Custom Import of Users and Groups Using API

Purpose of this guide: This page describes the API of the User Management application, which can be used to upload users and groups.

Audience: Network admin or technical employee with knowledge of how to use curl requests or dedicated tools to send HTTP requests to the API.

Previous steps: There are no previous steps.

When: When there is a need to upload users and groups from an ACD system(s) to the User Management application.

Next steps: There are no following steps.

Overview

As an alternative to using the Eleveo Data Providers, users and groups data can be imported using the provided API. This page describes the API, its endpoints and use cases.

The API requires authentication, due to this the upload consists of two steps:

1. Requesting and receiving an authentication token,

2. Uploading the token and data via API.

Prerequisites

As a prerequisite, the Provider Client needs to be added in User Management. Follow the procedure as described on the page: Configuring Client for User Importer. Write down the Client ID and Secret values (they will be used when requesting the token). Then continue on this page.

API Endpoints

The following API endpoints exist:

• Get Access Token – http://sso.<host>:<port>/auth/realms/<tenant>/protocol/openid-connect/token where:

  • <host> is an address or a name of the server where User Management is running

  • <port> is an address or a name of the server where User Management is running

  • <tenant> is the name of the realm (If not sure what the tenant name is check the URL of the Eleveo application: <tenant>.myeleveo.com)

• Send users – http://<host>:<port>/auth/realms/<tenant>/keycloak-push-api-provider/users?source=<source_id> where:

  • <host> is an address or a name of the server where User Management is running

  • <port> is an address or a name of the server where User Management is running

  • <tenant> is the name of the realm ((If not sure what the tenant name is check the URL of the Eleveo application: <tenant>.myeleveo.com)

  • <source_id> is the name of ACD from which data is uploaded

• Send groups – http://<host>:<port>/auth/realms/<tenant>/keycloak-push-api-provider/groups?source=<source_id> where:

  • <host> is an address or a name of the server where User Management is running

  • <port> is an address or a name of the server where User Management is running

  • <tenant> is the name of the realm ((If not sure what the tenant name is check the URL of the Eleveo application: <tenant>.myeleveo.com)

  • <source_id> is the name of the ACD from which data is being uploaded

Requesting and Getting the Token

The table below shows an example of the HTTP request, as well as the relevant header attributes and body which are needed to get an access token. The provided JSON body contains examples of configured parameters, replace them with relevant settings. Use a third party application or the curl command to send a request.

Sample response:

"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJXUzRxalJCZmUxRk4xa3UxakszcWpNS1pQQUJHNzdIQzBwSXlISXgxc0tRIn0.eyJqdGkiOiIyMDMzMWRjMi00NmZlLTQxMjQtYWZmZS0yYzllNWFmMGFjYzQiLCJleHAiOjE1OTAxMzUyNjUsIm5iZiI6MCwiaWF0IjoxNTkwMTM0OTY1LCJpc3MiOiJodHRwOi8vc3NvLmRldjA2My5kZXYuem9vbWludC5jb206MzA3MTcvYXV0aC9yZWFsbXMvZGV2MSIsImF1ZCI6IndmbS1hZG1pbmlzdHJhdGlvbi1hcHAiLCJzdWIiOiI0OTRmZWNkMS00ZTZmLTQwZTAtYTQxOC00OTNlZTQzYmUzN2UiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJ3Zm0tZm9yZWNhc3RpbmctYXBwIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiNjQ2MjRlZTctNjlmZS00YTEyLTljY2MtZjc1Y2ZiYzExY2I5IiwiYWNyIjoiMSIsInJlc291cmNlX2FjY2VzcyI6eyJ3Zm0tYWRtaW5pc3RyYXRpb24tYXBwIjp7InJvbGVzIjpbIldGTV9WSUVXX1FVRVVFIiwiV0ZNX0NSRUFURV9RVUVVRSJdfSwid2ZtLWZvcmVjYXN0aW5nLWFwcCI6eyJyb2xlcyI6WyJXRk1fREVMRVRFX0ZPUkVDQVNUIiwiV0ZNX0hJU1RPUklDQUxfREFUQV9QVVNIIiwiV0ZNX0NSRUFURV9GT1JFQ0FTVCIsIldGTV9WSUVXX0ZPUkVDQVNUIiwiV0ZNX0VESVRfRk9SRUNBU1QiLCJXRk1fRklMRV9VUExPQUQiXX19LCJzY29wZSI6ImVtYWlsIHByb2ZpbGUiLCJjbGllbnRJZCI6IndmbS1mb3JlY2FzdGluZy1hcHAiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudEhvc3QiOiIxMC4zMi4wLjEiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtd2ZtLWZvcmVjYXN0aW5nLWFwcCIsImNsaWVudEFkZHJlc3MiOiIxMC4zMi4wLjEiLCJlbWFpbCI6InNlcnZpY2UtYWNjb3VudC13Zm0tZm9yZWNhc3RpbmctYXBwQHBsYWNlaG9sZGVyLm9yZyJ9.bmcfw_Afwfek_SswhdKPAXImLigcVC3vfPjvR3TOMW1DwYSLiFtodEyzo200V-EwLVKQR2wXjCNfAFMCRYiaR3b4B3peT6cra9dVYXaU8pwfqpXmJb1IdxAxHvlu8fVjBJfiOyIZ6N2mFmTXqUqucioAFv2wD6LkrcpR1QXQcBzwKtb87xemSWL1NivAHUjz-wgg_-x5qAGfJofqQUI7F00Img2VmhkJfac1YWnBAcPaNEm0RGeVlANB1gL77C1opHrSBIUDzk56JaiR2WDjHPheSxo4CGKfTo0rp9dq3hK5jYU62KY8sAjADMy3j6dfE3zSfgehzaXVNyug2AE-7Q",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJjYzEzZmFhOS0yZmY4LTQyZjYtODQxYS0yMzY5ODIyMDQ2ZWMifQ.eyJqdGkiOiJmZGJjNTlkYi0yYzFiLTRmOTQtOTZjNC00ZDc3NjE0YzdhZmUiLCJleHAiOjE1OTAxMzY3NjUsIm5iZiI6MCwiaWF0IjoxNTkwMTM0OTY1LCJpc3MiOiJodHRwOi8vc3NvLmRldjA2My5kZXYuem9vbWludC5jb206MzA3MTcvYXV0aC9yZWFsbXMvZGV2MSIsImF1ZCI6Imh0dHA6Ly9zc28uZGV2MDYzLmRldi56b29taW50LmNvbTozMDcxNy9hdXRoL3JlYWxtcy9kZXYxIiwic3ViIjoiNDk0ZmVjZDEtNGU2Zi00MGUwLWE0MTgtNDkzZWU0M2JlMzdlIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6IndmbS1mb3JlY2FzdGluZy1hcHAiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiI2NDYyNGVlNy02OWZlLTRhMTItOWNjYy1mNzVjZmJjMTFjYjkiLCJyZXNvdXJjZV9hY2Nlc3MiOnsid2ZtLWFkbWluaXN0cmF0aW9uLWFwcCI6eyJyb2xlcyI6WyJXRk1fVklFV19RVUVVRSIsIldGTV9DUkVBVEVfUVVFVUUiXX0sIndmbS1mb3JlY2FzdGluZy1hcHAiOnsicm9sZXMiOlsiV0ZNX0RFTEVURV9GT1JFQ0FTVCIsIldGTV9ISVNUT1JJQ0FMX0RBVEFfUFVTSCIsIldGTV9DUkVBVEVfRk9SRUNBU1QiLCJXRk1fVklFV19GT1JFQ0FTVCIsIldGTV9FRElUX0ZPUkVDQVNUIiwiV0ZNX0ZJTEVfVVBMT0FEIl19fSwic2NvcGUiOiJlbWFpbCBwcm9maWxlIn0.03-IhDoWsXfBCkmj1l6rv7U9XNBu_vw2zpirrEPnxPc",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "64624ee7-69fe-4a12-9ccc-f75cfbc11cb9",
    "scope": "email profile"

Uploading Data to User Management

There are two types of upload requests:

• uploading users

• uploading groups

API Definition - Users

Use a third-party application or the curl command to send a request. Include the token obtained in the previous step.

Action	HTTP Method	Header	Query parameters	Body
		http://<host>:<port>/auth/realms/<tenant>/keycloak-push-api-provider/users?source=<source_id>
Sending users	POST	Content-Type: text/csv Authorization: Bearer <token received in the previous step>	source: name of ACD from which data is uploaded	Body text is an input stream with the following format: externalUserId, username, firstname, lastname, client/role*, groupIds, enabled, email, phoneExtension, teamIds  for example:

*Note that the user's role should be written in the format: client/role, for example: 'wfm-ui-app/WFM_AGENT', 'wfm-ui-app/WFM_SCHEDULER'. To read more about composite and effective user roles, go to the User Roles page.

Note that one user can have more user roles assigned, as well as belong to several groups or teams. In such a case, the client/role, groupIds or teamIds values should be separated with '#', for example:

4,john.black,John,Black,wfm-ui-app/WFM_SCHEDULER#wfm-ui-app/WFM_ANALYST,1#2#3,TRUE,john.blach@mockmail.com,012345678,12#13#14

If the source parameter is equal to 'uploadTest1', then imported users will have an attribute 'sourceId' equal to the source name ('uploadTest1'):

API Definition - Groups

Use a third party application or the curl command to send a request. Include the token obtained in the previous step.

Action	HTTP Method	Header	Query parameters	Body
		http://<host>:<port>/auth/realms/<tenant>/keycloak-push-api-provider/groups?source=<source_id>
Sending groups	POST	Content-Type: text/csv Authorization: Bearer <token received in the previous step>	source: name of ACD from which data is uploaded	Body text is an input stream with the following format: externalGroupId, groupName, childGroupsExternalIds for example:

Note that one group can have several child groups in it. In such case, the childGroupsExternalIds values should be separated with '#', for example:

3,group4,child1#child2#child3

Note that if the source parameter is equal to 'uploadTest1', then the groups will be imported as shown in the image below. The parent group with the name of the source (in this example 'uploadTest1') will be created, and all imported groups will be added to it as child groups.

All imported groups, and also the newly created parent group 'uploadTest1' will have an attribute 'sourceId' equal to the source name ('uploadTest1'):

Input Data Format

Each line of the input stream should contain the following data in the order indicated:

Import of Users

Import of Groups