Change Requests
Retrieve a list of Change Request Templates
Returns a list of Change Request Templates including information about the states of the templates.
GET {baseUrl}/fws/api/changerequest/template/listtemplatesExample response:
[
{
"uuid": “01234567-89ab-cdef-0123-456789abcdef”,
"name": "",
"context": "STANDARD",
"active": true,
"customProperties": [
{
"name": "",
"propertyType": "TEXT",
"mandatory": true,
"options": [
"", ...
],
"multiple": true,
"orderNumber": 1
}
],
"states": [
{
"uuid": "01234567-89ab-cdef-0123-456789abcdef",
"name": "",
"approvalLabels": [
"", ...
],
"category": "NOT_STARTED",
"transitionsTo": [
{
"uuid": "01234567-89ab-cdef-0123-456789abcdef",
"requiresApproval": true
}, ...
]
}
],
"initialState": "01234567-89ab-cdef-0123-456789abcdef"
}, ...
]
Response Parameters | Possible Values |
|---|---|
context | NONE, STANDARD, STUDY, CONTAINER, STANDARD_ASSET, STUDY_ASSET, ASSET |
category | NOT_STARTED, COMPLETED, WILL_NOT_DO, IN_REVIEW, IN_PROGRESS, DRAFT |
propertyType | TEXT, NOTE, NUMBER, DATETIME, SELECT, URL |
initialState is an optional field that is returned if populated in the ryze UI. options, multiple and orderNumber are optional fields in the customPropertiesand are returned depending on configuration in ryze.
Errors:
See Common Errors
Create a Change Request
Creates a new Change Request if the template ID specified both exists and is active. Any container AIDs or asset AIDs specified are checked for existence before being created. Any specified custom properties are checked against the change request template.
POST {baseUrl}/fws/api/changerequest
{
"templateID": "01234567-89ab-cdef-0123-456789abcdef",
"title": "",
"description": "",
"dueDate": "ccyymmddThhmmssZ",
"containerAIDs": [
"01234567-89ab-cdef-0123-456789abcdef", ...
],
"assets": [
{
"containerAID": "01234567-89ab-cdef-0123-456789abcdef",
"assetAID": "01234567-89ab-cdef-0123-456789abcdef"
}, ...
],
"customProperties": [
{
"name": "",
"values": ["", ...],
"propertyType": "TEXT",
"mandatory": true,
"orderNumber": 1
}, ...
]
}
Request Parameters | Values |
|---|---|
dueDate | [Optional] |
containers | [Optional] |
assets | [Optional] |
customProperties | [Optional] |
dueDate | [Optional] |
assetAID | [Optional] |
‘propertyType’ | TEXT, NOTE, NUMBER, DATETIME, SELECT, URL |
The context set on the Change Request Template (NONE, STANDARD, STUDY, CONTAINER, STANDARD_ASSET, STUDY_ASSET, ASSET) impacts which properties should be sent when creating the Change Request. If request includes properties that are not permitted within the context, an invalid_context_details error is returned.
The Change Request Template is configured in ryze, Admin > Repository > Change Requests.
If the context is NONE, then it is expected that there will be no assets or containers specified in the request. If the context is CONTAINER and the user has chosen to supply containerAIDs, then there must be no assets specified.
If the context is set to STANDARD or STUDY, then those containers must be of that container type.
If the context is ASSETS and the user chooses to supply assets, then both the assets field and the containerAIDs fields must be populated. The containerAIDs and the containerAID fields in the assets field must match. If the context is set to STANDARD_ASSET or STUDY_ASSET, then the assets specified in the request must be from one of those container types.
Example response:
{
"id": "CR-0"
}Related requests: Retrieve a list of Change Request Templates
Errors:
HTTP Status | Error Code |
|
|---|---|---|
400 | invalid_template_id | Badly formatted templateID. |
404 | unknown_template | Template not found for templateID. |
400 | template_inactive | Template not activated. |
400 | change_request_custom_properties_invalid | Invalid custom properties for template. |
400 | invalid_container_aid | Badly formatted container AID. |
404 | unknown_container | Container not found for AID. |
400 | invalid_asset_aid | Badly formatted asset AID. |
400 | invalid_context_details | Incorrect container or asset details for Template Context. |
404 | unknown_asset | Asset not found for AID. |
See also Common Errors
Retrieve Change Request Details
Retrieve the details of a Change Request with the specified ID.
GET {baseUrl}/fws/api/changerequest/:id{
"id":"CR-1",
"title": "",
"description": "",
"created": “ccyymmddThhmmssZ”,
"dueDate": “ccyymmddThhmmssZ”,
"customProperties": [
{
"name": "",
"values": ["", ...],
"propertyType": "TEXT",
"mandatory": true,
"orderNumber": 1
}, ...
],
"updated": “ccyymmddThhmmssZ”,
"templateID": "01234567-89ab-cdef-0123-456789abcdef",
"templateName": "",
"templateContext": "STANDARD",
"stateID": "01234567-89ab-cdef-0123-456789abcdef",
"stateName": "",
"stateCategory": "NOT_STARTED",
"approvers": [
{
"label": "",
"username": "",
"isApproved": true
}, ...
],
"owner": "",
"assignee": "",
"containers": [
{
"aid": "01234567-89ab-cdef-0123-456789abcdef",
"label": "",
"version": 1,
"containerType": "STANDARD"
}, ...
],
"assets": [
{
"container": {
"aid": "01234567-89ab-cdef-0123-456789abcdef",
"label": "",
"version": 1,
"containerType": "STANDARD"
},
"asset": {
"aid": "01234567-89ab-cdef-0123-456789abcdef",
"assetType": "FORM",
"label": ""
}
}, ...
],
"completedVersions": [
{
"container": {
"aid": "01234567-89ab-cdef-0123-456789abcdef",
"label": "",
"version": 1,mand
"containerType": "STANDARD"
},
"asset": {
"aid": "01234567-89ab-cdef-0123-456789abcdef",
"assetType": "FORM",
"label": ""
}
}, ...
],
"comments": [
{
"uuid": "01234567-89ab-cdef-0123-456789abcdef",
"username": "",
"at": “ccyymmddThhmmssZ”,
"comment": ""
}, ...
],
“fileReferences”: [
{
“uuid”: “01234567-89ab-cdef-0123-456789abcdef”,
“path”: “”
}, …
]
}
Request Parameters | Accepted Values |
|---|---|
propertyType | TEXT, NOTE, NUMBER, DATETIME, SELECT, URL |
templateContext | NONE, STANDARD, STUDY, CONTAINER, STANDARD_ASSET, STUDY_ASSET, ASSET |
stateCategory | NOT_STARTED, COMPLETED, WILL_NOT_DO, IN_REVIEW, IN_PROGRESS, DRAFT |
containerType | STANDARD, STUDY |
assetType | VISIT_SCHEDULE, VISIT, FORM, SECTION, QUESTION, CONDITION, METHOD, UNIT, DATASET, VARIABLE, VALUE, SELECTION_CRITERIA, RESULT_DISPLAY, ANALYSIS_RESULT, TERMINOLOGY, TERM, COMMENT, FILE, LINK |
dueDate | [Optional] |
updated | [Optional] |
templateID | [Optional] |
templateName | [Optional] |
templateContext | [Optional] |
stateID | [Optional] |
stateName | [Optional] |
stateCategory | [Optional] |
assignee | [Optional] |
customProperties > mandatory | [Optional] |
assets > asset | [Optional] |
completedVersions > asset | [Optional] |
comments > username | [Optional] |
When creating a change request and sending container information, only a container AID is specified. When retrieving a change request, theT container information received contains the AID and the latest version for that container.
Errors:
HTTP Status | Error Code |
|
|---|---|---|
404 | unknown_change_request | Change request not found for specified id. |
404 | change_request_deleted | Change request is in a deleted state. |
See also Common Errors
Add Approver to Change Request State Transition
PUT {baseUrl}/fws/api/changerequest/:crID/approver/:crsUUID/:label/:userUUIDRequest Parameters | Accepted Values |
|---|---|
crID | Change Request ID |
crsUUID | Change Request State ID |
label | Label of Change Request State for user to be added as |
userUUID | UUID of the user being added |
Add a user with the specified UUID as a Change Request State Transition approver for the specified label.
{}Related requests: List Users
Errors:
HTTP Status | Error Code |
|
|---|---|---|
404 | unknown_change_request | Change Request Not Found for crID. |
404 | change_request_deleted | Change request has been deleted. |
400 | invalid_change_request_state_uuid | Change Request State crsUUID Invalid format. |
404 | unknown_change_request_state | Change Request State not found for crsUUID. |
400 | invalid_approval_label | Invalid label for specified change request state transition. |
400 | invalid_user_id | Invalid format for userUUID. |
404 | unknown_user | User not found for given userUUID. |
See also Common Errors
Remove Approver from Change Request State Transition
Remove a User with the specified UUID from a Change Request State Transition for the specified label.
DELETE {baseUrl}/fws/api/changerequest/:crID/approver/:crsUUID/:label/:userUUIDRequest Parameters | Accepted Values |
|---|---|
crID | Change Request ID |
crsUUID | Change Request State ID |
label | Label of Change Request State for user to be added as |
userUUID | UUID of the user being added |
{}Related requests: List Users
Errors:
HTTP Status | Error Code |
|
|---|---|---|
404 | unknown_change_request | Change Request Not Found for crID. |
404 | change_request_deleted | Change request has been deleted. |
400 | invalid_change_request_state_uuid | Change Request State crsUUID Invalid format. |
404 | unknown_change_request_state | Change request state not found for crsUUID. |
400 | invalid_approval_label | Invalid label for specified Change Request State Transition. |
400 | invalid_user_id | Invalid format for the userUUID. |
404 | unknown_user | User not found for the specified userUUID. |
404 | approver_not_assigned | User doesn’t exist on Change Request as an approver. |
400 | change_request_already_approved | Trying to remove a user that has already approved change request transition. |
See also Common Errors
Delete a Change Request
Delete a Change Request with the specified ID.
DELETE {baseUrl}/fws/api/changerequest/:crID
{}Related requests:
Errors:
HTTP Status | Error Code |
|
|---|---|---|
404 | unknown_change_request | Change Request Not Found for id. |
See also Common Errors
Transition Change Request State
Transitions the Change Request to the Change Request state with the specified state UUID. Will validate that both the change request and the change request state for the specified IDs exist before transitioning.
PUT {baseUrl}/fws/api/changerequest/:crID/transition/:crsUUID{}Errors:
HTTP Status | Error Code |
|
|---|---|---|
404 | unknown_change_request | Change Request Not Found for crID. |
400 | invalid_change_request_state_uuid | Change Request State crsUUID invalid format. |
404 | change_request_deleted | Change request has been deleted. |
404 | unknown_change_request_state | Change request state not found for crsUUID. |
See also Common Errors
Approve a Change Request State Transition
Transitions the Change Request to the Change Request state with the specified state UUID. Will validate that both the change request and the change request state for the specified IDs exist before transitioning.
PUT {baseUrl}/fws/api/changerequest/:crID/approve/:label/:userID{}Related requests: List Users
Errors:
HTTP Status | Error Code |
|
|---|---|---|
404 | unknown_change_request | Change Request not found for specified crID. |
400 | invalid_user_id | userID is Invalid Format. |
404 | change_request_deleted | Change request has been deleted. |
404 | unknown_user | User not found for specified userID. |
400 | invalid_user | User is either not enabled or awaiting activation. |
400 | invalid_approval_label | Invalid label for specified change request transition. |
400 | approver_not_assigned | User trying to be approved is not assigned. |
See also Common Errors
Associate an uploaded file to a change request
PUT {baseUrl}/fws/api/changerequest/:crID/file
Allows the user to associate a previously uploaded file (Add a temporary file) to the change request with the supplied crID. The uuid and path supplied in the request will be the same values as the ‘Add a temporary file’ call
{
"uuid": "01234567-89ab-cdef-0123-456789abcdef",
"path": ""
}
{
"uuid": "01234567-89ab-cdef-0123-456789abcdef",
"path": ""
}Related requests: Add a temporary file
Errors:
HTTP Status | Error Code |
|
|---|---|---|
400 | invalid_file_id_format | The id passed in the request isn’t a valid UUID. |
404 | unknown_change_request | Change request not found for specified id. |
404 | unknown_file | Can’t find previously uploaded file. |
404 | change_request_deleted | Change Request has been deleted. |
See also Common Errors
Request a change request files download
Allows the user to request the preparation of files associated with a change request for download. Where crID is the change request and fileID is the file associated with that change request.
GET {baseUrl}/fws/api/changerequest/:crID/file/:fileID
{
"uuid": "01234567-89ab-cdef-0123-456789abcdef"
}Related requests:
Errors:
HTTP Status | Error Code |
|
|---|---|---|
404 | unknown_change_request | Change request not found for specified crID. |
400 | invalid_file_id | fileID not correct format. |
404 | unknown_file | File not found for fileID specified. |
404 | change_request_deleted | Change request has been deleted. |
See also Common Errors
Update a Change request
Allows a user to update a change request with the specified ID.
PUT {baseUrl}/fws/api/changerequest/:crID{
"title": "",
"description": "",
"dueDate": "ccyymmddThhmmssZ",
"containerAIDs": [
"", ...
],
"assets": [
{
"containerAID": "",
"assetAID": ""
}, ...
],
"customProperties": [
{
"name": "",
"values": ["", ...],
"propertyType": "NUMBER",
"mandatory": true,
"orderNumber": 1
}, ...
],
"completedVersions": [
{
"container": {
"aid": "",
"version": 1
},
"asset": {
"aid": ""
}
}, ...
]
}
Request Parameters | Accepted Values |
|---|---|
propertyType | TEXT, NOTE, NUMBER, DATETIME, SELECT, URL |
assets | [Optional] |
customProperties | [Optional] |
completedVersions | [Optional] |
If title, description or dueDate are omitted, their previous value is retained. If assets are supplied, then they must specify a containerAID but an assetAID is optional. If completedVersions are supplied, then a container must be specified but the asset is optional.
{
}Errors:
HTTP Status | Error Code |
|
|---|---|---|
404 | unknown_change_request | Change request not found for id. |
404 | unknown_template | Template not found for change request. |
400 | invalid_context_details | Incorrect details specified for change request template. |
400 | change_request_custom_properties_invalid | Custom properties are invalid for template. |
400 | invalid_container_aid | Container AID wrong format. |
404 | unknown_container | Container not found for AID. |
400 | invalid_asset_aid | Asset AID wrong format. |
404 | unknown_asset | Asset not found for AID. |
404 | change_request_deleted | Change Request has been deleted. |
See also Common Errors
