Workflows and Records

How records relate to workflows, and which API to use to update a contract.

In the Ironclad app, a contract in progress and the finished contract look like one thing. The API splits them in two:

  • A workflow is the process that produces a contract: create, review, sign, archive.
  • A record is the contract's entry in the repository.

Every workflow has a record behind it. Which API you use to change a contract depends on whether its workflow is still running.

How they're linked

  • A record created by a workflow has source.type set to workflow, and source.workflowId is that workflow's ID.
  • Once a workflow reaches its Archive step, its recordIds lists the records it created. Before then, recordIds may be missing even though the record exists.

While the workflow is in progress

While a workflow is active or paused, the workflow owns its record. Every time the workflow changes, and again at the Archive step, Ironclad rewrites the record from the workflow's data, including:

  • the record's name, type, and properties
  • links to related records, and parent and child relationships
  • user and group access

If you change that record through the Records API during this time, the request succeeds, but the change is overwritten the next time the workflow changes.

To change the contract while its workflow is in progress, update the workflow instead:

  • Update Workflow Metadata (PATCH /workflows/{id}/attributes) updates workflow fields. The workflow must be in the Review step.
  • For roles, approvals, signers, and documents, use the matching endpoints under /workflows/{id}.

After the workflow completes

Once a workflow is completed, its record is in the repository. Ironclad still keeps the workflow's own tracking properties up to date, such as workflow dates and step durations, but it stops rewriting the rest of the record. From then on, update the contract through the Records API, for example Update Record Metadata (PATCH /records/{id}) or Replace a Record (PUT /records/{id}). Those changes are kept.

If a workflow is cancelled before it completes, its record is never added to the repository.

Summary

Workflow statusUpdate the contract withRecords API changes
active, pausedWorkflows APIOverwritten by the workflow
completedRecords APIKept

Did this page help you?