Concur Expense Event
Overview
This page will host the documentation for all the Concur Expense related events that are publicly available on the public.concur.expense.report
topic in the Event Subscription Service (ESS). Subscribers will be able to subscribe to these events by following the steps described on the Event Subscription Service v4 page.
Limitations
This event subscription is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the subscription.
Scope Usage
Name | Description |
---|---|
expense.report.read |
Get information about expense reports. |
expense.report.readwrite |
Read and write expense report headers. |
Events
This section lists all the publicly available events.
Report Status Changed Event
The statusChanged
event is intended to publish a message whenever the status of an expense report changes as it traverses the approval workflow during its life cycle. Subscribers of the event are able to leverage the data in the message to perform synchronous or asynchronous actions depending on their business processes. For example, this could trigger an application to make API calls to Concur Expense or start of a process in a third party application.
The statusChanged
event will always be published for the following status changes without any additional configuration:
- Whenever a report is submitted.
- Whenever a report is sent back to the employee by an approver/processor.
- Whenever a report is recalled by the employee.
- Whenever a report stops in the legacy external validation step that is configured using the application connector.
- Whenever a report is paid.
In addition to the above, any workflow step configured for notifications by the administrator will also be published. Please refer to the Procedure: Creating External Validations and Workflow Event Notifications section of the Workflow General - Setup Guide for more information on how the events can be configured and optimized.
Filtering of events by subscribers:
- Subscribers only interested in the report submitted event should filter by
previousApprovalStatus
attribute in the payload and should specifically filter for valuesA_NOTF
andA_RESU
. - Subscribers interested in the report sent back events should filter by the
stepCode
attribute in the payload with a value ofSENDBACK
. - Subscribers interested in the report recalled events should filter by the
stepCode
attribute in the payload with a value ofRECALL
. - Subscribers interested in the reports that are pending processing in the legacy external validation step events should filter by the
stepCode
attribute in the payload with a value ofEXTVAL
. - Subscribers interested in the paid report events should filter by the
currentPaymentStatus
attribute in the payload with a value ofP_PAID
. - Subscribers interested in all other events can filter by the
stepCode
attribute with the values entered by the administrator in the workflows Admin UI screens.
Schema
statusChanged Event Payload Schema
Name | Type | Format | Description |
---|---|---|---|
id |
UUID |
RFC 4122 | Required Randomly generated unique identifier of this event. |
correlationId |
UUID |
RFC 4122 | Required Unique identifier used for logging/traceability. |
topic |
String |
Enum |
Required Identifies the topic that the event belongs to public.concur.expense.report . |
eventType |
String |
String |
Required Event Type: statusChanged - Identifies the event type on the topic. |
subtopic |
String |
Alphanumeric |
Required Unique identifier of the expense report whose status has changed. Maximum characters: 20, which is also populated as reportId . |
timeStamp |
timeStamp |
RFC 3339 | Required Current system time (UTC) when the event notification is issued. |
Facts |
Map |
Facts Schema | Required Key-value pairs providing the content of the event. |
transactionTimestamp |
String |
dateTime |
A key linking to a definition for the format. |
arrayOfThings |
Array |
Schema Two |
A key linking to another schema for the format. |
Status Changed Facts Schema
Name | Type | Format | Description |
---|---|---|---|
companyId |
UUID |
RFC 4122 | Required Company unique identifier from profile service. |
userId |
UUID |
RFC 4122 | Unique identifier for the User acting on the report resource. This is the user assigned to take action, and does not reflect the delegate who might have executed the action. This value can be NULL when a system instead of a user acts on the report. |
actingUserId |
UUID |
RFC 4122 | User unique identifier. If a delegate or expense proxy performed the action on behalf of the user then this will be populated with the user unique identifier for that delegate or expense proxy user, else it will be NULL. |
reportId |
String |
Alphanumeric |
Required Unique identifier of the expense report whose status has changed. Maximum characters: 20 |
previousApprovalStatus |
String |
Enum |
Required Unique identifier of the previous approval status of the expense report whose status has changed. Supported values: Not Submitted - A_NOTF , Sent Back to Employee - A_RESU , Recalled by Employee - A_RESU , Submitted & Pending Approval - A_PEND , Approved - A_APPR , Pending External Validation - A_EXTV , Pending Budget Approval - A_PBDG , Pending Cost Object Approval - A_PECO , Approved & In Accounting Review - A_ACCO |
currentApprovalStatus |
String |
Enum |
Required Unique identifier of the current approval status of the expense report whose status has changed. Supported values: Sent Back to Employee - A_RESU , Recalled by Employee: A_RESU , Submitted & Pending Approval: A_PEND , Approved: A_APPR , Pending External Validation: A_EXTV , Pending Budget Approval: A_PBDG , Pending Cost Object Approval: A_PECO , Approved & In Accounting Review: A_ACCO |
previousPaymentStatus |
String |
Enum |
Required Unique identifier of the previous payment status of the expense report whose status has changed. Supported values: Not Paid - P_NOTP , Processing Payment - P_PROC , Payment Confirmed - P_PAYC (may depend on configuration) |
currentPaymentStatus |
String |
Enum |
Required Unique identifier of the current payment status of the expense report whose status has changed. Supported values: Not Paid - P_NOTP , Processing Payment - P_PROC , Paid - P_PAID , Payment Confirmed - P_PAYC (may depend on configuration) |
stepCode |
String |
Enum |
Code provided by the admin that the client can use to differentiate between the steps. Report Submit - If the target step (the next workflow step that the report stops at) is not configured for notifications, then step code will be NULL . Report Send Back - SENDBACK Report Recall - RECALL Legacy External validation post submit - EXTVAL Legacy External validation pre-extract - EXTVAL Report Paid - If the target step (the next workflow step that the report stops at) is not configured for notifications, then step code will be PAIDREPORT . All other cases code step code as configured by admin in workflow configuration will be populated. |
href |
string |
RFC 3986 | URI of the report resource that can be called via the Expense v4 API. |
lastModifiedDate |
timeStamp |
RFC 3339 | Required Current system time (UTC) when the event notification is issued. |
processId |
String |
- | Required Unique identifier of the workflow process that this workflow is an instance of. |
startingStep |
Object |
- | Required Object containing the information of the step(s) the expense report is entering into. |
startingStep.roleCode |
String |
String |
Required Approver’s role code for the step which the expense report is entering into. |
startingStep.stepInstances |
Array |
- | Required List of step instances which the expense report is entering into. |
stepInstances.id |
String |
- | Required Unique identifier of the workflow process step instance which report is entering into. |
stepInstances.assignedUserId |
UUID |
RFC 4122 | Required Unique identifier of the User assigned to approve the report. |
Sample Events
{
"id": "0490b3fb-04ad-4919-b299-afb9fa75e07c",
"correlationId": "7e38939d-62f1-4bb4-9eef-5ea71fcbb1d8",
"eventType": "statusChanged",
"topic": "public.concur.expense.report",
"timeStamp": "2021-03-18T23:11:51.034Z",
"subtopic": "CB899F7D9F73420A8D8B",
"facts":{
"currentApprovalStatus": "A_PEND",
"reportId": "CB899F7D9F73420A8D8B",
"stepCode": "MANAGER",
"lastModifiedDate": "2023-04-07T22:10:57.817Z",
"userId": "f2d07d5f-7a6f-44fa-98c7-c4b405bd6ca3",
"previousPaymentStatus": "P_NOTP",
"companyId": "12fc85ee-6f43-4d85-ba0d-94e844849dc1",
"processId": "0211A2F15CD6354C8552FB9D7D83B331",
"currentPaymentStatus": "P_NOTP",
"startingStep": {
"roleCode": "MANAGER",
"stepInstances": [
{
"id": "CE70C1563F9B63448B6EF338077622CE",
"assignedUserId": "45afdc31-0593-4e95-ba75-b094e9326b6d"
}
]
},
"previousApprovalStatus": "A_RESU",
"actingUserId": null,
"href": "https://us.api.concursolutions.com/expensereports/v4/users/f2d07d5f-7a6f-44fa-98c7-c4b405bd6ca3/context/TRAVELER/reports/CB899F7D9F73420A8D8B",
}
}
{
"id": "3eabdcbf-07df-4acd-99de-7f5aef0f673d",
"correlationId": "7e38939d-62f1-4bb4-9eef-5ea71fcbb1d8",
"eventType": "statusChanged",
"topic": "public.concur.expense.report",
"timeStamp": "2021-03-19T00:37:39.550Z",
"subtopic": "CB899F7D9F73420A8D8B",
"facts": {
"currentApprovalStatus": "A_PECO",
"reportId": "CB899F7D9F73420A8D8B",
"stepCode": "CO_STEP",
"lastModifiedDate": "2023-04-10T15:55:17.962Z",
"userId": "45afdc31-0593-4e95-ba75-b094e9326b6d",
"previousPaymentStatus": "P_NOTP",
"companyId": "12fc85ee-6f43-4d85-ba0d-94e844849dc1",
"processId": "0211A2F15CD6354C8552FB9D7D83B331",
"currentPaymentStatus": "P_NOTP",
"startingStep": {
"roleCode": "CO_APPROVER",
"stepInstances": [
{
"id": "6D22160A844E4E4EBF8D0B4CD1CF4E5F",
"assignedUserId": "42d248f3-cc43-464b-8685-09e584835f25"
},
{
"id": "3DE6845BA15ACC41A7DE3F90D94291AD",
"assignedUserId": "aa024d31-95eb-4270-b9f8-cb6b5f558a7c"
}
]
},
"previousApprovalStatus": "A_PEND",
"actingUserId": null,
"href": "https://us.api.concursolutions.com/expensereports/v4/users/f2d07d5f-7a6f-44fa-98c7-c4b405bd6ca3/context/TRAVELER/reports/CB899F7D9F73420A8D8B"
}
}
{
"id": "be3a6976-00e7-4b06-9c95-b4f2c3330ea6",
"correlationId": "7e38939d-62f1-4bb4-9eef-5ea71fcbb1d8",
"eventType": "statusChanged",
"topic": "public.concur.expense.report",
"timeStamp": "2021-03-19T01:11:57.169Z",
"subtopic": "CB899F7D9F73420A8D8B",
"facts": {
"currentApprovalStatus": "A_ACCO",
"reportId": "CB899F7D9F73420A8D8B",
"stepCode": "ACCTCLERK",
"lastModifiedDate": "2023-04-10T21:54:16.661Z",
"userId": "4cecc318-ba1e-4a7d-871e-7cba3cc8e433",
"previousPaymentStatus": "P_NOTP",
"companyId": "12fc85ee-6f43-4d85-ba0d-94e844849dc1",
"processId": "0211A2F15CD6354C8552FB9D7D83B331",
"currentPaymentStatus": "P_NOTP",
"startingStep": {
"roleCode": "ACCT_CLERK",
"stepInstances": [
{
"id": "C855E3CC889C0C4EA011A1A7F0984135",
"assignedUserId": null
}
]
},
"previousApprovalStatus": "A_PEND",
"actingUserId": null,
"href": "https://us.api.concursolutions.com/expensereports/v4/users/f2d07d5f-7a6f-44fa-98c7-c4b405bd6ca3/context/TRAVELER/reports/CB899F7D9F73420A8D8B"
}
}