Deploy & ALM

Business data

Move reference records between environments with a data specification, and control what happens to lookups that don't exist in the target.

Logic often depends on reference records such as case types, document templates, approval levels and SLA tiers. They are data, not customizations, so they don’t travel in the solution. A data specification lists which tables and columns to export; export turns it into a data file, and import loads that file into the target environment.

Use this for reference and configuration data. Transactional data (customers, orders, cases) doesn’t belong in a release.

Move reference data

Write a data specification (below) and commit it, for example as specs/reference-data.xml.

Export the records with the project:

flowon-dynamics export -c "$DEV_CONNECTION" -p "Contoso Service" \
  --data-spec-file-path ./specs/reference-data.xml -o ./artifacts

The records are written to ./artifacts/data.xml.

Import them in the target environment:

flowon-dynamics import -c "$UAT_CONNECTION" --data-file-path ./artifacts/data.xml

The data specification

<DataSpecs>
  <Entities>
    <Entity logicalName="crm_casetype">
      <Columns>
        <Column name="crm_name" />
        <Column name="crm_defaultpriority" />
        <Column name="crm_slatier" importBehavior="FailIfNotExists" />
        <Column name="crm_defaultqueue" importBehavior="SetToNullIfNotExists" />
      </Columns>
    </Entity>
    <Entity logicalName="crm_documenttemplate" viewName="Active Document Templates">
      <Columns>
        <Column name="crm_name" />
        <Column name="crm_body" />
        <Column name="crm_casetype" importBehavior="SkipRecordImportIfNotExists" />
      </Columns>
    </Entity>
  </Entities>
</DataSpecs>

Entity settings

Setting	What it does
`logicalName`	The table to export. Each table can be listed once.
`<Columns>`	The columns to export. Include the table’s primary name column: records are matched by name in the target.
`viewName`	Optional. Export only the records in this Dataverse view of the table.
`<fetch>`	Optional. A FetchXML query, placed inside `<Entity>`, that selects the records to export.
`exportBehavior`	Optional. `DetectDuplicates` stops the export when two records have the same name; `IgnoreDuplicates` ignores them.

Import behaviors for lookups

When a record has a lookup, the import first looks for the referenced record by id, then by name. If it isn’t found, the column’s importBehavior decides what happens:

`importBehavior`	When the referenced record is missing	Use it for
`FailIfNotExists`	The import stops with an error.	Dependencies that must be there, such as the SLA tier of a case type.
`SkipRecordImportIfNotExists`	The whole record is skipped; the import continues.	Records that make no sense without their parent, such as templates of a case type that doesn’t exist.
`SetToNullIfNotExists`	The lookup is left empty; the record is imported.	Optional references, such as a default queue.
`CreateIfNotExists`	A record with that name is created and linked.	Simple lookup tables where a record with just a name is enough.

Set an import behavior on every lookup column whose target might be missing in some environment.

Many-to-many relationships

To move the links of a many-to-many relationship, add a <Relationships> section with one entry per relationship, giving its name and the two tables as first and second.

Steps before and after the import

A <PreImport> or <PostImport> section, for the whole file or for one table, runs commands around the data import. Two commands exist: disable-step and enable-step, which turn a Dataverse plug-in step off and on, for example so that an audit plug-in doesn’t fire while reference data loads.

<PreImport>
  <Command name="disable-step">
    <StepName>Contoso.Audit: Create of crm_casetype</StepName>
  </Command>
</PreImport>
<PostImport>
  <Command name="enable-step">
    <StepName>Contoso.Audit: Create of crm_casetype</StepName>
    <ContinueOnError>true</ContinueOnError>
  </Command>
</PostImport>

If a command fails, the import stops, unless the command has ContinueOnError set to true.

How it behaves

Records are matched by their name (the primary name column). An existing record with the same name is updated; otherwise a new one is created. Names must therefore be unique: two records with the same name in the export or in the data file stop the operation with an error.
Every table and column in the specification must exist in the environment; otherwise the export stops with an error that names it.
If any record fails to import, the command fails with exit code 1; data files listed after it are not imported.