Use Activity views

Activity views groups authorized Process activity through explicit references and associations. A reference is an opaque tenant-scoped identifier. It does not create a customer, case, application, or business-outcome record.

Use this guide after the source owner has recorded lifecycle facts. Activity views shows those facts, including waits and Decision Requests, while Lineage Explorer remains the execution investigation surface.

Access and ownership

workflow:read opens the Processes routes. The source owner authorizes every contributing source before KLA returns its reference, count, time, relationship, or timeline item. activity_reference:manage manages associations and activity_view:manage manages saved-view definitions. An association call also resolves read access to the source it names, so an identity that holds activity_reference:manage without read access to that source receives FORBIDDEN.

Operation	Generated control-plane procedure
Associate a source	activityReferences.admit
Correct an association	activityReferences.correct
Read effective associations	activityReferences.listEffective
Create, update, archive, or recover a saved view	activityViews.create, activityViews.update, activityViews.archive, activityViews.unarchive
Query groups, activity, or related work	activity.listGroups, activity.getGroup, activity.listActivity, activity.listRelatedGroups

The query path reads the primary API projection. It does not call an owner API for each row. A source owner remains responsible for its lifecycle facts, content, and source drill-down.

Associate two requests with one customer reference

Use explicit references supplied by the source owner or integration. Never derive a reference from prompt text, source display text, or message content. The first body associates one request with a customer reference and a request reference. Save it as request-104-association.json.

{
  "references": [
    { "namespace": "customer", "key": "external_id", "value": "CMB-42" },
    { "namespace": "request", "key": "external_id", "value": "REQUEST-104" }
  ],
  "source": {
    "sourceType": "input_wait",
    "sourceId": "11111111-1111-4111-8111-111111111111",
    "sourceRevision": "wait-104-v1"
  }
}

activityReferences.listEffective carries the source locator on its own and returns the associations that currently contribute to the projection. Save it as request-104-source.json.

{
  "source": {
    "sourceType": "input_wait",
    "sourceId": "11111111-1111-4111-8111-111111111111",
    "sourceRevision": "wait-104-v1"
  }
}

kla api activityReferences admit --input @request-104-association.json
kla api activityReferences listEffective --input @request-104-source.json

Use activityReferences.correct when the effective association changes. The correction names the association it supersedes. The old association remains in history and no longer contributes to the effective projection. Save the correction as request-104-correction.json.

{
  "reference": { "namespace": "request", "key": "external_id", "value": "REQUEST-104-CORRECTED" },
  "source": {
    "sourceType": "input_wait",
    "sourceId": "11111111-1111-4111-8111-111111111111",
    "sourceRevision": "wait-104-v2"
  },
  "supersedesAssociationId": "22222222-2222-4222-8222-222222222222"
}

kla api activityReferences correct --input @request-104-correction.json

Tombstoned sources stay removed after replay. A correction or tombstone can make coverage partial or unavailable; it cannot revive removed content.

Create a fixed saved view

Saved views accept a fixed configuration. The allowed filters are reference equality, source kind, recorded state, and an inclusive date range. The API, CLI, and UI reject formula fields, arbitrary expression trees, custom operators, and a business-outcome field.

A work-scope view lists individual requests. Save this definition as customer-request-history.json.

{
  "name": "Customer request history",
  "grouping": { "namespace": "request", "key": "external_id" },
  "labels": { "grouping": "Request" },
  "scope": "work",
  "orderedColumns": ["reference", "pending_work", "latest_activity", "waiting_since"],
  "filters": {
    "referenceEquals": [],
    "sourceKinds": ["input_wait", "input_event", "execution"],
    "statuses": ["waiting", "completed"]
  },
  "sort": { "field": "latest_activity", "direction": "desc" }
}

Related work belongs to a subject-scope view that carries a secondary grouping. activity.listRelatedGroups rejects any other configuration with secondary_grouping_required. Save this definition as customer-history-view.json.

{
  "name": "Customer history",
  "grouping": { "namespace": "customer", "key": "external_id" },
  "labels": { "grouping": "Customer", "secondaryGrouping": "Request" },
  "scope": "subject",
  "secondaryGrouping": { "namespace": "request", "key": "external_id" },
  "orderedColumns": ["reference", "pending_work", "latest_activity", "secondary_reference"],
  "filters": {
    "referenceEquals": [],
    "sourceKinds": ["input_wait", "input_event", "execution"],
    "statuses": ["waiting", "completed"]
  },
  "sort": { "field": "latest_activity", "direction": "desc" }
}

An update replaces the whole saved configuration. The body carries every configuration field with the view id and its current expectedRevision. This update adds the deadline column. Save it as customer-request-history-update.json.

{
  "id": "33333333-3333-4333-8333-333333333333",
  "expectedRevision": 1,
  "name": "Customer request history",
  "grouping": { "namespace": "request", "key": "external_id" },
  "labels": { "grouping": "Request" },
  "scope": "work",
  "orderedColumns": ["reference", "pending_work", "latest_activity", "waiting_since", "deadline"],
  "filters": {
    "referenceEquals": [],
    "sourceKinds": ["input_wait", "input_event", "execution"],
    "statuses": ["waiting", "completed"]
  },
  "sort": { "field": "latest_activity", "direction": "desc" }
}

Archiving keeps the definition and removes the view from the list. It takes the view id and the revision the update returned. Save it as customer-request-history-archive.json.

{
  "id": "33333333-3333-4333-8333-333333333333",
  "expectedRevision": 2
}

Recovery restores an archived view and takes the revision the archive returned. Save it as customer-request-history-unarchive.json.

{
  "id": "33333333-3333-4333-8333-333333333333",
  "expectedRevision": 3
}

kla api activityViews create --input @customer-request-history.json
kla api activityViews create --input @customer-history-view.json
kla api activityViews update --input @customer-request-history-update.json
kla api activityViews archive --input @customer-request-history-archive.json
kla api activityViews unarchive --input @customer-request-history-unarchive.json

Every saved-view mutation returns the next revision. Reload the saved definition before retrying a conflict.

Query work and customer history

Every query names one saved view. A requested filter narrows the saved filter, and a requested sort field must appear in the saved orderedColumns. Each successful response supplies asOf, coverage, and nextCursor. totalCount is scoped to the authorized snapshot and can be null when the query reaches its aggregation bound.

activity.listGroups lists the groups of the work-scope view. Save the query as waiting-requests-query.json.

{
  "viewId": "33333333-3333-4333-8333-333333333333",
  "filters": {
    "referenceEquals": [],
    "sourceKinds": ["input_wait"],
    "statuses": ["waiting"]
  },
  "limit": 25,
  "sort": { "field": "latest_activity", "direction": "desc" }
}

activity.getGroup reads one group. It requires referenceId and accepts no limit or sort. Save the query as request-104-group.json.

{
  "viewId": "33333333-3333-4333-8333-333333333333",
  "referenceId": "44444444-4444-4444-8444-444444444444"
}

activity.listActivity reads the timeline of one reference and pages through it with the cursor. Save the query as request-104-timeline.json.

{
  "viewId": "33333333-3333-4333-8333-333333333333",
  "referenceId": "44444444-4444-4444-8444-444444444444",
  "limit": 25,
  "sort": { "field": "latest_activity", "direction": "desc" }
}

activity.listRelatedGroups names the subject-scope view and the customer reference, then returns the request groups beneath it. Save the query as customer-42-history.json.

{
  "viewId": "55555555-5555-4555-8555-555555555555",
  "referenceId": "66666666-6666-4666-8666-666666666666",
  "limit": 25,
  "sort": { "field": "latest_activity", "direction": "desc" }
}

kla api activity listGroups --input @waiting-requests-query.json
kla api activity getGroup --input @request-104-group.json
kla api activity listActivity --input @request-104-timeline.json
kla api activity listRelatedGroups --input @customer-42-history.json

The returned cursor binds the query shape and projection snapshot. Use it only for the same view, reference, filters, and sort. Select Refresh to start a new authorized snapshot.

Use the typed TypeScript client

The TypeScript control-plane client uses the same tRPC procedures as the CLI. It carries the access token and tenant header through its configured transport. The Node and Python governance SDKs do not publish Activity views methods.

import type { AppRouter } from '@kla/api';
import { createControlPlaneClient } from '@kla/api-client';

const client = createControlPlaneClient<AppRouter>({
  baseUrl: process.env.KLA_API_URL!,
  tenantId: process.env.KLA_TENANT_ID!,
  token: process.env.KLA_ACCESS_TOKEN!,
});

const view = await client.activityViews.create.mutate(configuration);
const groups = await client.activity.listGroups.query({ viewId: view.id, limit: 25 });

The client receives the same typed configuration contract as the UI. Source authorization still occurs on the server for every query.

Review current activity

Open Processes and select an Activity view. The group list shows separate work references. Open a work reference for its timeline. Open a subject reference for related work. Use the owner links to continue investigation in Lineage Explorer or Decision Desk when the current identity can read that source.

Coverage and freshness describe the returned projection snapshot. A partial result can omit source activity. A permission change removes a source on the next authorized read.