A CUID (Collision-resistant Unique Identifier) is a 16-character alphanumeric string used to identify resources throughout the ActivityInfo platform. These identifiers are critical for use in formulas, the ActivityInfo API, and the R package, as they remain constant even if a resource's display name is changed.
Key characteristics
- Format: CUIDs consist of 16 characters using lowercase letters (a-z) and digits (0-9).
- Structure: Every CUID must begin with a letter (e.g., cw0qkvfkq6jnlx3r).
- Permanence: Unlike labels or names, a CUID is immutable once assigned to a resource.
Hierarchy and uniqueness scope
CUIDs are generated based on a specific hierarchy. Their uniqueness is either global across an entire server or scoped within a parent "container."
1. Globally Unique IDs
The following resources are assigned CUIDs that are unique across a single ActivityInfo server:
- Databases: The top-level container for all forms and data.
- Forms: Standard forms used for data collection.
- Reports: Analytical outputs like pivot tables or dashboards.
2. Container-scoped IDs
Certain resources only require uniqueness within their immediate parent container. This means the same CUID can potentially exist in different locations on the same server without conflict:
- Fields: Unique only within their specific Form. Two different forms can have fields with identical CUIDs.
- Select Options: Options in a Single Selection or Multiple Selection fields are Unique only within their specific Field.
- Records: Unique only within their specific Form. A record ID in "Form A" may be identical to a record ID in "Form B."
- Folders: Structural containers used to organize forms. The CUID of a form is only unique within a database. Two different folders can have identical CUIDs in different databases.
Practical applications
API and Integrations
When using the API to query data or update schemas, CUIDs are the primary way to target resources. For example, to fetch records from a specific form, you must provide that form's CUID (formId) to get form records.
Formulas
CUIDs are used in formulas to refer to specific fields or forms, ensuring the formula doesn't break if a field is renamed.
R Package
The ActivityInfo R package uses CUIDs for nearly all functions to reference specific resources when fetching schemas, querying data, and performing record operations such as adding, editing, and deleting.
Finding CUIDs
- ActivityInfo R package: You can use the getDatabaseTree function to list available resources and their CUIDs.
- ActivityInfo API: You can get a list of resources (folders, forms, and sub-forms) and their CUIDs in a database.
- In the Browser: CUIDs are often visible in the URL when viewing a specific database or form in the ActivityInfo web interface. In the example below, the Beneficiary Registry form CUID is visible on the address bar.
- Record CUIDs: You can view the CUID of a record in a form or a subform in the Interactive Table by clicking on “Views”, then “Select Columns”.
Check the “Record ID” option under “Available Columns” to expose the record CUIDs.
- Field CUIDs: You can view the CUIDs of the fields in a form by opening the form, clicking “Form Settings” in the top-right corner of the screen, and then selecting “Export Fields”.
This will download a CSV file showing all CUIDs for the fields in the form.
Generating CUIDs
When submitting a request through the ActivityInfo API to add a new database, folder, form, etc, you will need to generate the id of the new resource.
The Collision-resistant ids (CUID2) project has libraries in a number of programming languages for generating IDs that will be accepted by ActivityInfo.