# Resource and Capabilities

**Audience:** ERP users who are familiar with Action Target's system but are new to PlanetTogether.
**Scope:** Phase 1 — resource master data, capabilities, and capability assignments.
**Related stories:** US-003 (Resource Maintenance Matrix), US-004 (Resource, Capability, and Attribute Maintenance Tools).

---

## 1. How PlanetTogether Organizes the Factory

Before you can understand resources and capabilities, it helps to understand how PlanetTogether structures the physical world. PT uses a three-level hierarchy:

```
Plant
 └── Department(s)
      └── Resource(s)
```

### Plant

A **Plant** represents an entire facility or production location — in PlanetTogether terms, a single physical factory. For Action Target's Phase 1 integration, there is exactly **one plant**: Action Target Inc. (mapped from `base.ent.id = 1`).

The Plant is also the scope of a PT optimization run. When PT schedules jobs, it optimizes within the boundaries of a plant.

### Department

A **Department** is PlanetTogether's way of grouping resources that belong together. In most ERP systems, departments map closely to **work centers**. In Action Target's case, the four PT departments correspond to four vendor-organization rows in the ERP:

| PT Department | ERP `vend_org.org_id` | ERP `org_name` |
|---|---:|---|
| Fabrication | 1196 | AcTarg Fabrication |
| Assembly | 1445 | AcTarg Assembly |
| Electronics | 1544 | AcTarg Electronics |
| Wood Shop | 1628 | AcTarg Wood Shop |

> **What departments do in PT scheduling:** Departments have one scheduling effect — each department can have its own *frozen zone* (a window of time near the current clock where PT will not automatically move scheduled work). Otherwise, departments are organizational groupings, not scheduling constraints.

> **Important limitation:** Once a resource is assigned to a department in PT, it cannot be reassigned. Similarly, a department cannot be reassigned to a different plant. If a reassignment is ever needed, the resource or department must be deleted and recreated under the correct parent. Keep this in mind when setting up the initial data.

Department setup and maintenance is managed by IT and is **read-only context** for the Planning Resources tools. You will see departments when setting up resources, but you will not edit them there.

### Resource

A **Resource** is the central scheduling object in PlanetTogether. A resource represents anything on the factory floor that performs work: a machine, a workstation, a labor pool, a tool, or any other entity that jobs must be scheduled on.

**Key things to understand about resources:**

- Every resource belongs to one department (and therefore one plant).
- A resource must have at least one **capability** assigned to it before jobs can be scheduled on it (see Section 2).
- Each resource has a **Capacity Type** that controls how many operations it can run at once:
  - **SingleTasking** — Only one operation at a time. The operation must finish before the next one starts.
  - **MultiTasking** — A finite number of operations can run simultaneously, controlled by the number of people available on each shift interval.
  - **Infinite** — Any number of operations may be scheduled simultaneously with no constraint. Used when a resource type truly has no practical limit (e.g., a holding area).
- Resources can also have **efficiency multipliers** for setup time and cycle time, allowing PT to model resources that run faster or slower than standard time.

**Action Target's Phase 1 resource pattern:**

Resources are created at three granularities:

| Resource type | One record per... | PT Resource Type |
|---|---|---|
| **Machine** | Individual machine on the floor | `Machine` |
| **Work Center** | Work center (grouping of related machines or stations) | `WorkCenter` |
| **Labor pool** | Pool of workers with a shared skill set | `Labor` |

The current list of resources is maintained in `aps.resource_source` and managed through the Planning Resources screen. Do not rely on any static list in this document — the screen is always current.

---

## 2. Capabilities: Matching Resources to Work

### What a Capability Is

A **Capability** defines a *type of work* — a skill or process that a resource is qualified to perform. Think of it as a tag or classification. Examples might be "Welding," "Painting," "Assembly," or "CNC Machining."

Capabilities are the bridge between a job operation and the resources that can perform it. Here's how they connect:

1. A **capability** is created (e.g., "Welding").
2. That capability is **assigned** to one or more resources (e.g., the Weld resource and the PT Weld resource both receive the "Welding" capability).
3. A **job operation** declares that it *requires* the "Welding" capability.
4. PT's scheduler then knows which resources are eligible to schedule that operation on.

> **In ERP terms:** Capabilities typically correspond to work centers in traditional ERP systems. But they are more flexible — a capability can also represent a special material type, a process constraint, or any other qualifying characteristic that limits which resources can do the work.

### Action Target's Phase 1 Capability Structure

Phase 1 uses three distinct capability types, each following a consistent naming convention that signals both intent and scheduling behavior at a glance:

| Type | Naming pattern | What it means | Notes field value |
|---|---|---|---|
| **Labor** | `Labor - [Skill]` | Ties a labor resource to the type of work it performs. One labor capability per skill, assigned to exactly one labor resource. | *(empty)* |
| **Pool** | `Pool - [Process]` | Groups interchangeable resources. Any resource in the pool can satisfy the requirement. | `Jobs can run on any resource in the pool.` |
| **Machine** | `Machine - [Machine Name]` | Pins a requirement to a specific machine (or a very small set of equivalent machines). | `Jobs can only run on specific resources.` |

The **Notes** field on a capability conveys intent to planners and reviewers. Pool capabilities say *"Jobs can run on any resource in the pool,"* and Machine capabilities say *"Jobs can only run on specific resources."* Labor capabilities leave notes empty — the prefix makes the constraint self-evident.

**Why individual machines carry two capability types:**

A machine like the Brake 400T is typically assigned *both* a Pool capability and a Machine-specific capability:

- The **Pool** capability (e.g., `Pool - Bend`) groups it with other interchangeable brakes so that generic bending operations can land on any eligible brake.
- The **Machine** capability (e.g., `Machine - Bend 400T`) allows operations that require *this specific press* — due to tonnage or tooling — to be pinned exclusively to it.

An operation routes to whichever capability matches its requirement: generic work links to the Pool, tonnage-specific work links to the Machine capability.

### Capability Assignments

A **Capability Assignment** is the record that links a specific capability to a specific resource. It requires:

- The capability being assigned
- The resource receiving it
- The plant and department context (derived automatically from the resource)

A resource can have many capabilities. A capability can be assigned to many resources. When a job operation requires *multiple* capabilities, a resource must have **all of the required capabilities** to be eligible — not just one of them.

> **Example:** Suppose an operation requires both "Welding" and "Certified Inspection." Only a resource that has *both* capabilities assigned will be considered eligible to run that operation.

### Capability-Operation Links

The third piece of the capability picture is the **Capability-Operation Link**: a record that declares which capability a given ERP routing operation *requires*.

Think of it this way:

- **Resource-Capability Assignments** say: *"This resource can do this type of work."*
- **Capability-Operation Links** say: *"This operation requires this type of work."*

PT's scheduler matches them: an operation can only land on a resource when the resource has all the capabilities the operation's links require.

Each link also has a **Requirement Sequence** (`Seq`). The sequence number identifies which resource slot a capability requirement belongs to — PT must find a separate, simultaneously available resource to satisfy each distinct sequence number.

The sequence values recorded here are the **authoritative source** for which resource slots an operation uses. When jobs are exported to PT, one resource requirement row is created per distinct seq found in this table for the operation — not a fixed number. An operation that has only Seq 1 and Seq 3 links gets exactly two resource requirements. Among all of an operation's slots, the one with the **lowest seq** is marked as the primary requirement — the anchor slot PT treats as its scheduling driver. Action Target's Phase 1 design uses up to three slots per operation: the specific machine (Seq = 1), the pool the machine belongs to (Seq = 2), and a labor resource (Seq = 3).

### How Capabilities Affect Scheduling

PT will not schedule an operation on a resource unless that resource has all the capabilities the operation's links require. This means:

- Resources with no capabilities assigned cannot be scheduled on any operations.
- Operations with no capability link cannot be scheduled at all.
- Getting both sides right — what resources can do, and what operations require — is a prerequisite before job data can be exported to PT and scheduling can work correctly.

---

## 3. Our ERP Data Model: The `aps.*_source` Tables

All resource and capability data that flows to PlanetTogether is owned and maintained in the `aps` schema of the ERP database. PT is a *consumer* of this data — the ERP is the authoritative source of record.

The data lives in **source tables** (`aps.*_source`). PT-facing **export views** (`aps.*_v`) read from those source tables and present the data in the exact shape PT expects.

### Source Tables

| Table | What it holds | PT object it feeds |
|---|---|---|
| `aps.plant_source` | The single Action Target plant record. | `Plants` |
| `aps.department_source` | The four production departments, linked to `public.vend_org`. | `Departments` |
| `aps.resource_source` | Resource master records; each belongs to a department/plant. Work area resources carry `workcenter` (display name) and `workcenter_id` (the associated `ati_pool` id from `work_order.ati_pools`, stored as varchar; no FK enforced). | `Resources` |
| `aps.capability_source` | Capability definitions (name, description, notes). | `Capabilities` |
| `aps.capability_assignment_source` | Which capabilities are assigned to which resources. | `CapabilityAssignments` |
| `aps.capability_operation_link` | Links ERP routing operations to capabilities, each with a `requirement_seq`. This is the authoritative source for which resource slots an operation requires. Only operations with active rows here will have resource requirements generated on export. | `JobResourceCapabilities` |
| `aps.workcell_department_link` | Legacy lookup: maps workcell names to departments. Used for context; not a PT export. | (Internal reference) |

### Export Views

The export views are the data layer PT reads from. You do not need to interact with them directly, but understanding what they filter is useful:

| View | Filters / shape |
|---|---|
| `aps.plants_v` | Active plants only. Columns: `external_id`, `name`, `description`. |
| `aps.departments_v` | Active departments joined to the active plant. |
| `aps.resources_v` | Active resources only. Includes default `batch_type = 'None'`, `capacity_type`, `resource_type`. Exposes `workcenter` and `workcenter_external_id` (sourced from `workcenter_id` on `aps.resource_source`) for work area resources; null for machines and labor. |
| `aps.capabilities_v` | Active capabilities only. |
| `aps.capability_assignments_v` | Active assignments where both the capability and resource are also active. |

---

## 4. How Data Flows to PlanetTogether

Once your source tables are populated, the data flows to PT through export views:

```
aps.*_source tables  →  aps.*_v export views  →  PlanetTogether import
```

PT reads from the export views — it never reads directly from the source tables. The views:

- Filter out inactive records automatically (`where active = true`).
- Present columns in the exact names and shapes PT expects.
- Join related tables to resolve foreign keys into the values PT needs (e.g., `capability_assignment_source` is joined to both the capability and resource tables so only fully active assignments export).

**The ERP is authoritative.** PT consumes what the ERP sends. For Phase 1, changes made inside PT to resource data are not written back to the ERP source tables.

---

## 5. Using the Planning Resources Screen

The **Planning Resources** tab is located inside the **Product Information** app. It is the central place to maintain all resource and capability data before it is exported to PlanetTogether.

Access to create, edit, and retire records requires the **Manufacturing Engineering**, **Product Data Manager**, or **IT Admin** role. Planning and scheduling leads have view-only access.

The screen contains five data grids. Three of them interact with each other dynamically based on what row you select, which is explained at the end of this section.

---

### Main Toolbar

At the top of the screen, three toggle buttons control which grids are visible:

| Button | What it does |
|---|---|
| **Hide / Show Resources** | Collapses or expands the Resources grid. Hiding the grid also clears any active resource selection, which resets the Resource Capabilities filter back to showing all assignments. |
| **Hide / Show Capabilities** | Collapses or expands the Capabilities grid. Hiding it clears any active capability selection, resetting both the Resource Capabilities filter and the Operation Links filter. |
| **Hide / Show Operation Links** | Collapses or expands the Capability-Operation Links grid. The other grids are unaffected. |

---

### Readiness Issues

This grid runs a live validation check every time you open the screen or save a change. It shows problems that would prevent a successful export to PlanetTogether.

**Columns displayed:**

| Column | What it shows |
|---|---|
| Severity | How serious the issue is (e.g., Error, Warning). |
| Code | A short code identifying the type of issue. |
| Message | A plain-language description of the problem. |
| Resource | The Resource ID involved, if applicable. |
| Capability | The Capability ID involved, if applicable. |

This grid is read-only. You resolve issues by correcting the underlying data in the Resources, Capabilities, Resource Capabilities, or Operation Links grids below, then the Readiness Issues grid will refresh automatically.

---

### Resources Grid

This grid shows all APS resources from `aps.resource_source`. It is the starting point for managing everything the factory floor can do.

**Columns displayed by default:** Resource ID, Resource Name, Plant, Department, Resource Type, Capacity Type, Active.
*(A Notes column is also available but hidden by default.)*

**Toolbar actions:**

| Action | Behavior |
|---|---|
| **Add** | Opens the resource form in create mode. All required fields must be filled before saving. |
| **Edit** | Opens the resource form loaded with the selected row's data. Select exactly one row first. |
| **Retire** | Prompts for confirmation, then marks the resource inactive (`is_active = false`). The resource is never physically deleted. It will be excluded from PT exports and cannot be scheduled on new jobs, but any historical references remain intact. |
| **Show Inactive / Hide Inactive** | Toggles whether inactive (retired) resources appear in the list. Defaults to hiding inactive records. Toggling this clears the current resource selection. |
| **Show Only Unmapped / Show All Resources** | Filters the list to resources that have **no capability assignments at all**. These resources cannot be scheduled by PT. Use this to quickly identify gaps before exporting. Toggling this also clears the current selection. |

**Resource form fields:**

| Field | Required | Notes |
|---|---|---|
| Resource Name | ✅ | The display name in PT. Use properly-cased names ("Powder Coat," not "powder coat"). |
| Plant | ✅ | Defaults to the existing plant. Phase 1 always uses plant `1`. |
| Department | ✅ | Must match one of the four active departments. Pick from the dropdown. |
| Resource Type | ✅ | Loaded live from the database schema. Choose `Machine` for individual machines, `WorkCenter` for work centers, or `Labor` for labor pools. |
| Capacity Type | ✅ | Loaded live from the database schema. Defaults to `Infinite` for Phase 1. See Section 1 for what each value means in PT. |
| Notes | | Optional free-text for internal use. Not sent to PT. |

> **Resource Type and Capacity Type** dropdown values are loaded directly from the database schema's CHECK constraint via the API. This means the options always reflect what the schema allows — no UI change is needed if the constraint is ever updated.

**Selecting a resource row:** Clicking a row in this grid selects that resource and filters the Resource Capabilities grid to show only that resource's capability assignments. Any capability selection is cleared at the same time.

---

### Capabilities Grid

This grid shows all APS capability definitions from `aps.capability_source`.

**Columns displayed by default:** Capability ID, Name, Description, Active.
*(A Notes column is also available but hidden by default.)*

**Toolbar actions:**

| Action | Behavior |
|---|---|
| **Add** | Opens the capability form in create mode. |
| **Edit** | Opens the capability form for the selected row. |
| **Retire** | Prompts for confirmation, then marks the capability inactive. Never physically deleted. |
| **Show Inactive / Hide Inactive** | Toggles visibility of inactive capabilities. Defaults to hiding them. Clearing this also clears the current capability selection. |
| **Show Only Unmapped / Show All Capabilities** | Filters to capabilities that are not assigned to any resource. A capability with no resource assignments cannot be used to schedule anything. Use this to find capabilities that need to be assigned before exporting. |

**Capability form fields:**

| Field | Required | Notes |
|---|---|---|
| Capability ID | Read-only | Shown on the edit form for reference. On a new capability, the ID is generated automatically by the system — you do not supply it. |
| Name | ✅ | The display name in PT. This is what planners see when reviewing job requirements in PlanetTogether. |
| Description | | Optional. Describe the type of work this capability covers, which resources it applies to, or any constraints. |
| Notes | | Optional internal notes. |

> **Capability IDs are system-generated** when you add a new capability. You do not choose the ID. The generated ID flows to PT as the `Capabilities.ExternalId` and will be referenced by resource-capability assignments and operation links — so once created, a capability ID is permanent. Retire and recreate if a significant change is needed.

**Selecting a capability row:** Clicking a row selects that capability and simultaneously filters *two* grids:
1. **Resource Capabilities** — shows only assignments that include this capability (i.e., which resources can do this type of work).
2. **Capability-Operation Links** — shows only operation links for this capability (i.e., which operations require this type of work).

Any resource selection is cleared at the same time.

---

### Resource Capabilities Grid

This grid shows resource-to-capability assignments from `aps.capability_assignment_source`. It is the link that tells PT which resources are eligible to perform which types of work.

**Columns displayed by default:** Resource, Capability, Plant, Department, Active.
*(Notes is available but hidden.)*

**Toolbar actions:**

| Action | Behavior |
|---|---|
| **Add** | Opens the assignment form. Choose the resource and capability; Plant and Department are filled in automatically from the selected resource. |
| **Edit** | Opens the assignment form for the selected row. The Resource and Capability fields are **locked** because they form the composite primary key and cannot be changed after creation. Only **Notes** can be edited. |
| **Retire** | Prompts for confirmation, then removes or inactivates the assignment. |

**Assignment form fields:**

| Field | Add | Edit | Notes |
|---|---|---|---|
| Resource | ✅ editable | 🔒 locked | Dropdown shows only active resources. When a resource is selected, Plant and Department are filled in automatically. |
| Capability | ✅ editable | 🔒 locked | Dropdown shows only active capabilities. |
| Notes | editable | editable | Optional internal notes. |

**How the filter works:**

- If a **resource is selected** in the Resources grid: shows only that resource's assignments (i.e., what capabilities does this resource have?).
- If a **capability is selected** in the Capabilities grid: shows only assignments for that capability (i.e., which resources can do this work?).
- If **nothing is selected**: shows all assignments.

This makes the Resource Capabilities grid a two-direction lookup depending on what you click first.

---

### Capability-Operation Links Grid

This grid links ERP routing operations to the capabilities they require. It lives in a separate source table and is the mechanism that tells PT *what kind of work* each operation step needs, so PT can find eligible resources.

Every routing operation that will be scheduled in PT must have at least one link here. Without it, PT cannot find a resource for the operation and it will not schedule.

**Columns displayed by default:** Operation, Capability, Capability Name, Seq (Requirement Sequence), Active.
*(Operation ID and Notes are also available.)*

**Toolbar actions:**

| Action | Behavior |
|---|---|
| **Add** | Opens the operation link form. Choose the operation and capability. If a capability is currently selected in the Capabilities grid, the form pre-fills that capability. |
| **Edit** | Opens the form for the selected row. The Operation and Capability fields are **locked** (they identify the link). Only **Requirement Sequence** and **Notes** are editable. |
| **Retire** | Prompts for confirmation, then retires the link. |

**Operation link form fields:**

| Field | Add | Edit | Notes |
|---|---|---|---|
| Operation | ✅ editable | 🔒 locked | Dropdown populated from active ERP routing operations. |
| Capability | ✅ editable | 🔒 locked | Dropdown shows active capabilities. Pre-filled if a capability is selected. |
| Requirement Sequence | ✅ editable | editable | A positive integer (minimum 1). Determines the resource requirement slot in PT — see explanation below. |
| Notes | editable | editable | Optional internal notes. |

**Understanding Requirement Sequence:**

The Requirement Sequence (`Seq`) identifies which resource slot a capability requirement belongs to. PT must find a separate, simultaneously available resource to fill each slot. Action Target's Phase 1 design uses up to three slots per operation:

| Seq | Capability type | What PT finds |
|---|---|---|
| **1** | Machine (`Machine - …`) | The specific machine (or machine class) the operation runs on. Drives the operation's run time and scheduling window. |
| **2** | Pool (`Pool - …`) | A resource from the pool the machine belongs to. Constrains eligibility to machines within the defined group. |
| **3** | Labor (`Labor - …`) | The labor resource required to run the operation. Must be available at the same time as the machine. |

Not every operation has all three slots — for example, operations without a machine-specific requirement omit Seq = 1, and blast has only Seq = 1 (no pool or labor link in Phase 1).

**How the filter works:**

- If a **capability is selected** in the Capabilities grid: shows only operation links for that capability (i.e., which operations require this capability).
- If **nothing is selected** (or a resource is selected): shows all operation links.

---

### How the Tables Work Together

The three middle grids — Resources, Capabilities, and Resource Capabilities — plus the Operation Links grid are all connected through row selections. Here is a summary of what happens when you click in each grid:

| You click... | Resource Capabilities shows... | Operation Links shows... |
|---|---|---|
| A row in **Resources** | Only that resource's capability assignments | All links (unchanged) |
| A row in **Capabilities** | Only assignments for that capability | Only links for that capability |
| Empty space / deselect | All assignments | All links |

Clicking in Resources clears any capability selection, and clicking in Capabilities clears any resource selection. The two grids are mutually exclusive — you are always viewing the assignments from one direction at a time.

This design lets you quickly answer two common questions:

- *"What capabilities does the Weld resource have?"* → Click Weld in the Resources grid.
- *"Which resources can perform Welding, and which operations require it?"* → Click Welding in the Capabilities grid.

---

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

Some PlanetTogether resource features are available in the software but are not being configured for Phase 1. This is intentional — start simple and add complexity as needed.

| PT Feature | Phase 1 Status | Notes |
|---|---|---|
| Plants | ✅ Used | Single plant (Action Target). |
| Departments | ✅ Used | Four departments from ERP `vend_org`. Read-only in Phase 1 tools. |
| Resources | ✅ Used | Maintained in `aps.resource_source`. One per machine, one per work center, one per labor pool. |
| Capabilities | ✅ Used | Maintained in `aps.capability_source`. |
| Capability Assignments | ✅ Used | Maintained in `aps.capability_assignment_source`. |
| Capability-Operation Links | ✅ Used | Maintained in the operation capability link table. Required for job export. |
| Capacity Intervals / Calendars | ❌ Not used | PT will use default shift definitions; no ERP-driven calendar import in Phase 1. |
| Helper Resources (Seq > 1) | ✅ Used | Each operation links to up to three capability slots: Seq 1 = Machine, Seq 2 = Pool, Seq 3 = Labor. All three resources must be simultaneously available for PT to schedule the operation. |
| Cells | ❌ Not used | Cell scheduling not needed initially. |
| Product Rules | ❌ Not used | Confirmed not used for Phase 1. |
| Compatibility Code Tables | ❌ Not used | Not needed for Phase 1. |
| Cleanout Trigger Tables | ❌ Not used | Not needed for Phase 1. |

---

## 7. Summary: The Minimum You Need Before Jobs Can Schedule

Before PlanetTogether can schedule a job, the following must be in place:

1. ✅ Plant record exists (`aps.plant_source`).
2. ✅ Department records exist (`aps.department_source`) for all departments referenced by resources.
3. ✅ Resource records exist and are active (`aps.resource_source`).
4. ✅ Capability records exist and are active (`aps.capability_source`).
5. ✅ Every resource that will carry job operations has at least one capability assigned (`aps.capability_assignment_source`).
6. ✅ Every routing operation that will be scheduled in PT has at least one Capability-Operation Link pointing to a capability that is assigned to at least one active resource.

Missing any of these means PT either cannot find an eligible resource for an operation, or the operation will fail to schedule.