# 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

```bash
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:

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

### Renew Specific Sections

Renew only services and policies:

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

### Renew Using GOIDs

Renew entities by their GOIDs:

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

### Renew with Policy Revisions

Include complete policy revision history:

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

### Renew Server Module Files

Include server module file details:

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

### Exclude Specific Sections

Renew all except cluster properties:

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
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:

```bash
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-Command.md)**: Export entities from Gateway
- **[diff](Diff-Command.md)**: Uses renew internally for gateway comparisons
- **[import](Import-Command.md)**: 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

```bash
#!/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

```bash
#!/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

```bash
#!/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:

```bash
# 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