An External ID field stores an identifier from another system, such as a ServiceNow ticket number or an AuditBoard reference, on a Risk Cloud record. Each value can be used only once per field, so two records cannot hold the same external identifier.
Applies to
Builders add External ID fields to Workflows. Users with access to the Step enter and edit the value on the record. External ID is available only as a Workflow Field.
Before you begin
- Open the Application and the Workflow Step where you want the field.
- A Workflow can have up to five External ID fields. Risk Cloud blocks additional fields. See Rules and limits.
Add an External ID field
- Go to Application > Build, select the Application, and open the Step.
- Select Workflow Fields, then select + New Field.
- On the field type page, select External ID, then select Next.
- Enter a Name and a Label. Both are required. The name identifies the field in Build and Report. Users see the label on the record.
- Optional: enter a tooltip and guidance text.
- Select Save Field.
- Add the field to a Step. In the step builder, External ID fields display a tag icon.
Verify the result
Open a record at that Step. Confirm that the field appears with the label you entered.
Enter an External ID on a record
On the record, enter the identifier from the other system, such as a ServiceNow ticket number. The field looks and works like a text field.
If the value is already used in the same field on another record, Risk Cloud shows an error and does not mark the field as complete. Enter a different value or check the other record.
How External ID fields behave
- Several systems. Add one External ID field for each system, for example one for ServiceNow and one for AuditBoard.
- Field settings. Required or not required, enabled or read-only, and guidance text settings apply on the record page. You can also show, hide, enable, or make the field read-only with conditions based on another field.
- Steps and Workflows. An External ID field you add on one Step is available on other Steps in the same Workflow. It is not available in other Workflows.
Rules and limits
| Rule | Behavior |
|---|---|
| Uniqueness | A value is unique per field. Reusing it on the same field is rejected, and the API returns 409. Two different External ID fields can hold the same value. |
| Value format | Values are case-sensitive, up to 255 characters, and keep whitespace as you enter it. |
| Clearing a value | A blank or null value removes the ID from the record. |
| Fields per Workflow | You can add up to five External ID fields. Risk Cloud blocks additional fields in the UI, and the API returns 400. |
| Required | You can mark the field as Required. |
| Global Fields | Not supported. The field type is greyed out in the field type picker for Global Fields, and the backend rejects it. |
| Audit | Every set or remove is written to the field audit history. |
| Record deletion | Deleting a record frees its External ID values for reuse. |
Use External ID fields with the API
Integrations can write the identifier from a source system to a record's External ID field through the Risk Cloud API.
- Dedicated endpoints create, update, and delete an External ID field. You cannot create this field type through the general field creation endpoint.
- One endpoint sets the value on a record. It adds the value if none exists, updates it if one exists, and removes it if you send a blank or null value.
- If the value is already in use in the same field on another record, the API returns
409and does not save the value. If a Workflow already has five External ID fields, the API returns400when you add another. - Each set or remove through the API is written to the field audit history, the same as a change made on the record page.
For example, a sync job that creates a Risk Cloud record for each ServiceNow ticket can write the ticket number to the record's External ID field.
You need a field ID to write a value. To find the field IDs in a Workflow, see Risk Cloud API: Viewing Fields. Authenticate as you do for other Risk Cloud API requests.