Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Current »

You can use this REST API to develop integrations between Company Calendar Planner for Jira and other applications or systems. This page documents the available REST resources along with expected HTTP responses and sample requests.

To use REST API, an admin has to generate a token tied either to specific calendars or all calendars. It’s recommended to assign minimum calendars per token and to create "All Calendars" tokens only when it’s needed.

URI Structure

To use REST API, your application will make an HTTP request and parse the response.

Since the Cloud version of the app is hosted in the Cloud, while the Server and Data Center versions reside on the same server as Jira, there are different URLs for REST API.

For Jira Cloud REST API URIs start with:

https://ccj.brizoit.com/ccj/rest/brizo-calendar

For Jira Server REST API URIs start with your Jira URL followed by /rest/brizo-calendar

JIRA-SERVER-URL/rest/brizo-calendar

Jira URL can be copied from the browser or checked in Administration -> System -> General configuration, Base URL setting:

Authentication

Requests to the REST points should be authenticated by Bearer authentication (also known as token authentication). To do so, the clients must send the token in the Authorization header when making requests:

Authorization: Bearer <token>

When no token or wrong token is passed all REST resources return 401 error code.

REST resources

GET /api/1/calendar

Returns the list of calendars tied for the passed token.

Successful response brings JSON with calendars associated with the passed token:

See the response sample:

 Click here to expand...
[
    {
        "id": 1959,
        "sources": [
            {
                "id": 5655,
                "calendarId": 1959,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "meeting",
                    "name": "Meetings",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": true
                },
                "order": 1,
                "value": "{\"color\":\"#7500ca\",\"projectId\":-1,\"condColors\":[],\"name\":\"Dekki's meetings\",\"concurrence\":\"allow\",\"hideStartTime\":false,\"issueFields\":[{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.project\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"event.summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.users\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.reporter\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.description\",\"showEvent\":true,\"showInfo\":true}],\"summaryFromSourceName\":false,\"summaryFromIssueSummary\":false}"
            },
            {
                "id": 5656,
                "calendarId": 1959,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "jira",
                    "name": "Jira dates",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": false
                },
                "order": 2,
                "value": "{\"color\":\"#cc6fcc\",\"condColors\":[],\"dateRanges\":[],\"singleDates\":[\"duedate\"],\"summaryFromSourceName\":false,\"projectId\":-1,\"name\":\"Dekki's JD source\",\"issueFields\":[{\"id\":\"duedate\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"issuetype\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"status\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"assignee\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"reporter\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"description\",\"showEvent\":false,\"showInfo\":true}],\"hideStartTime\":false}"
            }
        ],
        "value": "{\"description\":\"\",\"name\":\"Dekki Gedru's first calendar\",\"usersFromEvents\":true}",
        "user": "66625976fc0cc7a600b08977"
    },
    {
        "id": 1995,
        "sources": [
            {
                "id": 5779,
                "calendarId": 1995,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "jira",
                    "name": "Jira dates",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": false
                },
                "order": 1,
                "value": "{\"color\":\"#057fff\",\"condColors\":[],\"dateRanges\":[],\"singleDates\":[\"duedate\"],\"summaryFromSourceName\":false,\"projectId\":10336,\"name\":\"Jira dates events\",\"issueFields\":[{\"id\":\"duedate\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"issuetype\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"status\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"assignee\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"reporter\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"description\",\"showEvent\":false,\"showInfo\":true}],\"hideStartTime\":false}"
            },
            {
                "id": 5780,
                "calendarId": 1995,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "sprint",
                    "name": "Jira sprints",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": false
                },
                "order": 2,
                "value": "{\"boardId\":132,\"color\":\"#cc6fcc\",\"name\":\"Sprints\",\"projectId\":10336,\"show\":0,\"state\":0,\"hideStartTime\":false}"
            },
            {
                "id": 5781,
                "calendarId": 1995,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "version",
                    "name": "Jira versions",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": false
                },
                "order": 3,
                "value": "{\"name\":\"Versions\",\"color\":\"#ff3e05\",\"projectId\":10371,\"show\":0,\"releasedStatus\":0}"
            },
            {
                "id": 5782,
                "calendarId": 1995,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "trip",
                    "name": "Business trips",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": true
                },
                "order": 4,
                "value": "{\"color\":\"#40af04\",\"projectId\":0,\"condColors\":[],\"name\":\"Business trips\",\"issuesAsResources\":false,\"concurrence\":\"allow\",\"hideStartTime\":false,\"issueFields\":[{\"id\":\"event.summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.users\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.reporter\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.description\",\"showEvent\":true,\"showInfo\":true}],\"summaryFromSourceName\":false,\"summaryFromIssueSummary\":false}"
            }
        ],
        "value": "{\"description\":\"\",\"name\":\"Development\",\"usersFromEvents\":true}",
        "user": "6666d5194d18cbf6772f4"
    }
]

GET /api/1/calendar/{calendarId}

Returns the calendar for the given calendar id.

In addition to properties returned by GET /api/1/calendar , this method brings permissions related properties.

Successful response brings JSON with a calendar:

See the response sample:

 Click here to expand...
{
    "id": 1959,
    "publicCalendar": false,
    "calendarEditable": false,
    "permCalendarEdit": {
        "groups": [],
        "users": []
    },
    "eventsEditable": false,
    "permEventsEdit": {
        "groups": [],
        "users": []
    },
    "eventReporterEdit": false,
    "sources": [
        {
            "id": 5655,
            "calendarId": 1959,
            "emailsEnabled": false,
            "eventType": {
                "issueRequired": false,
                "key": "meeting",
                "name": "Meetings",
                "projectRequired": false,
                "systemType": true,
                "usersRequired": true
            },
            "order": 1,
            "value": "{\"color\":\"#7500ca\",\"projectId\":-1,\"condColors\":[],\"name\":\"Dekki's meetings\",\"concurrence\":\"allow\",\"hideStartTime\":false,\"issueFields\":[{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.project\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"event.summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.users\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.reporter\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.description\",\"showEvent\":true,\"showInfo\":true}],\"summaryFromSourceName\":false,\"summaryFromIssueSummary\":false}"
        },
        {
            "id": 5656,
            "calendarId": 1959,
            "emailsEnabled": false,
            "eventType": {
                "issueRequired": false,
                "key": "jira",
                "name": "Jira dates",
                "projectRequired": false,
                "systemType": true,
                "usersRequired": false
            },
            "order": 2,
            "value": "{\"color\":\"#cc6fcc\",\"condColors\":[],\"dateRanges\":[],\"singleDates\":[\"duedate\"],\"summaryFromSourceName\":false,\"projectId\":-1,\"name\":\"Dekki's JD source\",\"issueFields\":[{\"id\":\"duedate\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"issuetype\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"status\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"assignee\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"reporter\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"description\",\"showEvent\":false,\"showInfo\":true}],\"hideStartTime\":false}"
        }
    ],
    "value": "{\"description\":\"\",\"name\":\"Dekki Gedru's first calendar\",\"usersFromEvents\":true}",
    "user": "534534976fc0cc7a60053444"
}

404 status code is returned for non-existing calendarId or when the calendarId is not associated with the token.

GET /api/1/source/{sourceId}

Returns the source for the given source id.

Successful response brings JSON with a source representation:

See the response sample:

 Click here to expand...
{
    "id": 5655,
    "calendarId": 1959,
    "emailsEnabled": false,
    "eventType": {
        "issueRequired": false,
        "key": "meeting",
        "name": "Meetings",
        "projectRequired": false,
        "systemType": true,
        "usersRequired": true
    },
    "order": 1,
    "value": "{\"color\":\"#7500ca\",\"projectId\":-1,\"condColors\":[],\"name\":\"Dekki's meetings\",\"concurrence\":\"allow\",\"hideStartTime\":false,\"issueFields\":[{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.project\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"event.summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.users\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.reporter\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.description\",\"showEvent\":true,\"showInfo\":true}],\"summaryFromSourceName\":false,\"summaryFromIssueSummary\":false}"
}

404 status code is returned for non-existing sourceId or when the sourceId belongs to a calendar that is not associated with the token.

POST /api/1/event/search

Searches for events.

Only events from sources with type key vacation, sickness, trip, meeting or custom are returned.

JSON body parameters:

startDate		long	Unix milliseconds timestamp. Mutually exclusive with startDateIso and endDateIso.
endDate			long	Unix milliseconds timestamp. Mutually exclusive with startDateIso and endDateIso.
startDateIso	string	ISO 8601 date and time. Mutually exclusive with startDate and endDate.
endDateIso		string	Unix milliseconds timestamp. Mutually exclusive with startDateIso and endDateIso.
calendarId		long    Id of the calendar to fetch events from. Mutually exclusive with sourceId.
sourceId		long    Id of the source to fetch events from. Mutually exclusive with calendarId.

Interval between start and end dates should be less than 92 days (i.e. a quarter).

JSON body parameters samples:

  1. Period passed as Unix milliseconds and calendarId:

{
  "startDate": 1672531200000,
  "endDate": 1680307200000,
  "calendarId": 1959
}

Here:
- startDate corresponds to Sun Jan 01 2023 00:00:00 GMT
- endDate corresponds to Sat Apr 01 2023 00:00:00 GMT

2. Period passed as ISO dates and sourceId:

{
  "startDateIso": "2023-01-01T00:00:00-05:00",
  "endDateIso": "2023-04-01T00:00:00-04:00",
  "sourceId": 5655
}

Here:
- startDateIso corresponds to Sun Jan 01 2023 00:00:00 EST
- endDateIso corresponds to Sat Apr 01 2023 00:00:00 DST

Successful response brings JSON with matching events:

As for now, values are non-paginated and all matching events are returned. We might introduce the pagination should we see the need.

See the response sample:

 Click here to expand...
{
    "maxResults": 2147483647,
    "startAt": 0,
    "total": 16,
    "values": [
        {
            "sourceId": 5655,
            "userKeys": [
                "63c16312eac4f07e3f3c4650"
            ],
            "author": "63c16312eac4f07e3f3c4650",
            "allDayStart": "2023-01-01",
            "allDayEnd": "2023-01-01",
            "created": 1673618588000,
            "summary": "Dekki's 1st January meeting",
            "id": 13473
        },
        {
            "sourceId": 5655,
            "endDate": 1672736400000,
            "startDate": 1672732800000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1673341200000,
            "startDate": 1673337600000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1673622600000,
            "startDate": 1673620800000,
            "userKeys": [
                "63c16312eac4f07e3f3c4650"
            ],
            "author": "63c16312eac4f07e3f3c4650",
            "updateAuthor": "63c16312eac4f07e3f3c4650",
            "created": 1673618378000,
            "summary": "fisrt gedru's meeting",
            "updated": 1673618498000,
            "id": 13471
        },
        {
            "sourceId": 5655,
            "endDate": 1673778600000,
            "startDate": 1673776800000,
            "userKeys": [
                "63c16312eac4f07e3f3c4650"
            ],
            "author": "63c16312eac4f07e3f3c4650",
            "created": 1673618484000,
            "summary": "second dekki's meeting",
            "id": 13472
        },
        {
            "sourceId": 5655,
            "endDate": 1673946000000,
            "startDate": 1673942400000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1674550800000,
            "startDate": 1674547200000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1675155600000,
            "startDate": 1675152000000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1675760400000,
            "startDate": 1675756800000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1676365200000,
            "startDate": 1676361600000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1676970000000,
            "startDate": 1676966400000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1677574800000,
            "startDate": 1677571200000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1678179600000,
            "startDate": 1678176000000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1678784400000,
            "startDate": 1678780800000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1679389200000,
            "startDate": 1679385600000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1679990400000,
            "startDate": 1679986800000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        }
    ]
}

400 status code is returned when parameters validation fails. The status is accompanied with the error messages. E.g.:

404 status code is returned for non-existing calendarId or sourceId or when the calendarId or sourceId correspond to a calendar that is not associated with the token.

In case you need to create or edit events via the REST API, please add an appropriate comment under CJ-4727 - Getting issue details... STATUS .

In case you need to create or edit calendars or sources via the REST API, please add an appropriate comment under CJ-4733 - Getting issue details... STATUS .

You might need to log-out from our Service Desk https://brizoit.atlassian.net/servicedesk to comment under these public issues. This is a known Jira bug.

  • No labels