openapi: 3.0.1 info: title: Gamification Rest Api description: Gamification addon rest endpoints license: name: LGPL url: https://www.gnu.org/licenses/lgpl-3.0.en.html version: "1.0" tags: - name: /gamification/announcements description: Manages announcement associated to users - name: /gamification/realizations description: Manages users realizations - name: /gamification/rules description: Manages rules paths: /gamification/announcements: post: tags: - /gamification/announcements summary: Creates a new Announcement description: Creates a new Announcement operationId: createAnnouncement requestBody: description: Announcement object to create content: application/json: schema: $ref: '#/components/schemas/AnnouncementActivity' required: true responses: "204": description: Request fulfilled "400": description: Invalid query input "500": description: Internal server error "401": description: Unauthorized operation /gamification/announcements/{announcementId}: delete: tags: - /gamification/announcements summary: Cancels an existing announcement description: Cancels an existing announcement operationId: cancelAnnouncement parameters: - name: announcementId in: path description: Announcement technical identifier required: true schema: type: integer format: int64 responses: "204": description: Request fulfilled "404": description: Object not found "401": description: Unauthorized operation /gamification/badges/add: post: operationId: addBadge requestBody: content: '*/*': schema: $ref: '#/components/schemas/BadgeDTO' responses: default: description: default response content: application/json: {} /gamification/badges/all: get: operationId: getAllBadges responses: default: description: default response content: application/json: {} /gamification/badges/delete/{id}: delete: operationId: deleteBadge parameters: - name: id in: path required: true schema: type: integer format: int64 responses: default: description: default response content: application/json: {} /gamification/badges/update: put: operationId: updateBadge requestBody: content: '*/*': schema: $ref: '#/components/schemas/BadgeDTO' responses: default: description: default response content: application/json: {} /gamification/connectors: get: summary: Retrieves the list of remote connectors operationId: getConnectors parameters: - name: username in: query description: Username required: true schema: type: string - name: expand in: query description: Used to retrieve extra information about connectors schema: type: string responses: "200": description: Request fulfilled "401": description: Unauthorized operation /gamification/connectors/disconnect/{connectorName}: delete: summary: Deletes an existing connector account description: Deletes an existing connector account operationId: disconnect parameters: - name: connectorName in: path description: Connector name required: true schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: required: - remoteId type: object properties: remoteId: type: string description: User Remote identifier responses: "204": description: Request fulfilled "401": description: Object not found "400": description: Invalid query input "500": description: Internal server error /gamification/connectors/oauthCallback/{connectorName}: get: summary: Validate Remote user identifier on a selected connector and associate it in his current profile. description: Validate Remote user identifier on a selected connector and associate it in his current profile. operationId: connect parameters: - name: connectorName in: path description: Connector name required: true schema: type: string - name: code in: query description: Access Token required: true schema: type: string responses: "200": description: Request fulfilled "400": description: Invalid query input "401": description: Unauthorized operation "500": description: Internal server error /gamification/connectors/settings: post: summary: Saves gamification connector settings description: Saves gamification connector settings operationId: saveConnectorSettings requestBody: content: application/x-www-form-urlencoded: schema: required: - apiKey - connectorName - enabled - redirectUrl - secretKey type: object properties: connectorName: type: string description: Remote connector name apiKey: type: string description: Remote connector Api key secretKey: type: string description: Remote connector secret key redirectUrl: type: string description: Remote connector redirect Url enabled: type: boolean description: Remote connector status default: true responses: "204": description: Request fulfilled "400": description: Bad request "401": description: Unauthorized operation "500": description: Internal server error /gamification/connectors/settings/{connectorName}: delete: summary: Deletes gamification connector settings description: Deletes gamification connector settings operationId: deleteConnectorSettings parameters: - name: connectorName in: path description: Remote connector name required: true schema: type: string responses: "204": description: Request fulfilled "400": description: Bad request "401": description: Unauthorized operation "500": description: Internal server error /gamification/connectors/username/{connectorName}: get: summary: Retrieve the username associated with a connector user identifier. description: Fetches the username corresponding to the given connector user identifier. operationId: getUsernameByConnectorUserId parameters: - name: connectorName in: path description: Connector name required: true schema: type: string - name: connectorUserId in: query description: Connector user identifier required: true schema: type: string responses: "200": description: Request fulfilled "400": description: Invalid query input "401": description: Unauthorized operation "404": description: No associated username found "500": description: Internal server error /gamification/leaderboard: get: summary: Retrieve the list leaderboard users/spaces including the selected identity to retrieve its rank operationId: getIdentityLeaderboard parameters: - name: spaceId in: query description: Space audience technical identifier to filter schema: type: integer format: int64 - name: programId in: query description: Program technical identifier to filter schema: type: integer format: int64 - name: identityType in: query description: "Type of leaderboard, whether users or spaces" schema: type: string default: USER enum: - USER - SPACE - name: identityId in: query description: Identity technical identifier to include in results schema: type: integer format: int64 - name: period in: query description: "Current period: WEEK, MONTH or ALL" schema: type: string default: WEEK - name: dateInSeconds in: query description: "Timestamp in seconds of date in the middle of selected period.\ \ If not defined, current time will be used." schema: type: integer format: int64 default: 0 - name: offset in: query description: Results offset schema: type: integer format: int32 default: 0 - name: limit in: query description: Results limit schema: type: integer format: int32 default: 0 responses: "200": description: Request fulfilled "401": description: Unauthorized operation /gamification/leaderboard/stats/{identityId}: get: summary: "Retrieves identity gamification statistics classified by program,\ \ ready to be displayed in a pie chart" operationId: getIdentityStats parameters: - name: identityId in: path description: Identity technical identifier required: true schema: type: string - name: spaceId in: query description: Space audience technical identifier to filter schema: type: integer format: int64 - name: period in: query description: "Current period to consider. Possible values: WEEK, MONTH or\ \ ALL" schema: type: string default: WEEK - name: dateInSeconds in: query description: "Timestamp in seconds of date in the middle of selected period.\ \ If not defined, current time will be used." schema: type: integer format: int64 default: 0 responses: "200": description: Request fulfilled "401": description: Unauthorized operation /gamification/programs: get: summary: Retrieves the list of available programs operationId: getPrograms parameters: - name: offset in: query description: Offset of results to retrieve schema: type: integer format: int32 default: 0 - name: limit in: query description: Limit of results to retrieve schema: type: integer format: int32 default: 0 - name: status in: query description: "Programs status filtering, possible values: ENABLED, DISABLED\ \ and ALL. Default value = ENABLED." schema: type: string default: ENABLED enum: - ENABLED - DISABLED - ALL - name: owned in: query description: Whether retrieve owned programs only or not schema: type: boolean - name: sortByBudget in: query description: "If true, this will return the filtered programs sorted by budget.\ \ Possible values = true or false. Default value = false." schema: type: boolean default: false - name: includeDeleted in: query description: "If true, this will return the filtered programs including deleted\ \ ones. Possible values = true or false. Default value = false." schema: type: boolean default: false - name: returnSize in: query description: "If true, this will return the total count of filtered programs.\ \ Possible values = true or false. Default value = false." schema: type: boolean default: false - name: lang in: query description: Used to retrieve the title and description in requested language schema: type: string - name: query in: query description: Term to search. schema: type: string - name: sortBy in: query description: "Sort field. Possible values: createdDate, startDate, endDate\ \ or score." schema: type: string default: title - name: sortDescending in: query description: Whether to retrieve results sorted descending or not schema: type: boolean default: true - name: spaceId in: query description: Space audience identifier schema: type: integer format: int64 default: 0 - name: expand in: query description: Used to retrieve extra information about the program schema: type: string responses: "200": description: Request fulfilled "400": description: Invalid query input "401": description: Unauthorized operation "500": description: Internal server error post: summary: Creates a program operationId: createProgram requestBody: description: Program object to create content: application/json: schema: $ref: '#/components/schemas/ProgramDTO' required: true responses: "200": description: Request fulfilled "400": description: Invalid query input "401": description: Unauthorized operation "500": description: Internal server error /gamification/programs/{id}: put: summary: Updates an existing program operationId: updateProgram parameters: - name: id in: path description: Program id required: true schema: type: integer format: int64 requestBody: description: Program object to update content: application/json: schema: $ref: '#/components/schemas/ProgramDTO' required: true responses: "200": description: Request fulfilled "400": description: Invalid query input "401": description: Unauthorized operation "500": description: Internal server error /gamification/programs/{id}/avatar: get: summary: Gets a program avatar operationId: getProgramAvatar parameters: - name: lastModified in: query description: "The value of lastModified parameter will determine whether the\ \ query should be cached by browser or not. If not set, no 'expires HTTP\ \ Header will be sent'" schema: type: integer format: int64 - name: id in: path description: program id required: true schema: type: string - name: r in: query description: A mandatory valid token that is used to authorize anonymous request required: true schema: type: string responses: "200": description: Request fulfilled "500": description: Internal server error "400": description: Invalid query input "403": description: Forbidden request "404": description: Resource not found /gamification/programs/{id}/color: post: summary: "Returns true if the color can be used, else return false" operationId: checkProgramColorValidity parameters: - name: id in: path description: program id required: true schema: type: integer format: int64 requestBody: content: application/x-www-form-urlencoded: schema: required: - color type: object properties: color: type: string description: Program color to check its validity responses: "200": description: Request fulfilled /gamification/programs/{id}/cover: get: summary: Gets a program cover operationId: getProgramCover parameters: - name: lastModified in: query description: "The value of lastModified parameter will determine whether the\ \ query should be cached by browser or not. If not set, no 'expires HTTP\ \ Header will be sent'" schema: type: integer format: int64 - name: id in: path description: program id required: true schema: type: string - name: r in: query description: A mandatory valid token that is used to authorize anonymous request required: true schema: type: string responses: "200": description: Request fulfilled "500": description: Internal server error "400": description: Invalid query input "403": description: Forbidden request "404": description: Resource not found /gamification/programs/{programId}: get: summary: Retrieves a program by its technical identifier operationId: getProgramById parameters: - name: programId in: path description: Program technical identifier required: true schema: type: integer format: int64 - name: lang in: query description: Used to retrieve the title and description in requested language schema: type: string - name: expand in: query description: Used to retrieve extra information about the program schema: type: string responses: "200": description: Request fulfilled "401": description: Unauthorized operation "400": description: Invalid query input "404": description: Not found "500": description: Internal server error delete: summary: Deletes an existing program identified by its id operationId: deleteProgram parameters: - name: programId in: path description: Program id to be deleted required: true schema: type: integer format: int64 responses: "204": description: Request fulfilled "400": description: Invalid query input "401": description: Unauthorized operation "404": description: Object not found "500": description: Internal server error /gamification/programs/{programId}/avatar: delete: summary: Deletes program avatar identified by program id operationId: deleteProgramAvatar parameters: - name: programId in: path description: Program identifier required: true schema: type: integer format: int64 responses: "204": description: Request fulfilled "401": description: Unauthorized operation "404": description: Object not found /gamification/programs/{programId}/cover: delete: summary: Deletes program cover identified by program id operationId: deleteProgramCover parameters: - name: programId in: path description: Program identifier required: true schema: type: integer format: int64 responses: "204": description: Request fulfilled "401": description: Unauthorized operation "404": description: Object not found /gamification/realizations: get: tags: - /gamification/realizations summary: Retrieves the list of achievements switch a filter. The returned format can be of type JSON or XLSX description: Retrieves the list of achievements switch a filter. The returned format can be of type JSON or XLSX operationId: getRealizations parameters: - name: fromDate in: query description: result fromDate required: true schema: type: string - name: toDate in: query description: result toDate required: true schema: type: string - name: sortBy in: query description: "Sort field. Possible values: date or actionType." schema: type: string default: date - name: sortDescending in: query description: Whether to retrieve results sorted descending or not schema: type: boolean default: true - name: earnerIds in: query description: "earnerIds, that will be used to filter achievements" schema: type: array items: type: string - name: offset in: query description: Offset of result schema: type: integer format: int32 default: 0 - name: limit in: query description: Limit of result schema: type: integer format: int32 - name: returnType in: query description: "Response content Type. Either xlsx or json. Default value: json" schema: type: string default: json - name: identityType in: query description: "Earner type, either USER or SPACE. Default: USER" schema: type: string default: USER enum: - USER - SPACE - name: statuses in: query description: "Realization status list. Possible values: ACCEPTED, PENDING,\ \ REJECTED, CANCELED, DELETED" schema: type: array items: type: string enum: - ACCEPTED - NONE - REJECTED - CANCELED - DELETED - PENDING - name: programIds in: query description: Program technical identifiers. that will be used to filter achievements schema: type: array items: type: integer format: int64 - name: ruleIds in: query description: Rule technical identifiers that will be used to filter achievements schema: type: array items: type: integer format: int64 - name: reviewerIds in: query description: "reviewerIds, that will be used to filter achievements" schema: type: array items: type: integer format: int64 - name: owned in: query description: "If true, this will return the list of realizations, the current\ \ user can manage. Possible values = true or false. Default value = false." schema: type: boolean default: false - name: allPrograms in: query description: "If true, this will return all realizations, even the ones where\ \ user can't access, will be retrieved by anonymizing the associated program\ \ and rule" schema: type: boolean default: false - name: spaceIds in: query description: Used to filter realizations by space audience schema: type: array items: type: integer format: int64 - name: returnSize in: query description: "If true, this will return the total count of filtered realizations.\ \ Possible values = true or false. Default value = false." schema: type: boolean default: false responses: "200": description: Request fulfilled "401": description: Unauthorized operation "500": description: Internal server error patch: tags: - /gamification/realizations summary: Updates an existing realization description: Updates an existing realization status operationId: updateRealizationStatus requestBody: content: application/x-www-form-urlencoded: schema: required: - id - status type: object properties: id: type: string description: Realization technical identifier status: type: string description: Realization technical identifier responses: "204": description: Request fulfilled "404": description: Object not found "400": description: Bad request "401": description: Unauthorized operation /gamification/realizations/manager: get: tags: - /gamification/realizations summary: "Return 'true' if the current user can manage some realizations, else\ \ return 'false'" operationId: isRealizationManager responses: "200": description: Request fulfilled /gamification/realizations/points: get: tags: - /gamification/realizations summary: Retrieves the points of a given user in last period type operationId: getAllPointsByUserId parameters: - name: userId in: query description: Username to retrieve its points. required: true schema: type: string - name: period in: query description: "Period Type. Possible values: WEEK or MONTH. Default: WEEK." schema: type: string default: WEEK responses: "200": description: Request fulfilled "400": description: Bad Request /gamification/realizations/{id}: get: tags: - /gamification/realizations summary: Retrieves an achievement identified by its id operationId: getRealization parameters: - name: id in: path description: Achievement id required: true schema: type: integer format: int64 responses: "200": description: Request fulfilled "401": description: Unauthorized operation /gamification/reputation/AllofBadges: get: operationId: getAllOfBadges parameters: - name: url in: query schema: type: string responses: default: description: default response content: application/json: {} /gamification/reputation/badge/{badge}/avatar: get: operationId: getBadgeAvatarById parameters: - name: badge in: path required: true schema: type: integer format: int64 responses: default: description: default response content: application/json: {} /gamification/reputation/badges: get: operationId: getUserBadges_1 parameters: - name: url in: query schema: type: string responses: default: description: default response content: application/json: {} /gamification/reputation/badges/{identityId}: get: operationId: getUserBadges parameters: - name: identityId in: path required: true schema: type: integer format: int64 responses: default: description: default response content: application/json: {} /gamification/reputation/otherBadges: get: operationId: getOtherBadges parameters: - name: url in: query schema: type: string responses: default: description: default response content: application/json: {} /gamification/reputation/stats: get: operationId: stat parameters: - name: url in: query schema: type: string responses: default: description: default response content: application/json: {} /gamification/reputation/status: get: operationId: getReputationStatus parameters: - name: username in: query schema: type: string - name: url in: query schema: type: string responses: default: description: default response content: application/json: {} /gamification/reputation/won: get: operationId: getallBadges parameters: - name: url in: query schema: type: string responses: default: description: default response content: application/json: {} /gamification/rules: get: tags: - /gamification/rules summary: Retrieves the list of available rules operationId: getRules parameters: - name: offset in: query description: Offset of results to retrieve schema: type: integer format: int32 default: 0 - name: limit in: query description: Limit of results to retrieve schema: type: integer format: int32 default: 20 - name: programId in: query description: Used to filter rules by program schema: type: integer format: int64 - name: spaceId in: query description: Used to filter rules by space audience schema: type: array items: type: integer format: int64 - name: eventName in: query description: Used to filter rules by event name schema: type: string - name: type in: query description: "Rules type filtering, possible values: AUTOMATIC, MANUAL and\ \ ALL. Default value = ALL." schema: type: string default: ALL enum: - AUTOMATIC - MANUAL - ALL - name: programStatus in: query description: "Programs status filtering, possible values: ENABLED, DISABLED\ \ and ALL. Default value = ENABLED." schema: type: string default: ALL enum: - ENABLED - DISABLED - ALL - name: status in: query description: "Rules status filtering, possible values: ENABLED, DISABLED and\ \ ALL. Default value = ALL." schema: type: string default: ALL enum: - ENABLED - DISABLED - ALL - name: dateFilter in: query description: "Rule period filtering. Possible values: STARTED, NOT_STARTED,\ \ ENDED, ALL" schema: type: string default: ALL enum: - ACTIVE - STARTED - STARTED_WITH_END - UPCOMING - ENDED - ALL - name: term in: query description: term to search rules with schema: type: string - name: favorites in: query description: Whether to search in favorites only or not schema: type: boolean default: false - name: tags in: query description: Whether to search in favorites only or not schema: type: array items: type: string - name: sortBy in: query description: "Sort field. Possible values: createdDate, startDate, endDate\ \ or score." schema: type: string default: score - name: sortDescending in: query description: Whether to retrieve results sorted descending or not schema: type: boolean default: true - name: includeDeleted in: query description: "If true, this will return the filtered rules including deleted\ \ ones. Possible values = true or false. Default value = false." schema: type: boolean default: false - name: realizationsLimit in: query description: Accepted users realizations count schema: type: integer format: int32 default: 0 - name: groupByProgram in: query description: Group rules by program schema: type: boolean default: false - name: orderByRealizations in: query description: Whether Sort by popular rules or not schema: type: boolean default: false - name: excludedRuleIds in: query description: Excluded rule Ids schema: type: array items: type: integer format: int64 - name: period in: query description: "Rule period filtering. Possible values: WEEK, MONTH, YEAR, ALL" schema: type: string default: ALL enum: - WEEK - MONTH - YEAR - ALL - name: returnSize in: query description: "If true, this will return the total count of filtered programs.\ \ Possible values = true or false. Default value = false." schema: type: boolean default: false - name: lockingRules in: query description: "If true, the rules to do first by the user in order to unlock\ \ other rules will be returned at first. Possible values = true or false.\ \ Default value = false." schema: type: boolean default: false - name: lang in: query description: Used to retrieve the title and description in requested language schema: type: string - name: expand in: query description: "Asking for a full representation of a specific subresource,\ \ ex: userRealizations" schema: type: string responses: "200": description: Request fulfilled "400": description: Invalid query input "401": description: Unauthorized operation "500": description: Internal server error put: tags: - /gamification/rules summary: Updates a rule operationId: updateRule requestBody: description: rule object to update content: application/json: schema: $ref: '#/components/schemas/RulePublication' required: true responses: "204": description: Request fulfilled "404": description: Object not found "400": description: Invalid query input "401": description: Unauthorized operation "500": description: Internal server error post: tags: - /gamification/rules summary: Creates a rule operationId: createRule requestBody: description: rule object to save content: application/json: schema: $ref: '#/components/schemas/RulePublication' required: true responses: "200": description: Request fulfilled "400": description: Invalid query input "401": description: Unauthorized operation "500": description: Internal server error /gamification/rules/{id}: get: tags: - /gamification/rules summary: Retrieves the list of available rules operationId: getRule parameters: - name: id in: path description: Rule technical identifier required: true schema: type: integer format: int64 - name: realizationsLimit in: query description: Accepted users realizations count schema: type: integer format: int32 default: 0 - name: lang in: query description: Used to retrieve the title and description in requested language schema: type: string - name: expand in: query description: "Asking for a full representation of a specific subresource,\ \ ex: countRealizations" schema: type: string responses: "200": description: Request fulfilled "404": description: Object not found "401": description: Unauthorized operation "500": description: Internal server error /gamification/rules/{ruleId}: delete: tags: - /gamification/rules summary: Deletes a rule operationId: deleteRule parameters: - name: ruleId in: path description: Rule technical identifier required: true schema: type: integer format: int64 responses: "200": description: Request fulfilled "404": description: Object not found "400": description: Invalid query input "401": description: Unauthorized operation "500": description: Internal server error patch: tags: - /gamification/rules summary: Change enablement status of rule description: Change enablement status rule operationId: updateRuleStatus parameters: - name: ruleId in: path description: Rule Id required: true schema: type: integer format: int64 responses: "204": description: Request fulfilled /gamification/triggers: get: summary: Retrieves the list of gamification triggers operationId: getTriggers parameters: - name: type in: query description: Used to filter triggers by Connector type schema: type: string - name: expand in: query description: Used to retrieve extra information about triggers schema: type: string responses: "200": description: Request fulfilled /gamification/triggers/status: post: summary: enables/disables trigger for connector account. description: enables/disables event for connector account operationId: updateAccountTriggerStatus requestBody: content: '*/*': schema: required: - accountId - enabled - trigger type: object properties: trigger: type: string description: Trigger name accountId: type: integer description: Account Id format: int64 enabled: type: boolean description: "Trigger status enabled/disabled. possible values:\ \ true for enabled, else false" responses: "204": description: Request fulfilled "400": description: Bad request "401": description: Unauthorized operation "500": description: Internal server error components: schemas: AnnouncementActivity: type: object properties: activityId: type: integer format: int64 assignee: type: integer format: int64 challengeId: type: integer format: int64 challengeTitle: type: string comment: type: string createdDate: type: string creator: type: integer format: int64 id: type: integer format: int64 templateParams: type: object additionalProperties: type: string BadgeDTO: type: object properties: createdBy: type: string createdDate: type: string deleted: type: boolean description: type: string enabled: type: boolean endValidityDate: type: string icon: type: array items: type: string format: byte iconFileId: type: integer format: int64 id: type: integer format: int64 lastModifiedBy: type: string lastModifiedDate: type: string neededScore: type: integer format: int32 program: $ref: '#/components/schemas/ProgramDTO' startValidityDate: type: string title: type: string uploadId: type: string EventDTO: type: object properties: cancellerEvents: type: array items: type: string id: type: integer format: int64 properties: type: object additionalProperties: type: string title: type: string trigger: type: string type: type: string ProgramDTO: type: object properties: audienceId: type: integer format: int64 avatarFileId: type: integer format: int64 avatarUploadId: type: string avatarUrl: type: string budget: type: integer format: int64 color: type: string coverFileId: type: integer format: int64 coverUploadId: type: string coverUrl: type: string createdBy: type: string createdDate: type: string deleted: type: boolean description: type: string enabled: type: boolean id: type: integer format: int64 lastModifiedBy: type: string lastModifiedDate: type: string open: type: boolean ownerIds: uniqueItems: true type: array items: type: integer format: int64 priority: type: integer format: int32 rulesTotalScore: type: integer format: int64 spaceId: type: integer format: int64 title: type: string type: type: string visibility: type: string enum: - RESTRICTED - OPEN RulePublication: type: object properties: activityId: type: integer format: int64 audienceId: type: integer format: int64 cacheTime: type: integer format: int64 createdBy: type: string createdDate: type: string defaultRealizationStatus: type: string enum: - ACCEPTED - NONE - REJECTED - CANCELED - DELETED - PENDING deleted: type: boolean description: type: string enabled: type: boolean endDate: type: string event: $ref: '#/components/schemas/EventDTO' id: type: integer format: int64 lastModifiedBy: type: string lastModifiedDate: type: string managers: uniqueItems: true type: array items: type: integer format: int64 message: type: string open: type: boolean prerequisiteRuleIds: uniqueItems: true type: array items: type: integer format: int64 program: $ref: '#/components/schemas/ProgramDTO' programId: type: integer format: int64 publish: type: boolean recurrence: type: string enum: - NONE - ONCE - DAILY - WEEKLY - MONTHLY score: type: integer format: int32 spaceId: type: integer format: int64 startDate: type: string templateParams: type: object additionalProperties: type: string title: type: string type: type: string enum: - AUTOMATIC - MANUAL