Learning Management

Find an example how to enable a learning management setup for hotelkit.

1 Characteristics
2 Functionality
3 Setup
- 3.1 Defining the Webhook
- 3.2 Request Types
- 3.3 Enable Requests
- 3.4 Synchronize users from hotelkit
- 3.5 Create notification for new learning content
- 3.6 Getting Status Changes
- 3.7 Send Supervisor Report

Managing learning content for hotelkit users ensures a well trained employee that can provide a remarkable guest experience and efficient hotel operation.

Feel free to adjust the example to your needs and ask your hotelkit contact with any question.

Characteristics

As learning content is mostly provided in various media the expertise shall stay in the partner. What needs to be considered is the structure of content. Exist topics that include various modules and each can be completed seperately or is the learning package to be completed at once? Can new modules be added later to an existing topic?

Information about new modules or whole topics should be received in the main communication plattform hotelkit to ease the user experience.

Additionally, it could be useful to inform supervisors about training progress.

Functionality

To adress the trainings to each user individually the functionality “user_list” is required. Optional is “user_push”. User_push allows the partner to send new users to hotelkit.

The notification sending is enabled with “messageImport”.

To get an update for the completion of trainings to your system simultaniously “hasActions” needs to be granted.

To check your granted functionalities you can use GET /setup/partner.

Endpoint description for made requests in this use case are found in the Partner & Customer YAML for the setup of the global and property-based settings and in Message Import to notify users about content.

The handling of users is documented in User Synchronization.

Setup

At the beginning the general setup is made. These settings are applied globally.

Afterwards a setup per customer is done before the import of messages starts.

Defining the Webhook

It has to be defined once and is valid globally for the partner:

PUT /setup/partner
{
    "webhook":"https://examplePartner.com/hotelkit "
}

To manage the users between the systems there are optional available settings.

As the identifer of a user from the partner (clientID) can also be inserted by the customer (when enabled in hotelkit), the partner must be able to limit the format of valid identifier. This will be done with a regular expression:

PUT /setup/partner
{
    "userSync":{
        "regEx":"^(\d{3}_\d*)(,\d{3}_\d*)*$",
        "examples":[
            "123_00025","123_12345,045_58975"
        ],
        "errorMessage":{
            "de_DE":"Personalnummern müssen dem Format XXX_XXXXX entsprechen",
            "en_US":"personnel numbers must be given in the format XXX_XXXXX"
        }
    }
}

Request Types

For different kinds of notifications that shall be send to hotelkit there should be an individual request type. E.g there is a requestType to inform employees about new learning content and a different type to report the learning progress to the supervisor.

The title of a type should clearly indicate what to do for this request. The details will be imported with content.

As stated the available status changes will be represented with actions. Therefore the referenceID of an item has to be submitted.

Our first request type enables the notification about new learning content.

PUT /setup/requests
{
    "type":"newTraining",
    "labelForCustomer":{
        "de_DE":"Lerninhalte",
        "en_US":"Learning content"
    },
    "titleForCustomer":{
    "en_US": "New Learning Content Available",
    "de_DE": "Neue Lerninhalte verfügbar"
  },
    "content":true,
    "link":true,
    "title":true,
    "attachements":false,
    "enabledByDefault":true,
    "sendRecipients":true,
    "sendCreater":false,
    "hasActions":true,
    "referenceID":true
}

The second request type summarizes a report to the supervisor with an attached pdf.

Enable Requests

Before sending requests to a client, the requestTypes must be enabled for the respective client. This request has to be done with each onboarding of a new client or when the enabled requestTypes change for a client.

To check imports in your test-environment, please make sure you are set as a recipient to read the import. This only applies in the test-environment.

Synchronize users from hotelkit

To adress the notification to the right user there is the need to fetch the users from hotelkit and compare the list against users in your system.

This routine should be done daily.

The routine will be described with the preferred option that the partner manages the users (push_user).

Before updating & making suggestions for users in hotelkit, clearly a partner has to load the available users from hotelkit. If the customer is new, the partner should check whether there is another customer-key that is better suited for getting all information about the users.

This step is optional, as a warning will be returned in the listing if there is a more suitable customer-key available.

After that the partner requests the available users for the customer:

Now the partner should match the available users with the users in his system. First priority should be on the given clientID. When no clientID is given this could be done by the name or e-mail.

With functionality “push_user”:

As there is no clientID given for user “hk-199150” , the partner should update this user. Either the user can be matched – the user will be sent via PUT /users/{ID}, or the matching is unclear and no action is taken from the partner.

In hotelkit the clientID will be validated against the inserted regular expression before set to the user.

With functionality “user_list”:

If the partner does not manage the users and uses only functionality userList, he can not address unmatched users in hotelkit.

Create notification for new learning content

Whenever new training content is available for a user a message to hotelkit shall be send via POST /requests and the relating requestType “newTraining”.

The following example shows a basic import.

The content can be extended by providing a training video as an attachement, embedding a YouTube-video directly or adding further text.

Options for text formatting and embedding YouTube-Videos is described in Message Import.

Import for “newTraining” with two actions

Getting Status Changes

The customer may now trigger an action with the buttons “Accept” or “Decline”. As “Decline” requests some more information (text), it will be triggered for documentation purposes.
As soon as a button is pushed, a request to the webhook is triggered:

Triggered “Decline”-action, with additional information.

If the status change was handled by the partner a 200 response must be sent to finish the synchronization. If there are no follow up actions available, there is no payload.

Follow up actions means that there are new possible states for the message.
The follow up actions will be returned in the response:

More Details on configurations of actions can be found in the chapter Status Management

Send Supervisor Report

To send a Summary to the supervisor the second type is used.

For this example we assume that the relevant information is provided in an attached pdf-document.