• Home
• Developer Resources
• API Usage Guides

Risk Cloud API: Automated Evidence Collection

Updated on: May 11, 2023

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.

1. Obtain the STEP_ID where you want to create a new record that holds the attachment
2. Obtain the FIELD_ID  where you would like to upload the attachment
3. Obtain the RECORD_ID  of the parent record to which the newly created evidence record will be linked
4. Upload a file using the following Evidence Collection POST request

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:

http://your-company.logicgate.com/build/steps/STEP_ID

Using 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:

http://your-company.logicgate.com/records/RECORD_ID

Using 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:

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 [email protected]!