Data Mapping

Data mapping enables environment-specific transformations during deployment. FlowOn supports four types of mapping files.

Mapping Types

Map Type	Purpose	Use Case
Configuration	Environment variables and settings	API URLs, feature flags, limits
Entity	Record ID mappings for lookups	Security roles, status values, templates
Localized Resource	Multi-language text	UI labels, messages, notifications
Service Connection	External API configurations	Endpoints, credentials, certificates

Generate Mappings Command

flowon generate-mappings [options]

Options:
  -p, --project <n>            FlowOn project name
  -o, --output <path>             Output directory for mapping files
  -t, --type <type>               Map type: Configuration, Entity, LocalizedResource, ServiceConnection
  --all                           Generate all mapping types
  -c, --connection <string>       Connection string

Example:

flowon generate-mappings \
  --project "CustomerPortal" \
  --output "./mappings/dev" \
  --all

Apply Mappings Command

flowon apply-mappings [options]

Options:
  -m, --mappings <path>           Path to mappings directory
  -t, --type <type>               Specific map type to apply
  --dry-run                       Preview changes without applying
  -c, --connection <string>       Target environment connection

Example:

flowon apply-mappings \
  --mappings "./mappings/production" \
  --connection "$PROD_CONNECTION_STRING"

---

Configuration Data Map

Configuration maps handle environment-specific settings like connection strings, URLs, and feature flags.

Structure

<?xml version="1.0" encoding="utf-16"?>
<Map type="Configuration">
  <Configuration name="[ConfigName]" type="[TypeCode]">
    <Source>[SourceValue]</Source>
    <Target>[TargetValue]</Target>
  </Configuration>
</Map>

Configuration Types

Type Code	Description	Example
1	String	URLs, connection strings, keys
2	Integer	Limits, counts, timeouts
3	Boolean	Feature flags
4	Decimal	Thresholds, percentages

Example: Configuration Map

<?xml version="1.0" encoding="utf-16"?>
<Map type="Configuration">
  <!-- API Endpoint Configuration -->
  <Configuration name="PaymentGateway_BaseUrl" type="1">
    <Source>https://sandbox.payment-gateway.com/api/v1/</Source>
    <Target>https://api.payment-gateway.com/api/v1/</Target>
  </Configuration>
  
  <!-- Feature Flags -->
  <Configuration name="EnableTwoFactorAuth" type="3">
    <Source>false</Source>
    <Target>true</Target>
  </Configuration>
  
  <!-- Rate Limits -->
  <Configuration name="MaxLoginAttempts" type="2">
    <Source>10</Source>
    <Target>5</Target>
  </Configuration>
  
  <Configuration name="SessionTimeout_Minutes" type="2">
    <Source>60</Source>
    <Target>30</Target>
  </Configuration>
  
  <!-- Environment Identifier -->
  <Configuration name="EnvironmentName" type="1">
    <Source>/Development_CRM/</Source>
    <Target>/Production_CRM/</Target>
  </Configuration>
  
  <!-- External Portal URLs -->
  <Configuration name="CustomerPortalUrl" type="1">
    <Source>https://portal-dev.company.com/</Source>
    <Target>https://portal.company.com/</Target>
  </Configuration>
</Map>

---

Entity Data Map

Entity maps handle record ID mappings for reference data that may have different GUIDs across environments.

Structure

<?xml version="1.0" encoding="utf-16"?>
<Map type="Entity">
  <Entity logicalName="[EntityLogicalName]" primaryNameAttribute="[NameField]">
    <Record>
      <Source name="[SourceName]" id="[SourceGUID]" />
      <Target name="[TargetName]" id="[TargetGUID]" />
    </Record>
  </Entity>
</Map>

Example: Entity Map

<?xml version="1.0" encoding="utf-16"?>
<Map type="Entity">
  <!-- Approval Actions -->
  <Entity logicalName="crm_approvalaction" primaryNameAttribute="crm_name">
    <Record>
      <Source name="Approve" id="a1b2c3d4-e5f6-7890-abcd-000000000001" />
      <Target name="Approve" id="f1e2d3c4-b5a6-0987-dcba-111111111111" />
    </Record>
    <Record>
      <Source name="Reject" id="a1b2c3d4-e5f6-7890-abcd-000000000002" />
      <Target name="Reject" id="f1e2d3c4-b5a6-0987-dcba-222222222222" />
    </Record>
  </Entity>

  <!-- Security Roles -->
  <Entity logicalName="role" primaryNameAttribute="name">
    <Record>
      <Source name="Customer Service Representative" id="d4e5f6a7-b8c9-0123-defa-000000000001" />
      <Target name="Customer Service Representative" id="a7b8c9d0-e1f2-3456-abcd-111111111111" />
    </Record>
    <Record>
      <Source name="Sales Manager" id="d4e5f6a7-b8c9-0123-defa-000000000002" />
      <Target name="Sales Manager" id="a7b8c9d0-e1f2-3456-abcd-222222222222" />
    </Record>
  </Entity>

  <!-- Business Units -->
  <Entity logicalName="businessunit" primaryNameAttribute="name">
    <Record>
      <Source name="Corporate" id="e5f6a7b8-c9d0-1234-efab-000000000001" />
      <Target name="Corporate" id="b8c9d0e1-f2a3-4567-bcde-111111111111" />
    </Record>
  </Entity>
</Map>

---

Localized Resource Map

Localized resource maps handle multi-language text values for labels, messages, and UI elements.

Structure

<?xml version="1.0" encoding="utf-16"?>
<Map type="LocalizedResource">
  <LocalizedResource name="[ResourceKey]">
    <Locale lcid="[LanguageCode]">
      <Source>[SourceText]</Source>
      <Target>[TargetText]</Target>
    </Locale>
  </LocalizedResource>
</Map>

Example: Localized Resource Map

<?xml version="1.0" encoding="utf-16"?>
<Map type="LocalizedResource">
  <!-- Application Status Labels -->
  <LocalizedResource name="Status_Pending">
    <Locale lcid="1033">
      <Source>Pending Review</Source>
      <Target>Pending Review</Target>
    </Locale>
    <Locale lcid="1025">
      <Source>قيد المراجعة</Source>
      <Target>قيد المراجعة</Target>
    </Locale>
  </LocalizedResource>

  <!-- Action Button Labels -->
  <LocalizedResource name="Action_Submit">
    <Locale lcid="1033">
      <Source>Submit Application</Source>
      <Target>Submit Application</Target>
    </Locale>
    <Locale lcid="1025">
      <Source>تقديم الطلب</Source>
      <Target>تقديم الطلب</Target>
    </Locale>
  </LocalizedResource>

  <!-- Validation Messages -->
  <LocalizedResource name="Validation_RequiredField">
    <Locale lcid="1033">
      <Source>This field is required</Source>
      <Target>This field is required</Target>
    </Locale>
    <Locale lcid="1025">
      <Source>هذا الحقل مطلوب</Source>
      <Target>هذا الحقل مطلوب</Target>
    </Locale>
  </LocalizedResource>
</Map>

---

Service Connection Map

Service connection maps handle external API configurations including endpoints, authentication, and OpenAPI specifications.

Structure

<?xml version="1.0" encoding="utf-16"?>
<Map type="ServiceConnection">
  <ServiceConnection name="[ConnectionName]" type="[TypeCode]">
    <Source>
      <Url>[SourceURL]</Url>
      <OpenApiSpecs>[OpenAPIJSON]</OpenApiSpecs>
      <SecuritySchemes>
        <SecurityScheme name="[SchemeName]" type="[SchemeType]">
          <type>[TypeCode]</type>
          <n>[DisplayName]</n>
          <key>[HeaderOrParamName]</key>
          <value>[Credential]</value>
          <location>[Header|Query]</location>
        </SecurityScheme>
      </SecuritySchemes>
    </Source>
    <Target>
      <!-- Same structure with production values -->
    </Target>
  </ServiceConnection>
</Map>

Security Scheme Types

Type Code	Scheme Type	Description
1	ApiKey	API key in header or query parameter
2	Bearer	OAuth 2.0 Bearer token
3	Basic	Basic authentication
4	OAuth2	Full OAuth 2.0 flow

Example: Service Connection Map

<?xml version="1.0" encoding="utf-16"?>
<Map type="ServiceConnection">
  <!-- Payment Gateway Service -->
  <ServiceConnection name="PaymentGateway_API" type="1">
    <Source>
      <Url>https://sandbox.paymentgateway.com/api/v2/</Url>
      <SecuritySchemes>
        <SecurityScheme name="API Key" type="ApiKey">
          <type>1</type>
          <n>API Key</n>
          <key>X-API-Key</key>
          <value>sandbox_key_abc123xyz789</value>
          <location>Header</location>
        </SecurityScheme>
      </SecuritySchemes>
    </Source>
    <Target>
      <Url>https://api.paymentgateway.com/api/v2/</Url>
      <SecuritySchemes>
        <SecurityScheme name="API Key" type="ApiKey">
          <type>1</type>
          <n>API Key</n>
          <key>X-API-Key</key>
          <value>prod_key_def456uvw012</value>
          <location>Header</location>
        </SecurityScheme>
      </SecuritySchemes>
    </Target>
  </ServiceConnection>
</Map>