Boomi Data Hub Repository API Reference (1.0.0) - Batch
Download OpenAPI Specification: Download
For more information about Postman collections, forking, and making your first API call, refer to the Working with Boomi APIs on Postman page.
Process large volumes of data efficiently. Submit, monitor, and manage bulk updates that create or modify golden records. Use this API for high-volume data loads or scheduled synchronization jobs.
Update Golden Records
Updates a batch of XML-formatted entities from a contributing source to update a specified universe (domain) under an authenticated account.
Additional Information: Note: You can implement requests for this operation in processes using the Boomi Data Hub connector's update golden records operation.
Security Requirements: You must have one of the following MDM privileges:
Without Advanced Security:
- MDM - Batch Admin
Authorizations:
path Parameters
| universeId | any Example: 851a6a64-6a88-4916-a5b7-d6a974d54318 Universe ID. Listed in the Repositories UI URL. |
query Parameters
| repositoryId | any Repository ID. Case sensitive. Required with JWT authentication only. You can obtain the repository ID from the URL after navigating to the repository in the user interface. |
| async | any Example: async=true Process asynchronously. When true, returns immediately with batch URL. When false, waits for processing to complete. |
| returnEntities | any Example: returnEntities=false Include entity details in the response when async=false |
Request Body schema: application/xmlrequired
In the request body wrap the entities in a <batch> element. Specify the contributing source by its ID in the <batch> element's src attribute. The entities must conform to the deployed model for the universe. In each entity, wrap the source record ID in an <id> element.
Entity operation (op) and example:
The first entity in the example is a normal update — creating a new golden record or a potential update to a linked golden record. If you omit the op attribute, its presence is implied with the value of "UPSERT".
In the second entity, the op attribute value CREATE indicates a request to force the creation of a golden record. In this case, it skips matching. The created golden record can potentially duplicate if the entity is successfully incorporated. If an incorporation error occurs because a source entity with the ID specified in the entity has a linked golden record and you configure the contributing source to disallow multiple links from individual golden records to source entities, it quarantines the entity.
In the third entity the presence of the op attribute value DELETE on the entity's root <contact> element indicates a request for the end-dating of the linked golden record.
Note: Dedicated repository API operations, End-date Single Golden Record and End-date Multiple Golden Records, exist for end-dating a golden record(s).
In the fourth entity, a routine update, the op attribute value UPSERT in collection items indicates a request for an update to collection items with matching keys in a linked golden record. Add the specified items to the collection if there are no such items. Either none or all items in an individual collection in an entity must have an operation specified. The supported operation types are UPSERT and DELETE. In addition, you can select operations only for collections for which you enable item identification by key field value. For examples on how collections are processed for match by key and match by occurrence, refer to Collection item matching examples. For more information on match by key collections, refer to Collection item operations.
grid attribute: The grid attribute is optional in an entity. The grid attribute value is expected to be a golden record ID. Suppose a golden record with a specific ID exists in the domain, but there is no link from the golden record to the source. In that case, it establishes a link from the golden record to the source entity specified in the entity's <id> element. This technique is most applicable to a non-contributing source, such as a data warehouse. However, the alternative of designating the source upon attachment as non-contributing is preferred because links to selected non-contributing sources establish automatically and would not need a Source to Boomi Data Hub integration. Suppose a golden record with the specified ID exists in the domain. In that case, links go from the golden record to the source. You can configure the contributing source to disallow multiple links from individual golden records to source entities. The updated golden record links to the source entity specified in the entity's <id> element. References in other golden records to the entity are updated accordingly.
XML request data
Responses
Request samples
- Payload
<batch src="SF"> <!-- first entity --> <contact> <id>1</id> <name>bob</name> <city>berwyn</city> <phones> <phone> <number>311 555-1234</number> <type>home</type> </phone> <phone> <number>311 555-4321</number> <type>mobile</type> </phone> </phones> <email>bob@gmail.com</email> </contact> <!-- second entity --> <contact op="CREATE"> <id>2</id> <name>sam</name> <city>pottstown</city> <phones> <phone> <number>311 555-8765</number> <type>mobile</type> </phone> </phones> <email>sam@gmail.com</email> </contact> <!-- third entity --> <contact op="DELETE"> <id>3</id> <name>eric</name> <city>lansdale</city> <phones> <phone> <number>311 555-9012</number> <type>home</type> </phone> <phone> <number>311 555-2109</number> <type>mobile</type> </phone> </phones> <email>eric@gmail.com</email> </contact> <!-- fourth entity --> <contact> <id>4</id> <name>bill</name> <city>malvern</city> <phones> <phone op="UPSERT"> <number>311 555-3456</number> <type>home</type> </phone> <phone op="UPSERT"> <number>311 555-6543</number> <type>mobile</type> </phone> </phones> <email>bill@gmail.com</email> </contact> </batch>
Response samples
- 202
- 400
- 401
- 403
- 404
- 500
- 503
https://c01-usa-east.hub.boomi.com/mdm/universes/851a6a64-6a88-4916-a5b7-d6a974d54318/records/updates/42
Update Golden Records (Stage)
Stages a batch of XML-formatted entities from a contributing source to update a specified universe (domain) under an authenticated account.
Additional Information: Note: You can implement requests for this operation in processes using the Boomi Data Hub connector's update golden records operation.
Security Requirements: You must have one of the following MDM privileges:
Without Advanced Security:
- MDM - Batch Admin
Authorizations:
path Parameters
| universeId | any Example: 851a6a64-6a88-4916-a5b7-d6a974d54318 Universe ID. Listed in the Repositories UI URL. |
| stagingCode | any Example: SFStaging Staging area code |
query Parameters
| repositoryId | any Repository ID. Case sensitive. Required with JWT authentication only. You can obtain the repository ID from the URL after navigating to the repository in the user interface. |
| async | any Example: async=true Process asynchronously. When true, returns immediately with batch URL. When false, waits for processing to complete. |
| returnEntities | any Example: returnEntities=false Include entity details in the response when async=false |
Request Body schema: application/xmlrequired
In the request body wrap the entities in a <batch> element. Specify the contributing source by its ID in the <batch> element's src attribute. The entities must conform to the deployed model for the universe. In each entity, wrap the source record ID in an <id> element.
Entity operation (op) and example:
The first entity in the example is a normal update — creating a new golden record or a potential update to a linked golden record. If you omit the op attribute, its presence is implied with the value of "UPSERT".
In the second entity, the op attribute value CREATE indicates a request to force the creation of a golden record. In this case, it skips matching. The created golden record can potentially duplicate if the entity is successfully incorporated. If an incorporation error occurs because a source entity with the ID specified in the entity has a linked golden record and you configure the contributing source to disallow multiple links from individual golden records to source entities, it quarantines the entity.
In the third entity the presence of the op attribute value DELETE on the entity's root <contact> element indicates a request for the end-dating of the linked golden record.
Note: Dedicated repository API operations, End-date Single Golden Record and End-date Multiple Golden Records, exist for end-dating a golden record(s).
In the fourth entity, a routine update, the op attribute value UPSERT in collection items indicates a request for an update to collection items with matching keys in a linked golden record. Add the specified items to the collection if there are no such items. Either none or all items in an individual collection in an entity must have an operation specified. The supported operation types are UPSERT and DELETE. In addition, you can select operations only for collections for which you enable item identification by key field value. For examples on how collections are processed for match by key and match by occurrence, refer to Collection item matching examples. For more information on match by key collections, refer to Collection item operations.
grid attribute: The grid attribute is optional in an entity. The grid attribute value is expected to be a golden record ID. Suppose a golden record with a specific ID exists in the domain, but there is no link from the golden record to the source. In that case, it establishes a link from the golden record to the source entity specified in the entity's <id> element. This technique is most applicable to a non-contributing source, such as a data warehouse. However, the alternative of designating the source upon attachment as non-contributing is preferred because links to selected non-contributing sources establish automatically and would not need a Source to Boomi Data Hub integration. Suppose a golden record with the specified ID exists in the domain. In that case, links go from the golden record to the source. You can configure the contributing source to disallow multiple links from individual golden records to source entities. The updated golden record links to the source entity specified in the entity's <id> element. References in other golden records to the entity are updated accordingly.
XML request data
Responses
Request samples
- Payload
<batch src="SF"> <!-- first entity --> <contact> <id>1</id> <name>bob</name> <city>berwyn</city> <phones> <phone> <number>311 555-1234</number> <type>home</type> </phone> <phone> <number>311 555-4321</number> <type>mobile</type> </phone> </phones> <email>bob@gmail.com</email> </contact> <!-- second entity --> <contact op="CREATE"> <id>2</id> <name>sam</name> <city>pottstown</city> <phones> <phone> <number>311 555-8765</number> <type>mobile</type> </phone> </phones> <email>sam@gmail.com</email> </contact> <!-- third entity --> <contact op="DELETE"> <id>3</id> <name>eric</name> <city>lansdale</city> <phones> <phone> <number>311 555-9012</number> <type>home</type> </phone> <phone> <number>311 555-2109</number> <type>mobile</type> </phone> </phones> <email>eric@gmail.com</email> </contact> <!-- fourth entity --> <contact> <id>4</id> <name>bill</name> <city>malvern</city> <phones> <phone op="UPSERT"> <number>311 555-3456</number> <type>home</type> </phone> <phone op="UPSERT"> <number>311 555-6543</number> <type>mobile</type> </phone> </phones> <email>bill@gmail.com</email> </contact> </batch>
Response samples
- 202
- 400
- 401
- 403
- 404
- 500
- 503
https://c01-usa-east.hub.boomi.com/mdm/universes/851a6a64-6a88-4916-a5b7-d6a974d54318/records/updates/42
Get Batch Update Status
The Get Batch Update Status operation retrieves the status, in XML format, of a particular batch update for a universe (domain) under the authenticated account. There is an option to also retrieve the individual entity status in the batch.
Additional Information: Note: You can implement requests for this operation in processes using the HTTP Client connector, as demonstrated by example 2 in the sample process Hub: Read Batch Information, which you can install in your account from the process library in Integration.
Security Requirements: You must have one of the following MDM privileges:
Without Advanced Security:
- MDM - Batch Admin OR
- MDM - Activity Reporting
Authorizations:
path Parameters
| universeId | any Example: 851a6a64-6a88-4916-a5b7-d6a974d54318 Universe ID. Listed in the Repositories UI URL. |
| batchId | any Example: 42 Batch update ID. To obtain the needed batch update resource ID, first perform an Update Golden Records or Update Golden Records (Stage) operations and extract the ID from the response body — the ID is the last segment of the batch update resource URL. |
query Parameters
| repositoryId | any Repository ID. Case sensitive. Required with JWT authentication only. You can obtain the repository ID from the URL after navigating to the repository in the user interface. |
| includeEntities | any Example: includeEntities=false Set to true to request entity status in addition to batch status. Set to false (the default) to request batch status only. |
Responses
Response Schema: application/xml
| batchId | string |
| source | string |
| instance | string |
| lockedBy | string |
| createdByType | object (BatchCreatedByType) |
| trackback | string |
| state | string |
| createdAt | string |
| updatedAt | string |
| parseStart | string |
| parseEnd | string |
| enrichStart | string |
| enrichEnd | string |
| incorporateStart | string |
| incorporateEnd | string |
| endedAt | string |
| entityCount | integer <int32> |
| quarantinedCount | integer <int32> |
| createdCount | integer <int32> |
| deletedCount | integer <int32> |
| updatedCount | integer <int32> |
object (BatchEntities) |
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
- 503
<batch> <batchId>42</batchId> <source>CRM_SYSTEM</source> <instance>string</instance> <lockedBy>string</lockedBy> <createdByType></createdByType> <trackback>string</trackback> <state>COMPLETED</state> <createdAt>2016-10-31T15:12:21Z</createdAt> <updatedAt>2016-10-31T15:12:21Z</updatedAt> <parseStart>2016-10-31T15:12:21Z</parseStart> <parseEnd>2016-10-31T15:12:21Z</parseEnd> <enrichStart>2016-10-31T15:12:21Z</enrichStart> <enrichEnd>2016-10-31T15:12:21Z</enrichEnd> <incorporateStart>2016-10-31T15:12:21Z</incorporateStart> <incorporateEnd>2016-10-31T15:12:21Z</incorporateEnd> <endedAt>2016-10-31T15:12:21Z</endedAt> <entityCount>5</entityCount> <quarantinedCount>5</quarantinedCount> <createdCount>5</createdCount> <deletedCount>5</deletedCount> <updatedCount>5</updatedCount> <entities> <entity id="12345"> <createdAt>2016-10-31T15:12:21Z</createdAt> <updatedAt>2016-10-31T15:12:21Z</updatedAt> <state>COMPLETED</state> <stateDetail>CREATED</stateDetail> <sourceEntityId>6f78f990-dbb9-4d97-94ff-64f7d31bc66f</sourceEntityId> <recordId>0fc4eb6d-f12c-4cdd-ba37-5475caed4887</recordId> <transactionId>d1684e83-5e78-4fbe-99f0-32f08e507288</transactionId> </entity> </entities> </batch>
Query Batch History
The Query Batch History operation retrieves records of incoming batches of source entries contributed to a specific universe (domain) under the authenticated account. The response provides information about each batch, including the batch ID, contributing source, batch status, creation timestamp, and processing end time.
Security Requirements: You must have one of the following MDM privileges:
Without Advanced Security:
- MDM - Batch Admin OR
- MDM - Activity Reporting
Authorizations:
path Parameters
| universeId | any Example: 851a6a64-6a88-4916-a5b7-d6a974d54318 Universe ID. Listed in the Repositories UI URL. |
query Parameters
| repositoryId | any Repository ID. Case sensitive. Required with JWT authentication only. You can obtain the repository ID from the URL after navigating to the repository in the user interface. |
Request Body schema: application/xmlrequired
The body of the request must conform to the following structure.
Paging: The optional offsetToken and limit attributes for <BatchHistoryQuery> are used for paging. The limit value is the maximum number of batches to return per page. Boomi Data Hub enforces a maximum of 200 entries per page regardless of the limit value. The offsetToken value corresponds to the offsetToken value returned from a previous Query Batch History request.
Child elements of <BatchHistoryQuery> set query filter parameters:
<sourceId>(optional) — sets a filter by source. Specify the source by its unique ID.<fromDate>and<toDate>(both optional) — set a time span filter. The date and time format is YYYY-MM-ddTHH:mm:ssZ (UTC).<state>(optional) — sets a filter by the batch status. This element can repeat — one token per occurrence. The following tokens are valid:- CREATED — Batches created for which processing has not yet begun.
- PARSING — Validate batches for specification of a valid contributing source for the target universe and validate batches whose entities are for conformance with the universe layout.
- PARSED — Batches specify a valid contributing source for the target universe and whose entities conform with the universe layout and are ready for enrichment.
- ENRICHING — Batches to which to apply data quality steps are to the entities.
- ENRICHED — Batches to which data quality steps have been applied to the batch entities and the entities are ready to be processed for incorporation in the target universe.
- PROCESSING — Batches whose entities are being processed for incorporation in the target universe.
- ERRORED — Batches whose entities failed processing with an unexpected error.
- COMPLETED — Batches where incorporation of entities are in the target universe.
- COMPLETED_ERRORS — Could not process entities in batches for incorporation into the target universe due to an unexpected error.
You must omit elements corresponding to unused filter parameters from <BatchHistoryQuery>.
| sourceId | string |
| fromDate | string |
| toDate | string |
| states | Array of strings |
| offsetToken | string |
| limit | integer <int32> |
Responses
Response Schema: application/xml
Array of objects (BatchMetaData) | |
| sourceId | string |
| offsetToken | string |
| resultCount | integer <int32> |
| totalCount | integer <int64> |
Request samples
- Payload
<BatchHistoryQuery offsetToken="MjAw" limit="100"> <sourceId>SFDC</sourceId> <fromDate>2023-01-01T00:00:00Z</fromDate> <toDate>2023-01-01T00:00:00Z</toDate> <state>string</state> </BatchHistoryQuery>
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
- 503
<BatchHistoryResponse sourceId="SFDC" resultCount="5" offsetToken="MjAw" totalCount="1000"> <batch> <batchId>42</batchId> <source>CRM_SYSTEM</source> <state>COMPLETED</state> <createdAt>2016-10-31T15:12:21Z</createdAt> <endedAt>2016-10-31T15:12:21Z</endedAt> </batch> <batch> <batchId>42</batchId> <source>CRM_SYSTEM</source> <state>COMPLETED</state> <createdAt>2016-10-31T15:12:21Z</createdAt> <endedAt>2016-10-31T15:12:21Z</endedAt> </batch> </BatchHistoryResponse>
Cancel Pending Batches
The Cancel Pending Batches operation sets pending batches that are in an ENRICHED or PARSED status to CANCELED for a given universe and source.
Additional Information: The operation cancels up to 10,000 pending batches. If you have more than 10,000 pending batches, repeat the request until all pending batches are canceled. Contact Boomi Support for assistance in determining the amount of pending batches.
Security Requirements: You must have one of the following MDM privileges:
Without Advanced Security:
- MDM - Batch Admin
Authorizations:
path Parameters
| universeId | any Example: 851a6a64-6a88-4916-a5b7-d6a974d54318 Universe ID. Listed in the Repositories UI URL. |
| sourceId | any Example: CRM_SYSTEM Source ID. The source ID is listed on the Sources page in the user interface. |
query Parameters
| repositoryId | any Repository ID. Case sensitive. Required with JWT authentication only. You can obtain the repository ID from the URL after navigating to the repository in the user interface. |
Responses
Response samples
- 202
- 400
- 401
- 403
- 404
- 500
- 503
1638472951234
