# Import Command

## Overview

The `import` command applies Gateway configuration from a bundle file to a target Gateway using GraphQL mutations. This is the primary method for deploying configuration changes, migrating between environments, or restoring backups.

## Syntax

```bash
graphman import [--using <mutation>] --input <input-file> [--variables.<name> <value>,...]
  [--gateway <name>]
  [--output <output-file>]
  [--options.<name> <value>,...]
```

## Parameters

### Required Parameters

| Parameter | Description |
|-----------|-------------|
| `--input` | Input bundle file containing Gateway configuration |

### Optional Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `--using` | Mutation query to use for import | `install-bundle` |
| `--input-id-mappings` | File containing GOID/GUID mappings | None |
| `--variables.<name>` | Variables for the mutation (name-value pairs) | None |
| `--gateway` | Gateway profile name from configuration | `default` |
| `--output` | Output file to capture mutation results | Standard output (console) |
| `--options.<name>` | Customize import operation (name-value pairs) | See defaults below |

### Default Options

| Option | Default Value | Description |
|--------|---------------|-------------|
| `bundleDefaultAction` | `null` | Default mapping action for entities |
| `excludeGoids` | `false` | Exclude GOIDs from entities |
| `forceDelete` | `false` | Force deletion of entities |
| `forceAdminPasswordReset` | `false` | Force admin password reset |
| `replaceAllMatchingCertChain` | `false` | Replace all matching certificate chains |

## Behavior

### Mutation Selection

- Default mutation is `install-bundle` for creating or updating entities
- Use `delete-bundle` mutation for deleting entities
- Only mutations (not queries) are valid for import operations

### Mapping Actions

Mapping actions control how entities are processed during import:

| 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 |

### Safety Features

- The Gateway profile must have `allowMutations: true` configured
- Import operations are rejected if mutations are not explicitly enabled
- This prevents accidental modifications to production environments

## Examples

### Basic Import

Import a bundle to the default Gateway:

```bash
graphman import --input bundle.json --gateway dev
```

### Import with Specific Action

Import with a specific default action:

```bash
graphman import --input bundle.json --gateway prod --options.bundleDefaultAction NEW_OR_UPDATE
```

### Delete Entities

Delete entities from the Gateway:

```bash
graphman import --using delete-bundle --input entities-to-delete.json --gateway dev
```

### Import with ID Mappings

Import using GOID/GUID mappings from a diff operation:

```bash
graphman import --input bundle.json --input-id-mappings mappings.json --gateway prod
```

### Import with Entity-Level Mappings

Override mapping actions for specific entity types:

```bash
graphman import --input bundle.json --gateway prod \
  --options.mappings.services.action NEW_OR_UPDATE \
  --options.mappings.policies.action ALWAYS_CREATE_NEW
```

### Import Without GOIDs

Import while excluding GOIDs (useful for cross-environment deployment):

```bash
graphman import --input bundle.json --gateway prod --options.excludeGoids true
```

### Import with Policy Activation

Import and immediately activate new policy revisions:

```bash
graphman import --input bundle.json --gateway prod --options.activate true
```

### Import with Comment

Add a comment to policy revisions:

```bash
graphman import --input bundle.json --gateway prod --options.comment "Release v2.0.1"
```

### Force Delete

Force deletion even when dependencies exist:

```bash
graphman import --using delete-bundle --input bundle.json --gateway dev --options.forceDelete true
```

### Import with Certificate Chain Replacement

Replace all matching certificate chains:

```bash
graphman import --input keys-bundle.json --gateway prod --options.replaceAllMatchingCertChain true
```

## Use Cases

### 1. Deploy to Development

Deploy configuration changes to development environment:

```bash
graphman import --input new-features.json --gateway dev --options.bundleDefaultAction NEW_OR_UPDATE
```

### 2. Promote to Production

Promote tested configuration to production:

```bash
graphman import --input release-bundle.json --gateway prod \
  --options.bundleDefaultAction NEW_OR_UPDATE \
  --options.comment "Production Release 2024-12-20"
```

### 3. Restore from Backup

Restore Gateway configuration from backup:

```bash
graphman import --input backup-20241220.json --gateway prod --options.bundleDefaultAction NEW_OR_UPDATE
```

### 4. Cross-Environment Migration

Migrate configuration between environments with ID mappings:

```bash
# First, create diff to get mappings
graphman diff --input-source @source --input-target @target --output diff.json

# Then import with mappings
graphman import --input diff.json --input-id-mappings diff.id-mappings.json --gateway target
```

### 5. Cleanup Unused Entities

Delete obsolete entities from Gateway:

```bash
graphman import --using delete-bundle --input obsolete-entities.json --gateway dev --options.forceDelete true
```

### 6. Policy Revision Migration

Migrate policies with their revision history:

```bash
graphman import --input policies-with-revisions.json --gateway prod \
  --options.migratePolicyRevisions true \
  --options.activate false
```

### 7. Selective Import

Import only specific entity types:

```bash
# First, slice the bundle
graphman slice --input full-bundle.json --sections services policies --output services-policies.json

# Then import
graphman import --input services-policies.json --gateway prod
```

## Advanced Features

### Mapping Hierarchy

Mappings can be specified at multiple levels (most specific wins):

1. Entity-level mappings in bundle properties
2. Entity-type-level mappings via `--options.mappings.<type>.action`
3. Global mappings via `--options.mappings.action`
4. Bundle default action via `--options.bundleDefaultAction`

### Role and User Group Management

Override role assignee and group membership replacement:

```bash
graphman import --input bundle.json --gateway prod \
  --options.overrideReplaceRoleAssignees true \
  --options.overrideReplaceUserGroupMemberships true
```

### Empty Folder Cleanup

Automatically delete empty parent folders:

```bash
graphman import --using delete-bundle --input entities.json --gateway dev \
  --options.deleteEmptyParentFolders true
```

### Server Module Files

Import bundles with server module files (SMF):

```bash
# Ensure .jar/.aar files are in the same directory as the bundle
graphman import --input bundle-with-smf.json --gateway prod
```

## Important Notes

- **Mutations Must Be Enabled**: Gateway profile must have `allowMutations: true`
- **Backup First**: Always backup before importing to production
- **Test in Lower Environments**: Test imports in dev/test before production
- **ID Mappings**: Use ID mappings for cross-environment deployments
- **Policy Revisions**: By default, new revisions are activated immediately
- **Dependencies**: Import may fail if dependencies are missing
- **Ordering**: Entity processing order matters for dependencies
- **Rollback**: No automatic rollback; maintain backups for recovery

## Safety Checklist

Before importing to production:

- [ ] Backup current production configuration
- [ ] Test import in development environment
- [ ] Review mapping actions
- [ ] Verify Gateway profile has `allowMutations: true`
- [ ] Check for dependency conflicts
- [ ] Plan rollback procedure
- [ ] Schedule during maintenance window
- [ ] Notify stakeholders

## Output

The import command outputs mutation results including:

- Status of each entity (created, updated, deleted, or error)
- Detailed status messages for failures
- GOIDs of newly created entities
- Warnings and errors encountered

## Error Handling

Common errors and solutions:

| Error | Solution |
|-------|----------|
| Gateway not opted for mutations | Set `allowMutations: true` in Gateway profile |
| Input parameter is missing | Provide `--input` parameter |
| Invalid query for import | Ensure using a mutation (not a query) |
| Dependency not found | Import dependencies first or include in bundle |
| Entity already exists | Use appropriate mapping action |
| Force delete required | Add `--options.forceDelete true` |

## Related Commands

- **[export](Export-Command.md)**: Export configuration for import
- **[diff](Diff-Command.md)**: Generate import bundles from differences
- **[mappings](Mappings-Command.md)**: Define mapping instructions
- **[validate](Validate-Command.md)**: Validate bundles before import

## Best Practices

1. **Always test imports in non-production first**
2. **Use version control for bundle files**
3. **Maintain ID mapping files for cross-environment deployments**
4. **Use comments to track changes**: `--options.comment "Ticket-123"`
5. **Exclude GOIDs for portable bundles**: `--options.excludeGoids true`
6. **Use specific mapping actions** instead of relying on defaults
7. **Review output for errors** before considering import successful
8. **Keep backups** of production configuration