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

  1. User creates Request, assigns hierarchical organization codes to expense items, clicks Submit to send to approver.
  2. The Request moves to the first step in the approval workflow Pending External Validation.
  3. Event Subscription Service is triggered.
    • Notification for event statusChange.PENDING.ExternalValidation is sent to the URL endpoint registered by the partner.
  4. Partner’s application receives notification statusChange event notification that includes Request ID and link.
  5. Partner’s application calls Request v4 API to obtain details of Request.
  6. Partner’s Application conducts funds/budget validation in ERP System.
  7. 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.
  8. User creates Expense Report associated to the relevant Request.
  9. Expense Report completes approval workflow and is sent for Financial Posting.
  10. 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 access concur.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).

  1. 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.
  2. 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.
  3. 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.
  4. 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

  1. 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”).
  2. This is your landing page and it will be the first page the user sees upon redirect from SAP Concur solutions.
  3. 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
  1. When your application receives the redirect call, you should strip the id and requestToken values from the URI and use those on a POST request to the Concur Authorization service to obtain the official OAuth 2.0 access_token and refresh_token for the customer using the password grant.
  2. 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. The access_token should be cached in memory and discarded after use.
    • refresh_token: Used to request a new access_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 the sub element after id_token is decoded. This is the Token you will use to make Request API calls for your customers.
  3. 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

  1. 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 Expenses id and href attributes that you will need to obtain Expense data.
  2. 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

  1. Your Application performs any of the following Funds Management actions:
    • Budget Checks
    • Encumbrance
    • Commitment Creation
  2. 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
  • Possible Funds Management actions based on the above events include:
    • Encumbrance Creation
    • Commitment Creation/Update
    • Commitment Deletion

Financial Data Posting and Feedback Loop

On this page