6. Wizard Configuration

This page contains information on configuring the Premium App Wizard installation logic.

• Summary of Properties
• Properties Description
• Premium App Modules

In this video, learn how to configure the properties of your Premium App Wizard.

The following configuration properties define the behavior of the Premium App. This is where most of the customization takes place.

Please take note of the required properties which must be updated from their default values.

The path of the config file is: docs/wizard/config/config.js.

• clientID
• wizardUriBase
• redirectURLOnWizardCompleted
• redirectURLWithParams
• premiumAppIntegrationTypeId
• enableUninstall
• prefix
• provisioningInfo
• premiumAppViewPermission

• premiumWidgetIntegrationTypeId
• checkInstallPermissions
• defaultLanguage
• availableLanguageAssets
• enableLanguageSelection
• languageQueryParam
• genesysCloudEnvironmentQueryParam
• enableCustomSetupPageBeforeInstall
• enableCustomSetupStepAfterInstall
• enableDynamicInstallSummary

The Implicit Grant Client ID used by the Wizard.

The default value must be replaced by your own Client ID created in the development org. For more details in creating an OAuth Client click here.

The base of the URL where your install wizard is hosted. Note, this is only the base, the install wizard will append page names to this value.

For default testing this would be: http://localhost:8080/wizard/

In production, this would be a URL hosted on your platform, e.g. https://yourcompany.com/product/wizard/

The URL of the landing page of your web app.

For default testing this would be: http://localhost:8080/premium-app-sample/index.html.

In production, this would be a URL hosted on your end eg. https://yourcompany.com/product/app

If enabled, this will add both the environment and language query parameters to the redirectURLOnWizardCompleted URL.

Unique ID for your Premium App provided by Genesys Cloud.

During initial development please use the default premium-app-example. Once your premium app has been approved by the AppFoundry Team, an integration type ID will be provided and then this property must be updated.

Allows you to deprovision the installed object by adding the query parameter uninstall=true in the wizard URL. This is merely for testing and should be set to false in production.

This string is prefixed to the names of Genesys Cloud objects created by the wizard.

Default: PREMIUM_EXAMPLE_

Recommended format: COMPANY_YOURPRODUCT_

If the prefix still contains common words then please try to make it as unique or original as possible. This will help lessen the chance of conflict with existing or possible future object names.

These are the Genesys Cloud items that will be added and provisioned by the wizard.

Each type of object that could be provisioned by Genesys Cloud is defined by a module. The following objects are supported:

• Role
• Group
• OAuth Client
• App Instance
• Interaction Widget
• Widget Deployment
• Webservices Data Actions Integration
• Data Table

The config.js file only provisions a portion of the possible modules. For a complete reference, please consult sample-provisioning-info.js which includes samples for all objects.

If your Premium App requires the provisioning of a non-supported object type then you'll need to create a custom module. Jump to the section by clicking here

The minimum permission required for a user to access the Premium App.

During initial development please use the default permission integration:examplePremiumApp:view. Once your premium app is approved, the unique integration domain will be generated and this must be updated.

(Optional) Unique ID for your Premium Widget provided by Genesys Cloud.

During initial development please use the default premium-widget-example. Once your premium app has been approved by the AppFoundry Team, an integration type ID will be provided and then this property must be updated.

Permission groups required for running the Wizard App.

Valid values: all, premium, wizard, none (default)

Permission groups are arrays of permissions defined in the installPermissions property of the configuration file.

Values description:

• all - Requires all permissions in the installPermissions property and the permission defined in premiumAppViewPermission.

Note: installPermissions.postCustomSetup is only checked if enableCustomSetupStepAfterInstall is true.

• premium - Only requires the permission defined in the premiumAppViewPermission property.
• wizard - Requires all permissions defined in the installPermissions property.

Note: installPermissions.postCustomSetup is only checked if enableCustomSetupStepAfterInstall is true.

• none (Default) - Will not check for permissions when running the install wizard.

Default language if somehow language was not determined dynamically. Normally, the language should be identified by the a query parameter in the Premium App URL.

The value should have a corresponding JSON file in wizard/assets/languages/ directory.

List available language assets - manage gcLangTag with possible formats like: en, en-US, enUS, en-CA, enCA, etc. Values in lower case, using - or no separator.

Enable language selection. If set to true, a language selector will appear in the upper right of the app. The values are determined by availableLanguageAssets.

The query parameter for determining the language. Default Value: langTag.

ie. https://my-premium-app.com/wizard/index.html?langTag=en-us

Only change this if you want to use a different name for the query parameter.

The query parameter for determining the Genesys Cloud environment. Default Value: environment.

ie. https://my-premium-app.com/wizard/index.html?environment=mypurecloud.com

Only change this if you want to use a different name for the query parameter.

The query parameter for determining the Genesys Cloud Host Origin. Default Value: hostOrigin.

ie. https://my-premium-app.com/wizard/index.html?hostOrigin=https://apps.mypurecloud.de&targetEnv=prod-euc1

Only change this if you want to use a different name for the query parameter.

The query parameter for determining the Genesys Cloud Target Environment. Default Value: targetEnv.

ie. https://my-premium-app.com/wizard/index.html?hostOrigin=https://apps.mypurecloud.de&targetEnv=prod-euc1

Only change this if you want to use a different name for the query parameter.

Enable the optional 'Step 2' in the provisioning process. If false, it will not show the page or the step in the wizard.

Example:

enableCustomSetupPageBeforeInstall is true:

enableCustomSetupPageBeforeInstall is false:

To know more about modifying the custom setup page, click here.

Enables the Post Custom Setup module in the install process. If true, it will invoke the postCustomSetup module (configure method) after the Genesys Cloud ones (provisioningInfo).

Enable this if you want to do additional or custom processing after the creation of objects.

To know more about Post Custom Setup, click here

Enable the dynamic build of the Install Summary to reflect items on the provisioningInfo

This way you don't have to manually modify the INSTALLATION DETAILS PAGE section in index.html Note that you may still have to update the text contained in the language assets folder to make each object section more descriptive.

Example if enabled:

The sections were dynamically generated through the onInstallDetailsEnter function in main.js.

A module represents a type of Genesys Cloud resource like a Role, a Group, etc. These modules are what creates, removes and configures the objects declared in the provisioningInfo property of the config.js file.

In the sample install wizard, objects such as Role, Group, App Instance, OAuth, Data Table and Interaction Widget are provided and ready to be consumed in the config.js file. These modules can be found in /docs/wizard/scripts/modules folder.

If your Premium App requires the creation of a Genesys Cloud object not currently supported, then a custom module needs to be created.

Each module should have one file with the the following functions:

• getExisting() - return a Promise resolving to an array. This array contains the entities of the Genesys Cloud object search.
• remove(logFunc) - returns a Promise resolving to an array. The array contains the return object for each Genesys Cloud entity deleted.

logFunc is a function that takes a string and is used to display a message in the app.

• create(logFunc, data) - returns a Promise resolving to an object. The object's keys are the names of every entity created of this type, with the value being the API response from Genesys Cloud upon creation.

logFunc (Function) takes a string and is used to display a message in the app.

data (Array) contents of the type found in provisioningInfo.

• configure(logFunc, installedData, userId) - returns a Promise.

Some Genesys Cloud objects cannot be fully configured upon creation and some may depend on other objects being created first. This function provides ability to further call other APIs after all objects have been provisioned.

logFunc (Function) takes a string and is used to display a message in the app.

installedData (Object) contains all the data of the created objects.

userId (String) User ID of current user if needed.

These functions should also be exported by the script module and a provisioningInfoKey key (eg. role, group, etc.) which identifies the keyword for the resource. This should match the keyword for the provisioningInfo in the configuration file.

Please refer to existing modules for more detailed examples on how they are structured.

Finally, add the import to the modules array in wizard.js

ie:

let modules = [
    roleModule,
    groupModule,
    appInstanceModule,
    OAuthClientModule,
    dataTableModule,
    interactionWidget,
    wsDataActions,
    widgetDeployment
];

The Premium Application Install Wizard makes use of both the Genesys Cloud Platform SDK and the Client Apps SDK. Once you fork the example code for your own installation wizard, it will be imperative that you keep the versions of those SDKs up to date. The most important reason for this is that as new AWS regions are supported by Genesys Cloud they are added to the SDKs. If your installer isn't kept up to date with the latest SDK versions then it may not operate on customers in newer regions.

The SDK references are located in the docs/wizard/index.html.

To be notified of new SDK release updates please subscribe to notifications on our Announcement forum in the Genesys Cloud Developer Center Form or follow us on Twitter @GenesysCloudDev

The latest version of the Genesys Cloud Platform SDK for Javascript should always be included by default.

<script src="https://sdk-cdn.mypurecloud.com/javascript/latest/purecloud-platform-client-v2.min.js"></script>

The Client Apps SDK, unlike the Platform SDK, doesn't provide a latest version. Therefore, from time to time you may need to verify that your install wizard is using the latest version.

<script src="https://sdk-cdn.mypurecloud.com/client-apps/2.6.3/purecloud-client-app-sdk.js"></script>

Proceed to Custom Setup