Provisioning

Introduction

The provisioning API is an admin-only API used to create users and push synchronisations in MyTimetable. This API can be used in your user provisioning processes to support an push synchronisation 'opt-out' scenario. The API is supported from MyTimetable version 3.0, and only supports JSON output and form-encoded input.

User resources

/users

Method: GET

Description: Query all known usernames.

Parameters: none

Request URL

$base_url/api/v0/users

Example response body

{
    "users": [
        "alice", 
        "bob", 
        "carol"
    ]
}

/users/{username}

Method: PUT

Description: Ensures a user with the specified username exists.

Parameters

Name	Description	Default value
`username` (required)	The username for which a user profile should be created if it doesn't exist already.	-

Example request URL

$base_url/api/v0/users/alice

Example response body: none (status code 204 indicates success/user already exists)

/users/{username}

Method: DELETE

Description: Deletes the user profile with the specified username if it exists.

Parameters

Name	Description	Default value
`username` (required)	The username for which a user profile should be deleted if it exists.	-

Example request URL

$base_url/api/v0/users/alice

Example response body: none (status code 204 indicates success/user not found)

Synchronization resources

/synchronizations

Method: GET

Description: Query all synchronizations.

Parameters: none

Request URL

$base_url/api/v0/synchronizations

Example response body

{
    "synchronizations": [
        {
            "id": 1,
            "username": "alice",
            "type": "o365"
        },
        {
            "id": 2,
            "username": "bob",
            "type": "googlecalendar"
        }
    ]
}

/synchronizations

Method: PUT

Description: Sets up a synchronization with a user's external calendar.

Parameters

Name	Description	Default value
`username` (required)	The username for which the synchronization should be created.	-
`type` (required)	The synchronization type, which indicates the calendaring service provider.	-
provisioning_smtpAddress *	The user's mailbox address in Exchange or Office 365.	-

* Only applicable when using a ProvisioningPreDelegatedEWSLinkingAdapter or ProvisioningPreAuthorizedOffice365LinkingAdapter.

Example request URL

$base_url/api/v0/synchronizations

Example request body (application/x-www-form-urlencoded)

username=alice&type=ews&provisioning_smtpAddress=alice@example.org

Example response body: none (status code 204 indicates success)

/synchronizations/{id}

Method: DELETE

Description: Deletes the synchronization with the specified id.

Parameters

Name Description Default value

id (required) The id of the synchronization which should be deleted. -

unlinkMode (required)

The unlink mode indicates what should happen to the events in the user's calendar:

UNLINK_ONLY Leaves all events in place.
DELETE_FUTURE_EVENTS Only events which have been pushed with this specific synchronization id and which have a start date in the future are removed.
DELETE_ALL_EVENTS All events which have been pushed with this specific synchronization id are removed.
CLEANUP All events which have been pushed by this MyTimetable instance are removed, even those with a different synchronization id.

-

Example request URL

$base_url/api/v0/synchronizations/3?unlinkMode=UNLINK_ONLY

Example response body: none (status code 204 indicates success; 422 indicates synchronization not found)

Sample usage

If you want to create a large number of synchronisations, create a text file with the username and email address of the users. Then you can run the following shell script to create the users:

while read user mail
do
curl -v -X PUT -H apiToken:xxx https://mytimetable_host/api/v0/users/$user
done < users.txt

The following script will create an 'o365' synchronisation for each user:

while read user mail
do
curl -v -X PUT -H apiToken:xxx -d username=$user -d type=o365 -d provisioning_smtpAddress=$mail https://mytimetable_host/api/v0/synchronizations
done < users.txt