We are pleased to bring you the following additions and enhancements to Developer Portal features in 23R2. REST API features added in 23R2 only affect API v23.2, unless otherwise noted.
Release Date: 23R2; August 2023
In 23R2, Vault will enable support for the HTTP/2 protocol. Developers can choose to use HTTP/2, but upgrading is not required.
Before Vault begins supporting HTTP/2, developers should evaluate existing integrations that might be designed to auto-upgrade their HTTP protocol for compatibility with HTTP/2. For example, HTTP/2 returns all API headers as lowercase, which may be an issue if an existing integration is expecting case-sensitive header values.
Release Date: June 9, 2023
Customers often need to bulk reclassify due to large scale changes to document types. Developers now have the ability to bulk reclassify the latest version of documents using the new Reclassify Multiple Documents endpoint. This will also support future reference model changes for Vault eTMF customers, who might require the reclassification of existing documents.
PUT /api/{version}/objects/documents/batch/actions/reclassify
With this change, the new endpoint and the existing Reclassify Document endpoint will also support migration mode. Migration mode allows users to set the document status and document number while reclassifying. The maximum batch size for bulk reclassification is 500 documents.
In Vault QMS, the majority of record or work access and assignments are managed through Quality Teams. You can learn more about all of the functions available with Quality Teams in Vault Help. Prior to this release, team assignments have been supported only in the UI of Vault QMS due to the highly controlled, often process-specific nature work assignments. This further implies that some operations, such as role changes in integrated systems, or work reassignments needed when an individual changes roles or leaves a company can be time consuming as they must be done through the vault UI on a record-by-record basis. In this release, we’re introducing public APIs to allow organizations to manage assignments within Quality Teams.
POST /app/quality/qms/teams/vobjects/{object_name}/actions/manageassignments
This new, bulk-enabled endpoint can accept a text or CSV file which describes the desired operations, including the addition or removal of users from team roles on records of the {object_name} specified in the endpoint URL. The endpoint returns a job ID, allowing for the user to retrieve the job status. The actual team assignment updates are performed asynchronously by the system on behalf of the user, and in this initial release, respect Quality Team specific configurations which impact business logic such as:
Vault notifies the invoking user of the results of the call upon completion.
This release introduces a new API endpoint called Execute Milestone Story Event. This feature is designed to support milestone creation for migrated records while minimizing system downtime and managing system performance. It includes a parameter to capture the object to be acted upon and accepts an optional VOF-standard idParam input to define alternative unique IDs.
POST /api/{version}/app/clinical/milestone/{object_name}/actions/applytemplate
The data input for this feature will be in CSV format, supporting a maximum of 500 data rows, plus a header row. Each row in the CSV input will define one object record ID, for which milestones will be created, and a single Story Event record to define what milestones will be created. All record IDs and Story Events must point to an active record at the same level as the {object_name} path parameter. This is particularly useful when a record is migrated into Vault in an advanced lifecycle state by providing an option to create any milestones that would normally be created by lifecycle state entry actions.
A series of synchronous validation checks will execute at runtime before any jobs are scheduled in Vault. If any validation checks fail, an error message is provided and no jobs are initiated or scheduled.
For every row in the CSV file, Vault will initiate a unique Create Milestones from Template job according to the story_event__v. As jobs complete, the API will return a success or failure result and job ID for each row.
Vault Admins can now see whether daily API Usage Logs contain Success, Failures, and Warnings. This allows Vault Admins to quickly inspect their Vault API usage and know if they need to download the log for further investigation. Insights are only available for API calls made after the release of 23R2.
A new response header, X-VaultAPI-Status, reflects the value of responseStatus in the JSON/XML response returned by Vault API and is intended for external reporting use cases. This new header is returned only in API v23.2+.
Vault now supports querying object attachment metadata, including file version, filename, and MD5 checksum. Attachments are supported as subqueries on objects in the SELECT and WHERE clauses. Querying object attachments is supported on objects with attachments enabled and is not supported on objects with “Use Action security to control Attachments” enabled.
Workflow queries now support retrieving the workflow configuration version (workflow_definition_version__sys). Additionally, workflow task queries now support retrieving the Completed By field (completed_by__sys) and Participant Group field (participant_group__sys). These fields are available for both active workflows and workflow tasks (active_worklow__sys and active_workflow_task__sys) and inactive workflows and workflow tasks (inactive_workflow__sys and inactive_workflow_task__sys).
Admins can now configure how text and number field values should be displayed in Vault using format masks. This enhancement supports use cases for capturing phone numbers in text fields and percentages in number fields.
In API v23.2, Query Describe in VQL includes a format_mask attribute for text and number fields. A new VQL function, TODISPLAYFORMAT(), returns the formatted value of text fields, number fields, formula fields (where the return type is Text or Number), and lookup fields (that are looking up text or number field values). This function is not supported in WHERE clauses. By default, queries that do not use this function return the raw field value.
The Vault Java SDK returns the raw field value.
SDK and VQL developers can now query all job history and related SDK job tasks by accessing new query targets: job_history__sys and job_task__sys.
Job history queries support filtering on:
Job task history queries support filtering on:
Query Describe now includes the VQL function name when X-VaultAPI-DescribeQuery=true and the SELECT clause applies a function to a field. This shows developers that VQL has transformed the return data.
With v23.1.3, the Vault Java SDK RecordWorkflowAction now supports document workflow actions (workflows on the envelope__sys object). Additionally, all workflow types now support record workflow actions on the start step and task step.
To support both object and document workflows, we’ve made changes to the workflow package in the Vault Java SDK. For example, in RecordWorkflowActionContext we’ve deprecated getRecords() for a new getWorkflowItems() method, and added two new interfaces for WorkflowItemDocument and WorkflowItemRecord.
This enhancement will enable customers to use custom actions to automate business processes.
With v23.1.3, the Vault Java SDK now includes a WorkflowActionService to retrieve configuration metadata of workflows and information about workflow instances, as well as methods to execute actions on active workflows. These include:
getWorkflowStartMetadata()getWorkflowInstances()getWorkflowStartRequirements()getAvailableWorkflows()startWorkflow()cancelWorkflow()getWorkflowParticipants()getWorkflowItems()getWorkflowItems()This enhancement is not applicable to legacy Document Workflows.
This feature introduces Object Lifecycle Services to the Vault Java SDK. These include:
ObjectLifecycleMetadataServiceObjectLifecycleStateUserActionMetadataServiceObjectLifecycleStateUserActionServiceThese services, which are located in the new lifecycle package, allow developers to retrieve configuration metadata of object lifecycles and actions, retrieve lifecycle information about object records, and execute user actions.
RecordService now supports setting object reference fields using any unique fields on the referring object. Previously, developers were limited to using the ID field.
This new service provides comprehensive access to field-type specific metadata for object fields. For example, developers can retrieve the maximum length for text fields and the minimum or maximum value for number fields.
Developers can now retrieve the Vault DNS, name, and ID of a remote Vault using an active Vault to Vault connection. This allows developers to construct notifications that guide a user to a remote Vault. Local and external Connections are not supported.
With v23.1.3, the Vault Java SDK Query Service now enforces limits on search terms to ensure optimal performance:
For API v23.2, the 250 character limit on individual search terms also applies. The API already enforces a limit of 50,000 characters on a given API call. Learn more about Query Service.
When a user updates a record that executes an SDK trigger, Vault now logs “[SDK User] on behalf of [Current User]” in the audit trail to show that the change was automatic based on the user’s action. Prior to 23R2, the audit trail would show that the user performed the SDK action.
For example, prior to 23R2, the audit trail would show “user@vault.com” performed the action, and with 23R2, the audit trail shows “System on behalf of user@vault.com”.
To maintain Vault performance, User Exception Messages (exception_message__sys) and User Exception Items (exception_item__sys) have been migrated to HVO Objects and no longer support faceting in Vault UI. Additionally, records that have been marked as inactive or are older than 180 days will be purged from Vault on a nightly basis. Customers who wish to retain this data for longer periods are encouraged to use Scheduled Data Exports or Vault Loader to extract the data for storage outside of Vault.
When creating SDK debug logs, Vault Admins and developers can now select additional options including Log Level and Class Filters. This allows for more granular control over what information is included in the logs and helps prevent hitting log limits when debugging. Log Level selection is inclusive of lower levels; for example, when the log level is set to WARN, debug logs will include warnings, errors, and exceptions. The default log level value is ALL. When Class Filters are applied, Vault will only capture log events from the selected class.The maximum number of class filters allowed is 10.
For this release, QualityOne introduces a new Vault Java SDK entry point that allows users to process incoming information when Vault receives an email and its attachments from external parties using the Automated COA Email Intake feature. After processing the incoming email’s information, the email intake feature creates the applicable COA Inspection records based on how developers customize the SDK entry point.
This enhancement introduces the new designer_layout attribute to the Checklistype component type. This attribute stores the component reference to the Layout record. For each checklist type, there is one Layout record that stores the fields that users will see in the Visual Checklist Designer.
Release Date: May 5, 2023
Vault will now only update object records if any changes have been made. Prior to this release, if a record was saved without any changes being made, it would count as an update. As a result, all record update related transactions would occur, such as updating the Last Modified Date, creating an audit trail entry, and firing SDK record triggers. In 23R1.2, these transactions will no longer occur for no-change saves.
With API v23.2 or later, if an API call to upsert or update records results in no changes, the API response will include a warning of either No changes in values - record not updated (for single records) or No changes in values - one or more records not updated (for multiple records). In this case, the record’s Last Modified Date is not changed (v23.2 or later), SDK record triggers do not execute (all versions), and Vault does not create an event in the Object Record Audit History (all versions).
If an SDK code to update records results in no changes, the SDK Runtime Log will include a warning of No changes in values - one or more records not updated. The record’s Last Modified Date is not changed, SDK record triggers do not execute, and Vault does not create an event in the Object Record Audit History.
This feature adds a new attribute, override_checkout_state_change, to the Changestatejobaction component. When true, this attribute allows a job configured with a document state change action to proceed even when a minor version of the document is checked out. This functionality is only available when the configured Current State is the lifecyle’s configured steady state type and the destination_state is the lifecycle’s configured obsolete state type.
This feature allows API users to filter individual object record and document audit trails by specific events. To filter by event, add the new events query parameter to the existing Audit History endpoints.
In this release, we’ve improved rendition generation performance when calling the Create Single Document endpoint many times in a row. For the best performance, it is good practice to use the Create Multiple Documents endpoint if you need to create more than 100 documents at once.
Starting with v23.2, the Create Single Document endpoint will return WARNING instead of SUCCESS if it is used to create more than 100 documents at once.
In this release, non-unique object field headers are blocked from being used in the following areas:
Prior to this release, non-unique headers were being ignored and failing silently. Going forward, these will be blocked and the API response will indicate FAILURE with details on which headers should be made unique.
Vault Loader Command Line users can now leverage Record Migration Mode to update and upsert records to any state while bypassing reference constraints, validation rules, entry actions, and entry criteria.
Learn more about using Record Migration Mode with the Vault Loader Command Line in Vault Help.
With v23.2, the EDL API endpoints are enabled in RIM and RegulatoryOne Vaults by default. Prior to this release, some customers needed to contact Veeva Support to enable these endpoints in RIM and RegulatoryOne Vaults.
Admins using the Upload Document Annotations and Upload Document Version Annotations endpoints will now see character limits enforced by Vault.
POST /api/{version}/objects/documents/{doc_id}/annotations
POST /api/{version}/objects/documents/{doc_id}/versions/{major_version}/
{minor_version}/annotations
The limits will vary depending upon the type of annotation:
For items that exceed the limits when leveraging these endpoints, Vault automatically truncates the values to the associated limit.
A new method, getName, has been added to the Picklist and PicklistValue interfaces. This allows developers access to the API name of the picklist or picklist value.
Learn more in the Javadocs.
This feature introduces a new method, getJobName, to the JobContext interface. This method allows SDK developers to retrieve the corresponding SDK job name.
Learn more in the Javadocs.
Developers can now set the Job Owner for ad hoc (non-scheduled) SDK Jobs. The owner can be set to either the INITIATING_USER or the REQUEST_OWNER. This allows developers to control how the custom code for the SDK Job will execute.
Learn more in the Javadocs.
Vault now generates a new logtype, SYSWRN, when a system-level warning occurs (for example, Intelligent Record Update warnings). These log entries will be included in active SDK Debug Logs and will be included in the SDK Runtime Logs when the log-level is set to WARN.
When evaluating field rules using IntegrationRuleService#evaluateFieldRules, if the field rule configures a reference lookup and a default value, Vault now returns the default value instead of an error when there is no match in the reference lookup. We encourage developers to review their code and configuration to ensure their field rules are evaluated properly.
VQL now enforces a limit of five (5) queries per user per Vault for concurrent execution and processing. VQL will throttle additional query requests until existing queries have completed. This change applies to all API versions.
Learn more about query performance and VQL transaction limits.