API: Work Schedule
The work schedule defines if days are working days or non-working days.
A day can be a non-working day if any of these two conditions are met:
- the day is a recurring non-working week day: a weekend day. For instance Sunday is not worked in most countries;
- the day has been defined as a non-working day: national bank holidays or other days deemed special. For instance the 1st of January is New Year’s day and is a bank holiday in most countries.
Endpoints can define which week days are working/non-working days, and which dates are non-working days.
To represent the work schedule, Day, WeekDay, and NonWorkingDay models are used.
Day Actions
None
Day Linked Properties
| Link | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| self | This day | Day | not null | READ |
| nonWorkingReasons | A list of resources describing why this day is a non-working day | (WeekDay/NonWorkingDay)[] | READ | |
| weekDay | The week day for this day | WeekDay | not null | READ |
Day Local Properties
| Property | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| date | The date in ISO8601 format (YYYY-MM-DD) | Date | not null | READ |
| name | The name of the day | String | not null | READ |
| working | true for a working day, false otherwise | Boolean | not null | READ |
WeekDay Actions
| Link | Description | Condition |
|---|---|---|
| update | Update this week day | Permission: edit work schedule |
WeekDay Linked Properties
| Link | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| self | This week day | WeekDay | not null | READ |
WeekDay Local Properties
| Property | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| day | The week day from 1 to 7. 1 is Monday. 7 is Sunday. | Integer | x >= 1, x <= 7 | READ |
| name | The name of the week day | String | not null | READ |
| working | true for a working week day, false otherwise | Boolean | not null | READ/WRITE |
NonWorkingDay Actions
| Link | Description | Condition |
|---|---|---|
| update | Update this non-working day | Permission: edit work schedule |
NonWorkingDay Linked Properties
| Link | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| self | This non-working day | NonWorkingDay | not null | READ |
NonWorkingDay Local Properties
| Property | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| date | The date in ISO8601 format (YYYY-MM-DD) | Date | not null | READ |
| name | The name of the non-working day day | String | not null | READ/WRITE |
Methods
Lists days
Lists days information for a given date interval.
All days from the beginning of current month to the end of following month are returned by default.
filters
string
optional query
JSON specifying filter conditions.
Accepts the same format as returned by the queries endpoint. Currently supported filters are:
-
date: the inclusive date interval to scope days to look up. When unspecified, default is from the beginning of current month to the end of following month.
Example:
{ "date": { "operator": "<>d", "values": ["2022-05-02","2022-05-26"] } }would return days between May 5 and May 26 2022, inclusive. -
working: when
true, returns only the working days. Whenfalse, returns only the non-working days (weekend days and non-working days). When unspecified, returns both working and non-working days.Example:
{ "working": { "operator": "=", "values": ["t"] } }would exclude non-working days from the response.
Example:[{ "date": { "operator": "<>d", "values": ["2022-05-02","2022-05-26"] } }, { "working": { "operator": "=", "values": ["f"] } }]
200
OK
DayCollectionModel{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This days collection\n\n**Resource**: DayCollectionModel"
}
]
}
}
},
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"description": "The array of days. Each day has a name and a working status\nindicating if it is a working or a non-working day.",
"items": {
"$ref": "#/components/schemas/DayModel"
}
}
}
}
}
}
],
"example": {
"_type": "Collection",
"total": 5,
"count": 5,
"_links": {
"self": {
"href": "/api/v3/days?filters=[{\"interval\":{\"operator\":\"<>d\",\"values\":[\"2022-04-29\",\"2022-05-03\"]}}]"
}
},
"_embedded": {
"elements": [
{
"_type": "Day",
"date": "2022-04-29",
"name": "Friday",
"working": true,
"_links": {
"self": {
"href": "/api/v3/days/2022-04-29"
},
"weekday": {
"href": "/api/v3/days/week/5",
"title": "Friday"
}
}
},
{
"_type": "Day",
"date": "2022-04-30",
"name": "Saturday",
"working": false,
"_links": {
"self": {
"href": "/api/v3/days/2022-04-30"
},
"nonWorkingReasons": [
{
"href": "/api/v3/days/week/6",
"title": "Saturday"
}
],
"weekday": {
"href": "/api/v3/days/week/6",
"title": "Saturday"
}
}
},
{
"_type": "Day",
"date": "2022-05-01",
"name": "Sunday (Labor day)",
"working": false,
"_links": {
"self": {
"href": "/api/v3/days/2022-05-01"
},
"nonWorkingReasons": [
{
"href": "/api/v3/days/week/7",
"title": "Sunday"
},
{
"href": "/api/v3/days/non_working/2022-05-01",
"title": "Labor day"
}
],
"weekday": {
"href": "/api/v3/days/week/7",
"title": "Sunday"
}
}
},
{
"_type": "Day",
"date": "2022-05-02",
"name": "Monday",
"working": true,
"_links": {
"self": {
"href": "/api/v3/days/2022-05-02"
},
"weekday": {
"href": "/api/v3/days/week/1",
"title": "Monday"
}
}
},
{
"_type": "Day",
"date": "2022-05-03",
"name": "Tuesday",
"working": true,
"_links": {
"self": {
"href": "/api/v3/days/2022-05-03"
},
"weekday": {
"href": "/api/v3/days/week/2",
"title": "Tuesday"
}
}
}
]
}
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Lists all non working days
Lists all one-time non working days, such as holidays. It does not lists the non working weekdays, such as each Saturday, Sunday. For listing the weekends, the /api/v3/days endpoint should be used.
All days from current year are returned by default.
filters
string
optional query
JSON specifying filter conditions.
Accepts the same format as returned by the queries endpoint. Currently supported filters are:
-
date: the inclusive date interval to scope days to look up. When unspecified, default is from the beginning to the end of current year.
Example:
{ "date": { "operator": "<>d", "values": ["2022-05-02","2022-05-26"] } }would return days between May 5 and May 26 2022, inclusive.
Example:[{ "date": { "operator": "<>d", "values": ["2022-05-02","2022-05-26"] } }]
200
OK
NonWorkingDayCollectionModel{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This non working days collection\n\n**Resource**: NonWorkingDayCollectionModel"
}
]
}
}
},
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"description": "The array of non working days. Each day has a name and a date.",
"items": {
"$ref": "#/components/schemas/NonWorkingDayModel"
}
}
}
}
}
}
],
"example": {
"_type": "Collection",
"total": 2,
"count": 2,
"_links": {
"self": {
"href": "/api/v3/non_working?filters=[{\"interval\":{\"operator\":\"<>d\",\"values\":[\"2022-04-29\",\"2022-12-24\"]}}]"
}
},
"_embedded": {
"elements": [
{
"_type": "NonWorkingDay",
"date": "2022-12-24",
"name": "Christmas Evening",
"_links": {
"self": {
"href": "/api/v3/days/non_working/2022-04-24"
},
"weekday": {
"href": "/api/v3/days/week/6",
"title": "Saturday"
}
}
},
{
"_type": "NonWorkingDay",
"date": "2022-05-01",
"name": "Labor day",
"_links": {
"self": {
"href": "/api/v3/days/non_working/2022-05-01"
},
"weekday": {
"href": "/api/v3/days/week/7",
"title": "Sunday"
}
}
}
]
}
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
View a non-working day
Returns the non-working day information for a given date.
date
string
required path
The date of the non-working day to view in ISO 8601 format.
Example:2022-05-06
200
OK
NonWorkingDayModel{
"type": "object",
"required": [
"_type",
"date",
"name"
],
"properties": {
"_type": {
"type": "string",
"enum": [
"NonWorkingDay"
]
},
"date": {
"type": "string",
"format": "date",
"description": "Date of the non-working day."
},
"name": {
"type": "string",
"description": "Descriptive name for the non-working day."
},
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This non-working day.\n\n**Resource**: NonWorkingDay"
}
]
}
}
}
},
"example": {
"_type": "NonWorkingDay",
"date": "2022-12-25",
"name": "Christmas",
"_links": {
"self": {
"href": "/api/v3/days/non_working/2022-12-25",
"title": "Christmas"
}
}
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the given date is not a non-working day.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Lists week days
Lists week days with work schedule information.
No parameters
200
OK
WeekDayCollectionModel{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This week days collection\n\n**Resource**: WeekDayCollectionModel"
}
]
}
}
},
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"description": "The array of week days.",
"minItems": 7,
"maxItems": 7,
"items": {
"$ref": "#/components/schemas/WeekDayModel"
}
}
}
}
}
}
],
"example": {
"_type": "Collection",
"total": 7,
"count": 7,
"_links": {
"self": {
"href": "/api/v3/days/week"
}
},
"_embedded": {
"elements": [
{
"_type": "WeekDay",
"day": 1,
"name": "Monday",
"working": true,
"_links": {
"self": {
"href": "/api/v3/days/week/1",
"title": "Monday"
}
}
},
{
"_type": "WeekDay",
"day": 2,
"name": "Tuesday",
"working": true,
"_links": {
"self": {
"href": "/api/v3/days/week/2",
"title": "Tuesday"
}
}
},
{
"_type": "WeekDay",
"day": 3,
"name": "Wednesday",
"working": true,
"_links": {
"self": {
"href": "/api/v3/days/week/3",
"title": "Wednesday"
}
}
},
{
"_type": "WeekDay",
"day": 4,
"name": "Thursday",
"working": true,
"_links": {
"self": {
"href": "/api/v3/days/week/4",
"title": "Thursday"
}
}
},
{
"_type": "WeekDay",
"day": 5,
"name": "Friday",
"working": true,
"_links": {
"self": {
"href": "/api/v3/days/week/5",
"title": "Friday"
}
}
},
{
"_type": "WeekDay",
"day": 6,
"name": "Saturday",
"working": false,
"_links": {
"self": {
"href": "/api/v3/days/week/6",
"title": "Saturday"
}
}
},
{
"_type": "WeekDay",
"day": 7,
"name": "Sunday",
"working": false,
"_links": {
"self": {
"href": "/api/v3/days/week/7",
"title": "Sunday"
}
}
}
]
}
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
View a week day
View a week day and its attributes.
day
integer
required path
The week day from 1 to 7. 1 is Monday. 7 is Sunday.
200
OK
WeekDayModel{
"type": "object",
"required": [
"_type",
"day",
"name",
"working"
],
"properties": {
"_type": {
"type": "string",
"enum": [
"WeekDay"
]
},
"day": {
"type": "integer",
"description": "The week day from 1 to 7. 1 is Monday. 7 is Sunday.",
"readOnly": true,
"minimum": 1,
"maximum": 7
},
"name": {
"type": "string",
"description": "The week day name."
},
"working": {
"type": "boolean",
"description": "`true` for a working week day, `false` otherwise."
},
"_links": {
"allOf": [
{
"$ref": "#/components/schemas/WeekDaySelfLinkModel"
}
]
}
},
"example": {
"_type": "WeekDay",
"day": 5,
"name": "Friday",
"working": false,
"_links": {
"self": {
"href": "/api/v3/day/week/5",
"title": "Friday"
}
}
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the day is out of the 1-7 range.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
View day
View the day information for a given date.
date
string
required path
The date of the non-working day to view in ISO 8601 format.
Example:2022-05-06
200
OK
DayModel{
"type": "object",
"required": [
"_type",
"date",
"name",
"working"
],
"properties": {
"_type": {
"type": "string",
"enum": [
"Day"
]
},
"date": {
"type": "string",
"format": "date",
"description": "Date of the day."
},
"name": {
"type": "string",
"description": "Descriptive name for the day."
},
"working": {
"type": "boolean",
"description": "`true` for a working day, `false` otherwise."
},
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"$ref": "#/components/schemas/Link"
},
"nonWorkingReasons": {
"type": "array",
"description": "A list of resources describing why this day is a non-working day.\nLinked resources can be `NonWorkingDay` and `WeekDay` resources.\nThis property is absent for working days.",
"items": {
"$ref": "#/components/schemas/Link"
}
},
"weekDay": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The week day for this day."
}
]
}
}
}
},
"example": {
"_type": "Day",
"date": "2022-12-25",
"name": "Sunday (Christmas)",
"working": false,
"_links": {
"self": {
"href": "/api/v3/days/2022-12-25"
},
"nonWorkingReasons": [
{
"href": "/api/v3/days/week/7",
"title": "Sunday"
},
{
"href": "/api/v3/days/non_working/2022-12-25",
"title": "Christmas"
}
],
"weekday": {
"href": "/api/v3/days/week/7",
"title": "Sunday"
}
}
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}