Build a Workflow

Workflows let you run code in response to record changes. A common pattern is validation: when a deal moves to a new stage, check that the required fields are filled in and flag the record if they aren't.

How workflows work

A workflow fires in three steps:

1. A record is added to a list (the trigger).
2. Clarify runs your JavaScript code.
3. Your code processes the record and writes changes back via the API.

Your code receives an input object and the API key in the environment:

Example: validate on stage change

This workflow validates that a deal has the required fields before it can move to Closed Won, and writes a plain-language error back to the record if not.

// Guard against loops: never react to changes our own workflows/API made.
if (input.actor.source === 'workflow' || input.actor.source === 'api-key') {
  return;
}

var record = input.record;
var attrs = record.attributes;

// Only act when the deal entered "Closed Won".
if (attrs.stage !== 'closed_won') {
  return;
}

var missing = [];
if (!attrs.amount) missing.push('amount');
if (!attrs.close_date) missing.push('close date');
if (!attrs.company_id) missing.push('company');

var error = missing.length ? 'Cannot close: missing ' + missing.join(', ') : '';

await fetch(
  'https://api.clarify.ai/v1/workspaces/' +
    input.workspace +
    '/objects/deal/records',
  {
    method: 'PATCH',
    headers: {
      Authorization: 'api-key ' + process.env.CLARIFY_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        id: record.id,
        type: 'record',
        attributes: { validation_error: error },
      },
    }),
  },
);

Key patterns

Loop guard

Every workflow that writes data must check the actor first. If you don't, your own write re-triggers the workflow and you get an infinite loop. Bail out when input.actor.source is "workflow" or "api-key".

Fetching the full record

The trigger payload only includes the fields involved in the change. If you need other fields, GET the record first:

var res = await fetch(
  'https://api.clarify.ai/v1/workspaces/' +
    input.workspace +
    '/objects/deal/records/' +
    input.record.id,
  { headers: { Authorization: 'api-key ' + process.env.CLARIFY_API_KEY } },
);
var full = (await res.json()).data;

Reading old values

input.diff carries the before/after for each changed field — useful when you care about what a field changed from, not just its current value.

Reporting validation errors

Write errors to a text field on the record (as above) rather than creating tasks. It keeps the feedback attached to the record and avoids task spam on repeated edits.

Tips

• Test against a single record before pointing the trigger at a full list.
• Double-check that your list filters match exactly the records you intend to process.