Input/Output Handling

Understand how Generic artifacts handle input props and output values.

Input Handling

Reading Props

Your container receives props as a JSON file mounted at /workspace/vars.json:

{
  "database_host": "postgres.example.com",
  "database_name": "mydb",
  "migration_version": "v1.2.3",
  "enable_logging": true,
  "retry_count": 3
}

Reading in Different Languages

Python:

import json

def read_vars():
    with open('/workspace/vars.json', 'r') as f:
        return json.load(f)

vars = read_vars()
database_host = vars['database_host']

Node.js:

const fs = require('fs');

const vars = JSON.parse(fs.readFileSync('/workspace/vars.json', 'utf8'));
const databaseHost = vars.database_host;

Bash:

#!/bin/bash
VARS_FILE="/workspace/vars.json"

DATABASE_HOST=$(jq -r '.database_host' "$VARS_FILE")
DATABASE_NAME=$(jq -r '.database_name' "$VARS_FILE")

Output Handling

Writing Outputs

Your container must write results to /workspace/outputs.json:

{
  "migration_status": "success",
  "rows_affected": 150,
  "completion_time": "2024-01-15T10:30:00Z"
}

Writing in Different Languages

Python:

import json
from datetime import datetime

def write_outputs(data):
    with open('/workspace/outputs.json', 'w') as f:
        json.dump(data, f, indent=2)

write_outputs({
    'migration_status': 'success',
    'rows_affected': 150,
    'completion_time': datetime.utcnow().isoformat()
})

Node.js:

const fs = require('fs');

const outputs = {
    migration_status: 'success',
    rows_affected: 150,
    completion_time: new Date().toISOString()
};

fs.writeFileSync('/workspace/outputs.json', JSON.stringify(outputs, null, 2));

Bash:

#!/bin/bash

cat > /workspace/outputs.json <<EOF
{
  "migration_status": "success",
  "rows_affected": 150,
  "completion_time": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
EOF

Output Contract

Bluebricks processes the outputs.json file after your container exits. Follow these requirements:

Requirement	Details
File name	outputs.json (exact name)
Location	/workspace/outputs.json
Size limit	≤ 1 MiB. Larger files are rejected or truncated
Structure	Single flat JSON object (top-level must be an object, not an array)
Nesting	Nested objects/arrays are allowed as values
Value types	string, number, boolean, object, array
Processing	Parsed immediately after container exit and registered as deployment outputs

Example valid output:

{
  "some_value": "test",
  "execution_time": 42,
  "config": {
    "nested": "value"
  },
  "items": ["a", "b", "c"]
}

After a successful run, outputs can be referenced by other packages using Data.<package_id>.<output_key> (e.g., Data.my_package.some_value).

Required Outputs

job_id

Bluebricks automatically adds job_id if not present in your outputs:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "custom_output": "value"
}

If you don't include it:

{
  "custom_output": "value"
}

Bluebricks adds it automatically:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "custom_output": "value"
}

Data Types

Supported Input Types

Type	Example	Description
string	"hello"	Text values
number	42	Numeric values
bool	true	Boolean values
list	["a", "b"]	Array of values
map	{"key": "value"}	Object/dictionary

Supported Output Types

Type	Example	Description
string	"success"	Text results
number	150	Numeric results
bool	true	Boolean results
list	["item1", "item2"]	Array results
map	{"status": "ok"}	Object results

Error Handling

Success Case

try:
    # Your logic here
    result = perform_operation()
    
    write_outputs({
        'status': 'success',
        'result': result
    })
    sys.exit(0)
    
except Exception as e:
    write_outputs({
        'status': 'failed',
        'error': str(e)
    })
    sys.exit(1)

Failure Case

#!/bin/bash
set -e

# If any command fails, script exits with non-zero code
# Bluebricks will detect the failure

if ! perform_operation; then
    cat > /workspace/outputs.json <<EOF
{
  "status": "failed",
  "error": "Operation failed"
}
EOF
    exit 1
fi

# Success case
cat > /workspace/outputs.json <<EOF
{
  "status": "success"
}
EOF
exit 0

Best Practices

Input Validation

def validate_inputs(vars):
    required_fields = ['database_host', 'database_name']
    
    for field in required_fields:
        if field not in vars:
            raise ValueError(f"Missing required field: {field}")
    
    if not isinstance(vars.get('retry_count', 1), int):
        raise ValueError("retry_count must be an integer")

Output Validation

def validate_outputs(outputs):
    required_outputs = ['status']
    
    for field in required_outputs:
        if field not in outputs:
            raise ValueError(f"Missing required output: {field}")
    
    if outputs['status'] not in ['success', 'failed']:
        raise ValueError("status must be 'success' or 'failed'")

Error Reporting

def write_error_output(error_message, error_code=None):
    outputs = {
        'status': 'failed',
        'error_message': error_message,
        'timestamp': datetime.utcnow().isoformat()
    }
    
    if error_code:
        outputs['error_code'] = error_code
    
    write_outputs(outputs)

Testing Input/Output

Local Testing

# Create test vars.json
cat > /tmp/vars.json << 'EOF'
{
  "database_host": "localhost",
  "database_name": "test_db",
  "migration_version": "v1.0.0"
}
EOF

# Run container with mounted files
docker run --rm \
  -v /tmp/vars.json:/workspace/vars.json \
  -v $(pwd)/src:/workspace/src \
  python:3.11-slim \
  python /workspace/src/migrate.py

# Check outputs
cat /tmp/outputs.json

See also

• Container Configuration -- image, command, and environment setup

• Generic Artifact Lifecycle -- plan, apply, and destroy stage configuration

• Generic Artifact State -- change tracking and execution behavior