# 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 ```bash graphman explode --input --output [--options. ,...] ``` ## 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: ```bash graphman explode --input bundle.json --output exploded/ ``` ### Intermediate Explosion (Level 1) Include certificates and WSDL resources: ```bash graphman explode --input bundle.json --output exploded/ --options.level 1 ``` ### Complete Explosion (Level 2) Explode everything including policy code: ```bash graphman explode --input bundle.json --output exploded/ --options.level 2 ``` ### Explode for Version Control Explode bundle for Git repository: ```bash 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: ```bash 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: ```bash # 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: `.service.json` - Policies: `.policy.json` - Policy Fragments: `.fragment.json` - Folders: `.folder.json` - Keys: `.key.json` - Trusted Certificates: `.cert.json` ### Associated Files - WSDL: `.wsdl` - WSDL Resources: `-wsdl-resource-.xml` - Policy XML: `.xml` - Policy JSON: `.cjson` - Policy YAML: `.yaml` - Policy Revisions: `-revision-.xml` - Certificate PEM: `.pem` - Key P12: `.p12` - Certificate Chain: `.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: ```json // 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: ```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](Implode-Command.md)**: Reverse operation - combine files back into bundle - **[export](Export-Command.md)**: Export configuration before exploding - **[slice](Slice-Command.md)**: 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: ```bash #!/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 ```