- SAP Managed Tags:
Did you know all those receipts and invoices attached to reports and payment requests can be stored locally or accessed on demand without needing to login to Concur? This blog post will introduce ways that SAP Concur provides our clients to manage their images outside of Concur.
I have been a Technical Consultant with SAP Concur for more than 10 years, working with clients of all sizes to implement Concur. Many of those clients are looking for a way to manage, internally, the documentation attached to expense reports and invoices.
An image is any supporting document that has been attached to an expense report or invoice. It could be a picture of a merchant receipt captured from the ExpenseIt feature in the Concur Mobile App, an attachment received via email and manually uploaded, or an invoice emailed to your Concur site via Invoice Capture.
Images for the Expense and Invoice modules are treated the same way. It doesn't matter what the image is attached to. If it is attached to a spend document in Concur, it can be retrieved.
There are a couple of ways to retrieve images. The method chosen will depend on your end goal.
Method 1 - Image Delivery Extract
This method requires an SFTP account on Concur's server. It is designed to retrieve all Concur images and store them locally. Adequate storage will be needed for this method. Both Invoice and Expense images are included in the same file. Retrieving images for only 1 product is not possible if there is data available to extract for both.
The Image Delivery Extract is a zip archive that is delivered via SFTP. Files are encrypted with your public PGP key so only the holder of the private half of that PGP key can decrypt the file and access the image data. Files are no more than 500mb. If the extracted data is more than 500 mb, multiple extract files will be created. Files have a file counter in the name. If there are 2 files created in 1 run, the file names would include '1 of 2' and '2 of 2'. The extract job is only run once a day during Concur's OverNight Processing schedule. It cannot be run on demand.
Once a report or invoice has been updated to a 'Sent for Payment' status, the attached images will be placed into the image extract. This status means that the report or invoice has been included in an accounting extract file or received a successful posting message from the Financial Integration Service API. Each image extract will contain all images for reports and invoices that have been updated to that status since the last time the image extract job was run. If you have requested to retrieve images that were attached after the document was extracted or posted, those images will also be included.
The zip archive will also contain an index file of all images in the archive. The employee ID, report ID, report key, and image ID are included in each record. If requested, the entry ID can also be included to identify the line item associated with the image.
Method 2 - Spend Docs v4 API
This method is designed to retrieve individual images and receipts as needed. It is not meant for bulk retrieval and long-term storage. Web Services needs to be purchased from your SAP Concur account rep in order to use this method.
The official documentation for this API can be found at https://developer.concur.com/api-reference/spend-documents/v4.spend-documents.html.
A simple call to retrieve an image looks like
/spend-documents/v4/receipts/representations?imageId={imageId}&companyId={companyId}&type=display
This will return the image as it is displayed in the UI.
/spend-documents/v4/receipts/representations?imageId={imageId}&companyId={companyId}&type=compliance will return the data needed to comply with regulatory bodies that require this documentation. Mexico CDFI is one example of a compliance document that can be retrieved if enabled in your Concur site.
You may notice 2 variables in the above calls. The CompanyID is unique to your Concur site and is part of the credentials needed to generate an access token. This will be the same value for each image you retrieve.
The ImageID is the unique identifier of the document you are trying to retrieve. This value can be found by using another API call. Depending on the API used and what type of record the image is attached to, multiple APIs may be needed to arrive at the ImageID.
There is another call available using the parameter receiptID. There are a couple of differences between receipts and images to call out since these are 2 similar parameters.
A receipt is all the data available regarding the charge. It can have XML, e-receipt, and other data. This is called with a receiptID. A receipt can also have an accompanying image. This is the visual form of a receipt that most of us recognize as a receipt. This is called with an imageID. A receipt doesn't have to have an image record and an image doesn't have to have a receipt record.
The receiptID is unique across all companies so it doesn't need a companyID when using a receipt. An imageID is not unique across all companies so it requires the companyID when it is used.
Here is an example of a way to drill down to the ImageID.
Scenario:
User login ID: testuser@test.com
ReportID: 1234567890
CompanyID: abcd-1234-b0796
Retrieve the User's ID
POST https://{{dataCenterURI}}/profile/identity/v4.1/Users/.search
{
"schemas": [ "urn:ietf:params:scim:api:messages:concur:2.0:SearchRequest" ],
"filter": "userName eq \"testuser@test.com\"",
"attributes": ["userName"]
}
Response
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 1,
"Resources": [
{
"id": "14c574d0-5363-4520-f274-b240568e729707",
"userName": "testuser@test.comt"
}
]
Retrieve expense report
https://{{dataCenterURI}}/expensereports/v4/users/14c574d0-5363-4520-f274-b240568e729707/context/TRAVELER/reports/1234567890/expenses
Response
[
{
…….
"expenseId": "14F156845765A7A9DE",
"receiptImageId": "B0443709D190EFE176",
…..
}
]
Retrieve the image from the above expense entry
https://{{dataCenterURI}}/spend-documents/v4/receipts/representations?imageId=B0443709D190EFE176&companyId=abcd-1234-b0796&type=display
Response
This method can be useful during an audit. Auditors may ask for receipts to support the reports or invoices they are reviewing. Instead of logging into Concur, looking for the specific report, opening each entry and downloading the attached images, an app could be created for the auditor to use on their own. They would just need to have some information about the owner of the report (loginID in the above example) and a way to identify the specific report (report ID in the above example).
Method 3 - Download from the User Interface
The last method is to search for the expense report via the Processor Queue and manually download the image directly from the UI. This works well for the occasional need to retrieve images.
I hope this has sparked some creative ideas about adhoc retrieval or storing of image documents. To learn more about the Image Delivery Extract or Spend Docs v4 API, please contact your SAP Concur Account Manager.
Have you implemented a solution you would like to share? An alternative method not described above? A use case that isn't met by these options you would like to share? Please leave a comment.
