WebAPI

WebAPI is used as a server/gateway in conjunction with the Workbench for all third-party components that use REST. It provides the framework for these new features:

CFSWorX mobile health and integration with third parties
KPIWorX support for Apple Watch
Web Login with External Identity Providers (OIDC and SAML 2.0)
Voice Machine Interface and Text Machine Interface

In addition, WebAPI provides a REST endpoint for retrieving data points from FrameWorX and its point managers. The WebAPI REST endpoint is secured by OAuth 2.0, and supports writing to points. (Note, the OData Connector service still exists, and its endpoint is still functional.)

An example REST URI for the Web API service would be:

http://localhost/fwxapi/rest/data?pointname=svrsim:sine double med -100 100.

Configuration for the new features listed above will be described with those features. No configuration is necessary for the REST endpoint.

The Windows service associated with the WebAPI is the ICONICS WebAPI Service (IcoWebAPIService). This service must be running to support the REST endpoint and the aforementioned other features.

WebAPI can be used in property configuration for ICONICS applications' use with multiple providers, including Amazon Alexa, Microsoft Bot, and Google. Using this tool, users are able to set Providers' settings (values) as well as perform JSON Configuration File Actions.

Configuring ICONICS WebAPI Service

Installation

HTTPS

You must configure HTTPS binding in IIS. See https://docs.microsoft.com/en-us/iis/manage/configuring-security/configuring-ssl-in-iis-manager.

Url Rewrite (optional)

On the IIS server configured for Url Rewrite, disable �Reverse rewrite host in response headers� in Application Request Routing -> Server Proxy Settings.

Application Request Routing

Platform Services

In Platform Services, make sure you fill in the �Public origin� with the protocol and host name where the service will be accessible from the outside. This step is important, because the IdentityServer must be able to provide endpoint discovery at https://<host_name>/fwxserverweb/security/.well-known/openid-configuration.

Platform Services Configuration

Security

Open Workbench Desktop.
Open Security -> Web Login -> Global Settings (General Settings section).
Check �Enabled� and select some certificate (This step is important; otherwise, all issued tokens will be invalidated once the FwxServer is restarted).
Add �Relying parties� (right-click �OIDC Relying Parties� -> �Add OIDC Relying party�).

Add Relying Parties

Each service has different configuration, the OIDC Relying Party must be configured for each service individually.
Add users to the Security.

Add Users to Security

Providers

Providers, as they are explained below, pertain to the Voice Machine Interface configuration within GENESIS64.

To Add a Provider:

Expand your project in the Project Explorer, then expand the Platform Services node and then the Voice Machine Interface node.
Right-click on the Providers node, then click on Add Provider, as shown below.

Adding a Web API Provider from the Project Explorer

-OR-

Select the Providers node then click on the Add Provider button, shown below, in the Edit section of the Home ribbon in the Workbench.

Add Provider Button

This opens the Provider properties window in the Workbench, as shown below. Enter a name for the Provider in the Name text entry field.

Provider Properties

Configuration

Provider Type - Use the pulldown menu to select from Amazon Alexa, Microsoft Bot, or Google. Notice that changing the Provider Type will load its own corresponding set of Properties in the bottom section of the window.

Properties

Once your Provider Type is selected, you'll be able to enter values for associated properties.

Amazon Alexa

For Amazon Alexa, you can set CameraProxyHost and AssetTreeViewPath values by entering them in the appropriate cells within the Value column. For AssetTreeViewPath, you can also opt to click the button to open the Data Browser and navigate to your selected asset tree view path.

Microsoft Bot

For Microsoft Bot, you can set LuisAppVersion, LuisEntityDeviceID, LuisEntityDeviceName, LuiseEntitySceneID, LuisUrl, LuisEntitySceneName, and AssetTreeViewPath by entering them in the appropriate cells within the Value column. For AssetTreeViewPath, you can also opt to click the button to open the Data Browser and navigate to your selected asset tree view path.

Google

For Google, you can set the AssetTreeViewPath values by entering it in the appropriate cell within the Value column. You can also opt to click the button to open the Data Browser and navigate to your selected asset tree view path.

Click Apply and Close to save your Provider properties. Your new Provider will now appear beneath the Providers node in the Project Explorer.

JSON Configuration File Actions

Deploy JSON Configuration file

This option deploys a JSON configuration file to a target machine. Deployment can be done by exporting the configuration JSON file from the Workbench and replacing the one in C:\Program Files\ICONICS\Genesis64\WebSites\IcoWebAPIService.

Generate JSON Configuration file

This option exports a provider into a JSON configuration file.

To Generate a JSON Configuration file:

Expand your project in the Project Explorer, then expand the Platform Services node and then the Web API node.
Right-click on the Providers node, then click on Generate JSON Configuration file, as shown below.

Generate JSON Configuration file from the Project Explorer

-OR-

Select the Providers node then click on the Generate JSON Configuration file button, shown below, in the Tools section of the Home ribbon in the Workbench.

Generate JSON Configuration file Button

The Workbench will generate the JSON Configuration file and show the results as they are generated in the Recent Tasks section on the right side of the Workbench, as shown below.

Generate JSON Configuration File Task in the Recent Tasks Section of the Workbench

Once generated, you can perform multiple actions, as shown in the image below. Click on Download generated file.

Download generated file from Recent Tasks

This opens the Save As window, where you can decide where you would like to save your generated JSON Configuration File (in compressed [zipped] file format).

Import JSON Configuration file

This option imports a provider from a JSON configuration file.

To Import a JSON Configuration file:

Expand your project in the Project Explorer, then expand the Platform Services node and then the Web API node.
Right-click on the Providers node, then click on Import JSON Configuration file, as shown below.

Import JSON Configuration file from the Project Explorer

-OR-

Select the Providers node then click on the Import JSON Configuration file button, shown below, in the Tools section of the Home ribbon in the Workbench.

Import JSON Configuration file Button

This opens the Import Configuration window, as shown below.

Import Configuration Window

Provider - Enter the Provider type (Amazon Alexa, Microsoft Bot, or Google) in the text entry field.
File - Enter the location of the JSON Configuration file in the text entry field that you wish to import or click on the button to open a file browser to navigate to your selected JSON Configuration file to import.

Click OK to finalize your settings and return to the Workbench.