Risk Cloud API: Update Record User Groups

Updated on: April 23, 2024

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.

PUT/api/v1/records/{record-id}

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.

GET/api/v1/internal/userGroups/default?record={record-id}

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.

GET/api/v1/userGroups?page=0&size=1000

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.

PUT/api/v1/records/{record-id}

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.