Provisioning - Xelion Configurator

Provisioning Guide

The Xelion Configurator allows you create a JSON configuration of a planned Xelion system. You can use this configuration to provision an actual Xelion tenant.

This provisioning service is available through a REST API. You make a HTTP call to the provisioning service, containing your tenant info and your JSON configuration, and we will do the rest. If you are using a Xelion Park Manager, please visit the Park Provisioning section for details on how to acquire the tenant information.

For full details, see the complete REST API.

Security

The API requires authentication for most calls. An API key is required for authentication.

The security model is based around an organization. You make calls using an API key linked to an organization. New provisioning orders are linked to that organization.

The security model is structured as a tree, meaning that you can create sub-organizations, with your current organization as the parent. A parent organization can manage all orders belonging to itself AND its child organizations. The parent has full access to itself and child organizations. For example, say we have organization P, which is the parent of organizations A and B. Then:

Organization A can see orders of Organization A, but not B or P.
Organization B can see orders of Organization B, but not A or P.
Organization P can see orders of Organization P, and A and B.

For example, this allows a distributor to manage its resellers, or resellers manage sub-resellers. If you wish to give a new customer access to the provisioning service, you create a new organization and generate an API key for that new organization. Because you have authenticated as your own organization, you are automatically set as the parent of the new organization.

Storing Third-Party Credentials

Certain steps of the provisioning might require extra calls to external services, such as SIP Trunk, redirection servers, etc. These external services might require additional authentication, and for this we have provided a way to store and link these credentials to an organization as described in the Security section.

Organization Credentials are stored encrypted, and can not be recovered through the API once created, but will be used during provisioning of a tenant. Once provided for an organization, every new provisioning order will be able to use these credentials. Credentials are stored as key-value pairs. See the API for more details and restrictions on the key name.

Requirements Xelion Tenant

The provisioning phase uses the Xelion API to configure the tenant. This means that in order to correctly provision the tenant, some requirements must be met on the Xelion Tenant.

The server must use HTTPS. The Xelion API does not allow access on HTTP.
The tenant must be started. The Xelion API only works on started tenants.
The default 'beheerder'/'admin' account must not be using the default password. Not only is this a security risk, but also the Xelion API will error when you call the /me/login with the default password to obtain the Xelion session token for Xelion-Tenant-Token. The configurator has a pristine check in place to prevent this security risk.
The tenant must be assigned enough user licenses. The user licenses are required because otherwise the provisioning cannot create the user accounts, as the Xelion API will error when trying to create a Xelion user without an available user license.

Provision

The provision endpoint is the entry-point of the provisioning service, creates an order from the specified configuration an schedules the order for execution. You must provide the information to access Xelion API of the tenant using the specified headers.

If you are using a Xelion Park Manager, please visit the Park Provisioning section for details on how to acquire these values.

POST /api/v1/provision

Header	Required	Example	Description
Xelion-Server-Url	Yes	https://my.server.xelion.com	URL to the Xelion Server
Xelion-Tenant-Name	Yes	pbx1	Name of the Xelion Tenant
Xelion-Tenant-Token	Yes	5944594058c3bb4b04d5c9db3072b30d56e513c13b9be4c9b2e0ae5734c6f99ac8	Authorization/Session token of the Xelion Tenant. See Xelion API on how to obtain this.
X-Callback-Url	No	https://my.callback.server.com/url/endpoint	URL to which order status changes are sent

You must pass the JSON configuration from the Configurator as the request body:

{
	"version": 1,
	"organization": {
		"name": "Fairy Tail"
	}
}

If everything is ok, you will receive the following response, containing a reference to the order id. You can use the Admin UI with this id to reference to your order.

{
	"id": 42
}

Callback / Webhook

If you passed the X-Callback-Url header in your provisioning request, then the server will notify you of changes to the order's status by sending a POST http request to that url. This is called a webhook, and can for example be used to notify your server when an order has started, has completed or has failed.

The body of the message being sent is as follows:

{
	"mid": 2,                     // Unique, chronological message id
	"type": "orderStatusChanged", // Type of the message, used to identify the data content
	"data": {                     // Message data
		"id": 1,                  // Id of the order
		"status": "FAILED"        // New status of the order. Possible values:
		                          // NOT_STARTED | IN_PROGRESS | FAILED | COMPLETED
	}
}

Test Provisioning

In order to test a configuration without submitting it as a new order, a test endpoint has been made available. Only the body of the request is tested, and as such no headers are required.

POST /api/v1/provision/test

You must pass the JSON configuration from the Configurator as the request body:

{
	"version": 1,
	"organization": {
		"name": "Fairy Tail"
	}
}

If everything is ok, you will receive a 200 OK response without a body. Otherwise you will receive a 400 Bad Request response with a body containing the cause of the error.