How to compare the user base of both systems, creating and updating users in hotelkit.
What to consider if muliple businesses share employees.
User Model in hotelkit
First it is important to understand how user activation in hotelkit works: Users can have different states in hotelkit.
Activated vs. Deactivated vs. Deleted
Activated users are all employees that work actively within hotelkit. They are eligible to receive requests. They can however be deactivated by the property at any time.
Deactivated users are supposed to be inactive within the property but are for some internal functions still available. They could be reactivated at any moment by the property. This state is meant for seasonal employees or temporarily unavailable employees (e.g. maternity leave). They cannot be selected as recipients for messages or requests.
Users also can be permanently removed from hotelkit. They will not be visible anymore and cannot be reactivated. From an API perspective it only needs to be known that users will disappear from every listing as soon as they are deleted.
Pending vs. Activated
If a vendor submits a new user, it will only be proposed to the property. The property then must either connect the user to an already existing user within hotelkit, create a new user (and attach some access) or ignore the user in hotelkit. If the property decides to make the user available in hotelkit the user is available at GET /users. Until then the user is available at GET /users/byStatus/pendingNew. In both cases the user’s attributes can be updated via PUT /users/ID. If the property decides to ignore the user, its data can only be seen at GET /users/byStatus/ignored to prevent a new proposal by the partner.
In case a user is send for deactivation in hotelkit by the partner, this change is also proposed to the property. The deactivation can be declined and the user remains active in hotelkit and listed in GET /users. In this case the deactivation should not be send again, as this would trigger a new proposal for deactivation.
Process
User Synchronization
The goal of the user synchronization process is that all users of the partner are available for the property within hotelkit.
It should be done when activating an integration and daily to ensure that users are synchronized regularly.
Additional updates can be send each time a user is edited in the partner, wether it’s an attribute or the activation status.
The daily process is displayed in the graphic.
Fetch active users
Fetch deactivated users
Fetch previously ignored users
Fetch pending users
Post new users
Each time hotelkit passes users back to the partner on a GET-call the partner has to iterate through each user internally to match the user.
The user matching is easiest made by ‘clientID’.
If ‘clientID’ is not given or null the matching should be done by name, mail and/or birthdate of the user.
We recommend name and birthdate or e-mail if all users have an individual mail at the partner.
ID vs. clientID
For every user there are two identifier:
The ID is the identifier within hotelkit. It has to be used whenever you refer this user in the API (e.g. when updating a user or when setting as recipient). It will be auto generated by hotelkit as soon as the user is POSTed or created internally.
The other attribute is clientID, this should be handled as the identifier on the side of the partner. It can be used to quickly identify the user within the partners system and as primary key for matching the user. It is configurable that the property can match hotelkit users by inserting the clientID manually within hotelkit. If the partner is unsure what to use as clientID, the hotelkit team will gladly assist.
User Attributes
ID* | string The identifer by which the user is referenced for hotelkit |
clientID* | ClientIDstring The identifer of the user from the partner. Will be used to reassure the correct connection of the user between hotelkit and the partner. |
givenName* | string The given name of a user |
surName* | string The surname of a given user |
loginName | string A identifer that the user needs to login. It should only be set if the partner enables SSO to make sure the user has the same authentication as on the identity provider |
titlePrefix | string a title that is prefixed to the name of a User |
titleSuffix | string a title that is suffixed to the name of a User |
birthDate | string($date) birthday of the user as 'dd.mm.YYYY' |
string($email) professional e-mail address of this user. | |
gender | string The gender of a user. Will be used for configure shown text accordingly. Enum: |
customerList* | example: List [ "demo1", "demo2" ] list of customer-keys in which the user should be active. string |
position | string position within a department |
department | string the department of a user. Can be used for granting access within hotelkit. |
roles | example: List [ "HOD", "Food & Beverage" ] specific roles of the user. could be used for access-management. The list of used roles should be negotiated with hotelkit. string |
telephone | string professional telephone availability |
startDate | string($date) start of employment as 'dd.mm.yyyy' |
personnelNumber | string A roster identification number. Will be used for presentation only. |
Use Cases
There are several goals that can be achieved with user synchronization:
Message Import
By default, the recipients of imports are managed within hotelkit, for each request type the customer is able to select recipients (a single person, multiple person or groups). The recipients can also be adjusted anytime. This ensures that the information is forwarded to the correct employees even with a high rate of employee turnover. The partner does not need to handle the employees in general.
This approach would not be suitable, whenever the partner needs to send information specifically to one person at a time. A common use case is the import of salary information or a notification about pending actions at the partner.
For solving those use cases the partner can send specific recipientIDs within its report (via the attribute recipientList) to which the report is sent to.
Single Sign On
For enabling a partner to act as an identity provider in a Single Sign on Scenario, the partner must provide the identity attributes for a user to hotelkit. For in depth process of the implementation, please refer to the “Use Cases” section.
Interactions with user endpoints
List User
The partner will get all available user of the customer.
Exceptions
A user is not listed as soon as he has no access to the customer anymore. Additionally, the customer can flag a user specifically as a user who is not available for hotelkit. See “Handling an ignored User”.
Deactivating a User
If a user gets deactivated in the partner (access is revoked) this change shall reflect in hotelkit by updating the user via PUT /users/{ID} and setting the attribute customerList to be empty “customerList”:[].
Eventough the user is send for deactivation, the property can decline the deactivation. It should be ensured that the deactivation is only send once.
To ease this case you can send updates to hotelkit whenever an attribute or the status in the partner changes. By this, you don’t have to check for activation status in the shown matching process above.
Handling an ignored User
A user gets ignored by a manual action of the property within hotelkit by changing the user from being pendingNew to ignored. This change will reflect in the next user synchronization iteration in the user not listed in GET /users/byStatus/pendingNew anymore. There is no action from your side needed.
Changing the status of an ignored user has to be done manually by the property.
Pagination
With API version 3.1 we provide pagination for user listing, which returns a subset of users.
The paramters determine the length of the list and at which user it starts:
limit: how many users per page
offset: at which user it will start
count (only in the header of the response): how many users are returned in the list, this can be used to check whether the limit has already been reached
total (only in the header of the response): total number of users
Chain Solutions
The case of Chain Solutions apply if multiple businesses share one administration.
In chain solutions it may be useful to call GET /users from the higher-level administration customer to ensure getting all customer. If a user is activated, the user will return in the result of customerList. An user will only contain the customer itself and every customer with a lower level.
This case is described in more detail in the section User Synchronization for Multi-property Cases.