Workflow attributes (also referred to as "fields" in the Ironclad app) can be accessed and updated using several of the workflow-related endpoints in our REST APIs. Each workflow attribute is assigned an API ID that is unique to the workflow, based on the label defined for the attribute in the Ironclad app.

📘

Field Codes != Attribute IDs

Don't confuse the attribute IDs in the REST API with the "field codes" that are used in workflow designer. Field codes are used to refer to fields in our document editor, to indicate where in a contract document a field value should be inserted. This field code is distinct from the attribute ID, and may or may not have the same value as the attribute ID for a field.

Attribute ID Format

Workflow attribute IDs are formatted as a "camelCased" identifier based on the attribute's label. A field with the label "Total Contract Value" will (typically) be exposed in our APIs with an attribute ID of totalContractValue. The "typically" here refers to some possible exceptions that are explained in the rules below.

📘

Legacy Attribute IDs

The format for new attribute IDs created in Ironclad was changed as of our release on April 13, 2022. This change only affects new attributes created after that date - workflows and their attributes created before that date used a random unique identifier for attribute IDs, and those IDs will continue to use their existing IDs in order to sustain existing integrations built by Ironclad users. For more details on this and tips for managing workflows using the legacy attribute ID scheme, see the article on legacy attribute IDs.

The attribute IDs are formatted according to the following rules:

• The first letter is always lower-cased, regardless of the case of the first letter of the field label.
• Only alphanumeric (a-z, A-Z, 0-9) characters are included in the ID. Non-alphanumeric characters (including spaces) will be ommitted from the ID.
• The next letter after any omitted non-alphanumeric characters will be capitalized.
• All other characters in the ID (besides the characters found after omitted characters) will be lower-cased regardless of their case in the field label.
• The length of the ID is limited to 50 characters. Excess characters in the field label after the first 50 mapped characters will not be included in the ID.
• If you create a field label that will generate an identical attribute ID to another existing field in the same workflow (according to the rules above), then the resulting attribute ID will have a number added as the final character of the attribute ID to distinguish it from the existing ID. E.g., if you have a field labelled "My Field" (with attribute ID myField), and then create a field in the same workflow labelled "My_Field", the attribute ID for the new field will be myField1. If you attempt to assign a field label in Ironclad that is indentical to another existing field label in the same workflow, then you will receive an error that the field label is already in use.

The table below shows some example mappings from field labels to attribute IDs.

Changing Field Labels and Attribute IDs

Once a field has been created and an attribute ID is mapped to it, changing the field label will not change its attribute ID. If you want to force the creation of a new attribute ID to match an updated field label (e.g., if you change a field label from "Requires Tax" to "Does Not Require Tax", and you don't want the attribute ID to remain as requiresTax), you will need to delete the field entirely and create a new field in the workflow.

It's important to note a few things related to deleting and recreating fields, however:

• Deleting a field will remove the field from any Salesforce or other integration workflow mappings, so you will need to recreate these mappings in your integration configuration after creating the new replacement field.
• Conditions and formula fields that make use of fields that are deleted may need to be reviewed and updated in order to work properly, since the deleted fields will be removed from rules in the condition. Also, fields that are re-created with the same or similar labels can potentially be re-inserted into the conditions or formulas that referenced the deleted fields, which may not be the result you intend.
• Tables and their column fields will need to be removed from the workflow document(s) and recreated in order to have their attribute IDs updated. Column fields can be removed from their table and recreated in order to generate a new attribute ID for them. Attribute IDs for tables will only be recreated if the table is deleted and recreated entirely.
• If a workflow has been launched before you delete the field and recreate it, the in-flight workflow will retain its original attribute IDs since it will be running on a previous version of the workflow template.
• Causing a new attribute ID to be generated may break custom integrations you have built using the Ironclad REST APIs.

Given all of this, before you delete and recreate any workflow fields, be sure that you review where the affected fields may be used in workflow conditions and formulas, Salesforce mappings, and/or custom integrations and be ready to make appropriate changes after the new fields are created.

Workflow Attribute IDs and Record Property IDs

Each workflow attribute is mapped to a corresponding record property in the repository, which will be used to identify the corresponding properties generated in records when the workflow is archived. Usually, the record corresponding to a workflow field will have an ID that starts with the mapped attribute ID of the workflow field, appended with an underscore and then a random UUID. So as an example:

Note that there are situations where workflow attributes can be mapped to different record properties because of equivalencies between workflow fields in the same workflow. The details of these record property mappings will be described in a future article.