DriveWorks Pro 22

Integration Theme

About

The Integration Theme uses a modern REST API for consuming and running DriveWorks Implementations.

With the Integration Theme you can use the Web API to:

• Embed a DriveWorks form in your website without an iFrame
• Query constant and variable values in a running specification
• Process Macros remotely from the client
• Drive constant values from anywhere
• Run transition and operations on existing specifications
• Use OData to query existing specifications
• Plus lots more

Benefits

The Integration Theme allows DriveWorks Implementations to be seamlessly connected to any website, application or connected device.

Integration with websites requires minimal JavaScript code which is easily obtained through the documentation.

Other benefits include:

• Secure - using CORS technology requests from non-domain clients are managed securely.
• Embed forms in a website without using iFrames
• Apply additional styling to controls and forms using CSS
• React to DriveWorks form events in the hosting client
• Pass data client to client (for example a price calculated by DriveWorks can be sent into a shopping basket)
• Query DriveWorks for the Specification History with API access to Transitions and Operations
• Access DriveWorks Implementations from any connected system or device

Getting Started

Learn how to select the Integration Theme for DriveWorks Live to use. See Select the Integration Theme.

Learn how the configuration and connection settings are applied.See Integration Theme Settings.

Resources

For quick reference we also provide a public demo site showing these examples and documentation.

Here you will find a range of resources to assist you in getting started with the Integration Theme, Server API and Client SDK.

Public Web API Demo Site.

The Server API documentation, Client SDK documentation and examples are available by selecting the Integration Theme when running DriveWorks Live or Personal Web Edition.

Server API

The Integration Theme uses a server side REST API.

REST (Representational State Transfer) is the basic principle of web interactions.

Clients (desktops, mobiles, tablets or anything connected to the internet) make requests to a server to push/pull data, expecting the server to respond with a request status and potentially get some data back.

Server API Documentation

Public Server API Documentation: https://webapi.driveworkslive.com/help/server.

The documentation, built on the Swagger framework, displays and interacts with all of the endpoints that can be accessed using the Integration Theme.

Here you will find:

• a description of the functionality of each endpoint
• the required format for sending a request to the endpoint
• information on the required data, the format of that data and its purpose
• the responses that the endpoint can produce
• the ability to try out each endpoint directly on the help page

Object (Endpoint) Diagram

Requests from the client target different endpoints or routes.

In simple terms, a web service endpoint is a web address (URL) at which clients of a specific service can gain access to it. By referencing that URL, clients can get to operations provided by that service.

Client SDK Documentation

Public Client SDK Documentation: https://webapi.driveworkslive.com/help/client.

DriveWorks also provides a Javascript Client SDK as a wrapper around the Server API making it even easier to consume DriveWorks from anywhere.

The Client SDK documentation displays all of the functions and properties that are available when utilizing the SDK to communicate with the Server API. Here you will find:

• a list of the available classes, functions and properties
• a list of the supporting data types, which show the format of data returned from the Server API when it reaches the client
• information on each entity detailing functionality, required data, data types, and return values

Client SDK Examples

Public Client SDK Examples: https://webapi.driveworkslive.com/home.html.

On top of the Client SDK there are also some Client SDK examples that show some of the capabilities available.

The Integration Theme provides a range of examples that showcase how the Integration Theme Client SDK can be used to interact with the Server API to create custom web content, powered by DriveWorks.

This collection of examples is a great way to get started or provide inspiration, and they are completely customizable and ready to use with your existing DriveWorks Projects and Specifications.

Example Sites

Public Example Sites: https://webapi.driveworkslive.com/example-sites.

Example sites demonstrate the Integration Theme Client SDK in real-world situations.

These aim to serve as a great starting point and inspiration for developing your own web sites or applications.

Each is completely customizable and ready to use with your existing DriveWorks Projects and Specifications.

Feel free to copy and modify any of the reference examples to your own needs.

Query Function

The Example Sites - Corporate Website example supports creating new or editing existing Specifications through a URL query function.

The Query Function requires the term /query?and then specific parameters and parameter values appending to the URL of the website, for example:

https://webapi.driveworkslive.com/example-sites/corporate-website/query?run=Demo-Cupboard

Authentication

For security reasons authentication (Login) credentials cannot be passed into the Query Function.

To allow different logins for different situations a sharedGroupAlias for each situation, is created in the DriveWorksConfigUser.xml file.

This is a server side configuration file which is never served to the client (browser) so all settings are secure.

See Integration Theme Settings, Shared Group - Multiple Connections for more information.

Once applied, the required sharedGroupAlias is selected by using the alias parameter in the Query Function.

Permissions

Certain parameters of the Query Function have been blocked by default for security reasons.

Constants and Macros must be explicity set in the DriveWorksConfigUser.xml file.

This is a server side configuration file which is never served to the client (browser) so all settings are secure.

See Integration Theme Settings - Permissions for more information.

Query Function Parameters

The available parameters are:

• run

  Will create a new Specification from the given Project name.

  For example:

  /query?run=MyProject

• driveapp

  Will run the given DriveApp Alias name.

  For example:

  /query?driveapp=MyDriveApp

• specification

  Will edit the given Specification ID.

  For example:

  /query?specification=123

• transition

  Combine with the specification parameter to run the given Transition name.

  For example:

  /query?specification=123&transition=Edit

• operation

  Combine with the specification parameter to run the given Operation name.

  For example:

  /query?specification=123&operation=CreateReports

• alias

  The name of the Group alias as specified in the DriveWorksConfigUser.xml. Combine with the run parameter to create a specification in another Group.

  This is required if the defaultGroupAlias has not been set in the config.js file. See Query Function Settings for more information.

  This is also required when multiple Groups or access points to the same Group are possible.

  For example:

  /query?alias=DistributorAlias&run=MyProject

• DWConstantNAME

  DWConstant is case sensitive.

  This must be declared in the URL exactly as above.

  Sets the constant to the value specified. Combine with the run parameter to set a constant value in a new Specification.

  For example:

  /query?run=MyProject&DWConstantName=1111

• DWMacroNAME

  DWMacro is case sensitive.

  This must be declared in the URL exactly as above.

  Will run the given Macro name and passes in the argument (optional). Combine with the run parameter to run a Macro in a new Specification.

  For example:

  /query?run=MyProject&DWMacroName=Argument

Escaping tags

When characters used in the structure of the URL are required as parameters or values to be passed into a Specification, the character must be encoded.

Common characters and their URL-encoding equivalent are listed below:

For a complete list of URL Encoding References, please refer to HTML URL Encoding Reference (W3 Schools).

For example when the value My Company is required to be passed into a Constant named DWConstantCompanyName, the Query Function URL will look like:

/query?run=MyProject&DWConstantCompanyName=My%20Company

Query Function Settings

Settings for the Query Function are applied in the config.js file for the Corporate Website example.

Open the config.js in an editor and locate the code below:

// (Optional) Configure the query function
// Enter a default Group Alias and/or Project name 
   to be used (when none are passed in the query string)
// Choose how sessions are handled
query: {
    defaultGroupAlias: "",
    defaultProjectName: "",
    autoLogin: false,
    requireNewSession: false,
    requireExactAlias: false,
},

Where the following settings can be applied:

• defaultGroupAlias

  A default Group Alias, so if one is not provided in the URL a session will be created with these credentials.

  If this is not set the alias parameter must be declared in the Query Function URL. See Query Function Parameters for more information.

• defaultProjectName

  A Project to run if one is not specified, this will create a new Specification with this Project.

• autoLogin

  If a session is not currently active, the Integration Theme will login to the Group with the credentials in the Group Alias.

• requireNewSession

  (true or false) will force a new session every time a URL is run, this will force the session to be change to the credentials passed into the Integration Theme via the Group Alias.

• requireExactAlias

  (true or false) This setting will ensure that the active session is running as the same Alias that has been provided. If a session is active an the Alias provided does not match the query will not be run.