Box Jobs and Nested Boxes in AutoSys — Complete Guide
- BOX jobs are containers — they don't execute commands, they control when child jobs can start
- A box enters SUCCESS only when ALL inner jobs have succeeded; it enters FAILURE if any inner job fails
- You can nest boxes inside boxes to build hierarchical batch workflows
BOX jobs are central to well-organised AutoSys environments. Without boxes, you'd have hundreds of independent jobs with no logical grouping, no shared scheduling, and no way to see the end-to-end status of a business process at a glance. With boxes, you can group related jobs, control their collective schedule, and see in seconds whether your end-of-day run succeeded.
How BOX jobs control child job execution
The box controls three things for its child jobs: 1. When they can start: Child jobs can only start when the box is in RUNNING state 2. The execution environment: All child jobs inherit the box's scheduling context 3. Collective status: The box reports SUCCESS only when ALL child jobs succeed
A child job's own conditions (start_times, conditions) still apply within the box. If Job B has condition: success(Job A), it still waits for Job A even though the box is running.
/* Box starts at 10 PM on weeknights */ insert_job: eod_box job_type: BOX date_conditions: 1 days_of_week: mon-fri start_times: "22:00" alarm_if_fail: 1 /* Job A: starts as soon as box is RUNNING */ insert_job: job_a job_type: CMD box_name: eod_box command: /scripts/step_a.sh machine: server01 owner: batch /* Job B: waits for Job A, but still inside the box */ insert_job: job_b job_type: CMD box_name: eod_box command: /scripts/step_b.sh machine: server01 owner: batch condition: success(job_a)
22:00 — job_a: STARTING (no condition — starts immediately)
22:12 — job_a: SUCCESS
22:12 — job_b: STARTING (condition met)
22:28 — job_b: SUCCESS
22:28 — eod_box: SUCCESS */
Nested boxes — boxes inside boxes
You can place a BOX job inside another BOX job. This creates a hierarchy that lets you organise complex batch flows into logical sub-processes.
In a nested setup, the parent box must be RUNNING before the child box can start. The child box must be RUNNING before its own child jobs can start. The parent box succeeds only when ALL child boxes (and their contents) have succeeded.
/* Parent box — the overall EOD run */ insert_job: master_eod_box job_type: BOX date_conditions: 1 days_of_week: mon-fri start_times: "21:00" /* Child box 1 — ETL processing */ insert_job: etl_box job_type: BOX box_name: master_eod_box /* inside master box */ /* Child box 2 — reporting (runs after ETL) */ insert_job: reporting_box job_type: BOX box_name: master_eod_box condition: success(etl_box) /* waits for ETL box to complete */ /* Jobs inside etl_box */ insert_job: etl_extract job_type: CMD box_name: etl_box command: /scripts/extract.sh machine: etl01 owner: batch
Debugging: box is running but inner jobs aren't starting
This is one of the most common issues you'll encounter. The box is in RUNNING state, but the jobs inside it stay INACTIVE or never start.
Most common causes: 1. The child job's own starting conditions aren't met (check condition attribute) 2. The child job has date_conditions: 1 with a start_times set — it's waiting for that specific time even though the box is running 3. The child job is ON_HOLD or ON_ICE 4. The child job's machine is offline (PEND_MACH) 5. The box_name attribute on the child job has a typo
# Check status of box and all inner jobs autorep -J eod_box -s # Check a specific inner job's attributes autorep -J job_b -d # Check if an inner job is on hold or on ice autostatus -J job_b # Check if the machine for an inner job is active autorep -M server01
job_a SU 0
job_b OH <- ON_HOLD — that's why it won't start!
job_c IN <- INACTIVE — waiting
| BOX job state | What it means | Can inner jobs run? |
|---|---|---|
| RUNNING | Box is active, conditions met | Yes — if their own conditions are met |
| SUCCESS | All inner jobs succeeded | No — box has completed |
| FAILURE | At least one inner job failed | No — remaining jobs don't start |
| INACTIVE | Box hasn't been triggered yet | No |
| ON_HOLD | Box manually held | No — box won't start |
| ON_ICE | Box suspended | No — box won't start |
🎯 Key Takeaways
- BOX jobs are containers — they don't execute commands, they control when child jobs can start
- A box enters SUCCESS only when ALL inner jobs have succeeded; it enters FAILURE if any inner job fails
- You can nest boxes inside boxes to build hierarchical batch workflows
- Child jobs inside a box should generally not have their own start_times — let the box control timing
⚠ Common Mistakes to Avoid
- ✕Setting date_conditions: 1 and start_times on a child job inside a box — the job will wait until that specific time even if the box is already running; usually child jobs inside boxes should not have their own start_times
- ✕Putting a machine attribute on a BOX job — it's ignored but signals a misunderstanding of how BOX jobs work
- ✕Not setting a condition on the second-to-last job in a chain, causing jobs to run in parallel unexpectedly
- ✕Confusing box state with child job state — a box in RUNNING doesn't mean all children are running; they follow their own conditions
Interview Questions on This Topic
- QWhat is a BOX job in AutoSys and what does it do?
- QWhen is a BOX job in SUCCESS state?
- QIf a BOX job is RUNNING but its child jobs aren't starting, what would you check?
- QWhat is a Super Box in AutoSys?
- QCan a BOX job contain another BOX job?
Frequently Asked Questions
What is a BOX job in AutoSys?
A BOX job is a container for other jobs. It doesn't execute any command itself — it groups jobs together and controls when they can run. Child jobs inside a box can only start when the box is in RUNNING state.
When does a BOX job move to SUCCESS?
A BOX job moves to SUCCESS only when ALL of its inner jobs have completed successfully. If any inner job fails, the box moves to FAILURE and remaining un-started inner jobs will not run.
My BOX job is RUNNING but inner jobs aren't starting — why?
Common causes: the inner job has date_conditions: 1 and is waiting for a specific start_times; the inner job has a condition that isn't met yet; the inner job is ON_HOLD or ON_ICE; the inner job's machine is offline; or the box_name attribute has a typo.
What is a Super Box in AutoSys?
Super Box is informal terminology for the highest-level BOX job that contains all other boxes and jobs for a given batch workflow. It provides a single point of control and visibility for the entire process.
Should child jobs inside a box have their own start_times?
Generally no. When a job is inside a box, the box controls the overall timing. Setting start_times on a child job means it will wait until that specific time even if the box is already running, which often causes confusion. Child jobs inside boxes typically rely on conditions (success of previous jobs) rather than clock times.
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.