Provisioning with Park Manager

In order to provision correctly, it is required to provide details about the Xelion tenant to provision, such as how to access and authenticate against the tenant.

The Xelion Configurator is intended to be as standalone as possible, to be only able to access a single tenant per order. This means the Xelion Configurator does not have access to the Master Tenant of your Xelion server, and is therefor restricted in its actions regarding the tenant. For example, the Xelion Configurator cannot start a new tenant on your Xelion server, nor can it update the tenant name, set the number of user licenses on that tenant, or retrieve a tenant authentication token.

In order to assist with these tenant actions, you can use the Xelion Park Manager, which was designed with multi-tenant operations in mind.

For provisioning, the Configurator requires three fields with Xelion Tenant details:

The server url
The tenant name. Combined with the server url, the location of the tenant can be derived. Note: we need the tenant name, not tenant label.
A valid tenant authentication token. The token is used to perform the provisioning actions using the tenant's API.

In order to retrieve these details, we can use the Park Manager API. In short, we ask the Park Manager to find an available tenant in the park, change its name, set its licenses and start the tenant. Next, we use the Park Manager API to retrieve a session on the Tenant we just started. These steps are summarized in the following image, and in the sections below the steps are described in more detail: Park Provisioning Flow

Start new tenant

First we ask the Park Manager API to find us an available tenant in the park. Available tenants are tenants that have been loaded with a template or backup of a Xelion tenant, and are ready to be started. You must configure this in your Xelion Server.

Making calls to the Park Manager API requires authentication, which can be provided by passing an API key of an enabled, valid User account in your park, without expired password, as a header in the request to the Park Manager API.

In order to retrieve a new tenant for your configuration, you must have at least one Xelion server in your park meeting the following conditions:

Server must use HTTPS. Otherwise we cannot access the Xelion API.
All tenants of a server must have a status. There must be no tenants with an unknown status on a server in the park, as this means your server is behaving unexpected and we rather not use it for provisioning.
Park value 'Max Provisioning Tenants' must be less than number of tenant IN_USE + reserved tenants on this server. This is a way to tune the number of tenants used per server. This value can be set in the Server settings in your Park Manager.
Must have at least 'requestedLicenses' of user licences available on the server. The total number of licenses is defined by your installed Xelion licence file on your Master Tenant. When assigning licenses to tenants, the available number of user licenses on your server decreases. This check is to assure that you have enough user licenses available to fulfill the request of #requestedLicenses number of user licenses.
Must have at least one tenant with status AVAILABLE. Only available tenants can be started.

The server with the lowest score of 'tenants in use' x 'active user licences' is selected and asked to provide a tenant. The tenant will be provided by directly contacting the server using the Xelion API.

You can make the following call to the Park Manager. You can update the name and label of the found tenant by providing additional parameters. You can also provide the number of requested user licenses you wish to use on this server. In terms of the Configuration JSON, this is equal to the number of objects in the 'users' array.

POST /api/v1/park/start-new-tenant?name=...&label=...&requestedLicenses=..

Header	Required	Example	Description
X-Auth-Key	Yes	K2Kj5AK4jh3BI2loxXQ28saZj4ru6SGF	Park API key
Query Parameters	Required	Example	Description
name	Yes	pbx1	New name of the Tenant.
label	No	My PBX1	New label of the Tenant. If not specified, uses name.
requestedLicenses	No	5	Number of user licences to assign to tenant.

The response body will contain the started tenant details, as well as the server it was started on. The interesting values for the configurator are:

server url = server.scheme://server.fqdn
server name = server.name
park tenant id = tenant.id
tenant name = subDatabaseName

Retrieve Tenant Token

Next, we use the Park Manager API to retrieve a session on the Tenant

POST /api/v2/tenants/[parkTenantId]/login

Header	Required	Example	Description
X-Auth-Key	Yes	K2Kj5AK4jh3BI2loxXQ28saZj4ru6SGF	Park API key
Parameters	Required	Example	Description
tenantId	Yes	1	ID of the park tenant. See tenant.id in start-new-tenant response body.

See the Xelion API login call for details. The response body will contain the Xelion login details of the specfied tenant, with which you can start making API calls to Xelion. The interesting values are:

tenant token = authentication

Park provisioning summary

Now we have all the information we need to provision the tenant using the Configurator.

Header	Required	Example	Description
X-Auth-Key	Yes	A57G2Jaubj2Wdsygf401fju28OP4j2ds	Configurator API key.
Xelion-Server-Url	Yes	https://my.server.xelion.com	URL to Xelion server. See server.scheme://server.fqdn in start-new-tenant response.
Xelion-Tenant-Name	Yes	pbx1	Name of the Xelion Tenant. See tenant.subDatabaseName in start-new-tenant response.
Xelion-Tenant-Token	Yes	5944594058c3bb4b04d5c9db3072b30d56e513c13b9be4c9b2e0ae5734c6f99ac8	Authorization/Session token of the Xelion Tenant. See authentication field in tenant login response.

You can now use this information for the Provisioning.