- SAP Managed Tags:
I am a Technical Consultant at SAP Concur and I have previously worked as an Implementation Project Manager / Functional Consultant for Concur Expense and Concur Invoice. I have worked with customers both large and small, and one challenge that everyone must solve for is how to retrieve the data required for financial posting into the ERP / accounting software.
The “standard” SAP Concur offering for this in the past was via accounting extracts—flat files that are delivered to a Concur-hosted SFTP site or that are manually downloaded via the UI. Today we will explore utilizing the Extracts v1 APIs to run extract jobs and retrieve the resulting data on-demand.
If you are new to Concur and are still in the process of designing / building an integration, I would strongly encourage you to check out this SAP blog post about the Financial Integration Service APIs. FIS allows for error handling on posting failures and allows for posting feedback back to Concur and is overall a more robust solution. Existing customers can also utilize FIS, but it may require additional configuration changes and cutover work.
Prerequisites
This post will not discuss authentication with Concur Expense. Please see this post for an introduction to authentication and web service application building within Concur Expense. You will need an application with the following scope:
- EXTRCT
Works with these SAP Concur solutions:
- Expense – Standard
- Expense – Professional
- Invoice – Standard
- Invoice - Professional
Introduction
Retrieving extracts consists of the following steps:
- Get a list of the extract definitions available in the site
- Run the extract definition you need
- Retrieve the extract data
The complete documentation can be found on the developer portal. Here is a link to a Postman collection to help get you started. This collection assumes you’re using the environment variables referenced in the Authentication blog post mentioned above.
Get Extract Definitions
The first step is to get a list of all the available extracts in your site. To do this, run a GET request to /api/expense/extract/v1.0 (see 01. Get Extract Definitions in the Postman collection). The response will look something like this:
Figure 1 Response from GET extract request
Review the <name> tags for the extract definition you’re interested in. My example has the default extracts in a Professional site for Invoice and Expense, respectively. The naming conventions are a bit different for a Standard site but should match up with your batch definitions. These names could also be different if you have a custom extract built by the Extract Services team. Consult with your Concur Administrator if you’re not sure which is the correct job.
I’ll take a moment to add a little side note here. Most Concur APIs will return data in XML by default. If you prefer to work with JSON, you can modify the request header Accept key to “application/json”.
Take note of the job-link—let’s use the standard Expense extract as an example, so that’s
https://us2.concursolutions.com/api/expense/extract/v1.0/gWlCLesc5QB5mVUFPMUMka2OPz9wvtXO0Jg/job
In my Postman collection, I’ve parameterized the calls to make them easier to read and understand, so I’ll take the job definition ID (“gWlCLesc5QB5mVUFPMUMka2OPz9wvtXO0Jg” in the above example) and enter this as the value for the collection variable “definitionID”. In your app, it probably makes more sense to copy and store the entire job-link value instead.
Run Extract
Once you’ve identified the extract you’re interested in, it’s time to run the extract. To do this, run a POST request to the job-link value from the previous step (see 02. Run Specific Extract in the Postman collection). The results will look like this:
Figure 2 Response from POST extract request
The value after the /job/ in the “id” tag (gWt$s1mrU4M0Xe7IaMEpawJqQG70AOOhqmig) in the above screenshot) is a unique job ID—we’ll take this and enter it as the value for the collection variable “jobID”. Again, I have parameterized the request to make it easier to read, but in your program you can just copy the entire status-link value. To check the status of the job, run a GET request using the “status-link” value (see 03. Get Job Status in the Postman collection). If you have the header set to return JSON, then a status of “2” indicates the job has completed successfully.
Figure 3 JSON response of job status
If you’re getting XML, then the status will be “Completed”.
Figure 4 XML response of job status
| Status | |
| JSON | XML |
| 0 | Queued |
| 1 | Running |
| 2 | Completed |
| 3 | Failed |
Typically the job should complete within a few minutes, although it can take longer if there are a large number of reports to extract. The best practice is to loop the job status request every 30 seconds until the status updates to 2 / Completed. It is also recommended to run a given extract no more than once per hour.
A status of 3 / Failed indicates an issue with the extract job running, and isn't related to the API call specifically. If you receieve this error, have an Authorized Support Contact (ASC) open a ticket with Concur Support for more details.
Get Extract File
Once the status is updated, it’s time to grab our extract by running a GET request using the “file-link” value (see 04. Get Extract File in the Postman collection). If your extract only has a single output file, then the results of the request will be the text of the extract directly.
Figure 5 Extract text as GET extract file response
If your extract has multiple output files (having the standard extract + attendee details is common), then the request will return a .zip with all of the files. In Postman, it will look like this:
Figure 6 ZIP as GET extract file response
To save the .zip, use the Send and Download option from the Send dropdown:
Figure 7 Send and Download option in Postman
Conclusion
The Extract APIs give you more flexibility and control over when extracts are run and how quickly you can access the data versus the typical Overnight Job schedule / file delivered to SFTP. Using the information in this post and the accompanying Postman collection, you should be on your way to a more efficient financial posting experience.
Share and Connect
What do you think? Do you have anything to add? Leave a comment below.
Did you find it useful? Give us a like and share on social media.
Want to know more about SAP Concur? Please follow here.
Want to ask questions about SAP Concur and its offerings? Ask here.
Thank you!
