- SAP Managed Tags:
I have been a Technical Consultant at SAP Concur for quite some time and have worked with many clients to help them build their interfaces between their systems and SAP Concur. While SAP Concur offers many APIs that can be called by external applications, there are also use cases where clients need their application to act based upon a trigger in Concur. The event subscription service can help in such cases by allowing external applications to subscribe to specific events and receive real-time notifications. In this blog post, we will explore how you can subscribe your applications to start receiving events.
Prerequisites Concur
To use SAP Concur's web service APIs, you must ensure that this is part of your contract with SAP Concur.
This post will not discuss authentication with Concur Expense. Please see this post to get an explanation creating an application in Concur.
You will need an application with the following SCOPEs:
- events.topic.read
- dependent on the event(s) you wish to subscribe to, further scopes are needed (check documentation)
Prerequisites Application Endpoint (webhook)
Your application needs to have a public facing endpoint available where the Event Subscription Service can deliver (POST) events to. The endpoint should:
- be set up to handle the number of events (implementing a queue is recommended)
- ensure reasonable uptime
- server endpoint must be accessible with a certificate that is signed by a known Certificate Authority and reachable through DNS
It is strongly recommended that you use the certificate Common Name as the authentication mechanism to ensure your endpoint is accessed by Concur’s service.
Introduction
At the moment of publishing there are events available for:
- Expense workflow
- Request workflow
- Financial Integration
- Itinerary
- User Provisioning
- Identity change
- Document Tax Compliance
- Travel
To start receiving events you must register your system with the Event Subscription Service and specify the topic you’re subscribing to (some topics even allow for additional filtering).
Detailed Walkthrough
- Obtain application-level Bearer token
- Get available event topics
- Check existing subscriptions
- Create/update a subscription
- Verify subscription
- Delete subscription
- Activate subscription
Before we dive into the details, I would like to highlight the resources where SAP Concur has these APIs documented. On the Concur Developer Center you will find a section on the Event Subscription Service v4. It is also listed on the SAP Business Accelerator Hub under Event Service.
I would also recommend checking out the Postman collection that I prepared. It will include all the steps that are described in this blogpost.
Obtain application-level Bearer token
The Event Subscription Services (ESS) v4 APIs require an application-level bearer token, which can be retrieved by using the client credentials grant type. Use below CURL statement to create the API call and replace the dataCenterURI, clientId and clientSecret.
curl --location ' https://{{dataCenterURI}}/oauth2/v0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={{clientId}}' \
--data-urlencode 'client_secret={{clientSecret}}' \
--data-urlencode 'grant_type=client_credentials'
Note: you can find what data center URI to use here.
Get available event topics
What event topics you can subscribe to will depend on the scopes that are available on the registered application. In the documentation (SAP Concur Developer Center | Event Subscription Management) you will find the necessary scopes required for the different event.
To find out what topics your application can register, you can retrieve the available topics for your application.
Example API call
GET /events/v4/topics
Check existing subscriptions
You can check whether your application already subscribed to any events. The following call would return all subscriptions for your application.
Example API call
GET /events/v4/subscriptions
Example API response:
Create/update a subscription
If you would like to create a new subscription, then you will need to register a (descriptive) system identifier (id) for a specific event topic (topic) for a particular webhook endpoint (endpoint). Each subscription is linked to one topic and each application can have up to 5 subscriptions.
Some event topics allow for additional filtering. Check the documentation if that is the case for the even that you wish to describe to. In the example below the filter is set to subscribe to all types of events within the topic.
Example API call
PUT /events/v4/subscriptions/webhook
{
"id": "external-approval-system-xyz",
"filter": ".*",
"topic": "public.concur.expense.report",
"webHookConfig": {
"endpoint": "https://some.valid.webhook.endpoint/"
}
}
A successful response would be a 200 message with a message stating the subscription was saved successfully.
Verify subscription
To verify your subscription, you can do another GET call with the “id” from the registration in the endpoint. Taking the id from the previous example (“external-approval-system-xyz”) this would look like the example below.
Example API call
GET /events/v4/subscriptions/external-approval-system-xyz
Example API response:
Delete subscription
Subscriptions that are no longer needed can be deleted.
Example API call
DELETE /events/v4/subscriptions/external-approval-system-xyz
Activate subscription
By this point you’ve probably used the previous subscription APIs to register one or more endpoints for one or more types of events. The subscription itself will not activate the Event Subscription Service for your application. The final step is to (re-)create a company JWT, which will update the ESS subscriptions with the company Id of the Concur entity.
In your Concur system, navigate to Administration > Authentication Admin > Company Request Token
Enter your client id as the App ID and submit to generate a request token. Afterwards follow the steps described on the same page to complete the process of obtaining a Company JWT. Please see this post to get a detailed explanation on authentication within Concur.
Once done, please verify again your subscription by doing a GET and you should see that the “companyIds” array is no longer empty and instead populated with the company id of your Concur entity.
Event Subscription Service behavior
The service has the following characteristics from the subscriber perspective:
- Requests will come from us.api.concursolutions.com, emea.api.concursolutions.com, or cn.api.concursolutions.com.
- Connection will always be established using a mutual TLS with webhook.api.concursolutions.com x509 certificate.
- Requests will always have a digital signature.
- Requests will be re-tried when the subscriber responds with HTTP Response Code(s): 5xx, 401, 403, or 429.
- Requests will not be re-tried when subscriber responds with HTTP Response Code(s):
- 2xx – Indicates successful receipt of the event.
- 4xx – Indicates posted event is unexpected or incorrectly formatted.
- Request will be retried until delivery OR event retention period expiration.
- Event retention period is 72 hours from the time of event being published.
- Events are not archived, but all of the event delivery attempts/responses are logged and retained for 30 days.
Conclusion
The Event Subscription Service will be very useful if you are building an application that needs to act upon a trigger/change that occurs in your Concur system. Such triggers could for example be a certain step in the workflow, a change on the user profile, a travel itinerary change, etc. While these subscriptions may sometimes trigger more events than your application may need, it will include enough information to identify what events to act upon.
Events allow applications to respond to specific scenarios immediately. They do not need to schedule API calls to find and identify the scenario on which it needs to act.
With the examples shown in this blogpost and the linked Postman collection, you should be well on your way to register and activate your first event subscription.
Share and Connect
What do you think? Do you have anything to add? Leave a comment below.
Did you find it useful? Give us a like and share on social media.
Do you have questions or want to know more about SAP Concur and its offerings? Please follow us here.
Thank you!
