Service Announcements: The following upcoming changes affect all versions of the API.

[X]

Developer Features in 18R1

We are pleased to bring you the following additions and enhancements to Developer Portal features in 18R1. REST API features added in 18R1 only affect API v18.1, unless otherwise noted. You can learn more about the 18R1 Release in Vault Help.

Removal of Weaker TLS Ciphers

Beginning in 18R1.3 (June 1, 2018), we will remove support for 1024 bit Diffie-Hellman ciphers and TLS v1.0 and will only support Elliptic Curve and TLS v1.2. To ensure your integrations continue working with Vault API, you must ensure that the technology you use to build and run integrations support strong ciphers.

Developer Release Notes on the Developer Portal

As of 18R1, we are now publishing the Developer Release notes here on the Developer Portal instead of on Vault Help. Past release information is still available on Vault Help, and can be accessed through the Past Releases page.

REST API v18.1

User & Person Object

Release Date: 17R3.5, March 2, 2018

In this release, Vault users are now represented as objects. The User (user__sys) object contains records of all existing Vault users, enabling customers to report on user data, create custom fields, and reference users from documents or objects with lookup fields and reference constraints. The Person (person__sys) object allows both Vault users and non-users to be in a single object. When referencing a user from a Person record, Vault synchronizes the standard fields from both records.

API users can leverage existing Vault object API endpoints to add existing domain users to a vault, create new users, and add or update users in bulk. API users can also update Person records. Note that when API users create, add, or update User object records, Vault also synchronizes those changes with the domain user across all vaults to which that user is a member. This includes cross-domain vaults.

Updates to Object Record Responses

References to users have always appeared as object references with a number as an id value in the response. References to objects, such as product__v, appear as a String type for the id. In v18.1, references to user__sys are returned as a String type. In all versions prior to V18.1, references to users and new references to user__sys will continue to appear as numbers.

Updates Object Metadata Responses

Starting in v18.1, references to user__sys will return user_sys as the object name with relationship information. Any fields referencing users (not user__sys) will continue to return the the name users as the object name.

In versions prior to v18.1, references to user__sys will return with users as when retrieving metadata on any object with a user reference.

Controlled Document Templates

Release Date: 17R3.4, February 9, 2018

In API v18.1, users can create and manage Controlled Document Templates using existing API endpoints. Controlled Document Templates are not supported in previous API versions.

The existing Bulk Create Document Templates endpoint can create Controlled Document Templates.

The existing Bulk Update Document Templates endpoint can update Controlled Document Templates, or convert existing basic templates to Controlled Document Templates.

Direct deletion of Controlled Document Templates via API is not supported. Users can indirectly delete a Controlled Document Template by deleting the document or version referenced by the template.

Expose API Usage Logs

Release Date: 17R3.4, February 9, 2018

Admin users can now access daily API usage logs. Users with the new Admin > Logs > API Usage permission can access these logs via the UI and API.

The required date query parameter allows you to get the log from a specific day within the last 30 days. The file is available as a CSV by default, but you can also request a logfile with log_format=logfile.

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

Enhanced Reports Tab

Release Date: 17R3.4, February 9, 2018

With the migration of reports to objects, API users can now read all visible report fields on the report_sys object. Hidden fields that contain a report’s filters and related queries are not included.

New Query Parameters for Domain endpoint

Release Date: 17R3.4, February 9, 2018

As of API v18.1, Domain Information API response will omit the vault_application__v field from each of Vault JSON objects by default. This will greatly improve the response time of this API. If you want this data, you can set the new query parameter include_application to true.

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

User API exclude query parameters

Release Date: 17R3.3, January 12, 2018

In v17.3, we added two new query parameters to the /users endpoints:

These parameters are false by default in v17.3 and below, and true by default in v18.1 and above. This means the following endpoints will now exclude vault_membership and app_licensing information by default:

View these endpoints in the REST API v18.1 Reference.

Rendition Types on Subtype & Classification

Release Date: 17R3.3, January 12, 2018

Since the Control for Rendition Types on Subtype & Classification feature, Admins can set renditions at the subtype and classification level. The Retrieve Document Subtype and Retrieve Document Classification APIs now return this rendition information in v18.1.

VQL

Formula Fields

Release Date: 17R3.4, February 9, 2018

In 17R3.4, we introduced Formula Fields. Formulas are evaluated during runtime, which means the fields are not stored and are not searchable. They cannot be used with VQL FIND, ORDER BY, WHERE clauses. If there is an error calculating a formula, VQL will return null for the field value.

User Object References

Release Date: 17R3.5, March 2, 2018

When including new references to user__sys in VQL queries, you must use API v18.1 or later.

Known Issues

Configuration Migration

Issue affected 17R3.4, February 9, 2018. Issue fixed in 17R3.5, March 2, 2018

The Import Package and Retrieve Package Deploy Results responses changed in all versions of the API. If you currently have an integration with either of these endpoints where you rely on the structure of the response, your integration may break. In 17R3.5 (March 2, 2018), this change will only affect v18.1 and all other versions will return to normal.

PUT /api/{version}/services/package

GET /api/{version}/vobject/vault_package__v/{package_id}/actions/deploy/results

To fix your integration, you need to view the new structure of the response and adjust your integration accordingly. When we fix this issue in 17R3.5, you can either return to your old integration code or upgrade your version to v18.1.