Migrate from deprecated SAP Concur API endpoints

Concur documentation:

• API reference on retirement date and migration
• List v3 & List item v3 (deprecated)
• List v4 & List item v4

SAP Concur has deprecated the List v3 API and List item v3 API, replacing them with List v4 and List item v4. If you have existing integrations with Concur, it's important to review your flows to ensure they do not call the endpoints scheduled for retirement.

This article explains how to find deprecated endpoints and replace them with the new endpoints.

Endpoint replacement

The following table lists the endpoints scheduled for retirement in the near future:

Updating a custom (DIY) flow

Follow the steps below to convert your existing flow configurations from deprecated to replacement operations.

Tip: If your Concur integration was based on a Celigo Quickstart integration template, you might find it simpler to reinstall the template, since the latest versions already include the List v4 and List item v4 API calls. Then, apply the corresponding changes that you’ve made to the flows for your business logic, as described in Refreshing an integration based on an SAP Concur template, below.

A. Find deprecated endpoints in existing flows

1. In integrator.io, navigate to Connections.
2. Search for Concur Expense or Concur Invoice.
3. In your first matching Concur connection, from the Actions overflow (...) menu, select Used by. A list of all items that use this connection appears.
4. Right-click the first flow step in the list and select your browser’s option to open it in a new tab.
5. Review the configuration for any of the deprecated endpoints listed in the table below:

When you encounter a deprecated endpoint, first copy the path parameter and search parameter values to a reference document to back them up when replacing the endpoints, following the instructions in the next section.

Examples of parameter replacement

Search parameters used in deprecated operations

Path parameters used in deprecated operations

Search parameters updated in replacement operations

Path parameters updated in replacement operations

B. Update flows to use replacement endpoints

For each export and import that is using a Deprecated API, find its corresponding Replacement API in the chart below, and select the new API name and operation.

For example, if the existing export is configured as follows:

• API name: Common : Lists v3 (Deprecated)
• Operation: Gets a single list by ID

Then, convert it according to the table, as follows, and as shown in the images below:

• API name: Common : Lists v4
• Operation: Get a List by List ID

Edit the export containing the deprecated operation,
and click to launch the search parameters

Notice that List ID is a Search parameter in the deprecated operation

In the upgraded v4 operation, you can now pass List ID as a path parameter

C. Add transformation rules

The responses from the Concur deprecated and replacement list endpoints are different, as demonstrated below:

As shown above, the deprecated endpoint contains the field ID, while the response of the new endpoint has id. Also, the path Items.ID is now content.id.

The new fields will affect the source record values in all of the affected flows’ import mapping. The easiest way to maintain the mapping is to add transformation rules in the export. After converting the new response data format to the old one, the mapping should work correctly.

Example response formats

Get all lists, deprecated operation response format:

{
  "Items": {
    "ConnectorID": "5678900011",
    "DisplayCodeFirst": true,
    "ExternalThreshold": 0,
    "ID": "a80a5070-3951-4316-886a-a60ab790f06b",
    "IsVendorList": true,
    "Name": "Airlines",
    "SearchCriteriaCode": "TEXT",
    "URI": "string"
  },
  "NextPage": "string"
}

Get All Lists, new operation response format:

{
  "content": [
    {
      "id": "a80a5070-3951-4316-886a-a60ab790f06b",
      "value": "Airlines",
      "levelCount": 1,
      "searchCriteria": "TEXT",
      "displayFormat": "(CODE) TEXT",
      "category": {
        "id": "a2dfc451-8f3c-410e-a5f2-20d79c8fc3dc",
        "type": "Vendor"
      },
      "isReadOnly": false,
      "isDeleted": false
    }
  ]
}

Define transformation panel with id renamed, giving its value to ID

Example transformation with Retrieve all list items based on the search criteria (deprecated) fields converted to Retrieve First Level Children Items of a List

D. Update import mappings

The responses from the deprecated and replacement Concur endpoints are different, as illustrated here:

Create a list item v4 API endpoint applied to the import, prior to mapping changes

So, after performing the changes mentioned in C. Add transformation rules, the next step is to change the mappings to remove the padlocked fields shown above.

Note that in the deprecated endpoints, as illustrated in the example below, the field name was ListID, the new endpoint name is listid, and the Concur Import field is updated.

Revised imports mappings

E. Remove unneeded transformation rules

Your legacy flows may have transformation rules applied to import flow steps, especially if you based them on an SAP Concur template. For example, the transformation rule applied in Import Concur list items (create) is no longer required for the Concur List item v4 response.

Click the Transformation rules ( ) button to the right of the import to edit these values, delete each unnecessary rule, and click Save.

Continue to revise the field mappings for the remaining flows, according to the examples provided above.

Refreshing an integration based on an SAP Concur template

The current versions of SAP Concur Celigo Quickstart integration templates have been upgraded to List v4 and List item v4 APIs. If you’ve built your integrations by modifying a template, it might be quickest to make the parallel changes from your modified list-related flows to a clean template installation, as described below:

1. Go to the integrator.io Marketplace (U.S. | EU) and open Concur Expense or Concur Invoice.
2. Find the template you had previously installed for your Concur account type and additional endpoint, and click Preview to start the installation process:
   • Acumatica – By default, SAP Concur lists are not available in any of the Concur – Acumatica templates installed from the Celigo Marketplace. The flow Concur lists to Acumatica departments is available only upon request.
     • Concur Expense (Best Practice) – Acumatica,
       Concur Expense (Enhanced) – Acumatica
     • Concur Invoice (Best Practice) – Acumatica,
       Concur Invoice (Enhanced) – Acumatica
   • NetSuite
     • Concur Expense (Best Practice) – NetSuite,
       Concur Expense (Enhanced) – NetSuite
     • Concur Invoice (Best Practice) – NetSuite,
       Concur Invoice (Enhanced) – NetSuite
   You don’t have to worry about overwriting your current integration; each new template installation produces a standalone integration in its own tile.
3. Check the flows related to lists, such as Concur lists to NetSuite departments and NetSuite departments to Concur list items, and compare the new configurations with your integration’s flows.
4. Copy the path parameters, search parameters, filter rules, and mappings (if any extra included) from your flow and paste them into the newly installed flow.
5. Delete the v3 list flows from your integration.
6. Detach the newly updated flows from the installed template integration, and attach each flow to your existing Concur integration.