# Routing Templates

**Audience:** ERP users who are familiar with Action Target's system but are new to PlanetTogether.
**Scope:** Phase 1 — router-to-template linking and template generation.
**Related stories:** US-014 (Routing Maintenance Tools), US-015 (Router Template Generation).

---

## 1. What Is a Template?

PlanetTogether schedules jobs by matching job operations to eligible resources. To do that efficiently, PT uses **templates** — pre-built representations of how a part is manufactured — that it holds in memory and applies each time a new job for that part arrives.

In Action Target's integration, a template is derived directly from an ERP **router**. The router already defines the sequence of operations, setup and run times, and the materials consumed at each step. Template generation reads that router and produces a standardized PT job structure from it — without touching native work order tables.

**Key things to understand:**

- Every part that will be scheduled in PT needs a template based on its current router.
- A template is tied to one specific router revision. When a router is superseded by a new revision, that new revision needs its own template.
- Generating a template is **safe to repeat** — re-running it refreshes the PT data from the current router state without creating duplicates.
- Templates do not affect live work orders. They are scheduling reference structures used by PT, not production documents.

---

## 2. Routers and the Concept of "Current"

An ERP **router** defines the manufacturing process for a part: the sequence of operations, the time each step takes, and the materials consumed. Routers are version-controlled — when a process changes, a new router revision is published for that part.

At any point in time, exactly one router revision is **current** for each part. A router is current when today's date falls within its effective date range (`Effective From` through `Effective To`). Older revisions are archived but remain visible in the system.

**Why this matters for templates:**

- Only a current router can have a template generated from it. The system blocks generation on archived routers.
- When a router is superseded by a new revision, the old template is not automatically updated. The new revision must be selected in the Templates screen and a new template generated from it.
- Future automation of this step is planned but not in scope for Phase 1.

---

## 3. What Gets Generated

When you generate a template from a router, the system produces a complete PT job structure covering:

| Generated object | What it represents |
|---|---|
| **Template Job** | The top-level PT job anchor for this router/part. |
| **Manufacturing Order** | One synthetic MO for the template — no sub-assembly expansion. |
| **Operations** | One PT operation per router BOM operation, in sequence order. |
| **Resource Requirements** | The machine, pool, and labor slots each operation needs (from Resource Management capability mappings). |
| **Resource Capabilities** | The specific capabilities required at each resource slot. |
| **Activities** | One internal activity per operation, used by PT for scheduling granularity. |
| **Materials** | Material consumption rows derived from the router's BOM. |
| **Products** | Output items for each operation, including phantom WIP items between steps. |
| **Operation Attributes** | Attribute/code pairs assigned to each operation, used by the PT Optimizer to group or sequence compatible operations (e.g., same burn material class or paint color). |
| **Path / Path Nodes** | The linear operation sequence that PT follows when scheduling. |

> **Resource requirement rows are only generated for operations that have active capability mappings in Resource Management.** An operation with no capability mapping will still appear in the template (with its activity, time, and BOM rows), but PT will not be able to assign a resource to it until a mapping is configured.

> **Operation attribute rows are only generated for operations that have active attribute links configured on the router.** Operations without attribute links will not have attribute rows — PT will not use them for grouping or sequencing until links are added and the template is regenerated.

---

## 4. The ERP Data Model

All template data lives in the `aps` schema alongside job and resource data, using `source_type = 'TEMPLATE'` to distinguish template rows from live work order rows.

### The Router Link

| Table | What it holds |
|---|---|
| `aps.template_router_link` | The anchor record tying one router revision to its generated template. Holds the canonical `link_id` that drives all generated IDs. |

The `link_id` is the key that all generated IDs are built from:

| Generated ID | Pattern | Example |
|---|---|---|
| Template Job ID | `template-{link_id}` | `template-42` |
| Template MO ID | `template-{link_id}-mo` | `template-42-mo` |
| Template Operation ID | `template-{link_id}-op-{bom_op_id}` | `template-42-op-68664` |

### Template Source Tables

Template rows share the same source tables as live job data — they are distinguished by `source_type = 'TEMPLATE'`:

| Table | Template content |
|---|---|
| `aps.job_source` | One template job per router link. |
| `aps.manufacturing_order_source` | One template MO per router link. |
| `aps.job_operation_source` | One row per BOM operation. |
| `aps.job_resource_source` | Resource requirement slots (machine, pool, labor). |
| `aps.job_resource_capability_source` | Capability requirements per resource slot. |
| `aps.job_activity_source` | One activity per operation. |
| `aps.job_material_source` | Material consumption rows. |
| `aps.job_product_source` | Output items, including phantom WIP. |
| `aps.job_path_source` | The single default path for the template MO. |
| `aps.job_path_node_source` | Predecessor/successor pairs defining operation sequence. |
| `aps.job_operation_attribute_source` | Attribute/code pairs per operation, generated from active attribute links on the router. |

---

## 5. Using the Templates Screen

The **Templates** tab is located inside the **Product Information** app. It is the central place to view router status, generate templates, and inspect what was generated.

Access to generate templates requires the **Manufacturing Engineering**, **Product Data Manager**, or **IT Admin** role.

---

### Main Toolbar

Three buttons appear at the top of the screen:

| Button | Behavior |
|---|---|
| **Generate Template** | Generates or regenerates the APS template for the selected router. Disabled unless exactly one **current** router is selected. Prompts for confirmation before running. |
| **Router Details** | Opens the Router Details panel for the selected router. Shows the operation list plus any blocking errors or warnings, without committing any data. |
| **Show / Hide Template Details** | Expands or collapses the Template Details panel below the Routers grid (see Section 5.4). |

---

### Routers Grid

This grid lists all routers and their current template status.

**Columns displayed by default:** Router Name, Part, Rev, Description, Effective From, Effective To, Current, Template Status, Template Job ID, Last Generated.

**Row colors:**

| Color | Meaning |
|---|---|
| Yellow | Router is not current (archived). Template generation is blocked. |
| Red | Router is current but has **no template** — it has never been generated. |
| No color | Router is current and has a generated template. |

**Routers grid toolbar:**

| Button | Behavior |
|---|---|
| **Show / Hide Archived** | Toggles visibility of non-current (archived) routers. Defaults to hidden — only current routers are shown on load. |
| **Show Only Unmapped / Show All** | Filters to routers with no template at all (`Template Status = none`). Use this to find gaps before a PT go-live. |

**Template Status values:**

| Status | Meaning |
|---|---|
| `none` | No template has ever been generated for this router. |
| `generated` | A template exists and was generated from this router. Check **Last Generated** to see when. |

---

### Router Details Panel

Clicking **Router Details** opens a modal for the selected router without modifying any data. It shows:

- **Blocking Errors** (red) — Problems that will prevent generation from succeeding. Fix these before attempting to generate. The most common is that the router is not current.
- **Warnings** (yellow) — Non-blocking issues that generation will proceed despite. The most common is that one or more operations have no active capability mapping in Resource Management, meaning those operations will not receive resource requirement rows.
- **Router Operations table** — Lists every BOM operation in sequence with setup and run times, its generated Template Operation ID (if a template already exists), and two readiness flags:
  - **Resource Mapped** — Whether an active capability mapping exists for this operation in Resource Management. Operations without a mapping will not have resource slots generated.
  - **Attribute Mapped** — Whether the operation has at least one active attribute link configured in the Routers tab. Operations without attribute links will not have attribute rows generated and will not be used by the PT Optimizer for grouping or sequencing.

> Use the Router Details panel to check readiness before generating, especially for routers whose operations have recently changed or whose capability mappings are new.

---

### Generation Result Panel

After clicking **Generate Template** and confirming, a result panel appears showing:

| Field | What it means |
|---|---|
| **Template Job ID** | The PT job ID that was created or reused for this template. |
| **Template MO ID** | The PT manufacturing order ID for this template. |
| **Created** | Number of new rows inserted across all template tables. |
| **Updated** | Number of existing rows refreshed. |
| **Skipped** | Rows that were already up to date and required no change. |
| **Errors** | Count of rows that failed. Any errors trigger a rollback — nothing is partially committed. |
| **Warnings** | Non-blocking notices, such as operations skipped due to missing capability mappings. |

A green success banner also appears at the top of the screen summarizing the result. The Routers grid refreshes automatically after generation to reflect the updated **Last Generated** date and **Template Status**.

---

### Template Details Panel

Clicking **Show Template Details** expands a set of read-only inspection tables below the Routers grid. These tables show the raw APS source rows that were generated for a template — useful for verifying what PT will receive.

Selecting a router row (when the panel is visible) automatically loads that router's template data across all tables:

- Template Job, Manufacturing Order, Operations, Paths, Path Nodes
- Activities, Resources, Resource Capabilities
- Materials, Products, Operation Attributes

A **Load All Templates** button on the Template Job table loads every template job in the system for comparison.

> This panel is primarily a diagnostic tool for verifying generation output and troubleshooting scheduling issues. Normal template maintenance does not require using it.

---

## 6. When to Generate or Regenerate

| Situation | Action |
|---|---|
| A new current router has no template (red row). | Select it and click **Generate Template**. |
| A router revision was superseded by a new revision. | Select the new current router row and generate. The old revision's template remains but will no longer be used for new jobs. |
| Capability mappings were added or changed for an operation. | Regenerate the template for any affected router so the new resource requirement rows are picked up. |
| Generation produced warnings about unmapped operations. | Configure the missing capability mappings in Resource Management, then regenerate. |
| Attribute links were added or changed for an operation. | Regenerate the template for any affected router so the updated attribute rows are picked up by PT. |
| Generation produced warnings about operations with no attribute mapping. | Add attribute links for those operations in the Routers tab, then regenerate. |
| Troubleshooting a scheduling issue in PT for a specific part. | Use **Router Details** to check readiness flags, then use **Show Template Details** to inspect the generated rows. |

---

## 7. Phase 1 Scope: What's Used and What's Not

| Feature | Phase 1 Status | Notes |
|---|---|---|
| Template generation from current routers | ✅ Used | One template per current router. Non-current routers are blocked. |
| Resource requirement generation | ✅ Used | Driven by capability mappings in Resource Management. Operations without mappings are skipped. |
| Material and product generation | ✅ Used | Derived from the router's BOM. Phantom WIP items are generated automatically. |
| Path and path node generation | ✅ Used | Single linear path per template MO. |
| Operation attribute generation | ✅ Used | Generated from active attribute links on the router's BOM operations. Operations without attribute links produce no attribute rows and will not be used by the PT Optimizer for grouping or sequencing. |
| Sub-assembly MO expansion | ❌ Not used | One MO per template; no recursive sub-assembly expansion. |
| Automatic regeneration on router publish | ❌ Not used | Manual regeneration only in Phase 1. Automation is a future enhancement. |
| Template deletion / deactivation | ❌ Not used | Old templates from archived routers are not automatically retired. |