Image Removed

Image Added

Legal notes

Copyright 2022 by TECHNIA AB

All rights reserved.

Preface

Widget as a Service (WaaS) is a configurable widget framework for the 3DEXPERIENCE platform and Box is the SaaS foundation for tailored 3DEXPERIENCE apps. As a configurable UI framework for making widgets, it is a cost-efficient solution compared to coding custom widgets from scratch. It also brings more and higher quality features than a coding project would normally do. Widget Box is often used to raise productivity and user acceptance by streamlining workflows or filling gaps.

WaaS Widget Box allows configuration of tailored 3DDASHBOARD widgets presenting data from standard OOTB services in any preferred way making users more efficient and happy willing to accept using the platform. The framework contains many different building blocks, such as tables and forms, that could be configured individually into simple or together into more complex apps, all integrating well with OOTB functionality such as 6WSearch.

The widget framework and definition is hosted on TECHNIA.cloud. Access controlled by subscription and token it can be added to any 3DEXPERIENCE environment, including cloud tenants. The widget is added by pasting a link into the administration dialog “Create Additional App“. The dialog allows adding widgets without any customization to the target environment just by adding the metadata of the whereabouts of the widget that is kept fully outside.

Widget as a Service consume Box calls all 3DEXPERIENCE data locally, between the 3DEXPERIENCE platform and the client browser. No 3DEXPERIENCE data, except user information for usage audit purposes (see agreement for details), is passed elsewhere or to the TECHNIA.cloud.

Essentials

Supported platforms

3DEXPERIENCE 2019x or higher

Subscription & access

All widget configurations are Widget configuration is controlled by an a subscription and access token tied to a subscription. Subscriptions have an end date and a user count. As the subscription runs out or the user count is exceeded, the widget is no longer accessible.

Hosting

All widget definitions Widgets are hosted on TECHNIA.cloud (currently on AWS). For more detail please refer to the agreement.

The following resources are hosted on TECHNIA.cloud

• Widget Framework (.html, .css, .js)

• Widget Definition

  • Configuration (e.g. columns, datasets etc .json)

  • Code (e.g. custom rendering, data calculations etc .js)

• Subscription detail and usage data

Setup (adding a widget in 3DEXPERIENCE)

Updates

The widget framework is evergreen and updates at least every 11 weeks. Updates could include improvements to existing functionality or new functionality enabled by configuration.

Widget definition & administration

Customers or customer representatives (consultants) sometimes control widget definitions themselves (depending on the agreement). Widget definition is currently managed over https://curl.se/ using basic authentication (you can use git bash or similar terminal).

List configurations

The following cURL will list the id and name of all configurations related to the admin user.

export SERVER=https://waas.technia.cloud
export USER=
export PASSWORD=
curl ${SERVER}/api/v1/configs -u "${USER}:${PASSWORD}" -k 

Parameter

Description

USER

An administration user with the proper access.

PASSWORD

The password of the administration user.

Create configuration

The following cURL template will create a new widget definition.

export SERVER=https://waas.technia.cloud
export CONFIG_NAME=
export CONFIG_FILE=
export USER=
export PASSWORD=
export CONTENT_TYPE='Content-Type: multipart/form-data'
curl -XPOST ${SERVER}/api/v1/configs -H "${CONTENT_TYPE}" -F "name=${CONFIG_NAME}" -F "config=@${CONFIG_FILE}" -u "${USER}:${PASSWORD}" -k 

Parameter

Description

CONFIG_NAME

A unique string representation of the configuration. Used when referring the widget from the “Create additional app” dialog.

CONFIG_FILE

The configuration file holding the definition.

USER

An administration user with the proper access.

PASSWORD

The password of the administration user.

Update configuration

The following cURL template will update the widget definition and/or its name (used referring from 3DX).

export SERVER=https://waas.technia.cloud
export CONFIG_ID=
export CONFIG_NAME=
export CONFIG_FILE=
export USER=
export PASSWORD=
export CONTENT_TYPE='Content-Type: multipart/form-data'
curl -XPUT ${SERVER}/api/v1/configs/${CONFIG_ID} -H "${CONTENT_TYPE}" -F "name=${CONFIG_NAME}" -F "config=@${CONFIG_FILE}" -u "${USER}:${PASSWORD}" -k 

Parameter

Description

CONFIG_ID

A numeric identifier of the configuration. Can be found calling list configurations.

CONFIG_NAME

A unique string representation of the configuration. Could be changed, used when referring the widget from the “Create additional app” dialog.

CONFIG_FILE

The configuration file holding the new definition.

USER

An administration user with the proper access.

PASSWORD

The password of the administration user.

Create & update code resource

To add a custom js resource to use in configurations (e.g. custom dataHandlers) you can push a js file to the server using the following cURL.

export SERVER=https://waas.technia.cloud
export COMPANY_ID=
export FILE=
export USER=
export PASSWORD=
export CONTENT_TYPE='Content-Type: multipart/form-data'
curl -XPOST ${SERVER}/api/v1/companies/${COMPANY_ID}/resources -H "${CONTENT_TYPE}" -F "file=@${FILE}" -u "${USER}:${PASSWORD}" -k 

Parameter

Description

COMPANY_ID

A numeric identifier of your company. Where to get this?

FILE

The js file holding the new resource definition.

USER

An administration user with the proper access.

PASSWORD

The password of the administration user.

Components & configuration

Concept overview

To make configuration independent from the many different service responses, and to hide complexity from the developer, the framework comes with a technical concept common to all components.

Image Removed

All services loads data to a common in memory data store. Query statements and other configuration is applied to populate UI components, all from the data store. This allows a compact and standardized cross component configuration format independent of service details. There is no direct dependency between any UI component configuration and the service layer, on top of that all components share the same data store and reflect data changed by other components.

Data store

The client (browser) data store is in memory and temporary, the purpose is to track cross component state, provide data to the UI rendering and to provide a common format to avoid service dependency in configuration. A data store is common practice in many modern UI frameworks e.g. https://redux.js.org/ and should not be confused with a data base.

Cytoscape.js

Image Removed

https://js.cytoscape.org/, a “Graph theory (network) library for visualisation and analysis“, is used as data store. The graph capabilities enables complex data store selection and structure traversal (similar to mql). The cytoscape.js selectors is similar to css selectors and is used in configuration. Normally it runs in headless mode without any visuals. Visuals can be used in development mode.

Framework / Core

Common configurations shared cross component.

Plugin code extensions

To enable custom logic such as value calculations, special rendering or data transformation of unknown services the framework comes with a plugin architecture.

TODO

Widget

A top level configuration. Defines a 3DDASHBOARD widget app that could be added to the compass.

{
  "$schema": "./schema/waas.schema.json",
  "title": "Widget Example",
  "resources": ["my-plugin.js"],
  "components": [{}],
  "table_definitions": [{}],
  "tableColumn_definitions": [{}],
  "toolbar_definitions": [{}],
  "command_definitions": [{}],
  "datasets": [{},{}],
  "services": [{}],
  "mode": {}
}

Property

Description

Type

Required

$schema

string

false

title

string

resources

string [array]

false

components

component [array]

table_definitions

table [array]

tableColumn_definitions

table column [array]

datasets

data set [array]

services

service [array]

mode

mode

Component

Defines a UI component used by the widget.

Remove this? Move requiresContext and root def to root widget conf?

{
    "name": "??neverUsed??",
    "type": "table",
    "definition": "ups-roots-example",
    "root": true,
    "requiresContext": true
}

Property

Description

Type

Required

name

a unique identifier used for reference (but never used?)

string

type

the component type (e.g. table) - already by the def?

string

definition

the component identifier (e.g. table name)

string

true

root

true for the default top level component

boolean

requiresContext

true in case the widget require a dropped context object

boolean

Data Set

A data set is used when you need to define a subset of the data store to use somewhere in the UI components. Could be related to some specific data or global. It is common to use statements t filter by some specific property. Data sets could be chained together (e.g. give me all project nodes related to me → out of those fully expand their folder structures → out of that result give me all in work documentation). Data sets uses cytoscape.js selectors and cotoscape.js traversing api's, the selector statements are directly used in the configuration format and is good to refer to for detail (api’s are used internally and hidden from the administrator).

Example use:

• Expanding a table row what related data in which direction should display as child rows? (e.g. product structure)

• In a related data column which nodes should be presented? (e.g. specifications)

• Loading the root nodes of a table should all data nodes go there or just with a certain state or type?

Property

Description

Type

Required

name

A unique identifier used for reference

string

true

type

Data set type (listed below e.g. expand)

string

true

datasets

Data set identifier references to be applied on the result set

string [array]

false

Expand (data set type)

Traverses the graph (similar to mql expand) the given number of levels applying the edge and node statements (selectors) on each every level independently (it require match for each level and not the result set, which cold give a different result). You can control the number of levels, the direction and what selectors to apply for edges and for nodes. Note that the node statements also apply to the starting nodes (a difference compared to mql). An expand returns all edges and nodes including the starting nodes in an eles collection.

{
    "name": "ups-roots-example",
    "type": "expand",
    "edgeStatement": "[type='VPMInstance']",
    "nodeStatement": "[type='VPMReference']",
    "predecessors": true,
    "leavesOnly": true,
    "levels": 100
}

Property

Description

Type

Required

levels

The number of levels to expand, if left out all levels is expanded (there is a max value to prevent issues, explicitly state a high value to override)

number

false

edgeStatement

https://js.cytoscape.org/#selectors selector validated with all edges, retains matching only

string

false

nodeStatement

https://js.cytoscape.org/#selectors selector validated with all nodes, retains matching only

string

false

predecessors

Expand direction, a true value expands up, default is false

boolean

false

leavesOnly

Removes all eles from the result set that is not a leaf according to the applied node and edge statements, default false

boolean

false

Filter (data set type)

Filters out all eles matching a given cytoscape selector statement.

{
    "name": "vpm-structure",
    "type": "filter",
    "statement": "[type='VPMInstance'],[type='VPMReference']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all edges and nodes in the collection, returns matching eles only

string

true

Nodes (data set type)

Filters out all nodes matching a given cytoscape selector statement.

{
    "name": "vpm-instances",
    "type": "nodes",
    "statement": "[type='VPMInstance']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all nodes in the collection, returns matching nodes only

string

false

Edges (data set type)

Filters out all edges matching a given cytoscape selector statement.

{
    "name": "vpm-references",
    "type": "edges",
    "statement": "[type='VPMReference']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all edges in the collection, returns matching edges only

string

false

Successors (data set type)

Fully expands all eles in the collection recursively then applies a given cytoscape selector statement on the result set of both edges and nodes.

{
    "name": "vpm-structure",
    "type": "successors",
    "statement": "[type='VPMReference'],[type='VPMInstance']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all eles in the result set collection, returns matching eles only

string

false

Predecessors (data set type)

Fully expands all eles in the collection recursively in the upwards direction (where used) then applies a given cytoscape selector statement on the result set of both edges and nodes.

{
    "name": "vpm-parent-structure",
    "type": "predecessors",
    "statement": "[type='VPMReference'],[type='VPMInstance']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all eles in the result set collection, returns matching eles only

string

false

Sources (data set type)

Gets the source nodes connected with the edges of the collection then applies a given cytoscape selector statement on the result set.

{
    "name": "vpm-parent-nodes",
    "type": "sources",
    "statement": "[type='VPMReference']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all nodes in the result set collection, returns matching nodes only

string

false

Targets (data set type)

Gets the target nodes connected with the edges of the collection then applies a given cytoscape selector statement on the result set.

{
    "name": "vpm-child-nodes",
    "type": "targets",
    "statement": "[type='VPMReference']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all nodes in the result set collection, returns matching nodes only

string

false

Outgoers (data set type)

Get edges and their target nodes coming out of the nodes in the collection, then applies a given cytoscape selector statement on the result set.

{
    "name": "vpm-children",
    "type": "outgoers",
    "statement": "[type='VPMReference'],[type='VPMInstance']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all eles in the result set collection, returns matching eles only

string

false

Incomers (data set type)

Get edges and their source nodes coming in to the nodes in the collection, then applies a given cytoscape selector statement on the result set.

{
    "name": "vpm-parents",
    "type": "incomers",
    "statement": "[type='VPMReference'],[type='VPMInstance']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all eles in the result set collection, returns matching eles only

string

false

Roots (data set type)

Get nodes with no incoming edges in the collection, then applies a given cytoscape selector statement on the result set.

{
    "name": "vpm-true-roots",
    "type": "roots",
    "statement": "[type='VPMReference']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all nodes in the result set collection, returns matching nodes only

string

false

Leaves (data set type)

Get nodes with no outgoing edges in the collection, then applies a given cytoscape selector statement on the result set.

{
    "name": "vpm-true-leaves",
    "type": "leaves",
    "statement": "[type='VPMReference']"
}

Property

Description

Type

Required

statement

https://js.cytoscape.org/#selectors selector validated with all nodes in the result set collection, returns matching nodes only

string

false

Services

Mode

Table