Lifecycle Role Assignment Rules

For both standard and custom roles, you can define a subset of users who are allowed in the role and define users that Vault automatically assigns to the role at document creation or when a workflow starts. You can also override the allowed users and default users settings based on standard object-type document fields like Country, Product, Study, etc.

Article Contents

The following sections provide detailed information and examples:

Limitations

  • The API can only be used with active lifecycles and roles.
  • The maximum number of roles that can be created or updated per request is 50,000.
  • The lifecycle role default rule cannot be set when creating override rules.
  • A role cannot be assigned more users or groups to default roles than allowed on the role.
  • The default owner__v role cannot be edited.

Vault Help Resources

Learn about Lifecycles & Workflows
Learn about Defining Allowed & Default Users for Roles
Learn about Users & Groups
Learn about Fields & Objects

Vault API Resources

See the Vault Documents API
See the Vault Binders API
See the Vault Roles API
See the Vault Users API
See the Vault Groups API
See the Vault Objects API

Retrieve Lifecycle Role Assignment Rules (Default & Override)

Request

Send GET to api/{version}/configuration/role_assignment_rule

Headers

Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Parameters

This endpoint alone will retrieve a list of all lifecycle role assignment rules (default & override) from all roles in all lifecycles in your vault.

To filter the results by lifecycle or role, add one or both of the following parameters to the request endpoint:

  • lifecycle__v={lifecycle_name} - Include the name of the lifecycle from which to retrieve information. For example: lifecycle__v=general_lifecycle__vs
  • role__v={role_name} - Include the name of the role from which to retrieve information. For example: role__v=editor__c

For example, to retrieve the lifecycle role assignment rules (default & override) from:

  • All roles in a specific lifecycle, use api/{version}/configuration/role_assignment_rule?lifecycle__v={lifecycle_name}
  • A specific role in all lifecycles, use api/{version}/configuration/role_assignment_rule?role__v={role_name}
  • A specific role in a specific lifecycle, use api/{version}/configuration/role_assignment_rule?lifecycle__v={lifecycle_name}&role__v={role_name}

The response will include:

  • The default role assignments.
  • The override role assignments when an override condition (when configured on the role) is met.
  • The override conditions (when configured on the role).

You can also filter the results by one or more override conditions. This can be included with the filters above or used on its own to retrieve the information from all roles in all lifecycles in which the conditions have been configured.

For example, to retrieve lifecycle role override rules when the product "CholeCap" and country "United States" are assigned to a document:

  • Use the system-managed object record id field values: api/{version}/configuration/role_assignment_rule?product__v=0PR0011001&country__v=0CR0022002
  • Or, use the object record name__v field values (via object__v.name__v lookup): api/{version}/configuration/role_assignment_rule?product__v.name__v=CholeCap&country__v.name__v=United States

The response will exclude the default role assignments and only return the override conditions and role assignments when the override condition is met.

Example

Retrieve lifecycle role assignment rules from a specific role (editor__c) in a specific lifecycle (general_lifecycle__vs):

$ curl -X GET -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__vs&role__v=editor__c

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "lifecycle__v": "general_lifecycle__vs",
            "role__v": "editor__c",
            "allowed_users__v": [
                "ally@veevapharm.com",
                "beth@veevapharm.com",
                "cruz@veevapharm.com",
                "dave@veevapharm.com"
            ],
            "allowed_groups__v": [
                "global_products_team__c",
                "vault_products_team__c",
                "vault_doc_management__c"
            ],
            "allowed_default_users__v": [
                "ally@veevapharm.com"
            ],
            "allowed_default_groups__v": [
                "global_products_team__c"
            ]
        },
        {
            "lifecycle__v": "general_lifecycle__vs",
            "role__v": "editor__c",
            "product__v.name__v": "CholeCap",
            "country__v.name__v": "United States",
            "product__v": "0PR0011001",
            "country__v": "0CR0022002",
            "allowed_users__v": [
                "etta@veevapharm.com",
                "finn@veevapharm.com",
                "greg@veevapharm.com",
                "hope@veevapharm.com"                
            ],
            "allowed_groups__v": [
                "cholecap_us_docs_group__c",
                "cholecap_us_research_group__c",
                "cholecap_us_compliance_group__c",
                "cholecap_us_product_management_group__c"
            ],
            "allowed_default_users__v": [
                "etta@veevapharm.com"
            ],
            "allowed_default_groups__v": [
                "cholecap_us_docs_group__c"
            ]
        }
    ]
}

Details

In the example response above, the editor__c role in the general_lifecycle__vs lifecycle is configured with the following role assignment rules:

Default Rule

When a document is assigned this lifecycle, the following users and groups are automatically assigned to the editor__c role:

  • allowed_default_users__v - The user ally@veevapharm.com is automatically assigned to the role.
  • allowed_users__v - The users beth@veevapharm.com, cruz@veevapharm.com, and dave@veevapharm.com can be (optionally) assigned to the role at any time during the lifecycle.
  • allowed_default_groups__v - The group global_products_team__c is automatically assigned to the role.
  • allowed_groups__v - The groups vault_products_team__c and vault_doc_management__c can be (optionally) assigned to the role at any time during the lifecycle.

Override Conditions

This lifecycle role has been configured with two override conditions which state: If both the product "CholeCap" and country "United States" are assigned to a document, do not apply the default rule, but instead apply the override rule.

The API returns both the system-managed object record id and the user-defined object record name__v (via the object__v.name__v lookup) field values which define the override conditions:

  • "product__v.name__v": "CholeCap" - The product object record name.
  • "country__v.name__v": "United States" - The country object record name.
  • "product__v": "0PR0011001" - The product object record ID.
  • "country__v": "0CR0022002" - The country object record ID.

Override Rule

When both the product "CholeCap" and country "United States" are assigned (at any time) to a document in this lifecycle, the following (alternate) users and groups are automatically assigned to the editor__c role:

  • allowed_default_users__v - The user etta@veevapharm.com is automatically assigned to the role.
  • allowed_users__v - The users finn@veevapharm.com, greg@veevapharm.com, and hope@veevapharm.com can be (optionally) assigned to the role during its lifecycle.
  • allowed_default_groups__v - The group cholecap_us_docs_group__c is automatically assigned to the role.
  • allowed_groups__v - The groups cholecap_us_research_group__c, cholecap_us_compliance_group__c, and cholecap_us_product_management_group__c can be (optionally) assigned to the role during its lifecycle.

Note: If the lifecycle role has not been configured with an override rule, the response will only display the default rule.

Errors

On failure, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Top

Create Override Rules

Request

Send POST to api/{version}/configuration/role_assignment_rule

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Input

Before submitting this request, prepare a JSON or CSV input file with the following information:

  • The name__v field values of the lifecycle and role to which the override rule is being added.
  • The id or name__v field values of the object records which define the override condition.
  • The user_name__v field values of the allowed and default users who will be assigned to the role when the override condition is met.
  • The name__v field values of the allowed and default groups who will be assigned to the role when the override condition is met.

Note the following scope and limitations:

  • This request can only be used to specify the override rules (conditions, users, and groups). It cannot be used to configure the default rules.
  • The input may include override rules for multiple lifecycles and roles.
  • Each role may be configured with multiple override rules.

Example CSV & JSON Input Files

Create an override rule on the editor__c role of the general_lifecycle__vs with the following override conditions, users, and groups:

lifecycle__v role__v product__v.name__v country__v.name__v allowed_users__v allowed_groups__v allowed_default_users__v allowed_default_groups__v
general_lifecycle__vs editor__c CholeCap United States "etta@veevapharm.com,finn@veevapharm.com,greg@veevapharm.com,hope@veevapharm.com" "cholecap_us_docs_group__c,cholecap_us_research_group__c,cholecap_us_compliance_group__c,cholecap_us_product_management_group__c" etta@veevapharm.com cholecap_us_docs_group__c
[
{
    "lifecycle__v": "general_lifecycle__vs",
    "role__v": "editor__c",
    "product__v.name__v": "CholeCap",
    "country__v.name__v": "United States",
    "allowed_users__v": [
        "etta@veevapharm.com",
        "finn@veevapharm.com",
        "greg@veevapharm.com",
        "hope@veevapharm.com"                
    ],
    "allowed_groups__v": [
        "cholecap_us_docs_group__c",
        "cholecap_us_research_group__c",
        "cholecap_us_compliance_group__c",
        "cholecap_us_product_management_group__c"
    ],
    "allowed_default_users__v": [
        "etta@veevapharm.com"
    ],
    "allowed_default_groups__v": [
        "cholecap_us_docs_group__c"
    ]
}
]    

To understand how and where these users and groups are being assigned, refer to the Details section of the previous request.

Example

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \
--data-binary @"C:\Vault\Override Rules\create-lifecycle-role-override-rules.json" \
https://myvault.veevavault.com/api/v12.0/configuration/role_assignment_rule

In this example:

  • The input file format is set to JSON.
  • The response format is not set and will default to JSON.
  • The path/name of the JSON input file is specified.
  • The API {version} is set to v12.0 (earliest available for this request).

Response

{
    "responseStatus": "SUCCESS",
    "data": [
        {
            "responseStatus": "SUCCESS"
        }
    ]
}

Details

For each override rule specified in the input, the response includes a SUCCESS or FAILURE message.

Errors

On failure, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Top

Update Override Rules

Request

Send PUT to api/{version}/configuration/role_assignment_rule

Headers

Input Content-Type - JSON application/json or CSV text/csv
Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Input

Before submitting this request, prepare a JSON or CSV input file. See the Create Override Rules request above for details.

Example

$ curl -X PUT -H "Authorization: {SESSION_ID}" \
-H "Content-Type: text/csv" \
--data-binary @"C:\Vault\Override Rules\update-lifecycle-role-override-rules.csv" \
https://myvault.veevavault.com/api/v12.0/configuration/role_assignment_rule

Details

For each override rule specified in the input, the response includes a SUCCESS or FAILURE message.

Errors

On failure, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Top

Delete Override Rules

Request

Send DELETE to api/{version}/configuration/role_assignment_rule

Headers

Response Accept - JSON application/json (default) or XML application/xml or CSV text/csv

Parameters

This endpoint alone will retrieve a list of all lifecycle role assignment rules (default & override) from all roles in all lifecycles in your vault.

Parameters

You must add the following parameters to the request endpoint:

  • lifecycle__v={lifecycle_name} - Include the name of the lifecycle from which to delete override rules. For example: lifecycle__v=general_lifecycle__vs
  • role__v={role_name} - Include the name of the role from which to delete override rules. For example: role__v=editor__c

This will delete ALL override rules configured on the specified lifecycle role.

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__vs&role__v=editor__c

Response

{
  "responseStatus": "SUCCESS",
  "data": {
    "rules_deleted": 2
  }
}

Details

The response above shows that two separate override rules were deleted from the lifecycle role.

If you'd rather delete only one of the override rules, you can include an additional parameter to define the specific override rule to be deleted. This is described in the next example:

Example

$ curl -X DELETE -H "Authorization: {SESSION_ID}" \
https://myvault.veevavault.com/api/v12.0/configuration/role_assignment_rule?lifecycle__v=general_lifecycle__vs&role__v=editor__c&product__v.name__v=CholeCap

For this request, assume the following:

  • There are two separate override rules configured on the editor__c role in the general_lifecycle__vs lifecycle.
  • The first override rule defines the users and groups assigned to the role when the product "CholeCap" is assigned to the document.
  • The second override rule defines the users and groups assigned to the role when the product "Nyaxa" is assigned to the document.
  • We only want to delete the first override rule.

When specifying the object records that define the override condition, you can use either the object record id value (e.g., product__v=0PR0011001) or name__v value (e.g., product__v.name__v=CholeCap via object__v.name__v lookup).

Response

{
  "responseStatus": "SUCCESS",
  "data": {
    "rules_deleted": 1
  }
}

Details

The response above shows that one override rule was deleted from the lifecycle role.

Errors

On failure, the response includes an error type and message describing the error. See the Errors table below.

History

Since v12

Top

Lifecycle Role Assignment Rule Errors

On failure, the response includes an error type and message describing the error.

Error Type Error Message Comments
INSUFFICIENT_ACCESS Insufficient privileges to perform the action : permission [{PERMISSION}] is expected. The logged-in API user does not have sufficient privileges to create the configuration data. The error message includes the name of the required permission.
METHOD_NOT_SUPPORTED Requested method [{METHOD}] not supported. Use the appropriate HTTP method: GET, POST, PUT, DELETE.
OPERATION_NOT_ALLOWED Cannot create rule for role [{LIFECYCLE}.{ROLE}] : max rules exceeds [50000]. There is a maximum of 50,000 rules that can be created per role with this request.
OPERATION_NOT_ALLOWED Multiple default users: can only define one default user for role [{LIFECYCLE}.{ROLE}]. If you specify multiple user IDs in the input for a default user role on a lifecycle which does not allow multiple users, this error is returned. The error message includes the lifecycle and role generating the error. Only one user ID may be assigned to the role.
OPERATION_NOT_ALLOWED Cannot set group to default : default groups not allowed for role [{LIFECYCLE}.{ROLE}]. If you specify a group ID in the input for a default group role which does not allow default groups, this error is returned. The error message includes the lifecycle and role generating the error. You cannot assign a group ID to the default role on this lifecycle.
OPERATION_NOT_ALLOWED Role is not modifiable : cannot modify override rules for role [{LIFECYCLE}.{ROLE}]. If you specify a role in the input which cannot be edited, this error is returned. The error message includes the lifecycle and role generating the error. You cannot create override rules for this role on this lifecycle.
INVALID_DATA Duplicate rule: rule [{FIELD_1}={VALUE_1},{FIELD_2}={VALUE_2}], etc.] exists in the input more than once. If the input contains duplicate field values, only the first instance is processed. The remaining duplicate fields are ignored.
INVALID_DATA Duplicate rule: rule [{FIELD_1}={VALUE_1},{FIELD_2}={VALUE_2}], etc.] already exists in the database. If the input contains a rule which is already configured on the specified lifecycle in Vault, this error is returned.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : no value expected since parent [{PARENT_OBJECT}] is not specified. Child objects are allowed to be in a condition only when the parent object is already in a condition.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : child record of [{PARENT_OBJECT}.{ID}] is expected. The child object record must be validated as an actual child of the selected parent. If validation fails, this error is returned.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : value does not resolve to a valid lifecycle or role. Vault performs a check of all lifecycle and role values included in the input. If a value does not resolve to a valid lifecycle or role, this error is returned. The error message includes the name of the lifecycle or role and the invalid value entered in the input. When creating override rules for a specific lifecycle and/or specific role, make sure the lifecycle value (e.g., general_lifecycle__vs and/or role value (e.g., editor__c) exists in your vault and is entered correctly in the input.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : object record ID does not resolve to a valid object [{OBJECT_RECORD}]. Vault performs a check of all object record IDs included as a condition in the input (e.g., product__v=00P2889114). If a value does not resolve to a valid object record ID, this error is returned. The error message includes the name of object record and invalid value entered in the input. When creating override rules for documents assigned a specific object record (e.g., product, country, study, etc.), you must enter the value of the object record ID (not the object record name). Make sure the object record value exists in your vault and is entered correctly in the input. Note that the object record does not need to be active.
INVALID_DATA Invalid value [{VALUE}] specified for parameter [{PARAMETER}] : object record ID does not resolve to a unique valid object [{OBJECT_RECORD}]. If the condition is used with a lookup (e.g., "product__v.name__v": "CholeCap") and there are multiple object records in the input with the same object record ID, this error is returned. The exception to this rule is that as long as the name is unique within its parent, there can be duplicate records.
INVALID_DATA Invalid values [{VALUE_1},{VALUE_2}] specified for parameter [user_list] : values do not resolve to a valid active [user]. User values in the input are validated. Each username must resolve to a valid active user in the current vault application. Duplicate users in the input are ignored. The error message includes a comma-delimited list of all users who were identified as invalid.
INVALID_DATA Invalid values [{VALUE_1},{VALUE_2}] specified for parameter [group_list] : values do not resolve to a valid active [group]. Group values in the input are validated. Each group must resolve to a valid active group in the current vault application. Duplicate groups in the input are ignored. The error message includes a comma-delimited list of all groups which were identified as invalid.

Top