This tutorial turns the two-page Checklist for New Application for Single Permit into a working Identità flow.

The checklist contains 15 numbered items. We will not create 15 unconditional Steps. Some items are application facts from NIDMS, some accept alternative documents, and some apply only to a particular job or accommodation type.

By the end, the flow will:

• collect the documents needed for every new Single Permit application;
• ask simple routing questions for conditional documents;
• enforce the checklist's document rules;
• compare important facts across the application pack; and
• show the correct manifest before a run is processed.

1. Translate the checklist before opening the builder¶

First decide what each checklist item means inside the program.

Why the Residence Application Form is different¶

For this flow, the Residence Application Form is a real core Step. Its extracted values feed derived Profile Variables. Cross-document checks use those resolved Profile Variables as the NIDMS side of the comparison instead of reading the form fields directly.

The important facts include:

nidms_given_names
nidms_surname
nidms_passport_number
nidms_address_in_malta
nidms_employment_start_date
nidms_employment_end_date

Not every routing fact appears on the form. Keep those values as defined Profile Variables and set them when the run is created. For example, application_type, submitter_type, employer_kind, and hiring_route remain set values. Do not change them to derived values without a real source field.

The NIDMS identity tutorial explains how the two kinds of Profile Variable work together.

2. Check the document catalogue¶

Before creating the flow, open the document catalogue in Admin and confirm that every requirement and accepted document type exists.

Most of the required catalogue already exists:

• Travel Document;
• Work Contract;
• Position Description;
• Proof of Advertisement;
• Declaration of Suitability;
• Health Screening Approval;
• property lease, accommodation declaration, and keeper's declaration;
• Housing Authority Approval;
• Professional Lease Attestation;
• Health Insurance;
• Driving Licence;
• Pre-Departure Course Certificate;
• Food Handling Certificate;
• Security Licence and Tag;
• Electrician Licence;
• Nursing/Midwifery Certificate; and
• Tourism and Hospitality Skills Pass.

Catalogue support used by this flow¶

The Identità catalogue includes the checklist-specific additions below. Check that they are present before activating a manually created flow:

Also confirm that the main Accommodation Evidence requirement accepts:

• Property Lease Agreement;
• Property Purchase Agreement;
• Keeper's Declaration for a hotel or guest house; and
• Declaration of Accommodation for free accommodation.

The Lease Professional Attestation must remain a separate requirement.

3. Create the empty flow¶

1. Open Flows.
2. Select New Flow.
3. Enter New Single Permit Checklist as the name.
4. Enter Documents and checks for a new Single Permit application as the description.
5. Clear Active while the flow is being built.
6. Select Create.

The empty builder contains Steps, Profile Variables, Cross-Document Checks, and Manifest Preview.

4. Add the routing Profile Variables¶

Profile Variables answer the questions that decide which conditional Steps belong in one applicant's manifest.

Create these variables with manual only as the source:

For Accommodation type, enter these choices:

rented | Rented property
owned | Applicant-owned property
hotel | Hotel or guest house
hosted_free | Free accommodation

Use separate Yes/No variables for the occupations. One applicant can need more than one extra document. For example, a catering job in hospitality may need both a Food Handling Certificate and a Skills Pass.

To add each variable:

1. Select Add Variable.
2. enter the Label and Name exactly as shown;
3. choose Choice or Yes / No;
4. leave document auto-derivation empty;
5. add a short description; and
6. select Add variable.

The officer sets these answers on the run's Application tab. An integration can populate them earlier when NIDMS and occupation routing are connected.

5. Add the always-needed Steps¶

Add these Steps first. Keep Core step selected, leave Required when empty, and use Send back when a required document is missing.

Add the Passport Step like this:

1. Select Add Step.
2. choose Identità: Passport;
3. enter order 10;
4. enter bundle Identity;
5. keep Core step selected;
6. choose Send back for a missing document;
7. leave both conditions empty;
8. enter the reviewer note from the table; and
9. select Add step.

Repeat the same pattern for the other core rows.

6. Add conditional health and accommodation Steps¶

Conditional Steps should have Core step cleared. Their condition decides whether they belong in the manifest.

Health Screening Approval¶

The checklist refers to the IDCU requirements. Set health_screening_required from the applicable health-screening policy. If the approval is required for every application handled by this flow, make the Step core and remove the variable.

Housing Authority Approval¶

Lease Professional Attestation¶

The attestation must be signed by the landlord and completed and officially stamped by the lawyer, notary, or legal procurator.

7. Add the vehicle and occupation Steps¶

Add these with Core step cleared:

Use bundle Occupation-specific evidence for all of them.

For the Driving Licence Step:

1. add the first condition, Operates an LPTV is yes;
2. add the second condition, Operates another vehicle is yes; and
3. choose ANY of rather than ALL of.

The applicant needs a licence when either driving route applies.

The supplied checklist does not explicitly limit the Pre-Departure Course to one occupation. The separate pre_departure_course_required variable avoids hard-coding an assumption. If the governing policy later says that every new application needs it, make the Step core.

8. Add document validation rules¶

Steps answer which document is needed. Validation rules answer whether the received document meets the checklist.

The flow builder does not currently expose a form for creating FlowValidationRule records. Add these through the validated flow seed or Django Admin. The supplied flow importer validates the rule structure before it updates a tenant.

Add at least these rules:

Do not put policy thresholds such as EUR 100,000 into the general money field type. Store the truthful amount and let a named business rule fail. See How validation works.

9. Add the important cross-document checks¶

Now compare the facts that should tell the same story across the application pack.

Create these checks:

Use Block severity and Send back when a mismatch means the submitted pack must be corrected. Use Flag and Flag to officer for signatures, external records, or wording that needs judgement.

The Proof of Advertisement job_titles field is a list. The fuzzy check compares each advertised job separately and passes when one candidate matches the proposed role. See Standardise difficult cross-checks and the match-type reference.

Add the NIDMS profile comparisons¶

Add a Profile variables field set to the applicable checks:

• NIDMS applicant name against Passport and employment documents;
• NIDMS passport number against the Passport;
• NIDMS Malta address against the accommodation pack; and
• NIDMS intended employment dates against insurance and accommodation coverage.

Choose the derived nidms_* variables as the reference source. The run first extracts the Residence Application Form, resolves those Profile Variables, and then compares the uploaded evidence with the resolved NIDMS profile.

10. Add reviewer notes from the checklist¶

Reviewer notes keep instructions visible beside each run requirement. Include:

• every uploaded original must be presented at the biometrics appointment;
• the passport copy must include blank pages;
• sports contracts need the association endorsement;
• vehicle-operating contracts must state the vehicle and capacities;
• the Position Description must correspond with the contract;
• accommodation evidence must name the applicant;
• a lease must show start and end dates;
• a hotel requires the Keeper's Declaration;
• free accommodation requires the Declaration of Accommodation;
• the lease attestation needs the landlord signature and professional stamp;
• an insurance quote is not a policy; and
• role-specific licences and certificates must belong to the applicant.

Notes explain what to review. Use validation rules and cross-checks for findings that must appear in Checks and affect the recommendation.

11. Test the Manifest Preview¶

Do not activate the flow until the preview produces the right list for several profiles.

Scenario A: ordinary office role in rented accommodation¶

accommodation_kind = rented
health_screening_required = yes
all occupation flags = no
pre_departure_course_required = no

Expected conditional documents:

• Health Screening Approval;
• Housing Authority Approval; and
• Lease Professional Attestation.

No driving or occupation-specific certificate should appear.

Scenario B: hospitality catering role in a hotel¶

accommodation_kind = hotel
health_screening_required = yes
food_handling_role = yes
tourism_hospitality_role = yes
pre_departure_course_required = yes

Expected accommodation document:

• Keeper's Declaration through the Accommodation Evidence requirement.

Expected extras:

• Food Handling Certificate;
• Full Skills Pass;
• Pre-Departure Course Certificate; and
• Health Screening Approval.

Housing Authority Approval and Lease Professional Attestation must be Not required.

Scenario C: LPTV driver with free accommodation¶

accommodation_kind = hosted_free
operates_lptv = yes
operates_other_vehicle = no

Expected extras:

• Driving Licence; and
• Declaration of Accommodation through the Accommodation Evidence requirement.

If both driving variables are unanswered, the Driving Licence Step should be Undecided, not silently Not required.

12. Run one complete test application¶

After the previews are correct:

1. edit the flow and select Active;
2. create a test run with a non-production reference;
3. fill every routing Profile Variable;
4. upload one file for every required Step;
5. wait for Automated review to finish;
6. check Requirements for missing and Received-with-issues documents;
7. check Documents for extraction validation errors;
8. check Checks for document-rule and cross-document results;
9. correct one extracted value and confirm that dependent results rerun;
10. replace one document and confirm that stale overrides are cleared when the computed result changes; and
11. download the vetting report and confirm that the checklist findings and SOP references are understandable.

Use the Run Detail reference while testing.

Finished-flow checklist¶

The flow is ready only when:

• every supplied-checklist requirement has a clear Step, condition, rule, or documented NIDMS source;
• alternatives are grouped into one requirement and documents needed together use separate Steps;
• every conditional Step has a Profile Variable and tested manifest scenario;
• each document type exposes the fields needed by its rules and cross-checks;
• factual field types do not contain policy thresholds;
• named SOP rules appear under Document checks;
• cross-document checks use the correct Exact, Fuzzy, Range, Signature, or External match type;
• Residence Application Form values are routed through derived NIDMS Profile Variables before cross-checking;
• a complete test run reaches Ready for decision; and
• the generated report explains both the evidence and the recommendation.