DriveWorks Pro 21

Integration Theme Settings

Integration Theme Settings

The Integration Theme files are installed in the ProgramData location for the version of DriveWorks in use.

For example:

C:\ProgramData\DriveWorks\[Version]\Live\Themes\Integration\

The files within this location make up the code for DriveWorks to host the Integration Theme endpoint.

These files are controlled by DriveWorks and will be subject to modifications from any subsequent upgrades.

This location also contains the files that store the connection and configuration settings.

These are known as:

• Base File

  The Base File is controlled by DriveWorks in the same way as the other files. The required settings should be copied from this file into the User File.

• User File

  The User File does not get overwritten on upgrading or reinstalling DriveWorks. This file is specific to your requirements.

These files are server side configuration files, and are never served to the client (browser) so all security credentials are secure and never seen by the public.

Base File

The Base File is named DriveWorksConfig.xml.

This file must not be edited. Any future upgrades or reinstallation of DriveWorks will overwrite this file.

The required settings should be copied from this file into the User File.

User File

The User File is named DriveWorksConfigUser.xml.

DriveWorks will create the DriveWorksConfigUser.xml file when the Integration Theme is selected (from the Theme selection task), and will include the configuration setting - staticFilesPath element.

This file (and all customizations within it) will remain untouched during uninstallation or reinstallation.

The User file stores the connection and configuration settings that will be used by the Integration Theme.

Not all configuration and connection settings need to be copied into the DriveWorksConfigUser.xml file.

Any settings that do not exist in the User File will be read from the Base File.

The most important aspect of this file, which will need to be configured, is the Group connection setting.

If The User File Does Not Exist

DriveWorks will create the DriveWorksConfigUser.xml file when the Integration Theme is selected (from the Theme selection task).

However, there are circumstances when the Integration Theme does not require to be selected and the DriveWorksConfigUser.xml file will not exist.

In this instance:

1. Make a copy of the base file, in the same location.
2. Rename it DriveWorksConfigUser.xml
3. Edit the DriveWorksConfigUser.xml with your required Configuration Settings and Connection Settings as below.

Group Connection Settings - DriveWorksConfigUser.xml file

Connection Settings require to be included within the following element:

<connections>

---Copy the required xml below within these elements---

</connections>

Shared Group Connection

To set up a connection to the Shared Group, include the following:

<configuration>
    <sessionTimeout>15</sessionTimeout>
    <specificationTimeout>10</specificationTimeout>
    <serveDocumentation>false</serveDocumentation>
    <maxRequestBodySize>30000000</maxRequestBodySize>
    <connections>
      <sharedGroupAlias name="DriveWorks" serverAddress="PROSERVER" groupName="MyGroup" username="Admin" password="">
         <permissions>
            <project name="Canopy">
              <variable name="Discount">
                <team name="Sales"/>
               </variable>
               <constant name="DiscountApplied">
                 <team name="Sales" canEdit="true"/>
               </constant>
             </project>
            </permissions>
          </sharedGroupAlias>
         </connections>
        </configuration>

Where:

• name is the name to give to the group alias.

  Your 3D scenes will not load if your Group Alias contains any hyphens.

  Change the value ConnectionOne to the name to give to the group alias.

• serverAddress is the name of the machine running Pro Server.

  Change the value localhost to the name of the machine running Pro Server.

• groupName is the name of the Group to login to.

  Change the value MyGroup to the group name as it appears inside Pro Server.

• username is the Username to use by default.

  Change the value Admin to the Username to use by default.

  Specifying Admin credentials will allow users to login with the Admin user, you may not want this, so we suggest creating a user with the correct permissions.

• password is the Password to use by default.

  Change the value password to the Password to use by default.

Shared Group - Multiple Connections

The Integration Theme is the only Theme capable of hosting multiple groups.

It is also possible to have multiple group connections to the same group.

This allows you to test and deploy multiple groups across multiple websites and create different logins for different situations.

For example, having multiple connection strings allows:

• The configurator to be publicly accessible with auto-populated Guest credentials.
• The same configurator to act as a distributor portal where credentials are required to be entered.
• A different development configurator to be accessed for testing purposes.

For each required situation a new sharedGroupAlias string is created within the <connections> element.

<connections>
      <sharedGroupAlias name="Public" serverAddress="PROSERVER" groupName="ProductionGroup" username="Guest" password="Guest"></sharedGroupAlias>
      <sharedGroupAlias name="Distributor" serverAddress="PROSERVER" groupName="ProductionGroup"></sharedGroupAlias>
      <sharedGroupAlias name="Development" serverAddress="PROSERVER" groupName="DevelopmentGroup" username="Admin" password=""></sharedGroupAlias>
</connections>

Individual Group Connection

To set up a connection to an Individual Group, include the following:

<individualGroupAlias name="ConnectionTwo" path="C:\DriveWorks\MyGroup.drivegroup" username="Admin" password="password" />

Where:

• name is the name to give to the group alias.

  Your 3D scenes will not load if your Group Alias contains any hyphens.

  Change the value ConnectionTwo to the name to give to the group alias.

• path is the path to the Individual Group file.

  Change the value C:\DriveWorks\MyGroup.drivegroup to the path to the Individual Group file.

• username is the Username to use by default.

  Change the value Admin to the Username to use by default.

  Default credentials are defined here to ensure the client side code is very secure.
• password is the Password to use by default.

  Change the value password to the Password to use by default.

Permissions

Because the Integration Theme is a request service the ability to list and edit all Constants, Variables and Macros has been blocked (for security reasons).

However there may be instances where access to certain Constants, Variables and Macros is required.

As such, you need to explicitly set what Constants, Variables and Macros are visible to what teams (and if they can edit them).

Permissions require to be included within the following element:

<connections>
    <sharedGroupAlias OR individualGroupAlias> --Taken from above--
        <permissions>

        ---Copy the required xml below within these elements---

        </permissions>
    </sharedGroupAlias OR /individualGroupAlias>
</connections>

To set up permissions, include the following:

<project name="Project1">
    <variable name="variable1">
        <team name="Team1" />
    </variable>
    <constant name="constant1">
        <team name="Team2" canEdit="true"/>
    </constant>
    <macro name="macro1">
        <team name="Team1"/>
    </macro>
</project>
<groupTable name="TableOne">
        <team name="Team1" />
</groupTable>

Where:

• name (attribute of the project element) is the name of the project that contains the Variable, Constant or Macro that is required to have permission.

  Change the value Project1 to the name of the required project.

• name (attribute of the Variable element) is the name of the Variable.

  Change the value Variable1 to the name of the Variable.

  Multiple Variables must be listed separately. For example:

  <variable name="variable1">
      <team name="Team1" />
  </variable>
  <variable name="variable2">
      <team name="Team1" />
  </variable>

  • name (attribute of the team element of the Variable element) is the name of the team that has permission.

    Change the value Team1 to the name of the team.

    Multiple teams must be listed separately. For example:

    <team name="Team1" />
    <team name="Team2" />
    <team name="Team3" />

• name (attribute of the Constant element) is the name of the Constant.

  Change the value constant1 (and constant2 if declaring multiple Constants, as below) to the name of the Constant.

  Multiple Constants must be listed separately. For example:

  <constant name="constant1">
      <team name="Team1" />
  </constant>
  <constant name="constant2">
      <team name="Team1" />
  </constant>

  • name (attribute of the team element of the Constant element) is the name of the team that has permission.

    • Change the value Team1 to the name of the team.

    • Change the value of the canEdit attribute to true to allow the Constant to be edited by the user (applies to the Constant element only).

    Multiple teams must be listed separately. For example:

    <team name="Team1" canEdit="true" />
    <team name="Team2" canEdit="true" />
    <team name="Team3" canEdit="true" />

• name (attribute of the Macro element) is the name of the Macro.

  Change the value macro1 (and macro2 if declaring multiple macros, as below) to the name of the Macro.

  Multiple Macros must be listed separately. For example:

  <macro name="macro1">
      <team name="Team1" />
  </macro>
  <macro name="macro2">
      <team name="Team1" />
  </macro>

• name (attribute of the groupTable element) is the name of the Group Table.

  Change the value TableOne and TableTwo to the name of the Group Table.

  Change the value Team1 to the name of the Team with permission.

  Group Table permissions are placed inside the permissions element and outside the project element.

  Multiple Group Tables must be listed separately. For example:

  <permissions>
      <project>
          ...
      </project>
      <groupTable name="TableOne">
          <team name="Team1" />
      </groupTable>
      <groupTable name="TableTwo">
          <team name="Team1" />
      </groupTable>
  </permissions>

Configuration Settings - DriveWorksConfigUser.xml file

Configuration Settings require to be included within the following element:

<configuration>

---Copy the required xml below within these elements---

</configuration>

Copy the xml from each required setting element below within these elements.

corsOrigins

This is a list of Origins that are permitted to make Cross Origin Requests.

Origins are URLs of websites that you wish to allow a request to be made from.

<corsOrigins>
    <origin1>*</origin1>
</corsOrigins>

By default this is set to * meaning all origins can make requests.

This should be changed to a single URL, for example:

<corsOrigins>
    <origin1>http://google.com</origin1>
</corsOrigins>

To block all requests leave the value blank, for example:

<corsOrigins>
    <origin1></origin1>
</corsOrigins>

To allow requests from multiple sources add additional origin elements, for example:

<corsOrigins>
    <origin1>http://google.com</origin1>
    <origin2>http://microsoft.com</origin2>
    <origin3>http://driveworks.co.uk</origin3>
</corsOrigins>

To allow requests from all subdomains, for example:

<corsOrigins>
    <origin1>http://*.google.com</origin1>
</corsOrigins>

sessionTimeout

The length of time in minutes that a session is allowed to remain inactive before it is timed out.

This defines how long to wait before timing out of a Session (It will cancel associated Groups and Specifications).

To set your preferred timeout value, include the following:

<sessionTimeout>20</sessionTimeout>

Where 20 is changed to your preferred value.

specificationTimeout

The length of time in minutes that a specification is allowed to remain inactive before it is timed out.

This defines how long to wait before timing out of a Specification.

This is per started Specification (you can start multiple specifications running within the same group within the same session.)

To set your preferred timeout value, include the following:

<specificationTimeout>10</specificationTimeout>

Where 10 is changed to your preferred value.

groupTimeout

The length of time in minutes that a Group is allowed to remain inactive before it is timed out.

This defines how long to wait before timing out of a Group (It will cancel associated Specifications).

This is per started Groups (you can connect to multiple groups within the same session).

To set your preferred timeout value, include the following:

<groupTimeout>15</groupTimeout>

Where 15 is changed to your preferred value.

staticFilesPath

The directory from which additional static files are to be served.

The .html and .css files for the examples landing page are located here.

<staticFilesPath>C:\Files\StaticFiles</staticFilesPath>

serveDocumentation

Set this to true if you want to enable the /help endpoint. This includes access to the server API and the Client SDK documentation.

It is recommended that this is set to false in a production environment.

To set your preferred value, include the following:

<serveDocumentation>true</serveDocumentation>

Where true is changed to your preferred value.

maxRequestBodySize

(Only required if using the Upload Control)

The maximum allowed request body size in bytes.

By default the value is 30,000,000 bytes (around 28mb); this can be changed as required to accommodate large file uploads if desired.

This line can be removed or commented out - by doing so, the limit will be disabled entirely (i.e. making the request body size unlimited)

To set your preferred value, include the following:

<maxRequestBodySize>30000000</maxRequestBodySize>

Where 30000000 is changed to your preferred value.

httpsPfxFilePath

See Using a SSL Certificate below.

httpsPfxPassphrase

See Using a SSL Certificate below.

httpsForceSslOnResources

Force all resource URLs to be returned with the HTTPS scheme.

This is useful when using load balancing that terminates the SSL connection.

To set your preferred value, include the following:

<httpsForceSslOnResources>True</httpsForceSslOnResources>

Where True will force all resource URLs to be returned with the HTTPS scheme.

fullyQualifiedDomainName

Set this to force all resource URLs to be returned with this fully qualified domain name (FQDN).

<fullyQualifiedDomainName>https://my-driveworks-site.com</fullyQualifiedDomainName>

multipartBodyLengthLimit

Sets the limit for the length (in bytes) of each multipart form body.

It is recommended that this value be uncommented and increased from the default if you are encountering issues with file uploads (using the Upload Control).

To set your preferred value, include the following:

<multipartBodyLengthLimit>134217728</multipartBodyLengthLimit>

Where 134217728 is changed to your preferred value (in bytes).

allowPublicFormResources

Set this to true to allow public, content-based caching for all form resources (images, etc.).

WARNING: This means that a request for a resource will NOT be authenticated and possibly stored in edge servers on the internet.

Each URL is based on the content of the file alone, so this is typically not an issue.

<allowPublicFormResources>true</allowPublicFormResources>

Example of Custom DriveWorksConfigUser.xml file

The following is an example of a typical DriveWorksConfigUser.xml file, with specific settings included.

The settings that are not included will be taken from the DriveWorksConfig.xml file.

<configuration>
    <sessionTimeout>15</sessionTimeout>
    <specificationTimeout>10</specificationTimeout>
    <serveDocumentation>false</serveDocumentation>
    <maxRequestBodySize>30000000</maxRequestBodySize>
    <connections>
        <sharedGroupAlias name="DriveWorks" serverAddress="PROSERVER" groupName="MyGroup" username="Admin" password="" >
            <permissions>
                <project name="Canopy">
                    <variable name="Discount">
                        <team name="Sales" />
                    </variable>
                    <constant name="DiscountApplied">
                        <team name="Sales" canEdit="true"/>
                    </constant>
                </project>
            </permissions>
        </sharedGroupAlias>
    </connections>
</configuration>

Using a SSL Certificate

There are vital configuration options for serving DriveWorks Live over HTTPS and avoiding SameSite security issues in newer versions of common browsers.

Set DriveWorks Live to use SSL

In DriveWorks Live Settings ensure SSL (Advanced) is checked.

Configure httpsPfxFilePath and httpsPfxPassphrase in the DriveWorksConfigUser.xml file

The DriveWorksConfigUser.xml file has the following commented code near the start of the file:

<!-- Uncomment and edit the following to configure an SSL certificate-->
<!-- The file path to your exported SSL certificate -->
<!--<httpsPfxFilePath></httpsPfxFilePath>-->
<!-- The passphrase for your exported SSL Certificate -->
<!--<httpsPfxPassphrase></httpsPfxPassphrase>-->
        

Uncomment the lines containing the httpsPfxFilePath and httpsPfxPassphrase.

Add the location of the SSL certificate (.pfx file) in between the httpsPfxFilePath tag.

Add the pass phrase the certificate has been set up to use in between the httpsPfxPassphrase tag.

The code should now look like the following:

<!-- Uncomment and edit the following to configure an SSL certificate-->
<!-- The file path to your exported SSL certificate -->
<httpsPfxFilePath>C:\DriveWorks\my-certificate.pfx</httpsPfxFilePath>
<!-- The passphrase for your exported SSL Certificate -->
<httpsPfxPassphrase>SecureExportedPassphrase</httpsPfxPassphrase>
        

See also

Integration Theme

How To: Configure DriveWorks Live For IIS

How To: Make Your Website React To Specification Events With The Integration Theme