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

This API does not support assigning software services or applications to profiles. To select which applications or software services are associated with a business hours profile, use Business calendar configuration (APM model > Business hours on the NAM Server navigation menu).

POST business calendar configuration switch

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

with parameters specified in the payload switches this functionality (business hours per application or per 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.

Note: This endpoint is only for setting the configuration. The API does not offer a way to check the state of this configuration.

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. Note that you still need to specify a dimension when disabling it.
dimension Two possible values:
  • Software service
  • Application

Example: enabling business hours

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

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. Instead of business hours by application or software service, the NAM Server reverts to standard business hours functionality.

Note that you still need to specify a dimension when disabling the functionality.

GET business calendar configuration

A GET request of the form:

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

returns information on 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 calendarSoftwareServicesNames 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 information on the specified business calendar from the specified NAM Server, including farm role.

This GET call does not return an *.ics calendar file. See below for an example of the information included in the response.

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 application Outlook to create the calendar:

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

  2. Open that file in a text editor such as notepad.

    • It will start with BEGIN:VCALENDAR and end with END:VCALENDAR, and it will include lots of formatting and other information that NAM does not need, but don't worry about that. Unnecessary information will be parsed out.
    • The calendar name is taken from the X-WR-CALNAME field. You can edit it from Business calendar configuration (APM model > Business hours on the NAM Server navigation menu).
  3. Send the entire contents of the file as the text/plain body for a
    POST https://nam-server-address:port/public/api/businesscalendar/v1
    request and send it.

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

The response shows information about the calendar added by the POST, not about any other calendar in your 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.