Contact Us 1-800-596-4880
  1. Homepage

  2. SAP Concur Connector (0.3.9)

All Connectors

SAP Concur Connector

Concur is a SaaS provider from SAP for integrated travel and expense management solutions.

Anypoint™ Connector for Concur operates as a bi-directional gateway between instances of Concur and Mule. It is a closed-source connector that supports SOAP and REST calls to various Concur APIs.

MuleSoft maintains this connector under the Select support policy.

Exchange: Concur Connector

Before You Begin

This document assumes that you are familiar with Concur, Mule, Anypoint Connectors, and Anypoint Studio.

You also need:

Requirements

For hardware and software requirements, visit the Hardware and Software Requirements page.

Namespace and Schema

When designing your application in Studio, the act of dragging the connector from the palette onto the Anypoint Studio canvas should automatically populate the XML code with the connector namespace and schema location.

If you are manually coding the Mule application in Studio’s XML editor or other text editor, paste these into the header of your Configuration XML, inside the <mule> tag.

<mule xmlns:concur="http://www.mulesoft.org/schema/mule/concur"
  ...
  xsi:schemaLocation="http://www.mulesoft.org/schema/mule/concur http://www.mulesoft.org/schema/mule/concur/current/mule-concur.xsd">
  ...
  <flow name="yourFlow">
  ...
  </flow>
</mule>

Using the Connector in a Mavenized Mule App

If you are coding a Mavenized Mule application, this XML snippet must be included in your pom.xml file.

Inside the <version> tags, put the desired version number.

<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>mule-module-concur</artifactId>
  <version>x.y.z</version>
</dependency>

Replace x.y.z with the version that corresponds to the connector you are using.

To obtain the most up-to-date pom.xml file information, access the connector in Anypoint Exchange and click Dependency Snippets.

Compatibility

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

Concur API Availability

This is the breakdown of supported API operations as of version 3.1.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

Attendee Types

v3.0

  • Get List Of Attendee Types

  • Get Attendee Type By Id

  • Post Attendee Type

  • Update Attendee Type

  • Delete Attendee Type

Digital Tax Invoices

v3.0

  • Retrieve Tax Invoices

  • Get Digital Tax Invoice By Id

  • Update Digital Tax Invoice by Id

Entry Attendee Associations

v3.0

  • Get Entry Attendee Associations

  • Get Entry Attendee Association By Id

  • Post Entry Attendee Association

  • Update Entry Attendee Association

  • Delete Entry Attendee Association

Expense Allocations

v3.0

  • Retrieve Allocations

  • Retrieve Single Allocation By Id

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

Expense Itemizations

v3.0

  • Get Expense Itemizations

  • Get Expense Itemization By Id

  • Post Expense Itemization

  • Update Expense Itemization

  • Delete Expense Itemization

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

Expense Delegators

v1.1

  • Get Expense Delegators

Expense Form

v1.1

  • Get Form Data

  • Get Form Fields

  • Get Form Types

Expense Reports

v1.1

  • Post Report Exception

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

  • Update Users Password

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

    • Fully supported.

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 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

    • Fully 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 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 Workflow actions are not supported at this time.

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

    • Updates passwords for up to 500 users.

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 "genericized". Using the standard endpoint tools available in Mule, you will be able to integrate callouts, but a connector cannot assist here.

To Install this Connector

  1. In Anypoint Studio, click the Exchange icon in the Studio taskbar.

  2. Click Login in Anypoint Exchange.

  3. Search for the connector and click Install.

  4. Follow the prompts to install the connector.

When Studio has an update, a message displays in the lower right corner, which you can click to install the update.

Configuring

  1. Start Anypoint Studio and create a new Mule project: Navigate to File > New > Mule Project.

  2. Type a project name and click Next. Accept default values on the next screen of the wizard and click Finish.

  3. In the Package Manager that appears at left by default in Studio, double-click your application’s project name to open it, and click the application’s XML file in src/main/app/yourMuleAppProjectName.xml.

  4. Select the Global Elements tab.

  5. Click the Create button, search for Concur and add a Concur connector configuration.

  6. Set the Concur Connector parameters in the global element for easy reference by your application later:

    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

Upgrading from an Older Version

If you’re currently using an older version of the connector, a small popup appears in the bottom right corner of Anypoint Studio with an "Updates Available" message.

  1. Click the popup and check for available updates.

  2. Click the Connector version checkbox and click Next and follow the instructions provided by the user interface.

  3. Restart Studio when prompted.

  4. After restarting, when creating a flow and using the Object Store Connector, if you have several versions of the connector installed, you may be asked which version you would like to use. Choose the version you would like to use.

We recommend that you keep Studio up to date with its latest version.

Using the 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.

Example Use Case

This user manual presents two of many use cases you might have for the Concur connector in your organization: getting a "list of lists" and retrieving "quickexpenses". You may jump ahead and paste the code for the flows 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.

concur connector flow examples

Retrieve a List of Lists

After creating a new project and a Concur global element, execute the following steps:

  1. Add a new Flow element by dragging it from the palette and give a name to the flow, such as getlists.

  2. Drag an HTTP Listener into your flow from the palette.

  3. Double-click the HTTP Listener and click the green plus sign next to the Connector Configuration dropdown and set the Host to localhost, and the Port to 8081.

  4. 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.

  5. Add a Concur connector to the new flow and select the Get list of lists operation, after selecting the Connector Configuration you desire.

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

  7. For reference you may check the particular "getlists" flow within the example XML code further down.

To execute the flow and check the outcome, perform the following steps:

  1. Right-click the project in the Package Explorer, and click 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

    {"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.

Create a Quick Expense

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

  2. Add an HTTP Listener 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 localhost as the Host and 8081 for the Port.

  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, referencing a global element from the Connector Configuration and set an Operation to perform and any other properties you require.

  6. Finally, add an Object to JSON transformer link in the previous example.

To execute the flow and check the outcome, perform the following steps:

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

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

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

  4. You should receive a JSON response like this:

    {"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. Click the stop button to halt the server running the application.

Example Use Case Code

The final XML for the two flows should look like this:

<?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>

Demos

You can download a fully functional demo application using the Concur connector.

See Also

Back to top
View on GitHub