Risk Cloud API: Create Records

Updated on: January 17, 2022

How to create a Record, assign values to Fields, and submit a Record using common Risk Cloud endpoints.

We will start off by assuming an Application and Workflow have been created in Risk Cloud using the Build tools. In this example, we have created an “Onboarding” Application with a Workflow called “Employee". This Workflow has three Steps: “Add Employee”, “Manager Meeting”, and “Active Employee.”

Since the Origin Step in this Workflow is “Add Employee,” we will be using the Risk Cloud API to create a Record in this Step of our Workflow. When our new Record is created in “Add Employee”, we would also like the following  Fields in this Step to be populated with values:

Now that we have our Workflow set up we can interact with the Risk Cloud API to create a Record in “Add Employee”, populate these Fields, and submit the Record to “Manager Review”.

To create a Record, we need to start with a POST request with the proper JSON body. The JSON body requires three JSON objects: “step”, “workflow”, and “currentValueMaps”. We will construct our JSON body one object at a time.

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

First, we need a Step object with a Step’s ID key value-pair. This Step ID can be pulled via the browser’s URL and should look like this:

https://your-company.logicgate.com/build/steps/{STEP_ID}

We will take this value and input it into our JSON body. Our JSON now looks like the following:

{
  "step": {
    "id": "STEP_ID"
  }
}

Workflow

We need to next first fetch the Workflow’s ID.

Type: GET

https://your-company.logicgate.com/api/v1/workflows/step/{STEP_ID}

We will take the “id” value as the WORKFLOW_ID and use this to continue to fetch all the Fields in the Workflow using the following endpoint.

Current Value Maps

Risk Cloud uses currentValueMaps to map values to the proper Fields. Let us create our currentValueMaps object for the first input text value, “Employee Name.”

Type: GET

https://your-company.logicgate.com/api/v1/fields/workflow/{WORKFLOW_ID}/values

Now we must parse through the array for the Fields we need and use the ID for our currentValueMap object.

So far our object should look like:

{
  "field": {
    "id": "TEXT_FIELD_ID",
     "fieldType": "TEXT"
   }
 }

We will now need to input the values we want to set for this Field. In the Risk Cloud platform we refer to this, in an API frame, as currentValues. For non-discrete values (such as text and numeric values) we only need to set the textValue of the currentValue. Our object now looks like the following:

{
  "currentValues": [
    {
      "textValue": "John Doe",
      "discriminator": "Common"
    }
  ],
  "field": {
    "id": "TEXT_FIELD_ID",
    "fieldType": "TEXT"
  }
}

Let us similarly set the “Job Type” Field, a discrete-value Select Field. When we fetched the list of Fields above, each Field object had a key called currentValues. These are the value inputs to this Field. For the Select Field (and all other discrete field types) the values in this array are the selectable values for this Field. Those values for this situation are 'Account Executive', 'Developer', and 'Customer Success Manager'.

We will set the value for the Job Type Field to be Developer. Our JSON object should look like the following now:

{
  "currentValues": [
    {
      "id": "SELECTED_CURRENT_VALUE_ID",
      "textValue": "Developer",
      "discriminator": "Common"
    }
  ],
  "field": {
    "id": "SELECT_FIELD_ID",
    "fieldType": "SELECT"
  }
}

Let us put everything together! We should get the following JSON object that is ready to create a new Record with Field inputs.

{
  "step": {
    "id": "STEP_ID"
  },
  "currentValueMaps": [
    {
      "currentValues": [
        {
          "textValue": "John Doe",
          "discriminator": "Common"
        }
      ],
      "field": {
        "id": "TEXT_FIELD_ID",
        "fieldType": "TEXT"
      }
    },
    {
      "currentValues": [
        {
          "id": "SELECTED_CURRENT_VALUE_ID",
          "textValue": "Developer",
          "discriminator": "Common"
        }
      ],
      "field": {
        "id": "SELECT_FIELD_ID",
        "fieldType": "SELECT"
        }
    }
  ]
}

Now we can submit this Record with the following endpoint

Type: POST

https://your-company.logicgate.com/api/v1/records/public

Body

{
  "step": {
    "id": "STEP_ID"
  },
  "currentValueMaps": [
    {
      "currentValues": [
        {
          "textValue": "John Doe",
          "discriminator": "Common"
        }
      ],
      "field": {
        "id": "TEXT_FIELD_ID",
        "fieldType": "TEXT"
      }
    },
    {
      "currentValues": [
        {
          "id": "SELECTED_CURRENT_VALUE_ID",
          "textValue": "Developer",
          "discriminator": "Common"
        }
      ],
      "field": {
        "id": "SELECT_FIELD_ID",
        "fieldType": "SELECT"
        }
    }
  ]
}

From this we get a response object with information pertaining to the Record created and submission including the Record ID, the Record’s current Step and creation date. For those users with the access, a Record will now appear in the Home Screen ready for “Manager Meeting.”