# CI Maintenance API
ATTENTION
Additional authorization is required to fulfill any request.
Use in the request the header Authorization: Bearer <Personal Token>.
# Get a list of all maintenance modes
Search query ?search= works for:
- ID of the maintenance mode.
- CI identifier, which is included in the scope of the maintenance mode.
- Maintenance mode name.
- Key / value of labels.
Sorting works for all fields except:
- CI list, which fall under the scope of the maintenance mode.
- Labels dictionary.
The maintenance mode is available to a user if at least one CI from the requested mode is available.
GET /api/public/sm/v1/rsm-maintenance
# Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| sortCol | string | no | The name of the column to sort the data |
| sortDir | string | no | Values: asc / desc – sorting direction |
| page | int | no | Results page number |
| perPage | int | no | The number of results per page. Default – 1000. To get all records, you need to pass a value -1 |
| search | string | no | Search query |
# Example output model
[
{
"id": 1,
"dateStart": "2020-03-26T10:26:24.4832533+03:00",
"dateEnd": "2020-03-26T11:26:24.4834019+03:00",
"title": "First",
"configItems": [
{
"id": 18503,
"scope": "CiAndChildren",
"depth": 2,
"state": "Completed",
"dateStart": "2020-03-26T10:26:24.4838953+03:00",
"dateEnd": "2020-03-26T10:41:24.4839772+03:00"
},
{
"id": 18510,
"scope": "Ci",
"depth": -1,
"state": "Completed",
"dateStart": "2020-03-26T10:41:24.4842012+03:00",
"dateEnd": "2020-03-26T11:26:24.484203+03:00"
}
],
"labels": {
"testKey1": "testValue1",
"testKey2": "testValue2",
"testKey3": "testValue3",
"testKey4": "testValue4",
"testKey5": "testValue5"
}
},
{
"id": 2,
"dateStart": "2020-03-26T17:26:24.4843528+03:00",
"dateEnd": "2020-03-26T20:56:24.4843544+03:00",
"title": null,
"configItems": [
{
"id": 18063,
"scope": "CiAndChildren",
"depth": 3,
"state": "Pending",
"dateStart": "2020-03-26T17:26:24.4843528+03:00",
"dateEnd": "2020-03-26T20:56:24.4843544+03:00"
},
{
"id": 18511,
"scope": "Ci",
"depth": -1,
"state": "Pending",
"dateStart": "2020-03-26T17:26:24.4843528+03:00",
"dateEnd": "2020-03-26T20:56:24.4843544+03:00"
},
{
"id": 18225,
"scope": "CiAndChildren",
"depth": 2,
"state": "Pending",
"dateStart": "2020-03-26T17:26:24.4843528+03:00",
"dateEnd": "2020-03-26T20:56:24.4843544+03:00"
}
],
"labels": {}
}
]
# Response codes
| Code | Description |
|---|---|
| 200 | Request completed successfully. |
| 401 | User not authorized. |
| 403 | Not have permission to view the maintenance modes. |
| 500 | An unexpected error occurred while processing the request. |
# Get maintenance mode by ID
The maintenance mode is available to the user if at least one CI from the requested mode is available.
GET /api/public/sm/v1/rsm-maintenance/{id}
# Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | long | yes | ID maintenance mode request |
# Example output model
{
"id": 1,
"dateStart": "2020-03-26T10:56:17.2159175+03:00",
"dateEnd": "2020-03-26T11:56:17.2160476+03:00",
"title": "First",
"configItems": [
{
"id": 18503,
"scope": "CiAndChildren",
"depth": 2,
"state": "Completed",
"dateStart": "2020-03-26T10:56:17.2166328+03:00",
"dateEnd": "2020-03-26T11:11:17.2167274+03:00"
},
{
"id": 18510,
"scope": "Ci",
"depth": -1,
"state": "Completed",
"dateStart": "2020-03-26T11:11:17.2170071+03:00",
"dateEnd": "2020-03-26T11:56:17.2170094+03:00"
}
],
"labels": {
"testKey1": "testValue1",
"testKey2": "testValue2",
"testKey3": "testValue3",
"testKey4": "testValue4",
"testKey5": "testValue5"
}
}
# Response codes
| Code | Description |
|---|---|
| 200 | Request completed successfully. |
| 403 | Not have permission to view this maintenance mode. |
| 404 | Maintenance mode with id {id} not found. |
| 500 | An unexpected error occurred while processing the request. |
# Get a list of maintenance modes by filter
Search query ?search= works for:
- Maintenance mode ID.
- CI identifier, included in the scope of the maintenance mode.
- Maintenance mode name.
- Set of labels (key / value).
Sort works for all fields except:
- CI list, which fall under the scope of the maintenance mode.
- Labels dictionary.
The maintenance mode is available to the user if at least one CI from the requested mode is available.
POST /api/public/sm/v1/rsm-maintenance/filter
# Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| sortCol | string | no | The name of the column to sort the data |
| sortDir | string | no | Values: asc / desc – sorting direction |
| page | int | no | Results page number |
| perPage | int | no | The number of results per page. Default – 1000. To get all records, you need to pass a value -1 |
| search | string | no | Search query |
# Model attributes in the request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| ids | long[] | no | List of maintenance mode identifiers |
| dateStart | DateTimeFilter | no | Conditions for filtering maintenance modes by maintenance mode start date |
| dateEnd | DateTimeFilter | no | Conditions for filtering maintenance modes by maintenance mode end date |
| configItemIds | long[] | no | List of CI identifiers, for which you need to get maintenance modes |
Inside an array of a specific field, the list is combined through a logical OR. For example ids: [1,2,3] – will select entities ID 1 OR 2 OR 3.
Fields intersect each other through a logical AND. For example: ids: [1,2,3], configItemIds: [100, 200] – service modes will be obtained if they have ID 1 OR 2 OR 3, AND while the CI included in them have the ID 100 OR 200.
The fields dateStart and dateEnd take the following values:
lessThanOrEqual- less than or equal to,moreThanOrEqual- greater than or equal to,Equal- equal to.
# Example input model
{
"ids": [
1,
2,
3,
4,
5
],
"dateStart": {
"lessThanOrEqual": "2020-03-26T09:59:51.332Z"
},
"dateEnd": {
"lessThanOrEqual": "2020-03-26T09:59:51.332Z",
"moreThanOrEqual": "2020-03-26T09:59:51.332Z"
},
"configItemIds": [
18063,
17110,
18580
]
}
For an example of an output model, see Get a list of all maintenance modes.
# Response codes
| Code | Description |
|---|---|
| 200 | Request completed successfully. |
| 400 | Empty filter in request |
| 400 | Invalid data model in the request body. |
| 403 | Insufficient rights to view maintenance modes for this filter. |
| 415 | Invalid input data type. Type is required: application/json. |
| 500 | An unexpected error occurred while processing the request. |
# Create maintenance mode
POST /api/public/sm/v1/rsm-maintenance
# Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| batchValidate | bool | no | The flag for checking the rights to set the maintenance mode for all specified CIs.false (default) – the maintenance mode will be set only for those CI, which are registered in the system and available to the user. The rest of the specified CIs will be ignored.true – a check will be performed for all CI to ensure that they are registered in the system and are available to the user to set the maintenance mode. If the check fails, then the maintenance mode will not be created. |
# Model attributes in the request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| title | string | no | Maintenance mode name |
| dateStart | DateTime | yes | Conditions for filtering maintenance modes by maintenance mode start date For example: “2020-03-26T10:56:17.2159175+03:00“ |
| dateEnd | DateTime | yes | Conditions for filtering maintenance modes by maintenance mode end date |
| configItems | custom | no | Maintenance mode scope - parametric filter by CI |
| configItems:id | long | yes | CI identifier |
| configItems:scope | string | yes | Parametric filter area. Accepts values:Ci – only selected CICiAndChildren – selected CI and successors |
| configItems:depth | int | no | The length of the edges of the CI successor graph. Default -1 – all successors |
| labels | custom object | no | Object with enumeration of user labels in the format:{"x1": "y1","x2": "y2"} |
# Example input model
{
"dateStart": "2020-03-26T10:56:17.2159175+03:00",
"dateEnd": "2020-03-26T11:56:17.2159175+03:00",
"title": "Test",
"configItems": [
{
"id": 1,
"scope": "CiAndChildren",
"depth": 3
}
],
"labels": {
"x1": "y1",
"x2": "y2"
}
}
For an example of an output model, see Get maintenance mode by ID.
# Response codes
| Code | Description |
|---|---|
| 201 | Maintenance mode successfully created. |
| 400 | Query body is empty. |
| 400 | Invalid data model in the request body. |
| 400 | Maintenance mode start time is not specified. |
| 400 | The end time of the maintenance mode is not specified. |
| 400 | The list of CI that need to be assigned a maintenance mode is not specified. |
| 400 | The end time of the maintenance mode must be greater than the start time. |
| 400 | CI identifier is not specified. |
| 400 | Invalid CI identifier value. |
| 400 | Invalid value for SM graph depth. |
| 400 | The specified CI were not found or you do not have sufficient rights. |
| 401 | Failed to authorize the user. |
| 403 | Insufficient rights to create service mode. |
| 415 | Invalid input data type. Type required: application/json. |
| 500 | An unexpected error occurred while processing the request. |
ATTENTION
dateEnd parameter must be greater than the current date and time.
# Maintenance mode edit
A PUT-request completely changes the model sent by the user, with the exception of some rules for changing the scope.
PUT /api/public/sm/v1/rsm-maintenance/{id}
# Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | long | yes | ID of a maintenance request |
| batchValidate | bool | no | The flag for checking the rights to set the maintenance mode for all specified CUs.false (default) – the maintenance mode will be set only for those CIs that are registered in the system and available to the user. The rest of the given CI will be ignored.true – a check will be made for all CI to ensure that they are registered in the system and are available to the user to set the maintenance mode. If the check fails, then the maintenance mode will not be created. |
# Model attributes in the request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| title | string | no | Maintenance mode name |
| dateStart | DateTime | yes | Conditions for filtering maintenance modes by maintenance mode start date. For example: “2020-03-26T10:56:17.2159175+03:00“ |
| dateEnd | DateTime | yes | Conditions for filtering maintenance modes by maintenance mode end date. |
| configItems | custom | no | Maintenance mode scope - parametric filter by CI |
| configItems:id | long | yes | CI identifier |
| configItems:scope | string | yes | Parametric filter area. Accepts values:Ci – only selected CICiAndChildren – selected CI and successors |
| configItems:depth | int | no | The length of the edges of the CI successor graph. Default -1 – all successors |
| labels | custom object | no | Object with enumeration of user labels in the format:{"x1": "y1","x2": "y2"} |
| cancel | bool | no | true - maintenance mode will be canceled if scheduled or completed if active. |
For an example of an output model, see Get maintenance mode by ID.
# Response codes
| Code | Description |
|---|---|
| 200 | Maintenance mode changed successfully. |
| 400 | Empty request body. |
| 400 | Invalid data model in the request body. |
| 400 | Invalid maintenance mode identifier value. |
| 400 | Maintenance mode start time is not specified. |
| 400 | The end time of the maintenance mode is not specified. |
| 400 | The list of CI that need to be assigned a maintenance mode is not specified. |
| 400 | The end time of the maintenance mode must be greater than the start time. |
| 400 | CI identifier is not specified. |
| 400 | Invalid CI identifier value. |
| 400 | Invalid value for CM graph depth. |
| 400 | The specified CI were not found or you do not have sufficient rights. |
| 400 | The specified maintenance mode has already ended. You cannot complete it. |
| 400 | The specified maintenance mode has already started. You cannot cancel it. |
| 400 | The specified maintenance mode has already ended. You cannot change it. |
| 400 | The specified mode has already started, you cannot change its start time. |
| 401 | Failed to authorize the user. |
| 403 | Not have permission to edit the maintenance mode. |
| 404 | Maintenance mode with ID {id} not found. |
| 415 | Invalid input data type. Type is required: application/json. |
| 500 | An unexpected error occurred while processing the request. |
# Partial update of maintenance mode data
Only the fields that need to be changed are passed in the PATCH request. Fields equal to null will not be changed.
PATCH /api/public/sm/v1/rsm-maintenance/{id}
Request parameters and request body, as well as input and output models, see Maintenance mode edit.
# Response codes
| Code | Description |
|---|---|
| 200 | Maintenance mode has been successfully changed. |
| 400 | Empty request body. |
| 400 | Invalid data model in the request body. |
| 400 | Invalid maintenance mode identifier value. |
| 400 | The end time of the maintenance mode must be greater than the start time. |
| 400 | The CI identifier is not specified. |
| 400 | Invalid CI identifier value. |
| 400 | Invalid value for CM graph depth. |
| 400 | The specified CI were not found or you do not have sufficient rights. |
| 400 | The specified maintenance mode has already ended. You cannot complete it. |
| 400 | The specified maintenance mode has already started. You cannot cancel it. |
| 400 | The specified maintenance mode has already ended. You cannot change it. |
| 400 | The specified mode has already started, you cannot change its start time. |
| 401 | Failed to authorize the user. |
| 403 | Not have permission to edit the maintenance mode. |
| 404 | Maintenance mode with ID {id} not found. |
| 415 | Invalid input data type. Type is required: application/json. |
| 500 | An unexpected error occurred while processing the request. |