Getting Started - Intake

This step-by-step guide will quickly get you started with the Xelion Configurator - Intake.

The goal of the Intake application is to retrieve a Xelion Configurator configuration in an easily understandable and visually appeasing way.

You have to integrate this application into your own webpage. The application works standalone i.e. it only uses JSON-in, JSON-out.
Settings of the Intake application can be set in advance using the Portfolio Manager. The result of the Intake application can be used by the Provisioning phase.

See this example stand-alone

Preparing your page

Before writing any code for the element, you need to do the following preparation steps on your page:

• Include JavaScript file

  <script src="https://orderconfigurator.xelion.com/libs/xelion-configurator/latest/js/xoc-intake.js"></script>

• Put a div element with a certain id where you want your Xelion Configurator to be placed:

  <div id="xelionid"></div>

Now you're ready to initialize the application and start using it.

Initialization

All that is left now is to initialize the Intake application with an initial configuration. See JSON reference for all options. Call the next piece of code at the end of your page, or at least after the <div id="xelionid"> tag.

<script>
	const inputConfiguration = {
		version: 1,
		organization: {
			name: 'MyOrganizationName',
		},
		departments: [
			{
				name: 'Reception',
				internalNumbers: ['300'],
				fallback: {
					type: 'voicemail',
				},
			},
		],
	};

	const options = {
		elementId: 'xelionid',
		inputConfiguration: inputConfiguration,
	};

	XelionOrderConfigurator.create(options);
</script>

You should get the following result:

See this example stand-alone

Congratulations! You have successfully integrated the Intake application into your page. But we have no way to retrieve our configuration yet. Let's look into this and some other features.

Callbacks

If you would like the configurator to provide you with controls, we provide the OK and Cancel callback functions. By passing these functions, you can retrieve the resulting configuration or cancel your operation from within the application.

If the callbacks are not defined, the buttons will not be shown. Note that the OK button will not be shown if the configuration is invalid.

<script>
	const inputConfiguration = {
		version: 1,
		organization: {
			name: 'MyOrganizationName',
		},
		departments: [
			{
				name: 'Reception',
				internalNumbers: ['300'],
				fallback: {
					type: 'voicemail',
				},
			},
		],
	};

	function okCallback(configuration) {
		alert("OK!\n" + JSON.stringify(configuration, null, 2));
	}

	function cancelCallback() {
		alert("CANCEL!");
	}

	XelionOrderConfigurator.create({
		elementId: 'xelionid',
		inputConfiguration: inputConfiguration,
		okCallback: okCallback,
		cancelCallback: cancelCallback,
	});
</script>

You should get the following result:

See this example stand-alone

Getting current configuration

You might want to do something with the result of the page. The current configuration of the application can be requested using the getCurrentConfig function on the XelionOrderConfigurator object. For example, you can use this to retrieve the configuration when the user presses a button on your page, outside of the application.

Note that you will receive an error if the configuration is invalid. You can catch this error with a try-catch clause.

In the example below we now also inline the options variable in the call to create instead of creating a separate variable.

<button id="get-config-button">Get Current Configuration</button>
...
<script>
	const inputConfiguration = {
		version: 1,
		organization: {
			name: 'MyOrganizationName',
		},
		departments: [
			{
				name: 'Reception',
				internalNumbers: ['300'],
				fallback: {
					type: 'voicemail',
				},
			},
		],
	};

	const configurator = XelionOrderConfigurator.create({
		elementId: 'xelionid',
		inputConfiguration: inputConfiguration,
	});

	document.getElementById("get-config-button").addEventListener("click", () => {
		try{
			const configuration = configurator.getCurrentConfig(); // this can throw an error
			alert("Config!\n" + JSON.stringify(configuration, null, 2));
		} catch(e) {
			alert("Error in config! Cause:\n" + e);
		}
	});
</script>

You should get the following result:

See this example stand-alone

Changing language

It is possible to change the language of the Intake, by providing the locale parameter during construction.

If the callbacks are not defined, the buttons will not be shown. Note that the OK button will not be shown if the configuration is invalid.

<script>
	const inputConfiguration = {
		version: 1,
		organization: {
			name: 'Meine Organisation',
		},
		departments: [
			{
				name: 'Rezeption',
				internalNumbers: ['300'],
				fallback: {
					type: 'voicemail',
				},
			},
		],
	};

	function okCallback(configuration) {
		alert("OK!\n" + JSON.stringify(configuration, null, 2));
	}

	function cancelCallback() {
		alert("CANCEL!");
	}

	XelionOrderConfigurator.create({
		elementId: 'xelionid',
		inputConfiguration: inputConfiguration,
		okCallback: okCallback,
		cancelCallback: cancelCallback,
		locale: "de",
	});
</script>

You should get the following result:

See this example stand-alone

Reference

.create

The create function is the entry-point of the application and starts rendering the Intake application on the page:

const options = {
	elementId: 'my-element-id',
	inputConfiguration: inputConfiguration,
	okCallback: (configuration) => {},
	cancelCallback: (configuration) => {},
	locale: "en",
};

function create(options) {...};

The options field is an object which can have the following properties:

Field	Type	Required	Description
elementId	String	Yes	Id of the html element on this page where the application should start.
inputConfiguration	Object	No	Input to start the application with a predefined configuration.
okCallback	Function: (configuration) => { .. })	No	When specified, will show an [OK] button in the application, which on click will execute the specified function. The function will provide the output of the current configuration as the first parameter to the function as an object.
cancelCallback	Function: () => { .. })	No	When specified, will show a [CANCEL] button in the application, which on click will execute the specified function.
locale	String	No	When specified, will change the language of the configurator. Valid options are: en - UK English (default) nl - Dutch de - German

.getCurrentConfig

The getCurrentConfig function allows extracting the current state of the Intake application. If the configuration is invalid, an error is thrown, which can be caught with a try-catch clause.

function getCurrentConfig()

Limitations

There are some limitations to the Intake configuration.

• The application is meant to be loaded only once on a page.
• Internally the application is a React application using redux. Due to the nature of React and redux, this application might not work if the page you are integrating this configurator in is also a React/redux application.

What's next?

Now that you've learned the basics, you can start integrating straight away! Don't forget to take a look at the Portfolio Manager and JSON reference.
You can also get started with the Provisioning of your order and its API.