Entry Criteria Evaluation Response

Some of Vault API's object and document lifecycle and workflow action endpoints support the entrycriteria query parameter. When a supported lifecycle or workflow action fails due to entry criteria violations and the entrycriteria=true query parameter is included in the request, the response includes a source_context object and an entry_criteria array in addition to the standard error fields.

If entrycriteria is omitted or set to false, the response is unchanged from the existing behavior. If entrycriteria=true is used on an unsupported action type, Vault returns OPERATION_NOT_ALLOWED.

Source Context Fields

The source_context object contains context about the record or document that caused the entry criteria error. When a nested state change on a related record triggers the failure, is_nested returns true and the source_context reflects the related record, not the originally targeted record. For example, approving a Contract record automatically moves its Tasks and a Task fails entry criteria. In this example, Task is a nested object and the Task record is the source_context, rather than Contract.

Field	Description
`source_context.is_nested`	This is set to `true` when the source of the entry criteria error is not the record or document the action was originally initiated on. Otherwise, `false`.
`source_context.type`	The type of source context: `object` or `document`.
`source_context.object_name`	The name of the object. For example, `task__c`.
`source_context.record_id`	The ID of the failing object record.
`source_context.document_id`	The ID of the failing document.
`source_context.major_version_number__v`	The major version of the failing document.
`source_context.minor_version_number__v`	The minor version of the failing document.
`source_context.lifecycle`	The name of the lifecycle the target state belongs to. For example, `contract_management_lifecycle__c`.
`source_context.target_state`	The name of the target state the action attempted to reach. For example, `in_review_state__c`.

Entry Criteria Array

The entry_criteria array contains one or more entry criteria requirements. Each item represents a single unmet criterion. The array includes all in-scope criteria that are not met. An empty array indicates all entry criteria passed.

As records or documents are updated, rule conditions may activate or deactivate. Vault drops criteria whose conditions have been deactivated from subsequent responses.

Field	Description
`entry_criteria[].type`	The type of requirement: `field`, `related_data`, or `message`.
`entry_criteria[].message`	The entry criteria validation message in the initiating user's language.
`entry_criteria[].field`	This is returned when `type` is `field`. See Field Type Fields.
`entry_criteria[].related_data`	This is returned when `type` is `related_data`. See Related Data Type Fields.

Field Type Fields

The following fields are returned for entry criteria that validate a field on the lifecycle's associated object or document:

Field	Description
`entry_criteria[].field.name`	The name of the field that must be populated.
`entry_criteria[].field.url`	The Metadata API URI for the field. For object fields: `/api/{version}/metadata/vobjects/{object_name}/fields/{field_name}`. For document fields: `/api/{version}/metadata/objects/documents/properties`.

The following fields are returned for object lifecycle entry criteria that validate the lifecycle state of related records or documents:

Field	Description
`entry_criteria[].related_data.direction`	The relationship direction: `INBOUND`, `OUTBOUND`, or `JOIN`.
`entry_criteria[].related_data.related_object`	The name of the related object, or `documents` for document relationships.
`entry_criteria[].related_data.join_object`	The name of the join object if the direction is `JOIN`.
`entry_criteria[].related_data.field_name`	The name of the reference field. For inbound relationships, this is the field on the related object. For outbound relationships, this is the field on the source object. For join relationships, this is the field on the join object.
`entry_criteria[].related_data.field_url`	The Metadata API URI for the field in `field_name`. The version matches the version used in the request.
`entry_criteria[].related_data.relationship_name`	The name of the inbound or outbound relationship. For example, `contract_owner__cr`.
`entry_criteria[].related_data.source_field_name`	The source object field name on the join object if the direction is `JOIN`.
`entry_criteria[].related_data.required_states[]`	The state names configured in the entry criteria. For example, `active_state__sys`. This is not returned when `required_state_types` is present.
`entry_criteria[].related_data.required_state_types[]`	The state type names configured in the entry criteria. For example, `complete_state__sys`. This is not returned when `required_states` is present.
`entry_criteria[].related_data.required_state_lifecycle`	The name of the lifecycle that owns `required_states`. This is not returned when `required_state_types` is configured.
`entry_criteria[].related_data.operator`	The evaluation operator used in the entry criteria configuration. See Evaluation Operators.
`entry_criteria[].related_data.unmet_count`	The total count of related records or documents that do not meet the entry criteria. See Unmet Count Behavior to interpret the counts returned in the response.

Message Type Fields

The message type is returned for all other entry criteria types, such as formula validations. The response returns no additional fields besides type and message. For example, the message returned may be Formula must be TRUE.

Evaluation Operators

The operator field in the related data type returns one of the following values:

Value	UI Label
`EQUALS`	Equals
`NOT_EQUALS`	Is not equal to
`INCLUDES`	Includes
`NOT_INCLUDES`	Does not include
`ALL_EQUAL`	All records equal
`NONE_EQUAL`	No records equal
`AT_LEAST_ONE_EQUAL`	At least one record equals
`ALL_INCLUDE`	All records include
`NONE_INCLUDE`	No records include
`AT_LEAST_ONE_INCLUDE`	At least one record includes
`AT_LEAST_ONE_EXISTS`	At least one record exists

Unmet Count Behavior

The value of unmet_count depends on the operator and relationship direction.

Outbound Relationships

For outbound relationships, unmet_count is 1 for most operators because an outbound relationship references a single related record. AT_LEAST_ONE_EQUAL and AT_LEAST_ONE_EXISTS always return null because a count is not meaningful when the check is only whether any matching record exists. Once the requirement is satisfied, the criteria no longer appear in the response.

Operator	Value
`EQUALS`, `NOT_EQUALS`, `INCLUDES`, `NOT_INCLUDES`, `ALL_EQUAL`, `NONE_EQUAL`	`1`
`AT_LEAST_ONE_EQUAL`, `AT_LEAST_ONE_EXISTS`	`null`

Inbound Relationships

For inbound relationships, ALL_EQUAL and ALL_INCLUDE return the count of related records not meeting the criteria because an inbound relationship can reference multiple related records. AT_LEAST_ONE_EQUAL, AT_LEAST_ONE_INCLUDE, and AT_LEAST_ONE_EXISTS always return null because a count is not meaningful for existence-check operators.

Operator	Value
`ALL_EQUAL`	Number of related records not in the required state
`ALL_INCLUDE`	Number of related records not belonging to the required states
`NONE_EQUAL`, `NONE_INCLUDE`	`null`
`AT_LEAST_ONE_EQUAL`, `AT_LEAST_ONE_INCLUDE`, `AT_LEAST_ONE_EXISTS`	`null`