tg-get-flow-class

Retrieves and displays a flow class definition in JSON format.

Synopsis

tg-get-flow-class -n CLASS_NAME [options]

Description

The tg-get-flow-class command retrieves a stored flow class definition from TrustGraph and displays it in formatted JSON. This is useful for examining flow class configurations, creating backups, or preparing to modify existing flow classes.

The output can be saved to files for version control, documentation, or as input for creating new flow classes with tg-put-flow-class.

Options

Required Arguments

• -n, --class-name CLASS_NAME: Name of the flow class to retrieve

Optional Arguments

• -u, --api-url URL: TrustGraph API URL (default: $TRUSTGRAPH_URL or http://localhost:8088/)

Examples

Display Flow Class Definition

tg-get-flow-class -n "document-processing"

Save Flow Class to File

tg-get-flow-class -n "production-flow" > production-flow-backup.json

Compare Flow Classes

# Get multiple flow classes for comparison
tg-get-flow-class -n "dev-flow" > dev-flow.json
tg-get-flow-class -n "prod-flow" > prod-flow.json
diff dev-flow.json prod-flow.json

Using Custom API URL

tg-get-flow-class -n "remote-flow" -u http://production:8088/

Output Format

The command outputs the flow class definition in formatted JSON:

{
    "description": "Document processing and analysis flow",
    "interfaces": {
        "agent": {
            "request": "non-persistent://tg/request/agent:doc-proc",
            "response": "non-persistent://tg/response/agent:doc-proc"
        },
        "document-rag": {
            "request": "non-persistent://tg/request/document-rag:doc-proc",
            "response": "non-persistent://tg/response/document-rag:doc-proc"
        },
        "text-load": "persistent://tg/flow/text-document-load:doc-proc",
        "document-load": "persistent://tg/flow/document-load:doc-proc",
        "triples-store": "persistent://tg/flow/triples-store:doc-proc"
    },
    "tags": ["production", "document-processing"]
}

Key Components

Description

Human-readable description of the flow class purpose and capabilities.

Interfaces

Service definitions showing:

• Request/Response Services: Services with both request and response queues
• Fire-and-Forget Services: Services with only input queues

Tags (Optional)

Categorization tags for organizing flow classes.

Prerequisites

Flow Class Must Exist

Verify the flow class exists before retrieval:

# Check available flow classes
tg-show-flow-classes

# Look for specific class
tg-show-flow-classes | grep "target-class"

Error Handling

Flow Class Not Found

Exception: Flow class 'invalid-class' not found

Solution: Check available classes with tg-show-flow-classes and verify the class name.

Connection Errors

Exception: Connection refused

Solution: Check the API URL and ensure TrustGraph is running.

Permission Errors

Exception: Access denied to flow class

Solution: Verify user permissions for accessing flow class definitions.

Use Cases

Configuration Backup

# Backup all flow classes
mkdir -p flow-class-backups/$(date +%Y%m%d)
tg-show-flow-classes | awk '{print $1}' | while read class; do
    if [ "$class" != "flow" ]; then  # Skip header
        tg-get-flow-class -n "$class" > "flow-class-backups/$(date +%Y%m%d)/$class.json"
    fi
done

Flow Class Migration

# Export from source environment
tg-get-flow-class -n "production-flow" -u http://source:8088/ > prod-flow.json

# Import to target environment
tg-put-flow-class -n "production-flow" -c "$(cat prod-flow.json)" -u http://target:8088/

Template Creation

# Get existing flow class as template
tg-get-flow-class -n "base-flow" > template.json

# Modify template and create new class
sed 's/base-flow/new-flow/g' template.json > new-flow.json
tg-put-flow-class -n "custom-flow" -c "$(cat new-flow.json)"

Configuration Analysis

# Analyze flow class configurations
tg-get-flow-class -n "complex-flow" | jq '.interfaces | keys'
tg-get-flow-class -n "complex-flow" | jq '.interfaces | length'

Version Control Integration

# Store flow classes in git
mkdir -p flow-classes
tg-get-flow-class -n "main-flow" > flow-classes/main-flow.json
git add flow-classes/main-flow.json
git commit -m "Update main-flow configuration"

JSON Processing

Extract Specific Information

# Get only interface names
tg-get-flow-class -n "my-flow" | jq -r '.interfaces | keys[]'

# Get only description
tg-get-flow-class -n "my-flow" | jq -r '.description'

# Get request queues
tg-get-flow-class -n "my-flow" | jq -r '.interfaces | to_entries[] | select(.value.request) | .value.request'

Validate Configuration

# Validate JSON structure
tg-get-flow-class -n "my-flow" | jq . > /dev/null && echo "Valid JSON" || echo "Invalid JSON"

# Check required fields
config=$(tg-get-flow-class -n "my-flow")
echo "$config" | jq -e '.description' > /dev/null || echo "Missing description"
echo "$config" | jq -e '.interfaces' > /dev/null || echo "Missing interfaces"

Integration with Other Commands

Flow Class Lifecycle

# 1. Examine existing flow class
tg-get-flow-class -n "old-flow"

# 2. Save backup
tg-get-flow-class -n "old-flow" > old-flow-backup.json

# 3. Modify configuration
cp old-flow-backup.json new-flow.json
# Edit new-flow.json as needed

# 4. Upload new version
tg-put-flow-class -n "updated-flow" -c "$(cat new-flow.json)"

# 5. Test new flow class
tg-start-flow -n "updated-flow" -i "test-instance" -d "Testing updated flow"

Bulk Operations

# Process multiple flow classes
flow_classes=("flow1" "flow2" "flow3")
for class in "${flow_classes[@]}"; do
    echo "Processing $class..."
    tg-get-flow-class -n "$class" > "backup-$class.json"
    
    # Modify configuration
    sed 's/old-pattern/new-pattern/g' "backup-$class.json" > "updated-$class.json"
    
    # Upload updated version
    tg-put-flow-class -n "$class" -c "$(cat updated-$class.json)"
done

Environment Variables

• TRUSTGRAPH_URL: Default API URL

Related Commands

• tg-put-flow-class - Upload/update flow class definitions
• tg-show-flow-classes - List available flow classes
• tg-delete-flow-class - Remove flow class definitions
• tg-start-flow - Create flow instances from classes

API Integration

This command uses the Flow API with the get-class operation to retrieve flow class definitions.

Advanced Usage

Configuration Diff

# Compare flow class versions
tg-get-flow-class -n "flow-v1" > v1.json
tg-get-flow-class -n "flow-v2" > v2.json
diff -u v1.json v2.json

Extract Queue Information

# Get all queue names from flow class
tg-get-flow-class -n "my-flow" | jq -r '
  .interfaces | 
  to_entries[] | 
  if .value | type == "object" then
    .value.request, .value.response
  else
    .value
  end
' | sort | uniq

Configuration Validation Script

#!/bin/bash
# validate-flow-class.sh
flow_class="$1"

if [ -z "$flow_class" ]; then
    echo "Usage: $0 <flow-class-name>"
    exit 1
fi

echo "Validating flow class: $flow_class"

# Get configuration
config=$(tg-get-flow-class -n "$flow_class" 2>/dev/null)
if [ $? -ne 0 ]; then
    echo "ERROR: Flow class not found"
    exit 1
fi

# Validate JSON
echo "$config" | jq . > /dev/null
if [ $? -ne 0 ]; then
    echo "ERROR: Invalid JSON structure"
    exit 1
fi

# Check required fields
desc=$(echo "$config" | jq -r '.description // empty')
if [ -z "$desc" ]; then
    echo "WARNING: Missing description"
fi

interfaces=$(echo "$config" | jq -r '.interfaces // empty')
if [ -z "$interfaces" ] || [ "$interfaces" = "null" ]; then
    echo "ERROR: Missing interfaces"
    exit 1
fi

echo "Flow class validation passed"

Best Practices

1. Regular Backups: Save flow class definitions before modifications
2. Version Control: Store configurations in version control systems
3. Documentation: Include meaningful descriptions in flow classes
4. Validation: Validate JSON structure before using configurations
5. Template Management: Use existing classes as templates for new ones
6. Change Tracking: Document changes when updating flow classes

Troubleshooting

Empty Output

# If command returns empty output
tg-get-flow-class -n "my-flow"
# Check if flow class exists
tg-show-flow-classes | grep "my-flow"

Invalid JSON Output

# If output appears corrupted
tg-get-flow-class -n "my-flow" | jq .
# Should show parsing error if JSON is invalid

Permission Issues

# If access denied errors occur
# Verify authentication and user permissions
# Contact system administrator if needed