# CI Maintenance API

ATTENTION

Additional authorization is required to fulfill any request.

Use in the request the header Authorization: Bearer <Personal Token>.

Where can I get a 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.

# 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 CI
CiAndChildren – 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 CI
CiAndChildren – 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.