Risk Cloud API: Upload Attachments
Updated on: January 17, 2022
Within Risk Cloud, you are able to add “Attachment” Fields to your Records. These Fields allow you, perhaps very obviously, to attach files. Customers use these Fields in order to upload evidence, add documents for employee attestation, and many additional use cases.
In this article, we will walk through three steps needed to attach a document using Risk Cloud API:
-
Obtain the
FIELD_IDwhere you would like to upload an attachment -
Upload a new file via a
POST /api/v1/attachments?field={FIELD_ID}request -
Attach the file to your specific record via a
POST /api/v1/valueMaps?record={RECORD_ID}request - Optional: Upload new version of an existing attachment (versioning) via a
POST /api/v1/internal/attachments/{attachmentId}request
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.
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.
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
}
]
}
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.
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:
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:
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: Attach the file to the record
In this final step, we will compile the information from our previous two steps in order to attach our upload to the specific record that we are interested in. We will build our POST request’s body using the following structure:
{
"currentValues": [
# RESPONSE FROM STEP 2
],
"field": {
"valueType": "Attachment",
"fieldType": "ATTACHMENT",
"id": "FIELD_ID"
}
}
Once you build the above body, send the following POST request:
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.
Step 4: Optional - Upload new version of an existing attachment
At this point, you should have gone thru Steps 1-3. This step is similar to Step 2. You will need the attachmentId aka the currentValue id (you can get this from Step 1 currentValues). It will also take in the same named updated file within the body request.
The response should look the same as Step 2 Route A but the versionCount should have incremented by 1. Additionally, since the valueMap and file exist at this point, you do NOT need to perform Step 3.
For any additional questions, please reach out to [email protected]!