Explode Command

Explode Command

Overview

The explode command breaks down a Gateway configuration bundle into multiple individual files organized by entity type and folder structure. This is useful for version control, code review, and managing large configurations.

Syntax

graphman explode --input <input-file> --output <output-dir>
  [--options.<name> <value>,...]

Parameters

Required Parameters

Parameter	Description
--input	Input bundle file containing Gateway configuration
--output	Output directory where files will be created

Optional Parameters

Parameter	Description	Default
--options.level	Level of explosion (0, 1, or 2)	0

Explosion Levels

The level option controls how deeply the bundle is exploded:

Level	Description	What Gets Exploded
0	Basic	Individual entities into separate JSON files
1	Intermediate	Level 0 + WSDL resources, certificates (PEM/P12), certificate chains
2	Complete	Level 1 + Policy code (XML, JSON, YAML) into separate files

Output Structure

Level 0 Structure

output-dir/
├── services/
│   ├── Service1.service.json
│   └── Service2.service.json
├── policies/
│   ├── Policy1.policy.json
│   └── Policy2.policy.json
├── folders/
│   └── MyFolder.folder.json
├── keys/
│   └── MyKey.key.json
└── bundle-properties.json

Level 1 Structure (Additional Files)

output-dir/
├── services/
│   ├── Service1.service.json
│   ├── Service1.wsdl
│   ├── Service1-wsdl-resource-1.xml
│   └── Service1-wsdl-resource-2.xml
├── keys/
│   ├── MyKey.key.json
│   ├── MyKey.p12              # Binary key file
│   └── MyKey.certchain.pem    # Certificate chain
└── trustedCerts/
    ├── TrustedCert1.cert.json
    └── TrustedCert1.pem

Level 2 Structure (Additional Files)

output-dir/
├── services/
│   ├── Service1.service.json
│   ├── Service1.xml           # Policy XML
│   └── Service1-revision-1.xml
├── policies/
│   ├── Policy1.policy.json
│   └── Policy1.cjson          # Policy code JSON
└── policyFragments/
    ├── Fragment1.fragment.json
    └── Fragment1.yaml         # Policy YAML

Folder Tree Structure

Entities with folder paths are organized hierarchically:

output-dir/
└── tree/
    └── APIs/
        └── External/
            ├── CustomerAPI.service.json
            └── CustomerAPI.xml

Examples

Basic Explosion (Level 0)

Explode bundle into individual entity files:

graphman explode --input bundle.json --output exploded/

Intermediate Explosion (Level 1)

Include certificates and WSDL resources:

graphman explode --input bundle.json --output exploded/ --options.level 1

Complete Explosion (Level 2)

Explode everything including policy code:

graphman explode --input bundle.json --output exploded/ --options.level 2

Explode for Version Control

Explode bundle for Git repository:

graphman explode --input prod-config.json --output repo/gateway-config/ --options.level 2
cd repo
git add gateway-config/
git commit -m "Updated gateway configuration"

Use Cases

1. Version Control Integration

Store Gateway configuration in Git with readable diffs:

graphman export --gateway prod --output temp-bundle.json
graphman explode --input temp-bundle.json --output repo/config/ --options.level 2
rm temp-bundle.json
git add repo/config/
git commit -m "Production configuration snapshot"

2. Code Review

Make configuration changes reviewable:

# Before changes
graphman export --gateway dev --output before.json
graphman explode --input before.json --output review/before/ --options.level 2

# After changes
graphman export --gateway dev --output after.json
graphman explode --input after.json --output review/after/ --options.level 2

# Review differences
diff -r review/before/ review/after/

3. Selective Editing

Edit specific entities manually:

graphman explode --input bundle.json --output work/ --options.level 2
# Edit work/services/MyService.service.json
# Edit work/services/MyService.xml
graphman implode --input work/ --output modified-bundle.json

4. Configuration Documentation

Generate human-readable configuration documentation:

graphman explode --input prod-config.json --output docs/prod-config/ --options.level 2
# Review individual files for documentation

5. Backup Organization

Organize backups in a readable format:

DATE=$(date +%Y%m%d)
graphman export --gateway prod --output temp.json
graphman explode --input temp.json --output backups/$DATE/ --options.level 1
rm temp.json

6. Policy Development

Extract policies for development:

graphman export --using policies --gateway dev --output policies.json
graphman explode --input policies.json --output policy-dev/ --options.level 2
# Develop policies in policy-dev/

File Naming Conventions

Entity Files

• Services: <name>.service.json
• Policies: <name>.policy.json
• Policy Fragments: <name>.fragment.json
• Folders: <name>.folder.json
• Keys: <name>.key.json
• Trusted Certificates: <name>.cert.json

Associated Files

• WSDL: <name>.wsdl
• WSDL Resources: <name>-wsdl-resource-<n>.xml
• Policy XML: <name>.xml
• Policy JSON: <name>.cjson
• Policy YAML: <name>.yaml
• Policy Revisions: <name>-revision-<n>.xml
• Certificate PEM: <name>.pem
• Key P12: <name>.p12
• Certificate Chain: <name>.certchain.pem

Special Features

Duplicate Entity Handling

When duplicate entities are found (same name), they are differentiated:

services/
├── MyService.service.json
└── MyService-1234567890-123.service.json  # Duplicate with timestamp

Safe File Names

Entity names are converted to safe file names:

• Special characters are replaced with underscores
• Spaces are preserved or replaced based on OS
• Path separators are handled appropriately

Bundle Properties

Bundle-level properties are saved separately:

// bundle-properties.json
{
  "meta": {
    "summary": true,
    "gateway": "production"
  }
}

Important Notes

• The output directory is created if it doesn't exist
• Existing files in the output directory may be overwritten
• Entity names must be unique within their type (or timestamps are added)
• Binary files (P12, JAR) are written in binary format
• Text files use UTF-8 encoding with CRLF line endings
• The tree directory contains entities with folder paths
• Level 2 explosion is recommended for version control
• Large bundles may create thousands of files

File Reference Format

Exploded files use a special reference format in JSON:

{
  "name": "MyService",
  "policy": {
    "xml": "{{MyService.xml}}"
  },
  "wsdl": "{{MyService.wsdl}}"
}

The {{filename}} format indicates the content is in a separate file.

Certificate Handling

Keys (Level 1)

• P12 format preferred over PEM if both exist
• Certificate chains extracted to separate PEM file
• Binary P12 files are base64 decoded

Trusted Certificates (Level 1)

• Certificate data extracted to PEM format
• PEM headers added automatically

User Certificates (Level 1)

• Certificate data extracted to PEM format
• SSH public keys extracted to .pub files

Policy Code Handling (Level 2)

Format Priority

When multiple policy formats exist, the following priority is used:

1. XML (if present)
2. JSON (if present)
3. Code (if present)
4. YAML (if present)

Only the highest priority format is exploded; others are removed.

Related Commands

• implode: Reverse operation - combine files back into bundle
• export: Export configuration before exploding
• slice: Extract specific sections before exploding

Best Practices

1. Use Level 2 for version control - provides maximum readability
2. Use Level 1 for backups - balances readability and file count
3. Use Level 0 for quick inspection - minimal file creation
4. Clean output directory before exploding to avoid stale files
5. Use with implode to round-trip test configurations
6. Commit to version control after exploding for tracking
7. Document folder structure in repository README

Workflow Example

Complete workflow for version-controlled configuration:

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

# Explode for version control
graphman explode --input temp.json --output config/ --options.level 2

# Clean up
rm temp.json

# Commit to Git
git add config/
git commit -m "Configuration update $(date +%Y-%m-%d)"
git push