Create rosters

This endpoint is used to create partner-level or client-level rosters.

Leave Feedback

URL

POST https://{api-url}/api/v2/tenants/{tenantId}/rosters

Sample URLs

For partner-level rosters:

https://{api-url}/api/v2/tenants/msp_5/rosters

For client-level rosters:

https://{api-url}/api/v2/tenants/client_7/rosters

Parameters

All fields are mandatory:

FieldSub-FieldsData TypeDescription
nameNAStringUnique name for roster used for roster identification.
timeZoneNAStringTime zone in which the roster should operate (see table below). An example time zone is:
"timeZone": {
"name": "Asia/Calcutta"
},
shiftDetailsStringNAGateway username.
nameStringUnique name for shift. The shift would be identified with the name.Example: Morning Shift
nameStringUnique name for shift. The shift would be identified with the name.Example: Morning Shift
schedule
  • type
    • one-time
    • recurring
StringDefine the schedule type for the roster.
  • If a roster should be active only for a single time period, provide"type": "one-time".
  • If a roster should repeat multiple times, provide"type": "recurring".
users
  • id
StringAdd users to a roster.
userGroups
  • uniqueId
StringAdd user groups to a roster.

Timezones

Region/CityRegion/CityRegion/City
Pacific/AsiaPacific/HonoluluAmerica/Anchorage
America/Los_AngelesAmerica/DenverAmerica/Chicago
America/New_YorkAmerica/Puerto_RicoAmerica/St_Johns
America/Buenos_AiresAtlantic/AzoresGMT
Europe/ParisEurope/IstanbulAfrica/Addis_Ababa
Asia/TehranAsia/YerevanAsia/Karachi
Asia/CalcuttaAsia/DaccaAsia/Saigon
Asia/ShanghaiAsia/TokyoAustralia/Darwin
Australia/SydneyPacific/GuadalcanalPacific/Auckland

One-tTime schedule types

Both fields are mandatory:

FieldDescription
startDatestartDate and endDate indicates a duration for a roster to operate. Use a start date for a roster. If, for example, a roster should start from 06-February-2018 at 07:00 AM, use "startDate": "2018-02-06T07:05:00+0000".
endDateProvide an end date for a roster.For example, if a roster should stop on 10-March-2018 at 05:30 PM, provide "endDate": "2018-03-10T17:30:00+0000".

Date should be in GMT format.

This is a sample payload to create a one-time roster:

{
	"name": "SJ Network Support",
	"description": "Team which handles SJ network issues",
	"timeZone": {
		"name": "Asia/Calcutta"
	},
	"shiftDetails": [{
		"name": "Morning shift",
		"schedule": {
			"type": "one-time",
			"startDate": "2018-02-06T07:05:00+0000",
			"endDate": "2018-03-10T17:30:00+0000"
		},
		"users": [{
			"id": "USR0000000018"
		}],
		"userGroups": [{
			"uniqueId": "USRGRP-37644ff5-7ea5-a3aa-e288-9c2666dc02e4"
		}]
	}]
}

Recurring schedule type

All fields are mandatory:

FieldDescription
startTimestartTime and endTime indicate the business hours for a roster.Provide start time for a roster.For example, a roster should start from 07:00 AM, provide "startTime": "07:00:00".
endTimeProvide end time for a roster.For example, a roster should end at 05:00 PM, provide "endTime": "17:00:00".
pattern
  • type
    • daily
    • weekly
    • monthly
    • yearly
Schedule pattern type for a roster to operate.
  • daily: Schedule a roster to repeat day-to-day.
  • weekly: Schedule a roster to repeat on certain week days. Example: "Monday, Wednesday".
  • monthly: Schedule a roster to repeat on certain weekdays or days of every month. Weekdays are specified as strings and days are specified as integer. Examples would be: the First Monday of every month or on the fourth day of every month.
  • yearly: Schedule a roster to repeat on yearly basis. Example: Repeat a roster once in a year or once in three years.
Use "Pattern Types for Recurring Schedule" below for the fields required to configure a recurring pattern type.

Pattern types for recurring schedule

TypeFieldsDescription
dailySchedule the roster to repeat day-to-day.
repeatFrequencySupported Values:1 through 10Provide how often a roster should repeat on daily basis. For example, if a roster should repeat once in two days, then use "repeatFrequency": 2.
startDatestartDate and endPattern indicate a duration for a roster to operate. Provide a start date for a roster. For example, if a roster should start from 10-February-2018, provide"startDate": "2018-02-10T00:00:00+0000".
endPattern
  • NEVER
  • OCCURRENCES
  • DATE
Configure a pattern to end a roster. OpsRamp supports three types of patterns:
  • NEVER: A roster should continue without any end time.
  • OCCURRENCES: A roster should stop after specific occurrences. For example, to end a roster after five occurrences, provide "OCCURRENCES": 5.
  • DATE: A roster should stop on a specific date. For example, to end a roster on 06-March-2018, provide "DATE": "2018-03-16T00:00:00+0000".
weeklySchedule a roster to repeat on weekly basis.
repeatFrequencyProvide how often a roster should repeat on weekly basis. For example, to repeat the roster once in two weeks, use "repeatFrequency": 2.
weekDays
  • Sunday
  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday
(Optional) Provide the week days on which a roster should repeat. For example, to repeat a roster on every Monday, Wednesday, and Thursday, use "weekDays": "Monday,Wednesday,Thursday".
startDateThe start date.
  • type
    • NEVER
    • OCCURRENCES
    • DATE
  • The end pattern.
    monthlyrepeatFrequency
    Supported values: 1 to 10
    Provide how often a roster should repeat on monthly basis. For example, to repeat a roster once in three months, provide "repeatFrequency": 3.
    repeatType
    • DAY_OF_WEEK
    • DAY_OF_MONTH
    Configure on which days in a month a roster should repeat.
    • DAY_OF_WEEK: Weekday on which a roster should repeat. Configure the week day using weekIndex and dayOfWeek fields.
    • DAY_OF_MONTH: Date on which a roster should repeat. Configure the date using the dayofMonth field.
    weekIndex
    • First
    • Second
    • Third
    • Fourth
    • Last
    The index of a week in a month.Example: First Monday, Second Saturday, Last Thursday.
    dayOfWeek
    • Sunday
    • Monday
    • Tuesday
    • Wednesday
    • Thursday
    • Friday
    • Saturday
    Week day on which the roster should repeat.For example, to repeat a roster on the first Monday of every month, provide "weekIndex": "First" and "dayOfWeek": "Monday".
    dayOfMonth
    Supported values:1 through 31
    Day on which a roster should repeat. Days range from 1 to 31. For example, to repeat a roster on the 2nd of every month, provide "dayOfMonth": 2.
    startDateThe start date.
    endPattern
    • type
      • NEVER
      • OCCURRENCES
      • DATE
    The end pattern.
    yearlySchedule a roster to repeat on yearly basis.
    repeatFrequency
    Supported values: 1 to 10
    Configure how often a roster should repeat on yearly basis. For example, to repeat a roster once in an year, provide "repeatFrequency": 1.
    startDateThe start date.
    endPattern
    • type
      • NEVER
      • OCCURRENCES
      • DATE
    The end pattern.

    Sample payloads for recurring pattern types

    Daily - Create a roster to repeat once in five days:

    "pattern": {
    	"type": "daily",
    	"repeatFrequency": 5
    }

    Weekly - Create a roster to repeat once in 5 weeks on specific weekdays:

    "pattern": {
    	"type": "weekly",
    	"weekDays": "Wednesday,Thursday,Friday",
    	"repeatFrequency": 5
    }

    Monthly - Create a roster to repeat once in 5 months on a specific weekday of a month:

    "pattern": {
    	"type": "monthly",
    	"repeatType": "DAY_OF_WEEK",
    	"weekIndex": "First",
    	"dayOfWeek": "Sunday",
    	"repeatFrequency": 5
    }

    Create a roster to repeat once in 5 months on a specific day of a month:

    "pattern": {
    	"type": "monthly",
    	"repeatType": "DAY_OF_MONTH",
    	"dayOfMonth": "1",
    	"repeatFrequency": 5
    }

    Yearly - Create a roster to repeat once in 2 years:

    "pattern": {
    	"type": "yearly",
    	"repeatFrequency": 2
    }

    Sample request

    {
    	"name": "SJ Network Support",
    	"description": "Team to handle all network issues in SJ site.",
    	"timeZone": {
    		"name": "Asia/Calcutta"
    	},
    	"shiftDetails": [{
    		"name": "Morning shift",
    		"schedule": {
    			"type": "one-time",
    			"startDate": "2018-02-05T07:05:00+0000",
    			"endDate": "2018-06-10T16:10:20+0000"
    		},
    		"users": [{
    			"id": "USR0000000018"
    		}],
    		"userGroups": [{
    			"uniqueId": "USRGRP-37644ff5-7ea5-a3aa-e288-9c2666dc02e4"
    		}]
    	}, {
    		"name": "Evening shift",
    		"schedule": {
    			"type": "recurring",
    			"startDate": "2018-03-06T00:00:00+0000",
    			"startTime": "16:30:00",
    			"endTime": "01:30:10",
    			"pattern": {
    				"type": "weekly",
    				"weekDays": "Wednesday,Thursday,Friday",
    				"repeatFrequency": 5
    			},
    			"endPattern": {
    				"type": "NEVER"
    			}
    		},
    		"users": [{
    			"id": "USR0000000020"
    		}],
    		"userGroups": [{
    			"uniqueId": "USRGRP-48965gg5-8fg6-a3aa-e288-0d3667e36f5"
    		}]
    	}]
    }

    Sample response

    {
    	"id": "ES-3b05178f-b197-46b2-9451-db9bfc3c8403",
    	"name": "SJ Network Support",
    	"description": "Team to monitor all network issues in SJ site.",
    	"createdTime": "2018-02-04T09:08:15+0000",
    	"updatedTime": "",
    	"timeZone": {
    		"id": "19",
    		"name": "Asia/Calcutta",
    		"label": "GMT +05:30 India",
    		"code": "IST"
    	},
    	"client": {
    		"id": 7,
    		"uniqueId": "client_7",
    		"name": "Logix Inc",
    		"activated": true
    	},
    	"shiftDetails": [{
    			"id": "ESD-237dffd1-8b86-47da-a40a-78246b6028e1",
    			"name": "Morning shift",
    			"schedule": {
    				"type": "one-time",
    				"startDate": "2018-02-06T07:05:00+0000",
    				"endDate": "2017-06-10T16:10:20+0000"
    			},
    			"users": [{
    				"id": "USR0000000018",
    				"loginName": "John_Smith",
    				"lastName": "Smith",
    				"firstName": "John",
    				"email": "john.smith@myorganization.com",
    				"phoneNumber": "",
    				"mobileNumber": "9004561234"
    			}],
    			"userGroups": [{
    				"uniqueId": "USRGRP-37644ff5-7ea5-a3aa-e288-9c2666dc02e4",
    				"name": "Network Admins",
    				"description": "",
    				"createdTime": "2017-03-14T11:40:35+0000"
    			}]
    		},
    		{
    			"id": "ESD-edaea54b-9a2a-42e9-b54b-6dea26c55202",
    			"name": "Evening shift",
    			"schedule": {
    				"type": "recurring",
    				"startDate": "2018-02-06T00:00:00+0000",
    				"startTime": "16:30:00",
    				"endTime": "01:30:10",
    				"pattern": {
    					"type": "weekly",
    					"weekDays": "Wednesday,Thursday,Friday",
    					"repeatFrequency": 5
    				},
    				"endPattern": {
    					"type": "NEVER"
    				}
    			},
    			"users": [{
    				"id": "USR0000000018",
    				"loginName": "James_Blake",
    				"lastName": "Blake",
    				"firstName": "James",
    				"email": "james.blake@myorganization.com",
    				"phoneNumber": "",
    				"mobileNumber": "9001237123"
    			}],
    			"userGroups": [{
    				"uniqueId": "USRGRP-37644ff5-7ea5-a3aa-e288-9c2666dc02e4",
    				"name": "Database Admins",
    				"description": "Team to monitor all Database issues.",
    				"createdTime": "2017-03-14T11:40:35+0000"
    			}]
    		}
    	]
    }