Risk Cloud API: Data Repositories

Updated on: September 05, 2024

Please reference our Data Repositories Help Article for in-depth information about the functionality and permissions needed. 

Obtain your API Access Token to get started.

High Overview of the Components Involved:

  1. Data Repository contains Item Fields ex
    • Data Repository => Risk Cloud Ingredients
    • Item Fields created on Risk Cloud Ingredients => Name, Description
  2. Data Repository contains Items that are mapped to the Item Fields structure ex
External Id Name Description
<item external id> Flour A sack of flour.

Table of Contents

Step 1 Create and Update Data Repository

Step 2 Create and Update Item Field on Data Repository

Step 3 Import Item into Data Repository

Step 4 Link and Unlink Between Record and Item

Step 5 Other

Step 1 Create and Update Data Repository

1.1 Check if Data Repository Name Already Exist

This endpoint will check if the requested Data Repository name already exist. We recommend doing this first before creating a new Data Repository.

GET/api/v1/data-repository/exists

This endpoint has the following parameters:

Query Parameter Required Description 
name
 No The Data Repository name you want to verify.

 

Response

Response Parameter Description
boolean Return true if the Data Repository name already exist.

Return false if the Data Repository name does NOT already exist.

1.2 Create Data Repository

This endpoint will create a new Data Repository. We recommend that you check the name for uniqueness before proceeding.

POST/api/v1/data-repository

This endpoint has the following parameters:

Query Parameter Required Description 
DataWarehouseIn
 Yes The DataWarehouseIn request you want to create. This will be in the request body. See below for DataWarehouseIn.

<DataWarehouseIn>

Request Object Parameter Request Object Type Description
name String The Data Repository name. Must be unique and cannot be blank.
description String The Data Repository description.
itemPrefix String The Data Repository item prefix. Cannot be blank.
externalIdDisplayName String The Data Repository external Id display name. Not needed for Data Repository creation.

Response

<DataWarehouseOut>

Response Parameter Description
id The Data Repository Id.
created The date the Data Repository was created.
updated The date the Data Repository was updated.
name The Data Repository name.
description The Data Repository description.
itemPrefix The Data Repository item prefix.
sequence The Data Repository sequence. Will always be set to zero.
externalIdDisplayName The Data Repository external Id display name.
itemFields The list of ItemFieldOut for the Data Repository. See below for ItemFieldOut .
itemCount The number of Items for the Data Repository.

<ItemFieldOut>

Response Parameter Description
id The Item Field id.
created The date the Item Field was created.
updated The date the Item Field was updated.
name The Item Field name.
displayOrder The Item Field display order.
displayInRecords If the Item Field should be displayed in records.
primaryField If the Item Field is a primary field. Only one Item Field may be primary field at a time.

1.3 Update Data Repository

This endpoint will update a single Data Repository.

PATCH/api/v1/data-repository/{id}

This endpoint has the following parameters:

Required Path Parameter Description
id The unique Data Repository Id.

 

Query Parameter Required Description 
DataWarehouseIn
 Yes The DataWarehouseIn request you want to create. This will be in the request body. See below for DataWarehouseIn.

<DataWarehouseIn> - same as 1.2 Response.

Response

<DataWarehouseOut> - same as 1.2 Response.

Step 2 Create and Update Item Field on Data Repository

2.1 Check if Item Field Name Already Exist

This endpoint will check if the requested Item Field name already exist. We recommend doing this first before creating a new Item Field.

GET/api/v1/data-repository/item-field/exists

This endpoint has the following parameters:

Query Parameter Required Description 
data-repository-id
 No The Data Repository you want to verify the Item Field on. 
name
 No The Item Field name you want to verify.

 

Response

Response Parameter Description
boolean Return true if the Item Field name already exist on the specified Data Repository.

Return false if the Item Field name does NOT already exist on the specified Data Repository.

2.2 Create Item Field on Data Repository

This endpoint will create a new Item Field on the specified Data Repository.

POST/api/v1/data-repository/{id}/item-field

This endpoint has the following parameters:

Required Path Parameter Description
id The unique Data Repository Id.

 

Query Parameter Required Description 
ItemFieldIn
 Yes The ItemFieldIn request you want to create. This will be in the request body. See below for ItemFieldIn.

<ItemFieldIn>

Request Object Parameter Request Object Type Description
name String The Item Field name. Must be unique and cannot be blank.
displayInRecords boolean Should the Item Field display in records.
primaryField boolean Is the Item Field the primary field.
displayOrder int The Item Field display order.

Response

<ItemFieldOut> - same as 1.2 Response.

 

2.3 Update Item Field on Data Repository

This endpoint will update a Item Field.

PATCH/api/v1/data-repository/item-field/{id}

This endpoint has the following parameters:

Required Path Parameter Description
id The unique Item Field Id.

 

Query Parameter Required Description 
ItemFieldIn
 Yes The ItemFieldIn request you want to update. This will be in the request body. See below for ItemFieldIn.

<ItemFieldIn> - same as 2.2 Response.

Response

<ItemFieldOut> - same as 1.2 Response.

 

Step 3 Import Item into Data Repository

3.1 Download the Import Data Template

This endpoint will download the import data template. You can populate it with Item data and upload it later.

GET/api/v1/data-repository/{id}/import/template

This endpoint has the following parameters:

Required Path Parameter Description
id The unique Data Repository Id.

 

Response

Response Parameter Description
StreamingResponseBody Returns the import data template file in csv format.

3.2 Upload the Import Data Template

This endpoint will upload your Item data into the Data Repository. This will create and/or update the Items based on an external id. Only columns where the headers match an Item Field name for the Data Repository will be used.

POST/api/v1/data-repository/{id}/items/import

This endpoint has the following parameters:

Required Path Parameter Description
id The unique Data Repository Id.
file The file you want to upload to process. Should be in csv format.

 

Response

200 status code with an empty body.

 

3.3 Search All Items

This endpoint will search and return all the Items for a given Data Repository.

POST/api/v1/data-repository/{id}/items

This endpoint has the following parameters:

Required Path Parameter Description
id The unique Data Repository Id.

 

Query Parameter Required Description 
item-field
 No Optional Item Field Id to filter the results. 
query
 No Optional query string to filter the results. 
itemSearchFilters
 No Optional list of ItemSearchFilter to filter the results. See below for ItemSearchFilter. 
.pageable params
 No Optional pageable params ex sort or size.

<ItemSearchFilter>

Request Object Parameter Request Object Type Description
itemFieldId String The Item Field Id. Must be unique and cannot be blank.
searchType ItemSearchType The search type ex TEXT or NUMBER or FIXED_DATE .
operator Operator The operator type ex EQUALS or NOT_EQUALS or GREATER_THAN_EQUALS .
textValue String The text value.
numberValue Float The number start value.
endNumberValue Float The number end value.
dateValue Date The date start value.
endDateValue Date The date end value.
dateRangeType DateRangeType The date range type ex FIXED or LAST_THREE_MONTHS or NEXT_ONE_YEAR.

 

Response

Response Parameter Description
Page<ItemOut> Returns a pageable of ItemOut. See below for ItemOut.

<ItemOut>

Request Object Parameter Request Object Type Description
id String The Item Id.
created Date The date the Item was created.
updated Date The date the Item was updated.
sequenceId long The Item sequence Id.
externalId String The Item Id external Id.
dataRepository DataWarehouseOut The DataWarehouseOut the Item is associated with. See below for DataWarehouseOut .
values  Map<String, Object> Map of Item Field Id and Item Field value.

<DataWarehouseOut> - same as 1.2 Response.

 

Step 4 Link and Unlink Between Item and Record

4.1 Link Record to Item

This endpoint will link a Record to one or more Items.

PATCH/api/v1/data-repository/{data-repository-id}/items/link/record/{record-id}

This endpoint has the following parameters:

Required Path Parameter Description
data-repository-id The unique Data Repository Id.
record-id The unique Record Id.

 

Query Parameter Required Description 
externalIds
 Yes The external Ids from the Items that you want to link to the Record. This will be in the request body.

 

Response

200 status code with an empty body.

 

4.2 Unlink Record to Item

This endpoint will unlink a Record from one or more Items.

DELETE/api/v1/data-repository/{data-repository-id}/items/link/record/{record-id}

This endpoint has the following parameters:

Required Path Parameter Description
data-repository-id The unique Data Repository Id.
record-id The unique Record Id.

 

Query Parameter Required Description 
externalIds
 Yes The external Ids from the Items that you want to unlink from the Record. This will be in the request body.

 

Response

200 status code with an empty body.

 

Step 5 Other

5.1 Find Data Repository

This endpoint will find the specified Data Repository with related Item Fields.

GET/api/v1/data-repository/{id}

This endpoint has the following parameters:

Required Path Parameter Description
id The unique Data Repository Id.

Response

<DataWarehouseOut> - same as 1.2 Response.

 

5.2 Find All Data Repositories

This endpoint will find all the Data Repositories with their related Item Fields.

GET/api/v1/data-repository

This endpoint has the following parameters:

Query Parameter Required Description 
include-item-counts
 No Optional boolean field to include the number of items in each data repository. It defaults to ex false. 
pageable params
 No Optional pageable params ex sort or size.

Response

Response Parameter Description
Page<DataWarehouseOut> Pageable list of DataWarehouseOut. See below for DataWarehouseOut .

<DataWarehouseOut> - same as 1.2 Response.

 

5.3 Delete Data Repository

This endpoint will delete the specified Data Repository. This will permanently remove all associated Items and Item Fields. 

DELETE/api/v1/data-repository/{id}

This endpoint has the following parameters:

Required Path Parameter Description
id The unique Data Repository Id.

 

Response

200 status code with an empty body.

 

5.4 Find Item Field

This endpoint will allow you to find a single Item Field.

GET/api/v1/data-repository/item-field/{id}

This endpoint has the following parameters:

Required Path Parameter Description
id The unique Item Field Id.

 

Response

<ItemFieldOut> - same as 1.2 Response.

 

5.5 Delete Item Field

This endpoint will delete the specified Item Field. Any remaining fields in the Data Repository will be reordered appropriately.

DELETE/api/v1/data-repository/item-field/{id}

This endpoint has the following parameters:

Required Path Parameter Description
id The unique Item Field Id.

Response

200 status code with an empty body.