Configuration model

Harmoney is configured by a set of artefacts — lists, questions, providers, form definitions, flow definitions, dossier definitions, FSP definitions and more — that refer to each other by identifier. This page explains how those artefacts are shaped, in which order they have to be created, how a reference to another artefact is resolved, and how to read the generated schemas this site publishes.

Read it before configuring an organization from an empty state. For a task-by-task walkthrough of that same journey, see the Step-by-step guide to a new set-up.

The three layers of an artefact

Every configuration artefact is built from the same three layers. Getting a configuration right means getting all three right, and each of them is documented in a different place.

Layer	What it is	Where the reference is
Envelope	the outer, fixed shape of the artefact — its identifier, its lists of sub-objects, and which of those are mandatory	the ## Reference section on the artefact's own page, where one is published
Settings	the free-form settings object carried by almost every artefact, whose shape depends on a sibling type field	the page of the module, flow step, action, validation or provider named by that type field
References	plain string fields holding the identifier of another artefact	How references are resolved on this page

The envelope

An exported configuration file always has the same three top-level keys:

Shape of every configuration file

{
  "type": "ROLE",
  "version": 1,
  "value": {
    "identifier": "my-role"
  }
}

• type — which kind of artefact the file holds. It is the value listed in the Creation order table below, and it is what decides when the file is imported when several files are imported together.
• version — the technical version of the configuration format. It is not a functional version.
• value — the artefact itself. Where a schema is published for an artefact, the ## Reference section of its page presents the schema of this object.

The settings

Most artefacts carry a settings object next to a field that says which type of thing is being configured — a module, a flow step, an action, a validation or a provider. That type field decides which settings apply:

A module and its settings inside an FSP definition

{
  "financialSpModules": [
    {
      "module": "RBA",
      "settings": {
        "fullDueDiligenceTimeout": 120
      }
    }
  ]
}

For the three type fields whose values are a fixed list — a module inside an FSP definition, a flowStep inside a flow definition, and a metric inside a dashboard — the published schema resolves settings itself. It states, per value of the sibling field, which settings shape applies, so a tool validating your file against the schema checks the settings object too. The schema view on this site does not display those branches, so to read the fields of one particular settings object, open the page for the type value.

The other settings objects — an action, a validation, a conditional section, a provider — name their type as an implementation class rather than a value from a fixed list, so the schema cannot resolve them and leaves them free-form.

Either way, look the type value up in the documentation: the page for that module, flow step, action, validation or provider carries the schema and a worked example of the matching settings object. Pages are named after the value that appears in the payload, so searching the site for the value itself finds the page that describes it.

The references

A field whose name ends in Identifier — or that holds a list of identifiers, such as forRoles — points at a different artefact. Those artefacts must already exist. That is what makes the creation order below a hard requirement rather than a recommendation.

Creation order

When several configuration files are imported together, they are grouped by their type and imported in a fixed order, so that an artefact is never imported before the artefacts it refers to. Within one type, files are imported in file-name order — except FSPs, which are ordered so that a parent FSP is imported before the FSPs that reference it.

Create artefacts in the same order when configuring by hand.

#	type	Artefact	Depends on
1	VAULT	secret values, referenced from provider settings as $vault{key}	—
2	WHITE_LABEL	white labels	—
3	REPORT_QUERY	report queries	—
4	TRANSLATIONS	translations	—
5	TASK_LIST	task list definitions	—
6	LIST	lists	—
7	FLOW_OPTION_DEFINITION	flow option definitions	—
8	PROFILE_DEFINITION	profile definitions	—
9	QUESTIONS	questions	—
10	PROVIDERS	providers	lists, questions
11	FORM	form definitions	questions
12	FLOW	flow definitions	providers, form definitions
13	ROLE	roles	—
14	DOSSIER_STATUS_TRANSITIONS	status transition definitions	roles
15	DOSSIER_DEFINITION	dossier definitions	status transition definitions, flow definitions, form definitions, flow option definitions, profile definitions, task list definitions
16	FSP_DEFINITION	FSP definitions	dossier definitions, form definitions, providers
17	FSP	FSPs	FSP definitions

The dependencies that drive that order:

note

Roles come before status transitions Roles have no dependencies of their own, so they are easy to leave until last. Do not — a status transition definition validates the roles in its forRoles lists against the roles that already exist, and fails the import if one of them is missing.

Form definitions appear twice on purpose. A flow definition's flow steps point at sections of a form definition, and an FSP definition's dossier questionnaires point at whole form definitions, so the forms have to exist before either.

How references are resolved

A reference is resolved by matching the identifier string against the artefacts that already exist in the same organization:

• The target must already exist. A reference to an artefact that is not there fails the import of that file with an error naming the missing identifier. Nothing is created implicitly.
• The identifier is matched exactly as written. No trimming and no case conversion is applied to a reference before it is matched, and some references — the questions used in a form definition's sections and the forRoles of a status transition — are matched in memory against the stored identifier, so my-role and My-Role are two different values there. Always write the identifier exactly as it is defined on the artefact it points at.
• References never cross organizations. An artefact resolves only against the artefacts of the organization it is imported into. A small number of artefacts, such as the shared flow option definitions delivered with the product, are also visible to every organization.
• Identifiers are unique per organization and are meant to be stable. Renaming an artefact's identifier does not update the artefacts that point at it, so those references break. Treat an identifier as permanent once anything refers to it.
• An identifier may contain only letters, digits, underscores and hyphens. This is checked when the artefact is created.

The reference fields, and the artefact each one points at:

Field in the payload	Points at	Page
listIdentifier	a list	Lists
forRoles	roles	Roles
reportIdentifier	a report query	Reports
questionIdentifier	a question	Questions
providerIdentifier, providers, identityProviders	providers	Providers
section	a section of a form definition	Form definitions
coveredBy	a flow step of the same flow definition	Flow definitions
dossierDefinitionIdentifier	a dossier definition	Dossier definitions
formDefinitionIdentifier	a form definition	Form definitions
flowDefinitionIdentifier	a flow definition	Flow definitions
profileDefinitionIdentifier	a profile definition	Profile definitions
taskListDefinitionIdentifier	a task list definition	Task lists
flowOptionDefinitionIdentifier	a flow option definition	Flow option definitions
dossierStatusTransitionDefinitionIdentifier	a status transition definition	Status transitions

Two more kinds of string field look like references but are not, and no artefact has to be created for them: fieldPath, path, inputFieldPath and answerSource hold a dotted path into a data structure, and fields such as className or implementationClass name an implementation that the application supplies. Their valid values are listed on the page of the setting that carries them.

An artefact's own identifier is not a reference. It names the artefact being defined, and it is the value that other artefacts will use to point at it.

How to read a rendered schema

Most configuration pages present a schema, generated from the application code, listing the fields of an artefact or of a settings object with their types and descriptions. The schema is the reference; the prose around it gives the context. Every published schema also carries at least one complete worked example, shown underneath the fields.

A generated schema is accurate about what it states, but there are things the application enforces that it cannot express. Read it with these in mind.

A field missing from the mandatory list is not necessarily optional. The import envelopes — the ## Reference section of each artefact page — do state which of their fields are mandatory. Most settings schemas do not yet, so on those, treat the field description as the authority on whether a value is needed.

An object with no fields means one of two things. Either the object is genuinely free-form, such as a map of your own keys to your own values, or it is a settings object the schema could not resolve. Typed maps do state their value type, so an object that lists no fields and no value type is one of those two cases. A module's, flow step's or metric's settings is resolved by the schema from its sibling type field even though the view above does not show it; an action's, validation's, conditional section's or provider's is not, and there the sibling type field is what tells you which page describes it.

An identifier field does not list the values you may use. The valid values are the artefacts of your own organization, which the generated schema cannot know. The description of the field says which kind of artefact it points at; How references are resolved above lists the same mapping for every reference field, with a link to the page for that artefact type.

Rules that span more than one field are written in the descriptions. Constraints such as "each module may appear only once" or "when this list is empty these defaults apply" have no structural equivalent in the schema, so they live in the description of the field they constrain. Read the descriptions of the fields you fill in, not only their types.

The character rule for identifiers is in the description, not in the schema. An identifier field is typed as a plain string. That letters, digits, underscores and hyphens are the only characters allowed is stated in the field's description.

🔗 References

• Step-by-step guide to a new set-up — the same journey as a task list.
• Libraries — the reusable definitions most of the artefacts above live in.
• FSP Definitions — where the libraries come together.