Revise Command

Revise Command

Overview

The revise command updates a bundle to conform to schema changes, normalize entity structures, and apply transformations. It's essential for migrating bundles between Gateway versions and ensuring bundle compatibility.

Syntax

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

Parameters

Required Parameters

Parameter	Description
--input	Input bundle file to revise

Optional Parameters

Parameter	Description	Default
--output	Output file for revised bundle	Standard output (console)
--options.<name>	Customize revise operation	See defaults below

Options

Option	Default	Description
normalize	false	Normalize/sanitize bundle for import
excludeGoids	false	Remove GOIDs from entities (requires normalize)

Behavior

Schema Revision

The revise command automatically:

• Updates entity structures to match current schema
• Adds new required fields with default values
• Removes deprecated fields
• Transforms field values to new formats
• Adjusts entity relationships

Normalization

When normalize: true:

• Sanitizes bundle for import operations
• Removes duplicate entities
• Validates entity structures
• Applies import-ready transformations
• Optionally removes GOIDs

Examples

Basic Revision

Revise bundle to current schema:

graphman revise --input old-bundle.json --output revised-bundle.json

Revise with Normalization

Normalize bundle for import:

graphman revise --input bundle.json --output normalized.json --options.normalize true

Revise and Remove GOIDs

Prepare portable bundle without GOIDs:

graphman revise --input bundle.json --output portable.json \
  --options.normalize true \
  --options.excludeGoids true

Revise to Console

View revised bundle without saving:

graphman revise --input bundle.json --options.normalize true

Use Cases

1. Gateway Version Migration

Migrate bundle from older Gateway version:

# Export from old gateway (v10.x)
graphman export --gateway old-gw --output old-version.json

# Revise for new gateway (v11.x)
graphman revise --input old-version.json --output migrated.json

# Import to new gateway
graphman import --input migrated.json --gateway new-gw

2. Schema Compatibility

Update bundle to match current schema:

graphman revise --input legacy-bundle.json --output current-schema.json

3. Cross-Environment Portability

Prepare bundle for cross-environment deployment:

graphman revise --input dev-bundle.json --output portable.json \
  --options.normalize true \
  --options.excludeGoids true

4. Bundle Cleanup

Clean up and normalize a bundle:

graphman revise --input messy-bundle.json --output clean-bundle.json \
  --options.normalize true

5. Duplicate Removal

Remove duplicate entities from bundle:

graphman revise --input bundle-with-dupes.json --output deduplicated.json \
  --options.normalize true

6. Import Preparation

Prepare exported bundle for import:

# Export from source
graphman export --gateway source --output export.json

# Revise for import
graphman revise --input export.json --output import-ready.json \
  --options.normalize true \
  --options.excludeGoids true

# Import to target
graphman import --input import-ready.json --gateway target

7. Version Control Preparation

Prepare bundle for version control:

graphman revise --input bundle.json --output vcs-ready.json \
  --options.normalize true \
  --options.excludeGoids true

Schema Changes Handled

The revise command handles various schema changes:

Field Additions

New required fields are added with defaults:

// Before revision
{
  "name": "MyService",
  "enabled": true
}

// After revision (if new field added to schema)
{
  "name": "MyService",
  "enabled": true,
  "newField": "defaultValue"
}

Field Removals

Deprecated fields are removed:

// Before revision
{
  "name": "MyService",
  "enabled": true,
  "deprecatedField": "value"
}

// After revision
{
  "name": "MyService",
  "enabled": true
}

Field Transformations

Field values are transformed to new formats:

// Before revision
{
  "timeout": "30"
}

// After revision
{
  "timeout": 30
}

Structure Changes

Entity structures are updated:

// Before revision
{
  "properties": "key1=value1,key2=value2"
}

// After revision
{
  "properties": [
    {"key": "key1", "value": "value1"},
    {"key": "key2", "value": "value2"}
  ]
}

Normalization Details

What Normalization Does

1. Sanitizes for Import

   • Removes export-only fields
   • Adds import-required fields
   • Adjusts entity mappings

2. Removes Duplicates

   • Identifies duplicate entities
   • Keeps one instance per unique entity
   • Preserves entity relationships

3. Validates Structure

   • Ensures required fields exist
   • Validates field types
   • Checks entity relationships

4. Applies Transformations

   • Converts data types
   • Normalizes field values
   • Updates entity references

GOID Exclusion

When excludeGoids: true (requires normalize: true):

• Removes all GOID fields from entities
• Makes bundle portable across environments
• Entities will get new GOIDs on import
• Useful for version control and templates

Important Notes

• Schema Version: Uses the configured schema version
• Backward Compatibility: Handles older bundle formats
• Forward Compatibility: Updates to current schema
• Normalization Required: excludeGoids requires normalize: true
• Bundle Properties: Preserved during revision
• Entity Order: Output is automatically sorted
• Non-Destructive: Original bundle is not modified
• Validation: Consider validating after revision

Schema Version

The revise command uses the schema version specified in:

1. Command line: --options.schema v11.2.0
2. Configuration file: graphman.configuration
3. Default: Latest supported schema version

graphman revise --input bundle.json --output revised.json --options.schema v11.1.1

Error Handling

Common errors and solutions:

Error	Solution
Input parameter is missing	Provide --input parameter
Invalid bundle format	Validate input bundle JSON syntax
Schema version not supported	Check supported versions with version command
Normalization failed	Check bundle structure and entity validity

Validation

Always validate after revising:

graphman revise --input bundle.json --output revised.json --options.normalize true
graphman validate --input revised.json

Performance

• Revision is generally fast (< 1 second for typical bundles)
• Large bundles (1000+ entities) may take longer
• Normalization adds minimal overhead
• Duplicate removal depends on entity count

Related Commands

• validate: Validate revised bundles
• export: Export with normalization options
• import: Import revised bundles
• schema: View schema information

Best Practices

1. Always revise before import when migrating between versions
2. Use normalize for imports to ensure bundle is import-ready
3. Exclude GOIDs for portability when deploying across environments
4. Validate after revision to catch any issues
5. Test in non-production before production deployment
6. Keep original bundles as backup before revision
7. Document schema version used for revision
8. Use version control for revised bundles

Workflow Examples

Version Migration Workflow

#!/bin/bash
# Export from old gateway
graphman export --gateway old-v10 --output old-export.json

# Revise for new schema
graphman revise --input old-export.json --output migrated.json \
  --options.normalize true

# Validate
graphman validate --input migrated.json

# Import to new gateway
graphman import --input migrated.json --gateway new-v11

Cross-Environment Deployment

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

# Revise and make portable
graphman revise --input dev-export.json --output portable.json \
  --options.normalize true \
  --options.excludeGoids true

# Deploy to test
graphman import --input portable.json --gateway test

# Deploy to prod
graphman import --input portable.json --gateway prod

Bundle Maintenance

#!/bin/bash
# Revise bundle to current schema
graphman revise --input old-bundle.json --output updated.json \
  --options.normalize true

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

# Commit to Git
git add config/
git commit -m "Updated bundle to current schema"

Troubleshooting

Revision Changes Bundle Unexpectedly

If revision makes unexpected changes:

• Review schema changes between versions
• Check field deprecations and additions
• Validate entity structures
• Compare before/after with diff tool

Normalization Fails

If normalization fails:

• Validate input bundle JSON syntax
• Check for malformed entities
• Verify entity relationships
• Review error messages for specific issues

GOID Exclusion Not Working

If GOIDs are not removed:

• Ensure normalize: true is set
• Verify excludeGoids: true is set
• Check that entities have GOID fields

Advanced Usage

Custom Schema Version

Revise to specific schema version:

graphman revise --input bundle.json --output revised.json \
  --options.schema v11.1.1 \
  --options.normalize true

Batch Revision

Revise multiple bundles:

#!/bin/bash
for file in bundles/*.json; do
  output="revised/$(basename $file)"
  graphman revise --input "$file" --output "$output" \
    --options.normalize true \
    --options.excludeGoids true
done

Revision with Validation

Revise and validate in one workflow:

#!/bin/bash
graphman revise --input bundle.json --output revised.json \
  --options.normalize true

if graphman validate --input revised.json; then
  echo "Revision successful and valid"
else
  echo "Revision produced invalid bundle"
  exit 1
fi