This documentation supports an earlier version of BMC Helix Operations Management.To view the documentation for the latest version, select 23.3 from the Product version picker.

Time frame management endpoints in the REST API

Use the following endpoints to manage time frames for event policies.

Related topic

Setting-event-policy-schedules-by-using-time-frames

Before you begin

Before you run an endpoint, you must authenticate yourself. For more information, see Access and authentication for the REST API.

Time frames for event policies

You can create, update, delete, and get details of time frames for event policies by running APIs.

POST /timeframes
Create a time frame
Request URL
 https://<BMC Helix Portal URL>/timeframe-service/api/v1.0/timeframes
Example request URL
 https://HostA.bmc.com/timeframe-service/api/v1.0/timeframes
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API..

Parameter details


Request body

{
 "name": "String",
 "schedule": "String",
 "description": "String"
}

Example request body

{
 "name": "skip weekends",
 "description": "skip weekends",
 "schedule": {
   "startTime": "16:49",
   "endTime": "16:51",
   "startDate": "19042022",
   "endsOn": {
     "endDate": "19052022"
   },
   "recurrence": {
     "frequency": "daily",
     "recurrenceSchedule": {
       "days": "all"
     }
   },
   "timeZone": {
     "name": "Asia/Kolkata",
     "offset": "+05:30"
   }
 }
}


Successful response

{
 "message": "[Successfully created timeframe.]",
 "object": {
   "id": "[68f1c644-3594-11ec-9a65-3515b2f79aad]"
 }
}

Unsuccessful responses

Scenario 1: You specify an invalid end date for the time frame.

{
 "message": "End date is empty or not valid in Timeframe.",
 "errorCode": "INVALID_TIMEFRAME_END_DATE"
}

Scenario 2: You specify an invalid or empty frequency value for the time frame.

{
 "message": "Recurrence repeat or frequency is empty or not valid in Timeframe.",
 "errorCode": "INVALID_TIMEFRAME_FREQUENCY"
}

Scenario 3: You specify a time frame name that already exists.

{
 "message": "Failed to create timeframe entry, entry with same name already exists for tenant 936425861.",
 "errorCode": "TIMEFRAME_ALREADY_EXIST"
}

Back to top

PUT /timeframes/<TIMEFRAME_ID>
Update a time frame based on timeframe ID

When you update a time frame, you can add or remove values from the time frame by sending the entire time frame request payload with the required values. To learn more about the request payload, see Example request body.

This update replaces the existing time frame definition similar to overwriting changes in a file.

Request URL
https://<BMC Helix Portal URL>/timeframe-service/api/v1.0/timeframes/<TIMEFRAME_ID>
Example request URL
https://HostA.bmc.com/timeframe-service/api/v1.0/timeframes/7bcb273e-cc3f-11ec-b865-75ecc7784575
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API..

Parameter details

Request body

{
 "name": "String",
 "schedule": "String",
 "description": "String"
}

Example request body 

{
 "name": "skip weekends",
 "description": "skip weekends",
 "schedule": {
   "startTime": "16:49",
   "endTime": "16:51",
   "startDate": "19042022",
   "endsOn": {
     "endDate": "19052022"
   },
   "recurrence": {
     "frequency": "weekly",
     "recurrenceSchedule": {
       "daysOfWeek": [
         2,
         3,
         4
        ]
     }
   },
   "timeZone": {
     "name": "Asia/Kolkata",
     "offset": "+05:30"
   }
 }
}

Successful response

{
 "message": "Successfully updated timeframe.",
 "object": {
   "id": "7bcb273e-cc3f-11ec-b865-75ecc7784575"
 }
}

Unsuccessful responses 

Scenario: You attempt to update a time frame that does not exist.

{
   "message": "No timeframe entry found for name testTimeframe.",
   "errorCode": "404"
}

Back to top

PUT /timeframes/<TIMEFRAME_NAME>?idType=name
Update a time frame based on time frame name

When you update a time frame, you can add or remove values from the time frame by sending the entire time frame request payload with the required values. To learn more about the request payload, see Example request body.

This update replaces the existing time frame definition similar to overwriting changes in a file.

Request URL
https://<BMC Helix Portal URL>/timeframe-service/api/v1.0/timeframes/<TIMEFRAME_NAME>?idType=name
Example request URL
 https://HostA.bmc.com/timeframe-service/api/v1.0/timeframes/skip weekends?idType=name
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API..

Parameter details

Request body

{
 "name": "String",
 "schedule": "String",
 "description": "String"
}

Example request body 

{
 "name": "skip weekends",
 "description": "skip weekends",
 "schedule": {
   "startTime": "16:49",
   "endTime": "16:51",
   "startDate": "19042022",
   "endsOn": {
     "endDate": "19052022"
   },
   "recurrence": {
     "frequency": "weekly",
     "recurrenceSchedule": {
       "daysOfWeek": [
         2,
         3,
         4
        ]
     }
   },
   "timeZone": {
     "name": "Asia/Kolkata",
     "offset": "+05:30"
   }
 }
}

Successful response

{
 "message": "Successfully updated timeframe.",
 "object": {
   "id": "7bcb273e-cc3f-11ec-b865-75ecc7784575"
 }
}

Unsuccessful responses 

Scenario: You attempt to update a time frame that does not exist.

{
 "message": "No timeframe entry found for name testTimeframe.",
 "errorCode": "404"
}

Back to top

DELETE  /timeframes/id
Delete a time frame by time frame ID
Request URL
 https://<BMC Helix Portal URL>/timeframe-service/api/v1.0/timeframes/id
Example request URL
https://HostA.bmc.com/timeframe-service/api/v1.0/timeframes/82a25453-cca1-11ec-9337-895a5a87b4db
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API..

Parameter details

Successful responses

{
 "message": "Successfully deleted timeframe.",
 "object": {
   "id": "82a25453-cca1-11ec-9337-895a5a87b4db"
 }
}

Unsuccessful response

Scenario 1: You specify an invalid time frame ID.

{
 "message": "Timeframe id is not valid UUID.",
 "errorCode": "INVALID_TIMEFRAME_ID"
}

Scenario 2:  You specify a time frame ID that does not exist.

{
 "message": "Failed to delete timeframe entry, entry with 74d1ee1f-3982-11ed-b8ff-ab7ae057bcc1 not exist for tenant 936425861.",
 "errorCode": "TIMEFRAME_ENTRY_DOES_NOT_EXIST"
}

Back to top

DELETE  /timeframes/<TIMEFRAME_NAME>?idType=name
Delete a time frame by time frame name
Request URL
 https://<BMC Helix Portal URL>/timeframe-service/api/v1.0/timeframes/<TIMEFRAME_NAME>?idType=name
Example request URL
https://HostA.bmc.com/timeframe-service/api/v1.0/timeframes/Exclude weekends?idType=name
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API..

Parameter details

Successful responses

{
 "message": "Successfully deleted timeframe.",
 "object": {
   "id": "82a25453-cca1-11ec-9337-895a5a87b4db"
 }
}

Back to top

GET  /timeframes/<TIMEFRAME_ID>
Get time frame details by time frame ID
Request URL
 https://<BMC Helix Portal URL>/timeframe-service/api/v1.0/timeframes/<TIMEFRAME_ID>
Example request URL
https://HostA.bmc.com/timeframe-service/api/v1.0/timeframes/68f1c644-3594-11ec-9a65-3515b2f79aad
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameter details

Successful response

{
 "message": "Timeframe entry found.",
 "object": {
   "id": "68f1c644-3594-11ec-9a65-3515b2f79aad",
   "name": "Exclude weekends",
   "description": "EPS",
   "schedule": {
     "startTime": "16:49",
     "endTime": "16:51",
     "startDate": "19042022",
     "endsOn": {
       "endDate": "19052022"
     },
     "recurrence": {
       "frequency": "daily",
       "recurrenceSchedule": {
         "days": "all"
       }
     },
     "timeZone": {
       "name": "Asia/Kolkata",
       "offset": "+05:30"
     }
   },
   "status": "ACTIVE",
   "lastRunTime": 1648452600000,
   "nextRunTime": 1648452600000
 }
}

The status parameter can have one of the following values:

  • ACTIVE
  • INACTIVE
  • EXPIRED

Back to top

GET  /timeframes/<TIMEFRAME_NAME>?idType=name
Get time frame details by time frame name
Request URL
 https://<BMC Helix Portal URL>/timeframe-service/api/v1.0/timeframes/<TIMEFRAME_NAME>?idType=name
Example request URL
https://HostA.bmc.com/timeframe-service/api/v1.0/timeframes/Exclude weekends?idType=name
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameter details

Successful response

{
 "message": "Timeframe entry found.",
 "object": {
   "id": "68f1c644-3594-11ec-9a65-3515b2f79aad",
   "name": "Exclude weekends",
   "description": "EPS",
   "schedule": {
     "startTime": "16:49",
     "endTime": "16:51",
     "startDate": "19042022",
     "endsOn": {
       "endDate": "19052022"
     },
     "recurrence": {
       "frequency": "daily",
       "recurrenceSchedule": {
         "days": "all"
       }
     },
     "timeZone": {
       "name": "Asia/Kolkata",
       "offset": "+05:30"
     }
   },
   "status": "ACTIVE",
   "lastRunTime": 1648452600000,
   "nextRunTime": 1648452600000
 }
}

The status parameter can have one of the following values:

  • ACTIVE
  • INACTIVE
  • EXPIRED

Unsuccessful response

Scenario: You specify a time frame name that does not exist.

{
 "message": "No timeframe entry found for name testTimeframe.",
 "errorCode": "404"
}

Back to top

GET  /timeframes
Get details of all time frames


Request URL
https://<BMC Helix Portal URL>/timeframe-service/api/v1.0/timeframes
Example URL
https://HostA.bmc.com/timeframe-service/api/v1.0/timeframes
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API..

Successful response

{
 "message": "[Successfully found timeframes]",
 "object": [
   {
     "id": "68f1c644-3594-11ec-9a65-3515b2f79aad",
     "name": "Exclude weekends",
     "description": "EPS",
     "schedule": {
       "startTime": "16:49",
       "endTime": "16:51",
       "startDate": "19042022",
       "endsOn": {
         "endDate": "19052022"
       },
       "recurrence": {
         "frequency": "daily",
         "recurrenceSchedule": {
           "days": "all"
         }
       },
       "timeZone": {
         "name": "Asia/Kolkata",
         "offset": "+05:30"
       }
     },
     "status": "ACTIVE",
     "lastRunTime": 1648452600000,
     "nextRunTime": 1648452600000
   },
   {
     "id": "68f1c644-3594-11ec-9a65-3515b2f79aae",
     "name": "Weekly time frame",
     "description": "EPS",
     "schedule": {
       "startTime": "16:49",
       "endTime": "16:51",
       "startDate": "19042022",
       "endsOn": {
         "endDate": "19052022"
       },
       "recurrence": {
         "frequency": "daily",
         "recurrenceSchedule": {
           "days": "all"
         }
       },
       "timeZone": {
         "name": "Asia/Kolkata",
         "offset": "+05:30"
       }
     },
     "status": "INACTIVE",
     "lastRunTime": 1648452600000,
     "nextRunTime": 1648452600000
   }
  ]
}

The status parameter can have one of the following values:

  • ACTIVE
  • INACTIVE
  • EXPIRED

Back to top

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*