How To: Configure IIS For The Integration Theme (KB20111101) (DriveWorks Documentation)

How To: Configure IIS For The Integration Theme

DriveWorks Live can run directly as an application or as a service through Internet Information Services (IIS) v10 or later (requires Windows 10 or Windows Server 2016 operating systems or later).

When running IIS on a Windows 10 machine, please be aware of the connection limit.

See IIS Connection Limit on Windows 10 for more information.

The advantages of using IIS include:

IIS provides faster transmission times between IIS and compression-enabled browsers
Dynamic Compression means faster load times for DriveWorks User Forms that display dynamic content (Pictures, DriveWorks 3D Files etc.) on the Client browser.
IIS runs as a service on your computer
This means that care must be taken when setting up credentials in IIS but has the benefit that the machine does not require to be logged on to run the application.

This article explains how to set up IIS so DriveWorks Live can be accessed without having to run the application.

Before you begin

Ensure Internet Information Services (IIS) is installed on the machine that will be the web server.

Please see How To: Install Internet Information Services (IIS) for more information.

Run DriveWorks Live (the application) on the Server machine before attempting to run through IIS

This includes the following steps:

Log on to the server machine using an account with sufficient privileges (make a note of the account used, as this will be used for the Application Pool Identity when IIS is set up).
Install DriveWorks Live
License DriveWorks Live
This can be done either by:
- Launching DriveWorks Live and connecting to the license server, once the Licensing wizard appears.
  Please see Licensing DriveWorks Live for more information.
  Or
- Using Environment Variables to hold the License Server address.
  Please see How To: License DriveWorks Live Using Environment Variables for more information.
  This is particularly useful when you only have access to the web root.
Connect to the Group from which the Projects will be specified.
Ensure all Projects will run by specifying them through the Specification Explorer in DriveWorks Live.
Read the following caution notes about specific items in your projects.

IIS and mapped network drives

To run DriveWorks Live through IIS, your Project should not use any mapped network drives. Mapped network drives are user specific, therefore it is much harder to ensure that the user you set up in IIS can access them.

All network locations should therefore be specified using a UNC (Uniform Naming Convention) path, for example:

\\< ServerName>\< ShareName>\ProjectFile.

Paths that should be specified using UNC include:

The Default Specification folder
Fully qualified paths used by Specification Flow Task properties.
Images presented on User Forms (although these can be relative to the Project rather than full paths).

Microsoft Excel and Word Document Interaction and Generation

Windows Services do not have access to many applications, especially COM programs such as Microsoft Word and Excel.

Ensure any Specification Tasks that require Microsoft Word and Excel are placed in the:

OnLeaveEvent of an Automatic State
OnEnterEvent of a Paused State that follows an Automatic State

This will allow these Tasks to be run by DriveWorks Autopilot and not DriveWorks Live (which it will not be able to do when running as a service through IIS).

The Specification Tasks this applies to include:

The image below explains which modules of DriveWorks will process data when the ReleaseDocuments task is placed on the two event types.

DriveWorks Administrator, User and Live
DriveWorks Autopilot
DriveWorks Administrator, User and Live

To maximize performance and for the best user experience, we recommend that as much processing as possible happens when in an Automatic state (Since the processing will be performed by DriveWorks Autopilot).

DriveWorks Plugins

All DriveWorks plugins used must be installed locally on the machine hosting IIS.

Network located plugins will not run through IIS.

Install the ASPNetCore Module

Launch Internet Information Services (IIS) Manager.
This can be found by launching the Control Panel (from the Windows Start Button), selecting System and Security, then select Administrative Tools and then double clicking Internet Information Services (IIS) Manager.
Click the server/machine name and choose Modules.
Ensure AspNetCoreModule is in the module list.

If the module is not shown, follow the steps below:

Download and install from the link:
ASPNetCore Module Download
After installation, refresh the module list by pressing F5 and check the AspNetCoreModule is listed.

Please note: The V2 version of this module is currently not supported by DriveWorks Live.

Create the API Endpoint Website in Internet Information Services (IIS) Manager

The Integration Theme consumes the Integration Theme RESTful API, it is best practice to set this up on its own endpoint and secure with HTTPS.

Follow the steps below to add the site to the IIS Manager.

Launch Internet Information Services (IIS) Manager.
This can be found by launching the Control Panel (from the Windows Start Button), selecting System and Security, then select Administrative Tools and then double clicking Internet Information Services (IIS) Manager.
From the connections pane, expand the computer name link and select the Sites node.
Right click on the Sites link and select Add Website.
- On the Add Website dialog enter a Site Name
  This name identifies the site in the IIS Manager only, it does not appear externally, although it is good practice to use the same name as your site (for instance api.driveworkslive.com).
- Click the browse button at the end of the Physical Path field.
- Browse to the location of the DriveWorks Live Theme containing the web.config file required to be used with this site.
  This will usually be the following location:
  Integration Theme - %ProgramData%\DriveWorks\[version number]\Live\Themes\Integration
  The ProgramData folder may be hidden. To make this visible:
  1. Close the window that was opened from browsing to the Physical Path field.
  2. Open Windows File Explorer.
  3. Select the Drive the software is installed on (usually C:).
  4. Select View from the File Explorer menu bar.
  5. Select Hidden items from Show/hide section.
  6. Back in IIS Manager, Click the Browse button at the end of the Physical Path field.
- Under Binding select type https.
- Under SSL certificate select an SSL Certificate to use with the website.
  For testing purposes, the built in self-signed certificate can be used.
  For production, we strongly recommend a SSL certificate from a trusted certificate authority.
- Click OK to save the website and return to the IIS Manager.
From the IIS Manager, select Application Pools from the Connections panel.
A new application pool has been added for the new website previously created.
From the Application Pools list, right click the site that was added above and choose Advanced Settings.
From the Advanced Settings dialog:
- From the .NET CLR Version drop down select No Managed Code
- Identity Setting
  From the Identity setting, check the Identity the service is to run under is correct.
  This should be a valid Windows User account that does not have administrative privilege's.
  This avoids potential security risks for certain DriveWorks Live features that require IIS to access the WebView runtime application.
  If the Identity is correct, click OK and proceed to Step 6.
  If the Identity requires to be changed:
  Ensure Load User Profile is set to True.
  1. From the Identity field, launch the Application Pool identity by clicking the button at the end of the field.
  2. From the Application Pool Identity dialog, select the Custom account type and click the Set.. button.
  3. Enter the User name, Password and Confirm Password.
  4. Click OK.
  5. Click OK in the Advanced Settings dialog to apply the changes.
From the Connections pane, select the newly created website and double click Authentication.
Ensure Anonymous Authentication is enabled and other forms of Authentication are Disabled.
There are many ways to secure the API endpoint, Anonymous allows DriveWorks to manage the security of the endpoint.
Other types of Authentication can be enabled to add an extra layers of protection.
For example, Basic Authentication would require the client to send a basic authorization header with any API requests to the endpoint.
To test the new website, open a browser and navigate to the new website name adding /api to the end of the URL.
The group not found message should be returned.
Please ensure no SSL certificate warnings are received at this point.
If your browser reports an error message, please see How To: Troubleshoot IIS.

Enable JSON Compression

When using DriveWorks 3D in the 3D Preview control we recommend enabling JSON compression in IIS.

By default IIS does not include JSON in the standard compression methods, which DriveWorks 3D files use.

The IIS settings can be modified to compress JSON with the following method:

In IIS Manager, select the site from the Sites folder in the Connections panel.
Under management double click Configuration Editor to open.
From the Section dropdown select system.webserver/httpCompression.
In the list select dynamictypes and click the ... button to edit.
Add the two JSON content mimetypes and enable them:
- application/json; charset=utf-8
- application/json
Close the dialog, click Apply in the top right and restart the website/IIS.

Configure the Integration Theme Settings

Please follow the information in the topic Integration Theme Settings to configure further settings.

File Upload Limits

This is only required if your Projects use the Upload Control.

Launch Internet Information Services (IIS) Manager, select the Site and double click Request Filtering.
Select the Hidden Segments tab from the Request Filtering window, and select web.config from the list.
From the Actions panel, select Edit Feature Settings...
Set the value for Maximum allowed content length to be equal or more than the value applied to the Upload Control File Size Limit property.
Click OK to close the Window and Restart the Website to ensure the setting is applied.

Developing the Client Examples

Visit Public Integration Theme Demo sites for more information on sites hosted in the Integration Theme.

This collection of example sites is another great way to get started.

Each example is freely customizable and ready to use with your existing DriveWorks Projects.

These are enabled by selecting "Copy Client SDK Examples to this folder" during the Theme Configuration setup process.

To preview Projects in the Example Sites:

The following is a instruction set in getting started with the Integration theme quickly.

Please ensure that an appropriate code editor is installed, as this will be needed to make changes to the site.

Visual Studio code is a free application that can be downloaded from Microsoft.

In Windows Explorer, navigate to the root of the static files location that was selected during setup.
Open the "example-sites" folder.
Open one of the example folders e.g. "simple-fullscreen".
Open the "config.js" file for this example in a code editor.
Enter the Server URL for the specific Integration Theme server - the same URL the landing page is served from.
Enter the Group Alias for the specific Group - configured in DriveWorksConfigUser.xml (see: Integration Theme Settings).
[optional] Enter the Credentials for a valid user (if no default is specified in DriveWorksConfigUser.xml).
Some examples may have further configuration options, each with custom inline guidance.
Repeat the configuration for each of the examples to be used. Each example has it's own config file, to assist with portability.
Start the Integration Theme and open the landing page.
Navigate to "Example Sites".
Select one of the configured examples.
If the example does not load, check the browsers console for error messages (F12).

These sites are designed to be copied out and hosted on another server acting as the Integration Theme client (not hosted by DriveWorks Live).

The Integration Theme landing page should not be used to host a production website - only to preview the funcionality demonstrated.

To copy an example to another location:

In Windows Explorer, navigate to the root of the static files location you selected during setup.
Open the "example-sites" folder.
Open the chosen example's folder within.
Copy the entire contents of this folder to your desired location.
Ensure the config.js file is pointed to your Integration Theme server url and group.
Update the Client SDK <script/> tag at the bottom of each HTML template to load the client SDK library hosted by the DriveWorks Live server URL.
1. Before: <script src="/DriveWorksLiveIntegrationClient.min.js"></script>
2. After: <script src="*https://your-server-url.com*/DriveWorksLiveIntegrationClient.min.js"></script>
3. The Server URL is the address hosting the Integration Theme landing page.

DriveWorks Pro 22 How To: Configure IIS For The Integration Theme (KB20111101)