NAM Server REST API - Business calendar

Applies to NAM 2019 Service Pack 1

Use these REST requests to manage NAM Server business hours functionality through the API.

Important
  • You can't POST or PUT calendars to a NAM Server with Business calendar mode set to Standard business hours. You first have to enable the functionality and select the dimension with a POST configure business calendar request.
  • You can't POST or PUT changes to the selection of applications or software services associated with a calendar. This API is intended only for managing calendars (not business hours profiles) and enabling or disabling the functionality. Open APM model > Business hours from the NAM Server navigation menu to select which applications or software services are associated with a business hours profile.

POST business calendar configure

To begin business calendar configuration through the API, send a POST request to enable the functionality and select the dimension.

A request of the form:

POST https://nam-server-address:port/public/api/businesscalendar/v1/configure

switches this functionality (business hours per application or software service) on or off for the specified NAM Server and selects the dimension (Software service or Application), depending on the contents of the application/json body of the request.

Field Description
enabled Boolean.
  • true enables custom business calendar functionality on the specified NAM Server, where the dimension is specified by dimension.
  • false disables custom business calendar functionality on the specified NAM Server.
dimension Two possible values:
  • Software service
  • Application

Example: enabling business hours per software service

To enable business hours per software service on the NAM Server, issue a POST request of the form

POST https://nam-server-address:port/public/api/businesscalendar/v1/configure

with the request body (application/json)

{
"enabled": true,
"dimension": "Software service"
}

Example: disabling business hours per software service

A call to

POST https://nam-server-address:port/public/api/businesscalendar/v1/configure

with a request body (application/json) of

{
"enabled": false,
"dimension": "Software service"
}

disables this functionality on the NAM Server. Note that you still need to specify a dimension when disabling it.

GET business calendar configuration

A GET request of the form:

GET https://nam-server-address:port/public/api/businesscalendar/v1

returns this NAM Server's business calendar configuration, including the business hours default profile and all defined custom calendars.

Example response for no custom calendar

In this example, no custom calendar defined. The response shows the default settings only (under standardBHConfiguration) as they might be defined through the NAM Server Business calendar configuration page (on the NAM Server navigation menu, select APM model > Business hours) in the Default profile section.

Example response after a custom calendar is added

This is the response after a custom calendar has been added. The new settings (under test-business-calendar-mode-01) are followed by the same default settings from the previous example (under standardBHConfiguration).

GET business calendars with associated names

A GET request of the form:

GET https://nam-server-address:port/public/api/businesscalendar/v1/withNames

gets all business calendars from the specified NAM Server, like a call to:

GET https://nam-server-address:port/public/api/businesscalendar/v1/

but the withNames option adds the names of the associated applications or software services to the response in subsections calendarSoftwareServices and calendarApplicationsNames.

For example, three applications and five software services are associated with the calendar in the following example section of a response to the withNames call.

Whether the business hours defined by the calendar actually apply to those applications or those software services depends on the business calendar mode of that NAM Server. Use POST business calendar configure to enable or disable a business calendar mode and choose the dimension.

GET specified business calendar

A GET request of the form:

GET https://nam-server-address:port/public/api/businesscalendar/v1/{calendar-name}

gets the specified business calendar from the specified NAM Server. You can use it for custom calendars and the default business hours calendar.

Example

From our previous example request

GET https://nam-server-address:port/public/api/businesscalendar/v1

we know that we have a calendar named Profile Alfa.

A call to

GET https://nam-server-address:port/public/api/businesscalendar/v1/Profile Alfa

with that calendar name appended to the request returns the settings for just the Profile Alfa calendar.

POST business calendar

A POST request of the form:

POST https://nam-server-address:port/public/api/businesscalendar/v1

adds a business calendar to the specified NAM Server, where the calendar is specified as a text/plain payload containing the plain text contents of the ICS-format file defining a calendar. Existing calendars are not overwritten.

Example using third-party applications Outlook (to create the calendar) and Postman (to send the request):

  1. In Outlook, save a calendar as an *.ics file.

  2. Open that file in a text editor such as notepad. It may include lots of formatting and other information that NAM does not need, but don't worry about that.

  3. Copy the entire contents of the file to the clipboard.

  4. Paste the entire contents into Postman as a text/plain body for a POST https://nam-server-address:port/public/api/businesscalendar/v1 request and send it.

  5. NAM parses the calendar for the information it needs, ignores the rest, and returns the calendar information in the request response.

The response shows only the calendar added by the POST, not the entire business calendar configuration.

PUT specified business calendar

A PUT request of the form:

PUT https://nam-server-address:port/public/api/businesscalendar/v1/{calendar-name}

puts the specified business calendar to the specified NAM Server, overwriting the calendar settings for any existing calendar with that name.

Specify the calendar settings as a text/plain payload containing the plain text contents of the ICS-format file defining a calendar.

DELETE business calendar configuration

A DELETE request of the form:

DELETE https://nam-server-address:port/public/api/businesscalendar/v1

deletes all custom business calendars from the specified NAM Server, leaving only the default business hours calendar as they might be defined through the NAM Server Business calendar configuration page (Default profile).

DELETE specified business calendar

A DELETE request of the form:

DELETE https://nam-server-address:port/public/api/businesscalendar/v1/{calendar-name}

deletes the specified business calendar from the specified NAM Server and returns the deleted calendar definition in the response.

HEAD business calendar configuration

A HEAD request of the form:

HEAD https://nam-server-address:port/public/api/businesscalendar/v1

returns the status of this NAM Server's business calendar configuration and the timestamp of the last change.