Launch External URL - Concur Request v4

The Launch External URL callout gives clients and third-party developers the ability to extend the functionality of the SAP Concur platform providing a means to deliver custom user interactions, or access functionality found in an external system. The client can add a Request Header, Request Entry, or Allocation form field that is configured to use the Launch External URL callout. Concur Request will display this field with an attached button that launches a separate browser window when clicked. The window is controlled by an application connector, created by a third-party developer or the client. The application connector is a web server that presents information in the window.

The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), they click a button such as “Done” that indicates the user has concluded their work in the window. The application connector or user closes the window.

The application connector can use web services to send information to update field values on the Request Header, Request Entry, or Allocation form types. The application connector may send the updates before or after the user closes the window. When the user returns to the SAP Concur platform, the page refreshes and they see the updated values only if the updates are made before the window is closed.

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

  • It uses an outbound callout where Request calls a public facing URL provided by the application connector, which is a web server hosted by the third-party developer or client. The connector domain must be on the allow list created during the configuration process.
  • The application connector can also use the web services to read or update SAP Concur data.
  • The developer or client can configure and maintain the application connector, or the connector can be maintained by us. This guide specifies the request and response format required.
  • The client Request administrator must configure a new form field and add the field to the desired form before this service can be used.

Limitations

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

Process Flow

Process Flow for Launch External Service

Products and Editions

  • Concur Request Professional Edition
  • The SAP Concur mobile app

Limitations

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 SAP Concur Integration Services to create custom applications that work with their configuration.

The Launch External URL callout is not supported for request entry bulk editing. For situations where the data needs to be the same, we recommend configuring Copy-Down of the desired data fields.

Only the Employee role can interact with the Launch External URL configured field. Request Approver and Request Administrator roles will not have access to open or interact with the Launch External URL callout configured field. When the Launch External URL field is configured, the Request Approver and Request Administrator roles should be configured as read-only or hidden.

If the Launch External URL callout is used as part of a process with other Request APIs to retrieve information from the Request Header, Entry, or Allocation, we recommend configuring the Request Form to have the Launch External URL callout field follow other fields that data will be retrieved from (i.e., place the Launch External URL callout field sequentially after the other fields).

The system requires certain named fields (not custom fields) to be completed before a user can open the Launch External URL configured field. The system will perform an abbreviated save to make the request record available to external APIs. These are the fields required to be completed by the end user before the Launch External URL callout can be opened (if these fields are included and configured as site required on the form):

  • At the Request Header level: Request Name, Request Date, Policy, and Start/End Date
  • At the Request Entry level: Expense Type, Amount, Transaction Date, Payment Type, and Currency

Any audit rules configured as Save actions will not be visible to the end user until the user returns to the Concur Request application from the pop-up window.

Launch External URL v4 is not currently supported in the China Datacenter.

Launch URL Process Overview

The configuration process has the following steps:

  1. Third-party developer, client or us downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.

  2. Concur Request registers the application connector. Be ready to supply the test and production domain information.

  3. Request Administrator creates a new form field with the Launch External URL control type and adds the field to the Request Header, Request Entry, or Allocation form(s).

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

  1. The user clicks the button next to the read-only Launch URL form field.

  2. Concur Request launches a new browser window and sends the Request Header, Entry, or Allocation Details URI, Company Domain, Employee ID, and Unique User ID in an encoded query string to the application connector.

  3. The application connector parses the query string to extract the sent data.

  4. The application connector uses an SAP Concur web service to gather information. This may be Request Header, Request Entry, or Allocation information.

  5. The application connector presents a web page in the new browser window for the end user. This can be a page from a commercial application, or a custom web application.

  6. The user completes the process in the external system in the browser window.

  7. The application connector sends any field update information to Concur Request using the SAP Concur web services.

  8. The user or the application connector closes the window and returns to Concur Request.

  9. Concur Request reloads the page the user came from in order to display any updated field values (if the application connector sends a value before the window is closed).

Note: Concur Request will perform a save for the area where the user came from (Entry, Allocation, Header) before the new browser window opens and upon refresh after the window is closed.

Security

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

Concur Request provides 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.

Concur Request 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 access.

Authorization

Launch External URL V4 uses the Authentication Grant process. When Launch External URL v4 calls are made, and the end-user is already logged into Concur, the customer or third party application will receive a temporary token in the query parameter, client_auth_code. Since the Launch External URL callout completes the first leg of this 3-legged OAuth2 grant, your application must then exchange the temporary token for a refresh token and access token. For this, please refer to the Authentication Grant page for the POST /oauth2/v0/token details.

Note: Users must be logged into their SAP Concur account for this process to work correctly.

Information on the Launch External URL setup is provided in the Configure Launch External URL v4 Service section below.

Functions

Details of the URI used for the Launch External URL request can be found on the Launch External URL - Request v4 page.

Concur Request Configuration

A custom field in Request with text data type for the Request Header, Entry, or Allocation must be configured as the Launch URL control type and the form field must be added to the desired form before this callout can be used. The Launch URL control type will not appear in the list until a partner application using the Launch External URL API has been registered and enabled for the company. The administrator must select either a single-line or a multi-line control type, depending on the data that will be placed in the field.

Note:

  • The Launch External URL currently only works with Professional Edition.
  • The Launch External URL is available to be configured at the Request Header, Entry, or Allocations-level fields.

Responses and Errors

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

Application Connector Management

SAP Concur administrators use the Manage Application Connectors link on the web services page under Administration to register, test, and enable application connectors.

Information on how to create, install, and configure the application connector is included in Callouts and Application Connectors.

Note: The application connector must use the same username and password pair to generate its validation signature hash. Both the username and password must be at least 10 characters for increased security and the maximum allowed length is 50 characters.

Configure Launch External URL v4 Service

Your client ID must first be registered. Details on registering your client ID can be found on the Authentication Grant page. The client ID used for the callout must have the redirect URL registered and the following grants assigned.

Required Grants: refresh_token, password, client_credentials, and authorization_code

No scopes are required to use the Launch External URL callout. However, if the Launch External URL callout is used as part of a process with other SAP Concur APIs, scopes for those other APIs will be needed.

The following steps explain how to register an application connector.

  1. On the Application Connector Registration page, select the desired registration from the list.

  2. Click Modify.

  3. In the Services section, select Launch External URL.

  4. Click Configure. The Configure Service window appears.

  5. Enter a valid URL for the endpoint that Concur Request will connect to on the host.

  • Confirm that the endpoint matches the actual endpoint of the remote service.
  • “Host Name” configured above plus “endpoint” will be the actual endpoint used when Concur Request connects to the clients’ application connector.

  1. Select the Active check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.

  2. Ensure the Service Version is set to v4 (only required if moving from v1 to v4).

  3. Enter the Client ID (used to identify your application).

  4. Enter the Redirect URL (base URL from which client will call to get User JWT).

  5. Click OK. The service is configured for your host.

  6. Click Save, to return to the Application Connector Registration page.

Launch External URL Form Field Configuration

Create a new form field with the Launch External URL control type.

  1. Click Administration > Request > Forms and Fields (left menu).

  2. Select the Form Type of Request Header, Request Entry, or Request Allocation.

  3. Click the Fields tab.

  4. Select a custom field and click Modify Field. Enter the field information, as example shown below:

  • Field Name: Cost Object
  • Control Type: Launch URL (Single-line) or Launch URL (Multi-line)
  • Application Connector: [Name of Application Connector Registered]
  • Popup Width: 400
  • Popup Height: 400

  1. Click Save.

  2. Go to the Forms tab and add the newly created field to the form.

Important Note: Make sure the Access Rights are set to Modify for the Employee role. Request Approver and Request Administrator roles should be configured as read-only or hidden.

On this page