How to integrate Concur with Sapho version 4.5 and greater

Last update:

Requirements

1. To connect Sapho to your production instance of Concur, you must have the Web Services component purchased from Concur. If your company hasn’t purchased the Web Services component, ask the Concur administrator in your organization to contact your Account Manager at Concur.

2. If your internal server hosting Sapho is behind a firewall, you will need to allow access to hostname www.concursolutions.com or www.us.api.concursolutions.com if you use OAuth1 if you use OAuth2, both with port 443, so Sapho can connect to the Concur cloud.

 

Tutorial 1: How to set up the Concur connector in Sapho using OAuth1

Please note:

  • This tutorial assumes you are a person who administers the Concur instance of your organization.
  • We recommend setting up the Concur connector using a dedicated user account. Having a separate user account will enable delegated authentication and transparency in your audit logs. Steps 1-3 below describe how to create a new user in Concur and assign the appropriate privileges to it.

Step 1: Sign in

Log in to www.concursolutions.com.

Step 2: Go to Expense Settings page

Hover over the Administration button in the top right corner of the Concur UI and click on Expense Settings.

c3.png

In the Expense Setup for your company, go to Users.

c4.png

Step 3: Create a new user

Click the button for Create/Edit User.

Add the required user details in the fields marked in red.

TIP: Since this new user needs an email address as its Login, we recommend creating a distribution group in your email system of employees in your organization who manage Concur (e.g. “saphoconcur@yourcompany.com”) and using that address. This ensures that you don’t need to manage a separate mailbox from your email provider.

For future reference, save the information you entered for the following fields: (1) Login (email address) and (2) Password because you will need to paste it in Sapho.

Set the user as Active and select the following checkboxes for user permissions:

  • Can Administer
  • Can Submit Expense Reports
  • Can Approve Expense Reports.

Click the Save button at the top of the page.

Step 4: Go to Partner Application Administration page

Hover over the Administration button in the top right corner of the Concur UI. Then, hover over Company and click Web Services.

c5.png

Step 5: Go to Application Registration page

On the left side, click on Register Partner Application.

a.png

Step 6: Add partner application & set access permissions

Click the New button.

b.png

On the form page:

  • Fill in Name and Description fields.
  • Add access to the following APIs by selecting the corresponding checkboxes:
    • Expense Report - Add, Approve, or Update Expense Reports
    • Imaging - Add or Retrieve Report and Line Item Images
    • List Items - Add, Update, or Delete List Items
    • Users - Add or Update User Accounts.

c.png

Step 7: Get the consumer key

On the same form for New Partner Application, under Application Authorization, you will find the consumer key. Copy and paste it in a secure place for later reference.

d.png

Step 8: Save the application

Click the OK button to save the partner application.

Step 9: Log in the Sapho Builder (Admin)

Go to the Connectors or Micro Apps page and start the Add Concur Connector or Add Concur Micro App wizard by clicking on the Concur icon.

Step 10: Update the URL of your instance (if needed)

The Instance URL is the domain in which your Concur instance resides. You can read more about these domains here. The default Instance URL is https://www.us.api.concursolutions.com, but you can update it as needed.

Step 11: Enter the username of your dedicated Concur account

The username is the Login (email address) you set for your dedicated Concur user account.

Step 12: Enter the password of your dedicated Concur account

Again, this is the password you set for your dedicated Concur user account.

Step 13: Enter the consumer key

This is the consumer key you obtained in Step 7.

Step 14: Finish the creation of the connector

Click Next to finish the creation of the connector. If you'd like to limit the data downloaded by the connector, see the Load Filters section below.

 

Tutorial 2: How to set up the Concur connector in Sapho using OAuth2

Please note:

  • This tutorial assumes you are a person who administers the Concur instance of your organization.
  • We recommend setting up the Concur connector using a dedicated user account. Having a separate user account will enable delegated authentication and transparency in your audit logs. Steps 1-3 below describe how to create a new user in Concur and 

Step 1: Sign in

Log in to www.concursolutions.com.

Step 2: Go to Expense Settings page

Hover over the Administration button in the top right corner of the Concur UI. Then click on Expense Settings.

c3.png

In the Expense Setup for your company, go to Users.

c4.png

Step 3: Create a new user

Click the button for Create/Edit User.

Add the required user details in the fields marked as red.

TIP: Since this new user needs an email address as its Login, we recommend creating a distribution group in your email system of employees in your organization who manage Concur (e.g. “saphoconcur@yourcompany.com”) and using that address.This ensures that you don’t need to manage a separate mailbox from your email provider.

For future reference, save the information you entered for the following fields: (1) Login (email address) and (2) Password because you will need to paste it in Sapho.

Set the user as Active and select the following checkboxes for user permissions:

  • Can Administer
  • Can Submit Expense Reports
  • Can Approve Expense Reports.

Click the Save button at the top of the page.

Step 4: Getting clientID / clientSecret

Work with Concur’s implementation team to obtain a new oauth2 client_id and client_secret and to define the scope of client’s application.

This process should take no longer than 48 hours.

The Implementation Team will respond with a new client_id, a new client_secret, your company’s refreshToken, and an expiry date.

Step 5: Log into the Sapho Builder (Admin)

Go to the Connectors or Micro Apps page and start the Add Concur Connector or Add Concur Micro App wizard by clicking on the Concur icon.

Step 6: Update the URL of your instance (if needed)

The Instance URL is the domain in which your Concur instance resides.

You can read more about these domains here. The default Instance URL is https://www.us.api.concursolutions.com , but you can update it as needed.

Step 7: Enter the username of your dedicated Concur account

The username is the Login (email address) you set for your dedicated Concur user account.

Step 8: Enter the password of your dedicated Concur account

Again, this is the password you set for your dedicated Concur user account.

Step 9: Enter the client_id and client_secret

These are the two keys you obtained in Step 4.

Step 10: Select the modules you want to synchronize

Use the switches at the bottom of the page to define the modules that need to be synchronized. If you do not have the Travel module activated, please switch the Travel Module off.

Step 11: Finish the creation of the connector

Click Next to finish the creation of the connector. If you'd like to limit the data downloaded by the connector, see the Load Filters section below.

 

Load Filters

The amount of data the connector will retrieve from Concur can be limited by applying a load filter. When you are in the "Select Entities to Sync with Sapho" screen in the connector wizard, set the Advanced Features toggle to ON.

You will notice that the default filter for the Reports entity is set to "Last 3 Months". This means the connector will load Concur expense reports created or modified during the last 3 months.

You can change the load filter to any of the predefined options, or you can click in the input field and write a custom filter, e.g. monthsToLoad=20.

Important Note: If your organisation does not have all Concur Modules activated, please make sure to set the related entity filters to 0. For example, if you would like to deactivate downloading data from the Travel Module, both of the Concur itineraries entity filters need to be set to 0 as indicated below:

historicalMonthsToLoad=0&futureMonthsToLoad=0

 

Troubleshooting

Possible issue #1: Sapho on-premises (most likely behind a firewall) might not be able to connect to the Concur cloud.

Solution: In your firewall settings, allow access to the hostname www.concursolutions.com with port 443, so Sapho can connect to the Concur cloud.

 

Possible issue #2: The site of concursolutions.com is down.

Solution: Check the status of the site here. If it’s marked as down, you will need to wait until it is back up. 

 

Delegated Authentication and Audit Trail

Once you have created a separate user in Concur and set up the connector in Sapho using that user account, you need to complete one more step for delegated authentication to work.

Sapho requires that all employees who are going to frequently use the micro apps to set the user account with which the connection to Concur was made as an Expense Delegate. Provide them with the employee name, email address, employee id, or login id of the dedicated account and ask them to adjust their Concur profile settings as described in Tutorial 2.

This will allow transparency in the Audit Trail of each Concur expense report. For example, when a manager approves an expense report through Sapho, their name will appear in the Updated By column (1) inline with the action that changed the report status to Approved. Additionally, their email will be available in the Description column in the Comment section (2).

c16.png

This comment is added by Sapho, not the end user itself. The purpose of this comment is to let Concur administrators distinguish which expense reports have been approved specifically through Sapho.

 

Tutorial 3: How to set up an Expense Delegate in Concur

This tutorial is intended for end users who are going to use Sapho to have streamlined access to Concur (such as approving reports in a few taps on their mobile phone). It is expected that you have been provided with the employee name, email address, employee id or login id of the user account used to connect Sapho to Concur.

Step 1: Sign in

Log in to www.concursolutions.com.

Step 2: Go to Profile Settings

In the top right corner of the Concur UI, click on Profile and then on Profile Settings.

e.png

Step 3: Go to Expense Delegates

Click on Expense Delegates.

f.png

Step 4: Add an expense delegate

On the Delegates tab, click the Add button.

g.png

Step 5: Find a delegate

Find the user account that was used to connect Sapho to Concur by entering the employee name, email address, employee id, or login id. (It is expected that one of these details will be provided by your System Admin). Click the Add button next to the search box.

i.png

Step 6: Add rights for the delegate

Assign the following permissions to the expense delegate:

  • Can Approve
  • Can View Receipts.

h.png

Step 7: Save changes

Click the Save button.