Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Concur Connector

The Concur connector is a closed-source connector that provides a connection between Mule and third-party SaaS from SAP, called Concur. It implements SOAP calls to different API versions, depending on the Concur API. See what API versions and operations are supported in the release notes for the particular version of Concur connector you plan to use.

This document provides detailed instructions on how to install the MuleSoft Concur connector and how to build and run simple demo applications that use this connector.

Prerequisites

To run the connector and build the demo applications you need the following:

Create Concur Developer Sandbox Account

You can skip this step if you already have a Concur account set up.
  1. Create an account on https://developer.concur.com/register. When you create a Sandbox for the first time, you will be run through the Setup Wizard to configure your instance of Concur to meet your specific requirements. The details will vary from person to person, so advising on how to configure Concur is out of the remit of this document. However, there are some specific requirements to ensure that all the APIs provided with this Connector work correctly:

    1. Any expenses you want to use when submitting Expense Reports MUST have Expense Codes configured.

    2. The user that you use to configure the Connector’s Credentials must have a manager, who is configured to Approve Expenses, if you want to be able to submit Expense Reports

  2. Log into https://www.concursolutions.com/ using your newly created account (or your previously existing Concur account if you are not using a developer sandbox).

  3. In the Concur Dashboard, choose the Administration menu, and then "Web Services"

    Choose

  4. Choose "Register Partner Application"

  5. Choose New and provide a name and description. Make sure the partner application is set to "Active", and tick the APIs you want to enable access to. It is important that you have enabled access for the APIs you want to use. In this case, we will select them all. Note down the Key and Secret values and select OK

    Note Key and Secret fields

Installing and Configuring the Concur Connector

  1. In Anypoint Studio select Help > Install New Software…​.

  2. Select Anypoint Connectors Update Site or http://repository.mulesoft.org/connectors/releases/3.5.0 from the Work with dropdown.

  3. From the Select folder check Version 3.0 of the Concur Connector and click Next.

  4. Follow the installation instructions.

Configuring a Concur Connector Global Element

  1. Start Anypoint Studio and select File > New > Mule Project menu item.

  2. Type Demo as a project name and click Next.

  3. Accept default values on the next screen of the wizard and click Finish.

  4. Double-click on src/main/app/Demo.xml to open.

  5. Select the Global Elements tab.

  6. Click on the Create button, search for Concur and add the Concur to the configuration. Add Concur Connector

  7. Set the Concur Connector parameters:

    1. Username and password (the same ones you used to login to the developer sandbox)

    2. Api URL - (typically https://www.concursolutions.com/ for the Developer Sandbox)

    3. Consumer Key (the value of "Key" when registering the Partner application.

      Concur Connector Parameters

Using the Concur Connector

With the Concur connector you can create and extract data with most of the Concur APIs, however certain operations are off-limits to connectors. The operations offered are based on what is available in the Concur Developer Sandbox.

Connecting to Concur

The Concur connector uses OAuth Native Flow to connect to Concur. This is described in detail on the Concur Authentication page. To allow OAuth connectivity, configure the connector with a username, password, API URL (typically https://www.concursolutions.com/), and an API Key.

If you are using a licensed version of Concur, you will be able to set up connectivity by creating an appropriate partner application, in the "Web Services" section of your Concur instance.

With a partner application set up and the appropriate configuration details available, you can use the Concur connector in your Mule flows. When you add a Concur connector object to your flow, you can configure it to use a global configuration reference, also known as a global element, for your login details the same way as for any other Anypoint Connector. See Configuring a Concur Connector Global Element above for details.

Use Cases

This user manual presents two of many use cases you might have for the Concur connector in your organization. You may jump ahead and paste the Complete Flow XML into the XML Editor in Studio after the Concur connector has been downloaded and a global element referencing your Concur instance credentials has been created. Download other demo applications here

Getting a List of Lists

  1. After starting a new project and creating a Concur global element that references the credentials needed to connect to your instance, complete the following.

  2. Add a new Flow element by dragging it from the palette and name it "getlists".

    flow-elem

    Create List Users Flow

  3. Drag an HTTP Endpoint into your flow from the palette.

  4. Double-click the HTTP Endpoint and click the green plus sign next to the Connector Configuration dropdown and set as below.

    Create HTTP Endpoint1

  5. Click OK to close the properties window, then enter "getlists" as the value in the "Path" field in this HTTP listener’s "Basic Settings" section.

    getlists path

  6. Add a Concur connector to the new flow and configure its properties according to the following images:

    Create Concur Connector

  7. Finally, add an Object to JSON transformer to the flow.

    Object to JSON transformer

  8. For reference you may check the particular "getlists" flow within the full demo Flow XML section.

Testing the Get List of Lists Flow

  1. Right-click on the project in the Package Explorer, and click Run As > Mule Application

    Run As Mule Application

  2. Check that the application has started by monitoring the Studio console.

  3. Open a browser and go to the http://localhost:8081/getlists URL.

  4. You should receive a JSON response like this

    
                  
               
    1
    
    {"list":[{"batchLink":"https://www.concursolutions.com/api/expense/list/v1.0/gWqXO46r6GsRt9CeqUjOAfZXRTmGyyVczqg/batch","id":"https://www.concursolutions.com/api/expense/list/v1.0/gWqXO46r6GsRt9CeqUjOAfZXRTmGyyVczqg","isVendor":false,"itemsLink":"https://www.concursolutions.com/api/expense/list/v1.0/gWqXO46r6GsRt9CeqUjOAfZXRTmGyyVczqg/items","levels":1,"name":"AT Tax Form List 1"},{"batchLink":"https://www.concursolutions.com/api/expense/list/v1.0/gWqXO46r6GsRsUIXmIbg3iUc6qE9AlKEVxA/batch","id":"https://www.concursolutions.com/api/expense/list/v1.0/gWqXO46r6GsRsUIXmIbg3iUc6qE9AlKEVxA","isVendor":false,"itemsLink":"https://www.concursolutions.com/api/expense/list/v1.0/gWqXO46r6GsRsUIXmIbg3iUc6qE9AlKEVxA/items","levels":1,"name":"BE Tax Form List 1"},{"batchLink":"https://www.concursolutions.com/api/expense/list/v1.0/gWqXO46r6GscWDPncbQqGUoCjCv4pxrnp2A/batch","id":"https://www.concursolutions.com/api/expense/list/v1.0/gWqXO46r6GscWDPncbQqGUoCjCv4pxrnp2A","isVendor":false,"itemsLink":"https://www.concursolutions.com/api/expense/list/v1.0/gWqXO46r6GscWDPncbQqGUoCjCv4pxrnp2A/items","levels":1,"name":"CH Tax Form List 1"}
  5. Hit the stop button to halt the server running the application.

Creating a Get Quick Expenses Flow

  1. Add a new Flow element by dragging it from the palette and name it "getquickexpenses".

    Create Get QuickExpenses Flow

  2. Add an HTTP Endpoint to your flow by dragging it from the palette.

  3. Use the configuration from the first demo, or if you did not create that flow, click the green plus sign next to Connector Configuration for the HTTP endpoint and enter the values as shown below.

    Create HTTP Endpoint2

  4. Click OK to close the properties window, then enter "getquickexpenses" as the value in the "Path" field in this HTTP listener’s "Basic Settings" section.

    path quickexp

  5. Add the Concur connector to the new flow and configure its properties according to the following images:

    Create Concur Connector

  6. Finally, add Object to JSON transformer as with the previous example.

Testing the Get Quick Expenses Flow

  1. Right-click the project in Package Explorer and click Run As > Mule Application.

    Run As Mule Application

  2. Check the console to see when the application starts.

  3. Open the browser and go to the http://localhost:8081/getquickexpenses URL.

  4. You should receive a JSON response like this:

    
                 
              
    1
    
    {"items":{"quickExpense":[{"comment":"","currencyCode":"USD","expenseTypeCode":"UNDEF","expenseTypeName":"Undefined","id":"gWr7TiTHdIi5fyWCPBRPtqjeCIWyv2w","locationName":"","ownerLoginID":"","ownerName":"Unknown","paymentTypeCode":"PENDC","receiptImageID":"","transactionAmount":111.0,"transactionDate":"2017-07-21T00:00:00","uri":"https://www.concursolutions.com/api/v3.0/expense/quickexpenses/gWr7TiTHdIi5fyWCPBRPtqjeCIWyv2w","vendorDescription":""},{"comment":"","currencyCode":"USD","expenseTypeCode":"UNDEF","expenseTypeName":"Undefined","id":"gWr7TiTXbQ47PtJ$pVkr6CzbLeRVRPww","locationName":"","ownerLoginID":"","ownerName":"Unknown","paymentTypeCode":"PENDC","receiptImageID":"","transactionAmount":111.0,"transactionDate":"2017-07-21T00:00:00","uri":"https://www.concursolutions.com/api/v3.0/expense/quickexpenses/gWr7TiTXbQ47PtJ$pVkr6CzbLeRVRPww","vendorDescription":""},
  5. Hit the stop button to halt the server running the application.

Complete Flow XML

The final flow XML should look like this:


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw" xmlns:concur="http://www.mulesoft.org/schema/mule/concur" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns:http="http://www.mulesoft.org/schema/mule/http"
        xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
        xmlns:spring="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd
http://www.mulesoft.org/schema/mule/concur http://www.mulesoft.org/schema/mule/concur/current/mule-concur.xsd
http://www.mulesoft.org/schema/mule/ee/dw http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd
http://www.mulesoft.org/schema/mule/json http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd">
    <http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration" />
            <concur:config name="Concur" username="${concur.username}" password="${concur.password}" apiUrl="${concur.apiUrl}" consumerKey="${concur.consumerKey}" doc:name="ConcurConnector">
            <concur:connection-pooling-profile initialisationPolicy="INITIALISE_ONE" exhaustedAction="WHEN_EXHAUSTED_GROW"/></concur:config>
        <flow name="getlists">
<http:listener config-ref="HTTP_Listener_Configuration"   path="getlists" doc:name="HTTP" />
    <concur:get-list-of-lists config-ref="Concur" doc:name="Concur"/>
            <json:object-to-json-transformer doc:name="Object to JSON"/>
        </flow>
        <flow name="getquickexpenses" >
<http:listener config-ref="HTTP_Listener_Configuration"   path="getquickexpenses" doc:name="HTTP" />
<concur:quick-expense-list config-ref="Concur" doc:name="GetQuickExpenses"/>
            <json:object-to-json-transformer doc:name="Object to JSON"/>
        </flow>
    </mule>

Concur API Availability

The various Concur APIs and their availability through MuleSoft’s connector are described in the section below. Moreover, this user guide is designed to be referenced alongside Concur’s API specifications available at the Concur documentation site.

Concur Connector 3.0 - Supported Concur API Versions

This is the breakdown of supported API operations as of version 3.0 of the Anypoint Concur connector. For more information on each of the operations see the sections below this table.

Name Version Supported operations

Attendees

v3.0

  • Get List Of Attendees

  • Get Expense Entry Attendee Details By Id

  • Post Expense Entry Attendee

Expense Entries

v3.0

  • Get List Of Expense Entries

  • Get Expense Entry Details By Id

  • Post Expense Entry Request

  • Update Expense Entry Request

  • Delete Expense Entry

Image

v3.0

  • Get List Of Receipts

  • Get Receipt Image Uri

  • Create Receipt Image

  • Delete Receipt Image

Expense Reports

v3.0

  • Get List Of Expense Reports

  • Get Expense Report Details By Id

  • Post Expense Report Header

  • Update Expense Report Header

Quick Expense

v3.0

  • Quick Expense List

  • Quick Expense By Id

  • Quick Expense

  • Update Quick Expense

  • Delete Quick Expense

Expense Group Configuration

v1.1

  • Get Expense Group Configuration

Trips

v1.1

  • List Itineraries

  • Get Itinerary

Payment Batches

v1.1

  • Get List Of PaymentBatches

Expense

v1.1

  • Post Expense Report Header Batch

  • Post Expense Report Submit Request

Attendees

v1.0

  • Batch Attendee List

Expense

v1.0

  • Batch List Items

  • Get List Details

  • Get List Items

  • Get List Of Form Fields

  • Get List Of Forms Of Payment

  • Get List Of Lists

Loyalty Program

v1.0

  • Update Loyalty Program

Trips

v1.0

  • Get Travel Profile

  • Get Travel Requests List

  • Get Updated Travel Profiles

  • Trip Approval

User

v1.0

  • Create Or Update Users

  • Get User Profile

Attendee

Manage and retrieve attendee information using this Concur web service, comprising the following APIs, two of which are fully supported.

  • Attendee List: POST

    • This API is fully supported under "Batch Attendee List". All Attendee List operations are managed in batches (including, for example, a "batch" of one), with a supplied Batch Type parameter determining if the batch should be CREATE-ed or UPDATE-ed. Batches have a maximum size of 1000, and anything above a size 1000 is ignored. The connector will throw an exception if a batch of size > 1000 items is submitted.

  • Attendee: GET

    • Fully supported as GET Attendee Details endpoint.

  • Attendee Type: GET

    • This API is not supported at this time.

Expense

Posting expense report information is a multi-stage process. Refer to the Expense Report Resource page for the steps required to post new expense reports and entries. Note that v1.1 APIs use different API formats from v2.0 APIs, and translation may be required. An ID for a v1.1 API is of the format "nOlmsYX2xcsvI7b\($p$\)snbhLUZq19M7jxRtk", whereas a 2.0 ID uses a shorter ID without special characters, in the format "425FE2ADB4954FCA90CD". Unfortunately, APIs are not available in both versions, so the user should be aware of this behavior.

  • Expense Entry Attendee: GET

    • V1.1 of this API is partially supported, but V2.0 is not supported at this time. GET List of Attendees and GET Attendee Details are both supported.

  • Expense Entry Attendee: POST

    • v1.1 of this API is supported, and operates in a Batch.

  • Expense Entry: GET

    • Get Expense Entry Details is supported, but note that Report and Entry ID fields returned from some APIs are not completely compatible across endpoints. Concur’s behavior is inconsistent in this area, for example "URI Source: The reportId value is returned in the RptKey element and the entryId value is returned in the RpeKey element by the function Get Full Report Details v1.1. The full URL is provided within the itemurl query string for the Request for the Launch External URL callout, and in the Report-Entry-Details-Url element by the Post Expense Entry function response." Do not expect a Report ID from one Web Service to work with another unless the documentation specifically states so.

  • Expense Entry: POST

    • Posts an expense entry for a given report, after a report header has been created. EntryID is optional, and is only required when a specific entry must be updated.

Concur recommends that you post one expense entry per request. Future versions of this endpoint will require this behavior.
  • Expense Report Header: POST

    • This API works in both single header (post Expense Report Header) and batch (post Expense Report Header Batch) modes. Report ID is only needed when updating an existing report. Note that the input types are different for single headers versus batches.

  • Expense Report: GET

    • V2.0 of this API is supported. GET List of Reports is supported, with a large number of (all optional) search filters as parameters. GET Report Details is supported, but may have inconsistent behavior based on Concur instance configuration, e.g. NOTE: Some elements will appear only if the OAuth consumer has the Web Services Admin role. These include: The ReportKey element, the employee’s credit card information, and the employee’s bank account information, VAT information, Journal entries. The Mule Connector does not support any of these items, as it has not been reviewed by Concur for security.

  • Expense Report: POST

    • Expense Report Submit is supported. Expense Report Exceptions and Workflow actions are not supported at this time.

Expense Operations Not Yet Supported

  • Company Card Transaction: GET

  • Expense Entry Itemization: POST

  • Expense Delegator: GET

  • Expense Entry Form Field: GET

  • Expense Form: GET

  • Expense Group Configuration: GET

  • Integration Status: POST

  • Location: GET

Extract

Extracts are not available in the Mule Connector, as they are an alternative integration means. There are no plans to support this resource.

Image

The imaging v3.0 APIs are mostly supported in JSON mode. PUT and DELETE Operations are not supported at this time as during development the endpoints did not work as documented. Once the APIs are functional they may be supported.

Itinerary

Itineraries are only partially supported. POST Itinerary Cancellations do not return valid XML, and therefore cannot be parsed and thus are not supported. Other API endpoints are supported as documented.

Bookings

Bookings are only partially supported. POST Booking Cancellations returns HTTP 404, and therefore cannot be parsed and thus are not supported. Other API endpoints are supported as documented.

  • Itinerary: GET

    • All APIs are supported: Get List of Itineraries, Get Itinerary Details

  • Booking: POST

    • The bookings endpoints are not currently supported.

  • Itinerary: POST

    • POST operations are not supported for Itineraries at this time.

List Items

  • List: GET

    • All APIs are supported: Get List of Lists, Get List Details, Get List Items.

  • List: POST

    • List updates are managed in batches, with a batch type parameter determining if the list change will be Create, Update or Delete. Batch limits are not discussed or tested, but it is safe to assume that batches must be less than 1000 or will be ignored, as with other batch API endpoints.

Meeting

Meeting endpoints are only supported in Travel for Concur Professional/Premium. These APIs are not supported by the Anypoint Concur Connector.

Payment Batch File

GET List of Payment Batches is supported, with an optional status filter parameter. POST Payment Batch Close is also supported, requiring the appropriate BatchID to be supplied.

Purchase Order Web Service

Purchase Order endpoints are only supported in Invoice for Concur Professional/Premium. These APIs are not supported by the Mule Connector.

Quick Expenses

Quick Expense v3.0 APIs are supported, using JSON as the interchange format. All endpoints are supported: GET all quickexpenses, GET QuickExpense by ID, Create a new QuickExpense (POST), Update a QuickExpense by ID (PUT), and DELETE a QuickExpense by ID.

Travel Request

Travel Requests are only partially supported, as an integrator must partner with Concur as an appropriate organization type (for example, a Travel Agency). Without the ability to create a travel request, an ID cannot be fetched, so GET Travel Request Details is not supported, nor is POST Travel Request Workflow Action. GET List of Travel Requests is supported, however.

Travel Profile

Travel Profile APIs are fully supported.

Trip Approval

POST Trip Approval (the only API) is supported . This updates a Trip Approval as either approved or rejected.

User

  • GET Employee Form Field

    • Get List of Employee Form Fields is supported.

  • User: GET

    • Get User Information is fully supported.

  • User: POST

    • POST New or Updated users is fully supported. The batch can only support up to 500 users.

  • User Password: POST

    • Update user passwords is not supported at this time.

TripIt from Concur

TripIt from Concur has not been considered in building the Mule Connector for Concur.

Developer Preview APIs

There are some APIs which are considered "Developer Previews". Connector support for these has not been added at this time due to the likelihood of significant API changes.

Callouts

Callouts are not available in the Concur connector. They require extensive specific configuration and cannot be easily "genericised". Using the standard endpoint tools available in Mule, you can integrate callouts, but a connector cannot assist here.