Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

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

MethodGET

Description: Query all known usernames.

...

Code Block
languagenone
{
    "users": [
        "alice@example.org", 
        "bob@example.org", 
        "carol@example.org"
    ]
}

/users/{username}

Method: GET

Description: Query a specific user.

...

Code Block
languagenone
$base_url/api/v0/users/alice@example.org

Example response body


Info

Please note the attributes property can be null.


Code Block
languagenone
{
    "username": "alice@example.org",
    "displayName": "Alice",
    "locale": "nl",
    "attributes": [
        {
            "name": "urn:mace:dir:attribute-def:displayName",
            "values": [
                "Alice"
            ]
        },
        {
            "name": "urn:mace:dir:attribute-def:mail",
            "values": [
                "alice@example.org"
            ]
        },
        {
            "name": "urn:mace:dir:attribute-def:eduPersonAffiliation",
            "values": [
                "member",
                "student"
            ]
        },
        {
            "name": "urn:mace:dir:attribute-def:eduPersonPrincipalName",
            "values": [
                "alice@example.org"
            ]
        }
    ],
    "roles": [
        "ROLE_MEMBER",
        "ROLE_STUDENT"
    ]
}

Response code

200 (OK), 404 (Not Found) if the user does not exist

/users (MyTimetable 2019.16+)

Method: POST

Description: Creates a user with the specified username.

...

NameDescriptionDefault value
username (required)
Username of the user.-
displayName Display Name of the user-null
localeLocale of the user, or empty for the default locale.-null
attributesAttribute for the user. This form value can be set multiple times. The format used is attributeName=attributeValue. When multiple values with the same attributeName are given, all attributeValues are persisted. See example request below.[]
rolesRoles of the user. This form value can be set multiple times.[]

...

Code Block
languagenone
{
    "username": "alice@example.org",
    "displayName": "Alice",
    "locale": "nl",
    "attributes": [
        {
            "name": "urn:mace:dir:attribute-def:displayName",
            "values": [
                "Alice"
            ]	
        },
        {
            "name": "urn:mace:dir:attribute-def:mail",
            "values": [
                "alice@example.org"
            ]
        },
        {
            "name": "urn:mace:dir:attribute-def:eduPersonAffiliation",
            "values": [
                "member",
                "student"
            ]
        },
        {
            "name": "urn:mace:dir:attribute-def:eduPersonPrincipalName",
            "values": [
                "alice@example.org"
            ]
        }
    ],
    "roles": [
        "ROLE_MEMBER",
        "ROLE_STUDENT"
    ]
}

...

201 (Created) if the user is created, 400 (Bad Request) if input validation fails, 409 (Conflict) if a user with the given username already exists

/users/{username}

MethodPUT

Description: Ensures a user with the specified username and properties existsa user with the specified username and properties exists.

Warning

Please note that properties of a user can be changed by other actions as well. For example, if you provision the user with two attributes, a subsequent login by the user might overwrite these two attributes with new values or add more attributes (as provided by the authentication provider). Another example is the user changing its locale in the interface. Please keep this in mind when updating user properties.


Parameters

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


Request body form values (MyTimetable 2019.16+)

Info
titleBehaviour

If no request body is sent, the following behaviour is used:

  • User does not exist: user is created
  • User already exists: nothing is changed
  • In either case, no response body is returned

If a request body is sent, the following behaviour is used:

  • User does not exist: user is created with the properties set as requested via the request body (otherwise they are not set)
  • User already exists: the properties of the user are updated with updated (or unset) with the properties set as requested via the request body (otherwise they are unchanged)
  • In either case, the user is returned as the response body

...

NameDescriptionDefault value
displayNameDisplay name of the user-null
localeLocale of the user, or empty for the default locale.-null
attributesAttribute for the user. This form value can be set multiple times. The format used is attributeName=attributeValue. When multiple values with the same attributeName are given, all attributeValues are persisted. See example request below.[]
rolesRoles of the user. This form value can be set multiple times.[]

...

  • If no request body is sent: 204 No Content
  • If a request body is sent: 201 Created (user newly created), 200 OK (user updated), or 400 (Bad Request) if input validation fails

/users/{username}

MethodDELETE

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

...

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

/users/{username}/synchronizations

MethodGET

Description: Query all synchronizations for a user.

...

Code Block
languagenone
{
    "synchronizations": [
        {
            "id": 1, 
            "type": "ews", 
            "username": "alice",
			"description": "alice@bob.test",
            "enabled": true,
		    "status": "OK",
            "lastResync": 1355320800000
        }
    ]
}

/users/{username}/synchronizations

MethodDELETE

Description: Delete all synchronizations for a user.

...

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

/users/{username}/synchronizations/{type}

MethodDELETE

Description: Delete synchronizations of a certain type for a certain user.

...

Example response body: none (status code 204 indicates success; 404 indicates no synchronizations found; 422 indicates invalid synchronisation type)

Synchronization resources

/synchronizations

MethodGET

Description: Query all synchronizations.

...

Code Block
languagenone
{
    "synchronizations": [
        {
            "id": 1, 
            "type": "o365", 
            "username": "alice",
			"description": "alice@bob.test",
            "enabled": true,
		    "status": "OK",
            "lastResync": 1355320800000
        },
        {
            "id": 1, 
            "type": "googlecalendar", 
            "username": "bob",
			"description": "bob@google.test",
            "enabled": true,
		    "status": "OK",
            "lastResync": 1355320800000
        }
    ]
}

/synchronizations

MethodPUT

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

...

Code Block
languagenone
{
    "synchronization":
        {
            "id": 1, 
            "type": "ews", 
            "username": "alice@example.org",
			"description": "alice@bob.test",
            "enabled": true,
		    "status": "OK",
            "lastResync": 1355320800000
        }
}

Response code: 200 OK, 422 Unprocessable Entity (username does not exist or synchronization type is not known), 550 Permission Denied (access not granted to mailbox)

/synchronizations/{id}

MethodDELETE

Description: Deletes the synchronization with the specified id.

...

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:

...