With the Automated Evidence Collection endpoint, you have the ability to push evidence files into the Risk Cloud.
Whether your systems are secure, custom, or on-prem, the Automated Evidence Collection endpoint allows you to automate the storage of evidence in the Risk Cloud on your terms, without needing to grant your Risk Cloud environment access to your internal systems.
In this article, we will walk through the steps necessary for uploading evidence with the Risk Cloud API.
- Obtain the
STEP_IDwhere you want to create a new record that holds the attachment - Obtain the
FIELD_IDwhere you would like to upload the attachment - Obtain the
RECORD_IDof the parent record to which the newly created evidence record will be linked - Upload a file using the following Evidence Collection
POSTrequest
Setup
Risk Cloud Application Setup
Automated Evidence Collection requires an application with two workflows linked to each other. The Controls Compliance Application available from Risk Cloud Exchange is an ideal application to get started.
API Authentication
Prior to any interaction with Risk Cloud’s APIs we will need to set the authorization header. Instructions on how this can be accomplished can be found in the usage article Risk Cloud API: Authentication.
Evidence Endpoint Usage
Step 1: Obtain the STEP_ID
In the first step, we will be running a series of requests in order to determine the STEP_ID where we would like to create a new record to hold the attachment. If you already know your STEP_ID you may continue to Step 2: Obtain the FIELD_ID.
Using the Risk Cloud application
The most straightforward way to find a step ID is to navigate to the step builder page in the UI and take the ID from the end of the URL:
https://your-company.logicgate.com/build/steps/STEP_IDUsing the Risk Cloud API
First, we need to determine the WORKFLOW_ID of the workflow that contains our field. To do this, you can send the following GET request:
This will return an array of workflow objects, each looking like this:
{
"id": "WORKFLOW_ID",
"name": TABLE REPORT NAME,
"recordPrefix": null,
"allowGroups": false,
"requireGroups": false,
"xpos": 177,
"ypos": 156,
"priority": 0,
"sla": {
"enabled": false,
"duration": 0
},
"steps": [
{
"stepType": "Origin",
"id": "xt2X0dSM",
"name": "Default Origin",
"stepType": "Origin",
"priority": 1,
"allowEntitlements": true,
"xpos": 55,
"ypos": 55,
"isPublic": false,
"sla": {
"enabled": false,
"duration": 0
},
"chain": false,
"origin": true,
"end": false
},
{
"stepType": "End",
"id": "Y5B1k7yq",
"name": "Default End",
"stepType": "End",
"priority": 2,
"allowEntitlements": true,
"xpos": 200,
"ypos": 55,
"isPublic": false,
"sla": {
"enabled": false,
"duration": 0
},
"chain": false,
"origin": false,
"end": true
}
]
}Once you identify the step where you would like to add an attachment, you can take the “id” value as your STEP_ID for the subsequent steps. Also keep track of the “id” value of the workflow object as the WORKFLOW_ID for the next step.
Step 2: Obtain the FIELD_ID
In this step, we will be running a series of requests in order to determine the FIELD_ID where we would like to upload our attachment. If you already know your FIELD_ID you may continue to Step 3: Obtain the FIELD_ID
Using the Risk Cloud application
The most straightforward way to find a field ID is to navigate to the step builder page in the UI and click the edit pencil on the specific field. The field ID will be displayed on the field edit modal:
Using the Risk Cloud API
Using our WORKFLOW_ID from the previous step, we can send a request to find the specific Field where we want to add an attachment. To do this, we will send the following GET request:
This request will return an array of field objects, similar to this object:
{
"fieldType": "TEXT_AREA",
"id": "FIELD ID",
"name": "text1",
"label": "text1",
"tooltip": null,
"currentValues": [],
"operators": [
"NULL",
"NOT_NULL",
"EQUALS",
"NOT_EQUALS",
"CONTAINS",
"DOES_NOT_CONTAIN"
],
"convertibleTo": [
"TEXT"
],
"pattern": null,
"message": null,
"hasHtml": false,
"fieldType": "TEXT_AREA",
"valueType": "Common",
"validTypeForCalculationInput": false,
"discrete": false,
"global": false
}Once you identify the field where you would like to add an attachment, you can take the “id” value as your FIELD_ID for the subsequent steps.
Step 3: Obtain the RECORD_ID
In this step, we will be running a series of requests in order to determine the RECORD_ID where we would like to serve as the parent record for linking uploaded attachments to. If you already know your RECORD_ID you may continue to Step 4: Upload a file using a POST request.
Using the Risk Cloud application
The most straightforward way to find a record ID is to navigate to the record in the UI and take the ID from the end of the URL:
https://your-company.logicgate.com/records/RECORD_IDUsing the Risk Cloud API
An overview of the record search endpoint is available in the article Risk Cloud API: Record Search.
Step 4: Upload a file using a POST request
In this step, we will use the STEP_ID, FIELD_ID, and RECORD_ID found in the previous steps to upload our attachment.
The file can be sent in the request using the multipart/form-data content type with a key named file and a value of the attachment file (often represented by HTTP request libraries or tools as the path to the file).
A cURL sample is demonstrated below:
curl --location 'https://your-company.logicgate.com/api/v1/evidence?parentRecordId={RECORD_ID}&fieldId={FIELD_ID}&stepId={STEP_ID}' \
--header 'Authorization: Bearer {API_TOKEN}' \
--form 'file=@"/the/path/to/evidence/file.pdf"'Once you have built this body, you can send it using the following POST request:
Optional Query Params:
jobExecutionOperationId
string
The JOB_EXECUTION_OPERATION_ID to update the history of when using an AEC Webhook.
dueDateInterval
integer
How long after record creation should the due date be set.
dueDateIntervalUnit
string
The unit the due date interval should be.
Values: DAYS, WEEKS, MONTHS, YEARS
assignUserId
string
The ASSIGN_USER_ID for the user that the newly created record will be assigned to.
assignFieldId
string
The ASSIGN_FIELD_ID for the field value that the newly created record will be assigned to.
The response should look like this:
{
"recordId": "CREATED_RECORD_ID",
"record": { Created Record Information Here },
"parentRecordId": "RECORD_ID",
"parentRecord": { Parent Record Information Here },
"attachmentId": "ATTACHMENT_ID",
"attachment": { Attachment Data Here },
"stepId": "STEP_ID",
"step": { Step Information Here }
}After sending this final POST request, your attachment should be attached to a newly created record in your specified Step linked to your specified Record and Field.
For any additional questions, please reach out to developer‑[email protected]!