We are pleased to bring you the following additions and enhancements to Developer Portal features in 22R3. REST API features added in 22R3 only affect API v22.3, unless otherwise noted.
For issues fixed in a release, see the "Developer Features" category of the fixed issues list in Vault CDMS Help.
Release Date: October 14, 2022
The Retrieve Study Jobs API allows users retrieve recent Study Jobs, across one or more Studies, with a single request. The primary use case fo rthis API is to automate the retrieval of export file data, across many studies, for example, study data extract ZIP files. With this API, users can filter for recently finished, successful jobs (status
= completed__v
) or determine each job_id
and use it to retrieve the output file with the Retrieve Job Output File API.
Release Date: October 14, 2022
The Start Study Job API for the Study Data Extract (SDE) job now supports the new parameter, include_study_design
. The default is false
. When set to true
, Vault will include additional CSV files about the study's design in the job's output.
Release Date: October 14, 2022
With this release, Study Jobs can now show a status of Queued (queued__v
). Once a Start Study Job request is submitted, and the job doesn't immediately enter the In Progress (in_progress__v
) status, the job enters the Queued status until the job starts. There aren't any functional changes to Jobs APIs with this enhancement.
Release Date: October 14, 2022
If an API did not already have a limit for number of actions in one request, one has been applied. Open Query By ID and Close Query By ID already had a limit of 500 in place. All others now have a limit of 100 actions per request. For example, the subjects
array of Create Subjects (Casebooks) can't have more than 100 entries in it.
Release Date: October 14, 2022
This release includes the following changes to the Create Subjects/Casebooks API:
The response now includes the Vault id
.
Vault rejects requests when the study design is configured for automatic Subject numbering (by_site
for Subject ID Generation Type). To use this API, the Study must use external__v
or manual__v
for subject ID generation. We made this change because when a Study automatically generates the Subject ID, the value set by an integration (the upstream system from Vault CDMS) would eventually be changed during normal data entry.
Release Date: October 14, 2022
This release includes the following chnages to the Retrieve Events/Forms API:
The Vault id
is now included at the Event and Form levels of the response. These values match up to those in data extracts and can assist with other APIs, such as Open Query by Event ID.
The response now includes event_did_not_occur
. This is set to true
(when a CDMS site user has marked the Event as Did Not Occur) or false
. When true
, Vault also includes the event_did_not_occur_reason
. Previously, this API could return an empty "forms": []
array for varied reasons, one being that the Event was marked as Did Not Occur.
When intentionally_left_blank
is false
, the response no longer includes intentionally_left_blank_reason
. Vault will only return intentionally_left_blank_reason
when intentionally_left_blank
is true
. Prior to this release, Vault returned "intentionally_left_blank_reason": null
.
Release Date: October 14, 2022
This release includes the following changes to the Retrieve Forms (Items) API:
The response only includes the unit_value
portion when the Item is of the Unit Codelist type. Previously, Vault returned "unit_value": null
.
If an Item is part of a Lab Panel of a Form (when the study is using the CDMS Local Labs module), it can now potentially have a lab_modifier
entry in the response. This property is only present when the modifier value is non-empty. It represents a tandem operator with the main value
property in the response.For example:
...."value": "1", "unit_value": "mg", "translated_value": "0.01", "translated_unit_value": "g", "lab_modifier": "<" ...
When intentionally_left_blank
is false
, the response no longer includes intentionally_left_blank_reason
. Vault will only return intentionally_left_blank_reason
when intentionally_left_blank
is true
. Prior to this release, Vault returned "intentionally_left_blank_reason": null
.
The intentionally_left_blank
/ intentionally_left_blank_reason
at the Item level are now included in the response. An Item can be marked ILB without the entire Form being marked ILB. Like the Form level, if "intentionally_left_blank": false
, then the response omits "intentionally_left_blank_reason": null
.
For an Item of type Unit Codelist, the translated values for value
/ unit_value
are now also returned. The additional pair is tagged as translated_value
/ translated_unit_value
. If the selection on screen is the same as the study design's standard unit of the Item the additional pair will have the same values. Otherwise, they contain the calculated value / unit to the study's defined standard. Examples:
Entered on Screen (Weight field) | Response Values |
---|---|
150.2 lbs | .. "item_name": "weight", "value": "150.2", "unit_value": "lbs", "translated_value": "68.129574", "translated_unit_value": "kg",... |
68.1 kg | .. "item_name": "weight", "value": "68.1", "unit_value": "kg", "translated_value": "68.1", "translated_unit_value": "kg",... |
Release Date: October 14, 2022
This release includes the following changes to the Retrieve Coding Requests API:
The Retrieve Coding Definitions API returns two pieces of information for each definition in the Study: coding_item_definition_id
(from the id
in the Vault record), and coding_item_definition_name
(from name__v
in the Vault record). Prior to this release, one would use name__v
value for the coding_item_definition
request to Retrieve Coding Requests to get coding requests of that type. The response body returned back coding_item_definition
, but using the id
value of the definition. To make this more consistent in this API, and to align with other coding APIs, the request and response parameters are now 'coding_item_definition_id'.
The response now includes study_country
with each coding request.
The Study context values in the response (Event Group, Event, Form, etc.) now return the design Name. Prior to this release, these returned the Label instead. We made this change to align with other CDMS APIs, which also return the Name. This results in changes in response property names, such as form
is now form_name
, event
is now event_name
, etc.
The information in response body about the definition is now in line with Retrieve Coding Definitions. The previous form_status
is now form_coding_status
, since the definition has two levels of status. Each of the statuses is returned by Retrieve Coding Definitions. Values for form_coding_status
are now picklist names (e.g., active__v
, needs_dictionary__v
) instead of labels (as before). The property form_type
now returns picklist names (e.g., ae__v
, cm__v
) instead of labels, also for consistency across all APIs.