Skip to content

Implode Command

Jump to bottom
Raju Gurram edited this page Dec 20, 2025 · 1 revision

Implode Command

Overview

The implode command is the inverse of the explode command. It combines multiple individual files from a directory structure back into a single Gateway configuration bundle. This is essential for reassembling exploded configurations after editing or version control operations.

Syntax

graphman implode --input <input-dir> [--output <output-file>]

Parameters

Required Parameters

Parameter Description
--input Input directory containing exploded Gateway configuration

Optional Parameters

Parameter Description Default
--output Output bundle file Standard output (console)

Behavior

Directory Structure Recognition

The implode command automatically recognizes:

  • Entity type directories: services/, policies/, folders/, etc.
  • Tree structure: tree/ directory for folder-organized entities
  • Bundle properties: bundle-properties.json file
  • File references: {{filename}} format in JSON files

File Reference Resolution

Files referenced using the {{filename}} format are automatically loaded:

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

The content of MyService.xml is loaded and embedded in the bundle.

Supported File Types

File Type Extension Processing
Entity JSON .json Parsed as JSON entity
Policy XML .xml Loaded as policy XML
Policy JSON .cjson Loaded and stringified as policy JSON
Policy YAML .yaml Loaded as policy YAML
WSDL .wsdl Loaded as WSDL content
WSDL Resources .xml Loaded as WSDL resource content
Certificate PEM .pem Loaded as certificate data
Key P12 .p12 Loaded as binary and base64 encoded
SSH Public Key .pub Loaded as SSH public key

Input Directory Structure

Expected Structure

input-dir/
├── services/
│   ├── Service1.service.json
│   ├── Service1.xml
│   └── Service1.wsdl
├── policies/
│   ├── Policy1.policy.json
│   └── Policy1.cjson
├── keys/
│   ├── MyKey.key.json
│   ├── MyKey.p12
│   └── MyKey.certchain.pem
├── tree/
│   └── APIs/
│       └── External/
│           ├── API1.service.json
│           └── API1.xml
└── bundle-properties.json

Examples

Basic Implode

Combine exploded files back into a bundle:

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

Implode After Editing

Edit exploded files and recombine:

# Explode
graphman explode --input original.json --output work/ --options.level 2

# Edit files in work/ directory
# ... make changes ...

# Implode
graphman implode --input work/ --output modified.json

Implode from Version Control

Implode configuration from Git repository:

git pull
graphman implode --input repo/gateway-config/ --output deployment-bundle.json
graphman import --input deployment-bundle.json --gateway dev

Implode to Console

View the imploded bundle without saving:

graphman implode --input exploded/

Use Cases

1. Version Control Workflow

Retrieve configuration from version control and deploy:

# Pull latest from Git
git pull origin main

# Implode configuration
graphman implode --input config/ --output deploy.json

# Deploy to gateway
graphman import --input deploy.json --gateway dev

2. Manual Configuration Editing

Edit specific entities and reassemble:

# Explode bundle
graphman explode --input bundle.json --output edit/ --options.level 2

# Edit files
vim edit/services/MyService.service.json
vim edit/services/MyService.xml

# Implode changes
graphman implode --input edit/ --output updated-bundle.json

3. Merge Manual Changes

Combine manual file changes with existing configuration:

# Export current state
graphman export --gateway dev --output current.json
graphman explode --input current.json --output current/ --options.level 2

# Make manual changes to files in current/

# Implode and deploy
graphman implode --input current/ --output updated.json
graphman import --input updated.json --gateway dev

4. Configuration Assembly

Assemble configuration from multiple sources:

# Copy entities from different sources into a directory
mkdir assembled
cp -r source1/services assembled/
cp -r source2/policies assembled/
cp -r source3/keys assembled/

# Implode into single bundle
graphman implode --input assembled/ --output combined-bundle.json

5. Policy Development Workflow

Develop policies externally and package:

# Create policy structure
mkdir -p policies-dev/policies
# ... develop policy files ...

# Implode for deployment
graphman implode --input policies-dev/ --output new-policies.json
graphman import --input new-policies.json --gateway dev

File Processing Details

Entity Recognition

Entities are recognized by their file suffix:

  • .service.json → Services
  • .policy.json → Policies
  • .fragment.json → Policy Fragments
  • .folder.json → Folders
  • .key.json → Keys
  • .cert.json → Trusted Certificates

Certificate and Key Processing

Keys

  • If {{filename.p12}} reference exists, loads binary P12 and base64 encodes
  • If {{filename.pem}} reference exists, loads PEM text
  • If {{filename.certchain.pem}} reference exists, parses certificate chain

Trusted Certificates

  • Loads PEM file and extracts base64 certificate data
  • Removes PEM headers (-----BEGIN CERTIFICATE-----, etc.)

User Certificates

  • Processes certificate PEM files
  • Loads SSH public key files (.pub)

Policy Code Processing

Policy code is loaded based on file references:

  • {{filename.xml}} → Loads as XML string
  • {{filename.cjson}} → Loads and stringifies as JSON
  • {{filename.yaml}} → Loads as YAML string

WSDL Processing

  • Main WSDL: {{filename.wsdl}}
  • WSDL Resources: {{filename-wsdl-resource-N.xml}}

Tree Structure Processing

Entities in the tree/ directory are processed recursively:

tree/
└── APIs/
    └── External/
        └── CustomerAPI.service.json

The folder path is preserved in the entity.

Important Notes

  • The input directory must exist and be a valid directory
  • Unknown directories are skipped with a warning
  • Entity type is determined by directory name (plural form)
  • The tree directory is special for folder-organized entities
  • File references use double curly braces: {{filename}}
  • Binary files (P12) are automatically base64 encoded
  • Certificate chains are parsed into array format
  • Bundle properties are optional but preserved if present
  • The output bundle is automatically sorted

File Reference Formats

Single Brace (Legacy)

{
  "pem": "{MyKey.pem}"
}

Double Brace (Preferred)

{
  "pem": "{{MyKey.pem}}"
}

Both formats are supported for compatibility.

Error Handling

Common errors and solutions:

Error Solution
Directory does not exist Verify the input directory path
Unknown entities Check directory names match entity plural names
File not found Ensure referenced files exist in the directory
Invalid JSON Validate JSON syntax in entity files
Missing certificate headers Ensure PEM files have proper headers

Validation

After imploding, validate the bundle:

graphman implode --input exploded/ --output bundle.json
graphman validate --input bundle.json

Round-Trip Testing

Test explode/implode round-trip:

# Original bundle
graphman explode --input original.json --output temp/ --options.level 2
graphman implode --input temp/ --output reconstructed.json

# Compare
diff original.json reconstructed.json

Note: Some differences may occur due to:

  • Formatting changes
  • Entity ordering
  • Whitespace normalization

Related Commands

  • explode: Break bundle into multiple files
  • export: Export configuration from Gateway
  • import: Import bundle to Gateway
  • validate: Validate imploded bundle

Best Practices

  1. Always validate after imploding: graphman validate --input bundle.json
  2. Test in development before deploying imploded bundles
  3. Maintain directory structure from explode operation
  4. Use version control for exploded configurations
  5. Document manual changes made to exploded files
  6. Keep file references consistent with actual filenames
  7. Backup before imploding if overwriting existing bundles
  8. Use level 2 explode for most complete implode compatibility

Workflow Example

Complete workflow for version-controlled configuration:

#!/bin/bash
# Pull latest configuration from Git
git pull origin main

# Implode configuration
graphman implode --input config/ --output deployment.json

# Validate bundle
graphman validate --input deployment.json

# Deploy to development
graphman import --input deployment.json --gateway dev

# If successful, deploy to production
if [ $? -eq 0 ]; then
  graphman import --input deployment.json --gateway prod
fi

Troubleshooting

Missing Files

If implode fails due to missing files:

# Find all file references
grep -r "{{" exploded/ | grep -v ".json:"

# Ensure all referenced files exist

Invalid JSON

If JSON parsing fails:

# Validate JSON files
find exploded/ -name "*.json" -exec python -m json.tool {} \; > /dev/null

Certificate Issues

If certificate processing fails:

# Verify PEM format
openssl x509 -in exploded/trustedCerts/cert.pem -text -noout

Contents

Clone this wiki locally