Overview
In this article we will look at an example of how to use the process execution-related objects to view and rerun documents using the Boomi Enterprise Platform API. To use the Boomi Enterprise Platform API, the user role must have the "API access" privilege.
These APIs allow solution builders, customers, and partners to access and display details about process executions in custom portals or dashboards outside of the Boomi user interface or to automate monitoring functions such as rerunning failed documents.
To help understand the relationships and intended usage for these APIs, we will walk through a real world use case to find, inspect, and rerun errored documents. For those familiar with the process reporting page and viewing details for a given execution, these APIs follow the same concepts and workflow.
Approach
The high level steps are as follows.
- Call ExecutionRecord to get a list of process executions.
- Call ExecutionConnector for a given executionId to get a list of connector steps used in the process.
- Call GenericConnectorRecord for a given executionConnectorId to get a list of documents tracked on that step.
- Call ConnectorDocument (optional) for a given genericConnectorRecordId to download the actual document data for inspection.
- Call RerunDocument for one or more genericConnectorRecordIds to resubmit for processing.
Implementation
Step 1: ExecutionRecord
Use ExecutionRecord to filter and retrieve the list of recent executions. This returns an executionId for each record, which is used throughout the subsequent calls.
This object represents the top level results displayed in the process reporting, Executions page:
Usage considerations
- You can filter by date range, status (success/error), runtime, and specific process IDs.
- Depending on how much activity is in your account, this query can return many records so be sure you are prepared to handle multiple pages of results.
Real world example
Let's get all the failed executions on a particular basic runtime in the past week.
Request
Filter by executionTime, status, and atomId.
POST https://api.boomi.com/api/rest/v1/BOOMI_ACCOUNT_ID/ExecutionRecord/query <QueryConfig xmlns="http://api.platform.boomi.com/"> <QueryFilter> <expression operator="and" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="GroupingExpression"> <nestedExpression operator="BETWEEN" property="executionTime" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression"> <argument>2021-03-02T00:00:00Z</argument> <argument>2021-03-09T00:00:00Z</argument> </nestedExpression> <nestedExpression operator="EQUALS" property="status" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression"> <argument>ERROR</argument> </nestedExpression> <nestedExpression operator="EQUALS" property="atomId" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression"> <argument>89ecbd6d-e9e4-429b-9d3b-2cc39a6fc2e5</argument> </nestedExpression> </expression> </QueryFilter> </QueryConfig>
Response
Returns matching executions (results truncated in this example). Note the executionIds that will be used in subsequent calls.
<bns:QueryResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bns="http://api.platform.boomi.com/" numberOfResults="3">
<bns:result xsi:type="bns:ExecutionRecord">
<bns:executionId>execution-2fd25969-292e-4896-a04c-ca8171f2a606-2021.03.08</bns:executionId>
<bns:account>BOOMI_ACCOUNT_ID</bns:account>
<bns:executionTime>2021-03-08T21:31:16Z</bns:executionTime>
<bns:status>ERROR</bns:status>
<bns:executionType>exec_manual</bns:executionType>
<bns:processName>Update Salesforce Contacts</bns:processName>
<bns:processId>b658595e-a4d8-496d-b2f8-df0200ffcf17</bns:processId>
<bns:basic runtimeName>Adam QA</bns:basic runtimeName>
<bns:basic runtimeId>89ecbd6d-e9e4-429b-9d3b-2cc39a6fc2e5</bns:basic runtimeId>
<bns:inboundDocumentCount>20</bns:inboundDocumentCount>
<bns:inboundErrorDocumentCount>2</bns:inboundErrorDocumentCount>
<bns:outboundDocumentCount>19</bns:outboundDocumentCount>
<bns:executionDuration>1726</bns:executionDuration>
<bns:message>Process exception</bns:message>
<bns:inboundDocumentSize>8463</bns:inboundDocumentSize>
<bns:outboundDocumentSize>2646</bns:outboundDocumentSize>
</bns:result>
...
</bns:QueryResult>
Step 2: ExecutionConnector
Once you have an executionId, call ExecutionConnector to return a list of the Connector steps (including the Start step) as well as any Trading Partner and Return Documents steps used in the process.
This object represents what you see in the UI when you click an execution's timestamp:
Usage considerations
- ExecutionConnector records are retrieved for a single executionId.
- If you want to find connector steps with failures, filter by errorCount GREATER_THAN 0.
- To get the retryable documents from the Start step only, filter by isStartstep EQUALS true. This will return a single record.
Real world example
Let's get the Start step connector reference for the failed executionId retrieved in the previous step.
Request
Filter by executionId and isStartstep.
POST https://api.boomi.com/api/rest/v1/BOOMI_ACCOUNT_ID/ExecutionConnector/query <QueryConfig xmlns="http://api.platform.boomi.com/"> <QueryFilter> <expression operator="and" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="GroupingExpression"> <nestedExpression operator="EQUALS" property="executionId" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression"> <argument>execution-2fd25969-292e-4896-a04c-ca8171f2a606-2021.03.08</argument> </nestedExpression> <nestedExpression operator="EQUALS" property="isStartstep" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression"> <argument>true</argument> </nestedExpression> </expression> </QueryFilter> </QueryConfig>
Response
Returns a single record. Note the id that will be used in subsequent calls. From the errorCount, we can see there were two failed documents.
<bns:QueryResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bns="http://api.platform.boomi.com/" numberOfResults="1"> <bns:result xsi:type="bns:ExecutionConnector" id="RVhFQ19DT05OdHJ1ZTpHZXQ6ODhjZjk3OTYtYTMwMi00ZDhlLWJkNWUtZmJiZjc3NTliYzBjOm51bGw6ZXhlY3V0aW9uLTJmZDI1OTY5LTI5MmUtNDg5Ni1hMDRjLWNhODE3MWYyYTYwNi0yMDIxLjAzLjA4" executionId="execution-2fd25969-292e-4896-a04c-ca8171f2a606-2021.03.08" executionConnector="Contact Query" connectorType="salesforce" actionType="Get" errorCount="2" successCount="18" size="8463" isStartstep="true" recordType="connector"/> </bns:QueryResult>
Step 3: GenericConnectorRecord
Now with the executionConnectorId, call GenericConnectorRecord to retrieve the metadata information for the documents captured on that connector step. The information returned includes status information as well as connector tracked fields and any user defined tracked fields configured for the connector operation.
This object represents the list of connector documents you see in the UI when you click on a connector step within an execution:
Usage considerations
- IMPORTANT: Documents can be searched and retrieved only within a given execution. You cannot search for documents across all executions.
- You can search by connectorField or user defined trackedFields.
- If you only want to retrieve Start step/retryable documents, it is possible to skip the ExecutionConnector call and call the GenericConnectorRecord directly and filter by startstep EQUALS true.
Real world example
Let's get all the failed documents for the executionId and executionConnectorId (representing the Start step) retrieved in the previous step.
Request
Filter by executionId, executionConnectorId, and status.
POST https://api.boomi.com/api/rest/v1/BOOMI_ACCOUNT_ID/GenericConnectorRecord/query <QueryConfig xmlns="http://api.platform.boomi.com/"> <QueryFilter> <expression operator="and" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="GroupingExpression"> <nestedExpression operator="EQUALS" property="executionId" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression"> <argument>execution-2fd25969-292e-4896-a04c-ca8171f2a606-2021.03.08</argument> </nestedExpression> <nestedExpression operator="EQUALS" property="executionConnectorId" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression"> <argument>RVhFQ19DT05OdHJ1ZTpHZXQ6ODhjZjk3OTYtYTMwMi00ZDhlLWJkNWUtZmJiZjc3NTliYzBjOm51bGw6ZXhlY3V0aW9uLTJmZDI1OTY5LTI5MmUtNDg5Ni1hMDRjLWNhODE3MWYyYTYwNi0yMDIxLjAzLjA4</argument> </nestedExpression> <nestedExpression operator="EQUALS" property="status" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression"> <argument>ERROR</argument> </nestedExpression> </expression> </QueryFilter> </QueryConfig>
Response
Returns two errored documents from the Start step. Note the ids that will be used in subsequent calls.
<bns:QueryResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bns="http://api.platform.boomi.com/" numberOfResults="2"> <bns:result xsi:type="bns:GenericConnectorRecord" id="R0VOX0NPTk5fUkVDX2V4ZWN1dGlvbi0yZmQyNTk2OS0yOTJlLTQ4OTYtYTA0Yy1jYTgxNzFmMmE2MDYtMjAyMS4wMy4wODpjb25uZWN0b3ItOGI1NTM5MDMtNDA1MS00Yjg4LWE0YTAtODU3ZDI3YmY1MTg5" executionConnectorId="RVhFQ19DT05OdHJ1ZTpHZXQ6MTQ1OTY4YzgtMTY0NS00OTRlLTlhNzQtNDlhMTc2Yzg3OTRlOjg4Y2Y5Nzk2LWEzMDItNGQ4ZS1iZDVlLWZiYmY3NzU5YmMwYzpleGVjdXRpb24tMmZkMjU5NjktMjkyZS00ODk2LWEwNGMtY2E4MTcxZjJhNjA2LTIwMjEuMDMuMDg" executionId="execution-2fd25969-292e-4896-a04c-ca8171f2a606-2021.03.08" basic runtimeId="89ecbd6d-e9e4-429b-9d3b-2cc39a6fc2e5" dateProcessed="2021-03-08T21:31:17Z" actionType="Get" connectorType="salesforce" connectionName="My Salesforce Org" operationName="Contact Query" connectionId="145968c8-1645-494e-9a74-49a176c8794e" operationId="88cf9796-a302-4d8e-bd5e-fbbf7759bc0c" documentIndex="0" incrementalDocumentIndex="1" status="ERROR" startstep="true" retryable="true" size="330"> <bns:trackedFields> <bns:trackedField name="Record ID" value="m.freeholtz@demo.com"/> </bns:trackedFields> <bns:errorMessage>Process exception</bns:errorMessage> </bns:result> <bns:result xsi:type="bns:GenericConnectorRecord" id="R0VOX0NPTk5fUkVDX2V4ZWN1dGlvbi0yZmQyNTk2OS0yOTJlLTQ4OTYtYTA0Yy1jYTgxNzFmMmE2MDYtMjAyMS4wMy4wODpjb25uZWN0b3ItNWJhZjJhNmQtMWZlZi00YWZhLTgxODUtYTgzM2Y2N2M0YmQw" executionConnectorId="RVhFQ19DT05OdHJ1ZTpHZXQ6MTQ1OTY4YzgtMTY0NS00OTRlLTlhNzQtNDlhMTc2Yzg3OTRlOjg4Y2Y5Nzk2LWEzMDItNGQ4ZS1iZDVlLWZiYmY3NzU5YmMwYzpleGVjdXRpb24tMmZkMjU5NjktMjkyZS00ODk2LWEwNGMtY2E4MTcxZjJhNjA2LTIwMjEuMDMuMDg" executionId="execution-2fd25969-292e-4896-a04c-ca8171f2a606-2021.03.08" basic runtimeId="89ecbd6d-e9e4-429b-9d3b-2cc39a6fc2e5" dateProcessed="2021-03-08T21:31:17Z" actionType="Get" connectorType="salesforce" connectionName="My Salesforce Org" operationName="Contact Query" connectionId="145968c8-1645-494e-9a74-49a176c8794e" operationId="88cf9796-a302-4d8e-bd5e-fbbf7759bc0c" documentIndex="1" incrementalDocumentIndex="2" status="ERROR" startstep="true" retryable="true" size="324"> <bns:trackedFields> <bns:trackedField name="Record ID" value="cynthia.wellers@insurance.com"/> </bns:trackedFields> <bns:errorMessage>Process exception</bns:errorMessage> </bns:result> </bns:QueryResult>
Step 4: ConnectorDocument
Optionally, if you want to download the actual document data to inspect it, call ConnectorDocument for a given genericConnectorRecordId. This is a two-part asynchronous API because the platform needs to communicate with the basic runtime.
This object represents clicking the View Document action in the UI for a given connector document:
Usage considerations
- The basic runtime must be online.
- It may return a very large response based on the size of the documents you are processing.
- This object is intended for individual troubleshooting and custom portal presentation. It is not intended for bulk export/archiving of all documents.
- The API user must have view document data privileges. This action is captured in the Audit Log, same as via the UI.
Real world example
Let's view the data for one of the failed documents to confirm it looks good before resubmitting. We'll call it with the genericConnectorRecordId retrieved in the previous step.
Request 1
Submit the view-document request to basic runtime.
POST https://api.boomi.com/api/rest/v1/BOOMI_ACCOUNT_ID/ConnectorDocument
<ConnectorDocument genericConnectorRecordId="R0VOX0NPTk5fUkVDX2V4ZWN1dGlvbi0yZmQyNTk2OS0yOTJlLTQ4OTYtYTA0Yy1jYTgxNzFmMmE2MDYtMjAyMS4wMy4wODpjb25uZWN0b3ItOGI1NTM5MDMtNDA1MS00Yjg4LWE0YTAtODU3ZDI3YmY1MTg5" xmlns="http://api.platform.boomi.com/"/>
Response 1
Returns the URL to download the document.
<bns:ConnectorDocumentDownload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bns="http://api.platform.boomi.com/" url="https://platform.boomi.com/account/BOOMI_ACCOUNT_ID/api/download/ConnectorDocument-f7accb49-b17c-4213-83b1-2be679f66185" message="Beginning download." statusCode="202"/>
Request 2
Call the URL provided in the previous response.
The ConnectorDocumentDownload API returns an HTTP 202 status until the document is ready for download, then it returns an HTTP 200 status. You must repeatedly poll until it is ready. Once ready, the document may only be downloaded a single time with the given URL.
GET https://platform.boomi.com/account/BOOMI_ACCOUNT_ID/api/download/ConnectorDocument-f7accb49-b17c-4213-83b1-2be679f66185
Response 2
Returns the actual document data.
<Contact> <Id>003A0000013uqbEIAQ</Id> <AccountId>001A000000teuFnIAI</AccountId> <LastName>Freeholtz</LastName> <FirstName>Martin</FirstName> <MailingStreet /> <MailingCity /> <MailingState /> <MailingPostalCode /> <MobilePhone /> <Title /> <Email>m.freeholtz@demo.com</Email> </Contact>
Step 5: RerunDocument
Use RerunDocument to resubmit documents for reprocessing for a given execution. You can rerun all documents for an execution by status (success, failure, or all) or individual documents by specifying a list of genericConnectorRecordIds. This is a two-part API call that behaves the same way as the ExecutionRequest call for executing a brand new process.
This object represents the Re-run documents options in the UI, to either rerun “All” or only “Selected” documents:
Real world example
With the list of errored Start step documents, let's call RerunDocuments with those genericConnectorRecordIds to resubmit them for processing.
Request 1
Include the originalExecutionId and the list of genericConnectorRecordIds to rerun.
POST https://api.boomi.com/api/rest/v1/BOOMI_ACCOUNT_ID/RerunDocument <RerunDocument originalExecutionId="execution-2fd25969-292e-4896-a04c-ca8171f2a606-2021.03.08" xmlns="http://api.platform.boomi.com/"> <SelectedDocuments> <Document genericConnectorRecordId="R0VOX0NPTk5fUkVDX2V4ZWN1dGlvbi0yZmQyNTk2OS0yOTJlLTQ4OTYtYTA0Yy1jYTgxNzFmMmE2MDYtMjAyMS4wMy4wODpjb25uZWN0b3ItOGI1NTM5MDMtNDA1MS00Yjg4LWE0YTAtODU3ZDI3YmY1MTg5"/> <Document genericConnectorRecordId="R0VOX0NPTk5fUkVDX2V4ZWN1dGlvbi0yZmQyNTk2OS0yOTJlLTQ4OTYtYTA0Yy1jYTgxNzFmMmE2MDYtMjAyMS4wMy4wODpjb25uZWN0b3ItNWJhZjJhNmQtMWZlZi00YWZhLTgxODUtYTgzM2Y2N2M0YmQw"/> </SelectedDocuments> </RerunDocument>
Alternatively if you wanted to retry all errored documents, you could do so like this:
<RerunDocument originalExecutionId="execution-2fd25969-292e-4896-a04c-ca8171f2a606-2021.03.08" xmlns="http://api.platform.boomi.com/"> <AllDocuments documentStatus="ERROR"/> </RerunDocument>
Response 1
Returns requestId and recordUrl for new execution.
<bns:RerunDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bns="http://api.platform.boomi.com/" originalExecutionId="execution-2fd25969-292e-4896-a04c-ca8171f2a606-2021.03.08" requestId="executionrecord-47eaa722-47be-4f1f-bc3e-e87d4e77af68" recordUrl="https://platform.boomi.com/api/rest/v1/BOOMI_ACCOUNT_ID/ExecutionRecord/async/executionrecord-47eaa722-47be-4f1f-bc3e-e87d4e77af68"> <bns:SelectedDocuments> <bns:Document genericConnectorRecordId="R0VOX0NPTk5fUkVDX2V4ZWN1dGlvbi0yZmQyNTk2OS0yOTJlLTQ4OTYtYTA0Yy1jYTgxNzFmMmE2MDYtMjAyMS4wMy4wODpjb25uZWN0b3ItOGI1NTM5MDMtNDA1MS00Yjg4LWE0YTAtODU3ZDI3YmY1MTg5"/> <bns:Document genericConnectorRecordId="R0VOX0NPTk5fUkVDX2V4ZWN1dGlvbi0yZmQyNTk2OS0yOTJlLTQ4OTYtYTA0Yy1jYTgxNzFmMmE2MDYtMjAyMS4wMy4wODpjb25uZWN0b3ItNWJhZjJhNmQtMWZlZi00YWZhLTgxODUtYTgzM2Y2N2M0YmQw"/> </bns:SelectedDocuments> </bns:RerunDocument>
Request 2
Use requestId (or recordUrl) to check the status of the new ExecutionRecord.
GET https://api.boomi.com/api/rest/v1/BOOMI_ACCOUNT_ID/ExecutionRecord/async/executionrecord-47eaa722-47be-4f1f-bc3e-e87d4e77af68
Response 2
Returns the ExecutionRecord for the retry execution. Note the originalExecutionId value is now populated, indicating this was a rerun execution.
<bns:AsyncOperationResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bns="http://api.platform.boomi.com/" responseStatusCode="200"> <bns:result xsi:type="bns:ExecutionRecord"> <bns:executionId>execution-8fa9e551-653c-49c9-958c-4936b3f2aac8-2021.03.08</bns:executionId> <bns:originalExecutionId>execution-2fd25969-292e-4896-a04c-ca8171f2a606-2021.03.08</bns:originalExecutionId> <bns:account>BOOMI_ACCOUNT_ID</bns:account> <bns:executionTime>2021-03-08T22:03:37Z</bns:executionTime> <bns:status>ERROR</bns:status> <bns:executionType>retry_manual</bns:executionType> <bns:processName>Update Salesforce Contacts</bns:processName> <bns:processId>b658595e-a4d8-496d-b2f8-df0200ffcf17</bns:processId> <bns:basic runtimeName>Adam QA</bns:basic runtimeName> <bns:basic runtimeId>89ecbd6d-e9e4-429b-9d3b-2cc39a6fc2e5</bns:basic runtimeId> <bns:inboundDocumentCount>2</bns:inboundDocumentCount> <bns:inboundErrorDocumentCount>2</bns:inboundErrorDocumentCount> <bns:outboundDocumentCount>0</bns:outboundDocumentCount> <bns:executionDuration>369</bns:executionDuration> <bns:message>Process exception</bns:message> <bns:inboundDocumentSize>654</bns:inboundDocumentSize> <bns:outboundDocumentSize>0</bns:outboundDocumentSize> </bns:result> </bns:AsyncOperationResult>