Recipes

Relay safety flags

Pass on safety flags wherever a person sees an item: on screen, in a spreadsheet, on a quote, or in what you give an assistant.

This is a worked example, not a supported connector. Interchange does not build or run connectors. You own the code you write from it, and the support boundary applies. Read the support boundary.

This recipe needs no key.

How it works

  1. Flags are data

    Each flag has a stable code, a severity and a message written to be shown as it is. Do not rewrite the message, and do not drop a flag because you do not know its code. New codes are added.

  2. Look on every shape

    Flags are on search results, on match candidates, on items and on equivalents answers. A view built from a search result still needs them.

  3. Do not rely on colour

    Write the severity as a word. A red icon alone fails anyone who cannot see it.

  4. No flag is not a clean bill

    An empty list means none is known. It does not mean the part is right for the job.

  5. Carry them into exports

    A flag in a CSV, a purchase order line or a prompt is a flag that reaches the person who orders the part.

The code

Node 22, no libraries. Adapt it to your language and your storage.

JavaScript: show flags on screen, in CSV and to an assistant
// A flag is data with a stable code and a message written to be shown as it is.
// Show it wherever a person sees the item: search results, candidates, the product page, a quote, an export.
export function renderFlags(flags) {
  if (!flags || flags.length === 0) return ""; // no flag means none is known, not that the part is safe
  return flags
    .map((f) => {
      // The severity is written out, so it never depends on a colour alone.
      const label = f.severity === "warning" ? "Warning" : f.severity === "caution" ? "Caution" : "Note";
      return label + ": " + f.message;
    })
    .join("\n");
}

// Flags are on three shapes. Pick them up from each, so a view built from a search result is not missing them.
export function flagsFor(shape) {
  return shape.safety_flags ?? [];
}

// For a spreadsheet or a purchase order line, the flags go in a column of their own and are never trimmed.
export function csvRow(item) {
  const cell = (s) => '"' + String(s).replace(/"/g, '""') + '"';
  return [item.ix_id, item.name, renderFlags(flagsFor(item))].map(cell).join(",");
}

// If you pass an answer to a language model, pass the flags and the disclaimer in the words given, not a summary.
export function forAssistant(answer) {
  return JSON.stringify({
    ix_id: answer.ix_id,
    equivalents: answer.equivalents,
    safety_flags: answer.safety_flags,
    disclaimer: answer.usage.disclaimer,
    data_set: answer.meta.data_set,
  });
}

Watch for

  • Show usage.disclaimer next to the result as well. Every answer carries it.

The calls are described in the API reference.