Combine Command

Combine Command

Overview

The combine command merges two or more Gateway configuration bundles into a single unified bundle. This is useful for consolidating configurations from multiple sources or environments.

Syntax

graphman combine --inputs <input-file> <input-file> ... [--output <output-file>]

Parameters

Required Parameters

Parameter	Description
--inputs	Two or more input bundle files to combine. At least two bundles are required.

Optional Parameters

Parameter	Description	Default
--output	Specify the output file to save the combined bundle	Standard output (console)

Behavior

Merge Strategy

When combining bundles, the command follows these rules:

1. Rightmost Precedence: When similar entities are encountered across multiple bundles, entities from the rightmost bundle take precedence
2. Entity Matching: Entities are matched based on their identifying attributes (e.g., name, GUID)
3. Non-duplicate Preservation: Unique entities from all bundles are preserved in the result
4. Automatic Sorting: The output bundle is automatically sorted for consistency

Processing Order

The combine operation processes bundles from left to right:

1. All entities from the rightmost bundle are added first
2. Entities from other bundles are added only if they don't already exist
3. The final result contains all unique entities with rightmost precedence for duplicates

Examples

Basic Combination

Combine two bundles into one:

graphman combine --inputs bundle1.json bundle2.json --output combined.json

Multiple Bundle Combination

Combine three or more bundles:

graphman combine --inputs base.json dev.json prod.json --output final.json

In this example:

• Entities unique to base.json are included
• Entities unique to dev.json are included
• Entities from prod.json override any matching entities from base.json or dev.json

Output to Console

Combine bundles and output to standard output:

graphman combine --inputs bundle1.json bundle2.json

Use Cases

1. Environment Configuration Merging

Combine a base configuration with environment-specific overrides:

graphman combine --inputs base-config.json production-overrides.json --output prod-config.json

2. Incremental Configuration Building

Build up a configuration from multiple smaller bundles:

graphman combine \
  --inputs core-services.json \
           security-policies.json \
           custom-assertions.json \
  --output complete-config.json

3. Configuration Consolidation

Merge configurations from multiple gateways into a unified bundle:

graphman combine --inputs gateway1.json gateway2.json gateway3.json --output consolidated.json

Important Notes

• Minimum Requirement: At least two input bundles must be provided
• Entity Identification: Entities are matched using their unique identifiers (typically name and/or GUID)
• Precedence Rule: Always remember that rightmost bundles take precedence in case of conflicts
• Automatic Sorting: The output is automatically sorted, ensuring consistent formatting
• File Format: All input files must be valid Gateway configuration bundles in JSON format

Error Handling

The command will fail if:

• The --inputs parameter is missing
• Fewer than two input bundles are provided
• Any input file cannot be read or is not a valid bundle format

Related Commands

• export: Export configuration from a Gateway
• import: Import a bundle to a Gateway
• diff: Compare two bundles to see differences

Technical Details

Algorithm

The combine operation uses the following algorithm:

1. Initialize an empty result bundle
2. Process the rightmost bundle first, adding all its entities to the result
3. Process remaining bundles from left to right:
   • For each entity in the current bundle
   • Check if a matching entity exists in the result
   • If no match is found, add the entity to the result
4. Sort the final result bundle for consistent output