# 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

```bash
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:

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

### Set Entity-Type Mapping

Different actions for different entity types:

```bash
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:

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

### Delete Mapping

Mark entities for deletion:

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

### Ignore Specific Entity Type

Skip certain entity types during import:

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

### Set Mapping Levels

Control dependency inclusion:

```bash
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:

```bash
# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
# 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:

```json
{
  "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:

```bash
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:

```bash
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:

```bash
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-Command.md)**: Import bundles with mapping instructions
- **[export](Export-Command.md)**: Export with default mappings
- **[diff](Diff-Command.md)**: 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

```bash
#!/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

```bash
#!/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

```bash
#!/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