DevOps Beginner

AutoSys Job Types — CMD, BOX, and File Watcher Explained

📅 March 19, 2026 ⏱ 3 min read 🎯 Beginner

Where developers are forged. · Structured learning · Free forever.

📍 Part of: AutoSys → Topic 7 of 30

AutoSys has three job types: CMD (command), BOX (container), and File Watcher.

🧑‍💻 Beginner-friendly — no prior DevOps experience needed

In this tutorial, you'll learn

AutoSys has three job types: CMD (command), BOX (container), and File Watcher.

AutoSys has three native job types: CMD (runs a command), BOX (container that controls child jobs), and FW File Watcher (watches for file arrival)
BOX jobs don't execute commands — they group jobs together and their status reflects the aggregate outcome of all inner jobs
Child jobs are linked to a BOX with the box_name attribute; without it they run independently

thecodeforge.io

Three AutoSys Job Types

Jil Job Types Cmd Box Filewatcher

✦ Plain-English analogy ✦ Real code with output ✦ Interview questions

⚡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.

🚨 START HERE

Quick Debug Commands for Job Types

Run these commands to quickly diagnose job type problems.

🟡

Job stuck in ACTIVATED/STARTING

Immediate ActionCheck if the machine is reachable and agent is running.

Commands

ping <machine>

autorep -q <job> -w | grep -i status

Fix NowIf machine is unreachable, use sendevent -E FORCE_STARTJOB on another machine or fix agent.

🟡

File Watcher not detecting file

Immediate ActionVerify file exists and has correct size.

Commands

ls -la /path/to/file

autorep -q watch_job -w | grep watch_file

Fix NowAdjust min_file_size to a value the file actually exceeds, or fix wildcard pattern.

🟡

Box job bypasses children

Immediate ActionCheck which jobs are inside the box.

Commands

autorep -q <box_name> -w

autorep -q <box_name> -w 2>&1 | grep -i "job_name"

Fix NowIf no children listed, add box_name to each child job JIL and re-insert.

🟡

CMD job shows SUCCESS but no output file

Immediate ActionCheck if the script actually ran and wrote output.

Commands

cat <std_out_file>

cat <std_err_file>

Fix NowAdd explicit exit codes in your script and verify file paths. Set alarm_if_fail: 1 to get notified.

Production Incident

The Box That Never Started: Nested Hierarchy Mistake

A parent BOX job went to SUCCESS immediately even though its child tasks hadn't run. The entire batch pipeline completed in 2 seconds.

SymptomParent BOX job shows SUCCESS status, but file exports and reports are missing. Logs show nothing ran inside the box.

AssumptionEngineer assumed that putting jobs inside a box automatically runs them in sequence.

Root causeThe 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.

FixAdded 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 Guide

Symptom to action guide for CMD, BOX, and File Watcher failures

CMD job shows FAILURE but script ran successfully→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.

BOX job stuck in RUNNING state for hours→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.

File Watcher job never triggers even though file exists→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.

Child CMD jobs inside a box don't start→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.

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.

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.jil · BASH

1234567891011121314151617181920212223

/* ── 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.jil · BASH

1234567891011121314151617181920212223242526272829303132

/* ── 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.jil · BASH

12345678910111213141516171819202122

/* ── 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.

Mental Model

Job Type Decision Flow

Think of your workflow as a pipeline: inputs, processing, outputs.

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.

🗂 Job Type Comparison

Quick reference for choosing the right job type

Job Type	JIL code	Does it execute a command?	Best used for
CMD	CMD or c	Yes — runs the command attribute	Shell scripts, programs, database calls
BOX	BOX or b	No — container only	Grouping related jobs, controlling batch flow timing
File Watcher	FW or f	No — watches for file	Event-driven triggers based on file arrival

🎯 Key Takeaways

AutoSys has three native job types: CMD (runs a command), BOX (container that controls child jobs), and FW File Watcher (watches for file arrival)
BOX jobs don't execute commands — they group jobs together and their status reflects the aggregate outcome of all inner jobs
Child jobs are linked to a BOX with the box_name attribute; without it they run independently
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
Always set alarm_if_fail on jobs that have external dependencies — silent failures are the worst
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

✕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 Questions on This Topic

QWhat are the three job types in AutoSys?JuniorReveal
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.
QWhat is a BOX job in AutoSys and what does it do?JuniorReveal
A BOX job is a container job. It doesn't execute any command. It groups other jobs (CMD, FW, or nested BOX jobs) and controls their scheduling. The BOX enters RUNNING when its start conditions are met. It reaches SUCCESS only when all child jobs succeed. It fails if any child fails.
QWhat is a File Watcher job and when would you use one?Mid-levelReveal
A File Watcher job watches for a file on a specified machine. When the file appears and reaches the minimum size, the job succeeds. Use it when downstream processing depends on an external file arriving — for example, waiting for a feed from a third-party system. It avoids fixed schedules.
QIf a BOX job is in RUNNING state but inner CMD jobs aren't starting, what would you check?SeniorReveal
First, verify that the child CMD jobs have the box_name attribute set to the correct BOX. Use autorep -q <box_name> -w to list all jobs inside the box. If they are missing, they won't run under the box. Next, check if the child jobs have their own start conditions or date_conditions that aren't met. Also check if the child jobs are in ACTIVATED state but waiting for a machine or queue.
QWhat attribute links a CMD job to its parent BOX job?JuniorReveal
The box_name attribute. You set it in the child job's JIL definition to the name of the parent BOX job.
QCan you put a File Watcher job inside a BOX job? What's a real use case?SeniorReveal
Yes. A real use case: you have a nightly batch process that should only start when a file arrives. You put a File Watcher inside a BOX, along with CMD jobs that process the file. The BOX starts (e.g., at 20:00), the FW watches for the file, and when it succeeds, the CMD jobs inside the box run. The box ensures that all processing completes before the batch session ends.

Frequently Asked Questions

What are the three types of jobs in AutoSys?

The three job types are: CMD (command job — executes a command or script), BOX (container job — groups other jobs and controls their scheduling), and FW (File Watcher — watches for a file to appear and triggers dependent jobs when it does).

Does a BOX job need a machine attribute?

No. BOX jobs don't execute any command, so they don't need a machine. Only CMD and File Watcher jobs need a machine specified.

What happens to inner jobs if a BOX job fails?

If a BOX job fails (because one of its inner jobs failed), the remaining inner jobs that haven't started yet will not start. The box stays in FAILURE state. You need to fix the underlying issue and then restart or force-start the box.

How does a File Watcher job know the file has finished being written?

The min_file_size attribute is your safeguard. The File Watcher won't declare SUCCESS until the file is at least the specified size in bytes. Set this to larger than an empty or incomplete file would be to avoid premature triggering.

Can a BOX job contain other BOX jobs?

Yes. You can nest boxes inside boxes to create hierarchical batch workflows. The outer box controls the overall schedule, inner boxes group related jobs, and CMD jobs do the actual work. This nesting can go multiple levels deep.

How do I make a File Watcher job trigger multiple times per day?

By default, a FW job succeeds once and stays in SUCCESS. To trigger multiple times, you need date_conditions and a run_window. When the run window ends, the job resets to INACTIVE. Next day, if the run window is open, it starts watching again. For multiple triggers within a single day, you need a different approach — e.g., separate FW jobs for each expected file.

🔥

Naren Founder & Author

Developer and founder of TheCodeForge. I built this site because I was tired of tutorials that explain what to type without explaining why it works. Every article here is written to make concepts actually click.

About Naren Get in touch

Forged with 🔥 at TheCodeForge.io — Where Developers Are Forged