Requirements

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.

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\($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

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

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

Click Login in Anypoint Exchange.

Search for the connector and click Install.

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

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

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

Select the Global Elements tab.

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

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

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

Consumer Key - the value of "Key" when registering the Partner application

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.

Click the popup and check for available updates.

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

Restart Studio when prompted.

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.

Retrieve a List of Lists

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

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

Drag an HTTP Listener into your flow from the palette.

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.

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.

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

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

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:

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

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

Create a Quick Expense

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

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

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.

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.

Add the Concur connector to the new flow, referencing a global element from the Connector Confiuration and set an Operation to perform and any other properties you require.

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

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

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

Check the console to see when the application starts.

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