Maintenanceman.nl

< All Topics
Print
Updated

Request Body

The request body exists of a single JSON object containing at least all mandatory and relevant optional parameters. In the structure as shown below.

{ 
"schedule":
    [ {
         "id": "string",
         "name": "string", 
         "interval":{
                "units": 0, 
                "orDays": 0, 
                "after": "string",
                "recurrencePattern":["string"]
                },
         "willReset": "string",
         "lastExecutedDate": "string", 
         "lastExecutedValue": 0,
         "preserveOnOverdueReset": true,
         "mergeLimit": 
                { 
                    "units": 0, 
                    "orDays": 0 
                },
         "startAt":{
                      "units":0,
                      "date":"String"
                    },
         "stopAt":{
                      "units":0,
                      "date":"String"
                    }
      }], 
"period": 0, 
"unitsPerDay": 0, 
"currentDate": "string", 
"currentUnits": 0, 
"dateZero":"string",
"resultType": "string", 
"dateFormat": "string" 
}

schedule

The schedule parameter is where the basic schedule is defined and includes recurrence intervals, dates and values of most recent occurrences and guiding parameters such as start-at and stop-at values. This parameter exists of an array of JSON objects.

Type: Array

Required: Yes

API Version: 1

id

The ‘id’ parameter is a unique key for reference to this schedule item. This can be any string value, but must be unique within the parent ‘schedule’ array. The id field is used as reference in the ‘after’ and ‘willReset’ parameters.

Type: String

Required: Yes

API Version: 1

name

The ‘name’ field is an optional, human readable name or description of the schedule item and will be returned with the result values.

Type: String

Required: Yes

API Version: 1

interval

The ‘interval’ parameter is a nested JSON object containing, amongst others, three parameters (units, orDays and recurrencePattern), each of which specifies the interval period in a different way. If more than one of the parameters is set, they will either complement each other or cancel each other out, depending the situation. For a valid request at least one of these parameters must contain a value.

"interval":{ 
	"units": 0,
	"orDays": 0,
	"recurrencePattern": Array("string"),
	"after": "string"
	}

Type: JSON Object

Required: Yes

API Version: 1

units

The interval value in ‘units’ specifies an Interval in any time independant unit such as kilometers, running hours, oscillations or any other unit of measure. The unit of measure is not specified but needs to be the same throughout the schedule.

Type: Integer

Required: No

API Version: 1

orDays

This parameter specifies the interval in normal 24 hour, calendar days.

Type: Integer

Required: No

API Version: 1

recurrencePattern

the recurrence pattern allows you to specify a calendar based interval pattern in a more flexible and intuitive way and exists from an array of string values, each of which are evaluated separately. A single recurrencePattern string could look like:

"Every 2nd day of every 3rd month"

or

"Every 31st december of every second year"

Evaluation of the recurrence pattern string is designed to process a very human readable specification, but is bound to some limitations. Therefore every string must specify the desired period in incrementing parent periods, separated by the keyword ‘of’, like:

"[smallest period] of [larger parent period] of [largest parent period]"

Words like ‘each’ or ‘every’ and suffixes behind numbers can be included for readability, but are not actually required and not evaluated in any way. Therefore the first two examples may also be written as:

"day 2 of month 3"

or

"december 31 of year 2"

Please see the full reference on recurrence pattern strings for more detailed specifications.

Type: Array(String)

Required: Yes

API Version: 2

after

Use this field to make the interval occur relative to another interval instead of a recurring at a fixed interval. Note that using this field will make the interval stop occurring at regular intervals and make it occur only once X time or units after another schedule item instead. You can provide an id or a comma separated string of id’s.

Type: String

Required: No

API Version: 1

willReset

Use this field to reset another schedule item to zero. This is typically used for schedule items that include the scope of others items. You can provide an id or a comma separated string of id’s.

Type: String

Required: No

API Version: 1

lastExecutedDate

Last historic occurrence date of the schedule item. Supported date formats for this field are ISO-8601, RFC 822, RFC 850, RFC 1036, RFC 1123, RFC 2822, RFC 3339, RSS or the W3C format. Other formats may work as well, but make sure to test them before use.

Type: String

Required: No

API Version: 1

lastExecutedValue

Last historic Units value of the last known execution of the schedule item. This is only required for time-independant intervals.

Type: Integer

Required: No

API Version: 1

preserveOnOverdueReset

Set this field to true if the schedule item needs to reccur even if the schedule item resetting the current one is over due. If not set, or if set to false, the schedule item may be reset by another item, even if that’s not executed and overdue.

Type: Boolean

Required: No

API Version: 1

mergeLimit

The merge limit exists of a single JSON object with two child parameters, ‘units’ and ‘orDays’. If any of these fields is set and the execution comes within the specified limit before another schedule item that resets the current one, this schedule item will not be executed.

"mergeLimit":{ 
              "units": 0, 
              "orDays": 0 
             }

Type: JSON Object

Required: No

API Version: 1

units

The merge limit in time-independant units (such as kilometers, running hours, etc).

Type: Integer

Required: No

API Version: 1

orDays

The merge limit in 24 hours calendar days.

Type: Integer

Required: No

API Version: 1

startAt

The startAt parameter indicates the first occurrence of the interval item defined in either a time-independant ‘units’ value or a fixed date. Note that, if both parameters are specified, only the first occurring one will be considered.

"startAt":{
       "units":0,
       "date":"String"
         }
units

The first occurrence of the interval item as the time-independant ‘units’ value.

date

Date of the first occurrence of the current schedule item. Supported date formats for this field are ISO-8601, RFC 822, RFC 850, RFC 1036, RFC 1123, RFC 2822, RFC 3339, RSS or the W3C format. Other formats may work as well, but make sure to test them before use.

stopAt

The stopAt parameter indicates when to stop scheduling the current interval item defined in either a time-independant ‘units’ value or a fixed date. Note that, if both parameters are specified, only the first occurring one will be considered.

"stopAt":{
      "units":0,
      "date":"String"
      }
units

The value from which the current interval item will no longer be scheduled as the time-independant ‘units’ value.

date

Date from which the current interval item will no longer be scheduled. Supported date formats for this field are ISO-8601, RFC 822, RFC 850, RFC 1036, RFC 1123, RFC 2822, RFC 3339, RSS or the W3C format. Other formats may work as well, but make sure to test them before use.

period

The total time period in ‘days’, counted from the ‘currentDate’ value for the schedule to be returned. This value is automatically limited to a maximum of 35 years, due to memory limitations.

Type: Integer

Required: No

API Version: 1

unitsPerDay

Average increment of time-independant units such as kilometers, running hours, oscillations or any other unit of measure, per day to base the outputted schedule on. This value is required for any schedule that uses the time independant interval.

Type: Integer

Required: No

API Version: 1

currentDate

Date to be used as the current point in time. This Value must be equal or greater than the latest ‘lastExecutedDate’. Supported date formats for this field are ISO-8601, RFC 822, RFC 850, RFC 1036, RFC 1123, RFC 2822, RFC 3339, RSS or the W3C format. Other formats may work as well, but make sure to test them before use.

Type: String

Required: Yes

API Version: 1

currentUnits

This field specifies the current value for the time-independant interval ‘units’ value. This value must be equal to or greater than the greatest ‘lastExecutedValue’ value and is mandatory for any time-independant schedule.

Type: Integer

Required: No

API Version: 1

dateZero

This field specifies the historic date at which the time-independant ‘units’ value first started at zero. This is a helper value that may prevent unexpected output on some exotic schedules. It is recommended to always specify this value, but if not specified the, API will use a virtual date instead. Supported date formats for this field are ISO-8601, RFC 822, RFC 850, RFC 1036, RFC 1123, RFC 2822, RFC 3339, RSS or the W3C format. Other formats may work as well, but make sure to test them before use.

Type: String

Required: No

API Version: 1

resultType

This value specifies the format in which the results are returned and can have three values, being ‘JSON’, ‘XML’ or a blank string. Please see the chapter on the Result Body for details on the returned content in either of the three cases.

Type: String

Required: No

API Version: 1

dateFormat

A date format to be used in the API call result. (E.g. y-M-d). The usable charachters to use for this field are:

  • d – The day of the month (from 01 to 31)
  • D – A textual representation of a day (three letters)
  • j – The day of the month without leading zeros (1 to 31)
  • l (lowercase ‘L’) – A full textual representation of a day
  • N – The ISO-8601 numeric representation of a day (1 for Monday, 7 for Sunday)
  • S – The English ordinal suffix for the day of the month (2 characters st, nd, rd or th.)
  • w – A numeric representation of the day (0 for Sunday, 6 for Saturday)
  • z – The day of the year (from 0 through 365)
  • W – The ISO-8601 week number of year (weeks starting on Monday)
  • F – A full textual representation of a month (January through December)
  • m – A numeric representation of a month (from 01 to 12)
  • M – A short textual representation of a month (three letters)
  • n – A numeric representation of a month, without leading zeros (1 to 12)
  • t – The number of days in the given month
  • L – Whether it’s a leap year (1 if it is a leap year, 0 otherwise)
  • o – The ISO-8601 year number
  • Y – A four digit representation of a year
  • y – A two digit representation of a year
  • e – The timezone identifier (Examples**UTC, GMT, Atlantic/Azores)
  • O – Difference to Greenwich time (GMT) in hours (Example**+0100)
  • P – Difference to Greenwich time (GMT) in hours:minutes
  • T – Timezone abbreviations (Examples**EST, MDT)
  • Z – Timezone offset in seconds. The offset for timezones west of UTC is negative (-43200 to 50400)
  • c – The ISO-8601 date (e.g. 2013-05-05T16:34:42+00:00)
  • r – The RFC 2822 formatted date (e.g. Fri, 12 Apr 2013 12:01:05 +0200)
  • U – The seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
    Please note that, if no time zone is specified, UTC time will be used.

Type: String

Required: No

API Version: 1

Table of Contents