Hi again.  Today’s post is the third post in a six-part series made by actual Technical Consultants working at SAP Concur on Concur’s new Identity and User Provisioning Services.  The last post talked about the different purposes and structures for Identity vs Spend and Travel.  Today’s post will talk about Synchronous and Asynchronous calls made by Identity or UPS and how they work together.

Ok, if you have been reading along in the series so far you will be aware that SAP Concur’s new Identity service allows for the creation of a user in Concur at nearly the same time that a user is created in a company’s own internal network.  In addition, you will remember that we referred to a user’s Identity profile as the base on which both Spend and Travel information gets added.    The last important difference that you need to understand to work with Identity and UPS is related to the way that each service processes their data.   In short, all updates to Identity are processed synchronously while all updates made through UPS are handled asynchronously.   I’ll explain how these work together below.

The following diagram gives examples of how synchronous and asynchronous calls are different.   As you can see, the arrow between the user provisioning service and a user’s identity profile goes both directions.   This means that within one API call, the requested update is processed for the identity profile and feedback about the success or failure of the update is immediately returned.   This is different from the update calls being made for Spend and Travel.   To make updates to Spend and Travel, two separate calls are required.  The first call communicates the updates that are being requested and second call is used to confirm the update status.

Now, let’s take a closer look at the process. When a user is created in Concur, they are given a unique identifier called a UUID. This identifier is assigned after successfully creating the user’s Identity.  It is required for all subsequent updates to Identity, Spend and Travel information that follow a user’s initial creation (per the SCIM standard).  If you are not storing this id internally, you can use a “GET” query to return the user’s UUID before making your updates. The latest Identity v4.1 update added a number of new search criteria that make looking up a user easy.  You can find a complete list of available search criteria in the new Identity v4.1 search guide linked below.

SAP Concur Developer Center | Identity v4.1 Search Guide

Here is an example of payload returned from a successful Identity profile update.   Note the UUID that is provided in the feedback.

Here is an example of a Spend update call.   As you can see, the UUID is embedded in the URL string itself.   Travel updates work the same way.   Variables can be used in place of the actual UUID when making updates programmatically.

Next, let’s talk about how to confirm that status of your Spend and Travel update.    Updates are made extremely quickly, but as explained above, they are not made in the same call.   Therefore, it is necessary to make a subsequent call to confirm the status of the update before considering the update cycle complete.  Whenever you make the first post to update data that lies within either the Spend or Travel extension sets, you will be given a provisioning ID.    This id is the key to identifying whether your updates were successful.   You may want to store this provisioning id so that you can check it at a later time.

Here is an example of where the provisioning id can be found in the payload of a Spend or Travel update.  Note that the total number of updates requested and the current status of the update are displayed as well.

You can use the provisioning id to check the status of your update by executing a separate GET call and including it in the following URL:

https://datacenterURL/provisioning/v4/provisions/provisioningID/status

If you have an error and need to get additional detail about what might be causing the issue you can add ‘?attributes=operations’ onto the end of the URL to get a more detailed description of the issue.   For example:

https://datacenterURL/provisioning/v4/provisions/provisioningID/status?attributes=operations

It may be easier to use the status plus attributes URL for all of your status update requests.  It tells you the specific issue that UPS had with applying your update request.   Also, you will want to be sure and page through the entire result set as it is possible that multiple errors were returned for the same update call, and you will be able to see them all listed in the payload returned.

Finally, if you would prefer that Concur send you an update once the request has been completed you can sign up for Concur’s Event Subscription Service (ESS).    This service will publish a message when your provisioning request is complete.   This process can be used to verify if the provisioning request was successful or if errors were returned.  You could then use this information to log an issue for investigation or trigger another API call to start another application.

Here is a link to Information about ESS itself:

SAP Concur Developer Center | Event Subscription Service v4

Here is a link to the ESS setup guide:

SAP Concur Developer Center | Event Subscription Service v4 Guide

Here is a link to information about Concur’s Identity change event used by ESS:

SAP Concur Developer Center | Identity Change Event

Here is a link to information about Concur’s User Provisioning event used by ESS:

SAP Concur Developer Center | Concur User Provisioning Event

Ok, that wraps up today’s post.   Upcoming posts that we will cover are listed below.  In addition, in case you missed the prior posts, I have provided links to those as well below.

Upcoming Posts will cover:

• Spend Role Codes and entitlements.
• V1, Bulk V3 retirement and transition to V4 API
• Best Practice and Debugging tips for using UPS.

Previous Post Link in Series:

• Link to Introduction to Identity and UPS
• Link to Identity vs Spend and Travel