Import Command

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

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:

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

Import with Specific Action

Import with a specific default action:

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

Delete Entities

Delete entities from the Gateway:

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:

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

Import with Entity-Level Mappings

Override mapping actions for specific entity types:

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

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

Import with Policy Activation

Import and immediately activate new policy revisions:

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

Import with Comment

Add a comment to policy revisions:

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

Force Delete

Force deletion even when dependencies exist:

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

Import with Certificate Chain Replacement

Replace all matching certificate chains:

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

Use Cases

1. Deploy to Development

Deploy configuration changes to development environment:

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

2. Promote to Production

Promote tested configuration to production:

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:

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

4. Cross-Environment Migration

Migrate configuration between environments with ID mappings:

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

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

6. Policy Revision Migration

Migrate policies with their revision history:

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

7. Selective Import

Import only specific entity types:

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

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

Empty Folder Cleanup

Automatically delete empty parent folders:

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

Server Module Files

Import bundles with server module files (SMF):

# 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 configuration for import
• diff: Generate import bundles from differences
• mappings: Define mapping instructions
• validate: 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