Documentation

Risk Cloud API: Data Repositories

Updated on:September 5, 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:

Data Repository contains Item Fields ex
- Data Repository => Risk Cloud Ingredients
- Item Fields created on Risk Cloud Ingredients => Name, Description
Data Repository contains Items that are mapped to the Item Fields structure. Example:

External Id	Name	Description
<item external id>	Flour	A sack of flour.

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. <`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. <`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` item is associated with. <`DataWarehouseOut`> – same as 1.2 Response.
`values`	Map	Map of Item Field Id and Item Field value.

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 unlink from 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`. <`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.

5.6 Find Items Linked to Record

This endpoint will find the specified Items that are linked to the record given the record id passed in via a path parameter.

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

This endpoint has the following path and query parameters:

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

Query Parameter	Required	Description
`include-all-fields`	No	Optional boolean field to return all field data or only the filtered fields.
`query`	No	Optional additional text filtering you may want to add.
`link-state`	No	Optional linked state to search for `LINKED` or `NOT_LINKED` items. Defaults to `LINKED`.
`pageable params`	No	Optional pageable params ex `sort` or `size`.

Response

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