Complete Job Bundle Format

An Ordyn complete job bundle is a ZIP archive that contains one portable job definition and the dependencies that should travel with it. Use this format when generating a complete job outside Ordyn or when an automation needs to assemble a job, scripts, collectors, managed files, and a self-service icon into one importable file.

The current format is job_definition_bundle schema version 1. Name generated archives with the .ordyn-job.zip suffix.

Authoring Resources

The documentation source includes these machine-readable JSON Schemas:

• json-schemas/job-definition-bundle-v1.schema.json, for manifest.json
• json-schemas/job-definition-v1.schema.json, for job.document
• json-schemas/script-v1.schema.json, for every bundled script document

A complete source tree is available at builder-json/examples/job-definition-bundle-v1. It can be zipped as-is and demonstrates scripts, a collector, a managed file, a file folder, a persistent variable, and an external reference.

JSON Schema validates document structure. It cannot verify ZIP entry checksums, source-ID relationships, folder cycles, or whether every environment-specific identifier has an external-reference declaration. Apply the rules on this page in addition to schema validation.

Archive Layout

manifest.json must be at the ZIP root. Every other entry must be declared by a file blob or the self-service icon in the manifest.

portable-diagnostics.ordyn-job.zip
├── manifest.json
└── files/
    └── diagnostics.conf

Archive paths:

• use / as the separator
• must be relative and non-empty
• may not contain empty, ., or .. segments
• may not contain backslashes, drive-letter prefixes, null bytes, or symbolic links
• must be unique when compared case-insensitively
• must identify files; explicit directory-marker entries such as files/ are not allowed

The archive may contain at most 10,000 entries, 15 GiB of uncompressed content, and a 1 MiB manifest.json. An entry larger than 1 MiB is rejected when its uncompressed size exceeds 100 times its compressed size. Storing generated payload entries without compression is a safe default.

Manifest Structure

The root object contains:

Field	Required	Description
schema_version	yes	Integer 1.
kind	yes	String job_definition_bundle.
generated_at	no	ISO 8601 generation timestamp.
job	yes	The root job source ID and complete job-definition document.
scripts	yes	Saved script entries carried by the bundle. Use an empty list when none are included.
collectors	yes	Collector entries carried by the bundle. Use an empty list when none are included.
file_folders	yes	Portable managed-file folder hierarchy. Use an empty list when none are included.
files	yes	Portable managed-file declarations. Use an empty list when none are included.
variable_definitions	yes	Persistent variable definitions used by the job. Use an empty list when none are included.
self_service_icon	yes	An icon blob declaration or null.
external_references	yes	Environment-specific references requiring import-time mapping. Use an empty list when none exist.

Minimal structure:

{
  "schema_version": 1,
  "kind": "job_definition_bundle",
  "job": {
    "source_id": "source-job-id",
    "document": {
      "schema_version": 1,
      "kind": "job_definition",
      "name": "Portable job",
      "target_timeout_seconds": 3600,
      "requirements": [],
      "desktop_execution": {},
      "user_interaction": {},
      "tasks": [
        {
          "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
          "kind": "log_message",
          "name": "Record context",
          "capability": null,
          "payload": {
            "message": "Running on {{ endpoint.hostname }}."
          },
          "enabled": true,
          "continue_on_error": false,
          "expires_in_seconds": null
        }
      ]
    }
  },
  "scripts": [],
  "collectors": [],
  "file_folders": [],
  "files": [],
  "variable_definitions": [],
  "self_service_icon": null,
  "external_references": []
}

Use the complete job-definition schema and the available-task documentation when authoring the job document.

Source IDs And Portable References

Every job, script, collector, file folder, file, and variable definition has a non-empty source_id. Source IDs identify objects inside the bundle; they do not need to exist in the destination environment. UUIDs are recommended because exported Ordyn resources already use them.

Source IDs must be unique within each section. Use them wherever the job refers to a bundled dependency:

• job.document.tasks[*].script_id points to a bundled script source_id
• job.document.tasks[*].collector_definition_id points to a bundled collector source_id
• a collector's script_source_id points to a bundled script source_id
• file_folders[*].parent_source_id points to another bundled folder source_id
• files[*].folder_source_id points to a bundled folder source_id
• a set_variable_override task's payload.variable_definition_id points to a bundled variable-definition source_id
• file.place payload file_id points to a bundled file source_id
• file.folder_sync payload folder_id points to a bundled folder source_id

References inside then_tasks, else_tasks, and body_tasks follow the same rules. Do not add bundled dependency references to external_references; Ordyn replaces them with the newly imported or explicitly reused local resources.

Persistent Variables

Include each persistent variable definition used by the job in variable_definitions. Runtime values below job.vars.* are created while a job runs and do not belong in this section.

{
  "source_id": "source-variable-id",
  "key": "vars.diagnostics.channel",
  "label": "Diagnostics channel",
  "description": "Selects the channel used by the diagnostics job.",
  "kind": "custom",
  "value_type": "string",
  "is_secret": false,
  "default_value": "stable",
  "default_secret_id": null
}

The destination resolves definitions by key:

• A definition with the same kind, value type, and secrecy setting is reused. Its local label, description, folder, and default remain unchanged.
• A missing custom definition can be created by a super administrator. It is created at the Variables root with the bundled metadata and safe default.
• A missing system definition blocks import.
• A same-key definition with a different kind, value type, or secrecy setting blocks import. Definitions are not renamed or overwritten.

For custom non-secret definitions, default_value may contain the default. For custom secret definitions, set default_value to null and put the source secret ID in default_secret_id; declare that field as a required secret external reference. The import review requests that mapping when it must create the definition. A compatible reused destination definition keeps its local default and does not require the bundled default-secret mapping. Secret contents are never stored in the bundle. System definitions always use null for both default fields.

Do not include current global, tenant, folder, group, endpoint, product, or package overrides. A set_variable_override task is job logic and may remain in the job document. Its definition source ID is resolved from variable_definitions; its concrete secret and tenant, endpoint-folder, group, or endpoint target must be declared in external_references.

Ordyn exports definitions selected by set_variable_override tasks and definitions whose known vars.* keys occur in the job document, including nested task payloads and expressions. References inside saved-script source code and managed-file contents are not scanned automatically. Add those definitions explicitly when constructing a bundle outside Ordyn.

Scripts And Collectors

Each script entry contains a source_id and a complete version 1 script document:

{
  "source_id": "source-script-id",
  "document": {
    "schema_version": 1,
    "kind": "script",
    "name": "Collect health",
    "description": null,
    "folder_id": null,
    "platform": "linux",
    "execution_target": "endpoint",
    "interpreter": "bash",
    "windows_execution_context": {
      "mode": "local_system",
      "account_id": null,
      "logged_in_user_identifier": null
    },
    "execution_mode": "blocking",
    "windows_desktop_mode": "default_session",
    "content": "printf '{\"healthy\":true}\\n'\n",
    "output_mode": "json",
    "output_schema": [],
    "exit_code_mappings": [],
    "parameters": [],
    "timeout_seconds": 300
  }
}

Set bundled script folder_id to null. Script folders are environment-specific and are not recreated by complete job import.

A collector contains its own settings and points to a bundled script:

{
  "source_id": "source-collector-id",
  "script_source_id": "source-script-id",
  "name": "Endpoint health",
  "description": null,
  "platform": "linux",
  "execution_target": "endpoint",
  "enabled": true,
  "output_validation_mode": "strict",
  "fields": []
}

The script interpreter and execution target must be compatible with the collector platform. A collector inherits its execution context from the referenced script. Linux endpoint collectors use Bash. Windows endpoint collectors use PowerShell or CMD. Server collectors use a server-targeted Bash script.

Managed Files And Icons

Each file entry describes the library file and its ZIP payload:

{
  "source_id": "source-file-id",
  "name": "diagnostics.conf",
  "mime_type": "text/plain",
  "folder_source_id": "source-folder-id",
  "blob": {
    "archive_path": "files/diagnostics.conf",
    "original_name": "diagnostics.conf",
    "mime_type": "text/plain",
    "extension": "conf",
    "size_bytes": 52,
    "checksum_sha256": "a7d254fb3bbe28803eadba2bb1df0ebb747bbca6af6891479e9f88b61720ec61"
  }
}

size_bytes is the exact uncompressed byte count. checksum_sha256 is the lowercase hexadecimal SHA-256 of the uncompressed entry contents. The declared archive entry must exist and match both values.

The self-service icon uses the same blob structure directly. It does not have a source_id, file name, or folder declaration. The payload must be a PNG image no larger than 128×128 pixels, with mime_type set to image/png and extension set to png.

File folders form a tree:

{
  "source_id": "source-folder-id",
  "parent_source_id": null,
  "name": "Portable diagnostics"
}

Every non-null parent must exist in file_folders, and the hierarchy may not contain cycles. During import, the operator chooses the destination below which these folders and files are created.

External References

Anything that must already exist in the destination environment belongs in external_references. Each entry describes one concrete identifier in the manifest:

{
  "key": "job.document.folder_id:folder_job:source-folder-id",
  "path": "job.document.folder_id",
  "label": "Job folder",
  "context_label": null,
  "reference_type": "folder_job",
  "original_value": "source-folder-id",
  "required": false,
  "clear_strategy": "null"
}

Rules:

• key must be unique. Use <path>:<reference_type>:<original_value> for predictable keys.
• path is a dot-separated path from the manifest root. Array indexes are numeric path segments.
• original_value must match the concrete value at path.
• required controls whether import must select a local replacement.
• clear_strategy is null for nullable fields and remove_array_item for optional list entries.
• context_label can identify the task or script containing the reference.
• Template expressions such as {{ job.vars.package_id }} remain dynamic and do not need an external-reference declaration.

Supported reference types are:

agent_release, collector_definition, driver_profile, endpoint, endpoint_group, file, folder_endpoint, folder_file, folder_job, install_answer_file, operating_system, os_image, package, script, secret, self_service_category, software_update_policy, software_product, software_product_variant, tenant, variable_definition, and windows_account.

Declare every concrete environment-specific identifier, including references in nested tasks and bundled scripts. Common locations include:

• the job folder and self-service category list
• task endpoints, packages, products, variants, operating systems, OS images, non-bundled scripts, and non-bundled collectors
• task payload files, file folders, source endpoints, agent releases, Wimboot images, update policies, install-answer files, and driver profiles
• bundled script Windows accounts and default secret parameters
• variable default secrets and concrete scope targets or secrets used by set_variable_override tasks

For an optional list entry such as a self-service category or driver profile, use remove_array_item. For an optional scalar such as the job folder, use null.

Construction Checklist

1. Author and validate the complete job.document.
2. Assign source IDs to every portable dependency.
3. Replace job references to portable dependencies with those source IDs.
4. Add every saved script used directly by the job or by a bundled collector.
5. Add collectors and point each script_source_id to its bundled script.
6. Add the persistent variable definitions referenced by the job.
7. Add file folders, files, and the optional icon.
8. Calculate every payload's exact byte count and lowercase SHA-256 checksum.
9. Declare every remaining concrete environment reference in external_references.
10. Validate manifest.json against the bundle schema and the embedded document schemas.
11. Create the ZIP with manifest.json at its root, no directory-marker entries, and no undeclared files.
12. Import the bundle into a test folder and review all mappings before running the job.

The import process malware-scans the ZIP and every declared payload. A structurally valid bundle can still be rejected when any entry fails scanning.