This example comes from section 4, Guide for Required Documentation, of the Vetting SOP, pages 5–6. It shows how the Residence Application Form and NIDMS work together without losing either part of the workflow.

We will use one small part of the SOP: checking an applicant's identity number, given name, and surname.

What the SOP asks us to check¶

The SOP describes checks made around the Residence Application Form:

• the identity document number is checked against NIDMS;
• a first-time application may have no identity document number;
• when a number exists, it must belong to the applicant and match NIDMS;
• the given name and surname must match the applicant's travel document; and
• the surname must never be empty.

For this tutorial, the submitted identity evidence is a Residence Permit / Card. The same pattern can be used with a national ID card or travel document when that is the required evidence.

The important modelling choice¶

Cross-checks use the resolved run profile as the authoritative NIDMS source. How a Profile Variable receives its value depends on where that fact exists:

• if the Residence Application Form contains the fact, make it a derived Profile Variable sourced from that form;
• if the form does not contain the fact, make it a defined Profile Variable and set it when the run is created or supplied by the NIDMS integration.

For example, the Identità Single Work Permit flow keeps the Residence Application Form as a real Step. Its extraction populates the derived nidms_residence_permit_number, nidms_given_names, and nidms_surname values. application_type is defined because the flow needs it at intake and the form does not provide that routing decision.

The resolved profile looks like:

application_type = renewal
nidms_residence_permit_number = 1234567A
nidms_given_names = Maya
nidms_surname = Borg

The Residence Permit / Card is another real uploaded document, so its values are document fields. Cross-checks compare the resolved NIDMS profile with that card.

NIDMS profile variables          Extracted document fields
-----------------------          -------------------------
residence permit number    <-->  Residence Permit: permit number
given names + surname      <-->  Travel Document: given names + surname

What we are going to build¶

Our small example has:

1. one defined routing variable and three derived NIDMS variables;
2. a Residence Application Form profile-anchor step;
3. Residence Permit and Travel Document evidence steps;
4. one exact check for the identity document number; and
5. one fuzzy check for the given name and surname together.

The number check runs only when a number is expected. The name check always runs, and an empty surname is a validation failure.

Profile-to-document cross-checks¶

The flow builder supports this pattern directly:

• a cross-check field set can choose Profile variables instead of a document type;
• one or more profile variables can be selected and joined into one value;
• a cross-check can have a Run when condition; and
• the engine includes the run's resolved profile value in the comparison.

The check result labels the profile side as NIDMS profile, so the reviewer can distinguish it from uploaded files.

1. Add the NIDMS profile variables¶

Create these profile variables:

For Application type, use these choices:

first_time | First-time application
renewal | Renewal

Configure each derived variable with Source document type Residence Application Form and the corresponding source field. Keep application_type as a defined creation value.

2. Add the profile-anchor and Residence Permit Steps¶

Keep the Residence Application Form Step that feeds the derived variables. Then add the Residence Permit document Step:

In Steps, select Add Step and configure:

The Residence Application Form needs residence_permit_number, given_names, and surname. The Residence Permit needs:

residence_permit_number

Add a core Travel Document Step whose fields include:

given_names
surname

The exact field names may differ in your document catalogue. Select the fields that carry these three facts.

3. Add the identity-number check¶

Create a cross-document check with:

Add two field sets to the check:

1. Profile variables → nidms_residence_permit_number
2. Residence Permit → residence_permit_number

The comparison should behave like this:

4. Add the name-and-surname check¶

Create a second check:

Add these field sets:

1. Profile variables → nidms_given_names + nidms_surname
2. Travel Document → its given-name field + surname field

The fields in each set are joined to make one full-name value. A fuzzy match is useful because harmless differences can occur:

Maya Borg       <-->  BORG MAYA
John P Smith    <-->  John Paul Smith

The check may accept differences in order, capital letters, punctuation, or a middle-name initial. It must not quietly accept a different person.

Keep the surname rule separate¶

The SOP says the surname must never be empty. Matching two full names is not enough to enforce that rule. Add required-field validation to both sources:

• nidms_surname must be present in the NIDMS profile; and
• the Travel Document's surname field must be extracted and non-empty.

If an identity document prints the person's full name in one place instead of separate given-name and surname fields, map it deliberately. Do not silently leave the surname empty.

5. Walk through one run¶

Imagine the run is created with:

application_type = renewal

Then the Residence Application Form extraction derives:

nidms_residence_permit_number = 1234567A
nidms_given_names = Maya
nidms_surname = Borg

The Residence Permit extractor returns:

residence_permit_number = 1234567A

The Travel Document extractor returns:

given_names = MAYA
surname = BORG

The result should be:

Now change the extracted Residence Permit number to 7654321A. The first check should become a blocking mismatch. The second check can still pass. Keeping the facts in separate checks tells the reviewer exactly what is wrong.

6. Check the design¶

The example is correctly modelled when:

• the Residence Application Form Step feeds the derived NIDMS Profile Variables;
• facts absent from the form remain defined/set Profile Variables;
• cross-checks read NIDMS values from the resolved profile rather than bypassing it and reading form fields directly;
• the Residence Permit and Travel Document remain real document Steps;
• the identity number is compared exactly;
• the identity-number check does not run for a first-time application with no number;
• given names and surname are compared with name-aware fuzzy matching;
• surname is required separately from the fuzzy match; and
• a mismatch shows both the NIDMS value and the extracted document value to the reviewer.

This pattern can be reused for other NIDMS facts: resolve the system value as a Profile Variable, extract the evidence value, and compare the two while preserving whether the Profile Variable was derived or set.

Next tutorial¶

Continue with a more complex example that normalises countries, company names, multi-job advertisements, and salary periods: Standardise difficult work-permit cross-checks.