Risk Cloud API: Upload Attachments

Updated on: January 17, 2022

This article will describe how to add an attachment to a Risk Cloud Record using our API.

Within Risk Cloud, you are able to add “Attachment” Fields to your Records. These Fields allow you to attach files such as evidence, documents for employee attestation, and many additional use cases.

Here are the possible use cases to attach a document using Risk Cloud API:

Use Case#1 Add New Attachment

  1. Obtain the FIELD_ID where you would like to upload an attachment

  2. Upload a new file via a POST /api/v1/attachments?field={FIELD_ID}

  3. Retrieve the current values (attachments) via a GET /api/v1/currentValues/field/{FIELD_ID}

  4. Attach the current values (attachments) to your specific record via a POST /api/v1/valueMaps?record={RECORD_ID}

Use Case #2 Add New Version for Existing Attachment

  1. Retrieve the current values (attachments) via a GET /api/v1/currentValues/field/{FIELD_ID}
  2. Upload new version of an existing attachment (versioning) via a POST /api/v1/internal/attachments/{attachmentId}

Obtaining Proper 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 here.

Use Case#1 Add New Attachment

Please follow this use case if you are adding a new attachment to the attachment field.

Step 1: Obtain the FIELD_ID

In the first 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 from obtaining it in the Field Edit menu of your Risk Cloud environment, you may continue to Step 2.

Part 1 : 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:

GET/api/v1/workflows

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": [
            {
                ..
            },
            {
                ..
            }
        ]
    }

After identifying the Workflow that contains the Field you would like to add an attachment to, you can take the “id” from this object as your WORKFLOW_ID.

Part 2 : Now that we have our WORKFLOW_ID, 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:

GET/api/v1/fields/workflow/{WORKFLOW_ID}/values

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 2: Upload a file

In this step, we will use the FIELD_ID found in step one 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/attachments?field={FIELD_ID}' \\
--header 'Authorization: Bearer {API_TOKEN}' \\
--form 'file=@"/the/path/to/attachment.pdf"'

Once you have built this body, you can send it using the following POST request:

POST/api/v1/attachments?field={FIELD_ID}

The response should look like this:

{
    "attachmentStatus": "CLEAN",
    "id": "QoZy9k73",
    "valueType": "Attachment",
    "discriminator": "CLEAN",
    "textValue": "FILE NAME",
    "numericValue": 1.0,
    "isDefault": false,
    "archived": false,
    "priority": 0,
    "attachmentStatus": "CLEAN",
    "contentType": "image/png",
    "fileSize": NUMBER,
    "fileExtension": "png",
    "originalFileExtension": "png",
    "awsS3Key": "S3 KEY",
    "versionCount": 1,
    "empty": false,
    "fieldId": "EbfvwDRi"
}

Step 3: Get the Current Values (Attachments)

We will retrieve the current values (attachments) by following this GET request:

GET/api/v1/currentValues/field/{FIELD_ID}

The response should look like this:

{
    "content": [
        {
            .. //current value 1 / attachment 1
        },
    ],
    "pageable": {
        ..
    },
    "last": true,
    "totalPages": 1,
    "totalElements": 3,
    "sort": {
        "empty": true,
        "unsorted": true,
        "sorted": false
    },
    "number": 0,
    "size": 20,
    "first": true,
    "numberOfElements": 3,
    "empty": false
}

Step 4: Attach the file to the record

In this final step, we will use the information from Step 3 to tie the attachment to the specified record. We will build our POST request’s body using the following structure:

{
  "currentValues": [
      # COPY THE ENTIRE CURRENT VALUE CONTENT FROM STEP 3 RESPONSE EX.
      { 
          .. //current value 1 / attachment 1 
      },
  ],
  "field": {
    "valueType": "Attachment",
    "fieldType": "ATTACHMENT",
    "id": "FIELD_ID"
  }
}

IMPORTANT: Make sure you copy the ENTIRE content list of current values (attachment) else those entries will be missing.

Once you build the above body, send the following POST request:

POST/api/v1/valueMaps?record={RECORD_ID}

The response should look like this:

{
    "id": "uexgD8Ej",
    "currentValues": [
        {
            "discriminator": "CLEAN",
            "id": "QoZy9k73",
            "valueType": "Attachment",
            "discriminator": "CLEAN",
            "textValue": "TEXT",
            "numericValue": 1.0,
            "isDefault": false,
            "archived": false,
            "priority": 0,
            "attachmentStatus": "CLEAN",
            "contentType": "image/png",
            "fileSize": 33517,
            "fileExtension": "png",
            "originalFileExtension": "png",
            "awsS3Key": "S3 KEY",
            "versionCount": 1,
            "empty": false,
            "fieldId": null
        }
    ],
    "field": {
        "fieldType": "ATTACHMENT",
        "id": "EbfvwDRi",
        "name": "attachment",
        "label": "attachment",
        "tooltip": null,
        "enableVersions": true,
        "validTypeForCalculationInput": false
    },
    "expressionResult": 1.0
}

After sending this final POST request, your attachment should be attached to your specified Record and Field.

Use Case#2 Add New Version for Existing Attachment

Please follow this use case if you are adding a new version to an existing attachment on the attachment field. FYI at this point, there should already be an existing attachment to work with.

Step 1: Get the Current Values (Attachments)

Refer to "Step 3: Get the Current Values (Attachments)" from above.

Step 2: Upload new version of an existing attachment

You will need the attachmentId aka the currentValue id from Step 1 above. It will also take in the same named updated file within the body request.

POST/api/v1/internal/attachments/{attachmentId}

The response should look like:

{
    "id": "<String>",
    "active": <boolean>,
    "created": <long>,
    "updated": null,
    "awsS3Bucket": null,
    "s3Directory": "<String>",
    "awsS3Key": "<String>",
    "contentType": "<String>",
    "fileSize": <long>,
    "fileExtension": "<String>",
    "awsVersionId": "<String>",
    "fileName": "<String>",
    "user": {
          ..
        },
        "lastDeactivated": null,
        "name": "LogicGate Administrator",
        "external": <boolean>,
        "locked": <boolean>,
        "serviceAccount": <boolean>,
        "superUser": <boolean>,
        "disabled": <boolean>,
        "empty": <boolean>,
        "idOrTransientId": "<String>",
        "transientIdOrId": "<String>",
        "fieldId": null
    }
}

You can rerun the GET current values endpoint or check the UI to verify that your attachment incremented in version.

 

For any additional questions, please reach out to [email protected]!