Skip to main content
Version: Unreleased

Migration Guide: v1.0.0 to v2.0.0

This guide explains how to migrate AutoTrigger job definitions from the legacy v1.0.0 schema to the current v2.0.0 schema.

Overview​

The v2.0.0 schema provides a simplified, more intuitive structure that better reflects the actual execution flow:

  • v1.0.0: Uses functionReferenceList with nested data, transport, and actions
  • v2.0.0: Uses flat pipeline structure with sources, transform, output, delivery, and action

Both schemas are currently supported for backward compatibility, but new reports should use v2.0.0.

Key Changes​

1. Root Structure​

v1.0.0:

{
  "function": {
    "functionReferenceList": [...]
  }
}

v2.0.0:

{
  "pipeline": {
    "sources": [...],
    "transform": {...},
    "output": {...},
    "delivery": {...},
    "action": [...]
  }
}

2. Field Name Changes​

v1.0.0 Fieldv2.0.0 Field
function.functionReferenceListpipeline (single object)
functionReferenceList[].data.selectionpipeline.sources
functionReferenceList[].data.transformationspipeline.transform
functionReferenceList[].data.formatChannelpipeline.output.formats
functionReferenceList[].transportpipeline.delivery.channels
functionReferenceList[].actionspipeline.action

3. Metadata Structure​

v1.0.0:

{
  "version": "1.0.0",
  "cronDefinition": "0 8 * * *"
}

v2.0.0:

{
  "metadata": {
    "schemaVersion": "2.0.0"
  },
  "schedule": {
    "cron": "0 8 * * *"
  }
}

Typical Scenarios​

The following examples demonstrate common AutoTrigger job configurations and their migration from v1.0.0 to v2.0.0.

Example 1: Basic PDF Report​

{
  "$schema": "/api/asyncJobs/schema",
  "name": "Daily Report",
  "description": "PDF report",
  "enabled": true,
  "metadata": {
    "schemaVersion": "1.0.0"
  },
  "schedule": {
    "cron": "0 6 * * *"
  },
  "type": "user",
  "pipeline": {
    "functionReferenceList": [
      {
        "reportName": "Daily Report",
        "description": "Daily PDF report",
        "data": {
          "selection": [
            {
              "dataSource": "es",
              "variableName": "CallData",
              "parameters": [
                { "index": "calls" },
                { "size": 0, "query": { ... }, "aggs": { ... } }
              ]
            }
          ],
          "transformations": {
            "transformationType": "js",
            "code": "return data;"
          },
          "formatChannel": [
            {
              "transformationType": "toPdf",
              "parameters": {
                "pageSize": "A4",
                "orientation": "landscape",
                "charts": [
                  {
                    "variableName": "CallData",
                    "chartTitle": "Call Volume"
                  }
                ]
              }
            }
          ]
        },
        "transport": ["emailChannelId"]
      }
    ]
  }
}

Key Differences:

  • pipeline.functionReferenceList[] → pipeline (single object)
  • data.selection → sources
  • data.transformations → transform
  • data.formatChannel → output.formats
  • transport → delivery.channels
  • metadata.schemaVersion and schedule.cron at root level

Note: Each scenario demonstrates a different use case. Choose the example that best matches your requirements and adapt the field values accordingly.

warning

Named Function References - Future Feature Named function references via codeFunctionReference are planned for a future release. Currently, only inline code transformations work. Do not rely on codeFunctionReference in production until explicitly supported.

Migration Steps​

Step 1: Export Your Current Jobs​

  1. Open the AutoTrigger dashboard
  2. Select each job you want to migrate
  3. Click Export to download the JSON configuration

Step 2: Review Schema Version​

Check the version or metadata.schemaVersion field to confirm the schema version:

  • "version": "1.0.0" → Needs migration
  • "metadata": { "schemaVersion": "2.0.0" } → Already on v2

Step 3: Update Root Fields​

Replace:

"version": "1.0.0",
"cronDefinition": "..."

With:

"metadata": {
  "schemaVersion": "2.0.0"
},
"schedule": {
  "cron": "..."
}

Step 4: Restructure Pipeline​

Replace the entire function.functionReferenceList structure with a pipeline object:

Before:

"function": {
  "functionReferenceList": [
    {
      "reportName": "...",
      "description": "...",
      "data": {
        "selection": [...],
        "transformations": {...},
        "formatChannel": [...]
      },
      "transport": [...],
      "actions": [...]
    }
  ]
}

After:

"pipeline": {
  "sources": [...],
  "transform": {...},
  "output": {
    "formats": [...]
  },
  "delivery": {
    "channels": [...]
  },
  "action": [...]
}

Step 5: Update Field Names​

Apply these field name changes:

  • data.selection → sources
  • data.transformations → transform
  • data.formatChannel → output.formats
  • transport → delivery.channels
  • actions → action

Step 6: Validate and Test​

  1. Import the updated JSON using Import Job Config
  2. Click Run Now to test the job
  3. Check the execution history for any errors
  4. Verify the output matches your expectations

Common Migration Issues​

Issue 1: Missing Transform​

Problem: v2.0.0 requires an explicit transform field.

Solution: Add a default transformation with inline code:

"transform": {
  "transformationType": "js",
  "code": "return data;"
}
warning

Transformation Options Currently only inline code transformations are supported. The codeFunctionReference field is a future feature.

Issue 2: Missing Output Formats​

Problem: v2.0.0 requires at least one output format in output.formats.

Solution: Add at least one format (e.g., JSON):

"output": {
  "formats": [
    { "transformationType": "toJson", "parameters": {} }
  ]
}

Issue 3: Multiple Reports in One Job​

Problem: v1.0.0 supported functionReferenceList with multiple report definitions. v2.0.0 uses a single pipeline.

Solution: Create separate jobs for each report, or combine logic into a single transformation that outputs all required formats.

Validation​

After migration, verify:

  1. Schema validation passes - The editor should not show validation errors
  2. Job runs successfully - Click Run Now and check execution history
  3. Output is correct - Verify generated files match expectations
  4. Scheduled execution works - Wait for next scheduled run or trigger manually

Support​

If you encounter issues during migration:

  1. Check the execution history for error messages
  2. Validate JSON against the schema at /api/asyncJobs/schema
  3. Compare your configuration with the examples in this guide
  4. Contact support with the error message and job configuration

Appendix: Field Reference​

Schema Field Comparison​

The following table shows the key field changes between v1.0.0 and v2.0.0:

Aspectv1.0.0v2.0.0Migration Notes
Schema versionmetadata.schemaVersion: "1.0.0"metadata.schemaVersion: "2.0.0"Keep in metadata object
Scheduleschedule.cronschedule.cronSame structure
Pipeline containerpipeline.functionReferenceList[]pipelineSingle object instead of array
Data sourcesdata.selectionpipeline.sourcesArray of source definitions
Transformationsdata.transformationspipeline.transformSingular, now at pipeline level
Output formatsdata.formatChannelpipeline.output.formatsNested under output object (required)
Delivery channelstransportpipeline.delivery.channelsNested under delivery object
Actionsactionspipeline.actionSingular form
Job namename (root)name (root)Same

Transformation Fields​

Fieldv1.0.0v2.0.0Status
Transformation typetransformationTypetransformationTypeSame
Inline codecodecodeSame
Named function refcodeFunctionReferencecodeFunctionReferenceFuture feature
tip

Current Best Practice Use inline code for transformations until codeFunctionReference is officially supported:

"transform": {
  "transformationType": "js",
  "code": "function(data) { return data; }"
}

References​