This documentation supports an earlier version of BMC Helix Operations Management.

To view the documentation for the latest version, select 23.2 from the Product version picker.

Managing time frames for event policies with REST APIs

The following section provides a list of supported endpoints and an overview about running these endpoints. Before you run an endpoint, you must authenticate yourself. For more information, see  Access and authentication for the REST API Open link

Managing time frames for event policies

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

POST /timeframes
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. Open link .

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringBodyYesName of the time frame.
scheduleStringBodyYes

Details of the time frame schedule. Time frame schedule has the following attributes:

NameDescription

Appointment time

Important

Make sure that you specify the time in the 24-hour format.

startTimeThe time when the time frame schedule begins.
endTimeThe time when the time frame schedule ends.
Recurrence pattern
recurrence

This indicates the number of times the time frame schedule will repeat. It has the following details:

  • frequency: The recurrence frequency for the time frame schedule. It has the following values:
    • One Time
    • Daily
    • Weekly
    • Monthly
  • recurrenceSchedule: The recurrence schedule for the time frame. It has the following attribute:
    • daysOfWeek: The days of the week on which the time frame schedule should repeat.

Range of reccurence

Important

Make sure that you specify the date in the DDMMYYYY format.

startDateThe start date of the time frame schedule.
endsOnThe end of time frame schedule includes the following options:
  • endDate: The end date of the time frame schedule.
  • occurrences: The number of occurrences of the time frame schedule.
  • never: An indicator to decide whether or not the time frame schedule ends.

You can specify only one of the preceding options at a time for this attribute.

Advanced Settings
timeZone

The time zone details for the time frame. It has the following attributes:

    • name: Name of the time zone.
    • offset: Offset indicates the difference in hours and minutes between a particular time zone and UTC.
descriptionStringBodyNoDescription of the time frame.

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>

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 will replace 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. Open link .

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringBodyYesName of the time frame that you want to update.
idStringBodyYesID of the time frame that you want to update.
scheduleStringBodyYes

Details of the time frame schedule. Time frame schedule has the following attributes:

NameDescription

Appointment time

Important

Make sure that you specify the time in the 24-hour format.

startTimeThe time when the time frame schedule begins.
endTimeThe time when the time frame schedule ends.
Recurrence pattern
recurrence

This indicates the number of times the time frame schedule will repeat. It has the following details:

  • frequency: The recurrence frequency for the time frame schedule. It has the following values:
    • One Time
    • Daily
    • Weekly
    • Monthly
  • recurrenceSchedule: The recurrence schedule for the time frame. It has the following attribute:
    • daysOfWeek: The days of the week on which the time frame schedule should repeat.

Range of reccurence

Important

Make sure that you specify the date in the DDMMYYYY format.

startDateThe start date of the time frame schedule.
endsOnThe end of the time frame schedule includes the following options:
  • endDate: The end date of the time frame schedule.
  • occurrences: The number of occurrences of the time frame schedule.
  • never: An indicator to decide whether or not the time frame schedule ends.

You can specify only one of the preceding options at a time for this attribute.

Advanced Settings
timeZone

The time zone details for the time frame. It has the following attributes:

    • name: Name of the time zone.
    • offset: Offset indicates the difference in hours and minutes between a particular time zone and UTC.
descriptionStringBodyNoDescription of the time frame.

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

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 will replace 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. Open link .

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringBodyYesName of the time frame that you want to update.
scheduleStringBodyYes

Details of the time frame schedule. Time frame schedule has the following attributes:

NameDescription

Appointment time

Important

Make sure that you specify the time in the 24-hour format.

startTimeThe time when the time frame schedule begins.
endTimeThe time when the time frame schedule ends.
Recurrence pattern
recurrence

This indicates the number of times the time frame schedule will repeat. It has the following details:

  • frequency: The recurrence frequency for the time frame schedule. It has the following values:
    • One Time
    • Daily
    • Weekly
    • Monthly
  • recurrenceSchedule: The recurrence schedule for the time frame. It has the following attribute:
    • daysOfWeek: The days of the week on which the time frame schedule should repeat.

Range of reccurence

Important

Make sure that you specify the date in the DDMMYYYY format.

startDateThe start date of the time frame schedule.
endsOnThe end of time frame schedule includes the following options:
  • endDate: The end date of the time frame schedule.
  • occurrences: The number of occurrences of the time frame schedule.
  • never: An indicator to decide whether or not the time frame schedule ends.

You can specify only one of the preceding options at a time for this attribute.

Advanced Settings
timeZone

The time zone details for the time frame. It has the following attributes:

    • name: Name of the time zone.
    • offset: Offset indicates the difference in hours and minutes between a particular time zone and UTC.
descriptionStringBodyNoDescription of the time frame.

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
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. Open link .

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
idStringPathYesID of the time frame that you want to delete.
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
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. Open link .

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringPathYesName of the time frame that you want to delete.
Successful responses

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

Back to top

GET  /timeframes/<TIMEFRAME_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

Parameter NameValue TypeLocated InMandatoryDescription
idStringPathYesID of the time frame for which you want to retrieve the 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/INACTIVE/EXPIRED",
    "lastRunTime": 1648452600000,
    "nextRunTime": 1648452600000
  }
}

Back to top

GET  /timeframes/<TIMEFRAME_NAME>?idType=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

Parameter NameValue TypeLocated InMandatoryDescription
nameStringPathYesName of the time frame whose details you want to retrieve.
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/INACTIVE/EXPIRED",
    "lastRunTime": 1648452600000,
    "nextRunTime": 1648452600000
  }
}

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


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. Open link .

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/INACTIVE/EXPIRED",
      "lastRunTime": 1648452600000,
      "nextRunTime": 1648452600000
    },
    {
      "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/INACTIVE/EXPIRED",
      "lastRunTime": 1648452600000,
      "nextRunTime": 1648452600000
    }
  ]
}

Back to top

Was this page helpful? Yes No Submitting... Thank you

Comments