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 Master Tenant, which we then use to create 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:
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.
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
- tenant database id = databaseId
- tenant name = subDatabaseName
Retrieve Master Tenant and Tenant Token
Next, we use the Park Manager API to retrieve a session on the Master Tenant, which we then use to create a session on the Tenant we just started.
POST /api/v1/park/servers/[serverName]/login| Header | Required | Example | Description |
|---|---|---|---|
| X-Auth-Key | Yes | K2Kj5AK4jh3BI2loxXQ28saZj4ru6SGF | Park API key |
| Parameters | Required | Example | Description |
| serverName | Yes | MT01 | Name of the park server. See server.name 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 master tenant on this server. The interesting values for the configurator are:
- master tenant token = authentication
With the master tenant token we can now create a session on the Tenant we just started. We need to call the Xelion API for this, not the Park API.
POST [xelion server url]/api/v1/master/tenants/[tenant database id]/login| Header | Required | Example | Description |
|---|---|---|---|
| Authorization | Yes | xelion ab8105613405abdf9856ab6754f75b985a95f09eea8e65f8d5eadbv4560a9bb3b2 | Authorization/Session token of the Xelion Master Tenant. |
| Parameters | Required | Example | Description |
| Xelion server url | Yes | https://my.xelion.server.com | URL to Xelion server. See server.scheme://server.fqdn in start-new-tenant response. |
| tenant database id | Yes | 1 | Database ID of the Tenant. See databaseId in start-new-tenant response. |
See the Xelion API login-through call for details. The response body will contain the Xelion login details of the specified tenant. The interesting values for the configurator 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.