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; 404 indicates user not found)
/users/{username}/synchronizations
Method: GET
Description: Query all synchronizations for a user.
Parameters:
| Name | Description | Default value |
username (required) | The username for which the synchronization should be created. | - |
Example request URL
$base_url/api/v0/users/alice/synchronizations
Example response body
{
"synchronizations": [
{
"id": 1,
"type": "ews",
"username": "alice"
}
]
}
/users/{username}/synchronizations
Method: DELETE
Description: Delete all synchronizations for a user.
Parameters:
| Name | Description | Default value |
username (required) | The username for which the synchronizations should be deleted. | - |
unlinkMode (required) | The unlink mode indicates what should happen to the events in the user's calendar:
| - |
Example request URL
$base_url/api/v0/users/alice/synchronizations?unlinkMode=DELETE_ALL_EVENTS
Example response body: none (status code 204 indicates success)
/users/{username}/synchronizations/{type}
Method: DELETE
Description: Delete synchronizations of a certain type for a certain user.
Parameters:
| Name | Description | Default value |
username (required) | The username for which the synchronizations should be deleted. | - |
type (required) | The synchronization type, which indicates the calendaring service provider. | - |
unlinkMode (required) | The unlink mode indicates what should happen to the events in the user's calendar:
| - |
Example request URL
$base_url/api/v0/users/alice/synchronizations/ews?unlinkMode=DELETE_ALL_EVENTS
Example response body: none (status code 204 indicates success; 404 indicates no synchronizations found; 422 indicates invalid synchronisation type)
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:
{
"synchronization":
{
"id": 1,
"username": "alice",
"type": "ews"
}
}
/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:
| - |
Example request URL
$base_url/api/v0/synchronizations/3?unlinkMode=UNLINK_ONLY
Example response body: none (status code 204 indicates success; 404 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
A sample Powershell script:
$username = "username_in_MTT"
$type = "ews"
$smtpAddress = "user@host.nl"
$apiToken = "xxx"
# Create the user in MyTimetable if it does not exist
Invoke-RestMethod https://mytimetable_host/api/v0/users/${username} -Method PUT -Headers @{apiToken=$apiToken}
# Setup a synchronisation for the user
Invoke-RestMethod https://mytimetable_host/api/v0/synchronizations -Method PUT -Headers @{apiToken=$apiToken} -ContentType "application/x-www-form-urlencoded" -Body @{username=$username;type=$type;provisioning_smtpAddress=$smtpAddress}
# Delete the synchronisation for the user and remove all events from the calendar
Invoke-RestMethod https://mytimetable_host/api/v0/users/${username}/synchronizations/${type}?unlinkMode=DELETE_ALL_EVENTS -Method DELETE -Headers @{apiToken=$apiToken}