Brief overview

An Integration that allows customers calling a customer-facing API to update end users attributes of a specific end user.

About this feature

Allows receiving real-time updates to update WalkMe's End User Object for the purpose of content Segmentation, Filtering on Insights and reporting.
The integration set up allows you to identify the fields you want to import from any payload (whitelist) that will be stored in WalkMe's End User Object and will later be available for Filtering on Insights, reporting and Segmentation.

Prerequisites

The End User Update API is accessible using WalkMe's Public API, which implies OAuth2 flow.

The customer's AM follow must follow the "WalkMe public API (REST) request process" (from the link above) in order to enable the WalkMe Public API so he can use the End user update API.

This means the customer will need to receive Account API credentials (username and password), and update their API scope to be 'endUserUpdate:write'

Creating an End User Update API Integration

Step 1 - Create a new End User Update API Integration

1. Navigate to Insights
2. Go to the Integrations tab (bottom left on the menu)
3. Click on API to WalkMe - this will open up the integration wizard

Step 2 - Define the Integration

1. Give the Integration a Name - Notice this is the name that will be shown on the Editor's Segmentation Center rule engine as well as on Insights so use a meaningful name.

2. Provide the User Identifier Property - Enter the field that will hold the end user identifier as identified in WalkMe - for example if your selected End User Identifier method is a variable containing the end user's email, the field entered should be the field in the payload JSON that will hold the end user's email. If your payload is in a format of a JSON object use dot separated names (.)

3. Enter the Properties to Import - Enter the fields and their type from the payload JSON that you wish to Import into WalkMe.
   These are the fields that will be available for Segmentation, Filtering on Insights and Reporting. If your payload is in a format of a JSON object use dot separated names (.).
   Supported Types are: String, Number, Date (in format of YYYY-MM-DD). Note- the attribute type you select will impact the segmentation conditions that will be available later on the rule engine. It is not possible to change a type of an attribute once it is set.

4. Click on Continue

Step 3 - Get Integration Endpoint

1. The integration now displays the endpoint to send your API request to in the following format:
cURL

curl -L -X POST 'https://api.walkme.com/public/v1/user/data' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>' \
--data-raw '{
    "token": "c865ab9ec9ffd1fbbe18a452951329bdd3e814484086bc0068da807208062c40",
    "data": [
        {
            "properties.ID": "[email protected]",
            "field1": "value",
            "field2": 123,
            "nested": {
                "field": 456
            }
        }
    ]
}'

2. Copy this Endpoint to the service you are using to send WalkMe the requests

Step 4 - Send Update Requests to the Update API Endpoint

The End User Update API is accessible through WalkMe's Public API. In order to use it, two calls should be made

1. A call to get get an Authorization token (See: https://developer.walkme.com/reference/getting-started-with-your-api)

2. Using the token Authorization extracted, send a POST request to the endpoint received in Step 3. The payload of your request should correspond with the integration set up (see examples below)

a. Request body must be a valid Json object with 'token' and 'data' properties.
b. The 'token' property should contain the value received when the endpoint was created on the integration center. It should not be confused with the "access-token".
c. The 'data' property is an array of Json objects with a user identifier field and at least one other field with value ("null" is not a valid value"). The fields names should align with the integration schema as defined when setting up the integration point.

Note

• It is not allowed to send "null" values in the api. Such calls will be considered illegal and will be ignored.
• The data properties do not have to include all of the attributes that were defined in the integration. only the field for the user identifier property is mandatory. In case of missing fields:
• When updating a single user, missing fields value will remain as is.
• When updating multiple users, missing fields values will be deleted.
• The maximum number of users per request is 100.
• Max size for request payload is 2MB.

Process Example

Step 1 - Create a new End User Update API Integration

1. Navigate to Insights
2. Go to the Integrations tab (bottom left on the menu)
3. Click on API to WalkMe - this will open up the integration wizard

Step 2 - Define the Integration

1. Give the Integration a Name - "Update Customer Attributes"
2. Provide the User Identifier Property - The WalkMe Identifier method is a variable returning the end user's email and my payload will have the end user's email under the property "Email" so I will type: "Email".
3. Enter the Properties to Import - The payload contains 2 properties which should be types "Type" and "Status". They will be renamed to "Customer_Type" and "Customer_Status" so these are the attribute names shown in the Segmentation Rule Engine and on Insights.
   Both of these properties are text values, so the selected "Property Type" will be "String".
4. Click on Continue

Step 3 - Get Integration Endpoint

1. The integration now displays the endpoint to send your API request to.
2. Click on the Copy icon and copy this Endpoint to the service you are using to send WalkMe the requests.

Step 4 - Send Update Requests to the Update API Endpoint by making two calls

Get an Authorization token

(See: https://developer.walkme.com/reference/getting-started-with-your-api)

Send a POST call to:

https://api.walkme.com/accounts/connect/token

Authorization Type = Basic Auth ( Username and password should be the username and password received for the Account (See Prerequisites) )

Body

"{["grant_type" : "client_credentials"]}"

An access token will be received in the response: 

 "access_token": "eyJhbGciOiJSUzI1NiIsImtpZNURDNTY1NkU4RDc4NEUiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJhYzRpVXJXLUNZSDNHUjY3LVYzRlpXNk5lRTQifQ.eyJuYmYiOjE1Nzc2Mjk1MzYsImV4cCI6MTU3NzcxNTkzNiwiaXNzIjoiaHR0cHM6Ly9hcGkud2Fsa21lcWEuY29tL2FjY291bnRzIiwiYXVkIjpbImh0dHBzOi8vYXBpLndhbGttZXFhLmNvbS9hY2NvdW50cy9yZXNvdXJjZXMiLCJXYWxrTWUgcHVibGljIl0sImNsaWVudF9pZCI6IjdkNjhiYTUwMGQwYTExZTk4MWI4MDJlZGRhNjMiLCJqdGkiOiI4NmQyZmE1Mi00YjkxLTQyZjUtOTgxMS0wZDUxOWM4YTI1ZGMiLCJqd2siOiIzYzM4eVVwbGVrSFJHWEFoVTVKajl3Z0JBYXBBdFoyQSIsInNjb3BlIjpbImxhbmd1YWdlczpyZWFkIiwibGFuZ3VhZ2VzOndyaXRlIiwicm9sZXM6cmVhZCIsInVzZXJzOnJlYWQiLCJ1c2Vyczp3cml0ZSJdfQ.Ufmo0cR6L9LfAfFl8tE-ZwQmFS5db0IRmXeRtDw2RZ88n1yV7wJ-bHKkZcIObv90achf2-3MhSdELZPH_YJQLz858Y79szfyUi5kraX2dHfA3U7UujjuL3qEUZMK0NR5JC37RIm-tvApOrbzl0Vc4aFKSF5Ae8pBOd2zfdsTvMkczI928AFJ-ieO9-U8Pl3vrYLNjaG-WzRE111ckQzzWMf1F2svdx9VRxxLOfm8TtVatuvcAS4uQFW1XKVVAn7VLMyGJDoM6Q03UXhUsyWwtQ78wilqY2xNEM0iQS9iuDfwp5dZEzw8nrIepKBoskBGXTac8z6QQXlHfpI3Gu64YyIQc2rDyyoFFZvPNOYbV5REI6rIKpYMWvTmDXyvnON84_Ojiq0HW-ikQmMSyvHWQpS0mXDiw4x3vkwOxUIaYwQJpCILGcqgomLr7XfoqRtPz25kG2ezneCuP0WpEGsT0K2I29m0pI4HwChXOY4UeRvbTpmCWBXnfYeE8RKNClnpFGv6Vl13hvVIu42IVTXy6w8dbngf9p0L9XzwaDRXnb6apDNow49gzVidjdSw1pe2A_INGbyyNeE-mxm-rIOTeqqY5q8MK62wOeF14W3KjztHhD0q7sMhaTrXHyk3pucK6LtDsdVSFWIpGKwI6L1yBNaujDOqxuhMzkblfDB7eXUCI6IjY5Q0UyMjUyQjVCRTA5ODFGNzE5MUVCQkY5",    "expires_in": 86400,    "token_type": "Bearer",    "scope": "languages:read languages:write roles:read users:read users:write"

}

Send Update user data call

Using the token extracted, send a POST request to the Integration Endpoint received in Step 3.

Send a POST call to:

https://api.walkme.com/public/v1/user/data

Authorization Type: Bearer Token

Token

= "eyJhbGciOiJSUzI1NiIsImtpZNURDNTY1NkU4RDc4NEUiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJhYzRpVXJXLUNZSDNHUjY3LVYzRlpXNk5lRTQifQ.eyJuYmYiOjE1Nzc2Mjk1MzYsImV4cCI6MTU3NzcxNTkzNiwiaXNzIjoiaHR0cHM6Ly9hcGkud2Fsa21lcWEuY29tL2FjY291bnRzIiwiYXVkIjpbImh0dHBzOi8vYXBpLndhbGttZXFhLmNvbS9hY2NvdW50cy9yZXNvdXJjZXMiLCJXYWxrTWUgcHVibGljIl0sImNsaWVudF9pZCI6IjdkNjhiYTUwMGQwYTExZTk4MWI4MDJlZGRhNjMiLCJqdGkiOiI4NmQyZmE1Mi00YjkxLTQyZjUtOTgxMS0wZDUxOWM4YTI1ZGMiLCJqd2siOiIzYzM4eVVwbGVrSFJHWEFoVTVKajl3Z0JBYXBBdFoyQSIsInNjb3BlIjpbImxhbmd1YWdlczpyZWFkIiwibGFuZ3VhZ2VzOndyaXRlIiwicm9sZXM6cmVhZCIsInVzZXJzOnJlYWQiLCJ1c2Vyczp3cml0ZSJdfQ.Ufmo0cR6L9LfAfFl8tE-ZwQmFS5db0IRmXeRtDw2RZ88n1yV7wJ-bHKkZcIObv90achf2-3MhSdELZPH_YJQLz858Y79szfyUi5kraX2dHfA3U7UujjuL3qEUZMK0NR5JC37RIm-tvApOrbzl0Vc4aFKSF5Ae8pBOd2zfdsTvMkczI928AFJ-ieO9-U8Pl3vrYLNjaG-WzRE111ckQzzWMf1F2svdx9VRxxLOfm8TtVatuvcAS4uQFW1XKVVAn7VLMyGJDoM6Q03UXhUsyWwtQ78wilqY2xNEM0iQS9iuDfwp5dZEzw8nrIepKBoskBGXTac8z6QQXlHfpI3Gu64YyIQc2rDyyoFFZvPNOYbV5REI6rIKpYMWvTmDXyvnON84_Ojiq0HW-ikQmMSyvHWQpS0mXDiw4x3vkwOxUIaYwQJpCILGcqgomLr7XfoqRtPz25kG2ezneCuP0WpEGsT0K2I29m0pI4HwChXOY4UeRvbTpmCWBXnfYeE8RKNClnpFGv6Vl13hvVIu42IVTXy6w8dbngf9p0L9XzwaDRXnb6apDNow49gzVidjdSw1pe2A_INGbyyNeE-mxm-rIOTeqqY5q8MK62wOeF14W3KjztHhD0q7sMhaTrXHyk3pucK6LtDsdVSFWIpGKwI6L1yBNaujDOqxuhMzkblfDB7eXUCI6IjY5Q0UyMjUyQjVCRTA5ODFGNzE5MUVCQkY5"

JSON payload example for one user:

JSON

{
    "token": "0c29ceeb01402d61b822bb4d2bf71ae8e3d94737ec60ca8f0f83503d0f69d16e",
    "data": [
        {
            "Email": "[email protected]",
            "Status": "New",
            "Type": "Internal"
        }
    ]
}

Body example for multiple users:

Example

{
    "token": "0c29ceeb01402d61b822bb4d2bf71ae8e3d94737ec60ca8f0f83503d0f69d16e",
    "data": [
         {
            "Email": "[email protected]",
            "Status": "New",
            "Type": "Internal"
        },
        {
            "Email": "[email protected]",
            "Status": "Retired",
            "Type": "Internal"
        },
      {
            "Email": "[email protected]",
            "Status": "Veteran",
            "Type": "External"
        }
    ]
}

Best practices

1. Once the End User Update API is called - the End User object will be updated immediately.

2. Less is more - Be sensitive with the total number of attributes that you integrate to WalkMe. We allow a total of 100 attributes total across all incoming integrations.

3. Unlike other Incoming Integrations, the End User Update API will only be updated once the API is called, and only for the specific End User that the API was called with.

4. If it is required to batch-set the attributes for all the end-users ahead of time, it is possible to use the Incoming Integration - CSV Upload.
   In that case, please note that the 2 integrations will set 2 different attributes, so:

a. The limitation of the 100 attributes is across all integrations - both the API and the Incoming batch
integration - so using all fields in both will decrease the actual limit to 50

b. In terms of rule definition for segmentation this will require building the condition with 2 rules and a "OR" relation in between. For example:
Incoming Integration customer type = 'paying' OR API integration customer type = 'paying'.

Limitations

• The segmentation rules are evaluated at every WM load, so if the end user clicked on a button that is connected to a webhook sending this call (for example a button for upgrading the account) - the condition will only be re-evaluated on the next WM load (next page or refresh).

• Since End User Update API uses WalkMe's Public API, the Public API limitations apply to it as well. For example, it is only available for MSA account.

• As will all incoming integrations, the End User Update API does not support Mobile Web.