ODS Lookup

ODS Lookup is a workflow action that searches Sharedo’s ODS for an existing person or organisation using whatever identity details are available at runtime. It helps workflow authors reduce duplicate ODS records, reconcile inbound contact channels, and pre-fill downstream participant steps with a reliable ODS identifier.

What it does

Many intake and referral processes receive incomplete data: an email address, a phone number, a name, a company number, or some combination of those fields. ODS Lookup turns those fragments into a single workflow decision:

• search ODS for likely person and organisation matches;
• score each candidate against the supplied channels;
• write the best match’s ODS id, entity type, confidence score, and matched fields to workflow variables;
• route the workflow through found, notFound, or failed.

This allows a workflow to make a clear next-step decision without re-implementing ODS search and scoring logic in every process.

Common use cases

Dedupe inbound enquiries

When a web form, email intake, or referral creates a new enquiry, run ODS Lookup before creating new parties. If a strong match is found, the workflow can branch to a review or merge path instead of creating a duplicate person or organisation.

Screen-pop and caller reconciliation

For telephony or assisted intake flows, a caller may be known by phone number, name, or email. ODS Lookup can combine those signals and return the best existing ODS record for the workflow to use in the next step.

Referral pre-fill

Referral workflows often receive referrer, respondent, organisation, or contact details from external sources. ODS Lookup can find the existing ODS record and populate participant or follow-up steps with less manual searching.

Business value

• Reduces duplicate ODS records by checking for an existing party before creation.
• Improves workflow consistency by centralising lookup and scoring rules in one action.
• Speeds up intake by returning an ODS id that can feed downstream participant, fetch, or branching steps.
• Supports partial data because the action works with any configured combination of email, phone, names, organisation name, and company number.
• Makes automation safer by exposing a confidence score and matched-field list rather than returning only a yes/no result.

Search inputs

The action can use any combination of:

• email;
• phone;
• first name;
• last name;
• organisation name;
• company number.

At least one input variable must be configured. Empty runtime values are ignored and do not contribute to the score.

Search scope

Workflow authors can configure the action to search:

• people only;
• organisations only;
• both people and organisations.

The default is to search both.

Confidence scoring

ODS Lookup assigns a score from 0 to 1 based on the fields that matched. The score is used to decide whether the found or notFound outlet should fire.

Default minimum confidence is 0.5.

Typical scoring signals include:

Scores are capped at 1.0.

Outputs

The action can write:

• matched ODS id;
• matched ODS type: person or organisation;
• confidence score;
• comma-separated matched fields, such as email,phone.

The ODS id output is mandatory so the match can be used by later workflow steps.

Workflow outcomes

ODS Lookup has three outlets:

• found — a best candidate was found with a score greater than or equal to the configured minimum confidence;
• notFound — no usable inputs were present, no candidates matched, or the best candidate was below the confidence threshold;
• failed — the ODS lookup call failed or the lookup service returned an application error.

When to use it

Use ODS Lookup when a workflow needs to decide whether a person or organisation already exists in ODS before creating or linking records.

It is especially useful in:

• enquiry intake;
• matter creation;
• referral processing;
• participant pre-fill;
• duplicate prevention;
• contact-centre or screen-pop workflows.

ODS Lookup technical notes

Component identity

• Kind: Visual Workflow action
• System name: AltOdsLookup
• Designer widget: Alt.OdsLookupDesigner
• Source path: src/vw-actions/ods-lookup
• Manifest: manifests/AltOdsLookup.wf-action.json
• Designer manifest: manifests/designer.widget.json
• Runtime template: template.ts
• Designer factory: factory.ts
• Designer view model: designer.ts
• Pure logic: scorer.ts, types.ts

Runtime architecture

The action is split into:

1. Factory (factory.ts)

• Uses defineWfActionFactory from @alterspective-engine/foundry.
• Creates Knockout observables for all configuration fields.
• Registers outlets and validation.
• Tracks workflow variables for designer integration and cleanup.

1. Designer (designer.ts + templates/OdsLookupDesigner.html)

• Provides the workflow node properties panel.
• Binds to the factory-populated action.config and action.ui fields.
• No async designer initialisation is required.

1. Template (template.ts)

• Runs server-side in the Sharedo workflow runtime.
• Reads input variable names from $model.Configuration.
• Resolves runtime values from ctx.
• Calls the tenant-installed ODS lookup plugin endpoint.
• Parses and scores candidates.
• Writes outputs to ctx.
• Fires found, notFound, or failed.

1. Scorer (scorer.ts)

• Contains pure, testable logic for:
• checking whether any input exists;
• parsing supported response shapes;
• normalising candidate rows;
• scoring candidates;
• sorting candidates by score and tie-break rules.

API dependency

The runtime calls:

POST /api/plugin/alterspective/ods/lookup

The manifest marks this as an internal/plugin API dependency because no public ODS lookup route is available in the source context. The endpoint is expected to be tenant-installed, read-only, and workflow-safe.

Request body shape:

{
  "email": "string|null",
  "phone": "string|null",
  "firstName": "string|null",
  "lastName": "string|null",
  "organisationName": "string|null",
  "companyNumber": "string|null",
  "entityTypes": "person|organisation|both",
  "enableFuzzyMatching": true,
  "pageSize": 10,
  "includeInactive": false
}

Configuration contract

StepConfig contains:

Defaults

The factory default configuration is:

{
  "emailVariable": "",
  "phoneVariable": "",
  "firstNameVariable": "",
  "lastNameVariable": "",
  "organisationNameVariable": "",
  "companyNumberVariable": "",
  "entityTypes": "both",
  "enableFuzzyMatching": false,
  "minConfidence": 0.5,
  "pageSize": 10,
  "odsIdVariable": "",
  "odsTypeVariable": "",
  "confidenceVariable": "",
  "matchedFieldsVariable": ""
}

Validation

Factory validation enforces:

• at least one input variable must be configured;
• odsIdVariable is required;
• minConfidence must be a number between 0 and 1.

Runtime also handles cases where configured input variables exist but their runtime values are empty. If all runtime inputs are empty, the action writes empty outputs and fires notFound.

Outlets

The factory registers:

Runtime success and failure handling uses Foundry workflow-runtime helpers:

• handleSuccess
• handleFailure
• classifyHttpError

Candidate parsing

parseSearchResponse supports multiple response shapes:

1. Plugin endpoint shape:

• items: [{ odsId, odsType, firstName, lastName, email, phone, ... }]

1. Public-style ODS query shape:

• results: [{ id, data: { ... } }]

1. Legacy/internal search shape:

• rows: [{ id, odsEntityType, result: "<json>" }]

Only active candidates are returned. Rows with isActive === false are filtered out.

Scoring rules

Local fallback scoring uses:

The type definitions also include fuzzy channels:

• fuzzyLastName
• fuzzyOrganisationName

The template passes enableFuzzyMatching to the plugin endpoint. If the plugin returns server-provided matchScore and matchedFields, scoreCandidates uses those values instead of recalculating local fallback scoring. This is how plugin-side fuzzy scoring can be honoured.

Sorting and tie-breaks

Candidates are sorted by:

1. score descending;
2. original result order ascending;
3. person before organisation as final tie-break.

This preserves upstream relevance ordering where scores are equal.

Output behaviour

When found fires:

• odsIdVariable receives the best candidate’s ODS id;
• odsTypeVariable receives person or organisation;
• confidenceVariable receives the numeric score;
• matchedFieldsVariable receives a comma-separated matched-channel list.

When notFound fires:

• odsIdVariable receives an empty string;
• odsTypeVariable receives an empty string;
• confidenceVariable receives the best score if available, otherwise 0;
• matchedFieldsVariable receives an empty string.

When failed fires:

• output variables are not populated by the failure branch.

Runtime safeguards

• minConfidence is clamped to 0..1, defaulting to 0.5.
• pageSize is clamped to 1..50, defaulting to 10.
• Empty input values are ignored.
• Response body preview logging is truncated to reduce oversized log entries.
• Failed HTTP responses and plugin application errors route to failed.

Build and deployment

This action follows the repo-wide workflow action conventions under src/vw-actions/{slug}.

Do not add per-component deploy scripts. Use the unified deployment wrapper:

npm run deploy:tenant -- --tenant <tenant> --widget AltOdsLookup

The designer widget may require a separate first-time deployment pass depending on tenant state and Foundry packaging behaviour:

npm run deploy:tenant -- --tenant <tenant> --widget Alt.OdsLookupDesigner

Tests

The behaviour signal includes a scorer test suite covering:

• search string construction;
• input detection;
• parsing plugin, public, legacy, malformed, and empty response shapes;
• inactive entity filtering;
• company number extraction;
• server-provided match metadata;
• email, phone, name, organisation, and company-number scoring behaviour;
• phone formatting handling;
• no-match scoring.

How it's built

Git is the single source of truth — the component lives at src/vw-actions/ods-lookup. Deployment is to the Sharedo IDE; the manifest defines how the platform loads it.

ODS Lookup user guide

Purpose

Use ODS Lookup when a workflow needs to find an existing ODS person or organisation from partial details such as email, phone, name, organisation name, or company number.

The action returns the best match and a confidence score so the workflow can decide whether to use the existing ODS record, ask for review, or continue as a new record.

Add the action

1. Open the workflow designer.
2. Add the ODS Lookup action from the Alterspective action category.
3. Give the action a clear name, such as:

• Lookup referrer in ODS
• Check for existing person
• Find organisation by company number

Configure inputs

In Inputs, choose one or more workflow variables to search with.

Available inputs are:

• Email variable
• Phone variable
• First name variable
• Last name variable
• Organisation name variable
• Company number variable

You must configure at least one input variable.

At runtime, the action only uses variables that contain a non-empty value. For example, if you configure email and phone but the phone value is blank, only email contributes to the lookup.

Choose search scope

In Search options, choose Search across:

• Both — search people and organisations.
• Persons only — search only person records.
• Organisations only — search only organisation records.

Use Both when the incoming data could be either a person or an organisation. Use a narrower option when the workflow already knows what type of party it is looking for.

Configure fuzzy matching

The Enable conservative fuzzy matching for surnames and organisation names option allows the lookup service to tolerate light spelling differences.

Recommended guidance:

• Leave it off for strict dedupe checks.
• Turn it on where spelling variation is common and a human review step follows.
• Avoid relying on fuzzy matching alone for fully automated high-impact decisions.

Set minimum confidence

Minimum confidence controls when the action fires found.

Default: 0.5

The action scores the best match from 0 to 1.

Examples:

• 0.5 means an email match, company-number match, or a strong combination of other details can be enough.
• 0.8 requires stronger evidence and is better for more automated linking.
• 0.3 is more permissive and may be useful before a manual

How to use it

In the Visual Workflow editor, find ODS Lookup in the toolbox under the Alterspective category and drag it onto a step. Configure its inputs/outlets in the node's designer panel.

For the authoritative configuration fields and behaviour, see the component's designer help panel and the source linked in the footer.