Fetch List Callout

The Concur Fetch List callout allows clients to import list items from an internal system to Expense when a user is filling out list fields for an expense. The Expense service sends a request for list items to an application connector, created by the client, a third-party developer, or us. The connector is hosted by the client or developer, and has access to the list item system of record. The connector uses the list information sent from Expense to search for all matching list items in the system of record. Once the connector has the list items, it sends the data to Expense. The user sees the list items and can select the appropriate item for the expense. When the user saves the expense, the list item is added to the list within Expense.

This callout differs from the inbound SAP Concur web services in the following ways:

  • It uses an outbound message where Expense calls a public facing API endpoint provided by the application connector.
  • The third-party developer or client can configure and maintain the public web service interface (the application connector), or the connector can be maintained by us. This guide specifies the request and response format required by us.
  • The client Expense administrator must configure a list (most commonly a connected list), and we must perform database configuration on the list before this service can be used.

Limitations

Access to this documentation does not provide access to the API. 

Process Flow

A process flow diagram showing flow between the SAP Concur platform, an application connector, and client's data source

Products and Editions

  • Concur Expense Professional Edition
  • The SAP Concur Mobile App

Product Restrictions

SAP Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the review process.

Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.

Concur Expense and Fetch List Configuration

Expense must have a list field configured to use an external source before this callout can be used. The client creates the list, we configure it to use the external source, and the client creates the connected list definition if necessary. If using a connected list, Expense Admin creates a connected list definition in Forms and Fields.

To configure a Fetch List callout:

  1. Follow the process to create a new Application Connector (refer to Managing Application Connectors)
  2. On the Application Connector Registration page (from Manage Application Connectors), select the desired registration from the list.
  3. Click Modify.
  4. On the System page under Services, select Fetch List.
  5. Click Configure.
  6. Add the details of your previously configured list(s): the List Name, List Category, Language Code, and Connected List Level (if applicable).
  7. Click Add List. (Repeat steps 6-7 until all desired lists are added.)
  8. Click Active.
  9. Click OK.

Note: If this Fetch List callout is made inactive and then subsequently saved on the System page, any lists that have been added to this Fetch List as a Configured List will be deleted from that Fetch List service.

Fetch List Process Overview

Once the configuration is complete, the callout uses the following process:

  1. The user selects the external source list field while creating an expense entry.
  2. Expense sends the list field information and the item codes for the previously selected levels (for connected lists) to the application connector.
  3. The application connector queries the list system of record and returns the set of list items to Expense.
  4. Expense displays the list items in a drop down list.
  5. The user selects the desired list item and saves the expense.

Security

We will make calls to the application connector’s endpoint using SSL. During configuration, we will connect to the application connector to validate that its hostname and access credentials are valid.

In the code we provide for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.

Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before we can access the connector.

Authentication

Authentication between the SAP Concur platform and the application connector is performed using HTTP Basic Authentication. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in the platform on the Register Application Connector page in Web Services under Administration.

Functions

Responses and Errors

Refer to the HTTP Status Codes page for details of the common responses and errors.

On this page