Usar vistas de actividad

Las vistas de actividad agrupan la actividad autorizada de Processes mediante referencias y asociaciones explícitas. Una referencia es un identificador opaco del ámbito del tenant. No crea un registro de cliente, caso, solicitud ni resultado de negocio.

Use esta guía después de que el propietario de la fuente haya registrado los hechos de ciclo de vida. Las vistas de actividad muestran esos hechos, incluidas las esperas y las Decision Requests. Lineage Explorer sigue siendo la superficie de investigación de la ejecución.

Acceso y propiedad

workflow:read abre las rutas de Processes. El propietario de la fuente autoriza cada fuente que contribuye antes de que KLA devuelva su referencia, recuento, hora, relación o elemento de cronología. activity_reference:manage gestiona las asociaciones y activity_view:manage gestiona las definiciones de vistas guardadas. Una llamada de asociación también resuelve el acceso de lectura a la fuente que nombra, por lo que una identidad con activity_reference:manage sin acceso de lectura a esa fuente recibe FORBIDDEN.

Operación	Procedimiento generado del plano de control
Asociar una fuente	`activityReferences.admit`
Corregir una asociación	`activityReferences.correct`
Leer asociaciones efectivas	`activityReferences.listEffective`
Crear, actualizar, archivar o recuperar una vista guardada	`activityViews.create`, `activityViews.update`, `activityViews.archive`, `activityViews.unarchive`
Consultar grupos, actividad o trabajo relacionado	`activity.listGroups`, `activity.getGroup`, `activity.listActivity`, `activity.listRelatedGroups`

La ruta de consulta lee la proyección de la API principal. No llama a la API de un propietario por cada fila. El propietario de la fuente sigue siendo responsable de sus hechos de ciclo de vida, su contenido y su detalle de fuente.

Asociar dos solicitudes con una referencia de cliente

Use referencias explícitas suministradas por el propietario de la fuente o la integración. Nunca derive una referencia del texto de un prompt, del texto mostrado de una fuente ni del contenido de un mensaje. El primer cuerpo asocia una solicitud con una referencia de cliente y una referencia de solicitud. Guárdelo como 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 lleva solo el localizador de fuente y devuelve las asociaciones que contribuyen actualmente a la proyección. Guárdelo como 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 cuando cambie la asociación efectiva. La corrección nombra la asociación que sustituye. La asociación anterior permanece en el historial y deja de contribuir a la proyección efectiva. Guarde la corrección como 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

Las fuentes con tombstone siguen eliminadas tras la reproducción. Una corrección o un tombstone puede dejar la cobertura en partial o unavailable; no restaura el contenido eliminado.

Crear una vista guardada fija

Las vistas guardadas aceptan una configuración fija. Los filtros permitidos son la igualdad de referencia, el tipo de fuente, el estado registrado y un rango de fechas inclusivo. La API, la CLI y la UI rechazan campos de fórmula, árboles de expresión arbitrarios, operadores personalizados y un campo de resultado de negocio.

Una vista de ámbito de trabajo enumera solicitudes individuales. Guarde esta definición como 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" }
}

El trabajo relacionado pertenece a una vista de ámbito de sujeto que lleva una agrupación secundaria. activity.listRelatedGroups rechaza cualquier otra configuración con secondary_grouping_required. Guarde esta definición como 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" }
}

Una actualización reemplaza toda la configuración guardada. El cuerpo lleva todos los campos de configuración junto con el id de la vista y su expectedRevision actual. Esta actualización añade la columna de plazo. Guárdela como 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" }
}

El archivado conserva la definición y retira la vista de la lista. Requiere el id de la vista y la revisión que devolvió la actualización. Guárdelo como customer-request-history-archive.json.

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

La recuperación restaura una vista archivada y requiere la revisión que devolvió el archivado. Guárdela como 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

Cada mutación de una vista guardada devuelve la siguiente revisión. Vuelva a cargar la definición guardada antes de reintentar un conflicto.

Consultar trabajo e historial de cliente

Cada consulta nombra una vista guardada. Un filtro solicitado restringe el filtro guardado, y un campo de orden solicitado debe aparecer en los orderedColumns guardados. Cada respuesta correcta proporciona asOf, coverage y nextCursor. totalCount se limita a la instantánea autorizada y puede ser null cuando la consulta alcanza su límite de agregación.

activity.listGroups enumera los grupos de la vista de ámbito de trabajo. Guarde la consulta como 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 lee un grupo. Requiere referenceId y no acepta limit ni sort. Guarde la consulta como request-104-group.json.

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

activity.listActivity lee la cronología de una referencia y la pagina con el cursor. Guarde la consulta como 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 nombra la vista de ámbito de sujeto y la referencia de cliente, y después devuelve los grupos de solicitud que hay debajo. Guarde la consulta como 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

El cursor devuelto vincula la forma de la consulta y la instantánea de proyección. Úselo solo para la misma vista, referencia, filtros y orden. Seleccione Actualizar para iniciar una nueva instantánea autorizada.

Usar el cliente TypeScript tipado

El cliente TypeScript del plano de control usa los mismos procedimientos tRPC que la CLI. Transporta el token de acceso y la cabecera de tenant por su transporte configurado. Los SDK de gobernanza de Node y Python no publican métodos de vistas de actividad.

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 });

El cliente recibe el mismo contrato de configuración tipado que la UI. La autorización de fuentes se sigue aplicando en el servidor en cada consulta.

Revisar la actividad actual

Abra Processes y seleccione una vista de actividad. La lista de grupos muestra referencias de trabajo separadas. Abra una referencia de trabajo para su cronología. Abra una referencia de sujeto para el trabajo relacionado. Use los enlaces de propietario para continuar la investigación en Lineage Explorer o Decision Desk cuando la identidad actual pueda leer esa fuente.

La cobertura y la frescura describen la instantánea de proyección devuelta. Un resultado parcial puede omitir actividad de una fuente. Un cambio de permisos retira una fuente en la siguiente lectura autorizada.