Deploy & ALM

Data mapping

Give each environment its own configuration values, service connections, localized resources and record references when you deploy a project.

Some values in a Logic Fabric project are right only for the environment they were built in: the URL of a payment service, an API key, a feature switch, the id of the “Tier 2 Support” team. Data map files let you replace those values per environment during deployment, so the same package goes to test and production unchanged.

The four data map files

File	Replaces	Example
`configuration.datamap.xml`	Configuration values	`PaymentGateway_BaseUrl`, `MaxDiscountPercent`, `EnableSmsNotifications`
`serviceconnection.datamap.xml`	Service connections: URL, OpenAPI specification and security settings	The ERP endpoint and its API key
`localizedresources.datamap.xml`	Localized resources, per language	A notification text that differs per market
`entity.datamap.xml`	References to specific records	The team, queue or business unit a flow assigns cases to

Each entry has a Source, the value in the package, and a Target, the value to use in the environment you deploy to.

Set up mappings for an environment

Extract the data map files from an exported package. No connection is needed:
Terminal window
```
flowon-dynamics generate-mappings \
  --project-file-path ./artifacts/Contoso_Service.flop \
  --output-directory ./mappings/uat
```
The command prints how many files it wrote, or that the package has no data map files.
Edit the Target values in each file for the target environment. Leave the Source values and the attributes as they are.
Repeat for each environment (for example ./mappings/prod), and commit the folders.
Pass the files to import with --map-file-path. See Import.

File formats

Configuration values

<Map type="Configuration">
  <Configuration name="PaymentGateway_BaseUrl" type="1">
    <Source>https://sandbox.payments.contoso.com/v2/</Source>
    <Target>https://payments.contoso.com/v2/</Target>
  </Configuration>
  <Configuration name="EnableSmsNotifications" type="3">
    <Source>false</Source>
    <Target>true</Target>
  </Configuration>
</Map>

The type attribute is written by generate-mappings; keep it as it is.

Localized resources

<Map type="LocalizedResource">
  <LocalizedResource name="CaseClosedNotification">
    <Locale lcid="1033">
      <Source>Your case has been closed.</Source>
      <Target>Your case {0} has been resolved. Reply within 7 days to reopen it.</Target>
    </Locale>
    <Locale lcid="1031">
      <Source>Ihr Fall wurde geschlossen.</Source>
      <Target>Ihr Fall {0} wurde gelöst. Antworten Sie innerhalb von 7 Tagen, um ihn wieder zu öffnen.</Target>
    </Locale>
  </LocalizedResource>
</Map>

Service connections

<Map type="ServiceConnection">
  <ServiceConnection name="ErpOrders" type="1">
    <Source>
      <Url>https://erp-test.contoso.com/api/</Url>
      ...
    </Source>
    <Target>
      <Url>https://erp.contoso.com/api/</Url>
      <SecuritySchemes>
        ...
      </SecuritySchemes>
    </Target>
  </ServiceConnection>
</Map>

In Target you can set the Url, the OpenApiSpecs and the SecuritySchemes (for example the header name and value of an API key). Start from the generated file and change only the values.

Record references

<Map type="Entity">
  <Entity logicalName="team" primaryNameAttribute="name">
    <Record>
      <Source name="Tier 2 Support" id="0f8e2c1a-4b3d-4e5f-8a9b-1c2d3e4f5a6b" />
      <Target name="Tier 2 Support" id="7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d" />
    </Record>
  </Entity>
</Map>

Records have different ids in each environment. For each record the project refers to, set the Target name and id of the matching record in the target environment.

Apply mappings to an imported project

To change the environment-specific values of a project that is already imported (for example after rotating an API key), apply data map files without importing the package again:

flowon-dynamics apply-mappings \
  -c "$PROD_CONNECTION" \
  --project-name "Contoso Service" \
  --map-file-path ./mappings/prod/serviceconnection.datamap.xml

It prints, for example, Applied 1 data map file(s) to project 'Contoso Service'.