# Configuring Atomic Security for Objects

With Atomic Security for Objects, you can secure object [fields][1], [actions][2], [object controls][12], and [relationships][3] by individual lifecycle states or assigned roles on an object record. This grants permissions on specific fields, actions, or relationships based on user roles on the record and state of the record.

To configure Atomic Security, you must first assign an object lifecycle to the specified object. Atomic Security settings do not apply to users with a _Vault Owner_ security profile.



<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: Atomic Security is also available for documents. See <a href="/en/gr/62043/">Configuring Atomic Security for Documents</a>
.</p>
    </div>
  </div>
</div>



## How Vault Evaluates Atomic Security for Objects

Vault evaluates Atomic Security independently for object records and object fields. First, Vault evaluates <a href="/en/gr/33946/#role-assignment">object record security</a>
. For example, Vault grants a user _Edit_ permission on the record if one of the user's roles assigned to the record grants _Edit_ permission on the record. Second, Vault evaluates [object field Atomic Security][1] for every role assigned on the record for that lifecycle state. When a role is assigned on an object record, Vault includes it in the Atomic Security field evaluation, even if the role itself does not grant any permissions on the record in the lifecycle state.

Consider the following examples for the _Study Lifecycle_ in the _Active_ state:

**Default Atomic Security Example**

The _Study Name_ field has an Atomic Security default of _Edit_, and there are no role overrides configured for the field. In this situation, for any role assigned to a _Study_ record in the _Active_ state, Vault grants users _Edit_ access to the _Study Name_ field as long as the user can access the record itself.

**Role Override Example**

The _Study Name_ field has an Atomic Security default of _Edit_, and there is a role override for the _Viewer_ role that grants _Read_ access. Therefore, for users in the _Viewer_ role assigned to a _Study_ record in the _Active_ state, Vault grants _Read_ access to the _Study Name_ field due to the role override, even though the Atomic Security default is _Edit_. 

**Multiple User Roles and Overrides Example**

First, Vault evaluates <a href="/en/gr/33946/#role-assignment">object record security</a>
: Roles A, B, and C are assigned to a _Study_ record in the _Active_ state. Roles A and B grant _Read_ access to _Study_ records. Role C grants _Edit_ access to _Study_ records. User 1 is assigned to Role A (_Read_ record access) and Role B (_Read_ record access). User 2 is assigned to Role B (_Read_ record access) and Role C (_Edit_ record access). Vault grants User 1 _Read_ access to Study records because _Read_ is the highest level of object record security granted by their roles. Vault grants User 2 _Edit_ access to Study records because _Edit_ is the highest level of object record security granted by their roles. 

Second, Vault evaluates [object field Atomic Security][1]: The _Study End Date_ field has an Atomic Security default of _Read_. Role A has a role override on the _Study End Date_ field that provides _Edit_ access. Roles B and C do not have role overrides on the _Study End Date_ field. 

User 1 is assigned to Role A (_Read_ record access, _Edit_ role override) and Role B (_Read_ record access, no role override). Vault grants User 1 _Read_ access to the _Study End Date_ field even with the _Edit_ role override, because their object record security does not allow _Edit_ access on the _Study_ record.

User 2 is assigned to Role B (_Read_ record access, no role override) and Role C (_Edit_ record access, no role override). Vault grants User 1 _Read_ access to the _Study End Date_ field even though their object record security allows _Edit_ access on the _Study_ record, because they do not have a role override on the _Study End Date_ field and the default Atomic Security is _Read_. 

User 3 is assigned to Role A (_Read_ record access, _Edit_ role override) and Role C (_Edit_ record access, no role override). Vault grants User 3 _Edit_ access to the _Study End Date_ field because they have an _Edit_ role override on the _Study End Date_ field and their object record security allows _Edit_ access on the _Study_ record.

## Atomic Security for Object Types {#object-types}

Vault applies the same Atomic Security settings on [fields][1] or [actions][2] across all object types. You cannot apply Atomic Security for specific object types. For example, when setting the state behavior to _Read_ for the _Audit End Date_ on the _Campaign_ object, Vault sets that same permission across all object types for the _Audit End Date_ field. Though Vault displays a list of values for fields or actions that are relevant to a specific object type, this is for filtering purposes only.

## Configuring Atomic Security on Fields {#Atomic_Security_Fields}

Atomic Security on fields allows you to configure field-level security that varies by lifecycle state and role. Atomic Security controls which fields are editable, read-only, or hidden for object records in a given state.

You can also use Atomic Security to define a default state behavior. If the object has record-level security enabled (through <a href="/en/gr/36122/">matching</a>
 or <a href="/en/gr/25494/">custom</a>
 sharing rules), the default state behavior applies to all roles within that state. You can define overrides for certain application roles.

For example, in VeePharm's eTMF vault, the _Milestone_ object uses the _Draft_, _Baseline_, _Planned_, and _Complete_ lifecycle states. For most users, the _Actual Start_ and _Finish_ date fields are irrelevant in the _Draft_ and _Baseline_ states and are read-only in the _Planned_ and _Complete_ lifecycle states**.** To prevent users from seeing those fields, Gladys, a VeePharm _System Admin_, configures Atomic Security on the _Actual Start_ and _Finish_ date fields. With her configuration, these fields remain hidden while the records are in _Draft_ and _Baseline_ states, and become read-only in _Planned_ and _Complete_ states. Gladys configures an override on the _Planned_ state, which provides _Edit_ access to the _Actual Start_ and _Finish_ date fields for the _Study Manager_ role.

### Behavior Options

When setting a default and override behavior, you see the following options:

  * **Edit**: Allows a user to view the field label and edit the field value. This assumes the user has _Edit_ permission on the object records at the security profile level, and the object record is editable (<a href="/en/gr/33946/">Dynamic Access Control</a>
).
  * **Read**: Allows a user to view the field label and value, but not edit the value. For example, a user can see the _Therapeutic Area_ field on a _Product_ record, but cannot update the value.
  * **Hide**: The field value is never visible. When editing a record, the field label also does not appear.

### How to Set Atomic Security on Fields

To set Atomic Security on fields:

  1. Navigate to **Admin > Configuration > Object Lifecycles**. Click into a lifecycle and then into an individual state.
  2. From the **Atomic Security: Fields** section, click **Edit**.
  3. Select **Edit** (default), **Read**, or **Hide** from the **State Behavior** picklist to apply the security setting to each field.
  4. Optional: Click **+ Role Override** to add an _Application Role_ to override the state behavior. This option adds the selected role to the page. You can then select a different behavior for each action.
  5. Click **Save** to make the changes effective.

When creating a new object record, Vault does not assign a lifecycle state and role to the record. However, security settings configured on the entry state and owner role override, if defined, are automatically applied when creating a record.

### Limitations

  * Users can still search for field values hidden with Atomic Security using VQL or faceted search in the user interface. Search results will not display the field value, but a user may determine more or less accurately the value by conducting multiple searches and observing whether or not object record appears in the results. Hiding a field with Atomic Security does not prevent a user with malicious intent from guessing hidden field values.
  * Audit trails, displayed in the **Actions** menus on the object details page, do not honor Atomic Security. When hiding fields with Atomic Security, we recommend disabling the _Object Record Audit_ permission to prevent users from seeing hidden field values.

## Configuring Atomic Security for Object Controls {#object-controls}

With Atomic Security on object controls, you can granularly control whether users can see certain UI elements of an object's layout based on lifecycle state and role.

### How to Set Atomic Security on Object Controls

To set Atomic Security on fields:

  1. Navigate to **Admin** > **Configuration** > **Object Lifecycles**. Click into a lifecycle and then into an individual state.
  2. From the **Atomic Security: Controls** section, click **Edit**.
  3. Select **Read** (default) or **Hide** from the **State Behavior** picklist to apply the security setting to each control.
  4. Optional: Click **+ Role Override** to add an _Application Role_ to override the state behavior. This option adds the selected role to the page. You can then select a different behavior for each action.
  5. Click **Save** to make the changes effective.

## Configuring Atomic Security on User & System Actions {#Atomic_Security_Actions}

Atomic Security allows you to control which object actions or lifecycle actions are hidden, viewable, or executable for object records by lifecycle state and role. Settings you configure through Atomic Security cannot provide more access than a user has through the security profile. For example, Tracy Lee's security profile does not grant the _Workflow_ > _Start_ permission. If she's assigned to an application role that is granted _Execute_ permission for _Send Quality Review_,  she still cannot perform the action because it would start a workflow.

When defining Atomic Security for user actions on objects, you must first define a default access level for each lifecycle state. All roles will have that access level on object records within the state. You can then apply overrides for certain application roles. For example, in VeePharm's Quality Vault, the _Quality Event Lifecycle_ uses the _Initiated_ lifecycle state, which contains the _Send for Impact Assessment_ and _Send for Quality Review_ actions. Although VeePharm may want these actions viewable for all roles, they only want to enable those in the _Owner_ role to execute each action. To do this, a VeePharm _System Admin_, configures Atomic Security on the actions, and then sets the **State Behavior** to _View._ He then uses **Role Override** to apply the _Execute_ permission to the _Owner_ role on each action.

### Behavior Options

When setting a default and override behavior, you see the following options:

  * **Hide**: User actions do not appear in the workflow and state changes menu or the **Actions** menu.
  * **View**: User actions do not appear in the workflow and state changes menu. User actions display as _Disabled_ in the **Actions** menu from the list page. If user actions are enabled to be displayed in all actions, the user action is displayed as _Disabled_ in the **Actions** menu on the detail page.
  * **Execute**: Allows users to see and click on the action in the **Actions** menu.

### How to Set Atomic Security on User & System Actions

To set up Atomic Security on user and system actions:

  1. Navigate to **Admin > Configuration > Object Lifecycles**. Click into a lifecycle and then into an individual state.
  2. From the **Atomic Security: Actions** section, click **Edit**.
  3. Select **Execute** (default), **View**, or **Hide** from the **State Behavior** picklist to apply the security setting to each action.
  4. Optional: Click **+ Role Override** to add an _Application Role_ to override the state behavior. This option adds the selected role to the page. You can then select a different behavior for each action.
  5. Click **Save** to make the changes effective.

## Configuring Atomic Security on Active Workflow Actions {#active-workflow-actions}

Active workflow actions are options for workflow instances that are in progress, for example, _Add Participants_ and _Cancel Workflow_. By default, in Vaults that do not use Atomic Security for Objects, access to these actions is granted automatically to the workflow owner and also granted via permission sets. When you enable Atomic Security, workflow owners will continue to have access to these actions regardless of permission sets.

### Behavior Options

When setting a default and override behavior, you see the following options:

  * **Execute**: Allows users to see and click on the action.
  * **Hide**: The action is never visible to users.

### How to Set Atomic Security on Active Workflow Actions

To set up Atomic Security on active workflow actions:

  1. Navigate to **Admin > Configuration > Object Lifecycles**. Click into a lifecycle and then into an individual state.
  2. From the _Atomic Security: Active Workflow Actions_ section, click **Edit**.
  3. Select **Execute** (default) or **Hide** from the state behavior picklist to apply the security setting to each action.
  4. Optional: Click **+ Role Override** to add an _Application Role_ to override the state behavior. This option adds the selected role to the page. You can then select a different behavior for each action.
  5. Click **Save** to make the changes effective.

## Configuring Atomic Security on Relationships {#Atomic_Security_Relationships}

Atomic Security on relationships allows you to control when inbound relationships on object records or documents can be modified according to object lifecycle state and user role.

Atomic Security on relationships controls which users can relate an object record or document. For example, VeePharm's _Campaign_ object has a document field, _Budget Proposal_, which creates a relationship between a specific campaign (the object record) and a specific document. An Admin can configure Atomic Security so that only users in the _Campaign Coordinator_ role can edit this relationship (link a campaign to a budget document, or unlink it) in most lifecycle states, and even that role is prevented from editing once the record goes into _Approved_ state. Users who are not in the _Campaign Coordinator_ role will see the relationship to the budget document, but they cannot remove it or link another document through that relationship.

You can use Atomic Security to define a default state behavior for object or document relationships. When configured, all roles will have the default access on object relationships within that specific state. For example, in VeePharm's Quality Vault, once the _Complaint_ object record is in _CAPA Approval_ state, users should not assign a new _Investigation_ or delete an existing _Investigation_ related to the _Complaint_. To prevent users from adding or removing related _Investigation_ records, an Admin uses Atomic Security to set the relationships between the _Complaint_ and _Investigations_ objects to _Read_. With her configuration, the relationship is read-only while in the _CAPA Approved_ state.

### Behavior Options

When setting a default and override behavior, you see the following options:

  * **Edit**: Allows a user to edit relationships without restrictions.
  * **Read**: Relationships are read-only. Users cannot relate documents or related objects to the object record or remove an existing relationship.

### How to Enable Atomic Security on Object-to-Object Relationships

Object-to-object relationships are controlled by configuring Atomic Security on object-type fields on an object. To enable Atomic Security on object-to-object relationships:

  1. Navigate to **Admin > Configuration > Objects > [Object] > Relationships**.
  2. Select the desired object reference or parent object reference field.
  3. Click **Edit**.
  4. Select the **Secure relationship** checkbox. Note that this option is only available on object reference and parent object reference fields assigned to a lifecycle. Note that this checkbox is only selectable if the referenced object is assigned to a lifecycle.
  5. Click **Save** to make the relationship [configurable via the object's lifecycle][11].

### How to Enable Atomic Security on Document-to-Object Relationships

Document-to-object relationships are controlled by configuring Atomic Security on object-type document fields. After enabling Atomic Security on an object-type document field, Vault clears the document field when a user selects the _Create Draft_ action on a document. The document field is not cleared after a regular, non-draft version creation. This is because the _Create Draft_ action indicates you are creating a document minor version intended for  the next major version lifecycle, and the new major version should not reference the secured object record referenced by the prior major version.

To enable atomic security on object types of document field relationships:

  1. Navigate to **Admin > Configuration > Document Fields**.
  2. Click on the object type of document field.
  3. Click **Edit**.
  4. Select the **Secure based on the states and roles of the referenced object records** checkbox. Note that this checkbox is only selectable if the referenced object is assigned to a lifecycle
  5. Click **Save** to make the relationship [configurable via the object's lifecycle][11].

### How to Set Atomic Security on Relationships {#secure_inbound_relationships}

To set up Atomic Security on relationships:

  1. Navigate to **Admin > Configuration > Object Lifecycles**. Click into a lifecycle and then into an individual state.
  2. From the **Atomic Security: Relationships** section, click **Edit**.
  3. Select **Edit** (default) or **Read** from the **State Behavior** picklist to apply the security setting to each relationship.
  4. Optional: Click **+ Role Override** to add an _Application Role_ to override the state behavior. This option adds the selected role to the page. You can then select a different behavior for each action.
  5. Click **Save** to make the changes effective.

### How Vault Applies Atomic Security on Relationships

#### Atomic Security on Record-to-Record Relationships

  * When creating and saving a new record, Vault checks if the record can be saved based on the security settings. Users cannot create new records if at least one object reference refers to a record where the relationship has the _Read_ permission. On save, Vault validates each object reference field with a secured inbound relationship and displays an inline error message on object reference fields that fail validation.
  * When editing and saving a record with an object reference field that has the _Edit_ permission, Vault validates if the referenced record can be reassigned based on inbound relationship Atomic Security.
  * Users cannot inline edit an object reference field in a related list if the corresponding inbound relationship on the object has the _Read_ permission.
  * If an object record has at least one object reference field with the _Disable_ permission, the _Delete_ action is not visible to the user.

#### Atomic Security on Document-to-Record Relationships

  * Vault honors Atomic Security on relationships when editing document fields from the Doc Info page, as well as when you delete a document or document version, copy a document or object record, or edit an object reference field.
  * When you create a draft, Vault clears out relationships fields secured by Atomic Security.
  * Atomic Security on relationships will not prevent you from versioning a document.

 [1]: #Atomic_Security_Fields
 [2]: #Atomic_Security_Actions
 [3]: #Atomic_Security_Relationships
 [11]: #secure_inbound_relationships
 [12]: #object-controls