From 45b415613a0d600560e8ca02f7a05e899530ee4c Mon Sep 17 00:00:00 2001 From: Anjali Selvaraj Date: Mon, 28 Apr 2025 13:58:40 -0700 Subject: [PATCH] ERS-33145 externalize events --- .../expense/v4.expense-events-new.md | 347 ++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 src/event-topics/expense/v4.expense-events-new.md diff --git a/src/event-topics/expense/v4.expense-events-new.md b/src/event-topics/expense/v4.expense-events-new.md new file mode 100644 index 0000000000..9cfaa7a663 --- /dev/null +++ b/src/event-topics/expense/v4.expense-events-new.md @@ -0,0 +1,347 @@ +--- +title: Concur Expense Event +layout: reference +--- + +# 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](/api-reference/ess/v4.event-subscription.html) page. + +## Limitations + +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 Created Event + +The `reportCreated` event is intended to be published when a new expense report has been created. + +### Report Updated Event + +The `reportUpdated` event is published when an expense report is updated. + +### Report Deleted Event + +The `reportDeleted` event is published when an expense report is deleted. + +### 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](https://www.concurtraining.com/customers/tech_pubs/Docs/_Current/SG_Exp/Exp_SG_Workflow_General.pdf) 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 values `A_NOTF` and `A_RESU`. +* Subscribers interested in the report sent back events should filter by the `stepCode` attribute in the payload with a value of `SENDBACK`. +* Subscribers interested in the report recalled events should filter by the `stepCode` attribute in the payload with a value of `RECALL`. +* 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 of `EXTVAL`. +* Subscribers interested in the paid report events should filter by the `currentPaymentStatus` attribute in the payload with a value of `P_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 + +### Report Created Event 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. | +| `route` | `String` | `String` | For internal use. This will be set to stable. | +| `topic` | `String` | `Enum` | **Required** Identifies the topic that the event belongs to `public.concur.expense.report`. | +| `eventType` | `String` | `String` | **Required** Event Type: `reportCreated` - Identifies the event type on the topic. | +| `timeStamp` | `timeStamp` | RFC 3339 | **Required** Current system time (UTC) when the event notification is issued. | +| `facts` | `Map` | [facts schema](#report-created-event-payload-facts-schema) | **Required** Key-value pairs providing the content of the event. | + +### Report Created Facts Schema + +| Name | Type | Format | Description | +|--------------------|-------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `companyId` | `UUID` | RFC 4122 | **Required** Unique identifier of the company the report belongs to. | +| `userId` | `UUID` | RFC 4122 | The unique identifier of the report creator unless a delegate or proxy is involved. In these instances, it will be the user for which the report is being created (i.e., the report owner).
This value can be NULL when a system initiates the change action instead of a user. This would include API calls with a Company JWT.
Use Identity v4 API to retrieve user details. | +| `actingUserId` | `UUID` | RFC 4122 | User unique identifier. If a delegate or expense proxy created the report on behalf of another user, then this will be populated with the identifier for that delegate or expense proxy user, else it will be NULL.
Use Identity v4 API to retrieve user details. | +| `reportId` | `String` | `Alphanumeric` | **Required** Unique identifier of the newly created expense report. Maximum characters: 20 | +| `reportType` | `String` | `Enum` | **Required** This value identifies the method used to create the report. Supported values:
Regular,
Reconciliation,
Statement,
AutoCreated | +| `lastModifiedDate` | `timeStamp` | RFC 3339 | **Required** Current system time (UTC) when the event notification is issued. | +| `href` | `string` | RFC 3986 | URI of the report resource that can be called via the Expense v4 API. | + +### Report Updated Event 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. | +| `route` | `String` | `String` | For internal use. This will be set to stable. | +| `topic` | `String` | `Enum` | **Required** Identifies the topic that the event belongs to `public.concur.expense.report`. | +| `eventType` | `String` | `String` | **Required** Event Type: `reportUpdated` - Identifies the event type on the topic. | +| `timeStamp` | `timeStamp` | RFC 3339 | **Required** Current system time (UTC) when the event notification is issued. | +| `facts` | `Map` | [facts schema](#report-updated-event-payload-facts-schema) | **Required** Key-value pairs providing the content of the event. | + +### Report Updated Facts Schema + +| Name | Type | Format | Description | +|--------------------|-------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `companyId` | `UUID` | RFC 4122 | **Required** Unique identifier of the company the report belongs to. | +| `userId` | `UUID` | RFC 4122 | The unique identifier of the report creator unless a delegate or proxy is involved. In these instances, it will be the user for which the report is being created (i.e., the report owner).
This value can be NULL when a system initiates the change action instead of a user. This would include API calls with a Company JWT.
Use Identity v4 API to retrieve user details. | +| `actingUserId` | `UUID` | RFC 4122 | User unique identifier. If a delegate or expense proxy created the report on behalf of another user, then this will be populated with the identifier for that delegate or expense proxy user, else it will be NULL.
Use Identity v4 API to retrieve user details. | +| `reportId` | `String` | `Alphanumeric` | **Required** Unique identifier of the newly created expense report. Maximum characters: 20 | +| `reportType` | `String` | `Enum` | **Required** This value identifies the method used to create the report. Supported values:
Regular,
Reconciliation,
Statement,
AutoCreated | +| `lastModifiedDate` | `timeStamp` | RFC 3339 | **Required** Current system time (UTC) when the event notification is issued. | +| `href` | `string` | RFC 3986 | URI of the report resource that can be called via the Expense v4 API. | + +### Report Deleted Event 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. | +| `route` | `String` | `String` | For internal use. This will be set to stable. | +| `topic` | `String` | `Enum` | **Required** Identifies the topic that the event belongs to `public.concur.expense.report`. | +| `eventType` | `String` | `String` | **Required** Event Type: `reportDeleted` - Identifies the event type on the topic. | +| `timeStamp` | `timeStamp` | RFC 3339 | **Required** Current system time (UTC) when the event notification is issued. | +| `facts` | `Map` | [facts schema](#report-deleted-event-payload-facts-schema) | **Required** Key-value pairs providing the content of the event. | + +### Report Deleted Facts Schema + +| Name | Type | Format | Description | +|--------------------|-------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `companyId` | `UUID` | RFC 4122 | **Required** Unique identifier of the company the report belongs to. | +| `userId` | `UUID` | RFC 4122 | The unique identifier of the report creator unless a delegate or proxy is involved. In these instances, it will be the user for which the report is being created (i.e., the report owner).
This value can be NULL when a system initiates the change action instead of a user. This would include API calls with a Company JWT.
Use Identity v4 API to retrieve user details. | +| `actingUserId` | `UUID` | RFC 4122 | User unique identifier. If a delegate or expense proxy created the report on behalf of another user, then this will be populated with the identifier for that delegate or expense proxy user, else it will be NULL.
Use Identity v4 API to retrieve user details. | +| `reportId` | `String` | `Alphanumeric` | **Required** Unique identifier of the newly created expense report. Maximum characters: 20 | +| `reportType` | `String` | `Enum` | **Required** This value identifies the method used to create the report. Supported values:
Regular,
Reconciliation,
Statement,
AutoCreated | +| `lastModifiedDate` | `timeStamp` | RFC 3339 | **Required** Current system time (UTC) when the event notification is issued. | + +### Report Status Changed Event 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. | +| `route` | `String` | `String` | For internal use. This will be set to stable. | +| `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. | +| `timeStamp` | `timeStamp` | RFC 3339 | **Required** Current system time (UTC) when the event notification is issued. | +| `facts` | `Map` | [facts schema](#status-changed-event-payload-facts-schema) | **Required** Key-value pairs providing the content of the event. | + +### Report Status Changed Facts Schema + +| Name | Type | Format | Description | +|--------------------------------|-------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `companyId` | `UUID` | RFC 4122 | **Required** Unique identifier of the company the report belongs to. | +| `userId` | `UUID` | RFC 4122 | The unique identifier of the focus SAP Concur user in the change action. In the case of a report submittal, then this will be the report owner. In the case of any other workflow action, then this will be the appropriate manager/approver/processor. It will NOT reflect a delegate or proxy user who might have executed the action on behalf of the focus user - see actingUserId.
This value can be NULL when a system initiates the change action instead of a user. This would include API calls with a Company JWT.
Use Identity v4 API to retrieve user details. | +| `actingUserId` | `UUID` | RFC 4122 | User unique identifier. If a delegate or expense proxy performed the action on behalf of another user, then this will be populated with the identifier for that delegate or expense proxy user, else it will be NULL.
Use Identity v4 API to retrieve user details. | +| `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) | +| `reportType` | `String` | `Enum` | **Required** This value identifies the method used to create the report. Supported values:
Regular,
Reconciliation,
Statement,
AutoCreated | +| `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 + +### Report Created + +```json +{ + "id": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "correlationId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "route": "stable", + "eventType": "reportCreated", + "topic": "public.concur.expense.report", + "timeStamp": "1970-01-01T00:00:00.000Z", + "facts": { + "reportType": "Regular", + "companyId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "reportId": "4E6593CB987D459C88FA", + "lastModifiedDate": "1970-01-01T00:00:00.000Z", + "actingUserId": null, + "href": "https://us2.api.concursolutions.com/expensereports/v4/users/bbd64e6f-d096-48e5-8dd8-b7b67de1a951/context/TRAVELER/reports/4E6593CB987D459C88FA", + "userId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951" + } +} +``` + +### Report Updated + +```json +{ + "id": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "correlationId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "route": "stable", + "eventType": "reportUpdated", + "topic": "concur.expense.report", + "timeStamp": "1970-01-01T00:00:00.000Z", + "facts": { + "reportType": "Regular", + "companyId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "reportId": "4E6593CB987D459C88FA", + "lastModifiedDate": "1970-01-01T00:00:00.000Z", + "href": "https://us2.api.concursolutions.com/expensereports/v4/users/bbd64e6f-d096-48e5-8dd8-b7b67de1a951/context/TRAVELER/reports/4E6593CB987D459C88FA", + "actingUserId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "userId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951" + } +} +``` + +### Report Deleted + +```json +{ + "id": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "correlationId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "route": "stable", + "eventType": "reportDeleted", + "topic": "concur.expense.report", + "timeStamp": "1970-01-01T00:00:00.000Z", + "facts": { + "reportType": "Regular", + "companyId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "reportId": "1F7597D8217649F7BA4F", + "lastModifiedDate": "1970-01-01T00:00:00.000Z", + "actingUserId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951", + "userId": "bbd64e6f-d096-48e5-8dd8-b7b67de1a951" + } +} + + +``` +### Report Status Changed + +```json +{ + "id": "0490b3fb-04ad-4919-b299-afb9fa75e07c", + "correlationId": "7e38939d-62f1-4bb4-9eef-5ea71fcbb1d8", + "route": "stable", + "eventType": "statusChanged", + "topic": "public.concur.expense.report", + "timeStamp": "2021-03-18T23:11:51.034Z", + "facts":{ + "currentApprovalStatus": "A_PEND", + "reportId": "CB899F7D9F73420A8D8B", + "stepCode": "MANAGER", + "lastModifiedDate": "2023-04-07T22:10:57.817Z", + "userId": "f2d07d5f-7a6f-44fa-98c7-c4b405bd6ca3", + "reportType": "Regular", + "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" + } +} +``` + +```json +{ + "id": "3eabdcbf-07df-4acd-99de-7f5aef0f673d", + "correlationId": "7e38939d-62f1-4bb4-9eef-5ea71fcbb1d8", + "route": "stable", + "eventType": "statusChanged", + "topic": "public.concur.expense.report", + "timeStamp": "2021-03-19T00:37:39.550Z", + "facts": { + "currentApprovalStatus": "A_PECO", + "reportId": "CB899F7D9F73420A8D8B", + "stepCode": "CO_STEP", + "lastModifiedDate": "2023-04-10T15:55:17.962Z", + "userId": "45afdc31-0593-4e95-ba75-b094e9326b6d", + "reportType": "Statement", + "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" + } +} +``` + +```json +{ + "id": "be3a6976-00e7-4b06-9c95-b4f2c3330ea6", + "correlationId": "7e38939d-62f1-4bb4-9eef-5ea71fcbb1d8", + "route": "stable", + "eventType": "statusChanged", + "topic": "public.concur.expense.report", + "timeStamp": "2021-03-19T01:11:57.169Z", + "facts": { + "currentApprovalStatus": "A_ACCO", + "reportId": "CB899F7D9F73420A8D8B", + "stepCode": "ACCTCLERK", + "lastModifiedDate": "2023-04-10T21:54:16.661Z", + "userId": "4cecc318-ba1e-4a7d-871e-7cba3cc8e433", + "reportType": "AutoCreated", + "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" + } +} +```