/
Calendar Web Services

Calendar Web Services

May 17, 2023

Overview

Universal Controller supports the following RESTful-based web services for Calendar operations, which are listed alphabetically on this page.

Formatting specifications for each web service, including details about parameter requirements, are provided.



Note

You can create and modify a Calendar that contains one or more global Custom Days only if the Custom Day Global Permitted Universal Controller system property is set to true.

Add an Existing Custom Day to a Calendar



Description



Description

URI

http://host_name/uc/resources/calendar/customdays

HTTP Method

POST

Description

Adds the specified Custom Day to the specified Calendar.

URI Parameters

See Add an Existing Custom Day to a Calendar: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/calendar/customdays?calendarname=test&customdayid=sfsdffsf123456dfhkjhk

Example Response

  • Status 200 /OK
    Custom day <customDay> successfully added to the calendar <calendar>.

  • Status 400 /Bad Request
    Calendar <calendarName> doesn`t exist.

  • Status 400 /Bad Request
    Custom Day <customDay> is already in the Calendar <calendarName>.

Add an Existing Custom Day to a Calendar: URI Parameters

Name

Description

Specifications

Required

Mutually Exclusive With

Name

Description

Specifications

Required

Mutually Exclusive With

calendarid

Unique ID for the Calendar.



Y
(unless calendarname
is specified)

calendarname

calendarname

Name used within the Controller to identify the Calendar.

Maximum 40 alphanumerics.

Y
(unless calendarid
is specified)

calendarid

customdayid

Unique ID for the Custom Day.



Y
(unless customdayname
is specified)

customdayname

customdayname

Name used within the Controller to identify the Custom Day.

Maximum 40 alphanumerics.

Y
(unless customdayid
is specified)

customdayid

Create a Calendar



Description



Description

URI

http://host_name/uc/resources/calendar

HTTP Method

POST

Description

Creates a new Calendar.

Example URI

http://localhost:8080/uc/resources/calendar

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example Request

See Create a Calendar: Example Request, below.

Calendar Properties

See Create a Calendar: Calendar Properties.

Custom Day Properties

See Create a Calendar: Custom Day Properties.

Local Custom Day Properties

See Create a Calendar: Local Custom Day Properties.

Example Response

  • Status 200 /OK
    Successfully created the calendar with sysId <sysId>.

Create a Calendar: Example Request

XML Request

JSON Request

XML Request

JSON Request

<calendar retainSysIds="true"> <businessDays>Monday,Tuesday,Wednesday,Thursday,Friday</businessDays> <customDays> <customDay> <name>uc - Christmas</name> <sysId>daf16d70c0a801650040c4d58a3feebd</sysId> </customDay> <customDay> <name>uc - Flag Day</name> <sysId>daf16d8fc0a801650040c4d54b2432fb</sysId> </customDay> </customDays> <comments>American Calendar</comments> <firstDayOfWeek>Sunday</firstDayOfWeek> <localCustomDays> <localCustomDay> <adjustment>None</adjustment> <adjustmentAmount>1</adjustmentAmount> <adjustmentType>Day</adjustmentType> <category>Holiday</category> <comments /> <ctype>Single Date</ctype> <date>2017-08-23</date> <dateList /> <day>1</day> <dayofweek>Sun</dayofweek> <month>Jan</month> <name>local custom day</name> <observedRules /> <relfreq>1st</relfreq> <sysId>616ec15e7a5e40dbaae421e3688a25e5</sysId> </localCustomDay> </localCustomDays> <name>uc - American Calendar</name> <opswiseGroups /> <sysId>da24b953c0a8016501fbcb18464d8328</sysId> </calendar>

{ "businessDays": { "value": "Monday,Tuesday,Wednesday,Thursday,Friday" }, "comments": "American Calendar", "customDays": [ { "name": "uc - Christmas", "sysId": "daf16d70c0a801650040c4d58a3feebd" }, { "name": "uc - Flag Day", "sysId": "daf16d8fc0a801650040c4d54b2432fb" } ], "firstDayOfWeek": "Sunday", "localCustomDays": [ { "adjustment": "None", "adjustmentAmount": 1, "adjustmentType": "Day", "category": "Holiday", "comments": null, "ctype": "Single Date", "date": "2017-08-23", "dateList": [], "day": 1, "dayofweek": "Sun", "month": "Jan", "name": "local custom day", "observedRules": [], "relfreq": "1st", "sysId": "616ec15e7a5e40dbaae421e3688a25e5" } ], "name": "uc - American Calendar", "opswiseGroups": [], "retainSysIds": true, "sysId": "da24b953c0a8016501fbcb18464d8328" }

Create a Calendar: Calendar Properties

Property

UI Field Name

Description

Specifications

Required

Property

UI Field Name

Description

Specifications

Required

businessDays

Business Days

Comma-separated list of days.

Valid values:



  • Sunday

  • Monday

  • Tuesday

  • Wednesday

  • Thursday

  • Friday

  • Saturday

Optional: useDefaultIfBlank attribute. Boolean; Valid values: true/false.

  • If businessDays is blank or is not specified in the Request, businessDays defaults to Monday,Tuesday,Wednesday,Thursday,Friday. To disable this behavior, set useDefaultIfBlank to false. That is, to set businessDays to blank when a calendar contains "Business Day" Custom Day(s), specify: <businessDays useDefaultIfBlank="false"></businessDays>.

  • If businessDays is blank and the useDefaultIfBlank attribute is not included in the Request (<businessDays />), businessDaysdefaults to Monday,Tuesday,Wednesday,Thursday,Friday.

  • If businessDays is not blank, useDefaultIfBlank is ignored.

  • If useDefaultIfBlank is set to true (<businessDays useDefaultIfBlank="true"></businessDays>), businessDaysdefaults to Monday,Tuesday,Wednesday,Thursday,Friday.

  • If useDefaultIfBlank is set to false (<businessDays useDefaultIfBlank="false"></businessDays>), business days are not set.

The Read a Calendar web service will return useDefaultIfBlank only if businessDays is empty; useDefaultIfBlank will be set to false.

N

comments

Description

User-defined; description for the calendar.



N

excludeRelated

n/a

Specification for whether or not to exclude related records (Custom Days, Local Custom Days) from an update, even if they are provided in the request.

Valid values: true/false (default is false).

N

exportReleaseLevel

n/a

Universal Controller release that the record was exported from.

read only

N

exportTable

n/a

Record table information.

read only

N

firstDayOfWeek

First Day Of Week

Day that is considered the start of the week.

Valid values:

  • Sunday

  • Monday

  • Tuesday

  • Wednesday

  • Thursday

  • Friday

  • Saturday

N

name

Name

Name used within the Controller to identify this calendar.

Maximum 40 alphanumerics.

Y

opswiseGroups

Member of Business Services

List of Business Services:
 
XML



<opswiseGroups> <opswiseGroup>test</opswiseGroup> </opswiseGroups>



 
JSON



"opswiseGroups": [ "test" ]



N

retainSysIds

n/a

Specification for whether or not the Create a Calendar web service will persist the sysId property.





  • If retainSysIds="true" and sysId is included in the request/response, sysId will be persisted to the database.



  • If retainSysIds="false" and sysId is included in the request/response, sysId will be ignored; it will be autogenerated by the Controller.





Note

In XML web services, retainSysIds is specified as an attribute in the <calendar> element.

Valid values: true/false (default is true).

N

sysId

n/a

System ID field in the database for this Calendar record.

Persisted only if retainSysIds is set to true.

N

firstQuarterStart

1st Quarter Start

To specify the start of the 1st Quarter, a day and month must be specified as shown below.
 
XML

<firstQuarterStart> <day>15</day> <month>01</month> </firstQuarterStart>

 JSON

"firstQuarterStart": { "day": "15", "month": "Jan" }

Valid values:

  • month:

    • integer value between 1-12

    • string value 3 letter month

      • Jan

      • Feb

      • Mar

      • Apr

      • May

      • Jun

      • Jul

      • Aug

      • Sep

      • Oct

      • Nov

      • Dec

  • The day must also be valid for the given month. For example, Feb 30 is not allowed.

If any other Quarter is specified then this property is also required.

secondQuarterStart

2nd Quarter Start

To specify the start of the 1st Quarter, a day and month must be specified as shown below.
 
XML

<secondQuarterStart> <day>14</day> <month>Apr</month> </secondQuarterStart>

 JSON

"secondQuarterStart": { "day": "14", "month": "Apr" }

Valid values:

  • month:

    • integer value between 1-12

    • string value 3 letter month

      • Jan

      • Feb

      • Mar

      • Apr

      • May

      • Jun

      • Jul

      • Aug

      • Sep

      • Oct

      • Nov

      • Dec