Senior 8 min · March 19, 2026
JIL Job Types: CMD, BOX and File Watcher

AutoSys Job Types — Missing box_name Creates Empty BOX

Parent BOX job succeeds but nothing runs? The missing box_name attribute causes silent failure.

N
Naren Founder & Principal Engineer

20+ years shipping production infrastructure and CI/CD at scale. Everything here is grounded in real deployments.

Follow
✓ Production
production tested
May 23, 2026
last updated
1,554
articles · all by Naren
 ● Production Incident 🔎 Debug Guide ⚙ Triage Commands
⚡Quick Answer
  • CMD jobs execute commands or scripts on a target machine. Exit code 0 = success.
  • BOX jobs are containers that control when child jobs run. They don't execute anything.
  • File Watcher jobs watch for file arrival and trigger dependent jobs.
  • Performance: File Watcher polls every 30-60 seconds — set watch_interval to balance latency vs load.
  • Production insight: Box jobs fail if any child fails — know the ripple effect before building deep hierarchies.
  • Biggest mistake: Using depends_on without a healthcheck in Docker, but here it's forgetting box_name on child CMD jobs.
✦ Definition~90s read
What is JIL Job Types?

AutoSys job types define the behavior and execution model of each workload unit in the CA Workload Automation AE (AutoSys) ecosystem. The three primary types — CMD, BOX, and File Watcher — serve fundamentally different purposes. CMD jobs execute a command or script on a remote agent; BOX jobs are logical containers that group other jobs (CMD, BOX, or File Watcher) to manage dependencies, scheduling, and parallel execution; File Watcher jobs trigger downstream work when a file appears, changes, or reaches a certain age on a monitored host.

★
Think of job types like different types of workers.

Understanding these distinctions is critical because misusing a job type — like defining a BOX without a box_name attribute — silently creates an empty container that never runs its children, a common pitfall that wastes hours of debugging.

In practice, CMD jobs are your workhorses for running shell scripts, executables, or SQL queries. BOX jobs are the orchestration layer: they define start conditions (time, calendar, dependencies) and then all jobs inside inherit those conditions unless overridden.

File Watcher jobs bridge the gap between external events and AutoSys scheduling, polling a file system path at a configurable interval. Each type has strict JIL syntax rules — for example, a BOX job requires box_name to nest jobs, and omitting it produces a valid but inert BOX that never triggers its children.

This is not a syntax error; AutoSys accepts the JIL silently, making it a logic bug that only surfaces during execution.

Choosing the right type depends on your trigger mechanism. Use CMD for time-based or dependency-driven execution. Use BOX when you need to group jobs with shared conditions or run them in a specific order. Use File Watcher when an external process (like an ETL landing or file transfer) must complete before AutoSys proceeds.

Avoid using BOX as a simple wrapper for a single CMD — that adds unnecessary overhead. Also note that File Watcher jobs are polling-based, not event-driven, so they introduce latency equal to the polling interval. For real-time file triggers, consider alternative tools like inotify or a message queue integration.

The gotcha with missing box_name is a classic example of how AutoSys’s lenient JIL parser can hide logical errors — always validate your job definitions with autorep -J <jobname> -q to confirm the box membership is correctly wired.

Plain-English First

Think of job types like different types of workers. CMD jobs are the workers who actually do the task. BOX jobs are the supervisor who groups workers together and controls their schedule. File Watcher jobs are the security guard who watches the door and calls the team the moment a specific file (package) arrives.

Every job in AutoSys has a job_type attribute that determines its fundamental behaviour. There are only three native job types, and understanding what each one does — and more importantly when to use each — is essential for building effective AutoSys workflows.

In practice, most AutoSys environments are built from a combination of all three types working together: BOX jobs contain CMD jobs, and File Watcher jobs trigger other jobs when files arrive.

How AutoSys JIL Defines a BOX Without a box_name

In AutoSys, a BOX is a container job type that groups other jobs (commands, file watchers, other boxes) for scheduling and dependency management. The JIL (Job Information Language) definition for a box_type job requires a box_name attribute to identify the container. When box_name is omitted, AutoSys creates an empty BOX — a valid job object with no child jobs, no start conditions, and no runtime behavior. This is not an error; the system accepts the definition silently, but the resulting job does nothing.

A box_type job without box_name has no parent-child relationships. It exists in the database with status INACTIVE, never transitions to RUNNING, and cannot trigger downstream jobs. The job definition still consumes a slot in the job stream, but it contributes zero logic. This is distinct from a command job with a missing command — that fails on execution. A box without box_name succeeds at definition but fails at purpose.

Use this pattern intentionally only when you need a placeholder — a stub that reserves a job name for future expansion. In production, it is almost always a mistake. Teams often discover empty BOXes during incident triage: a job stream appears to hang because a parent BOX is empty, so no child jobs ever start. The fix is to either supply the correct box_name or delete the definition. Always validate JIL with a dry-run or schema check before deployment.

Silent Failure
An empty BOX does not error on definition or sendevent — it just never runs. Your scheduler logs will show no failure, only absence.
Production Insight
A team deployed a new job stream with a box_type job but forgot the box_name attribute. The stream appeared in the scheduler but never triggered any child jobs. The symptom was a stalled pipeline with no error messages — only manual inspection of the job definition revealed the missing box_name. Rule: always run 'autorep -J <jobname>' after definition to verify the box contains expected children.
Key Takeaway
A box_type job without box_name is syntactically valid but semantically dead.
Always validate JIL with autorep or a schema check before deployment.
Empty BOXes cause silent pipeline stalls — the hardest failures to debug.
Three AutoSys Job Types Three AutoSys Job Types. CMD · BOX · File Watcher · Executes a command · Script / program / SQL · exit 0 = SUCCESS · exit non-0 = FAILURE · Most common typeTHECODEFORGE.IOThree AutoSys Job TypesCMD · BOX · File Watcher CMDExecutes a commandScript / program / SQLexit 0 = SUCCESSexit non-0 = FAILUREMost common type BOXContainer for jobsNo command executedControls child scheduleSUCCESS = all children OKNest boxes in boxes FW File WatcherWatches a file pathTriggers on file arrivalmin_file_size guardUse run_windowEvent-driven patternTHECODEFORGE.IO
thecodeforge.io
Three AutoSys Job Types
Jil Job Types Cmd Box Filewatcher

CMD — the command job

CMD (or just 'c' in JIL shorthand) is the most common job type. It executes a command, script, or program on a specified machine.

The job runs as the specified owner user on the machine. Whatever exit code the command returns determines the job status: exit code 0 means SUCCESS, any non-zero exit code means FAILURE.

CMD jobs are used for
  • Shell scripts
  • Python or Perl scripts
  • Java programs invoked from command line
  • Database scripts called via sqlplus, psql, or similar
  • Any executable that can be called from a command line
cmd_job_examples.jilBASH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
/* ── Simple shell script job ── */
insert_job: run_etl_extract
job_type: CMD
command: /opt/scripts/etl/extract_data.sh
machine: etl-server-01
owner: etluser
date_conditions: 1
days_of_week: all
start_times: "23:00"
std_out_file: /logs/autosys/run_etl_extract.out
std_err_file: /logs/autosys/run_etl_extract.err
alarm_if_fail: 1
n_retrys: 1
term_run_time: 120

/* ── Python script job with arguments ── */
insert_job: generate_risk_report
job_type: CMD
command: "/usr/bin/python3 /opt/reports/risk_report.py --date $(date +%Y%m%d)"
machine: report-server-01
owner: reportuser
condition: success(run_etl_extract)
alarm_if_fail: 1
Output
/* CMD job exits 0 → status becomes SUCCESS */
/* CMD job exits non-zero → status becomes FAILURE → alarm fires */
Exit code 0 means success — make sure your scripts honour this
AutoSys determines success or failure purely by exit code. A script that catches an exception and exits 0 will look successful to AutoSys even if it did nothing useful. Always exit with a non-zero code when your script encounters an error it can't recover from.
Production Insight
Shell scripts that catch all errors and exit 0 mask data failures.
Set trap for non-zero exit inside your scripts and propagate the error.
Rule: always end your script with 'exit $?' or equivalent.
Key Takeaway
CMD jobs are your workhorses.
The exit code is the only truth.
Never let your script swallow failures.

BOX — the container job

A BOX job is a container that holds other jobs (including other BOX jobs). The BOX itself doesn't execute any command — it controls when the jobs inside it can start.

Key BOX behaviour to internalise
  • Jobs inside a box will only run if the box is in RUNNING state
  • The box enters RUNNING state when its own start conditions are met
  • The box moves to SUCCESS only when ALL inner jobs have succeeded
  • The box moves to FAILURE if any inner job fails
  • If you put a box inside another box, the parent box must be RUNNING for the inner box to run

BOX jobs are how you group related batch processes together. A typical end-of-day processing flow might have one parent box containing several child boxes, each of which contains the actual CMD jobs.

box_job_example.jilBASH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/* ── Parent BOX: controls when the whole flow runs ── */
insert_job: eod_processing_box
job_type: BOX
date_conditions: 1
days_of_week: mon-fri     /* business days only */
start_times: "22:00"
alarm_if_fail: 1
description: "End-of-day batch processing — runs all ETL and reports"

/* ── CMD jobs INSIDE the box ── */
insert_job: eod_extract
job_type: CMD
box_name: eod_processing_box   /* this links it to the parent box */
command: /opt/scripts/eod_extract.sh
machine: etl-server-01
owner: batchuser

insert_job: eod_transform
job_type: CMD
box_name: eod_processing_box
command: /opt/scripts/eod_transform.sh
machine: etl-server-01
owner: batchuser
condition: success(eod_extract)   /* waits for extract to succeed */

insert_job: eod_load
job_type: CMD
box_name: eod_processing_box
command: /opt/scripts/eod_load.sh
machine: etl-server-01
owner: batchuser
condition: success(eod_transform)
Output
/* Timeline:
22:00 — eod_processing_box starts (RUNNING)
22:00 — eod_extract starts immediately (no condition)
22:08 — eod_extract succeeds → eod_transform starts
22:25 — eod_transform succeeds → eod_load starts
22:40 — eod_load succeeds → box moves to SUCCESS */
Production Insight
Nested boxes can cause cascading failures — one deep child failure kills the entire parent box.
Use separate boxes for independent flows to limit blast radius.
Rule: keep box nesting to 3 levels max in production.
Key Takeaway
BOX jobs group and control child jobs.
They succeed only when all children succeed.
One failure takes down the whole box.

File Watcher — the event-driven trigger

A File Watcher job does exactly what the name says: it watches for a file on a machine. When the file appears (and optionally reaches a minimum size, indicating it's finished being written), the File Watcher job completes with SUCCESS, which then triggers dependent CMD jobs.

File Watcher jobs are essential in integration scenarios where an upstream system drops a file that downstream processing depends on. Instead of scheduling the downstream job at a fixed time and hoping the file is there, you let the File Watcher trigger it the moment the file actually arrives.

Key File Watcher attributes
  • watch_file — the full path and filename to watch for (supports wildcards)
  • watch_interval — how often to check (in seconds, default 60)
  • min_file_size — minimum file size in bytes before declaring success
  • watch_file_min_size — same as above, alternate attribute name
file_watcher_example.jilBASH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/* ── File Watcher: wait for upstream file ── */
insert_job: watch_for_trades_file
job_type: FW                          /* FW = File Watcher */
watch_file: /data/inbound/trades_*.csv
watch_interval: 30                    /* check every 30 seconds */
min_file_size: 1024                   /* must be at least 1 KB */
machine: data-landing-server
owner: batchuser
date_conditions: 1
days_of_week: mon-fri
run_window: "08:00 - 20:00"           /* only watch during business hours */
alarm_if_fail: 1
description: "Watches for daily trades file from upstream system"

/* ── CMD job that runs after file arrives ── */
insert_job: process_trades_file
job_type: CMD
command: /opt/scripts/process_trades.sh
machine: processing-server-01
owner: batchuser
condition: success(watch_for_trades_file)   /* triggers when file found */
alarm_if_fail: 1
Output
/* 09:47:32 — watch_for_trades_file: found /data/inbound/trades_20260319.csv (45302 bytes)
09:47:32 — watch_for_trades_file: SUCCESS
09:47:33 — process_trades_file: starting (condition met) */
File Watcher watches for the file, not the content
A File Watcher job completes as soon as it finds a file matching the pattern AND the file reaches the minimum size. It doesn't validate the file content. If the upstream system writes an empty or partial file before the full transfer completes, min_file_size is your safeguard — set it to something larger than an empty or header-only file.
Production Insight
If the upstream system writes the file slowly, the File Watcher might trigger on a partially written file.
Use min_file_size to ensure the file is complete, but this is inexact.
Rule: for large files, consider having the upstream write a .done marker file and watch for that instead.
Key Takeaway
File Watcher jobs enable event-driven processing.
They succeed when a file matching the pattern exists and is large enough.
Always set a realistic min_file_size to avoid premature triggers.

Choosing the Right Job Type for the Task

While the three job types serve distinct purposes, real workflows blend them. Guidance:

  • Use CMD for any executable work. This is your default job type.
  • Use BOX to group jobs that must complete together before something else runs. A box ensures atomicity of a batch step.
  • Use File Watcher when processing depends on external file arrival. Do not use a fixed schedule if arrival time is unpredictable.
  • Avoid using BOX as a simple scheduler — use date_conditions on individual jobs if you don't need container semantics.
  • Consider FW inside a BOX to start a batch sequence when a file arrives — the FW succeeds, then triggers the downstream CMD inside the same box.
Job Type Decision Flow
  • If the work is a script or program → CMD
  • If you need to control a group of jobs as a unit → BOX
  • If the start signal is an external file → File Watcher
  • If you need all three → nested BOX containing FW and CMD tasks
Production Insight
Common anti-pattern: wrapping every single CMD in its own BOX.
That adds unnecessary complexity and makes debugging harder.
Rule: only use a BOX when you actually need to group two or more jobs together.
Key Takeaway
Match job type to the workflow shape.
CMD for work, BOX for containment, FW for triggers.
Over-engineering job types wastes time and hides problems.

Job Type Limitations and Gotchas

Each job type has constraints that bite in production:

  • CMD jobs cannot be inside a box without box_name attribute. Missing it means the job runs independently.
  • BOX jobs cannot have a machine attribute — they don't execute commands. Adding one is harmless but confusing.
  • File Watcher jobs only watch one directory/pattern at a time. To watch multiple patterns, create multiple FW jobs.
  • File Watcher jobs succeed once. To re-trigger on a new file each day, you need date_conditions and a run_window.
  • BOX jobs with many children can take a long time to report final status because it awaits all children. Use alarms to detect partial failures early.
BOX jobs don't support parallel execution by default
A box runs children based on their individual conditions. If you want parallelism, set conditions to allow multiple children to start simultaneously. The box itself does not enforce any ordering beyond what you define.
Production Insight
A File Watcher job that never triggers can go unnoticed for days if alarm_if_fail is not set.
Add alarm_if_fail: 1 and configure notification rules in AutoSys.
Rule: every job that has external dependencies should alarm on failure.
Key Takeaway
Understand the quirks of each job type.
Missing box_name, wrong machine, unset alarms — these are top production issues.
Keep it simple: use the minimal job type that gets the job done.

How Job Types Behave During Box Abort — What the Docs Won't Tell You

A BOX job aborts. What happens to its children? The answer depends on the job type and the abort strategy you set. CMD jobs inside a box follow the BOX's abort setting — if the BOX aborts, they get killed unless you set 'term_run' to force them to completion. But File Watcher jobs? They ignore the BOX abort entirely. The watcher keeps running until it triggers or you manually kill it. This is a common source of zombie processes in production. The WHY: File Watcher is event-driven, not a task that can be killed mid-execution. The BOX doesn't 'own' it the same way. If you need a File Watcher to stop when its parent box aborts, you have to wrap it in a CMD job that polls the watcher's status or set a MAX_RETRY on the watcher itself. Otherwise, expect orphan triggers.

BoxAbortBehaviour.ymlYAML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// io.thecodeforge — devops tutorial
// Box abort kills CMD children, but not File Watcher

insert_job: PaymentBatch_Box job_type: box
condition: success(PaymentGateway_Check)
term_run: 1

insert_job: ExtractPayments job_type: cmd
command: /app/scripts/extract_payments.sh
box_name: PaymentBatch_Box
term_run: 0  # inherits box term_run=1

insert_job: WatchIncomingPayment job_type: fw
watch_file: /incoming/payments/
file_pattern: "*.csv"
box_name: PaymentBatch_Box
# No 'term_run' — watcher ignores box abort
Output
When PaymentBatch_Box aborts:
- ExtractPayments: killed immediately (inherits box's term_run)
- WatchIncomingPayment: continues watching. Will trigger even if box is dead.
Production Trap:
Don't assume a box abort stops everything. File Watcher jobs are like landmines — they ignore the box's kill signal. Always explicitly set 'max_runs' or a timeout on watchers inside boxes.
Key Takeaway
File Watcher inside a box ignores box abort. Wrap it in a CMD job or set max_runs to prevent orphaning.

Why File Watcher Jobs Fail Silently — and How to Catch Them

File Watcher jobs are notorious for failing without alerting anyone. The root cause: they don't execute a command. They only check for a file condition. If the file never arrives, the watcher stays in RUNNING state forever. No exit code. No error message. You only notice when a downstream job times out. The fix is brutal but necessary: always set a retry limit and a time window. Use 'max_runs' to cap the number of watcher evaluations. Use 'watch_interval' and 'max_wait' to enforce a timeout. Never let a File Watcher run indefinitely. The second trick: use the 'trigger_on_failure' attribute on the file condition itself — not the job. This way, if the file never appears, you can fire a failure job that sends an alert. Without this, your watcher is a silent black hole.

FileWatcherTimeout.ymlYAML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// io.thecodeforge — devops tutorial
// Enforce timeout on file watcher to avoid dead jobs

insert_job: WaitForSalesReport job_type: fw
watch_file: /data/reports/sales/
file_pattern: "daily_sales_*.csv"
watch_interval: 60  # seconds
max_wait: 1800      # 30 minutes max
max_runs: 30        # 30 retries, then abort

// Add failure alert
insert_job: SalesReportMissed job_type: cmd
command: /usr/local/bin/alert_team.sh 'Sales report missing'
condition: failure(WaitForSalesReport)
Output
If file not found within 30 minutes:
- WaitForSalesReport: TERMINATED (status: TERMINATED)
- SalesReportMissed: triggers immediately with exit code 0
- Alert sent to team within 60 seconds
Senior Shortcut:
Set max_runs to the number of watch_interval cycles you're willing to wait. If you expect the file within 10 minutes at 60s intervals, max_runs=10. Anything beyond is dead weight.
Key Takeaway
File Watcher jobs need explicit max_runs and max_wait to avoid silent failures. Always pair them with a failure trigger.

Mixing CMD and BOX Jobs for State Dependencies — the Missing Pattern

You have three independent systems that need data in order. A batch process, a database export, and an FTP push. The naive approach: chain them with conditions in a linear sequence. The problem? If the first job fails, everything downstream waits forever. A better pattern: use a BOX job as a state tracker. Put each job in the box with 'max_run_alarm' and 'term_run' set to 1. This gives you a single point of control. You can abort the entire batch on any failure. But you can also inspect the box's status to determine if the batch is 'running' or 'failed' without checking individual jobs. The real power: use the box's exit code as a global status. When the box finishes, the exit code reflects the worst child status. This lets you trigger a cleanup job outside the box based on the final outcome — not just individual job status.

StateTrackerBox.ymlYAML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// io.thecodeforge — devops tutorial
// Box as state tracker for batch orchestration

insert_job: DataPipelineBox job_type: box
max_run_alarm: 3600
term_run: 1

insert_job: BatchExtract job_type: cmd
command: /app/scripts/batch_extract.sh
box_name: DataPipelineBox

insert_job: DBExport job_type: cmd
command: /app/scripts/db_export.sh
box_name: DataPipelineBox
condition: success(BatchExtract)

insert_job: FTPPush job_type: cmd
command: /app/scripts/ftp_push.sh
box_name: DataPipelineBox
condition: success(DBExport)

// Conditional cleanup (outside the box)
insert_job: CleanupOnFailure job_type: cmd
command: /app/scripts/cleanup.sh
condition: failure(DataPipelineBox)
Output
If BatchExtract fails:
- DataPipelineBox: status FAILED
- DBExport and FTPPush: not started (condition not met)
- CleanupOnFailure: triggers (box exit code reflects failure)
Senior Shortcut:
Use the box's exit code as a single source of truth for downstream dependencies. No need to check individual job statuses — the box aggregates them.
Key Takeaway
A BOX job is not just a container. It's a state aggregator. Use its exit code to trigger cleanup or rollback jobs after batch completion.

Press Win + R: The Unsung DevOps Shortcut for JIL Job Management

Before you open a terminal or SSH into a remote box, press Win + R. This Windows Run dialog is your fastest path to launching AutoSys tools without navigating menus. Why does this matter? Because DevOps velocity depends on reducing friction. Instead of hunting for the AutoSys client shortcut or typing full paths, Win + R lets you run autorep, jil, or sendevent directly if your environment variables are set. For JIL job types like CMD, BOX, or File Watcher, you can quickly verify job definitions or trigger manual events from your workstation. The Run dialog also supports UNC paths and command-line arguments, so you can paste a full AutoSys command like autorep -j MY_BOX -q to inspect a box definition. This habit cuts seconds per operation — and over a day, that adds up to real productivity gains. Set your PATH to include the AutoSys bin directory, and Win + R becomes your silent partner in debugging job types without ceremony.

win_r_autosys_shortcuts.ymlYAML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// io.thecodeforge — devops tutorial
// 25 lines max
name: AutoSys Win+R shortcuts
variables:
  autosys_bin: C:\Program Files\CA\AutoSys\bin
setup:
  - task: Add autosys_bin to system PATH
    command: setx PATH "%PATH%;{{ autosys_bin }}" /M
  - task: Verify autorep accessible via Win+R
    command: autorep -V
    expected_output: "AutoSys Version 11.3"
routines:
  - description: Inspect JIL job types quickly
    win_r_input: autorep -j MY_FILE_WATCHER -q
    why: Validate File Watcher definition without opening GUI
  - description: Edit JIL job on the fly
    win_r_input: notepad C:\jobs\my_cmd_jil.txt
    why: Quick edit of a CMD job's JIL file before update
  - description: Trigger event for box abort test
    win_r_input: sendevent -E FORCE_STARTJOB -J MY_BOX
    why: Simulate box abort scenario for testing state dependencies
Output
AutoSys Version 11.3
Production Trap:
If your AutoSys environment variables are not global (e.g., set per-user only), Win + R may fail silently. Test with autorep -V immediately after setup to avoid wasted time during incident response.
Key Takeaway
Win + R bypasses menu navigation, giving you instant access to AutoSys commands — accelerate JIL debugging by setting your PATH once.

Change the Color: Visual Distinction for Job Types in AutoSys GUI

AutoSys allows job color customization in the Console or Application Browser, but most teams overlook this simple tactic. Why change colors? When you have a box containing dozens of CMD jobs, File Watcher triggers, and nested boxes, visual cues prevent misreads during a box abort. Assign distinct colors per job type — for example, blue for CMD, green for BOX, orange for File Watcher. This turns a monochrome job list into an instant status map. To change the color, open the job definition in AutoSys Console, navigate to the Display tab (or equivalent in your version), and set the 'Job Color' property. In JIL, add color: lightblue to your job definition. For File Watcher jobs, use color: orange to highlight event-driven triggers that may fail silently. When monitoring a box abort, a red (failed) box with orange File Watchers inside immediately signals that the trigger never fired. Color is not cosmetic — it's a diagnostic shorthand that reduces cognitive load during firefights. Standardize this across your team to turn job lists into visual dashboards.

jil_color_coding_job_types.ymlYAML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// io.thecodeforge — devops tutorial
// 25 lines max
name: JIL color coding for job types
spec:
  job_types:
    - type: CMD
      jil_color: lightblue
      why: High-frequency execution jobs need fast scan
    - type: BOX
      jil_color: green
      why: Containers visually group dependencies
    - type: File Watcher
      jil_color: orange
      why: Event-driven triggers prone to silent failure
  example_jil:
    - job: MY_FILE_WATCHER
      color: orange
      owner: devops
      status: active
      command: /usr/local/bin/watch_file.sh
    - job: MY_BOX
      color: green
      box_name: PARENT_BOX
    - job: MY_CMD
      color: lightblue
      command: echo 'Running CMD job'
best_practice:
  - Standardize color map in team wiki
  - Use red only for failure states (reserved)
  - Apply color via JIL update: alter_job:color MY_CMD lightblue
Output
assigning color: orange to job MY_FILE_WATCHER
Production Trap:
Color changes are cosmetic — a green box in the GUI may still be failed. Always validate job status via autorep -j after box abort scenarios; color is a visual aid, not a status indicator.
Key Takeaway
Assign distinct colors to CMD, BOX, and File Watcher jobs — visual differentiation speeds up box abort analysis and prevents silent failure oversight.
● Production incidentPOST-MORTEMseverity: high

The Box That Never Started: Nested Hierarchy Mistake

Symptom
Parent BOX job shows SUCCESS status, but file exports and reports are missing. Logs show nothing ran inside the box.
Assumption
Engineer assumed that putting jobs inside a box automatically runs them in sequence.
Root cause
The child CMD jobs were defined without the box_name attribute. They were not linked to the parent BOX. The parent BOX had no children, so it succeeded instantly.
Fix
Added box_name: parent_box_name to each child job's JIL definition. Re-ran the parent box via sendevent -E FORCE_START.
Key lesson
  • Always verify child jobs have the box_name attribute set to the correct parent box.
  • Use autorep -q <box_name> -w to list all jobs inside a box and confirm membership.
  • Never assume that job definitions placed under a box heading in JIL automatically belong to it.
Production debug guideSymptom to action guide for CMD, BOX, and File Watcher failures4 entries
Symptom · 01
CMD job shows FAILURE but script ran successfully
→
Fix
Check the script's exit code. AutoSys treats any non-zero exit as failure. Ensure your script exits 0 on success, or override n_retrys and alarm_if_fail.
Symptom · 02
BOX job stuck in RUNNING state for hours
→
Fix
Check status of all child jobs inside the box using autorep -q <box_name>. Look for a child that is RUNNING, ACTIVATED, or TERMINATED. Use sendevent -E KILLJOB on the stuck child to unblock.
Symptom · 03
File Watcher job never triggers even though file exists
→
Fix
Verify the file path on the machine where the watcher runs. Check watch_interval and min_file_size. Use 'ls -la' to check file size and permissions. Ensure file matches the wildcard pattern. Run autorep -q <job> -w to see current status.
Symptom · 04
Child CMD jobs inside a box don't start
→
Fix
Confirm the parent box is in RUNNING state (not SUCCESS or FAILURE). Check that child jobs have box_name set. Also check if child jobs have their own date_conditions or conditions that prevent them from starting.
★ Quick Debug Commands for Job TypesRun these commands to quickly diagnose job type problems.
Job stuck in ACTIVATED/STARTING−
Immediate action
Check if the machine is reachable and agent is running.
Commands
ping <machine>
autorep -q <job> -w | grep -i status
Fix now
If machine is unreachable, use sendevent -E FORCE_STARTJOB on another machine or fix agent.
File Watcher not detecting file+
Immediate action
Verify file exists and has correct size.
Commands
ls -la /path/to/file
autorep -q watch_job -w | grep watch_file
Fix now
Adjust min_file_size to a value the file actually exceeds, or fix wildcard pattern.
Box job bypasses children+
Immediate action
Check which jobs are inside the box.
Commands
autorep -q <box_name> -w
autorep -q <box_name> -w 2>&1 | grep -i "job_name"
Fix now
If no children listed, add box_name to each child job JIL and re-insert.
CMD job shows SUCCESS but no output file+
Immediate action
Check if the script actually ran and wrote output.
Commands
cat <std_out_file>
cat <std_err_file>
Fix now
Add explicit exit codes in your script and verify file paths. Set alarm_if_fail: 1 to get notified.
Job Type Comparison
Job TypeJIL codeDoes it execute a command?Best used for
CMDCMD or cYes — runs the command attributeShell scripts, programs, database calls
BOXBOX or bNo — container onlyGrouping related jobs, controlling batch flow timing
File WatcherFW or fNo — watches for fileEvent-driven triggers based on file arrival

Key takeaways

1
AutoSys has three native job types
CMD (runs a command), BOX (container that controls child jobs), and FW File Watcher (watches for file arrival)
2
BOX jobs don't execute commands
they group jobs together and their status reflects the aggregate outcome of all inner jobs
3
Child jobs are linked to a BOX with the box_name attribute; without it they run independently
4
File Watcher jobs are the right pattern for event-driven integration scenarios where processing should start when a file arrives, not at a fixed time
5
Always set alarm_if_fail on jobs that have external dependencies
silent failures are the worst
6
Minimal job type usage
only use BOX when you need to group, only use FW when file arrival is the trigger

Common mistakes to avoid

5 patterns
×

Adding a machine attribute to a BOX job

Symptom
No error but configuration is misleading; engineers later expect the BOX to execute something.
Fix
Remove machine from BOX JIL definitions. BOX jobs don't need a machine.
×

Not setting min_file_size on File Watcher jobs

Symptom
File Watcher triggers on an empty or partially-written file, causing downstream CMD jobs to fail.
Fix
Set min_file_size to a value larger than an incomplete file. For example, set to 1024 if minimal valid file is 2 KB.
×

Forgetting to set box_name on child CMD jobs

Symptom
CMD jobs run independently and the BOX completes immediately with no children executed.
Fix
Add box_name: <parent_box_name> to every child job that should be inside the box.
×

Expecting a File Watcher job to re-trigger multiple times in one day

Symptom
File Watcher succeeds once in the morning; a second file dropped in the afternoon does not trigger again.
Fix
Use date_conditions and run_window to allow the FW to reset each day, or use a different design for multiple triggers per day.
×

Using a BOX job to run a single CMD job

Symptom
Unnecessary nesting adds complexity; troubleshooting the BOX hides the actual CMD failure.
Fix
Only use BOX when you need to group two or more child jobs. A single CMD job runs fine on its own.
INTERVIEW PREP · PRACTICE MODE

Interview Questions on This Topic

Q01JUNIOR
What are the three job types in AutoSys?
Q02JUNIOR
What is a BOX job in AutoSys and what does it do?
Q03SENIOR
What is a File Watcher job and when would you use one?
Q04SENIOR
If a BOX job is in RUNNING state but inner CMD jobs aren't starting, wha...
Q05JUNIOR
What attribute links a CMD job to its parent BOX job?
Q06SENIOR
Can you put a File Watcher job inside a BOX job? What's a real use case?
Q01 of 06JUNIOR

What are the three job types in AutoSys?

ANSWER
CMD (command), BOX (container), and File Watcher (FW). CMD executes a script or program. BOX is a container that holds other jobs and controls their execution. File Watcher monitors a file system for file arrival.
FAQ · 6 QUESTIONS

Frequently Asked Questions

01
What are the three types of jobs in AutoSys?
02
Does a BOX job need a machine attribute?
03
What happens to inner jobs if a BOX job fails?
04
How does a File Watcher job know the file has finished being written?
05
Can a BOX job contain other BOX jobs?
06
How do I make a File Watcher job trigger multiple times per day?
📖 What to Read Next
→AutoSys Job Dependencies and ConditionsUnderstand how to chain jobs with conditions like success() and failure(). Build on the job types you learned here.→AutoSys Real-World Patterns and Best PracticesSee how the three job types combine in real enterprise batch workflows.→AutoSys Integration with SAP and OracleRelated: AutoSys Integration with SAP and Oracle on TheCodeForge.→AutoSys date_conditions and run_windowRelated: AutoSys date_conditions and run_window on TheCodeForge.→Git Hooks ExplainedRelated: Git Hooks Explained on TheCodeForge.
N
Naren Founder & Principal Engineer

20+ years shipping production infrastructure and CI/CD at scale. Everything here is grounded in real deployments.

Follow
✓ Verified
production tested
May 23, 2026
last updated
1,554
articles · all by Naren
🔥

That's AutoSys. Mark it forged?

8 min read · try the examples if you haven't

←
Previous
JIL Introduction and Syntax
7 / 30 · AutoSys
Next
JIL Attributes Complete Reference
→