The resources use a data model that is supported by a set of client-side libraries that are made available on the files and libraries page.
There is a WADL document available that describes the resources API.
| name | path | methods | description |
|---|---|---|---|
| AccountApi |
|
|
An Account has to be created for at least one manager or developer. It is identified by a unique email address. The password ensures the identity. Optionally an account may have information about the user in form of her/his first name and last name. It is possible to change the password, the first name or last name at a later point of time. In addition to creating an account another possible request is to get the created account but only with the correct credentials. In the response of all requests the hashed password isn't returned because of security reasons. |
| Api |
|
With the API some application information can be queried like the current date and time. | |
| DonationApi |
|
|
A donation stands for a real world purpose. This could be for example a real donation for a charitable purpose or an event for the organisation’s employees like the arrangement for the company party or purchasing a new coffee machine. When a donation is created, players can pool coins for a certain amount and the connected purpose if she/he has enough coins. If the required amount is reached, the goal is reached and the purpose can be implemented by the responsible manager. |
| GoalApi |
|
|
A Goal comprises one or more tasks and has to be completed if the player wants to earn the connected awards. To create a goal some already created components are needed. So the condition when a goal is completed is defined in the goal rule and the connected tasks. Who can complete a goal is defined by the role of a player and whether it can be done by a group. It is also possible to define whether a goal is repeatable so that the player can complete the tasks and obtains its coins and points as rewards again. All goals that are associated with the organisation can be requested or like the elements before only one specific goal, if the correspondent id is used. The name, the associated rewards and also the rule for completion can be changed as well as the indication if the goal is repeatable or a goal that can be reached by a group. It is also possible to change the roles so different people can complete the goal. |
| MarketPlaceApi |
|
|
The marketplace gives players the opportunity to offer tasks that have to be completed by their colleagues so that they are able to fulfil those tasks and obtain the respective reward. Upon creation of a task, an initial bid in terms of coins is set, which will be obtained as additional reward. Via Bids this initial bid can be raised. To be able to create offers, a marketplace for the organisation is needed. If none exists yet, it first has to be created. If an offer is created an initial bid in terms of coins is set which is obtained by the person who completes it. The initial bid can be raised by other colleagues in order to increase the incentive of fulfilling the task. When a player has completed a Task that belongs to an offer, she/he will obtain all bids as a reward. The particular task is then also added to the player’s list of the finished tasks. All offers a player has put on the marketplace can be requested. The name of an offer can be changed at a later point of time as well as the optional date when an offer ends or the deadline when the associated task of an offer should be done at the latest. At the marketplace not all offers may are visible for each player because the offers can be filtered by the roles a player has. It can also additionally filtered by the date an offer was created or the prize which can be earned. By making a bid, the reward of coins for completing a task is raised. The bidden amount of coins will be subtracted from the bidder’s current account and will be added to the offer’s current prize. Each player can make several bids on condition that her/his coins are enough otherwise the bid cannot be made. It is also possible to get all bids that was made for an offer. |
| OrganisationApi |
|
|
An Organisation represents for example a specific company or an association which represents a group of people belonging together and which are participating in the gamification process. An Organisation possessed an generated API key which is needed for all further interactions because all database entries are associated with this unique key and so with the respective organisation. The API key is uniquely in the whole application. It may be changed, for this reason it has no primary key. When an Organisation is created it has to be connected with an account. Each organisation may be managed by many people, but at least by one who is added to the list of the manager of the respective organisation and so also the Account. In the response of all requests the account's password isn't returned because of security reasons. |
| PlayerApi |
|
|
A player represents a user in the gamification application, eg. an employee of an organisation or a customer. By the creation, each player is assigned a nickname and certain roles. Each player has a list for his earned rewards, already finished Goals and finished Tasks. The initial value of possible points, coins and index of a level is set to "0". These can be raised by fulfilling tasks in the gamification application. Furthermore a player can have an avatar, by specifying the path of an image previously uploaded to a server. A player can be set active or can be deactivated so that she/he cannot complete tasks. In addition to create and to delete a player it is possible to get one particular player of one specific organisation by her/his associated id or all players of the organisation. The avatar of one player can also be requested. To display the status of a player ancillary the already finished goals and finished tasks it can be requested all earned permanent rewards. If only one status element is needed, the current points, coins, badges or achievements can be gotten instead. Each player can also have a list of contacts which represent other players in the same organisation, so players can send them little presents. At a later point of time it is possible to change the password, nickname, avatar and the roles or contacts a player has. In the responses the player's password and avatar isn't returned because of security reasons respectively overload. To get the avatar of a player a specific get request can be sent ("/player/{id}/avatar"). |
| PlayerGroupApi |
|
|
Players can be assigned to a group by its creation or at a later point in time. For example depending on the respective organization, a group can be a department, a work group or several employees with the same occupation. It is possible to create special tasks which can be done only as a group. When a member of a group completed such a task the group obtains its rewards. So a group can also have a list of already earned rewards and finished Goals. Like a player, a group can be assigned an image as a logo. This can either be done when creating the group or later through a PUT query. Later players can also be added to a group or the group’s name can be changed. |
| PlayerLevelApi |
|
|
API for player level related services. |
| PresentApi |
|
|
Players in a gamification application can send presents to each other, whereby one or more players can be a recipient. These presents can be a small image or a short text message which contains for example a little praise. A Board serves a player to send and to store presents in terms of a short text message or an image. The difference between these two messages is as the name suggests, that the text message contains a short text and the image message an image. To archive the presents they can be moved to an additional list. It is possible to get for one player all her/his text messages or all messages with a small image that were created. Furthermore all new presents of player can be requested as well as the accepted and archived presents. All denies presents were removed from the in-box. |
| RewardApi |
|
|
A Reward will be awarded in dependent of the goal for a group or one person after a person fulfilled a task. A reward can be a permanent reward like a badge or achievement which can be obtained only once or a volatile reward such as coins, points or a particular level which can be earned several times and so can be changed by getting for example more coins or decrease the coins by giving a bid for an offer in the marketplace. Ancillary all possible types for creating a reward, all already created rewards for one particular organisation or with the associated id only one specific reward can be requested. For all rewards the name and description can be changed after they have been created. Dependent on the reward has an image or an amount of points respectively coins these attributes also can be changed. |
| RoleApi |
|
|
A role describes which members of an organisation is allowed to do or see particular elements of the engine such as to fulfil a particular task and get its rewards. Each Player can have many different roles such as one for his occupation or the department in which she/he works. But the roles can also be a part of an invented role system that isn’t oriented towards the work context. All roles are specific to the respective created organisation. Ancillary creating and deleting, either all roles of a specific organisation or with a given id the associated role can be gotten. The name of one role can also be changed at a later point of time. |
| RuleApi |
|
|
With a Goalrule can be defined which tasks and if all or only one task have to be fulfilled to reach a goal. When a goal rule is fulfilled the goal is added to the player’s list of finished goals. If the goal can also be done by a group it is also added to its list of finished goals. There are two types of rules that can be defined: a TaskRule or a PointsRule. All created rules which are created in the context of one specific organisation can be requested with the appendant API key. With the given id also a particular rule can be requested, also for example to change some attributes like the name, the description or, if it is a PointsRule, the amount of points which has to be reached. |
| TaskApi |
|
|
A Task is the basic module and represents for example a specific activity. For a creation of a task, the roles are needed which indicate who is allowed to fulfil this task. To complete the task only one of these roles is needed. One or more tasks can be assigned to a goal, so depending on the rule of the goal some additional tasks may also have to be completed to fulfill the goal so the player can earn the associated rewards. If the task is tradeable it can be offered in the marketplace, so that another player can do it and gets the reward of it. When a player has completed a task, it will be added to the player’s list of finished tasks. At the same time the date and time is also stored when this request was sent and the task was officially be done. If the task is the last one to fulfill a goal, the goal is also added to the player’s list of finished goals and the player will obtain all its associated rewards. It is possible to query all tasks which are associated with a particular organisation or with the help of the associated id one specific task. When a task was created it is possible to change the task’s name, description and roles of players who are allowed to fulfil this task. Furthermore a task can be set tradeable or not at a later point of time. |
| type | description |
|---|---|
| Account | An Account has to be created for at least one manager or developer. It is identified by a unique email address. The password ensures the identity. Optionally an account may have information about the user in form of her/his first name and last name. It is possible to change the password, the first name or last name at a later point of time. In addition to creating an account another possible request is to get the created account but only with the correct credentials. |
| Achievement | The achievement class contains an image and a description for a documentary use to track significant results or milestones the player was able to achieve during her/his play. It's a more elaborate way to record the players achievements than the badge class. An achievement is a permanent reward, so a player can get a specific achievement only once. |
| Badge | The badge class serves as a Reward-subclass that represents a distinct icon. It should be used as a an instantly recognizable visual reference to an badge a player was able to reach. A badge is a permanent reward, so a player can award a specific badge only once. |
| Bid | A player can give one or more bids for an offer so its total prize gets higher and in order to increase the incentive of fulfilling the task. The bidden amount of coins will be subtracted from the bidder’s current account and will be added to the offer’s current prize. Each player can make several bids on condition that her/his coins are enough otherwise the bid cannot be done. |
| Coins | The Coins class serves as a Reward-subclass, that allocates coins to a player. Coins are a volatile reward which can be earned more than one time. These awarded coins are added to the current amount of coins a player owns. |
| DayOfWeek | |
| Donation | |
| DonationCall | A DonationCall represents a call for donations. This could be a real world purpose like a real donation for a charitable purpose or an event for the organisation's employee. Players can donate obtained coins to reach a particular amount of coins. If the required amount is reached, the goal is reached and the purpose can be implemented by the responsible manager. |
| FinishedGoal | When a player has completed a Goal, it will be added to the player’s list of finished goals. If the goal is a group goal it is also stored in the group's list of finished goals. At the same time the date is also stored when this request was sent and the goal was officially be done. |
| FinishedTask | When a player has completed a Task, it will be added to the player’s list of finished tasks. At the same time the date is also stored when this request was sent and the task was officially be done. If the task is the last one to fulfill a goal, the goal is also added to the player’s list of finished goals and the player will obtain all its associated rewards. |
| GetPointsRule | A PointsRule is a sub-class of the GoalRule. It specifies to reach a certain amount of points. If the player collected all needed points for example by executing tasks, the rule is completed. So every time the player receives points it is checked if one PointsRule is fulfilled. |
| Goal | A Goal comprises one or more tasks and is associated with a goal rule. If the player wants to earn the connected awards the rule has to be fulfilled. To create a goal some already created components are needed. So the condition when a goal is completed is defined in the goal rule and the connected tasks. Who can complete a goal is defined by the role of a player and whether it can be done by a group. It is also possible to define whether a goal is repeatable so that the player can complete the tasks and obtains its coins and points as rewards again. All goals that are associated with the organisation can be requested or like the elements before only one specific goal, if the correspondent id is used. The name, the associated rewards and also the rule for completion can be changed as well as the indication if the goal is repeatable or a goal that can be reached by a group. Is is also possible to change the roles so different people can complete the goal. |
| GoalRule | With a GoalRule can be defined which tasks and if all or only one task have to be fulfilled to reach a goal and to obtain the rewards for it. When a goal rule is fulfilled the goal is added to the player’s list of finished goals. If the goal can also be done by a group it is also added to its list of finished goals. There are two types of rules that can be defined: a TaskRule or a PointsRule. |
| ImageMessage | A present can be an imageMessage in the form of an image icon with a positive message for the receiver. |
| LocalDateTime | |
| MarketPlace | Players can create an offer with a task for the marketplace so another player can bid to do this task and get its rewards. Via Bids an initial bid by the creator can be raised. To be able to create offers, a marketplace for the organisation is needed. If none exists yet, it first has to be created. |
| Month | |
| Offer | With an offer a player can create a task for other players. At this point of time an initial bid in terms of coins is set which is obtained by the person who completes it. The initial bid can be raised by other colleagues in order to increase the incentive of fulfilling the task. When a player has completed a Task that belongs to an offer, she/he will obtain all bids as a reward. The particular task is then also added to the player’s list of the finished tasks. |
| Organisation | An Organisation represents for example a specific company or an association which represents a group of people belonging together and which are participating in the gamification process. An Organisation possessed an generated API key which is needed for all further interactions because all database entries are associated with this unique key and so with the respective organisation. The API key is uniquely in the whole application. It may be changed, for this reason it has no primary key. When an Organisation is created it has to be connected with an account. Each organisation may be managed by many people, but at least by one who is added to the list of the manager of the respective organisation and so also the Account. |
| PermanentReward | Permanent rewards are rewards that can be earned only once. These are for example an achievement or a badge. If a player has such an reward she/he may reach the goal again but doesn't get the reward one more time. |
| Player | A player represents a user in the gamification application, eg. an employee of an organisation or a customer. By the creation, each player is assigned a nickname and certain roles. Each player has a list for his earned rewards, already finished Goals and finished Tasks. Points, coins and index of a level can be earned or raised by fulfilling tasks in the gamification application. Furthermore a player can have an avatar. A player can be set active or can be deactivated so that she/he cannot complete tasks. By default every created player is active until she/he is deactivated. Each player can also have a list of contacts which represent other players in the same organisation to send little presents. At a later point of time it is possible to change the password, nickname, avatar and the roles or contacts a player has. |
| PlayerGroup | Players can be assigned to a group by its creation or at a later point in time. For example depending on the respective organization, a group can be a department, a work group or several employees with the same occupation. It is possible to create special tasks which can be done only as a group. When a member of a group completed such a task the group obtains its rewards. So a group can also have a list of already earned rewards and finished Goals. Like a player, a group can be assigned an image as a logo. |
| PlayerLevel | A player level shows the status of the player. This can be a number or a status like a titel. After the Player completed a task her/his level can advance if the conditions are fulfilled. |
| Points | Points class serves as a Reward-subclass, that allocates points to a player. Points are a volatile reward which can be earned more than one time. The awarded points are added to the current ones of a player. |
| Present | A present is a little positive message which one player can send to one or more other players. These presents can be an image or a short text message which contains for example a little praise. A Board serves a player to send and to store these presents in terms of a short text message or an small image. The difference between these two messages is as the name suggests, that the text message contains a short text and the image message an image. To archive the presents they can be moved to an additional list. It is possible to get for one player all her/his text messages or all messages with a small image that were created. Furthermore all new presents of a player can be requested as well as the accepted and archived presents. All denied presents were removed from the in-box. |
| PresentAccepted | Presents that are in the in-box of the board a player can accept or deny. If the player accept a present its status is set to accepted and an PresentAccepted object is created. |
| PresentArchived | Presents that are accepted a player can archived. If the player archived a present an PresentArchived object is created. |
| ReceiveLevel | The ReceiveLevel class is a Reward-subclass that allocates a specific level to a player which can serve as a status. |
| Reward | The super class of all rewards. Here are general information of the reward like to which organisation the reward belongs to or the goal to which it is associated. A Reward will be awarded in dependent of the goal for a group or one person after a person fulfilled a task. It can be chosen between one or more of the following rewards for a task: A permanent reward like a badge or achievement which can be obtained only once, or a volatile reward such as coins, points or a particular level which can be changed by getting for example more coins or be decreased by giving a bid for an offer in the marketplace. |
| Role | A role describes which members of an organisation is allowed to do or see particular elements of the engine such as to fulfil a particular task and get its rewards. Each Player can have many different roles such as one for his occupation or the department in which she/he works. But the roles can also be a part of an invented role system that isn’t oriented towards the work context. All roles are specific to the respective created organisation. |
| State | A State is the default answer of the engine. It gives information about the current date and time as well as the current version. It also shows the used path of the local host and the protocols that are supported. |
| Status | |
| Task | The Super Class for different types of Task. A Task is the basic module and represents for example a specific activity. By its creation the roles were assigned which indicate who is allowed to fulfil this task. To complete the task only one of these roles is needed. One or more tasks can be assigned to a goal, so depending on the rule of the goal some additional tasks may also have to be completed to fulfill the goal so the player can earn the associated rewards. If the task is tradeable it can be offered in the marketplace, so that another player can do it and gets the reward of it. |
| TaskRule | A TaskRule defines the combination of tasks until a goal is fulfilled. So for a defined sample of tasks either all of them have to be fulfilled (type: DoAllTaskRule) which corresponds an AND-expression, or only one of a specific selection, which is like an OR-expression (type: DoAnyTaskRule). |
| TextMessage | A present can be a short positive text message, which is sent to one or more receivers. It can contain a little thank or a praise. |
| URL | |
| VolatileReward | A volatile reward is a reward that can be awarded more than one time. So the player can reach a goal and earn the connected rewards again. Such a reward is for example a specific amount of points which is added to the player's current points. |