Mappings Command

Mappings Command

Overview

The mappings command defines mapping instructions for bundled entities, controlling how they are processed during import operations. Mappings determine whether entities are created, updated, deleted, or ignored when imported to a Gateway.

Syntax

graphman mappings --input <input-file>
  [--output <output-file>]
  [--mappings.action <action>]
  [--mappings.<entity-type>.action <action>]
  [--mappings.level <0|1|2>]
  [--mappings.<entity-type>.level <0|1|2>]
  [--options.<name> <value>]

Parameters

Required Parameters

Parameter	Description
--input	Input bundle file

Optional Parameters

Parameter	Description	Default
--output	Output file with mapping instructions	Standard output (console)
--mappings.action	Global mapping action for all entities	None
--mappings.<type>.action	Mapping action for specific entity type	None
--mappings.level	Global mapping level (0, 1, or 2)	None
--mappings.<type>.level	Mapping level for specific entity type	None
--options.bundleDefaultAction	Bundle-level default action	None

Mapping Actions

Action	Behavior
NEW_OR_UPDATE	Create new entity or update if exists
NEW_OR_EXISTING	Create new entity or use existing without updates
ALWAYS_CREATE_NEW	Always create a new entity (generates new GOID)
DELETE	Delete the entity from the Gateway
IGNORE	Skip the entity entirely

Mapping Levels

Level	Description
0	No mappings - entity is not included in mapping instructions
1	Entity-level only - mapping for the entity, excluding dependencies
2	All entities - mapping for the entity and all its dependencies

Behavior

Mapping Instruction Generation

The command:

1. Reads the input bundle
2. Removes duplicate entities
3. Applies mapping actions based on parameters
4. Generates mapping instructions in bundle properties
5. Outputs bundle with embedded mapping instructions

Mapping Hierarchy

Mapping actions are applied in order of specificity:

1. Entity-specific mappings (highest priority)
2. Entity-type mappings (--mappings.<type>.action)
3. Global mappings (--mappings.action)
4. Bundle default action (--options.bundleDefaultAction)

Examples

Set Global Mapping Action

Apply same action to all entities:

graphman mappings --input bundle.json --output mapped.json \
  --mappings.action NEW_OR_UPDATE

Set Entity-Type Mapping

Different actions for different entity types:

graphman mappings --input bundle.json --output mapped.json \
  --mappings.services.action NEW_OR_UPDATE \
  --mappings.policies.action ALWAYS_CREATE_NEW \
  --mappings.folders.action NEW_OR_EXISTING

Set Bundle Default Action

Set bundle-level default:

graphman mappings --input bundle.json --output mapped.json \
  --options.bundleDefaultAction NEW_OR_UPDATE

Delete Mapping

Mark entities for deletion:

graphman mappings --input entities-to-delete.json --output delete-bundle.json \
  --mappings.action DELETE

Ignore Specific Entity Type

Skip certain entity types during import:

graphman mappings --input bundle.json --output mapped.json \
  --mappings.action NEW_OR_UPDATE \
  --mappings.clusterProperties.action IGNORE

Set Mapping Levels

Control dependency inclusion:

graphman mappings --input bundle.json --output mapped.json \
  --mappings.services.action NEW_OR_UPDATE \
  --mappings.services.level 1

Use Cases

1. Controlled Deployment

Deploy with specific actions per entity type:

# Services: update or create
# Policies: always create new
# Folders: use existing
graphman mappings --input bundle.json --output deployment.json \
  --mappings.services.action NEW_OR_UPDATE \
  --mappings.policies.action ALWAYS_CREATE_NEW \
  --mappings.folders.action NEW_OR_EXISTING

graphman import --input deployment.json --gateway prod

2. Deletion Preparation

Prepare bundle for entity deletion:

graphman mappings --input obsolete-entities.json --output delete-bundle.json \
  --mappings.action DELETE

graphman import --using delete-bundle --input delete-bundle.json --gateway dev

3. Selective Import

Import some entities, ignore others:

graphman mappings --input bundle.json --output selective.json \
  --mappings.services.action NEW_OR_UPDATE \
  --mappings.policies.action NEW_OR_UPDATE \
  --mappings.clusterProperties.action IGNORE \
  --mappings.scheduledTasks.action IGNORE

graphman import --input selective.json --gateway test

4. Policy Versioning

Always create new policy versions:

graphman mappings --input policies.json --output versioned-policies.json \
  --mappings.policies.action ALWAYS_CREATE_NEW

graphman import --input versioned-policies.json --gateway dev

5. Infrastructure Setup

Set up infrastructure without overwriting:

graphman mappings --input infrastructure.json --output setup.json \
  --mappings.folders.action NEW_OR_EXISTING \
  --mappings.clusterProperties.action NEW_OR_EXISTING \
  --mappings.jdbcConnections.action NEW_OR_EXISTING

graphman import --input setup.json --gateway new-env

6. Environment-Specific Mappings

Different mappings for different environments:

# Development: always update
graphman mappings --input bundle.json --output dev-bundle.json \
  --mappings.action NEW_OR_UPDATE

# Production: create new versions
graphman mappings --input bundle.json --output prod-bundle.json \
  --mappings.action ALWAYS_CREATE_NEW

Output Structure

The mappings command embeds mapping instructions in the bundle:

{
  "services": [...],
  "policies": [...],
  "properties": {
    "mappings": {
      "services": [
        {
          "action": "NEW_OR_UPDATE",
          "srcId": "service-guid",
          "srcName": "MyService"
        }
      ],
      "policies": [
        {
          "action": "ALWAYS_CREATE_NEW",
          "srcId": "policy-guid",
          "srcName": "MyPolicy"
        }
      ]
    }
  }
}

Mapping Levels Explained

Level 0: No Mappings

Entity is excluded from mapping instructions:

graphman mappings --input bundle.json --output mapped.json \
  --mappings.services.level 0

Result: Services are not included in properties.mappings.

Level 1: Entity Only

Mapping for the entity, excluding dependencies:

graphman mappings --input bundle.json --output mapped.json \
  --mappings.services.action NEW_OR_UPDATE \
  --mappings.services.level 1

Result: Only service entities get mapping instructions, not their dependencies.

Level 2: Entity and Dependencies

Mapping for entity and all dependencies:

graphman mappings --input bundle.json --output mapped.json \
  --mappings.services.action NEW_OR_UPDATE \
  --mappings.services.level 2

Result: Service entities and their dependencies (folders, policies, etc.) get mapping instructions.

Entity Type Names

Use plural form of entity types:

Entity Type	Plural Name
Service	services
Policy	policies
Policy Fragment	policyFragments
Folder	folders
Key	keys
Trusted Certificate	trustedCerts
JDBC Connection	jdbcConnections
JMS Destination	jmsDestinations
Cluster Property	clusterProperties
Scheduled Task	scheduledTasks
Encapsulated Assertion	encassConfigs

Important Notes

• Mapping Priority: Entity-specific > Type-specific > Global > Bundle default
• Duplicate Removal: Duplicates are automatically removed
• Bundle Properties: Mappings are stored in properties.mappings
• Import Usage: Mapped bundles are used with the import command
• Delete Action: Use with delete-bundle mutation
• Level Default: If not specified, level 2 (all entities) is typically used
• Action Validation: Invalid actions are rejected during import

Related Commands

• import: Import bundles with mapping instructions
• export: Export with default mappings
• diff: Generate bundles with automatic mappings

Best Practices

1. Be explicit with actions - don't rely on defaults
2. Use type-specific mappings for fine-grained control
3. Test in non-production before applying to production
4. Document mapping strategy in deployment procedures
5. Use IGNORE carefully - ensure dependencies are handled
6. Review output bundle before importing
7. Use DELETE with caution - deletions are irreversible
8. Consider dependencies when setting mapping levels

Workflow Examples

Deployment Pipeline

#!/bin/bash
# Export from dev
graphman export --gateway dev --output dev-export.json

# Apply production mappings
graphman mappings --input dev-export.json --output prod-deployment.json \
  --mappings.services.action NEW_OR_UPDATE \
  --mappings.policies.action NEW_OR_UPDATE \
  --mappings.folders.action NEW_OR_EXISTING \
  --mappings.clusterProperties.action IGNORE

# Import to production
graphman import --input prod-deployment.json --gateway prod

Cleanup Workflow

#!/bin/bash
# Identify obsolete entities
graphman slice --input current-config.json \
  --sections services \
  --filter.services.folderPath.eq /Deprecated \
  --output obsolete.json

# Mark for deletion
graphman mappings --input obsolete.json --output delete-bundle.json \
  --mappings.action DELETE

# Delete from gateway
graphman import --using delete-bundle --input delete-bundle.json --gateway dev \
  --options.forceDelete true

Multi-Environment Deployment

#!/bin/bash
BUNDLE="release-v2.0.json"

# Dev: always update
graphman mappings --input $BUNDLE --output dev-bundle.json \
  --mappings.action NEW_OR_UPDATE
graphman import --input dev-bundle.json --gateway dev

# Test: create new versions
graphman mappings --input $BUNDLE --output test-bundle.json \
  --mappings.action ALWAYS_CREATE_NEW
graphman import --input test-bundle.json --gateway test

# Prod: controlled update
graphman mappings --input $BUNDLE --output prod-bundle.json \
  --mappings.services.action NEW_OR_UPDATE \
  --mappings.policies.action ALWAYS_CREATE_NEW
graphman import --input prod-bundle.json --gateway prod

Troubleshooting

Mappings Not Applied

If mappings aren't applied during import:

• Verify mapping instructions in bundle properties
• Check import command output for warnings
• Ensure entity types are spelled correctly (plural form)
• Verify bundle structure is valid

Unexpected Entity Behavior

If entities behave unexpectedly during import:

• Review mapping action hierarchy
• Check for entity-specific mappings in bundle
• Verify mapping levels
• Review import command options

DELETE Action Not Working

If deletion fails:

• Use delete-bundle mutation: --using delete-bundle
• Add --options.forceDelete true if dependencies exist
• Verify entities exist in target Gateway
• Check Gateway permissions