> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/workflows/parameters.md). # Workflow Parameters Reference Workflows, certifications, and result details This page describes common properties for listing workflows, certifications, and certification results: ### Workflow Properties When [listing access workflows](/4yItIzMvkpAvMVFAamTf/developers/api/workflows/listaccessworkflows.md), all Veza Workflows are returned within a `values` array. Each has the properties: | Name | Type | Description | | ------------- | ------------------------------------ | -------------------------- | | `workflow_id` | string | Workflow GUID | | `name` | string | Workflow display name | | `description` | string | Extended description | | `owner` | [WorkflowUser](#workflowuser) object | Owner user details | | `notes` | string | Workflow notes | | `query` | WorkflowQuery object | Workflow search conditions | | `creator` | [WorkflowUser](#workflowuser) object | Creator user details | | `created_at` | string (RFC 3339 timestamp) | Creation date | ### Certification Properties [Listing access certifications](/4yItIzMvkpAvMVFAamTf/developers/api/workflows/listaccesscertifications.md) returns all Certifications for a workflow, within a `values` array. Note that to maintain certification integrity, some properties are immutable and can't be modified, while other values system-updated. Mutable fields such as "name," "notes," "reviewers" and "due date" can be changed by operators and admins using the Veza UI: | Name | Type | Description | | ------------------ | ------------------------------------ | --------------------------------------- | | `certification_id` | string | Certification GUID | | `workflow_id` | string | Workflow GUID | | `query_used` | WorkflowQuery | The query for the workflow (immutable). | | `name` | string | Certification name (not used) | | `notes` | string | Certification notes | | `due_date` | string (RFC 3339 timestamp) | Due date timestamp | | `reviewers` | [WorkflowUser](#workflowuser) object | List of reviewers | > See [Query Builder API](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder.md) for more details on query construction. Internal fields are updated by the workflow service to store important metadata: | Name | Type | Description | | ---------------------- | ------------------------------------ | --------------------------------------------------------------- | | `state` | AccessCertState | Certification status | | `snapshot_time` | string (RFC 3339 timestamp) | Date of graph snapshot at certification creation | | `started_at` | string (RFC 3339 timestamp) | Certification creation date | | `query_completed_at` | string (RFC 3339 timestamp) | Timestamp indicating when certification results were generated | | `completed_at` | string (RFC 3339 timestamp) | Certification completion date | | `created_by` | [WorkflowUser](#workflowuser) object | Certification creator details | | `completed_by` | [WorkflowUser](#workflowuser) object | User who marked certification as *complete* | | `total_result_count` | int | Total query results | | `results_updated_at` | string (RFC 3339 timestamp) | Timestamp | | `results_updated_by` | [WorkflowUser](#workflowuser) object | User details | | `total_complete_count` | int | Number or result rows with an accept, reject, or fixed decision | | `creator` | [WorkflowUser](#workflowuser) object | User details | | `created_at` | string (RFC 3339 timestamp) | Timestamp | | `updated_at` | string (RFC 3339 timestamp) | Timestamp | | `updated_by` | [WorkflowUser](#workflowuser) object | User details | | `error_reason` | string | Error message, if the workflow query failed | | `expired_at` | string (RFC 3339 timestamp) | Timestamp | | `total_result_count` | int | Total number of results | | `total_complete_count` | int | Results with a final decision | | `total_rejected_count` | int | Results with a "reject" decision | | `total_accepted_count` | int | Results with an "accept" decision | | `total_fixed_count` | int | Results that have been "marked as fixed" | States can be: * `CERT_STATE_SEARCHING` // The query is still running * `CERT_STATE_IN_PROGRESS` // the certification is being reviewed * `CERT_STATE_COMPLETED` // the review of the certification is complete ### Result Properties [Certification results](/4yItIzMvkpAvMVFAamTf/developers/api/workflows/getaccesscertresult.md) include a numeric ID, the query details, and any decisions and notes. Each result includes entity details for the source -> destination nodes and the cumulative permissions under review: | Name | Type | Description | | ----------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accumulated_effective_permissions` | string list | Cumulative canonical (C/R/U/D) permissions to the resource | | `accumulated_raw_permissions` | string list | List of concrete system permissions to the resource | | `action_log_entries` | [ActionLog](#actionlog) array | Log of previous actions on the result | | `decision` | string | Row decision | | `destination` | [ResultNode](#resultnode) object | The result destination (typically a resource) | | `notes` | string | The most recent note applied to the result | | `notification_response_infos` | array | Error message and status for Webhook integrations, pushed with [UpdateWebhookInfo](/4yItIzMvkpAvMVFAamTf/developers/api/workflows/updatewebhookinfo.md) | | `notification_status` | string | Whether the integration triggered successfully | | `result_id` | int | Result unique identifier for the certification | | `reviewers` | Array of [WorkflowUsers](#workflowuser) | Reviewer details | | `reviewer_assignment` | ReviewerAssignmentInstructions object | Instructions for fallback and auto-assigned reviewers | | `signed_off_at` | string (RFC 3339 timestamp) | | | `signed_off_by` | [WorkflowUser](#workflowuser) object | Details for a single reviewer | | `signed_off_state` | string | `UNKNOWN_SIGNED_OFF` `NOT_SIGNED_OFF` `SIGNED_OFF` | | `source` | [ResultNode](#resultnode) object | Result source (typically a principal) | | `updated_at` | string (RFC 3339 timestamp) | | | `updated_by` | [WorkflowUser](#workflowuser) object | | | `waypoint` | [ResultNode](#resultnode) object | Related intermediate entity details, if specified by the workflow query | Valid decisions are: 1. `RESULT_DECISION_NONE` // No decision has been made 2. `RESULT_DECISION_ACCEPTED` // The access described in the result row is acceptable 3. `RESULT_DECISION_REJECTED` // The access described in the result row isn't correct 4. `RESULT_DECISION_FIXED` // The access was rejected, but has been fixed Both the number or string value for the decision are allowed, for example `"decision": 4` or `"decision": RESULT_DECISION_FIXED`. The `notes` field will always contain the most recent note. Previous notes can be reviewed in the [action log](/4yItIzMvkpAvMVFAamTf/developers/api/workflows/listaccesscertresults.md) using the List Cert Results API. ### ResultNode Shows source, destination, or intermediate entity details for a query result: | Name | type | Description | | ---------- | -------------- | ----------------- | | `type` | string | Entity type | | `name` | string | Entity name | | `id` | string | Entity UID | | properties | key:value pair | Entity properties | ### WorkflowUser Reviewer details, typically a Veza user account. If [global IdP settings](/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/global-idp-settings.md) are configured, the user type and id refer to Veza graph entities: | Name | Type | Description | | ----------- | ------ | ------------------------------------ | | `user_type` | string | SSO entity type or `localCookieUser` | | `id` | string | User GUID | | `email` | string | User email address | | `name` | string | Full username | You can get details for a local Veza user from *Administration* > *User Management*. For graph entities (identities from an external identity provider), inspect the entity details using *Access Search* or the *Entities* page. [List Reviewer Infos](/4yItIzMvkpAvMVFAamTf/developers/api/workflows/listreviewerinfo.md) will return all users for a given certification. * When assigning reviewers using preview Workflows APIs, requested users are validated before assigning them to a certification result, and not assigned when the user can’t be found. Assignee `id` and `user_type` are required to identify reviewers. `name` and `email` are optional but if provided must match the Veza user record. ### ActionLog Results contain a record of all prior actions on a certification result. | Name | Type | Description | | ----------------- | ------------------------------------ | --------------------------- | | `action` | string | Action log event type | | `user` | [WorkflowUser](#workflowuser) object | Reviewer details | | `time` | string | RFC 3339 timestamp | | `decision_detail` | object | Decision type and any notes | Possible actions are: * `NOTE_ADDED` * `REVIEWER_ASSIGNED` * `DECISION` The response will include the type, id, email, and name of the user who made the change: ```json { "entries": [ { "action": "REVIEWER_ASSIGNED", "user": { "user_type": "localCookieUser", "id": "e5aeaaf6-5d7a-4982-aa61-d0e6dea612a5", "email": "cookie@cookie.ai", "name": "preview-auth0" }, "time": "2022-09-20T17:50:06.939577367Z", "reviewer_detail": { "old_reviewers": [], "new_reviewers": [ { "user_type": "localCookieUser", "id": "299d63c2-8edb-4ed1-a725-e56d84d956b7", "email": "aallen@veza.com", "name": "docs" } ] } }, { "action": "DECISION", "user": { "user_type": "localCookieUser", "id": "e5aeaaf6-5d7a-4982-aa61-d0e6dea612a5", "email": "cookie@cookie.ai", "name": "preview-auth0" }, "time": "2022-09-20T17:50:21.424281596Z", "decision_detail": { "decision": "RESULT_DECISION_ACCEPTED", "note": "OK" } }, { "action": "DECISION", "user": { "user_type": "localCookieUser", "id": "e5aeaaf6-5d7a-4982-aa61-d0e6dea612a5", "email": "cookie@cookie.ai", "name": "preview-auth0" }, "time": "2022-09-20T17:50:44.381372987Z", "decision_detail": { "decision": "RESULT_DECISION_FIXED", "note": "" } }, { "action": "NOTE_ADDED", "user": { "user_type": "localCookieUser", "id": "e5aeaaf6-5d7a-4982-aa61-d0e6dea612a5", "email": "cookie@cookie.ai", "name": "preview-auth0" }, "time": "2022-09-20T17:52:14.773114900Z", "note": "updating the note" } ] } ``` ### ReviewerAssignmentInstructions The `reviewer_assignment` specifies how reviewers should be assigned to rows, during initial certification create or when reviewers are re-assigned by smart action. `users_manager` and `resource_managers` assigns reviewers based on Global IdP settings. `reviewers` is a way to specify one or more reviewers to apply to every row. `fallback_reviewers` is one or more reviewers that to assign to rows if auto assign by user or resource manager fails for any reason ```json { "reviewer_assignment": { "fallback_reviewers": [ { "email": "string", "id": "string", "name": "string", "user_type": "string" } ], "resource_managers": true, "reviewers": [ { "email": "string", "id": "string", "name": "string", "user_type": "string" } ], "users_manager": true } } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/workflows/parameters.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.