v1.0.0 to v1.0.0

---

name: version-inspector

description: >-

Inspect IBM BAW snapshots and browse deployed containers. Handles read-only

queries, including snapshot metadata (version name, lifecycle status, creation

date, toolkit dependencies), process-app listings, and container inventories.

Works for both Process App and Toolkit types on BAW on-premises, BAW on Cloud,

and CP4BA. Use whenever an administrator wants to inspect, view, or browse

versions or snapshots. This skill is read-only and does not change state.

For state-changing lifecycle operations (installing applications, activating,

deactivating, deleting snapshots, or setting/syncing environment variables),

use version-lifecycle-manager.

license: Apache-2.0

compatibility: "IBM BAW 22.x and later; IBM CP4BA 22.x and later"

allowed-tools:

- Bash

metadata:

version: "1.0.0"

display_name: BAW Version Inspector

short_description: Browse and inspect BAW snapshot metadata — version names, lifecycle status, creation dates, and toolkit dependencies.

author: IBM BAW Team

---

# Version Inspector

Retrieve and present a plain-language summary of a BAW snapshot's current state — version name, lifecycle status, creation date, in-flight task count, and toolkit dependencies — using the public Operations REST API. No write operations are performed. Works for both Process App and Toolkit container types.

## Entry point — choosing the right path

Before calling any API, determine how much the user already knows:

| User knows | Start at |

|---|---|

| Container acronym **and** snapshot version | Retrieval workflow below |

| Container acronym but **not** the snapshot version | Snapshot picker section below |

| Neither container nor snapshot | Container browser section below |

---

```bash

curl -sk -X GET \

```

The `optional_parts=versions` parameter returns containers **and** their snapshots in a single call. Use `type=PA` or `type=TK` to filter to Process Apps or Toolkits only; omit to return both.

Present results in two labelled tables — Process Apps first, then Toolkits (`"toolkit": true`):

**Process Apps**

| Name | Acronym | Created |

|------|---------|---------|

| HR Process Application | HRAPP | 2025-06-10 |

**Toolkits**

| Name | Acronym | Created |

|------|---------|---------|

| Shared Utilities | SHAREDTK | 2025-03-01 |

> `container` in the response is the acronym to use in all subsequent API calls. `container_name` is the display name.

After presenting the list, ask: "Which one would you like to inspect? I can show you its snapshots."

---

## Snapshot picker — user knows the container but not the snapshot

Use this path when the user provides a container acronym (or name) but not a snapshot version — or after selecting a container from the browser above.

```bash

curl -sk -X GET \

```

Present that container's snapshots as a table:

| Acronym | Name | Status | Created |

|---------|------|--------|---------|

| v2.0 | HR Process v2.0 | Active ✅ | 2025-06-10 |

| v1.9 | HR Process v1.9 | Inactive ⏸ | 2025-03-01 |

Then ask: "Which snapshot would you like to inspect in detail?"

---

## Retrieval workflow — known container and snapshot

### Step 1 — Call the Operations API

**Method:** `GET`

**Path:** `/ops/std/bpm/containers/{container}/versions/{version}`

```bash

curl -sk -X GET \

```

This is a read-only call — no confirmation is needed before making it. Show the exact `curl` command in the response.

### Step 2 — Enrich toolkit dependencies (if needed)

The Operations API `version` schema does not include a `toolkitDependencies` field. To retrieve dependency data, make a second call to the WLE endpoint.

> **WLE context root:** If `<WLE_BASE_URL>` prefix is already known or was established earlier in the session (e.g. `/rest` or `""`), reuse it directly. **Do not probe if the prefix is already known.**

**Probe only once if the WLE context root is unknown:**

If the WLE context root has not been determined yet, test prefixes (`/rest`, `""`, `/baw`, `/bas`) once and cache the working prefix for all subsequent calls in the session:

```bash

for prefix in "/rest" "" "/baw" "/bas"; do

code=$(curl -sk -o /dev/null -w "%{http_code}" \

"https://<host>:9443${prefix}/bpm/wle/v1/processApps?includeToolkitProcessApps=true" \

-H "Authorization: Basic <base64(user:pass)>" \

-H "BPMCSRFToken: <csrf_token>")

echo "prefix='${prefix}' -> HTTP $code"

done

```

Use the first prefix that returns HTTP 200 as `<WLE_BASE_URL>` for the calls below and reuse it across all subsequent queries.

**For Process Apps:**

```bash

curl -sk -X GET \

"<WLE_BASE_URL>/bpm/wle/v1/processApps?includeToolkitProcessApps=true" \

-H "Authorization: Basic <base64(user:pass)>" \

-H "BPMCSRFToken: <csrf_token>"

```

Locate the container by `shortName`, then find the target snapshot in `installedSnapshots` by `acronym`. Look for toolkit references in `toolkits`, `dependencies`, or `usedToolkitSnapshots` (field name varies by BAW version).

**For Toolkits:**

```bash

curl -sk -X GET \

"<WLE_BASE_URL>/bpm/wle/v1/toolkit?includeSnapshots=true" \

-H "Authorization: Basic <base64(user:pass)>" \

-H "BPMCSRFToken: <csrf_token>"

```

Locate the toolkit by `shortName`, then find the target snapshot in `installedSnapshots`.

If no dependency data is found from either source, report "No toolkit dependencies found for this snapshot." — do not infer or guess.

### Step 3 — Present the Snapshot Summary

Use this fixed block format. Fill every field; use `—` for fields not returned by the API.

```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Snapshot Summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Container : <container> (Process App | Toolkit)

Snapshot name : <version_name>

Snapshot ID : <version>

Status : Active ✅ | Inactive ⏸ | Unknown

Created : YYYY-MM-DD HH:mm UTC

Branch : <branch_name> (or —)

Default : Yes | No

State : <status> (e.g. New, Validated, Released)

Dependencies

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Toolkit name | Acronym | Snapshot |

|------------------|---------|----------|

| System Data | TWSYS | 1.0 |

(or: No toolkit dependencies found for this snapshot.)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

```

**Field mapping (Operations API → summary block):**

| Block field | API field | Notes |

|---|---|---|

| Container | `container` + `toolkit` flag | `toolkit: true` → "Toolkit", `false` → "Process App" |

| Snapshot name | `version_name` | Human-readable name |

| Snapshot ID | `version` | Acronym — use in subsequent API calls |

| Status | `active: true` → Active ✅ · `active: false` → Inactive ⏸ · field absent → Unknown | |

| Created | `creation_date` | Format as `YYYY-MM-DD HH:mm UTC` |

| Branch | `branch_name` | From Operations API response |

| Default | `is_default` | `true` / `false` |

| State | `status` | Development lifecycle state |

| Dependencies | WLE enrichment (Step 2) | Not in Operations API response |

### Step 4 — Offer next steps

End with: **Next steps:** To activate, deactivate, delete this snapshot, or manage its environment variables, use the `version-lifecycle-manager` skill — or ask me to do it now.

---

## Boundaries

**In scope:** Read-only snapshot metadata queries, listing process apps and toolkits, container inventory discovery, toolkit dependency inspection.

**Out of scope — redirect explicitly:**

- **State-changing lifecycle operations:** Installing applications, activating/deactivating snapshots, deleting snapshots, and setting/syncing environment variables → use `version-lifecycle-manager`.

- **Runtime process instance operations:** Inspecting or acting on running/failed instances → use `inspect-baw-processes`.

- **Generating BPMN processes or Business Objects:** → use `generate-baw-bpmn` or `generate-baw-business-objects`.

---

## Error handling

| HTTP | Likely cause | What to say |

|---|---|---|

| `401` | Invalid credentials | "Authentication failed — check the username/password or API key and try again." |

| `400 CWTBG0624E` | Container acronym not found | "The container `<acronym>` was not found — acronyms are case-sensitive. Offer to list containers to confirm the exact acronym." |

| `400 CWTBG0646E` | Snapshot acronym not found | "The snapshot `<version>` was not found in container `<acronym>`. Offer to list snapshots to confirm the exact acronym." |

| `404` | Operations API not present on server | "This server may be IBM BPM 8.x, which does not support the Operations REST API. Use the Process Admin Console to inspect snapshots manually." |

---

## Examples

**Example 1 — Process App snapshot**

**Example 2 — CP4BA cluster**

**Example 3 — Toolkit snapshot**

4. Render the Snapshot Summary block.

5. Offer lifecycle action next steps.

3. Ask: "Which one would you like to inspect? I can show you its snapshots."

4. Once the user picks a container, present its snapshots from the `branches[].versions[]` already returned, or call `GET /ops/std/bpm/containers/{container}/versions` if snapshots weren't included.

5. Once the user picks a snapshot, proceed with the Snapshot Summary workflow (Steps 1–4).

**Example 5 — User knows the container but not the snapshot**

Input: "I want to check the status of our current INVOICING process app but I'm not sure what the snapshot name is."

2. Call `GET /ops/std/bpm/containers/INVOICING/versions` and present its snapshots as a picker table (Acronym, Name, Status, Created).

3. Ask the user to confirm which snapshot to inspect.

4. Then proceed with the Snapshot Summary workflow.

## Reference files

- **`references/BAW_SNAPSHOT_API.md`** — Authentication patterns, CSRF token acquisition, base URLs by deployment type, full response schemas for the Ops API and WLE endpoints, and common error codes.