How do I create a target state definition?

A target state definition (or just definition) is a named list of configuration resources you’d like a domain to match: the data types, property types, transaction types, recipes, workflows and so on that drive the LUSID platform. See all configuration resources.

You build a definition once, store it in a registered source so it is versioned, and deploy it to as many domains as you like. Editing a definition never changes a domain on its own.

Note: You can pick resources by hand (as described in this article) or copy all from one domain to another.

Prerequisites

• At least one registered source. See how to register a source.

• The entitlement to create and save definitions. If you can see Target State Definitions under Data Management but the New definition button is missing, you have read-only access.

• To pull resources from a domain, access to the cell that owns it.

Method

Step 1: Create the definition

1. Navigate to Data Management > Target State Definitions and select New definition.

2. Under Identifier, enter a Scope and a Code, for example default and eod-holdings. Together these become the deployment name that is managed in every domain you deploy to. Letters, numbers, dashes and underscores only.

3. Under Where is it stored?, select the Source that will hold the definition. No source is preselected, even if you have only one.

4. Check the File path in this source. Admin Portal suggests <source folder>/<code>.json. You can change it, but the path must end in .json.

5. Select Create & add resources. The definition is created as an empty file in the source.

If a definition with the same scope and code already exists, Admin Portal tells you where it is stored and asks you to choose a different code.

Step 2: Add configuration resources from a domain

You can add configuration resources individually by hand or copy them them all from one domain to another. To add individually:

1. Select Add resources from a domain (or Add resources in the header).

2. In the Add resources from a domain dialog, choose a cell, then a domain within it, then select Continue. Reading a domain never changes it.

3. On the Select resources page, select Choose resource types and tick the types you want to browse. A domain typically holds far more resources than are worth listing at once, so nothing is listed until you choose. If the definition already holds resources, a shortcut offers Show only the N types this definition already uses.

4. Tick the configuration resources you want. Use the search box to narrow the list. Select all N ticks every row currently shown. Resources already in the definition appear ticked, greyed out and marked In definition.

5. For each ticked row, the Behaviour column lets you choose Resource or Reference:

   • Resource: the definition manages it. A deployment creates, updates and removes it to match.

   • Reference: it must already exist in the target domain. The definition uses it but never changes it.

6. Select Add N to definition.

If your selection depends on resources the definition does not hold, the Dependencies found dialog lists them. Each dependency defaults to Reference, the safe choice because it changes nothing in the target. Switch one to Resource if you want the definition to manage it too. Select Add selection + N dependencies to continue, or Back to selection to add nothing.

You return to the builder with the new resources in place. Each added resource records the domain it was pulled from in the Pulled from column.

Step 3: Optionally edit values

You can change the values a definition holds without touching any domain. Edits apply to the definition only.

To edit one resource:

1. In the builder, select the pencil icon (Edit values) at the end of the row.

2. Change any field. Simple values edit as text. Structured values edit as JSON, and Admin Portal refuses to save while any JSON is invalid.

3. Select Save changes.

To change one field across many resources, for example to move everything from one scope to another:

1. Optionally tick the resources you want to change. Then select Transform values in the toolbar, or Edit values of N selected… in the selection bar.

2. Under Apply to, choose All N shown or Only the N selected.

3. Choose the Field, then under Where the value is choose an existing value or any value, and enter the new value under Set it to.

4. Select Apply to N resources.

Changed cells are highlighted, and the header shows N with edited values. The Unsaved changes chip appears until you save.

Step 4: Set write behaviour

Write behaviour decides what a deployment does when a resource is already in the domain, and what happens to it when you take it out of the definition. You can set it on one resource, on a selection, or as a default for the whole definition.

• One resource: select the value in its Write behaviour column.

• Several resources: tick them and select Set write behaviour (N) in the selection bar.

• Whole definition: select Write behaviour: ... in the toolbar. This default is added to every resource and can only add protections. A resource that chooses less still gets the default.

Choose one of five presets:

Under Advanced you can combine the two choices directly: what to do When it already exists in the domain and When it is removed from this definition.

Resources you pull in from a domain start as Adopt, because they were read from a live domain and a plain create would fail when deployed back to it. References have no write behaviour, because the definition never creates, updates or deletes them.

Three points are worth knowing before you rely on write behaviour:

• It keys off the deployment's own record of what it has deployed before, not off what happens to be in the domain.

• Provision and One-shot do not stop the first create. A resource the deployment has never created is still created.

• Delete protection is read from the last deployment, so a change applies from the next deployment onwards. Protecting a resource and then removing it takes two deployments.

Select Apply. The header shows N with changed write behaviour until you save.

Step 5: Optionally remove resources

• One resource: select the bin icon (Remove from definition) at the end of its row and confirm with Remove. The resource stays in every domain it already exists in until a deployment applies the change. A reference cannot be removed here, because the definition uses it but never changes it.

• Every resource: select Remove all resources in the header and confirm with Remove all. This empties the definition, references included.

Nothing is saved until you select Save changes.

Step 6: Save or discard

• Save changes writes the definition straight back to its source, at the path you chose when creating it. For a Git source this is a commit to the configured branch with the message Update target state definition <scope>/<code> via Admin Portal. There is no commit message to type and no branch to choose. On success the button reads Saved.

• Discard changes returns the definition to the last saved version. The confirmation names what will be thrown away, such as 2 edited resources, 1 added resource and 3 removed resources. It cannot be undone.

If you navigate away with unsaved changes, Admin Portal asks whether to Discard changes or Continue editing.

If someone else saved the same definition while you were editing, saving fails with a message that the definition changed in its source. Select Reload definition to pick up their version. Your unsaved edits are lost, so copy anything you need first.

Other ways to bring a definition in

• Upload definition on the list page opens a definition file from your computer in the builder for review. The upload is not stored anywhere until you select Save to a source and choose a Source and path.

• Export Definition in the builder header downloads the current definition as <scope>-<code>.json.

• Upload Target State Definition on a Source's row menu saves a file straight into that Source.

Working with large definitions

When a definition holds more than 1,000 resources, the builder starts every resource type collapsed and shows a banner such as 20,118 resources across 87 types. Sections start collapsed to keep the page responsive. Expand a type with the chevron beside its name, or select Expand all and confirm. Search and the Scope and Resource type facets work on collapsed sections too.

A definition file may be at most 50 MB. Above 5 MB it becomes slow to load, compare and deploy.

Troubleshooting

Some resources are flagged as reference only and held as managed. Certain resource types can be named by a definition but never created, updated or deleted by one. If a definition file holds such a type as a managed resource, the builder shows a warning and a Hold as references button. Select it before deploying.

"N resource entries in this definition could not be read and are not shown." The definition file contains entries the builder cannot parse. Saving removes them. If you did not expect this, discard your changes and inspect the file in your Source.

The definition list looks out of date. Select Rescan in the notice at the top of the list. Admin Portal reads the definitions from every Source when you open the list, and reports any Source it could not read.

FAQs

What is the difference between a resource and a reference? A resource is managed: the definition creates, updates and removes it. A reference must already exist in the target domain and is never changed by the definition. Use References for shared prerequisites you do not own, such as a data type maintained by another team.

Does editing a definition change my domain? No. The definition is the desired state. Nothing changes in a domain until you deploy the definition, and every deployment shows you the full plan first.

Can I remove several resources at once? Not as a selection. You can remove one at a time, or remove every resource with Remove all resources.

Why do some definitions show a Read-only badge? They are platform-owned and maintained by FINBOURNE. You can view and deploy them but not edit them.