SGNL Job Template

This repository provides a template for creating JavaScript jobs for the SGNL Job Service.

Quick Start

1. Use this template to create a new repository
2. Clone your new repository locally
3. Install dependencies: npm install
4. Modify src/script.mjs with your job logic
5. Update metadata.yaml with your job schema
6. Test locally: npm run dev
7. Run tests: npm test
8. Build: npm run build
9. Release: Create a git tag and push

Development

Local Testing

# Run the script locally with mock data
npm run dev

# Run unit tests
npm test

# Watch mode for development
npm run test:watch
npm run build:watch

# Validate metadata
npm run validate

# Lint code
npm run lint
npm run lint:fix

File Structure

• src/script.mjs - Main job implementation (⚠️ Edit this!)
• metadata.yaml - Job schema and configuration (⚠️ Edit this!)
• tests/script.test.js - Unit tests
• dist/index.js - Built script (generated by npm run build)
• scripts/ - Development utilities

Implementation Checklist

Required Changes

• Update job name and description in metadata.yaml
• Define input parameters in metadata.yaml
• Define output schema in metadata.yaml
• Implement invoke handler in src/script.mjs
• Update test mock data in tests/script.test.js
• Update README with job-specific documentation

Optional Enhancements

• Implement error handler for error recovery
• Implement halt handler for graceful shutdown
• Add additional test cases
• Customize development runner in scripts/dev-runner.js

Event Handlers

Your script must export a default object with these handlers:

invoke (Required)

Main execution logic for your job.

invoke: async (params, context) => {
  // Your job logic here
  return {
    status: 'success',
    // ... other outputs
  };
}

error (Optional)

Error recovery logic when invoke fails.

error: async (params, context) => {
  // params.error contains the original error
  // Attempt recovery or cleanup
  return {
    status: 'recovered',
    // ... recovery results
  };
}

halt (Optional)

Graceful shutdown when job is cancelled or times out.

halt: async (params, context) => {
  // params.reason contains halt reason
  // Clean up resources, save partial progress
  return {
    status: 'halted',
    cleanup_completed: true
  };
}

Context Object

The context parameter provides access to:

{
  env: {
    ENVIRONMENT: "production",
    // ... other environment variables
  },
  secrets: {
    API_KEY: "secret-key",
    // ... other secrets
  },
  outputs: {
    "previous-job-step": {
      // ... outputs from previous jobs in workflow
    }
  }
}

Testing

Unit Tests

Tests are in tests/script.test.js. Update the mock data to match your job's inputs:

const params = {
  target: 'your-target',
  action: 'your-action'
  // ... other inputs
};

Local Development

Use npm run dev to test your script locally with mock data. Update scripts/dev-runner.js to customize the test parameters.

Deployment

1. Ensure tests pass: npm test
2. Validate metadata: npm run validate
3. Build distribution: npm run build
4. Create git tag: git tag v1.0.0
5. Push to GitHub: git push origin v1.0.0

Usage in SGNL

Reference your job in a JobSpec:

{
  "id": "my-job-123",
  "type": "nodejs-22",
  "script": {
    "repository": "github.com/your-org/your-job-repo",
    "version": "v1.0.0",
    "type": "nodejs"
  },
  "script_inputs": {
    "target": "[email protected]",
    "action": "create"
  },
  "environment": {
    "ENVIRONMENT": "production"
  }
}

Support

• Job Development Guide
• SGNL Job Service