Developer Features in 24R1

We are pleased to bring you the following additions and enhancements to Developer Portal features in 24R1. REST API features added in 24R1 only affect API v24.1, unless otherwise noted.

Service Announcements

External URL Reverse IP Lookup Change

Release Date: 23R3.4; February 9, 2024

External URL jobs are now sent from an IP address associated with Veeva Vault. Organizations who are currently allowinglisting by domain must update their rules to support the *.veevavault.com domains.

HVO Renamed to Raw with New One Billion Record Limit

Release Date: 23R3.2; December 8, 2023

High volume objects are now called raw objects. As we look to increase the scalability of our standard objects, we will begin treating high volume objects more like regular database tables, used for storing raw data. To make the purpose of these objects clearer, we are updating the terminology across our user and developer documentation and in the Vault UI and API, referring to this class of objects instead as raw objects.

There is now a limit of one billion records for raw objects. In addition, the data_store attribute for the Object MDL component now includes a value of raw. This change is backward compatible, and high_volume is still supported as an input value.

Merge Records API

Release Date: 23R3.4; February 9, 2024

Duplicate records in Vault can happen due to migrations, integrations, or day-to-day activities. These duplicate records can be difficult to correct because of the many ways an object record can be referenced. For example, an object record may be referenced in both configuration and document and record relationships.

This feature allows developers with the Application: Object: Merge Records permission to merge two records using main_record_id and duplicate_record_id into a single record on Objects where the new setting, Enable Merges is turned on. All inbound references from the Duplicate record, including attachments, will be updated to the Main record. Field values on the Main record are not changed, and when the process is complete, the Duplicate record is deleted. SDK record triggers are not invoked during this process.

POST /api/{version}/vobjects/{object_name}/actions/merge

Developers can also use Vault Java SDK to invoke a merge records operation action using the RecordMergeRequest interface, and may also create Record Merge Event Handlers which can define custom logic for merging records. Only one event handler is allowed per object.

You can only initiate record merges through the Vault API or the Vault Java SDK, and you can learn more about the Vault configuration required for merging records in Vault Help.

23R3.4

Release Date: 23R3.4; February 9, 2024

REST API v24.1

Bulk Rendition Operations

As a result of a configuration change or migration project, there may be a need to re-render a substantial amount of documents. This new endpoint accepts a CSV file with document IDs to initiate a bulk re-render operation.

POST /api/{version}/objects/documents/batch/actions/rerender

End Session Endpoint

This new REST API endpoint ends a Vault session. This allows integrations to end the Vault session instead of letting the session expire. If a user has more than one active session, ending one session does not affect the user’s other sessions. For example, ending a user’s API session will not affect their active UI sessions.

DELETE /api/{version}/session

View this endpoint in the v24.1 REST API Reference.

REST API: Read and Delete Annotations

In this release, some existing REST APIs have changed by appending /file to the existing endpoint:

The new Read Annotations by Document Version and Type API endpoint will return annotations as JSON, and allow users to paginate results and filter annotations by type using optional query parameters, such as annotation_types, limit, offset, and pagination_id:

GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations

The above API also returns the Annotation ID id__sys, which can be directly called using the new Read Annotations by ID API endpoint:

GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations/{annotation_id}

Developers may also get replies to a specific Annotation ID using the Read Replies by Parent ID endpoint, and use optional parameters limit, offset, and pagination_id:

GET /api/{version}/objects/documents/{doc_id}/versions/{major_version}/{minor_version}/annotations/{annotation_id}/replies

The last update of this feature is the Delete Annotations endpoint, which can be used to delete annotations in a batch by providing document_id__v, major_version__v, major_version__v, and annotation_id__v as nodes in a JSON payload:

DELETE /api/{version}/objects/documents/annotations/batch

Warnings and Errors Message in API Usage Logs

API Usage Logs will now include error and warning messages that appear in the CSV file output. New columns will include api_response_warning_message and api_response_error_message.

Additionally, the X-VaultAPI-ReferenceId header will be included in the API Usage Logs with column reference_id.

These columns are included when downloaded using the Vault UI or API v24.1+.

Workflow Initiators Select Task Assignment Type

Vault now allows workflow initiators to select whether a task is assigned to Any or Every participant in a participant control of a workflow start step. This choice is enabled when configuring a workflow task and is stored in the MDL of the workflow component as the following XML tag <vwf:assignmentType type="runtimeChoice" />.

When using the Vault REST API to start a workflow where workflow initiators can select the assignment type, the system will expect a value of assigned (assigned to all users) or available (available to any user) for the {participant_group}.assignment_type__c body parameter.

Learn more about starting a workflow with the Vault REST API.

Action Layouts: Additional Improvements

Users can now create up to 50 custom layouts per Object - Object Type Pair, regardless of how many system or standard layouts there are. The previous limit was 20 custom layouts.

Clinical: EDL Override: Automation, Template Hierarchy, and Usability Enhancements

A new REST API endpoint will be made available to generate Milestone Documents in bulk. The endpoint will accept a CSV file of up to 500 records.

POST /api/{version}/app/clinical/milestone/actions/generatemilestonedocuments

VQL

SDK Job Enhancements: VQL for SDK Jobs

To allow better control over SDK jobs, developers can now use the job_instance__sys VQL query target to find a running job and retrieve the job status and other job metadata.

Learn more about querying job instances.

Document Attachments

VQL queries can now access document attachment metadata via the attachments__sysr relationship. Developers must query attachments as subqueries in the SELECT or WHERE clauses. Document attachment subqueries support the ALLVERSIONS option.

Learn more about querying document attachments.

TOLABEL

In VQL, the TOLABEL() function will return the localized label of referenced components for the lifecycle states and picklist values of standard volume objects. Raw objects (formerly high volume objects) are not currently supported.

With this function, developers no longer need to convert and match name values to labels with a separate API call or hard-coded dictionary. This allows the API call to retrieve user-facing values in a single step.

Learn more about the TOLABEL() function.

Vault Java SDK

Document Lifecycle Services SDK

This feature introduces Document Lifecycle Services to the Vault Java SDK to retrieve configuration metadata about document lifecycles and lifecycle user actions. It also provides methods to execute user actions and state changes on documents.

Learn more about Document Lifecycle Services.

Vault Java SDK: New capabilities for Annotations

Vault Java SDK will now support creating and editing text annotations using coordinates.

When retrieving annotations via SDK, it will also include Modified by User (modified_by_user_sys) and Modified Date Time (modified_date_time_sys) fields. The values of fields will default to Created By and Created Date information when the last modified information does not exist for an annotation.

Learn more about Annotation Services.

SDK Job Enhancements: Cancel SDK Jobs

Developers can now cancel an SDK job using the cancelJob() method in the Vault Java SDK. Custom SDK code can only cancel custom SDK jobs. This can be used to avoid multiple async jobs running at the same time, which could lead to inaccurate results.

SDK Job Enhancements: Job Task Retry

Developers can now retry a JobTask during SDK job execution using the setRetry(Boolean retry) method. Tasks can only be retried up to five (5) times, and the SDK must be annotated as idempotent=true. This feature can be used to increase the resilience of code in case of temporary errors, such as thread lock conflict or unavailable system resources.

SDK Job Enhancements: Retrieve Job Owner

Developers can now get the owner(s) of a job or the initiating user of a one-time job using the getJobOwner() method. This function can be used to alert the job owner about the status of the job.

The returned JobOwner provides two methods: getId() to retrieve the user or group ID getType() to determine whether the owner is a user or a group

Vault Java SDK: Record Service Enhancements

This feature enables developers to change the object type of a record as well as to save a record in migration mode via the Java SDK Record Service.

Two optional methods are added to RecordBatchSaveRequest.Builder:

If migrationMode is set to true, the system will allow the creation or update of object records in any lifecycle state or state type. Additionally, Vault bypasses entry criteria, entry actions, validation rules, event actions, and reference constraints when creating or updating records in migration mode.

User Object: Trigger Support

Vault now supports SDK record triggers on the user__sys object. Record triggers are only invoked when changes are made directly to the user__sys object on the Vault. Triggers on the user__sys object are not invoked for domain attribute updates (such as first name or last name) originating from other Vaults.

Learn more about user triggers.

Action Layouts: Summary Fields

The 23R3.4 extension of the Action Layouts feature will introduce Summary Fields which will be accessible for Object and Objecttype components via MDL using the summary_fields attribute. Learn more about Object and Objecttype components.

For SDK, the summary_fields attribute can be obtained using the getSummaryFields() method for both the ObjectMetadata and ObjectTypeMetadata interfaces.

Learn more in the javadocs.

MDL

Enhanced Dashboards Tab

The Dashboard component type now includes the tags attribute, which returns a list of tags associated with the Dashboard.

Learn more about Dashboard components.

Reusable Labels for Document Field Layouts

Vault will no longer enforce the uniqueness of the label attribute of Docfieldlayout components. Uniqueness will still be enforced on the name.

Learn more about Docfieldlayout components.

Layout Rule: Display As Read-Only Effect

Admins can now configure Layout Rules to display fields as read-only. This feature adds a new displayed_as_readonly_fields attribute, which accepts a comma-separated list of field names, to the Layoutrule component.

Learn more about Layoutrule components.

Validation Management: Printable View for Test Scripts

With 24R1, Vault Validation Management will provide a way to generate a printable view of a test script that will include related object records and evidence collected from executors, such as screenshots, that are stored as test step file attachments. With the introduction of printable views, a new Printableviewtestscript component type will be available via MDL. The component references two files as attributes: template (XML) and header_logo (*.png, *.jpg, *.jpeg, *.bmp, *.gif, *.svg, *.tif, *.tiff).

Quality Team Related Object Security dynamically adds a user to a specific role on a related object if that related object is an identified object associated with a Quality Team-enabled object. This feature allows Quality Team members to dynamically edit or delete records associated with a Quality Team-enabled process in a secure and scalable way and restricts modification of the records if they are not part of the parent Quality Team.

This feature uses the Qualityteam component type’s new subcomponent, Qualityteamrelatedobjectsecurity, together with the new Appsecurityrule component type. These can be used to configure Related Object Security via the MDL API and to transfer the configuration using Vault Deployment Packages (VPK).

External Notifications Enhancements: Multiple Recipients and Add Document from Library

Organizations often use External Notifications to correspond with stakeholders outside their companies about product complaints through email. This correspondence often involves multiple people identified on a Complaint record, like the initial reporter, the complainant, and healthcare providers.

Prior to this release, users were required to initiate one External Notification for each Person identified on a record. With the 24R1 release, Admins can configure an External Notification that allows users to send one email to multiple Persons on a record.

To support this functionality, this feature adds a new Qualityexternalnotificationtemplate Component Type to all Quality Vaults with QMS enabled.

Quality Incidents: Create a Quality Incident from a QR Code (QMS)

Vault QMS enables users to create Quality Incident records that capture information known at the time the incident is encountered, and includes a lightweight process that allows the appropriate individuals to triage the incident and determine if a full-fledged quality event process is necessary. System administrators can now configure QR codes to be printed and placed anywhere employees or contractors work. Vault QMS users can scan QR codes with their mobile device’s camera to fill out a streamlined page that collects required information about the incident they encountered.

This new feature introduces a new Qualityincidentintakelayout Component Type for MDL.

23R3.2

Release Date: 23R3.2; December 8, 2023

REST API v24.1

Non-consecutive Document IDs

When documents are created, Vault automatically assigns a document ID (note, this is different from Document Number). With v24.1, we are making changes to how Document IDs are generated to support future functionality - these changes will result in document IDs consistently not being sequential numbers.

There were already scenarios where Document IDs may not be sequential (i.e. due to document deletions), but these changes in v24.1 will result in Document IDs never being sequential.

Customers should assess any existing integrations if the Document ID is being used as a basis for document sequence. We do not recommend that the Document ID field be used as a means of identifying document creation order, but rather recommend the use of Document Number.

New Object Audit Fields in CSV Exports and API

The object audit API (CSV and JSON) and data exports from the Vault UI (CSV) now include new fields that display the API names for fields, objects, new values, and old values. The affected endpoints are:

GET /api/{version}/vobjects/{object_name}/{object_record_id}/audittrail

GET /api/{version}/audittrail/object_audit_trail

These new fields make it easier to join audit data with other Vault data and to perform additional analysis of audit data in external systems. This feature is automatically part of API v24.1.

Action Layouts: Layout Profiles

Admins can now configure Layout Profiles that can define what Layouts are available to users on object records. With this enhancement, as new Layouts are configured on objects, customers can also assign what each user should see by default and what additional layouts should be available to them to switch between.

In API v24.1, when using the Create Object Records or Update Object Records endpoints to create or update Users, a new standard field called layout_profile__sys will be available.

POST /api/{version}/vobjects/{object_name}

PUT /api/{version}/vobjects/{object_name}

This feature adds the new Layoutprofile component type to all Vaults.

Action Layouts: Layout Pages

Admins can now optionally configure up to 10 separate Pages in a Layout. Pages contain sections to allow for grouping them into more focused displays so that users can navigate between each Page based on the context and work to be done. By default, all existing layouts will remain unchanged, but the user interface for the left-hand navigation will appear slightly cleaner, and users will have the option to minimize the menu, allowing for a full-screen view.

In API v24.1, the Retrieve Page Layout Metadata endpoint will now include information (Label, Name, and Section) on any configured Pages, if more than one exists in a given layout. In addition, the Retrieve Page Layouts and Retrieve Page Layout Metadata endpoints will include additional information (such as Description, Status, Default, and Display Lifecycle Stages).

GET /api/{version}/metadata/vobjects/{object_name}/page_layouts

GET /api/{version}/metadata/vobjects/{object_name}/page_layouts/{layout_name}

This feature adds the following attributes to the Pagelayout component type:

Action Layouts: Layout Rules Enhancement

To further enable the flexibility in these Layout changes, we have also enhanced Layout Rules.

Layout Rules are applied to each Layout and any Layout Pages within, but with the introduction of Layout Pages, rules can now be defined to hide or show Views and Pages within Layouts. Additionally, a new Layout Selection Rule is available called Focus On, which allows Admins to define criteria for overriding a default Layout.

There is also a new Display as Required option, which allows fields to be displayed as required fields based on the Layout Rule Expression - this can reduce the potential for users to encounter Entry Criteria errors by ensuring that fields display as required in the right circumstances.

In API v24.1, the Retrieve Page Layout Metadata endpoint will now include additional layout rule information, such as hiding view and pages, requiring field input and displaying view as selected.

GET /api/{version}/metadata/vobjects/{object_name}/page_layouts/{layout_name}

This feature adds the following attributes to the Layoutrule component type:

Reference ID for Vault API

X-VaultAPI-ReferenceId is a new API header that is defined by the client application calling the Vault API. When using API v23.3+, and the API request includes a value for this header, Vault API will return the value in the API response and include it in the API usage logs when downloaded using Vault API v23.3+ or from the Vault Admin UI.

Binder Limits

Vault now has clearly documented and enforced limits for Vault Binders to ensure good binder performance. Customers and Veeva services will be able to use binders in a predictable and easy to understand way. For all API versions, the following limits now apply to binders:

These limits will apply to the following endpoints for all API versions:

POST /api/{version}/objects/binders/templates/{template_name}/bindernodes

POST /api/{version}/objects/binders/{binder_id}/documents

POST /api/{version}/objects/binders/{binder_id}/sections

PUT /api/{version}/objects/binders/templates

If a customer has binders currently that are over any of these limits, the Veeva Account Team will be reaching out directly.

Document Templates Limit

Vault now has clearly documented and enforced limits for Basic and Controlled Document Templates to ensure reliable document template performance.

These limits will apply to the following endpoints for all API versions:

POST /api/{version}/objects/documents/templates

PUT /api/{version}/objects/{documents_or_binders}/{id}/versions/{major_version}/{minor_version}/lifecycle_actions/{name__v}

If a customer has binders currently that are over any of these limits, the Veeva Account Team will be reaching out directly.

Workflow REST API Error Type Updates for Adding Participants

When using the Initiate Workflow Action endpoint to add participants or reassign tasks, if the workflow is configured to use either the Use Role as Participants or Use Custom Action to Define Participants option on participant controls, the API now returns an INVALID_DATA error type if the attempted action is not consistent with the participant control settings.

Vault Java SDK

Enhancements to Query Field Type

Field rules now allow using a different SELECT field than the Query field in the field rule. This will be used by app developers/customers to get required field value without overloading the Query Field.

To achieve this, we’re introducing a new Query Field Select attribute (query_field_select).

The attribute will be recommended on Field Rules used in Vault to Vault Connections, but will not be required for field rules on local or external connections.

EDL SDK: Manual Matching of Documents

To support customers who use EDL manual matching, we are introducing an SDK interface to enable the manual matching and unmatching of documents to EDL Items. In comparison, the API can be used to manually add, remove, lock, and unlock documents from EDL Items, but it does not support excluding and including automatically matched documents.

The EDL service provides methods to perform the following actions for manual matching:

Vault Java SDK: Object Metadata Service Enhancements

This feature enhances the SDK Object Metadata Service in the following ways:

Retrieve Vault Domain Name

A new method, getDomain(), is now available in the VaultInformation interface that can be used to retrieve the domain name for a given Vault.

MDL

Duplicate Check: Check Lifecycle State Processing Enhancement

In support of new changes to the Record Check: Duplicate Checks feature set, the Qualityrecordcheck component has a new attribute, lifecycle_states_to_not_transition. This optional attribute is only applicable to Duplicate Check types of Record Checks. Setting this attribute to a list of one or more lifecycle states shall prevent instances of the Qualityrecordcheck from performing lifecycle state transitions on matched records in one of those states.

Notification Categories & Email Preferences

Admins can now specify a notification category for each notification template. Admins can also now define the frequency of notifications Vault sends by email. A frequency of Never treats the notification like an in-app notification only. The Notificationtemplate component has two new attributes to support this: notification_category and email_preferences.