# Workflow Parameters Reference This page describes common properties for listing workflows, certifications, and certification results: ### Workflow Properties When [listing access workflows](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/workflows/listaccessworkflows), 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](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/workflows/listaccesscertifications) 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](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder) 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](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/workflows/getaccesscertresult) 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](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/workflows/updatewebhookinfo) | | `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](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/workflows/listaccesscertresults) 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](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/global-idp-settings) 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](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/workflows/listreviewerinfo) 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 } } ```