Please reference our Bulk Link Records Help Article for in-depth information about the functionality and permissions needed.
Obtain your API Access Token to get started.
Step 1 Setup Bulk Link Records Request
1.1 Check for Incomplete Bulk Link Record Request
This endpoint will verify if you have any incomplete Bulk Link Record (BLR) Request. Ideally, we should only run ONE unique set of workflow (wf) /step combination at a time. The order matters, so the reverse is possible as long as we don’t have the exact same workflow/step combination. The combination will be available once the the latest one completes or fails.
Possible combinations Ex.
| Input New BLR Request (req) | Existing BLR Request [STATUS] | Allowed? |
|---|---|---|
| req#1 wf1 / step 1 -> wf1 / step 2 | none | yes – no other active request exist |
| req#2 wf1 / step 1 -> wf1 / step 2 | req#1 wf1 / step 1 -> wf1 / step 2 [PROCESSING / PENDING UPLOAD / FILE ERRORS / SYSTEM ERROR] | no – one other active request exist |
| req#2 wf1 / step 1 -> wf1 / step 2 | req#1 wf1 / step 1 -> wf1 / step 2 [COMPLETED / COMPLETED WITH ERROR] | yes – no other active request exist |
| req#2 wf1 / step 1 -> wf1 / step 2 | req#1 wf1 / step 2 -> wf1 / step 1 [PROCESSING / PENDING UPLOAD / FILE ERRORS / SYSTEM ERROR] | yes – reverse case is still acceptable |
| req#2 wf1 / step 1 -> wf1 / step 2 | req#1 wf1 / step 2 -> wf1 / step 1 [COMPLETED / COMPLETED WITH ERROR] | yes – reverse case is still acceptable |
This endpoint has the following parameters:
sourceWorkflowId
No
The first workflow Id you selected
targetWorkflowId
No
The second workflow Id you selected
Response
boolean
Return true if it has an incomplete request.
1.2 Create Bulk Link Records Endpoint
This endpoint will create a new Bulk Link Record Request. We recommend you verify that there are no incomplete Bulk Link Record Request before proceeding with this endpoint.
This endpoint has the following parameters:
sourceWorkflowId
No
The first workflow Id you selected
targetWorkflowId
No
The second workflow Id you selected
Response
<BulkLinkRecordsResult>
| Response Parameter | Description |
|---|---|
id | The Bulk Link Record Request Id. |
creator | The Bulk Link Record Request creator. |
submitter | The Bulk Link Record Request submitter. |
dateCompleted | The date the Bulk Link Record Request was completed. |
dateCreated | The date the Bulk Link Record Request was created. |
status | The current status for the Bulk Link Record Request. |
sourceWorkflowId | The first workflow Id. |
sourceWorkflowName | The first workflow name. |
sourceApplicationId | The first workflow > application Id. |
sourceApplicationName | The first workflow > application name. |
sourceApplicationIcon | The first workflow > application icon. |
sourceApplicationColor | The first workflow > application color. |
targetWorkflowId | The second workflow Id. |
targetWorkflowName | The second workflow name. |
targetApplicationId | The second workflow > application Id. |
targetApplicationName | The second workflow > application name. |
targetApplicationIcon | The second workflow > application icon. |
targetApplicationColor | The second workflow > application color. |
workflowMapType | The workflow relationship mapping type between the first and second workflow. |
fileName | The name of the file you uploaded. |
errorTemplateCount | The number of errors found on your uploaded file. |
requestTotal | The total number of rows you aimed to link after your Bulk Link Record Request finished processing. |
requestSuccessTotal | The total number of successful links after your Bulk Link Record Request finished processing. |
requestErrorTotal | The total number of unsuccessful links after your Bulk Link Record Request finished processing. |
Step 2 Upload and Verify File on Bulk Link Record Request
2.1 Download Bulk Link Record Template
This endpoint will download the bulk link record template file for your Bulk Link Record Request. You populate it with data and upload it later.
This endpoint has the following parameters:
| Required Path Parameter | Description |
|---|---|
requestId | The unique Bulk Link Records Request Id. |
Response
| Response Parameter | Description |
|---|---|
| Returns the base template xlsx file. |
2.2 Upload File
This endpoint will upload your file to the given Bulk Link Record Request. It will perform a high level validation check and should pass before processing. It does not do any detailed level validation or actual record linking.
This endpoint has the following parameters:
| Required Path Parameter | Description |
|---|---|
requestId | The unique Bulk Link Records Request Id. |
file | The file you want to upload to process. Can be in xlsx or csv format. |
Response
<BulkLinkRecordsResult> – same as 1.2 Response.
2.3 Delete File
This endpoint will delete the file from the given Bulk Link Record Request. You can run the upload file endpoint again to add a new file.
This endpoint has the following parameters:
| Required Path Parameter | Description |
requestId | The unique Bulk Link Records Request Id. |
Response
<BulkLinkRecordsResult> – same as 1.2 Response.
Step 3 Process File and Complete Record Linking
3.1 Process File
This endpoint will start the file process. We recommend the file passing the high level validation check before proceeding. This endpoint will perform a detailed level validation check and either result in (1) failed detailed level validation > download file validation error summary, no records were linked (2) passed detailed level validation > download completed / completed with error summary, records were linked.
This endpoint has the following parameters:
| Required Path Parameter | Description |
requestId | The unique Bulk Link Records Request Id. |
Response
200 status code with an empty body.
3.2 Route 1 Failed Detailed Level Validation > Download File Validation Error Summary
This endpoint will download the validation error summary. The file failed the detailed level validation check. The Bulk Link Record Request should have the status FILE_ERRORS. No records have been linked.
This endpoint has the following parameters:
| Required Path Parameter | Description |
requestId | The unique Bulk Link Records Request Id. |
Response
| Response Parameter | Description |
ModelAndView | Returns the validation error summary in xlsx format. |
3.3 Route 2 Passed Detailed Level Validation > Download Processed Completed (with Errors) Summary
This endpoint will download the completed (with errors) summary. The file passed the detailed level validation check. The Bulk Link Record Request should have the status COMPLETED or COMPLETED_WITH_ERRORS. Records should have been linked.
This endpoint has the following parameters:
| Required Path Parameter | Description |
requestId | The unique Bulk Link Records Request Id. |
Response
| Response Parameter | Description |
ModelAndView | Returns the completed / completed with errors summary in xlsx format. |
Step 4 Other
4.1 Find Bulk Link Record Request
This endpoint will find the given Bulk Link Records Request.
This endpoint has the following parameters:
| Required Path Parameter | Description |
requestId | The unique Bulk Link Records Request Id. |
Response
<BulkLinkRecordsResult> – same as 1.2 Response.
4.2 Find All Bulk Link Record Request
This endpoint will find all the Bulk Link Records Request that you have access to.
This endpoint has the following parameters:
| Query Parameter | Required | Description |
| No | Optional pageable fields ex sort or size. |
Response
| Response Parameter | Description |
Page<BulkLinkRecordsResult> | Pageable list of BulkLinkRecordsResult. |
<BulkLinkRecordsResult> – same as 1.2 Response.
4.3 Deactivate Bulk Link Record Request
This endpoint will deactivate the given Bulk Link Records Request.
This endpoint has the following parameters:
| Required Path Parameter | Description |
requestId | The unique Bulk Link Records Request Id. |
Response
<BulkLinkRecordsResult> – same as 1.2 Response.