Funds Management Integration Guide
This guide describes an integration between SAP Concur Solutions and client ERP Encumbrance or Funds Management Modules. This integration will provide near real-time budget validation of funds. The integration leverages the Event Subscription Services with Concur Request and Financial Services APIs to provide bi-directional communication between a client’s SAP Concur entity and their ERP Encumbrance or Funds Management Module.
Limitations
This feature is only available to customers who have Concur Request and Concur Expense deployed in a Professional environment.
Funds Management Workflow
- User creates Request, assigns hierarchical organization codes to expense items, clicks Submit to send to approver.
- The Request moves to the first step in the approval workflow Pending External Validation.
- Event Subscription Service is triggered.
- Notification for event
statusChange.PENDING.ExternalValidation
is sent to the URL endpoint registered by the partner.
- Notification for event
- Partner’s application receives notification
statusChange
event notification that includes Request ID and link. - Partner’s application calls Request v4 API to obtain details of Request.
- Partner’s Application conducts funds/budget validation in ERP System.
- Partner’s application either:
- Approves Request
- Create Commitment in ERP System.
- Approves Request and sends back Commitment/Document ID.
- Request moves through the workflow approvals in Concur Request. * Rejects Request
- Sends Request back to the employee for revision with an informational comment.
- Funds Management workflow starts over when Request is re-submitted.
- User creates Expense Report associated to the relevant Request.
- Expense Report completes approval workflow and is sent for Financial Posting.
- Partner’s application:
- Deletes Commitment.
- Real Cost Posting to Funds or Grants.
Event Subscription Service
The Event Subscription Service (ESS) implements Publish/Subscribe pattern using principles of Event Driven Architecture. When the Request event occurs, ESS sends that event to the configured endpoint with relevant information.
Delivery Model
It is important to remember that ESS doesn’t have an API that you can call for SAP Concur events, ESS delivers events to your endpoint. It uses an outbound callout where a public facing URL (web server hosted by you or your customer) provided by you is called. Please review the ESS Delivery Model for more details.
Access Control
ESS requires your application to have the proper authentication token and scopes. Required scopes are:
- ESS API level scope:
events.topic.read
to access ESS API. - Resource level scope:
travelrequest.write
to accessconcur.request
topic and to be able to create subscriptions to that topic.
Please review the ESS Access Control section for more details.
Service Behavior
Please review the ESS Service Behavior section for ESS characteristics from the subscriber perspective.
Authentication
Please review the ESS Authentication section for a list of ways you can ensure that your endpoint is being accessed by our service, including our Public Key.
Endpoint Requirements
It is important that you review the Endpoint Requirements section for a list of requirements your endpoint must meet.
Subscribing Your Endpoint
In order to subscribe to the relevant topic for your application concur.request
, you must first obtain the necessary credentials (Application ID and Secret) from your SAP Concur Certification Project Manager (CPM).
- Authenticate
- The authentication is done by using an authentication token that represents the event subscriber. This can be obtained by calling the Client Credentials grant type using your OAuth 2.0 credentials. The authentication token generated by this grant will have a authentication token type of App where your Application ID is the subject of the token.
- For authorization, the application needs to contain the scope
events.topic.read
in order to access the ESS API. This scope will be inherited by the authentication token during the Client Credentials Grant, which is then checked by the ESS API. This is the Token you will use to manage your subscriptions.
- Browse available topics
- Before you create any subscription, you need to verify that you have sufficient access to the topic
concur.request
. - If that request returns empty you need to get in touch with your SAP Concur CPM to set proper scopes to your application.
- Before you create any subscription, you need to verify that you have sufficient access to the topic
- Create a Subscription
- Confirm your authentication token has the scope
events.topic.read
scope. - Create a unique name (id) for your subscription. Subscription names are globally unique, and you will get an error if name is already taken. Examples:
- public.partner.{Integration Name}.concur-request.dev
- public.partner.{Integration Name}.concur-request.qa
- public.partner. {Integration Name}.concur-request.prod
- Set filter to .* (regexp syntax), you can use it later to filter out unwanted types of events.
- Confirm your authentication token has the scope
- Verify your Subscription
- You can verify your subscription to an event. You might notice that your subscription contains some parameters that you cannot modify for security reasons but can use them for troubleshooting purposes.
applicationId
- identifies your application as an owner of that subscription.companyIds
- a list of UUIDs of companies that allowed your application to access their data, the process of connecting companies to your application is described later in this document.- groups and scope - are used for complex access control scenarios.
Receiving Events
In order to begin receiving events for a customer’s entity, the customer must first enable your integration in the SAP Concur App Center.
App Center Application
Activation / Connection
Quick Connect is the process in which a customer connects their company’s SAP Concur instance to your application thus enabling your integration.
The landing page will facilitate the customer’s connection to your application. You should develop a web page that listens for an HTTP GET request from SAP Concur solutions, while adhering to the App Center UX Design Guidelines. This guide includes requirements and recommendations to help ensure that our shared users have a positive experience.
Authentication
- The connection flow begins from the SAP Concur App Center. A customer’s logged-in Company Administrator finds your App Listing and clicks the Connect button. Once the Administrator has accepted the terms & conditions, the SAP Concur App Center will open a new window to your pre-defined redirect URI (referred to as your “Connect URI”).
- This is your landing page and it will be the first page the user sees upon redirect from SAP Concur solutions.
- The redirect URI will contain the following parameters:
id
: Customer’s Unique Identifier (UUID) (Company Level).requestToken
: Temporary Token used to obtain a full access token for a customer.userId
: Unique Identifier for user who clicked the Connect button.
https://{partner_redirect_URI}?id=8568a4cd-8ffc-49d6-9417-be2d69aa075f&requestToken=5l85ae5a-426f-4d6f-8af4-08648c4b696b&userId=9bdded51-00b8-4f84-8bef-6d3afe727007
- When your application receives the redirect call, you should strip the
id
andrequestToken
values from the URI and use those on a POST request to the Concur Authorization service to obtain the official OAuth 2.0access_token
andrefresh_token
for the customer using the password grant. - When you receive the
access_token
you will also receive the elements below. Store them with the customer’s profile metadata:access_token
: Valid for only one hour. Theaccess_token
should be cached in memory and discarded after use.refresh_token
: Used to request a newaccess_token
. Has a 6-month lifetime.refresh_expires_in
: This is Epoch time format, convert to UTC.geolocation
: To be used as the base URI for all subsequent API calls on behalf of the customer.id
: The customer’s unique identifier (UUID) which is returned as thesub
element afterid_token
is decoded. This is the Token you will use to make Request API calls for your customers.
- Along with the above elements, you will also receive the scopes associated with your application. Confirm the
travelrequest.write
scope is included.
Receiving Events
Once the customer has enabled your application, you will begin receiving event notifications for Request Events. The event notification payload includes the Request id
and href
attributes that you will need to make the subsequent calls to the Request APIs.
Example of ESS Request Status Change Notification
POST https://{PartnerEndpoint}/api/ess
HEADERS: none
Body: JSON
{
"id": "5d1f9624-7a1c-49a8-af53-a40bd1134bdb",
"correlationId": "59cd7eb5-a193-4e2e-b367-32e5de313095",
"eventType": "statusChange.PENDING.ExternalValidation",
"topic": "concur.request",
"timeStamp": "2020-07-23T13:16:19.83Z",
"data": null,
"facts": {
"companyId": "2fced72e-6347-42e6-ba27-352bbe98696f",
"role": "ExternalValidation",
"workflowStepCode": "Q_EXTV",
"isClosed": "false",
"requestId": "33EK",
"actingUserId": "24ff1596-9fd0-4f2b-8c0a-c445f4301f91",
"id": "7E6C9EE209C60E488AF8367AC7B25452",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/7E6C9EE209C60E488AF8367AC7B25452",
"userId": "24ff1596-9fd0-4f2b-8c0a-c445f4301f91",
"status": "PendingExternalValidation"
},
"groups": null,
"scopes": [
"travelrequest.write"
]
}
Obtaining Request Data
- Get Request Details - Use the Get the content of an existing Request call to obtain the Request details. You will send the GET call to the
href
URI received in the Event Notification payload. The response will include the Expensesid
andhref
attributes that you will need to obtain Expense data. - Get Expected Expenses - Use the Get Expected Expense Content call to obtain the content of the expected expenses. You will send the GET call for each expense received in the Get Request Details response.
Initial External Validation
- Your Application performs any of the following Funds Management actions:
- Budget Checks
- Encumbrance
- Commitment Creation
- Your application determines if Request gets sent to approver or back to employee.
Request Workflow Action
Use the Workflow Resources to move the Request in the approval workflow. Approval actions are:
approve
: moves the Request to the next approval step.sendback
: rejects the Request and sends back to the employee, this action allows you to include a comment to the employee.
Continued External Validation
Your application should monitor event notifications for Requests that you have approved until they complete approval workflow. Certain actions by users and/or approvers could cause the Request to re-start the approval workflow or be cancelled. Examples:
- User recalls Request to edit information, requiring a re-submittal of Request.
- Approver (at any level of approval flow) rejects Request and sends it back to employee.
- User Cancels Request.
- Request events your application should monitor are:
- Canceled:
statusChange.CANCELED
- Sent Back / Recalled:
statusChange.SENTBACK
- Approved:
statusChange.APPROVED
- Canceled:
- Possible Funds Management actions based on the above events include:
- Encumbrance Creation
- Commitment Creation/Update
- Commitment Deletion
Financial Data Posting and Feedback Loop
- The ERP receives the posting data for the Concur Expense Report(s) linked to the Request via Financial Integration Service. See the Financial Posting via Financial Integration Service guide for more information.
- For information on the various financial integration processes, see Financial Integration Service Use Cases.