Skip to content

Renew Command

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

Renew Command

Overview

The renew command refreshes a bundle by fetching the latest details for its entities from a live Gateway. This is useful when working with partial bundles, outdated exports, or when you need complete entity information including policy revisions and dependencies.

Syntax

graphman renew --input <input-file> --gateway <name> [--sections <section>...]
  [--output <output-file>]
  [--options.<name> <value>,...]

Parameters

Required Parameters

Parameter Description
--input Input bundle file to renew
--gateway Gateway profile name to fetch entity details from

Optional Parameters

Parameter Description Default
--sections Sections to renew (entity type plural names) * (all sections)
--output Output file for renewed bundle Standard output (console)
--options.<name> Customize renew operation See defaults below

Options

Option Default Description
useGoids false Use GOIDs to identify entities instead of names
includePolicyRevisions false Include policy revision history
includeMultipartFields false Include server module file details

Behavior

Entity Identification

By default, entities are identified by their identity attributes (typically name):

  • Services: by name and resolution path
  • Policies: by name and folder path
  • Keys: by alias
  • Trusted Certificates: by subject DN

With useGoids: true, entities are identified by their GOID (Gateway Object ID).

Renewal Process

  1. For each entity in the input bundle, a query is generated
  2. The Gateway is queried to fetch the latest entity details
  3. The renewed entity replaces the original in the output bundle
  4. All sections are processed independently

Section Selection

  • Use * to renew all sections (default)
  • Specify specific sections to renew only those entity types
  • Use -section prefix to exclude specific sections
  • Unspecified sections are copied without renewal

Examples

Basic Renewal

Renew all entities in a bundle:

graphman renew --input partial-bundle.json --gateway dev --output renewed-bundle.json

Renew Specific Sections

Renew only services and policies:

graphman renew --input bundle.json --gateway dev \
  --sections services policies \
  --output renewed.json

Renew Using GOIDs

Renew entities by their GOIDs:

graphman renew --input bundle.json --gateway prod \
  --options.useGoids true \
  --output renewed.json

Renew with Policy Revisions

Include complete policy revision history:

graphman renew --input bundle.json --gateway prod \
  --options.includePolicyRevisions true \
  --output bundle-with-revisions.json

Renew Server Module Files

Include server module file details:

graphman renew --input bundle.json --gateway dev \
  --sections serverModuleFiles \
  --options.includeMultipartFields true \
  --output renewed.json

Exclude Specific Sections

Renew all except cluster properties:

graphman renew --input bundle.json --gateway dev \
  --sections "*" -clusterProperties \
  --output renewed.json

Use Cases

1. Refresh Outdated Bundle

Update an old bundle with current Gateway state:

# Old bundle from last month
graphman renew --input old-bundle.json --gateway prod --output current-bundle.json

2. Complete Partial Export

Fetch full details for a partial export:

# Export summary
graphman export --using all:summary --gateway prod --output summary.json

# Renew to get full details
graphman renew --input summary.json --gateway prod --output full-details.json

3. Cross-Environment Entity Lookup

Find entities in target environment by name:

# Bundle with entity names from dev
graphman renew --input dev-entities.json --gateway prod --output prod-entities.json

4. Policy Revision Retrieval

Get complete policy history:

graphman export --using policies --gateway prod --output policies.json

graphman renew --input policies.json --gateway prod \
  --options.includePolicyRevisions true \
  --output policies-with-history.json

5. Diff Preparation

Prepare bundles for accurate diff comparison:

# Renew both bundles
graphman renew --input dev-summary.json --gateway dev --output dev-full.json
graphman renew --input prod-summary.json --gateway prod --output prod-full.json

# Compare
graphman diff --input-source dev-full.json --input-target prod-full.json --output differences.json

6. Entity Verification

Verify entities exist in target environment:

# Try to renew entities
graphman renew --input entities-to-check.json --gateway prod --output verified.json

# Check for errors in output

7. Migration Validation

Validate migrated entities:

# After migration, renew to verify
graphman renew --input migrated-entities.json --gateway new-env \
  --output verification.json

Section Specification

Sections use entity type plural names:

Section Name Entity Type
services Web Services
policies Policies
policyFragments Policy Fragments
folders Folders
keys Private Keys
trustedCerts Trusted Certificates
jdbcConnections JDBC Connections
jmsDestinations JMS Destinations
clusterProperties Cluster Properties
scheduledTasks Scheduled Tasks
encassConfigs Encapsulated Assertions
serverModuleFiles Server Module Files

Special Section Names

Section Meaning
* All sections in the bundle
-<section> Exclude the specified section

Advanced Features

GOID-Based Renewal

When entities have been renamed or moved, use GOIDs:

graphman renew --input bundle.json --gateway prod \
  --options.useGoids true \
  --output renewed.json

This is useful when:

  • Entity names have changed
  • Entities have moved to different folders
  • You need to track entities across renames

Selective Section Renewal

Renew only specific entity types:

graphman renew --input bundle.json --gateway dev \
  --sections services policies folders \
  --output renewed-services.json

Non-renewed sections are copied as-is from the input bundle.

Server Module File Handling

When renewing server module files:

graphman renew --input bundle.json --gateway dev \
  --sections serverModuleFiles \
  --options.includeMultipartFields true \
  --output renewed.json

The actual .jar/.aar files are saved alongside the bundle.

Important Notes

  • Gateway Access Required: The Gateway must be accessible
  • Entity Must Exist: Renewal fails if entity doesn't exist in Gateway
  • Identity Matching: By default, entities are matched by name/path
  • GOID Stability: GOIDs are environment-specific
  • Performance: Large bundles may take time to renew
  • Network Dependency: Requires network access to Gateway
  • Partial Renewal: Can renew specific sections only
  • Error Handling: Errors are reported per entity

Error Handling

Common errors and solutions:

Error Solution
Gateway details are missing Configure gateway profile in graphman.configuration
Entity not found Verify entity exists in Gateway or check name/GOID
Error encountered while renewing Check Gateway connectivity and permissions
Empty result Verify entity identification (name vs GOID)

Output

The renewed bundle contains:

  • Latest entity details from the Gateway
  • Updated checksums
  • Current configuration values
  • Policy revisions (if requested)
  • Server module file metadata (if requested)

Performance Considerations

  • Renewal requires one query per entity type
  • Large bundles may take significant time
  • Network latency affects performance
  • Use specific sections to reduce renewal time
  • Consider using summary exports for faster operations

Comparison with Export

Aspect Renew Export
Input Existing bundle Query/filter criteria
Scope Entities in bundle All matching entities
Use Case Refresh known entities Discover entities
Performance Depends on bundle size Depends on query scope

Related Commands

  • export: Export entities from Gateway
  • diff: Uses renew internally for gateway comparisons
  • import: Import renewed bundles

Best Practices

  1. Use for outdated bundles - refresh old exports
  2. Renew before diff - ensure accurate comparisons
  3. Use specific sections - improve performance
  4. Use GOIDs for renamed entities - track across changes
  5. Include revisions when needed - for complete policy history
  6. Verify entity existence - check renewal output for errors
  7. Test in non-production - validate renewal before production use

Workflow Examples

Update Old Backup

#!/bin/bash
# Renew old backup with current state
graphman renew --input backups/old-backup.json --gateway prod \
  --output backups/renewed-backup.json

# Verify renewal
graphman validate --input backups/renewed-backup.json

Prepare for Migration

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

# Renew in target to check existence
graphman renew --input source-export.json --gateway target \
  --output target-existing.json 2>&1 | tee renew-log.txt

# Review log for missing entities
grep "error" renew-log.txt

Policy Revision Analysis

#!/bin/bash
# Export policies
graphman export --using policies --gateway prod --output policies.json

# Renew with revisions
graphman renew --input policies.json --gateway prod \
  --options.includePolicyRevisions true \
  --output policies-full.json

# Analyze revisions
jq '.policies[].policyRevisions | length' policies-full.json

Troubleshooting

Entity Not Found

If renewal fails for specific entities:

# Check entity names in bundle
jq '.services[].name' bundle.json

# Verify entities exist in Gateway
graphman export --using services --gateway dev --output check.json

Partial Renewal Success

If some entities renew but others fail:

  • Check Gateway logs for errors
  • Verify entity permissions
  • Ensure entity types are supported
  • Check for deleted entities

Performance Issues

If renewal is slow:

  • Renew specific sections only
  • Use smaller bundles
  • Check network connectivity
  • Consider using summary exports

Contents

Clone this wiki locally