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, 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 object	Owner user details
notes	string	Workflow notes
query	WorkflowQuery object	Workflow search conditions
creator	WorkflowUser object	Creator user details
created_at	string (RFC 3339 timestamp)	Creation date

Certification Properties

Listing access certifications 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 object	List of reviewers

See Query Builder API 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 object	Certification creator details
completed_by	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 object	User details
total_complete_count	int	Number or result rows with an accept, reject, or fixed decision
creator	WorkflowUser object	User details
created_at	string (RFC 3339 timestamp)	Timestamp
updated_at	string (RFC 3339 timestamp)	Timestamp
updated_by	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 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 array	Log of previous actions on the result
decision	string	Row decision
destination	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
notification_status	string	Whether the integration triggered successfully
result_id	int	Result unique identifier for the certification
reviewers	Array of WorkflowUsers	Reviewer details
reviewer_assignment	ReviewerAssignmentInstructions object	Instructions for fallback and auto-assigned reviewers
signed_off_at	string (RFC 3339 timestamp)
signed_off_by	WorkflowUser object	Details for a single reviewer
signed_off_state	string	UNKNOWN_SIGNED_OFF NOT_SIGNED_OFF SIGNED_OFF
source	ResultNode object	Result source (typically a principal)
updated_at	string (RFC 3339 timestamp)
updated_by	WorkflowUser object
waypoint	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 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 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 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 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:

{
  "entries": [
    {
      "action": "REVIEWER_ASSIGNED",
      "user": {
        "user_type": "localCookieUser",
        "id": "e5aeaaf6-5d7a-4982-aa61-d0e6dea612a5",
        "email": "[e-mail]",
        "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": "[e-mail]",
            "name": "docs"
          }
        ]
      }
    },
    {
      "action": "DECISION",
      "user": {
        "user_type": "localCookieUser",
        "id": "e5aeaaf6-5d7a-4982-aa61-d0e6dea612a5",
        "email": "[e-mail]",
        "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": "[e-mail]",
        "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": "[e-mail]",
        "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

{
    "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
    }
}