Release Notes

Risk Cloud API: Grant Users Record Access

User Groups give you the ability to provide more detailed access to particular records in your application, similar to how permission sets allow you to restrict access on steps. User Group access will allow you to "tag" specific users or User Groups (pre-defined groups of users) to a record and restrict access to only those users and User Groups tagged.

This access can also be granted to individual users as well, where users can be granted access to a record individually. This appears in the Risk Cloud web application under Record Access > Users for User Group enabled records.

On the API level, this list of users is represented as a "Default User Group", a unique type of user group that is uniquely create for each individual record.

Additionally, the Risk Cloud API enables you to dynamically grant users access to records via default user groups.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Update Default User Group

The User Group API offers the following Update Default User Group endpoint, allowing you to set or remove users from a record's default user group.

Use Cases

Get Record ID

The record-id can be obtained from the Risk Cloud web application, emails, or via the Risk Cloud API.

Using the Risk Cloud application

The most straightforward way to find the record ID for record-id is to open the desired record in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/records/{record-id}

Using email

The Contextual Notifications feature offers the ability to set Custom Fields and System Fields in outbound emails. As a result, Record ID is a System Field that can be included in outbound emails from the Risk Cloud. This Record ID could in turn be parsed from the email for use in the following Post Record Comment API request.

Using the Risk Cloud API

Reference the article Risk Cloud API: Record Search to obtain record IDs via the Risk Cloud API.

Get Default User Group

When a record is created, a default User Group is added that is used for granting specific users access to the record. It's important to preserve this User Group when adding and removing additional User Groups.

In order to preserve this User Group when updating User Groups on a record, the default User Group is needed, which can be obtained from the following internal Risk Cloud API endpoint.

For record-id, use the record ID obtained in the step above.

Response

The default User Group ID can be located as the value of the id property in the response object.

{
  "id": "a1b2c3d4",
  "recordDefault": true,
  "title": " Default Group",
  "users": []
}

Get User IDs

The user IDs to add to the default user group can be obtained from either you Risk Cloud web app environment directly or from the Risk Cloud API.

Get User ID (Web App Environment)

A user ID can be located within you Risk Cloud web app environment in the following location:

  • Navigate to Admin > Users
  • Search for an select a user by clicking their email
  • The user ID can be found in under the User ID label

Get User ID (Risk Cloud API)

A user ID can be located via the User API, specifically in the id property of the returned user objects.

To obtain all users, reference the article Risk Cloud API: Viewing Users.

To obtain a user ID by a particular email, use the following internal User API endpoint.

Response

{
  "content": [
    {
      "id": "a1b2c3d4",
      "email": "[email protected]",
      // ... truncated ...
    }
  ],
  "pageable": {
    // ... truncated ...
  },
  // ... truncated ...
}

Update Default User Group

With the default User Group ID and the User IDs of users to add to the default user group, the users can be added via the following API endpoint and request body payload.

Additionally, if you wish to remove users from the default user group, you may omit the user objects from the request payload to have them removed.

Request Body

Use the record ID obtained in the first step for the record ID in the record query parameter.

Use the full payload from the Get Default User Group response, including id, name, users, and recordDefault  as the basis of the request body.

Modify the users array with user objects containing the user IDs of the users you wish to grant access to the record. The id, status of Active, and valueType of User should be present in the user objects.

{
    "recordDefault": true,
    "users": [
        {
            "status": "Active",
            "valueType": "User",
            "id": "{user-id}"
        }
    ],
    "id": "{user-group-id}",
    "title": " Default Group"
}

Response

A 200 response confirming that the Default User Group was updated. Upon refreshing the record in the Risk Cloud Web Application, the users are updated accordingly.

v2024.5.1 Release Notes

These are Release Notes for v2024.5.1 of Risk Cloud API v2, released on May 30th, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

Risk Cloud API v2 Resources

Featured Updates

What's Changed

Changed: field-type in query

  • Changed enum value:  TEXT_CALCULATION to TEXT_CONCATENATION

Changed response property: content[].type

  • Changed enum value:  TEXT_CALCULATION to TEXT_CONCATENATION

Changed response property: content[].fields[].type

  • Changed enum value:  TEXT_CALCULATION to TEXT_CONCATENATION

New Articles

No new articles.

v2024.5.0 Release Notes

These are Release Notes for v2024.5.0 of Risk Cloud API v2, released on May 15th, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

New Articles

No new articles.

v2024.4.2 Release Notes

These are Release Notes for v2024.4.2 of Risk Cloud API v2, released on May 1st, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

New Articles

No new articles.

v2024.4.1 Release Notes

These are Release Notes for v2024.4.1 of Risk Cloud API v2, released on April 17th, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

Risk Cloud API v2 Resources

Featured Updates

What's Changed

Changed: field-type in query

  • Added enum value:  TEXT_CALCULATION

Changed response property: content[].type

  • Added enum value:  TEXT_CALCULATION

Changed response property: content[].fields[].type

  • Added enum value:  TEXT_CALCULATION

New Articles

No new articles.

v2024.4.0 Release Notes

These are Release Notes for v2024.4.0 of Risk Cloud API v2, released on April 4th, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

Risk Cloud API v2 Resources

Featured Updates

Changed response

  • Added property type (string)

    • The type of workflow

    • Enum values:

      • WORKFLOW
      • JIRA_WORKFLOW
      • ANALYSIS_WORKFLOW

New Articles

No new articles.

v2024.3.1 Release Notes

These are Release Notes for v2024.3.1 of Risk Cloud API v2, released on March 20th, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

Risk Cloud API v2 Resources

Featured Updates

Specified auth, servers, and alphabetical order added to OpenAPI Specification.

New Articles

No new articles.

Risk Cloud API: Assign Records

Assigning users to records in the Risk Cloud can also be accomplished via the Risk Cloud API.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Assign Records Endpoint

The internal Record API offers the following Assign Records endpoint, allowing custom integrations to assign users to records via the Risk Cloud API.

The endpoint is available to all users with Application and Assign entitlements.

This endpoint has the following path parameters.

Path Property Description
record-id The unique ID of the record to assign the passed user to.

This endpoint has the following required request body properties.

{
  "id": "a1b2c3d4",
  "status": "Active"
}
Property Description
id The unique ID of the user to assign to the record.
status A required property to include alongside the request. A value of "Active" is expected.

Use Cases

Get Record ID

The record-id can be obtained from the Risk Cloud web application, emails, or via the Risk Cloud API.

Using the Risk Cloud application

The most straightforward way to find the record ID for record-id is to open the desired record in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/records/{record-id}

Using email

The Contextual Notifications feature offers the ability to set Custom Fields and System Fields in outbound emails. As a result, Record ID is a System Field that can be included in outbound emails from the Risk Cloud. This Record ID could in turn be parsed from the email for use in the following Post Record Comment API request.

Using the Risk Cloud API

Reference the article Risk Cloud API: Record Search to obtain record IDs via the Risk Cloud API.

Get User IDs

The user IDs to add to the newly created group can be obtained from either you Risk Cloud web app environment directly or from the Risk Cloud API.

Get User ID (Web App Environment)

A user ID can be located within you Risk Cloud web app environment in the following location:

  • Navigate to Admin > Users
  • Search for an select a user by clicking their email
  • The user ID can be found in under the User ID label

Get User ID (Risk Cloud API)

A user ID can be located via the User API, specifically in the id property of the returned user objects.

To obtain all users, reference the article Risk Cloud API: Viewing Users.

To obtain a user ID by a particular email, use the following internal User API endpoint.

Response

{
  "content": [
    {
      "id": "a1b2c3d4",
      "email": "[email protected]",
      // ... truncated ...
    }
  ],
  "pageable": {
    // ... truncated ...
  },
  // ... truncated ...
}

Assign Record

Once the user ID and record ID are obtained, the record can be assigned to the user via the Assign Records endpoint.

Request

Place the record ID in the URL path in the place of {record-id} and place the user ID in the request body in the place of {user-id}.

{
  "id": "{user-id}",
  "status": "Active"
}

Response

Expect a 200 response to confirm the assignment of the user on the record.

Risk Cloud API: View Record Audits

Record audits track record events such as when and how a record was created, moved, deleted, and more.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Retrieve Record Audits Endpoint

The Record Audits API offers the following Retrieve Record Audits endpoint which returns an iterable page of all record audits in a given timeframe.

The endpoint is available to all users with a build entitlement.

This endpoint has the following optional query parameters for additional filtering.

Query Parameter Description
minCreated A timestamp measured in milliseconds since the Unix epoch where, if provided, the response will only contain records audits that have been modified since the given timestamp.
maxCreated A timestamp measured in milliseconds since the Unix epoch where, if provided, the response will only contain records audits that have been modified since the given timestamp.
workflow The unique ID of a workflow where, if provided, the response will only contain record audits from the identified workflow.
page The zero-indexed page number (must not be less than 0, defaults to 0).
size The size of the page and maximum number of items to be returned (must not be less than 1, defaults to 20).

Use Cases

Get Workflow ID

To request all record audits in a workflow, use the workflow query parameter with the ID of the workflow.

The workflow ID can be obtained from either your Risk Cloud web app environment directly or from the Risk Cloud API.

Get Workflow ID (Web App Environment)

The workflow ID can be located within your Risk Cloud web app environment in the following location:

  • Navigate to Build > Applications
  • Search for and open the application containing the workflow
  • Open the edit gear icon (⚙) on the workflow to open the Workflow Editor
  • The workflow ID can be found under the Workflow ID label in the editor window

Get Workflow ID (Risk Cloud API)

The workflow ID can be located via the Retrieve Workflows endpoint, specifically in the id property of workflow objects returned in the content property of the response.

Retrieve Record Audits

Once the Workflow ID and timestamps are determined, the following request can be made to return all of the given workflow's record audits in the specified timeframe.

Response

The response contains all the record audits, along with additional contextual information for each audit such as the step, audit type, and user. The auditType property can have any of the following values.

CreatedAudit
CopiedAudit
LinkingAudit
LinkedAudit
UnlinkedAudit
DeletedAudit
MovedAudit
AssignedAudit
SecondaryAssignedAudit
SecondaryUnassignedAudit
PreservedAudit
UnassignedAudit

A sample output is shown below.

{
  "content": [
    {
      "id": "abcd1234",
      "active": true,
      "created": 1710426007818,
      "updated": null,
      "record": {
        "id": "efgh5678",
        "active": true,
        "created": 1710426006820,
        "updated": null,
        "state": "LIVE",
        "sequenceId": 22,
        "status": "IN_PROGRESS",
        "name": "",
        "viewableTitle": "",
        "initialStateEndStep": false,
        "workflowDueDate": null,
        "recordType": "RECORD",
        "isPublic": false
      },
      "source": {
        "id": "ijkl9012",
        "active": true,
        "created": 1696954275470,
        "updated": 1702410681371,
        "stepType": "ORIGIN",
        "name": "Default Origin",
        "priority": 1,
        "userGroupOperationType": "FULL_ACCESS",
        "xpos": 55,
        "ypos": 55,
        "isPublic": true,
        "commentsEnabled": true,
        "documentsEnabled": false,
        "externalUserMfaRequired": false,
        "uxriEnabled": true,
        "sla": {
          "enabled": false,
          "duration": 0
        },
        "workflow": {
          "id": "mnop3456",
          "active": true,
          "created": 1696954275551,
          "updated": 1713881453125,
          "name": "Item",
          "recordPrefix": "Item",
          "allowGroups": false,
          "requireGroups": false,
          "xpos": 147,
          "ypos": 98,
          "priority": 1,
          "sla": {
            "enabled": false,
            "duration": 0
          },
          "allowAec": false,
          "sequence": {
            "id": "qrst7890",
            "active": true,
            "created": 1696954275485,
            "updated": null
          },
          "application": null,
          "userGroups": [],
          "primaryField": null,
          "workflowType": "WORKFLOW"
        },
        "assignableUserType": "APP_AND_EXTERNAL_USERS",
        "end": false,
        "chain": false,
        "origin": true
      },
      "target": null,
      "user": {
        "status": "Active",
        "id": "uvwx1234",
        "active": true,
        "created": 1677696956370,
        "updated": 1713993694617,
        "email": "[email protected]",
        "company": null,
        "imageUrl": null,
        "imageS3Key": null,
        "tier": "SECONDARY",
        "pricingUserTier": "POWER",
        "first": "First",
        "last": "Last",
        "mfaEnabled": false,
        "mfaSetup": false,
        "autoprovisioned": true,
        "scimStatus": "Active",
        "lastLogin": null,
        "lastDeactivated": null,
        "name": "First Last",
        "locked": false,
        "superUser": false,
        "external": false,
        "disabled": false,
        "serviceAccount": false,
        "empty": false,
        "idOrTransientId": "uvwx1234",
        "transientIdOrId": "uvwx1234"
      },
      "sourceUser": null,
      "targetUser": {
        "status": "Active",
        "id": "uvwx1234",
        "active": true,
        "created": 1677696956370,
        "updated": 1713993694617,
        "email": "[email protected]",
        "company": null,
        "imageUrl": null,
        "imageS3Key": null,
        "tier": "SECONDARY",
        "pricingUserTier": "POWER",
        "first": "First",
        "last": "Last",
        "mfaEnabled": false,
        "mfaSetup": false,
        "autoprovisioned": true,
        "scimStatus": "Active",
        "lastLogin": null,
        "lastDeactivated": null,
        "name": "First Last",
        "locked": false,
        "superUser": false,
        "external": false,
        "disabled": false,
        "serviceAccount": false,
        "empty": false,
        "idOrTransientId": "uvwx1234",
        "transientIdOrId": "uvwx1234"
      },
      "fieldAudits": [],
      "dueDate": null,
      "stepDueDate": null,
      "auditType": "CreatedAudit"
    }
  ],
  "pageable": {
    "sort": {
      "empty": true,
      "sorted": false,
      "unsorted": true
    },
    "offset": 0,
    "pageSize": 20,
    "pageNumber": 0,
    "paged": true,
    "unpaged": false
  },
  "last": true,
  "totalElements": 1,
  "totalPages": 1,
  "size": 20,
  "number": 0,
  "sort": {
    "empty": true,
    "sorted": false,
    "unsorted": true
  },
  "numberOfElements": 1,
  "first": true,
  "empty": false
}

 

Risk Cloud API: Update Record User Groups

User Groups give you the ability to provide more detailed access to particular records in your application, similar to how permission sets allow you to restrict access on steps. User Group access will allow you to "tag" specific users or User Groups (pre-defined groups of users) to a record and restrict access to only those users and User Groups tagged. Additionally, the Risk Cloud API enables you to dynamically set User Groups on records.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Update Record User Group Endpoint

The Record API offers the following Update Record User Group endpoint, allowing you to set or remove User Groups on a record.

Use Cases

Get Record ID

The record-id can be obtained from the Risk Cloud web application, emails, or via the Risk Cloud API.

Using the Risk Cloud application

The most straightforward way to find the record ID for record-id is to open the desired record in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/records/{record-id}

Using email

The Contextual Notifications feature offers the ability to set Custom Fields and System Fields in outbound emails. As a result, Record ID is a System Field that can be included in outbound emails from the Risk Cloud. This Record ID could in turn be parsed from the email for use in the following Post Record Comment API request.

Using the Risk Cloud API

Reference the article Risk Cloud API: Record Search to obtain record IDs via the Risk Cloud API.

Get Default User Group

When a record is created, a default User Group is added that is used for granting specifc users access to the record. It's important to preserve this User Group when adding and removing additional User Groups.

In order to preserve this User Group when updating User Groups on a record, the default User Group is needed, which can be obtained from the following internal Risk Cloud API endpoint.

For record-id, use the record ID obtained in the step above.

Response

The default User Group ID can be located as the value of the id property in the response object.

{
  "id": "a1b2c3d4",
  "recordDefault": true,
  "title": " Default Group",
  "users": []
}

Get User Group IDs

The User Group IDs to add to a record can be obtained from either you Risk Cloud web app environment directly or from the Risk Cloud API.

Get User ID (Web App Environment)

A user ID can be located within you Risk Cloud web app environment in the following location:

  • Navigate to Build > Access
  • Select to Groups tab
  • Open the User Group editor by clicking the title of a User Group
  • The user group ID can be found in under the User Group ID label

Get User Group ID (Risk Cloud API)

If you create a new User Group via the instructions in Risk Cloud API: Create User Groups, the ID can be obtained from the id property of the returned user group object.

To obtain all user groups, you can request the following endpoint to return a paginated group of all user groups in the environment.

Response

{
  "content": [
    {
      "id": "a1b2c3d4",
      "title": "User Group Name",
      // ... truncated ...
    }
  ],
  "pageable": {
    // ... truncated ...
  },
  // ... truncated ...
}

Update Record User Group

With the default User Group ID and the User Group IDs of user groups to add to the record, the User Groups can be added via the following API endpoint and request body payload.

Additionally, if you wish to remove User Groups from a record, you may omit User Group IDs from the request payload to have them removed.

Request Body

Use the record ID obtained in the first step for the record ID in both the URL path and within the request body.

Use the User Group IDs for as the values of the id properties in each object of the userGroups array.

Ensure that you preserve the default User Group, by including its ID in all requests.

{
  "id": "{record-id}"
  "userGroups": [
    {
      "id": "{default-user-group-id}"
    },
    {
      "id": "{user-group-id-1}"
    },
    {
      "id": "{user-group-id-2}"
    }
  ]
}

Response

A 200 response confirming that the User Groups were updated. Upon refreshing the record in the Risk Cloud Web Application, the User Groups are updated accordingly.

Risk Cloud API: Create User Groups

User Groups give you the ability to provide more detailed access to particular records in your application, similar to how permission sets allow you to restrict access on steps. User Group access will allow you to "tag" specific users or User Groups (pre-defined groups of users) to a record and restrict access to only those users and User Groups tagged. Additionally, the Risk Cloud API enables you to dynamically create User Groups as a part of custom integrations.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Create User Group Endpoint

The internal User Group API offers the following Create User Group endpoint, allowing you to create User Groups from a title and the IDs of users to add to the group alone.

POST/api/v1/internal/userGroups

This endpoint returns a summary of the created group, including its name and ID.

Use Cases

Get User IDs

The user IDs to add to the newly created group can be obtained from either you Risk Cloud web app environment directly or from the Risk Cloud API.

Get User ID (Web App Environment)

A user ID can be located within you Risk Cloud web app environment in the following location:

  • Navigate to Admin > Users
  • Search for an select a user by clicking their email
  • The user ID can be found in under the User ID label

Get User ID (Risk Cloud API)

A user ID can be located via the User API, specifically in the id property of the returned user objects.

To obtain all users, reference the article Risk Cloud API: Viewing Users.

To obtain a user ID by a particular email, use the following internal User API endpoint.

Response

{
  "content": [
    {
      "id": "a1b2c3d4",
      "email": "[email protected]",
      // ... truncated ...
    }
  ],
  "pageable": {
    // ... truncated ...
  },
  // ... truncated ...
}

Create User Group

With the User IDs of the users to added to the new User Group, the User Group can be created via the following API endpoint and request body payload.

POST/api/v1/internal/userGroups

Request Body

Note that "status": "Active" is required to accompany all user IDs. Populate the User IDs obtained above into JSON objects and add them to the users array. Additionally set the title to the desired title of the user group, which is recommended to be unique.

{
    "users": [
        {
            "status": "Active",
            "id": "user-id-1"
        },
        {
            "status": "Active",
            "id": "user-id-2"
        }
    ],
    "title": "New User Group Title"
}

Response

The response contains the newly created User Group's ID, the title, and an indicator that it's not a record default User Group (which is expected).

{
    "id": "user-group-id",
    "recordDefault": false,
    "title": "New User Group Title"
}
Risk Cloud API: Export Attachments

Within Risk Cloud, you are able to add “Attachment” fields to your records enabling you to store files within Risk Cloud alongside your records. Once stored, these files can be exported via the Risk Cloud API.

Alternatively, to upload attachments to the Risk Cloud, refer to the article Risk Cloud API: Upload Attachments.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Export Attachment Endpoint

The Attachments API offers the following Export Attachment endpoint which returns a String of a URL to the image, based on the value ID of a value on a particular record’s attachment field.

This endpoint returns a String of the image URL in S3, meaning that the Accept header of the request should be either Accept: text/plain or Accept: */*.

Use Cases

Obtain Value ID

To obtain the value ID of a value on a particular record’s attachment field, use the Risk Cloud API: Record Search endpoint to view the fields and values of an attachment on a set of records, filterable by application, workflow, step, or a timestamp.

The value ID of an attachment field can be located in the response of the Record Search endpoint in the property content[].fields[].values[].id for fields where content[].fields[].values[].type is ATTACHMENT. In the below sample the value ID would be abcd1234 (ellipses are used to omit information for clarity).

Response

{
  ...
  "content": [
    {
      ...
      "fields": [
        {
          ...
          "values": [
            {
              "id": "abcd1234",
              "type": "ATTACHMENT",
              "textValue": "Evidence.pdf",
              "numericValue": 1.0,
              "object": "value"
            }
          ]
        }
      ]
    }
  ]
}

Obtain Attachment URL

Using the value ID obtained from the Record Search endpoint, make a request to the export attachment endpoint, which will return a String of a URL to the image.

Response

https://env-logic-gate.amazonaws.com/attachment/file_123456789.pdf

Get the Attachment

Finally, run a GET request directly on the returned URL to obtain the file. The file type for download can be inferred from the extension of the file name.

SFTP Integration
Risk Cloud API: Update Records

Updating records is an essential capability in the Risk Cloud, and with Risk Cloud’s Record API, you can update the values of Risk Cloud records via the Risk Cloud API.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Update Records Endpoint

The Record API offers the following Update Records endpoint which updates the values a given record.

The Update Records endpoint requires that the user whose API token is being used for the request is entitled with Write access to the given record.

This endpoint has the following request body properties.

[
  {
    "fieldId": "e5f6g7h8",
    "values": [
      "The string value of the field"
    ]
  }
]
Query Parameter Requiredness Description
fieldId optional The unique ID of the field to set the values to on the given record.
values optional An array of strings representing the text values to set to the fields of the corresponding field IDs on the given record.

Resources

Get Record ID

The record-id can be obtained from the Risk Cloud web application, emails, or via the Risk Cloud API.

Using the Risk Cloud application

The most straightforward way to find the record ID for record-id is to open the desired record in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/records/{record-id}

Expected Values for Field Types

Different field types expect different value formats. Below are the common field types and the expected string formats for the values array:

  • Text Fields:

    Example: "Sample text"

    Text fields expect a single string value.

  • User Fields:

    Example: "[email protected]"

    User fields expect the user's email address as a string.

  • Date Fields:

    Example: "2023-12-31"

    Date fields expect a date in the YYYY-MM-DD format.

  • Number Fields:

    Example: "12345.67"

    Number fields expect a numeric value as a string. This can include integers or decimals based on the field's configuration. For example, a field with the DECIMAL format will accept values like "12345.67".

  • Select + Multi Select Fields:

    Example: "Option1"

    Select and Multi Select fields expect the selected option as a string.

  • Checkbox Fields:

    Example: "true" or "false"

    Checkbox fields expect a boolean value as a string ("true" or "false").

  • Attachments:

    Attachments require separate addition via the endpoints highlighted in the Risk Cloud API: Upload Attachments.

    Example: Use the /api/v1/attachments endpoint to upload files before referencing them in the record update.

  • Fixed Date Calculation Fields:

    Example: "2024-06-15"

    Fixed date calculation fields expect a date string formatted as YYYY-MM-DD.

  • Calculation Fields:

    Example: "1.0"

    Calculation fields expect a numeric value as a string. These values are often the result of other field calculations and should adhere to the numeric format specified.

Using email

The Contextual Notifications feature offers the ability to set Custom Fields and System Fields in outbound emails. As a result, Record ID is a System Field that can be included in outbound emails from the Risk Cloud. This Record ID could in turn be parsed from the email for use in the following Post Record Comment API request.

Using the Risk Cloud API

Reference the article Risk Cloud API: Record Search to obtain record IDs via the Risk Cloud API.

Get Field ID

The field ID for the fieldId property can be obtained from either your Risk Cloud web app environment directly or from the Risk Cloud API.

Get Field ID (Web App Environment)

The field ID can be located within your Risk Cloud web app environment in the following location:

  • Navigate to Build > Applications
  • Search for and open the application containing the step
  • Open the workflow containing the step
  • Open the step
  • Open the field for editing
  • The field ID can be found in the Field ID section

Get Field ID (Risk Cloud API)

The field ID can be located via the Retrieve Fields endpoint, specifically in the id property of field objects returned in the content property of the response.

Risk Cloud API: Create Records

Creating records is an essential capability in the Risk Cloud, and with Risk Cloud’s Record API, you can create new Risk Cloud records, populate field data, schedule due dates, and set assignees via the Risk Cloud API.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Create Records Endpoint

The Record API offers the following Create Records endpoint which creates a record on a given step with configurable field values and assignees.

The Create Records endpoint requires that the user whose API token is being used for the request is entitled with Write access to create records on the given step.

POST/api/v1/records/steps

This endpoint has the following request body properties.

{
  "stepId": "a1b2c3d4",
  "assigneeEmailAddress": "[email protected]"
  "fields": [
    {
      "fieldId": "e5f6g7h8",
      "values": [
        "The string value of the field"
      ]
    }
  ]
}
Property Requiredness Description
stepId required The unique ID of the step to create a record on.
assigneeEmailAddress optional The email of a Risk Cloud user to assign the record to.
recordDueDate optional A generic date string for setting the due date of the created record (e.g 2024-04-05 12:00:00)
fields optional An array of field IDs and values to set to their corresponding fields on the created record.
fields > fieldId optional The unique ID of the field to set the values to on the created record.
fields > values optional An array of strings representing the text values to set to the fields of the corresponding field IDs on the created record.

Resources

Get Step ID

The step ID for the stepId property can be obtained from either your Risk Cloud web app environment directly or from the Risk Cloud API.

Get Step ID (Web App Environment)

The step ID can be located within your Risk Cloud web app environment in the following location:

  • Navigate to Build > Applications
  • Search for and open the application containing the step
  • Open the workflow containing the step
  • Open the step
  • The step ID can be found in the web browser URL bar https://environment.logicgate.com/build/steps/{step-id}

Get Step ID (Risk Cloud API)

The step ID can be located via the Retrieve Steps endpoint, specifically in the id property of step objects returned in the content property of the response.

Get Field ID

The field ID for the fieldId property can be obtained from either your Risk Cloud web app environment directly or from the Risk Cloud API.

Get Field ID (Web App Environment)

The field ID can be located within your Risk Cloud web app environment in the following location:

  • Navigate to Build > Applications
  • Search for and open the application containing the step
  • Open the workflow containing the step
  • Open the step
  • Open the field for editing
  • The field ID can be found in the Field ID section

Get Field ID (Risk Cloud API)

The field ID can be located via the Retrieve Fields endpoint, specifically in the id property of field objects returned in the content property of the response.

Risk Cloud API: View Field Audits
A guide to the API endpoints that allow you to track field audits

This article details the endpoints for obtaining and exporting field audits. The results from these endpoints are only accessible to access keys belonging to users with the Admin > All module entitlement and in some cases if you have access to the required entity.

  1. Field Audit
  2. Field Audit Export

Field Audit

Find All Field Audit By Record Id

Retrieve all field audits based on record id.

Required Path Parameter Description
recordId The unique ID of a record where, if provided, the response will only contain field audits from the identified record.

This endpoint has the following optional query parameters for additional filtering.

Query Parameter Description
page The zero-indexed page number (must not be less than 0, defaults to 0).
size The size of the page and maximum number of items to be returned (must not be less than 1, defaults to 20).

Result

A paginated response of all field audit results related to the record, containing the following info:

Result Field Description
id The unique ID of the field audit.

fieldId The unique ID of the field audit.
fieldLabel
The label of the field, which is presented to end users for the field.

fieldName
The name of the field, which is used to identify the field in the Build and Reports modules.

created
The created date of the field audit in epoch time in milliseconds ex. 1712168746685

recordId The unique ID of the record.
userName The name of the creator.
userEmail The email of the creator.
fieldValues The list of field values.
executorId The unique ID of the executor.
executorName
The name of the executor.

executorType
The type of executor ex. USER_ACTION

defaultValue
Is this value the default field value or not ex. false

Get Most Recent Field Audit By Value Map

Retrieve the most recent field audit by value map.

Required Path Parameter Description
valueMapId The unique ID of a value map where, if provided, the response will only contain field audits from the identified value map.

Result

A simplified field audit object response of the most recent field audit related to the value map, containing the following info:

Result Field Description
id The unique ID of the field audit.

fieldId The unique ID of the field.
fieldLabel
The label of the field, which is presented to end users for the field.

fieldName
The name of the field, which is used to identify the field in the Build and Reports modules.

fieldType The type of field ex. Common
created
The created date of the field audit in epoch time in milliseconds ex. 1712168746685

recordId The unique ID of the record.
userId The unique ID of the user.
userName The name of the user.
userEmail The email of the user.
fieldValues The list of field values.

Field Audit Export

Export All Field Audit By Record Id

Export all field audits based on record id. Optionally, results can be ordered by pageable parameters and be within the specified min created date and max created date range.

Required Path Parameter Description
recordId The unique ID of a record where, if provided, the response will only contain field audits from the identified record.

This endpoint has the following optional query parameters for additional filtering.

Query Parameter Description
page The zero-indexed page number (must not be less than 0, defaults to 0).
size The size of the page and maximum number of items to be returned (must not be less than 1, defaults to 20).
minCreated The min created date in epoch time in milliseconds ex. oldest date lower bound 1711997926000

maxCreated The max created date in epoch time in milliseconds ex. newest date upper bound 1712170726000

Result

A view containing all field audit results related to the record. This response can be saved as a csv, xlsx, txt, or other appropriate formats for later viewing.

Ex.

Created Date,Field Id,Field Label,Field Name,Field Type,Field Values,Record Id,User Email,User Name,Executor ID,Executor Name,Execution Type,Is Default Value
2024-04-03 18:25:53,LkTGrIvx,Select the date by which the record must be completed.,Due Date,DueDateFieldTransient,[1717261200000],bnWzIMRy,[email protected],LogicGate Administrator,gMLjJcmK,LogicGate Administrator,USER_ACTION,false
2024-04-03 18:25:47,3PvdkyZM,t,t,InfiniteTextField,[new 11],bnWzIMRy,[email protected],LogicGate Administrator,gMLjJcmK,LogicGate Administrator,USER_ACTION,false
Everbridge integration
v2024.3.0 Release Notes

These are Release Notes for v2024.3.0 of Risk Cloud API v2, released on March 6th, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

Risk Cloud API v2 Resources

Featured Updates

Specified auth, servers, and alphabetical order added to OpenAPI Specification.

New Articles

No new articles.

v2024.2.1 Release Notes

These are Release Notes for v2024.2.1 of Risk Cloud API v2, released on February 21st, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

New Articles

v2024.2.0 Release Notes

These are Release Notes for v2024.2.0 of Risk Cloud API v2, released on February 8th, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

New Articles

monday.com integration
v2024.1.1 Release Notes

These are Release Notes for v2024.1.1 of Risk Cloud API v2, released on January 24th, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

New Articles

Snowflake Integration
Risk Cloud API: Moving Records

In the Risk Cloud web application, records are moved to their next step by submitting them. This behavior can also be performed via the Risk Cloud API for custom integrations.

In this article, we will walk through the steps necessary for moving a record to another step via the Risk Cloud API.

  1. Obtain the record-id of the record to move
  2. Obtain the step-id of the step to move to
  3. Move the record to the desired step

Authentication

Obtain your API Access Token to get started, additionally, this endpoint is limited to the Admin role, so ensure that the creator of the API Key used has the Admin role entitlement.

Step 1: Obtain the record-id

The record-id can be obtained from the Risk Cloud web application, emails, or via the Risk Cloud API. If you already know your record-id you may continue to Step 2: Obtain the step-id

Using the Risk Cloud application

The most straightforward way to find the record ID for record-id is to open the desired record in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/records/{record-id}

Using email

The Contextual Notifications feature offers the ability to set Custom Fields and System Fields in outbound emails. As a result, Record ID is a System Field that can be included in outbound emails from the Risk Cloud. This Record ID could in turn be parsed from the email for use in the following Post Record Comment API request.

Using the Risk Cloud API

Reference the article Risk Cloud API: Record Search to obtain record IDs via the Risk Cloud API.

2. Obtain the step-id

Using the Risk Cloud application

Open the desired step from the builder page located at Build > Applications > (Select a Step) in the Risk Cloud web application, then take the ID from the end of the URL. Ensure that this is a valid step on the same workflow that the record represents.

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

Using the Risk Cloud API

The Steps API, provides a paginated means of iterating through all resources entitled to the API user.

To search for an application, use the Retrieve Steps endpoint.

3. Moving Records

In this step, we will use the record-id and step-id found in the previous steps to move the record.

Path Parameter Description
record-id The unique ID of the record to move
step-id The unique ID of the step to move the record to
Sample Request Body

The request body can be empty for this PUTrequest.


Response

A 200 response with JSON confirming the the structure and status of the moved record.

{
  "id": "a1b2c3d4",
  "active": true,
  "created": 1706651975544,
  "updated": null,
  "sequenceId": 1,
  "status": "COMPLETE",
  "name": "A-1",
  "viewableTitle": "A-1",
  "initialStateEndStep": false,
  "workflowDueDate": null,
  "recordType": "RECORD",
  "isPublic": false
}

 

v2024.1.0 Release Notes

These are Release Notes for v2024.1.0 of Risk Cloud API v2, released on January 10th, 2024.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

New Articles

Risk Cloud API: Post Record Comments

Creating comments via the Risk Cloud API allows custom integrations to post contextual updates to records to keep related information from external sources centralized in the Risk Cloud.

In this article, we will walk through the steps necessary for posting a comment to a record via the Risk Cloud API.

  1. Obtain the record-id of the record that you would like to post the comment to
  2. Post Record Comment
POST/api/v1/comments

Authentication

Obtain your API Access Token to get started.

Comments Feature

Ensure that the Comments feature is enabled for your step. To enable comments on a record step:

  • Navigate to the step via Build > Applications > Open an application > Open a step in a workflow > Configure Step
  • Check the box "Enable Comments"

Step 1: Obtain the record-id

The record-id can be obtained from the Risk Cloud web application, emails, or via the Risk Cloud API. If you already know your record-id you may continue to Step 2: Post Record Comment

Using the Risk Cloud application

The most straightforward way to find the record ID for record-id is to open the desired record in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/records/{record-id}

Using email

The Contextual Notifications feature offers the ability to set Custom Fields and System Fields in outbound emails. As a result, Record ID is a System Field that can be included in outbound emails from the Risk Cloud. This Record ID could in turn be parsed from the email for use in the following Post Record Comment API request.

Using the Risk Cloud API

Reference the article Risk Cloud API: Record Search to obtain record IDs via the Risk Cloud API.

2. Post Record Comment

In this step, we will use the record-id found in the previous step to create a comment. Additionally you will require the text of the post in Rich Text HTML format.

POST/api/v1/comments
Sample Request Body
{ 
  "record": {
    "id": "record-id"
  },
  "content": "<p>Your comment here.</p>"
}
Response

A 200 response with JSON confirming the structure of the new comment.

Risk Cloud API: Export Table Report

Exporting Table Report data via the Risk Cloud API in a CSV or XLSX is a common use case, as it provides a means of exporting record data in the same format as it would be displayed within a table report in the Risk Cloud web application.

In this article, we will walk through the steps necessary for obtaining a table report, and its records, as a CSV or XLSX data export via the Risk Cloud API.

  1. Obtain the table-report-id that you would like applied as the columns for the CSV or XLSX export
  2. Retrieve Table Report Export
POST/api/v1/records/export/csv

Authentication

Obtain your API Access Token to get started, and for more on exporting record data and exporting table reports, refer to our Help Center articles Export Record Data and Export Data from Table Reports.

Step 1: Obtain the table-report-id

The table-report-id can be obtained from the Risk Cloud web application or via the Risk Cloud API. If you already know your table-report-id you may continue to Step 2: Retrieve Table Report Export

Using the Risk Cloud application

The most straightforward way to find the table report ID for table-report-id is to open the desired table report from the reporting page located at Reports > Table Reports in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/report/tableReport/{table-report-id}

Using the Risk Cloud API

The Retrieve Table Reports endpoint returns all table reports that the user is entitled to by workflow. If no table reports are returned, check the permissions of the requesting API user to ensure that proper permissions are granted.

This endpoint has the following optional query parameters for additional filtering.

Query Parameter Description
applicationId The unique ID of an application where, if provided, the response will only contain table reports from the identified application.
query A query string where, if provided, the response will be filtered to only contain table reports that have a title, application name, or workflow name that have a case-insensitive match with the given query string
page The zero-indexed page number (must not be less than 0, defaults to 0).
size The size of the page and maximum number of items to be returned (must not be less than 1, defaults to 20).
Response Body

This will return a paginated response of table report objects, each looking like the following. For more information on iterating paginated responses, reference the article Risk Cloud API: Pagination. Parse the table report objects by properties like workflowName, applicationName, or title until you have located the intended table report.

{
  "id": "a1b2c3d4",
  "title": "My Table Report",
  "created": 1685482001992,
  "updated": 1685482002192,
  "modified": 1685482002192,
  "defaultLayout": false,
  "workflowId": "e5f6g7h8",
  "workflowName": "My Workflow",
  "applicationId": "i9j0k1l2",
  "applicationName": "My Application",
  "applicationLive": true,
  "applicationPermissionsEnabled": false,
  "applicationColor": "#49b800",
  "applicationIcon": "fas__fa-cubes",
  "totalLayoutFields": 2,
  "homeScreenPresent": false,
  "creatorEmail": "[email protected]",
  "creatorName": "Jane Doe",
  "totalReportFilters": 0,
  "totalJoins": 0
}

2. Retrieve Table Report Export

In this step, we will use the table-report-id found in the previous step to export the table report, and its record data, as a CSV or XLSX. The csv in the path may be swapped for xlsx to switch the returned format of the spreadsheet.

POST/api/v1/records/export/csv
Sample Request Body
{ 
  "tableReport": "table-report-id"
}
Response

A CSV or XLSX of the table report record data, with field columns reflecting the table report.

Mandiant Integration
Rapid7 Integration
Whistic Integration
Workday TPRM Integration
Microsoft Power BI Native Integration
Microsoft 365 Native Integration
v2023.12.0 Release Notes

These are Release Notes for v2023.12.0 of Risk Cloud API v2, released on December 14th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

Risk Cloud API: Link Records

Linking records is a powerful offering provided by the Risk Cloud API, enabling users to build out integrations to automate the internal connections of their Risk Cloud data.

Obtain your API Access Token to get started, and for more on record links and workflow maps, refer to our Help Center article Connecting Workflows Together.

Link Records Endpoint

The Records API offers the following Link Records endpoint which allows API users to link records to other records of their respective workflow mappings. Additionally, the endpoint provides the flexibility to either preserve existing linkages or remove them all via the strategy query parameter.

The Link Records endpoint is only available to accounts with Admin level privileges. If you would like to link records via the Risk Cloud API with an API token from a non-Admin account, reference the Link Parent and Child Endpoints section below.

Link Records

POST/api/v1/records/link-by-identifiers

This endpoint has the following query parameter, which can be left empty for the default use case.

Query Parameter Description
strategy Determines the linking strategy of the records:

  • RESPECT_MAPPING (default) - checks to ensure that every record involved has the capacity to be linked
  • REMOVE_EXISTING - removes all relationships between involved records prior to linking

Request Body

Link records by ID

The request body of the Link Records endpoint consists of an array of objects containing recordId properties to set the record IDs of the parent and child records to be linked.

{
  [
    {
      "recordId": "{parent-record-id}"
    },
    {
      "recordId": "{child-record-id}"
    }
  ]
}
Link records by name

The request body of the Link Records endpoint consists of an array of objects containing recordName properties to set the record IDs of the parent and child records to be linked.

{
  [
    {
      "recordName": "{parent-record-name}"
    },
    {
      "recordName": "{child-record-name}"
    }
  ]
}
Link records by primary field

The request body of the Link Records endpoint consists of an array of objects containing primaryFieldValue and workflowId properties to set the record IDs of the parent and child records to be linked.

{
  [
    {
      "primaryFieldValue": "{parent-primary-field-value-string}",
      "workflowId": "{parent-workflow-id}"
    },
    {
      "primaryFieldValue": "{child-primary-field-value-string}",
      "workflowId": "{child-workflow-id}"
    }
  ]
}

Response

The response contains an empty 200 OK if the record linkage was successful.

Link Parent and Child Endpoints

For non-Admin users, linking parent and child records can also be accomplished via the Risk Cloud API with the following endpoints.

POST/api/v1/records/{child-record-id}/parent?layout={layout-id}
POST/api/v1/records/{parent-record-id}/child?layout={layout-id}

Use Case

Get Default Layout

The Link Parent and Child endpoint each require the ID of a layout object. For the purposes of linking records, the default layout is recommended. The ID of the default layout in your Risk Cloud environment can be obtained from the following internal endpoint. The layout ID can be located in the id property of the response.

Response

{
  "id": "a1b2c3d4",
  "active": true,
  "created": 1512570904482,
  "updated": 1713208740015,
  "title": "Default",
  "defaultLayout": false,
  "workflow": null,
  "layoutType": "Default"
}

Link Parent or Child

Parent or child records reflect the directionality of their corresponding linked workflows. The parent-child relationship of the linked workflows may already be known, however, if it is not known, test each endpoint call with records from each workflow to confirm which one succeeds.

POST/api/v1/records/{child-record-id}/parent?layout={layout-id}
POST/api/v1/records/{parent-record-id}/child?layout={layout-id}

Request

Each of these endpoints take a payload of an ID of the record to link as either a parent or child of the record specified by the child-record-id or parent-record-id in the URL path. Additionally use the layout-id obtained from the steps above.

{
  "id": "a1b2c3d4"
}

Response

200 response and JSON payload confirming the linkage.

New Year, New Developer Relations Resources: 2023 in Review

The year 2023 marked the official launch of LogicGate’s Developer Relations program! With this program, we’ve adopted an API-First approach and have released a number new API endpoints, resources, and tools throughout the year, with some highlights below:

  • Risk Cloud API v2 - our latest API endpoints, with concise and highly documented details, tailor made for developers
  • Risk Cloud API Postman Collection - our Postman collection for seamlessly getting started with testing and building out your API integration
  • Public OpenAPI Specification - our OpenAPI specification for empowering full flexibility with our API, updated per-release
  • Developer Portal Redesign - rebranding the hub for our developer community for searching release notes, API documentation, and guides
  • API Release Notes - per-release notes on API changes and updates
  • Usage Guides - our API usage guides for covering common use cases and recipes
  • Developer Relations Contact Email ([email protected]) - our Developer Relations contact email for any questions or ideas
  • 1:1 Developer Meetings - one-on-one Developer Relations sync meetings to ideate and brainstorm custom integration use cases directly with our customers

In the spirit of the new year, here's a look back on some interesting new metrics gathered from the first year of our Developer Relations program!

Top Requested Endpoints (Overall)

  1. POST /api/v1/valueMaps
  2. GET /api/v1/roles/user/{user-id}
  3. GET /api/v1/records/{record-id}
  4. GET /api/v1/currentValues/users
  5. GET /api/v1/records

Top Requested Endpoints (v2)

  1. GET /api/v2/records
  2. GET /api/v2/fields
  3. GET /api/v2/workflow-maps/{id}
  4. GET /api/v2/workflows
  5. GET /api/v2/steps/{id}

Top User Agents (Programming Languages)

  1. Java
  2. Python
  3. cURL
  4. .NET
  5. Go

Top API Resources by Request

  1. Records (39.8%)
  2. Current Values (18.2%)
  3. Value Maps (18.1%)
  4. Applications (9.3%)
  5. Fields (6.6%)

1:1 Developer Meetings

We’ve hosted 22 one-on-one Developer Relations meetings to ideate and brainstorm custom integration use cases directly with our customers.

What’s next in 2024?

  • Developer Relations Newsletter - subscribe and receive the latest API updates right to your email (sign up for the list here)
  • Expanded Risk Cloud API v2 endpoints (Linked Records, Record Creation, Users, etc)

v2023.11.0 Release Notes

These are Release Notes for v2023.11.0 of Risk Cloud API v2, released on November 16th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

v2023.10.2 Release Notes

These are Release Notes for v2023.10.2 of Risk Cloud API v2, released on November 6th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

Workday Employee Information Risk Cloud Connector
Formstack Go Risk Cloud Connector
Black Kite Compliance Ratings Risk Cloud Connector
Risk Cloud API: Export Step Permission Sets

Step Permission Sets are an access type that encompass a collection of steps within an application. As an application builder, step permission sets can be created to correspond to different combinations of steps in your application.

With the Risk Cloud API, step permission set information can be exported along with information on what users are in each step permission set.

Obtain your API Access Token to get started, and for more on step permission sets, refer to our Help Center article Creating Permission Sets for your Applications.

Retrieve Step Permission Sets Endpoints

The Step Permission Sets API offers the following Retrieve Step Permission Sets endpoints which allow API users to either return a list of all step permission sets in the Risk Cloud environment or return detailed information about a particular step permission set such as users and permissions.

Retrieve Step Permission Sets

This endpoint has the following query parameters, which can be left empty for the default use case.

Query Parameter Description
application-id The unique ID of an application where, if provided, the response will only contain step permission sets from the identified application.
query A query parameter flag where, if provided, the response will only contain step permission sets that match the name of either the application, step permission set, or both, depending on the search type specified in search-type.
search-type A specifier what property name the query applies to. Values include: APPLICATION, PERMISSIONSET, and BOTH

Response

The response contains a JSON array of all step permission sets in the environment. A sample response is shown below.

{
  "content": [
    {
      "id": "a1b2c3d4",
      "name": "Manage Documents",
      "defaultStepPermissionSetForNewUsers": false,
      "stepCount": 2,
      "userCount": 4,
      "roleCount": 3,
      "application": {
        "id": "e5f6g7h8",
        "name": "Cyber Risk Management Application",
        "color": "#00a3de",
        "icon": "fas__fa-cubes",
        "hasDashboard": null,
        "type": null,
        "live": false,
        "permissionsEnabled": false,
        "workflows": []
      }
    }
  ],
  "pageable": {
    "sort": {
      "empty": true,
      "sorted": false,
      "unsorted": true
    },
    "offset": 0,
    "pageNumber": 0,
    "pageSize": 20,
    "unpaged": false,
    "paged": true
  },
  "totalElements": 1,
  "totalPages": 1,
  "last": false,
  "size": 20,
  "number": 0,
  "sort": {
    "empty": true,
    "sorted": false,
    "unsorted": true
  },
  "numberOfElements": 1,
  "first": true,
  "empty": false
}

Retrieve a Step Permission Set

This endpoint has the following required path parameter.

Path Parameter Description
{step-permission-set-id} The unique ID of the step permission set to return.

Response

The response contains detailed information on the requested step permission set, including information on associated users and permissions. A sample response is shown below.

{
  "id": "a1b2c3d4",
  "active": true,
  "created": 1642809081423,
  "updated": 1652291058707,
  "name": "Manage Documents",
  "locked": false,
  "defaultStepPermissionSetForNewUsers": false,
  "permissions": [
    {
      "created": null,
      "updated": null,
      "end": {
        "id": "e5f6g7h8",
        "active": true,
        "created": 1642809081185,
        "updated": 1699026534455,
        "stepType": "END",
        "name": "Document Repository",
        "priority": 3,
        "userGroupOperationType": "FULL_ACCESS",
        "xpos": 375,
        "ypos": 55,
        "commentsEnabled": true,
        "documentsEnabled": false,
        "externalUserMfaRequired": false,
        "uxriEnabled": true,
        "workflow": {
          "id": "i9j0k1l2",
          "active": true,
          "created": 1642809081185,
          "updated": 1663870139710,
          "application": null
        },
        "assignableUserType": "APP_AND_EXTERNAL_USERS",
        "end": true,
        "chain": false,
        "origin": false
      },
      "operationType": "EDIT",
      "permissionSetId": null,
      "step": {
        "id": "e5f6g7h8",
        "active": true,
        "created": 1642809081185,
        "updated": 1699026534455,
        "stepType": "END",
        "name": "Document Repository",
        "priority": 3,
        "userGroupOperationType": "FULL_ACCESS",
        "xpos": 375,
        "ypos": 55,
        "commentsEnabled": true,
        "documentsEnabled": false,
        "externalUserMfaRequired": false,
        "uxriEnabled": true,
        "workflow": {
          "id": "i9j0k1l2",
          "active": true,
          "created": 1642809081185,
          "updated": 1663870139710,
          "application": null
        },
        "assignableUserType": "APP_AND_EXTERNAL_USERS",
        "end": true,
        "chain": false,
        "origin": false
      },
      "type": "STEP_PERMISSION",
      "endId": "e5f6g7h8",
      "startId": null
    }
  ],
  "users": [
    {
      "status": "Active",
      "id": "m3n4o5p6",
      "active": true,
      "created": 1574197320453,
      "updated": 1677532088796,
      "email": "[email protected]",
      "imageS3Key": null,
      "first": "Jane",
      "last": "Doe",
      "stepPermissionSetIds": [
        "a1b2c3d4"
      ],
      "roleIds": [],
      "empty": false,
      "idOrTransientId": "m3n4o5p6",
      "transientIdOrId": "m3n4o5p6"
    }
  ],
  "application": {
    "id": "q7r8s9t0",
    "active": true,
    "created": 1642809081193,
    "updated": 1699026534455,
    "name": "Cyber Risk Management Application",
    "createdBy": null,
    "color": "#00a3de",
    "icon": "fas__fa-cubes",
    "type": "CONTROLS_COMPLIANCE",
    "sourceApplicationId": null,
    "sourceEnvironment": null,
    "permissionsEnabled": false,
    "imported": true,
    "copied": false,
    "live": false,
    "calcsV2": true,
    "currency": "USD",
    "uxriEnabled": true
  },
  "applicationId": "q7r8s9t0",
  "userIds": [
    "m3n4o5p6"
  ]
}

 

Risk Cloud API: Export User Groups

User Groups are pre-defined groups of users that allow you to provide more detailed access to specific records in your application workflows.

With the Risk Cloud API, user group information can be exported for identifying what users are in each user group.

Obtain your API Access Token to get started, and for more on user groups, refer to our Help Center article Getting Started with User Groups.

Retrieve User Groups Endpoint

The User Groups API offers the following Retrieve User Groups endpoint which return a list of all user groups in the Risk Cloud environment.

Retrieve User Groups

This endpoint has the following required query parameters.

Query Parameter Description
default Whether default user groups or non-default user groups are to be returned which will always be false for this use case.
results A necessary query parameter flag for this endpoint which will always be false for this use case.

Response

The response contains a JSON array of all user groups sets in the environment, including user information. A sample response in shown below.

[
     {
        "id": "a1b2c3d4",
        "recordDefault": false,
        "title": "Policy Team",
        "users": [
            {
                "status": "Active",
                "id": "e5f6g7h8",
                "email": "[email protected]",
                "company": null,
                "imageUrl": "/api/v1/users/e5f6g7h8/images?v=upload_file_e5f6g7h8.jpg",
                "imageS3Key": "profile-picture/upload_file_e5f6g7h8.jpg",
                "status": "Active",
                "tier": "SECONDARY",
                "pricingUserTier": "POWER",
                "mfaEnabled": false,
                "mfaSetup": false,
                "autoprovisioned": false,
                "scimStatus": null,
                "lastLogin": null,
                "lastDeactivated": null,
                "name": "Jane Doe",
                "locked": false,
                "external": false,
                "disabled": false,
                "serviceAccount": false,
                "stepPermissionSetIds": [],
                "roleIds": [],
                "superUser": false,
                "empty": false,
                "idOrTransientId": "e5f6g7h8",
                "transientIdOrId": "e5f6g7h8"
            }
        ]
    }
]
Risk Cloud API: Export Roles

Roles correspond to functions within your organization's hierarchy (e.g. Compliance, Audit, IT Operations, etc.) and can contain permission sets and entitlements to define the access of the members of the role.

With the Risk Cloud API, role information including associated entitlements, permission sets, and users can be exported for tracking access or aligning your role structure with external systems.

Obtain your API Access Token to get started, and for more on roles, refer to our Help Center articles Creating Roles and Modular Entitlements for Roles.

Retrieve Roles Endpoint

The Roles API offers the following Retrieve Roles endpoint which return a list of all roles in the Risk Cloud environment.

Retrieve Roles

Response

The response contains a JSON array of all roles in the environment, including information on associated permission sets, entitlements, and users. A sample response in shown below.

{
  "id": "y6z7a8b9",
  "active": true,
  "created": 1678070118163,
  "updated": null,
  "name": "Build Access",
  "locked": false,
  "superAdmin": false,
  "defaultRoleForNewUsers": false,
  "autoprovisioned": false,
  "externalId": null,
  "stepPermissionSets": [
    {
      "id": "u2v3w4x5",
      "active": true,
      "created": 1678069970011,
      "updated": null,
      "name": "[Quantify] Analysis Reviewer",
      "locked": false,
      "defaultStepPermissionSetForNewUsers": false,
      "permissions": [],
      "users": [],
      "application": null,
      "applicationId": null,
      "userIds": []
    }
  ],
  "moduleEntitlements": [
    {
      "type": "MODULE",
      "created": 1678070118301,
      "updated": null,
      "end": {
        "id": "q8r9s0t1",
        "active": true,
        "created": 1517517792850,
        "updated": 1591623597460,
        "value": "A_BUILD",
        "onlyUse": true,
        "tab": "Application",
        "name": "Build"
      },
      "operationType": "EDIT",
      "module": {
        "id": "q8r9s0t1",
        "active": true,
        "created": 1517517792850,
        "updated": 1591623597460,
        "value": "A_BUILD",
        "onlyUse": true,
        "tab": "Application",
        "name": "Build"
      },
      "type": "MODULE",
      "endId": "q8r9s0t1",
      "startId": null
    }
  ],
  "users": [
    {
      "status": "Active",
      "id": "m4n5o6p7",
      "active": true,
      "created": 1599984017146,
      "updated": 1699904531204,
      "email": "[email protected]",
      "imageS3Key": null,
      "first": "Jane",
      "last": "Doe",
      "roleIds": [
        "a1b2c3d4",
        "e5f7g8h9",
        "i0j1k2l3"
      ],
      "stepPermissionSetIds": [],
      "empty": false,
      "idOrTransientId": "m4n5o6p7",
      "transientIdOrId": "m4n5o6p7"
    }
  ],
  "moduleCount": 14,
  "userCount": 1
}

 

Risk Cloud API: Linked Record Search

Whether it's for parent records or a child records, the Risk Cloud’s Record API empowers integration use cases to automate and process linked records.

Obtain your API Access Token to get started.

Retrieve Linked Records Endpoints

The Record API offers the following Retrieve Linked Records endpoints which return lists of all records that are either the parent or child records of a given source record.

Retrieve Child Records

This endpoint has the following required query parameters for filtering.

Query Parameter Description
parent The unique ID of the parent record to seek linked child records from
sourceWorkflow The unique ID of the workflow that the parent record is from

workflow The unique ID of the linked workflow that the linked child records are from
mapped Whether the returned records are linked to the parent (should be set to true for this use case)

Retrieve Parent Records

This endpoint has the following required query parameters for filtering.

Query Parameter Description
child The unique ID of the child record to seek linked parent records from
sourceWorkflow The unique ID of the workflow that the child record is from

workflow The unique ID of the linked workflow that the linked child records are from
mapped Whether the returned records are linked to the child (should be set to true for this use case)

 

Risk Cloud API: Record Search

From field values to due dates, the Risk Cloud’s Record API enables you to export and process your record data via the Risk Cloud API.

Additionally, API users can filter records by application, workflow, step, and even when records were last updated.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Retrieve Records Endpoint

The Record API offers the following Retrieve Records endpoint which returns an iterable page of all records that the current user has Read or Write access to.

The Records API is available to all authenticated users, however it only returns records that are entitled to be read by the user whose API token is being used for the request.

Entitlement is based on any of the following being true:

  • The user has a read or write step permission set entitlement to the step
  • The user is assigned to the record

To retrieve all record data from a particular workflow or application, ensure that the user whose API token is being used for the API integration has permission set entitlements in place to read or write every step of the workflow or application.

This endpoint has the following optional query parameters for additional filtering.

Query Parameter Description
application-id The unique ID of an application where, if provided, the response will only contain records from the identified application.
workflow-id The unique ID of a workflow where, if provided, the response will only contain records from the identified workflow.
step-id The unique ID of a step where, if provided, the response will only contain records on the identified step.
updated-min A timestamp measured in milliseconds since the Unix epoch where, if provided, the response will only contain records that have been modified since the given timestamp.
page The zero-indexed page number (must not be less than 0, defaults to 0).
size The size of the page and maximum number of items to be returned (must not be less than 1, defaults to 20).

Use Cases

Records by Application

To request all records in an application, use the application-id query parameter with the ID of the application.

The application ID can be obtained from either your Risk Cloud web app environment directly or from the Risk Cloud API.

Get Application ID (Web App Environment)

The application ID can be located within your Risk Cloud web app environment in the following location:

  • Navigate to Build > Applications
  • Search for and open the application
  • The application ID can be found in the web browser URL bar https://environment.logicgate.com/build/applications/{application-id}

Get Application ID (Risk Cloud API)

The application ID can be located via the Retrieve Applications endpoint, specifically in the id property of application objects returned in the content property of the response.

Records by Workflow

To request all records in a workflow, use the workflow-id query parameter with the ID of the workflow.

The workflow ID can be obtained from either your Risk Cloud web app environment directly or from the Risk Cloud API.

Get Workflow ID (Web App Environment)

The workflow ID can be located within your Risk Cloud web app environment in the following location:

  • Navigate to Build > Applications
  • Search for and open the application containing the workflow
  • Open the edit gear icon (⚙) on the workflow to open the Workflow Editor
  • The workflow ID can be found under the Workflow ID label in the editor window

Get Workflow ID (Risk Cloud API)

The workflow ID can be located via the Retrieve Workflows endpoint, specifically in the id property of workflow objects returned in the content property of the response.

Records by Step

To request all records on a step, use the step-id query parameter with the ID of the step.

The step ID can be obtained from either your Risk Cloud web app environment directly or from the Risk Cloud API.

Get Step ID (Web App Environment)

The step ID can be located within your Risk Cloud web app environment in the following location:

  • Navigate to Build > Applications
  • Search for and open the application containing the step
  • Open the workflow containing the step
  • The step ID can be found in the web browser URL bar https://environment.logicgate.com/build/steps/{step-id}

Get Step ID (Risk Cloud API)

The step ID can be located via the Retrieve Steps endpoint, specifically in the id property of step objects returned in the content property of the response.

Records Updated Since Date

To request all records that have been updated (either a field has been updated or the record has been moved, assigned, or linked), use the updated-min query parameter with a timestamp measured in milliseconds since the Unix epoch. An example for January 1st 2023 at 9:00am GMT would be 1672563600000.

The updated-min query parameter can additionally be used alongside other query parameter filters such as application-id, workflow-id, and step-id to fine-tune your record search further.

Retrieve Records by Field Value Endpoint

The Record API also provides the ability to return records that have a particular field value. This can be accomplished with the following v1 API endpoint and query parameters.

Query Parameter Description
field The unique ID of the field for the associated text value to filter records by.
textValue The text value of the given field to filter records by.

 

v2023.10.1 Release Notes

These are Release Notes for v2023.10.1 of Risk Cloud API v2, released on September 25th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

Prisma Cloud Risk Cloud Connector
VISO Trust Risk Cloud Connector
Adobe Sign Risk Cloud Connector
SharePoint Risk Cloud Connector
NetSuite TPRM Risk Cloud Connector
NetSuite Expense Report Risk Cloud Connector
v2023.10.0 Release Notes

These are Release Notes for v2023.10.0 of Risk Cloud API v2, released on October 4th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

Records (New)

Retrieve a page of all records that the current user has Read or Write access to.

These fields can be filtered by the following properties:

  • application-id - get all records of a given application
  • workflow-id - get all records of a given workflow
  • step-id - get all records of a given step
  • updated-min - get all records that have been modified since the given timestamp
CrowdStrike Risk Cloud Connector
Qualys Risk Cloud Connector
v2023.9.1 Release Notes

These are Release Notes for v2023.9.1 of Risk Cloud API v2, released on September 25th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

RiskRecon Risk Cloud Connector
v2023.9.0 Release Notes

These are Release Notes for v2023.9.0 of Risk Cloud API v2, released on September 8th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

Steps

POST/api/v2/steps
  • assignableUserType - the default value has been updated from APP_AND_EXTERNAL_USERS to APP_USERS
v2023.8.1 Release Notes

These are Release Notes for v2023.8.1 of Risk Cloud API v2, released on August 24th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

Fields (New)

Retrieve a page of all fields whose parent application the current user has Build Access to.

These fields can be filtered by the following properties:

  • application-id - get all fields of a given application
  • workflow-id - get all fields of a given workflow
  • step-id - get all fields of a given step
  • field-type - get all fields of a given fields type
v2023.8.0 Release Notes

These are Release Notes for v2023.8.0 of Risk Cloud API v2, released on August 10th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

Risk Cloud API: Postman

Build and refine your custom integration with our user-friendly Risk Cloud API Postman Workspace, which you can import to your Postman setup in the button below.

Once the Risk Cloud API Postman Collection and Environment have been forked to your Postman Workspace, you're ready to begin integrating with the following next steps.

  • Obtain either your API token or client key & secret key by following the instructions in Risk Cloud API: Authentication

  • In the Risk Cloud API Environment, set the following variable-value pairs:

    • bearerToken - your API token obtained above
    • baseUrl - your Risk Cloud environment (https://environment.logicgate.com, with environment swapped for your subdomain)

  • If authenticating via a client and secret, additionally set the following variable-value pairs:

    • basicAuthUsername - your client key

    • basicAuthPassword - your secret key

  • You're setup to begin sending requests to your Risk Cloud environment from Postman!
v2023.7.1 Release Notes

These are Release Notes for v2023.7.1 of Risk Cloud API v2, released on July 27th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API updates.

v2023.7.0 Release Notes

These are Release Notes for v2023.7.0 of Risk Cloud API v2, released on July 13th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

Steps (New)

Retrieve a page of all steps that the current user has Build Access to parent application to.

POST/api/v2/steps

Create a step from a JSON request body.

Retrieve a step specified by the ID in the URL path.

Delete a step specified by the ID in the URL path.

Update a step specified by the ID in the URL path from a JSON request body. Only present properties with non-empty values are updated.

v2023.6.1 Release Notes

These are Release Notes for v2023.6.1 of Risk Cloud API v2, released on June 29th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API v2 updates are in this release. Step v2 and Record Read v2 API endpoints are both in active development.

ServiceNow (Asset) Risk Cloud Connector
v2023.6.0 Release Notes

These are Release Notes for v2023.6.0 of Risk Cloud API v2, released on June 14th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

Application

Return Type

  • Changed response : 200 OK
  • Changed content type : application/json
    • Changed property restrictBuildAccess (boolean)

Request

  • Changed content type : application/json
  • Changed property restrictBuildAccess (boolean)

Return Type

  • Changed response : 200 OK
  • Changed content type : application/json
    • Changed property restrictBuildAccess (boolean)
POST/api/v2/applications

Return Type

  • Changed response : 200 OK
  • Changed content type : application/json
    • Changed property restrictBuildAccess (boolean)

Return Type

  • Changed response : 200 OK
  • Changed content type : application/json
    • Changed property content (array)
    • Changed items (object):
      • Changed property restrictBuildAccess (boolean)
Google Looker Native Integration
OpenAI Risk Cloud Connector
v2023.5.2 Release Notes

These are Release Notes for v2023.5.2 of Risk Cloud API v2, released on June 5th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

No API v2 updates are in this release. Step v2 and Record Read v2 API endpoints are both in active development.

v2023.5.1 Release Notes

These are Release Notes for v2023.5.1 of Risk Cloud API v2, released on May 18th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

Application

  • Changed response : 200 OK
  • Changed content type : application/json

    • Added property restrictBuildAccess (boolean)

    • Deleted property restrict-build-access (boolean)

  • Changed response : 200 OK
  • Changed content type : application/json

    • Added property restrictBuildAccess (boolean)

    • Deleted property restrict-build-access (boolean)

  • Changed content type : application/json
  • Added property restrictBuildAccess (boolean)

  • Deleted property restrict-build-access (boolean)

POST/api/v2/applications
  • Changed response : 200 OK
  • Changed content type : application/json

    • Added property restrictBuildAccess (boolean)

    • Deleted property restrict-build-access (boolean)

  • Changed response : 200 OK
  • Changed content type : application/json

    • Changed property content (array)

    • Changed items (object):

      • Added property restrictBuildAccess (boolean)

      • Deleted property restrict-build-access (boolean)

    • Changed property page (object)

      • Added property totalElements (integer)

      • Added property totalPages (integer)

      • Deleted property total-elements (integer)

      • Deleted property total-pages (integer)

Workflow

  • Changed response : 200 OK
  • Changed content type : application/json

    • Added property recordPrefix (string)

    • Added property applicationId (string)

    • Deleted property record-prefix (string)

    • Deleted property application-id (string)

  • Changed response : 200 OK
  • Changed content type : application/json

    • Added property recordPrefix (string)

    • Added property applicationId (string)

    • Deleted property record-prefix (string)

    • Deleted property application-id (string)

  • Changed content type : application/json
  • Added property recordPrefix (string)

  • Deleted property record-prefix (string)

POST/api/v2/workflows
  • Changed content type : application/json
  • New required properties:
    • applicationId
    • recordPrefix
  • New optional properties:
    • application-id
    • record-prefix
  • Added property recordPrefix (string)

  • Added property applicationId (string)

  • Deleted property record-prefix (string)

  • Deleted property application-id (string)

  • Changed response : 200 OK
  • Changed content type : application/json

    • Added property recordPrefix (string)

    • Added property applicationId (string)

    • Deleted property record-prefix (string)

    • Deleted property application-id (string)

  • Changed response : 200 OK
  • Changed content type : application/json

    • Changed property content (array)

    • Changed items (object):

      • Added property recordPrefix (string)

      • Added property applicationId (string)

      • Deleted property record-prefix (string)

      • Deleted property application-id (string)

    • Changed property page (object)

      • Added property totalElements (integer)

      • Added property totalPages (integer)

      • Deleted property total-elements (integer)

      • Deleted property total-pages (integer)

Workflow Map

  • Changed response : 200 OK
  • Changed content type : application/json

    • Changed property page (object)

      • Added property totalElements (integer)

      • Added property totalPages (integer)

      • Deleted property total-elements (integer)

      • Deleted property total-pages (integer)

v2023.5.0 Release Notes

These are Release Notes for v2023.5.0 of Risk Cloud API v2, released on May 8th, 2023.

Risk Cloud API v2 is a collection of new API-first and RESTful API endpoints to streamline the creation of custom integrations with the Risk Cloud.

These endpoints are currently in open alpha, meaning that backwards compatibility is not guaranteed and breaking changes are to be expected as the endpoints are finalized. The full release of these new v2 endpoints is anticipated for late 2023.

Risk Cloud API v2 Resources

Featured Updates

Authentication

POST/api/v1/account/token

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Application

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

POST/api/v2/applications

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed content type : application/json

  • Changed property type (string)

    Added enum values:

    • CONTROLS_COMPLIANCE
    • CYBER_RISK_MANAGEMENT
    • DATA_PRIVACY_MANAGEMENT
    • ESG
    • INTERNAL_AUDIT_MANAGEMENT
    • OPERATIONAL_RESILIENCY
    • POLICY_MANAGEMENT
    • REPOSITORY

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed content type : application/json

  • Added property restrict-build-access (boolean)

  • Deleted property restrictBuildAccess (boolean)

  • Changed property type (string)

    Added enum values:

    • CONTROLS_COMPLIANCE
    • CYBER_RISK_MANAGEMENT
    • DATA_PRIVACY_MANAGEMENT
    • ESG
    • INTERNAL_AUDIT_MANAGEMENT
    • OPERATIONAL_RESILIENCY
    • POLICY_MANAGEMENT
    • REPOSITORY

Workflow

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

  • Added: application-id in query
  • Added: include-jira-workflows in query
  • Deleted: applicationId in query
  • Deleted: includeJiraWorkflows in query

POST/api/v2/workflows

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed content type : application/json

New required properties:

  • application-id
  • record-prefix

New optional properties:

  • applicationId
  • recordPrefix
  • Added property record-prefix (string)

  • Added property application-id (string)

  • Deleted property recordPrefix (string)

  • Deleted property applicationId (string)

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed content type : application/json

  • Added property record-prefix (string)

  • Deleted property recordPrefix (string)

Workflow Map

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

  • Added: workflow-id in query
  • Deleted: workflowId in query

POST/api/v2/workflow-maps

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Changed response : 200 OK

  • New content type : application/json

  • Deleted content type : */*

Risk Cloud API: Automated Evidence Collection

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
POST/api/v1/evidence?parentRecordId={RECORD_ID}&fieldId={FIELD_ID}&stepId={STEP_ID}

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:

POST/api/v1/evidence?parentRecordId={RECORD_ID}&fieldId={FIELD_ID}&stepId={STEP_ID}

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]!

UCF Risk Cloud Connector
Salesforce Risk Cloud Connector
Jira Risk Cloud Connector
DocuSign Risk Cloud Connector
Slack Native Integration
ServiceNow Ticket Risk Cloud Connector
Google Drive Risk Cloud Connector
BitSight Risk Cloud Connector
Microsoft Teams Native Integration
CUBE Risk Cloud Connector
Vital4 Risk Cloud Connector
Risk Cloud API: Getting Started

The Risk Cloud API is a collection of RESTful API endpoints that empower you and your team to directly integrate, automate, and build with the Risk Cloud. Risk Cloud API endpoint payloads are JSON based, with some endpoints supporting exports in CSV and XSLX formats for flexible integration.

Explore our full API documentation or step through our step-by-step walkthrough below.

Getting Started

In this walkthrough, we will go over some basic concepts of the Risk Cloud API, including authentication, pagination, getting data, and updating data.

Authentication

The Risk Cloud API uses OAuth 2.0 for authentication, using bearer Access Token in the Authorization HTTP header. To obtain an API Access Token and get started building out your integration, reference the guide Risk Cloud API: Authentication.

Postman

Build and refine your custom integration with our user-friendly Risk Cloud API Postman Workspace, which you can import to your Postman setup in the button below.

For more Postman setup information, reference our guide Risk Cloud API: Postman.

Pagination

The Risk Cloud API contains a variety of endpoints that may return a substantial amount of listed data. These endpoints utilize a style of offset pagination to provide a flexible and consumable means of processing Risk Cloud data. To learn more about pagination in the Risk Cloud API, reference the guide Risk Cloud API: Pagination.

Rate Limit

The Risk Cloud API recommends a rate limit of 10 requests per second in order to ensure optimal and efficient performance.

Getting Data

From exporting to data lakes to fine tuning data for existing dashboard tools, the Risk Cloud API provides a flexible means of exporting data from your Risk Cloud environment. Linked below are guides covering common use cases for exporting Risk Cloud environment data. For all available endpoints, feel free to explore our full API documentation.

Modifying Data

The Risk Cloud API can also perform actions in your Risk Cloud environment such as creating records and users or updating fields and attachments on records. To learn more about modifying data in your Risk Cloud environment via the Risk Cloud API, reference the linked guides below. For all available endpoints, feel free to explore our full API documentation.

Webhooks

In addition to the Risk Cloud API, there are also Risk Cloud Webhooks, which allow you to enhance your custom integrations by sending Risk Cloud automation event data to your external systems. To learn more, checkout our guide Risk Cloud Webhooks.

Contact

Contact LogicGate's Developer Relations team directly for API assistance at [email protected].

Ascent Risk Cloud Connector
SecurityScorecard Risk Cloud Connector
Tenable Risk Cloud Connector
Black Kite Risk Cloud Connector
Risk Cloud API: Pagination

The Risk Cloud API contains a variety of endpoints that may return a substantial amount of listed data. These endpoints utilize a style of offset pagination to provide a means of processing the data in smaller portions.

Page Requests

Risk Cloud API endpoints that support Pagination accept two optional query parameters to indicate what portion of data to return.

  • page - an integer representing the zero-indexed page number (must not be lessthan 0, defaults to 0)
  • size - an integer representing the size of the page and maximum number of itemsto be returned (must not be less than 1, defaults to 20)

These query parameters function conceptually similar to how pages are implemented in the Risk Cloud UI, where the page is the page number value, albeit zero-indexed, and size is the Results per page value.

Example

The Field Read All endpoint of GET /api/v1/fields utilizes Pagination. If there are 50 active Fields (numbered 1-50) in a Risk Cloud environment, then the following query parameters will return the following Fields.

Page Size Request Fields
None (Default 0) None (Default 20) GET /api/v1/fields 1-20
0 20 GET /api/v1/fields?page=0&size=20 1-20
1 20 GET /api/v1/fields?page=1&size=20 21-40
2 20 GET /api/v1/fields?page=2&size=20 41-50
0 8 GET /api/v1/fields?page=0&size=8 1-8
1 8 GET /api/v1/fields?page=1&size=8 9-16

Page Responses

When a Risk Cloud API endpoint returns a Page, the response body contains a variety of properties. 

Property Type Description
content array A list of the returned items
number integer The zero-indexed page number
size integer The size of the page and maximum number of items to be returned
totalElements integer The total number of items available
totalPages integer The total number of pages available based on the size
first boolean Whether the current page is the first one
last boolean Whether the current page is the last one
empty boolean Whether the current page is empty
numberOfElements integer The number of items currently on this page
sort object The sorting parameters for the page
sort.empty boolean Whether the current page is empty
sort.sorted boolean Whether the page items are sorted
sort.unsorted boolean Whether the page items are not sorted

Page Processing

Depending on the integration, there are multiple strategies for processing data from a Risk Cloud API endpoint that supports Pagination.

  • Bulk
  • Iteration

Bulk

The Bulk strategy involves sending a single request to obtain a bulk result. This is accomplished by providing a large value for the size query parameter. The size value should be large enough to surpass the expected maximum amount of possible returned items. An example would be: GET /api/v1/fields?size=1000

The items can then be obtained from the content property of the response.

Pseudocode Example

CALL GetFields with size as 1000 RETURNING response 
SET items to response.content

Iteration

The Iteration strategy involves sending multiple requests and assembling a result. This can be accomplished in multiple ways, including the following.

  • Incrementing the pagenumber until a response where last is true is received
  • Incrementing the page number until it reaches the amount of the totalPagesresponse property

Pseudocode Example

SET items to [] 
SET index to 0 
REPEAT 
  CALL GetFields with page as index RETURNING response 
  APPEND response.content to items 
  INCREMENT index 
UNTIL response.last = true

 

Tidying Up Existing REST APIs

Originally posted on Nordic APIs

What if, one morning, you discover that every internal REST API endpoint of your web application is suddenly displayed as-is in your public REST API documentation? Your Developer Portal is overflowing with messages from eager API users struggling to make integrations with the exciting new functionality the endpoints provide.

  • “Is the name property required on this GET request?”
  • “What is the request body supposed to look like to create a new Blog object?”
  • “I tried to update a User, and now I’m seeing null pointer exceptions everywhere!”

On top of an overflowing portal, not only are the newly posted internal endpoints causing confusion but regressions are being discovered in preexisting public API endpoints too! Whether this scenario feels like a distant bad dream or resonates a little too close to reality, as time and development tickets go by, the quality and conciseness of some existing API endpoints may slowly decline.

From older public endpoints to internal endpoints that may become public, how can you tidy up existing REST API endpoints for public usage? Let’s get tidying!

Strategies for Tidying REST APIs

Rescope the Data

Request and response data can often be closely tied to internal database resources. It can be tempting to include all properties that are available on a resource in the API to support more integration possibilities. However, some resource properties may not be relevant to an API user.

Data Transfer Objects (DTOs), which provide a decoupled representation of your database resources, are particularly useful for making more concise request and response payloads for REST API endpoints. In addition to conciseness, DTOs also improve maintainability and flexibility, allowing for database and service level resources to be updated independently from their corresponding API representations.

DTOs and Database Resources

Using a User resource as an example, a JSON representation of a User database resource may contain the following properties.

json
{
  "id": "string",
  "email": "string",
  "password": "string",
  "roleId": "string",
  "companyId": "string",
  "firstName": "string",
  "lastName": "string",
  "loginAttempts": 0
}

A JSON representation of a User DTO could contain a scoped-down, API-friendly representation of the data, as shown below.

json
{
  "id": "string",
  "email": "string",
  "firstName": "string",
  "lastName": "string"
}

What Properties Should Be Included in the DTO?

For a given resource (e.g., a User), consider the following process for crafting a DTO representation:

  • Begin with an empty DTO.
  • Consider each property and relationship of the resource individually (e.g. User.emailUser.loginAttempts, etc…).
  • Reflect on the value of including the property or relationship in the API.
  • User.email is high value in an API endpoint for both identifying the user or creating an integration to email the user.
  • User.loginAttempts may only be relevant to the internal web application and omitting it from the API may make the endpoint more concise.

It can be difficult to decide to omit an available property from a resource’s DTO representation in an API. However, as API users build out integrations, it’s less complicated to add a property to an API endpoint by popular demand rather than having to risk breaking backward compatibility by removing a potentially unused existing property.

If introducing a DTO on an existing API endpoint’s request or response would break API compatibility, consider creating a separate endpoint for the DTO implementation and coordinating a migration or deprecation strategy with API users.

Observe the UI

A single front-end change that works with what is available can be more valuable to a team in the short term than multiple changes across the stack, saving time and precious story points. However, over time, this can cause the alignment between the front-end and back-end to decline, which could call for a reassessment of the existing API endpoint.

For example, a radio button component with three options in a UI may be represented by three corresponding boolean properties in the API, where each option was added individually over time in separate code contributions. However, after taking a look at the current state of the functionality, the radio button component as a whole may be better represented in the API via a single enum property with values for each option.

If your web app has a user interface, observe how an existing endpoint is used in the frontend:

  • Are there unused properties on the endpoint?
  • Is data being transformed in the frontend to accommodate the endpoint, where the endpoint could be modified itself?
  • Are other endpoints being referenced where a concise, composite endpoint that supports the same functionality would be better suited?

Once these questions have been addressed, consider updating the API endpoint accordingly to align it closer to how it’s currently being used.

Reference a Guideline

If you have existing API guidelines for your public endpoints, dust them off! If you don’t have API guidelines, consider modeling existing API guidelines (e.g. ZalandoMicrosoftGoogle) or creating your own from API best practices.

Some examples of API guidelines to improve the consistency and clarity of an API could include:

  • Are the API documentation descriptions concise, accurate, or relevant?
  • Are URL paths aligned (using camelCase vs. kebab-case)?
  • When should query parameters be used vs. request body?

Once you have API guidelines in place, pass through your API and capture any notable deviations in some API maintenance tickets. With defined API guidelines, there is also an opportunity to integrate the guidelines into code review automation to ensure that the guidelines are preserved going forward.

Notate Required-Ness

As API endpoints may expand over time, identifying what request body properties or query parameters are actually required can become daunting. It can be incredibly valuable to take a second look at an existing endpoint, test it, and even dig into the underlying code to determine what is truly required. Once the required properties on an endpoint have been identified, ensure that the properties are noted as being required in the API documentation as well.

Break It Down

Some endpoints can carry a lot of responsibility, perhaps even snowballing in scope over time. In particular, endpoints that update resources can have large request body payloads containing multiple related objects, making it difficult to break down and simplify the endpoint.

While CRUD (Create, Read, Update, Delete) does not necessarily match the HTTP methods of REST 1-to-1, the CRUD methodology does provide a widely adopted and straightforward framework for breaking down a resource’s endpoint functionality into a handful of more concise endpoints.

Let’s use the example of an update endpoint for a User resource that has a Blog relationship resource in the request payload.

json
{
  "email": "string",
  "firstName": "string",
  "lastName": "string",
  "blogs": [
    {
      "id": "string",
      "title": "string",
      "content": "string"
    }
  ]
}

The existing endpoint allows an API user to update a User while also creating or updating an attached Blog.

  • Consider the unique resources in the endpoint’s request.
  • If each resource had its own Create, Read, Update, or Delete API endpoints, how could similar functionality be achieved (albeit with more requests)?
  • Could an existing object be represented as an ID instead of the full object?

After answering these questions, a decision could be made to:

  • Remove the Blog from the User update endpoint.
  • Write new endpoints for updating or creating a Blog that accept the User.id to establish the relationship.
  • Achieve similar functionality through the new, more concise endpoints.

The new create or update endpoints for a Blog could then have a payload similar to the following.

json
{
  "title": "string",
  "content": "string",
  "userId": "string"
}

Additionally, it may be valuable to include usage documentation to accompany the new endpoint flow. While there is a case to be made that multiple endpoints could be expensive for paid APIs or less performant, the introduction of new concise endpoints can additionally provide more flexibility to your API and potential integrations.

Next Steps

As development moves forward and edge cases arise, it can be worth considering these tips when refactoring or reviewing API changes.

  • Rescope the data: Evaluate the necessity of resource properties.
  • Observe the UI: Leverage the current UI to inform API decisions.
  • Reference a guideline: Align your API and adopt best practices with a guide.
  • Notate required-ness: Ensure that optional and required properties are up-to-date.
  • Break it down: Evaluate how endpoint functionality could be replicated with scoped-down endpoints.

REST API maintenance is a continuous process. When there is routine attention to the accuracy, relevance, and clarity of existing API endpoints, API users and developers alike can be more confident in the use cases and integrations they create and support.

Risk Cloud API: Authentication

How to use Risk Cloud's API to create or retrieve an API Access Token

The Risk Cloud API uses OAuth 2.0 for authentication which uses a bearer token in the Authorization http header. In order to start using the API, first retrieve your Client and Secret keys from the Profile page. This can be navigated to by clicking the Person icon in the top right corner and then the Profile button.

In the Profile page, go to the "Access Key" tab. If this tab is not there, please contact your Risk Cloud administrator as you may not have API privileges.

In the "Access Key" tab you will see both Client and Secret keys. These are both necessary to generate an access key or retrieve an existing access key.

*Note that this panel also has the ability to generate the Access Key on its own.
After having both Client and Secret keys they will need to be base64 encoded with a colon in between them: {CLIENT}:{SECRET}

Once they are encoded, take your encoded string and place it in the authorization header as Authorization: Basic {ENCODED}

Once this URL is pinged with the correct Authorization Header a JSON response will appear mimicking the following structure:

POST/api/v1/account/token

Response:

{
    "access_token": "KEY_HERE",
    "token_type": "bearer",
    "expires_in": 31532918,
    "scope": "read write"
}

The returned access token can then be used in the authorization header to interact with Risk Cloud's API

Authorization: Bearer {ACCESS_TOKEN}
Risk Cloud API: Export Record Data

Exporting Record data via the Risk Cloud API is a common use case. While the endpoints in Risk Cloud API: Record Search cover how to return and filter record data in a JSON format, there are use cases where CSV or XLSX formats are convenient.

In this article, we will walk through the steps necessary for obtaining CSV and XLSX data exports of your records via the Risk Cloud API.

  1. Obtain the layout-id that you would like applied as the columns for the CSV or XLSX export
  2. Obtain the application-id, workflow-id, and step-id that you would like to export record data for
  3. Select the status that you would like to export record data for
  4. Retrieve Record Export
POST/api/v1/records/export/csv

Authentication

Obtain your API Access Token to get started, and for more on exporting record data and layouts, refer to our Help Center articles Export Record Data and Overview of Layouts.

Step 1: Obtain the layout-id

The layout represents the field columns of the CSV or XLSX export. The layout-id can be obtained from the Risk Cloud web application or via the Risk Cloud API. If you already know your layout-id you may continue to Step 2: Obtain application-id, workflow-id, and step-id

Using the Risk Cloud application

The most straightforward way to find a layout ID is to open the desired layout from the builder page located at Build > Layouts in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/build/layouts/{layout-id}

Using the Risk Cloud API

The Retrieve Layouts endpoint returns all layouts that the user is entitled to, either as an Admin, Builder, or Step Permission Set grantee. If no layouts are returned, check the permissions of the requesting API user to ensure that proper permissions are granted.

This will return an array of layout objects, each looking like the following. Parse the layout objects by properties like workflow, application, or title until you have located the intended layout.

{
  "id": "a1b2c3d4",
  "active": true,
  "created": 1595957773409,
  "updated": 1617645014337,
  "title": "[Reg Compliance] Assessments",
  "defaultLayout": true,
  "workflow": {
    "id": "e5f6g7h8",
    "active": true,
    "created": 1592837365474,
    "updated": 1676386494460,
    "name": "Risk and Impact Assessments",
    "recordPrefix": "Assessment",
    "allowGroups": false,
    "requireGroups": false,
    "xpos": 26,
    "ypos": 288,
    "priority": 2,
    "sla": {
      "enabled": false,
      "duration": 0
    },
    "allowAec": false,
    "steps": [
      
    ],
    "sequence": null,
    "application": {
      "id": "i8j9k0l1",
      "active": true,
      "created": 1567164504184,
      "updated": 1702410681371,
      "name": "RCX: Regulatory Compliance",
      "createdBy": null,
      "color": "#00a3de",
      "icon": "fas__fa-university",
      "type": "REGULATORY_COMPLIANCE",
      "sourceApplicationId": "m2n3o4p5",
      "sourceEnvironment": "grc",
      "permissionsEnabled": false,
      "imported": true,
      "copied": false,
      "live": true,
      "calcsV2": true,
      "currency": "USD",
      "uxriEnabled": true
    },
    "userGroups": [
      
    ],
    "primaryField": null,
    "workflowType": "WORKFLOW"
  },
  "layoutType": "Display"
}

2. Obtain the application-id, workflow-id, and step-id

Application, workflow, and step IDs can be obtained from the Risk Cloud web application or via the Risk Cloud API. If you already know your application-id, workflow-id, and step-id you may continue to Step 3: Select Status.

Using the Risk Cloud application

The most straightforward way to find application, workflow, and step IDs is via the Risk Cloud web application.

Application ID

Open the desired application from the builder page located at Build > Applications in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/build/applications/{application-id}

Workflow ID

Open the desired application containing the workflow from the builder page located at Build > Applications in the Risk Cloud web application, then select the edit gear icon on the top-right corner of the Workflow to open the Workflow Editor modal. The workflow ID will be displayed under the Workflow ID label.

Step ID (Optional)

Open the desired step from the builder page located at Build > Applications > (Select a Step) in the Risk Cloud web application, then take the ID from the end of the URL.

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

Using the Risk Cloud API

Applications, workflows, and steps all have endpoints in our Risk Cloud API v2, which provide a paginated means of iterating through all resources entitled to the API user.

To search for an application, use the Retrieve Applications endpoint.

To search for an application, use the Retrieve Workflows endpoint.

To search for an application, use the Retrieve Steps endpoint (optional).

3. Select Status (optional)

Exported records may also be filtered by the status of the Record for a more granular selection. Record statuses that can be filtered are: INACTIVE, NOT_ASSIGNED, ASSIGNED, IN_PROGRESS, and COMPLETE.

4. Retrieve Record Export

In this step, we will use the layout-id, application-id, and workflow-id (with optional step-id, and status) found in the previous steps to export the records.

Additionally, csv in the path may be swapped for xlsx to switch the returned format of the spreadsheet.

POST/api/v1/records/export/csv
Sample Request Body
{ 
  "layout": "layout-id",
  "applications": ["application-id"], 
  "workflow": "workflow-id", 
  "statuses": ["IN_PROGRESS"], 
  "step": "step-id" 
}
Response

A CSV or XLSX representation of the records, with field columns reflecting the provided layout.

Risk Cloud API: Upload Attachments

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

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

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

  3. Attach the file to your specific record via a POST /api/v1/valueMaps?record={RECORD_ID} 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 the 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: 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:

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.

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

Risk Cloud API: View User Access Audits
A guide to the API endpoints that allow you to track user login attempts

This article details 3 endpoints for obtaining access logs for All Login Attempts, Successful Logins, and Login Failures. The results from these endpoints are only accessible to access keys belonging to users with the Admin > All module entitlement.

Login Attempts

Retrieve a log of login successes and failures for a Risk Cloud user, using their email.

Parameters

  • email: a valid user email (e.g. [email protected], or for Postman syntax admin%[email protected])
  • size: the size of the paged response
  • page: the number of the page in the response

Result

A paginated response of all login logs ordered from newest to oldest containing the following info:

  • Type: Login or LoginFail
  • Timestamp: time stamp to determine time of Login
  • Message: details on reason for LoginFail, null for Login
  • Remote Address: remote IP of Login user

Logins (Successes)

Retrieve a log of successful login attempts for all users.

Parameters

  • email: a valid user email (e.g. [email protected], or for Postman syntax admin%[email protected])
  • size: the size of the paged response
  • page: the number of the page in the response

Result

A paginated response of all login logs ordered from newest to oldest containing the following info:

  • Type: Login
  • Timestamp: time stamp to determine time of Login
  • Message: null for Login
  • Remote Address: remote IP of login user

Logins (Failures)

Retrieve a log of failed login attempts.

Parameters

  • email: a valid user email (e.g. [email protected], or for Postman syntax admin%[email protected])
  • size: the size of the paged response
  • page: the number of the page in the response

Result

A paginated response of all login logs ordered from newest to oldest containing the following info:

  • Type: LoginFail
  • Timestamp: time stamp to determine time of LoginFail
  • Message: details on reason of LoginFail
  • Remote Address: remote IP of Login user
Risk Cloud PowerBI Connection

How to set up PowerBI to pull data from a Risk Cloud Table Report automatically.

After loading/importing the Power BI Template file, LogicGate_EXAMPLE_Extract to PowerBI.pbit (reach out to [email protected] for the file), you will see a screen that looks like the below. You will need to enter (1) your OAuth 2.0 client; (2) your OAuth 2.0 secret; (3) your Risk Cloud environment URL; and (4) the Table Report ID you would like to extract data from.

To find the Client and Secret, within Risk Cloud, you can navigate to your User Profile via the User icon at the top-right corner of your screen. There, flip to the Access Key key tab and you will see your Client and Secret.

You can obtain your Table Report ID from the URL in your browser window after navigating to a Table Report, as shown below.

Note: The Table Report ID is the last eight digits of the URL. In the image above this is D7r2TCSR (this will be different for your Table Report).

Once you have all that information, you can then enter it into the Power BI template similar to the below:

From there, it will load all your table report data into a table in Power BI.

Lastly, you can use that information to build reports, add additional data sources from other internal systems, and more!

Risk Cloud Webhooks

Use Risk Cloud Webhooks to enhance your custom integrations and send event data to your external systems to detect Risk Cloud events and perform custom operations.

Make your custom integrations more responsive and integrated with Risk Cloud Webhooks. This feature gives you the ability to send event data from Risk Cloud to an external URL via an HTTP request when a triggering event occurs in Risk Cloud.

A Risk Cloud Webhook can be setup in the Risk Cloud as a type of Job Operation, and can be triggered based off the following detected events in your Risk Cloud environment:

  • Record Due - fires when a record is approaching or past its due date
  • Record Reassigned - fires when a record is manually reassigned
  • Record Created - fires when a record is created
  • Record Moved - fires when a record is moved to a new step in a workflow
  • Fixed Scheduled - fires at a recurring or set time

Setting up Risk Cloud Webhooks can be accomplished in the following steps:

  1. Work with your relationship manager or customer success manager to enable Risk Cloud Webhooks in your environment. NOTE: Risk Cloud Webhooks may need to be added to your Risk Cloud subscription agreement.

  2. Configure the external webhook URLs that you would like to send data to.

  3. Create jobs in Risk Cloud with your desired triggering event and use the new webhook operation to send data to your specified URL.

Configuring Webhook URLs

Once Risk Cloud Webhooks has been enabled in your environment, you will be able to add webhook URLs from the Admin > Integration page. Clicking “Configure Integration” will bring up a modal where you are able to add webhook URLs.

Make sure to give your webhook URLs recognizable names, as this is how they will be referenced when you create a Job.

When you click “Save Webhook URL,” we will attempt to call the provided URL with a standard GET request.

If successful, your webhook will be saved and you will be presented with a one-time secret key. This key is presented only once, and can be used to ensure that data is coming from Risk Cloud.

Creating a Risk Cloud Webhook Job

Now that you have configured one or more webhook URLs, you can begin adding webhook job operations. You can learn more about creating jobs in this help article.

Once you have specified your trigger and an optional message, you will want to select the “webhook” operation. Once this operation is selected, you can specify which webhook URL should be sent data when the job is triggered. We will show you an example of what data is being sent based on the workflow/trigger that you have selected.

NOTE: No custom field data will be sent with Risk Cloud Webhooks. We are only sending event data and record/workflow identification data.

When you save your job everything will be ready for Risk Cloud to start sending event data via webhooks.

Reach out to [email protected] for additional support or your relationship manager to enable this feature.

Risk Cloud API: View Applications, Workflows, and Steps

How to obtain Application, Workflow, and Step information for review and future API requests via the Risk Cloud API.

API Authentication

Prior to any interaction with Risk Cloud's APIs we will need to obtain an Access Token for the Authorization header. Instructions on how the Access Token can be obtained can be found here.

Background

When working with the Risk Cloud via the API, it is common to require IDs for entities such as Applications, Workflows, and Steps.

The endpoint described below returns an array of all Applications in your environment, including their Workflows and Steps. The endpoint provides important ID data for Applications, Workflow, and Steps that can be used to interact with the API further, such as using a Step ID to Create Records or a Workflow ID to get a list of Fields.

Usage

To obtain a list of all Applications, Workflows, and Steps in your environment, make the following request.

curl --request GET 'https://your-company.logicgate.com/api/v1/applications?generic=true' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

The response will contain an array of all Applications. Application, Workflow, and Step IDs can be located as the values for id properties for usage in future API requests.

[
  {
    "active": true,
    "color": "string",
    "copied": true,
    "created": "2019-08-24T14:15:22Z",
    "homeScreen": {
      "active": true,
      "application": {},
      "created": "2019-08-24T14:15:22Z",
      "id": "string",
      "tableReports": [
        null
      ],
      "updated": "2019-08-24T14:15:22Z"
    },
    "icon": "fa-bookmark",
    "id": "string",
    "imported": true,
    "live": true,
    "name": "string",
    "permissionsEnabled": true,
    "type": "string",
    "updated": "2019-08-24T14:15:22Z",
    "workflows": [
      {
        "active": null,
        "allowGroups": null,
        "application": null,
        "applicationId": null,
        "created": null,
        "fields": null,
        "id": null,
        "name": null,
        "primaryField": null,
        "priority": null,
        "recordPrefix": null,
        "requireGroups": null,
        "sequence": null,
        "sla": null,
        "steps": null,
        "updated": null,
        "userGroups": null,
        "workflowMaps": null,
        "workflowType": null,
        "xpos": null,
        "ypos": null
      }
    ]
  }
]

 

Risk Cloud API: Viewing Fields

This article walks through obtaining Field information for review and future API requests via the Risk Cloud API.

API Authentication

Prior to any interaction with Risk Cloud's APIs we will need to obtain an Access Token for the Authorization header. Instructions on how the Access Token can be obtained can be found here.

Background

When working with the Risk Cloud via the API, it is common to require IDs for Fields for accomplishing tasks such as updating Records.

The following endpoint will return an array of Field objects that exist within a given Workflow.

Usage

Obtaining all Fields of a Workflow can be accomplished in two steps:

  1. Obtaining a Workflow ID

  2. Requesting the Workflow's Fields

Obtaining a Workflow ID

To obtain Workflow IDs in your environment (more information on this endpoint can be found in Viewing Applications, Workflows, and Steps), make the following request.

curl --request GET 'https://your-company.logicgate.com/api/v1/applications?generic=true' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

The response will contain an array of all Applications. Workflow IDs can be located as the values for id properties for "workflow" objects in that JSON.

[
  {
    ...
    "workflows": [
      {
        ...
        "id": null
      }
    ]
  }
]

Requesting the Workflow's Fields

Now that you have obtained a Workflow ID, you can obtain a list of all Fields on that Workflow.

curl --request GET 'https://your-company.logicgate.com/api/v1/fields/workflow/{workflowId}/values' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

The response will contain a list of all Fields that exist within the given Workflow. The Field IDs of which can be used for updating Records or viewing current Field values.

[
  {
    "active": true,
    "convertibleTo": [
      "string"
    ],
    "created": "2019-08-24T14:15:22Z",
    "currentValues": [
      {
        "active": null,
        "archived": null,
        "created": null,
        "defaultField": null,
        "discriminator": null,
        "empty": null,
        "field": null,
        "fieldId": null,
        "id": null,
        "idOrTransientId": null,
        "isDefault": null,
        "numericValue": null,
        "priority": null,
        "textValue": null,
        "transientIdOrId": null,
        "updated": null,
        "valueType": null
      }
    ],
    "defaultValues": [
      {
        "active": null,
        "archived": null,
        "created": null,
        "defaultField": null,
        "discriminator": null,
        "empty": null,
        "field": null,
        "fieldId": null,
        "id": null,
        "idOrTransientId": null,
        "isDefault": null,
        "numericValue": null,
        "priority": null,
        "textValue": null,
        "transientIdOrId": null,
        "updated": null,
        "valueType": null
      }
    ],
    "discrete": true,
    "fieldType": "TEXT",
    "global": true,
    "id": "string",
    "label": "string",
    "labels": [
      "string"
    ],
    "name": "string",
    "operators": [
      "EQUALS"
    ],
    "tooltip": "string",
    "updated": "2019-08-24T14:15:22Z",
    "validTypeForCalculationInput": true,
    "valueType": "string",
    "workflow": {
      "active": true,
      "allowGroups": true,
      "application": {},
      "applicationId": "string",
      "created": "2019-08-24T14:15:22Z",
      "fields": [
        null
      ],
      "id": "string",
      "name": "string",
      "primaryField": {},
      "priority": 0,
      "recordPrefix": "string",
      "requireGroups": true,
      "sequence": {},
      "sla": {},
      "steps": [
        null
      ],
      "updated": "2019-08-24T14:15:22Z",
      "userGroups": [
        null
      ],
      "workflowMaps": [
        null
      ],
      "workflowType": "[",
      "xpos": 0,
      "ypos": 0
    },
    "workflowId": "string"
  }
]

 

Risk Cloud API: Viewing Users

This article walks through obtaining User information for review and future API requests via the Risk Cloud API.

Authentication

Obtain your API Access Token to get started.

Permissions

Listing all Users via the Risk Cloud API requires an Access Token from an Admin Primary account.

Background

When working with the Risk Cloud via the API, it is common to require IDs for Users for accomplishing tasks from as enabling and disabling Users to assigning Users to Records.

The following endpoint will return an array of all Users in your Risk Cloud environment.

Usage

To obtain a list of all Users in your environment, make the following request.

The response will contain an array of all Users in your environment, the IDs of which can be located as the values for id properties for usage in future API requests.

[
  {
    "active": true,
    "convertibleTo": [
      null
    ],
    "created": "2019-08-24T14:15:22Z",
    "currentValues": [
      null
    ],
    "defaultValues": [
      null
    ],
    "discrete": true,
    "fieldType": "[",
    "global": true,
    "id": "string",
    "label": "string",
    "labels": [
      null
    ],
    "name": "string",
    "operators": [
      null
    ],
    "tooltip": "string",
    "updated": "2019-08-24T14:15:22Z",
    "validTypeForCalculationInput": true,
    "valueType": "string",
    "workflow": {},
    "workflowId": "string",
    "allowLocalLogin": true,
    "applicationEntitlements": [
      null
    ],
    "archived": true,
    "autoprovisioned": true,
    "company": "string",
    "defaultField": {},
    "disabled": true,
    "discriminator": "string",
    "email": "string",
    "empty": true,
    "external": true,
    "field": {},
    "fieldId": "string",
    "first": "string",
    "idOrTransientId": "string",
    "imageUrl": "string",
    "intercomHash": "string",
    "isDefault": true,
    "languageTag": "string",
    "last": "string",
    "lastLogin": {},
    "locked": true,
    "loginAttempts": 0,
    "modulePermissionSets": [
      null
    ],
    "notificationPreference": true,
    "numericValue": 0,
    "password": "string",
    "priority": 0,
    "records": [
      null
    ],
    "resetPasswordToken": "string",
    "roles": [
      null
    ],
    "scimStatus": "string",
    "sendEmail": true,
    "serviceAccount": true,
    "status": "string",
    "stepPermissionSets": [
      null
    ],
    "superUser": true,
    "textValue": "string",
    "tier": "[",
    "timeZone": "string",
    "transientIdOrId": "string"
  }
]
Risk Cloud API: Create Users

This article walks through creating Users via the Risk Cloud API.

API Authentication

Prior to any interaction with Risk Cloud API we will need to obtain an Access Token for the Authorization header. Instructions on how the Access Token can be obtained can be found here.

Permissions

Creating a User via the Risk Cloud API requires an Access Token from an Admin Primary account.

Background

In order to create Users in your environment via the Risk Cloud API, we will need to assemble the JSON of the User for an API POST request.

The Create User endpoint can be helpful for integrations that automate the onboarding of new colleagues or teams to the Risk Cloud.

Usage

Creating a User via the Risk Cloud API can be accomplished in two steps:

  1. Configure the User in JSON

  2. Create the User via a request

Configure the User in JSON

Below is a sample JSON body of a User to be created.

{
  "active": true,
  "status": "Active",
  "tier": "SECONDARY",
  "valueType": "User",
  "sendEmail": false,
  "email": "[email protected]",
  "first": "FirstName",
  "last": "LastName",
  "company": "Your Company"
}

The properties of tier, sendEmail, email, first, last, and company should be adjusted to the User you will be creating.

The sendEmail property is important in that if this is true then the system will send an automatic Welcome Message after the User is created.

Additionally, the tier property designates the User's access tier. Values can be:

  • "PRIMARY" Primary users are users who have access to the Build section of the app (these are typically Admin users).
  • "SECONDARY" Secondary users are users without access to the Build section (these are typically end-users).
  • "LIMITED" Limited users are secondary users who only use the platform infrequently (these are typically end-users performing quarterly or annual tasks).

Create the User via a request

Once the JSON for the User you'd like to create has been assembled, you can create the User by placing the JSON in the following request.

curl --request POST 'https://your-company.logicgate.com/api/v1/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--data-raw '{
"active": true,
"status": "Active",
"tier": "SECONDARY",
"valueType": "User",
"sendEmail": false,
"email": "[email protected]",
"first": "FirstName",
"last": "LastName",
"company": "Your Company"
}'

If successful, the User will be created and the response will contain the new User's information as shown below, including the User ID which can be used for future API requests.

{
  "status":"Active",
  "id":"a4b3c2d1",
  "active":true,
  "created":1629383622871,
  "updated":1629383622932,
  "email":"[email protected]",
  "company":"Your Company",
  "imageUrl":null,
  "imageS3Key":null,
  "status":"Active",
  "tier":"SECONDARY",
  "first":"FirstName",
  "last":"LastName",
  "languageTag":"en-GB",
  "timeZone":"Europe/Kiev",
  "notificationPreference":false,
  "mfaEnabled":false,
  "mfaSetup":false,
  "autoprovisioned":false,
  "scimStatus":null,
  "sendEmail":false,
  "roles":[],
  "stepPermissionSets":[],
  "applicationEntitlements":[],
  "records":[],
  "lastLogin":null,
  "external":false,
  "superUser":false,
  "name":"FirstName LastName",
  "locked":false,
  "idOrTransientId":"a4b3c2d1",
  "transientIdOrId":"a4b3c2d1",
  "empty":false
}

 

Accessibility Improvements at LogicGate

Where to Begin?

1. Start Small

Screenshot of the LogicGate application’s record page with circles denoting which items have tab focus.
The Tab Stops feature in Microsoft Accessibility Insights visually shows the focus path of each tab press across a page.

What do we Attack First?

1. Using aria-label

Screenshot of the top toolbar of a record page in the LogicGate application with readout from a screen reader.
Without an aria-label, buttons and other elements are not given context when announced through screen readers. We were able to address these issues by adding “aria-label” to each button, with short text describing what each button does. Ex: In the above, aria-label=”Add to your favorites”

In the above image (left), a label, “What is the Weather Like Today,” is present, but it is not associated with the accompanying radio buttons, which loses context for screen readers (middle). The above was fixed (right) by changing the label to a legend, which provides text for screen readers in radio groups.

Having sufficient foreground and background color contrast helps text and labels stand out to users. WAVE has a built-in color contrast checker where you can quickly lighten and darken colors until they pass WCAG guidelines.

How do we Know We’re Helping?

  • Can we interact with elements using common keys (enter, space, arrow keys, etc.)?
Screenshot of toolbar from LogicGate application with active focus on the notifications icon.
We use an outline on many items to more easily show when an element has focus.

What’s Next?

Left: our first iteration involved an extra focus on an SVG asterisk to show when fields are required. Right: our current iteration denotes required fields with a text asterisk, while still conveying information to a screen reader. Text denoting asterisks are for required fields, not pictured.
What Do We Look for in Developers?

Interviews are stressful. From finding time to meet a slew of people with different titles, to handling a dreaded technical curveball, interviewing can feel like a full-time job, except one where you don’t get paid. Amidst all of this, you’re trying to ask the right questions to determine if you’ll want to be a member of the team six months after signing the acceptance letter. At the very least, knowing what to expect would take some stress out of the interview process.

At LogicGate, we want you to be prepared every step of the way: from your first chat with a team member, to your final onsite. We figure the best way to prepare is to know exactly what we’ll ask, so consider this a crib sheet for your interview journey. What can you expect from your first day on the job to your one-year anniversary and beyond? While we can’t create a time machine to look at your one-year anniversary, we can describe what we look for in employees and the culture we provide at LogicGate.

What does LogicGate look for in engineers?

Aside from bug-smashing and coding skills, we look for engineers who are considerate, curious, and collaborative. Being a considerate engineer doesn’t just mean organizing variables alphabetically with meaningful names. While we appreciate taking the time to clean up code, a thoughtful engineer considers the user and recognizes how every line of code committed helps solve a larger business problem.

We also look for engineers who anticipate problems before they occur and are happy to research solutions that could improve our team’s efficiency. When the answer isn’t obvious, are they willing to reach out for help, jump on a call to pair, or message a channel for clarification?

While we appreciate coding capabilities and prowess in certain areas of the stack, we are just as closely looking for how a candidate helps enhance our six core values. We hope that anyone joining our team strengthens our commitment to these values as they grow into their position.

What can I expect from the interview process?

Our goal is to have a breezy interview process, especially considering candidates use their free time to apply. We aim for transparency while being careful not to waste anyone’s time.

1. Phone Screen

A team member will reach out to you for a casual chat, usually no more than 30 minutes. While chatting, communication is key. We look for engineers who strengthen our core values, which are integral parts of our organization. Have you embraced curiosity by trying out new testing utilities? Have you done the right thing by taking ownership of a mistake you made in the past?

Most importantly, what are you looking for? Everyone has a different vision of the ideal workplace. We’d like to hear what motivates you in your career — whether that’s thoughtful perks or opportunities to learn. Finally, do you see LogicGate as a place where you can thrive? If so, we’re happy to be a potential next step in your journey.

2. Hiring Manager Interview

Don’t worry, we won’t be asking you to pseudo-code Dijkstra’s algorithm or tell us how to set up CD variables. This is a two-way conversation between you and a member of our engineering team, so feel free to show off and name some technologies! When you’re met with a challenging problem, what are some tools you’ve used?

We also want to hear how you like to work with other team members. Do you prefer to jump on a call and chat about technical issues, write a bulleted list of edge cases, or perhaps you appreciate starting a thread with other engineers? One of our values at LogicGate is to be as one. We hope to discover the skills you bring to LogicGate that help strengthen and empower our growing development team.

3. Tech Challenge

You’ll then receive a take-home challenge catered to the role you applied for. We haven’t slipped any hidden bugs into the code to make you squirm. Instead, we want to see how you tackle problem solving. We hope these challenges highlight your skills without wasting time with unnecessary fluff.

Overall, we’re looking for:

  • Comfort in the coding language of your stack
  • Consideration to keep code tidy and use thoughtful naming conventions
  • Ability to follow instructions and determine critical functionality
  • Recognition of existing code patterns
  • Ability to discuss your thought process in a recap

4. Onsite

The final step of our process is an onsite, which may or may not happen in our Chicago office. This is the first time you’ll get to see our app in action. Many of us hadn’t heard of GRC before starting at LogicGate, so this is a good opportunity to ask how our app helps empower customers to solve their unique challenges.

As you meet more members of the team, we’ll revisit the technical competencies and core values from earlier calls. We’d also like to hear your thoughts on the technical challenge. What was your thought process when solving the challenge? After submission, did you consider another approach that might have worked?

We’re also available to answer any questions about working at LogicGate: what perks do we offer, how closely do we collaborate, why do we have a goat for a mascot?

We recognize LogicGate is also being interviewed, so we welcome any questions that come to mind. Overall, we hope you finish this step with a good idea of what we do and how we operate. If any question remains unanswered, feel free to reach out to a member of our team.

What is it like to work at LogicGate?

We want to get you involved as soon as possible. While some of the first week is spent onboarding, you’ll be greeted with several “easy win” tickets to get your feet wet without drowning in tasks.

As your knowledge of our app grows, you’ll tackle more challenges and become familiar with your squad’s responsibilities. Over the following months, small wins become larger victories, and you’ll begin touching new parts of the app or stack, should you desire. We definitely want our candidates to explore their interests and embrace curiosity.

We embrace the agile flow at LogicGate, which you’ll notice from the daily stand and ticket pointing, to a retrospective at the end of each sprint. We also encourage pairing with one another — even in our remote-first environment. All our developers, project managers, etc. work collaboratively and are quick to jump on a call with one another to solve a bug, clean up some logic, or figure out how to implement a user story.

Using the crawl, walk, run approach also helps us develop new features. Why create a monstrous new set of changes in one fell swoop when we can disassemble a feature into smaller pieces? This helps our entire engineering team, from frontend engineers to QA testers, develop, implement, and sign off on new features.

Interested?

Find out more about our open positions here.

v2021.4.0 Release Notes

Featured Updates

Jobs

What does the future hold for a given Record? Now there is a way to tell! With the new Upcoming Job Runs by Record endpoint, API users can see a glimpse into the future of a Record's upcoming Job runs.

All Updates

New

 

Deleted

 

Deprecated

 

Changed

Method Parameter
  • Add step in query
  • Delete trigger in query
  • Add generic in query
  • Delete validated in query
  • Delete hasChild in query
  • Delete validated in query
  • Delete page in query
  • Delete size in query
  • Add hidden in query
  • Add tableReport in query
  • Delete map in query
  • Add id in query
  • Add name in path
  • Delete user in query
  • Add minUpdated in query
  • Delete record in query
  • Add direct in query
  • Add includeJiraWorkflows in query
  • Delete distinct in query

API Documentation

Check out our API Documentation for more usage information on all of the Risk Cloud's API endpoints.

v2021.3.0 Release Notes

Featured Updates

Images

Release the cat memes! Images are further supported in the Rich Text portions of the Risk Cloud platform. API users can now retrieve and upload images via the following new endpoints.

POST/api/v1/images/upload

Record Audits

Have you ever been curious how active a particular Risk Cloud Workflow is? The GET /api/v1/audit/records endpoint now accepts a Workflow ID, allowing users to filter retrieved Record Audits by Workflow.

An example usage is below (timestamps are expected in milliseconds):

All Updates

New

POST/api/v1/images/upload

 

Changed

Method Parameter
  • Add generic in query
  • Add workflow in query
  • Add trigger in query
  • Delete step in query
  • Delete entitled in query
  • Add hasChild in query
  • Add minUpdated in query
  • Delete field in query
  • Delete numericValue in query
  • Delete textValue in query
  • Add validated in query
  • Add page in query
  • Add size in query
  • Delete cache in query
  • Delete workflow in query
  • Delete hidden in query
  • Delete tableReport in query
  • Add steps in query
  • Add workflow in query
  • Delete workflows in query
  • Delete field in query
  • Add distinct in query
  • Delete direct in query
  • Delete includeJiraWorkflows in query

API Documentation

Check out our API Documentation for more usage information on all of the Risk Cloud's API endpoints.

v2021.2.0 Release Notes

Featured Updates

Favorites

Favorites are here! Users are now able to show some love to their favorite Records, Dashboards, and Reports.

The following new endpoints empower API users to manage and search their Favorites, including by type (e.g. Record, Dashboard, TableReport, VisualReport).

POST/api/v1/favorites

Record Due Date

The sun gently sets as the PUT /api/v1/records/due-date endpoint is deprecated as of v2021.2.0. API users can now migrate to PATCH /api/v1/records/{recordId}/due-date as the replacement to this endpoint.

All Updates

New

POST/api/v1/favorites
POST/api/v1/slack/state

 

Deleted

POST/api/v1/jobs/scheduled

 

Deprecated

 

Changed

Method Parameter
  • Delete generic in query
  • Add page in query
  • Add record in query
  • Delete minUpdated in query
  • Add field in query
  • Add numericValue in query
  • Add textValue in query
  • Delete hasChild in query
  • Delete minUpdated in query
  • Delete validated in query
  • Add hidden in query
  • Add tableReport in query
  • Add workflows in query
  • Delete steps in query
  • Delete workflow in query
  • Add state in query
  • Add user in query
  • Add direct in query
  • Add includeJiraWorkflows in query
  • Delete distinct in query

API Documentation

Check out our API Documentation for more usage information on all of the Risk Cloud's API endpoints.

v2021.1.0 Release Notes

Featured Updates

Record Search

Searching for Records of a particular Workflow? Summaries of record data can now be aggregated by Workflows and even Steps via the GET /api/v1/records/search/summarize endpoint.

Job History

No resume or CV necessary! Job history can now be obtained by the new GET /api/v1/jobs/history endpoint, which allows API users to obtain historical information of a given job including statuses, trigger dates, and more.

All Updates

New

POST/api/v1/jobs/scheduled

 

Deleted

 

Changed

Method Parameter
  • Add minUpdated in query
  • Delete page in query
  • Delete record in query
  • Add applicationId in query
  • Add entitled in query
  • Delete permitted in query
  • Add hasChild in query
  • Add minUpdated in query
  • Delete field in query
  • Delete numericValue in query
  • Delete textValue in query
  • Add cache in query
  • Add workflow in query
  • Delete page in query
  • Delete size in query
  • Delete hidden in query
  • Delete tableReport in query
  • Add steps in query
  • Add workflow in query
  • Delete workflows in query
  • Add map in query
  • Add nextCursor in query
  • Add size in query
  • Add nextCursor in query
  • Add size in query
  • Add field in query
  • Add record in query
  • Delete minUpdated in query

API Documentation

Check out our API Documentation for more usage information on all of the Risk Cloud's API endpoints.

2 Quick Tips I’ve learned for FE Testing as a LogicGate Dev

Tip #1: Run a Single Test in Jasmine

describe('Component: Table Report', () => {
 
  it('should render', () => {
    expect(component).toBeDefined();
  });
});
fdescribe('Component: Table Report', () => {
 
  it('should render', () => {
    expect(component).toBeDefined();
  });
});
describe('Component: Table Report', () => {
 
  fit('should render', () => {
    expect(component).toBeDefined();
  });
});

Tip #2: Add Breakpoints Using Chrome Dev Tools

Screenshot of the chrome dev tools shelf with the Source tab (third tab) selected
Kotlin at LogicGate

Here at LogicGate we are constantly on the lookout for new technology to add to our toolbelts. One of the latest additions to our tech stack has been getting a lot of attention in the JVM community after being named an officially supported language for Android development by Google. It’s Kotlin!

The Kotlin Use Case

LogicGate is primarily a Spring Boot application written in Java 8. While the MVP of the application was being developed there was an emphasis on quick features and unfortunately maintaining a sensible degree of test coverage became an afterthought. A horror, we know. However, given the sparse test suite, the task presented a green field opportunity and we were free to experiment a bit.

In comes Kotlin. We wanted to explore adding a new JVM language to our stack. We wanted to quickly produce a high volume of base tests and wanted to avoid some of Java’s verbosity. This was the perfect opportunity to try something new with relatively low risk.

Why Kotlin over Java?

Kotlin is a modern language that has a strong type system to minimize or completely eliminate null references. Kotlin also adds a more solid functional style than Java 8 does. With Java 8, you must stream everything to perform functional operations on something.

Java:

List<String> str = things.stream()
 .map(Object::toString())
 .collect(Collectors.joining(“, “));

Kotlin:

val joined = things.joinToString(", ")

We can see from this simple example that Kotlin allows the ability to write very functional style code and be readable.

This allows developers to write clean, concise, and readable functional code with less verbosity. And all the beauty of being on the JVM.

This, coupled with the Java interoperability, makes Kotlin a force to be reckoned with as a programming language of choice.

The Kotlin Experience

Tests are an amazing way to get developers familiar with Kotlin. It provides a safe place to experiment and learn without the fear of accidentally shipping bugs to production. During the early implementation of our Kotlin test suite we were able to iterate based on new ideas and inter-developer debates on proper Kotlin idioms. Since production code wasn’t at stake such refactors provided low-stress updates.

Another huge pro of Kotlin for our dev-team is its amazing interoperability with Java and, as IntelliJ users, IDE support for Kotlin is incredible. We are able to use any Java class within our Kotlin code with no problem. This was a huge benefit for us and a big reason why we chose to use Kotlin for our test suite.

We went from 0 tests to 300+, both unit and integration. All written in Kotlin! It has been a great experience and really proven to us that Kotlin can provide value on the JVM.

The Future of Kotlin at LogicGate

Now that all developers on our backend team have got their hands dirty with Kotlin we are ready to write some production code! We plan to explore additional Kotlin integration in the application through incremental conversion of utility classes. As our team grows and we scale our core product we will definitely look to Kotlin as a strong candidate for new microservices and internal projects.

Spring Boot with Neo4j & MySQL

Our customers use LogicGate to build complex process applications that link organizational hierarchies, assets, and compliance requirements across the enterprise. The dynamic nature of the platform (giving users the ability to customize objects and their attributes, workflow, etc.) can be supported by a relational database, to a point, using an entity-attribute-value model. However, for complex processes with recursively linked entities, this relational model restricts insight across deeply linked assets.

How do we access these recursively linked entities? Answer: Neo4j.

Neo4j uses nodes and relationships instead of tables and join columns. Nodes store a small amount of data where the majority of the data stored are in the relationships between the nodes. This allows for large scale traversals of recursively linked entities to be done with ease.

After scouring the Internet for resources on how to use Neo4j with another datasource I struggled with a large volume of out-dated resources. With lots of help from the Neo4j slack channel I was able to get a MySQL datasource and a Neo4j datasource running together in the same application. In this post I will explain how to configure all of it. Enjoy!

Graph database + Relational database = < 3

Neo4j 4.1.6 is the last iteration before 4.2.0 which was officially released on Jan. 25th, 2017. One would say, “Why not just use 4.2.0?” Well, 4.2.0 requires Spring Boot 1.5.0 which does not have a release version just yet. So let’s focus on the latest Neo4j release version and Spring Boot 1.4.X.

Firstly, install Neo4j. Follow the instructions found on this page. If on a Mac simply run brew install neo4j . When Neo4j is done installing run neo4j start in terminal to start up the database. That is all that is needed to install Neo4j.

Let’s dive into the Spring Boot portion. Open build.gradle file and add the following dependencies:

compile "org.springframework.data:spring-data-neo4j-rest:3.4.6.RELEASE"
compile "org.springframework.data:spring-data-neo4j:4.1.6.RELEASE"
compile "org.neo4j:neo4j-ogm-core:2.0.6"
compile "org.neo4j:neo4j-ogm-http-driver:2.0.6"

For this use case, the communication method to the Neo4j database has to be a RESTful call. To achieve this the HTTP driver can be used. There are two other driver options: Bolt and Embedded. This post will focus on using the HTTP driver.

Refresh the gradle dependencies by running ./gradlew clean build in the root directory of theSpring Boot project. After this, we can start configuring the application.

We will need to edit existing / add new annotations within the Java file that contains the application configuration.

Application Class Annotations

@ComponentScan(values = {"com.example"})

This tells Spring Boot to scan all project packages.com.example holds all the classes that pertain to both relational and graph databases. This includes @Controller, @Service, @Entity, and @Repository .

@EnableAutoConfiguration(exclude = {Neo4jDataAutoConfiguration.class, DataSourceAutoConfiguration.class})

This explicitly tell Spring Boot how to set up our datasources. This is why Neo4jDataAutoConfiguration.class and DataSourceAutoConfiguration.cass are excluded.

Currently the application class should look like the following:

package com.example;
import ...
@Configuration
@ComponentScan(values = {"com.example"})
@EnableAutoConfiguration(exclude = {Neo4jDataAutoConfiguration.class, DataSourceAutoConfiguration.class})
public class DemoApplication {
public static void main(String[] args) {
  SpringApplication.run(DemoApplication.class, args);
 }
}

Datasource Configuration Class

The next step will be to create a configuration file that will configures both the MySQL and Neo4j databases. The annotations for this class file are the following:

@Configuration
@EnableNeo4jRepositories(basePackages = "com.example.graph")
@EnableJpaRepositories(basePackages = "com.example.relational")
@EnableTransactionManagement
  • @Configuration annotation tells Spring that “This is a configuration file please load it!”. This will generate bean definitions at runtime
  • @EnableNeo4jRepositories(basePackages = "com.example.graph) will tell Spring Boot to enable all repositories under the package com.example.graph to be a neo4j graph repository
  • @EnableJpaRepositories(basePackages = "com.example.relational") will tell Spring Boot to enable all repositories under the package com.example.relational to be relational repositories.
  • @EnableTransactionManagement allows us to use annotation-driven transaction management

Now that annotations are set up let’s beginning building out our configuration class.

public class DatasourceConfig extends Neo4jConfiguration

Our class needs to extend Neo4jConfiguration so configuration for Neo4j settings can be set explicitly.

Next, create a configuration bean that will configure the Neo4j database.

@Bean
public org.neo4j.ogm.config.Configuration getConfiguration() {
  org.neo4j.ogm.config.Configuration config = new org.neo4j.ogm.config.Configuration();
  config
    .driverConfiguration()
    .setDriverClassName("org.neo4j.ogm.drivers.http.driver.HttpDriver")
    .setURI("http://YOUR_USERNAME:YOUR_PASSWORD@localhost:7474");
  return config;
}

This method wires up the Neo4j database with Spring Boot. Setting the location of the database with a username and password and we also state which driver we are using. In this case, using the HttpDriver .

The next bean sets the configuration settings in the Neo4j session that is used to interact with the Neo4j database.

@Bean
public SessionFactory getSessionFactory() {
  return new SessionFactory(getConfiguration(), "com.example.graph");
}

Another Neo4j bean that needs to be configured is the getSession bean. This allows Neo4j to integrate with the Spring Boot application.

@Bean
public Session getSession() throws Exception {
  return super.getSession();
}

Now that Neo4j is almost taken care of let’s set up the relational datasource. In this case, MySQL is used. To achieve this, creating a datasource bean as well as a entity manager bean is needed.

@Primary
@Bean(name = "dataSource")
@ConfigurationProperties(prefix = "spring.datasource")
public DataSource dataSource() {
  return DataSourceBuilder
    .create()
    .driverClassName("com.mysql.jdbc.Driver")
    .build();
}

@Primary
@Bean
@Autowired
public LocalContainerEntityManagerFactoryBean entityManagerFactory(DataSource dataSource) {
  LocalContainerEntityManagerFactoryBean entityManagerFactory = new LocalContainerEntityManagerFactoryBean();
  entityManagerFactory.setDataSource(dataSource);
  entityManagerFactory.setPackagesToScan("com.example.core");
  entityManagerFactory.setJpaDialect(new HibernateJpaDialect());
  Map<String, String> jpaProperties = new HashMap<>();
  jpaProperties.put("hibernate.connection.charSet", "UTF-8");
  jpaProperties.put("spring.jpa.hibernate.ddl-auto", "none");
  jpaProperties.put("spring.jpa.hibernate.naming-strategy", "org.springframework.boot.orm.jpa.SpringNamingStrategy");
  jpaProperties.put("hibernate.bytecode.provider", "javassist");
  jpaProperties.put("hibernate.dialect", "org.hibernate.dialect.MySQL5InnoDBDialect");
  jpaProperties.put("hibernate.hbm2ddl.auto", "none");
  jpaProperties.put("hibernate.order_inserts", "true");
  jpaProperties.put("hibernate.jdbc.batch_size", "50");

  entityManagerFactory.setJpaPropertyMap(jpaProperties);
  entityManagerFactory.setPersistenceProvider(new HibernatePersistenceProvider());
  return entityManagerFactory;
}

These beans are declared primary because the MySQL database should take precedence over the Neo4j database.

The JPA properties can be tweaked to your liking as well!

The last thing that needs to set up are the transaction managers. These manage the transactions for the relational database, Neo4j database, and then the manager for the overall application.

@Autowired
@Bean(name = "neo4jTransactionManager")
public Neo4jTransactionManager neo4jTransactionManager(Session sessionFactory) {
  return new Neo4jTransactionManager(sessionFactory);
}

@Autowired
@Primary
@Bean(name = "mysqlTransactionManager")
public JpaTransactionManager mysqlTransactionManager(LocalContainerEntityManagerFactoryBean entityManagerFactory)
  throws Exception {
  return new JpaTransactionManager(entityManagerFactory.getObject());
}


@Autowired
@Bean(name = "transactionManager")
public PlatformTransactionManager transactionManager(Neo4jTransactionManager neo4jTransactionManager, JpaTransactionManager mysqlTransactionManager) {
  return new ChainedTransactionManager(
    mysqlTransactionManager,
    neo4jTransactionManager
  );
}

The ChainedTransactionManager allows for multiple transaction managers. This means that any transaction that occurs will be delegated to each manager. If the first manager fails, the second manager will then be invoked.

I have created a repository with a demo application that can be found on GitHub.

That’s it! The application now has access to both MySQL and Neo4j! Like / comment. All constructive criticism welcomed!

This is my first blog post ever! Wahoo!