Legal notes

Copyright 2022 by TECHNIA AB

All rights reserved.

Preface

Widget 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.

Widget Box allows configuration of tailored 3DDASHBOARD widgets presenting data from standard OOTB services in any preferred way making users more efficient and 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 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

Widget configuration is controlled by a subscription and access token. 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

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.

Deployment & 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). This chapter cover deployment & administration only, to read more on the configuration format please refer to #UI Framework & configuration.

Configuration administration

List configurations

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

export SERVER=https://widgets.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://widgets.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://widgets.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.

Code Resource administration

Create & update code resource

To deploy a custom resource and make it available to your configurations you can push a file to the server using the following cURL. To learn more about writing code extensions please refer to #Plugin-code-extensions.

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

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.

UI Framework & configuration

Common concepts

To make configuration independent of service detail, 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.

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 cytoscape runs in headless mode without any visualizations. Visual graphs can be enabled in development mode and provides a live view of the data store but comes with a performance cost. Developers can also query the data store graph using developers console.

Nomenclature

Word

Meaning

nodes

objects

edges

relationships

eles

a collection of edges and/or nodes

Colours

TODO

Configuration

Widget

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

{
  "$schema": "./schema/widgets.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

An array of plugin resources see #Code-Resource-administration

string [array]

false

components

An array of component name references #Component

component [array]

table_definitions

An array of #Table definitions

table [array]

tableColumn_definitions

An array of #Column-configuration definitions

column [array]

toolbar_definitions

command_definitions

datasets

An array of #Data-set definitions

data set [array]

services

An array of service definitions #Service

service [array]

mode / development

When true a visual graph and other helpful debug tools good for development is displayed, there will be a performance overhead, default false

boolean

false

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 other specific data or global, automatically picking up the context it is applied to.

It is common to use statements to filter by some specific property. Data sets uses cytoscape.js#selectors selectors and cytoscape.js#collection/traversing traversing API’s, the selector statements are directly used by administrators in configuration and is good to refer to for detail (API’s are used internally and only of interest when writing #Plugin-code-extensions).

Example use:

• When expanding a table row, what related data 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?

Chained data sets

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). To chain simply use the datasets property and point out the data sets to apply on the result set of the first data set before returning.

Data set configuration

Common data set properties

The following properties applies to all data set configuration

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 chain. Applies to the result set.

string [array]

false

Expand

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. There is an option to retain leaf nodes of that expand only.

{
    "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

cytoscape.js#selector validated with all edges, retains matching only

string

false

nodeStatement

cytoscape.js#selector validated with all nodes, retains matching only

string

false

predecessors

Expand direction, true expands upwards (where used), 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

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

cytoscape.js#selector validated with all edges and nodes in the collection, returns matching eles only

string

true

Nodes

Filters out all nodes matching a given cytoscape selector statement.

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

Property

Description

Type

Required

statement

cytoscape.js#selector validated with all nodes in the collection, returns matching nodes only

string

false

Edges

Filters out all edges matching a given cytoscape selector statement.

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

Property

Description

Type

Required

statement

cytoscape.js#selector validated with all edges in the collection, returns matching edges only

string

false

Successors

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

cytoscape.js#selectors validated with all eles in the result set collection, returns matching eles only

string

false

Predecessors

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

A cytoscape.js#selector validated with all eles in the result set collection, returns matching eles only

string

false

Sources

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

A cytoscape.js#selector validated with all nodes in the result set collection, returns matching nodes only

string

false

Targets

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

A cytoscape.js#selector validated with all nodes in the result set collection, returns matching nodes only

string

false

Outgoers

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

A cytoscape.js#selector validated with all eles in the result set collection, returns matching eles only

string

false

Incomers

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

A cytoscape.js#selector validated with all eles in the result set collection, returns matching eles only

string

false

Roots

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

A cytoscape.js#selector validated with all nodes in the result set collection, returns matching nodes only

string

false

Leaves

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

A cytoscape.js#selector validated with all nodes in the result set collection, returns matching nodes only

string

false

Service

Services are configured globally and independently from each UI component, please refer to #Common-concepts for better understanding of the high level solution and how services fits the overall picture.

Transformer

To populate the client data store (graph), a transformer is applied. The transformer parses the service response payload into nodes and edges and populates the graph data store. To facilitate standard and documented services, built-in transformers are included. It is possible to register you own transformers to parse any undocumented or external service into the data store, and use the UI components just as usual for any data. See #Code-Resource-administration for detail on how to deploy plugin code. Refer to #Plugin-code-extensions for transformer coding details. To use an extension point it out in your widget definition #Widget.

The framework comes with several built-in transformers.

Built-in transformers

Transformer

Description

6w

corpus

cvservlet

3DEXPERIENCE Services

Best practice is using the documented and supported services listed on Dassault Systèmes Developer Assistance (3ds.com). Widget configuration based on documented services is most stable over time and require the least possible maintenance.

There are other undocumented platform services used by many of the OOTB Widget apps. Using such service could be beneficial and enable better performance or other capabilities, with the risk of change and more maintenance over time. It is possible to configure such services, often a custom transformer plugin is required to parse the data to the data store (graph).

Authentication

All service calls uses the 3DEXPERIENCE platform authenticated API’s.

Chained services

It is quite common that data is a combination of multiple chained services e.g. first call a service get all the instances (relationships), then based on that result get all references (objects). To chain services use the services property. A chained service will use the eles that the transformer of the parent service returns.

Macros

All service configuration support macros. A macros is typically a physical id or similar. A macro is identified with double curly brackets e.g. {{contextId}}.

Key

Description

contextId

Physical id of the dropped context object or the id property of the related node (e.g. for column or chained data)

securityContext

TODO

Service configuration

{
    "name": "example1",
    "uri": "/resources/v1/modeler/dseng/dseng:EngItem/{{contextId}}/dslc:changeControl",
    "transformer": "relatedChange",
    "relationType": "controllingChange",
    "services": ["changeAction"]
}

{
    "name": "example2",
    "uri": "/resources/enorelnav/navigate/getecosystem?tenant=OnPremise",
    "transformer": "customEcoSystem",
    "relationType": "example",
    "method": "POST",
    "payload": {
        "debug": false,
        "ecoSystemWithDetail": true,
        "id": "{{contextId}}",
        "widgetId": "a-widget-id"
    }
}

Property

Type

Required

name

A unique identifier used for configuration reference

string

true

uri

The service URI (without server protocol and port), see Dassault Systèmes Developer Assistance (3ds.com) for supported services

string

true

transformer

A built in or plugin transformer responsible for parsing the service response to data store. See #Transformer .

string

true

relationType

When a service do not include edge (relation) detail this value would be used as edge type.

string

false

services

An array of service names. See #Chained-services .

string [array]

false

method

An http method, default GET

string

false

payload

JSON object request payload

object

false

securityContextHeaderPattern

string

false

runOnce

Call the service just once with the same arguments for that view. Useful to improve performance when the same data is present multiple times in the same view e.g. recurring person data such as owner in a table

boolean

false

condition

Defines a where clause to control for what data to call the service. e.g. only call for change approval data for nodes in a certain state

object

false

Table

The table component is a highly configurable, feature rich and navigable data grid. It allows for presentation of data in many different ways, and it is often possible fulfil business requests, just by configuration. The table implements the common framework concept and uses Cytoscape.js#data eles data select keys to configure data into cells. Read #Common-concepts to learn more about the high level concept.

Advanced implementations

The table component allows advanced implementations such as custom rendering or data calculations using the plugin architecture. Lear more about plugins in #Plugin-code-extensions.

Table configuration

{
    "name": "example",
    "datasets": ["rootNodesInitalLoadData"],
    "columns": [
        "title",
        "owner",
        "state",
        "DEFAULT_SEPARATOR",
        "related_docs"
    ],
    "services": ["initialLoadService"],
    "expand": {
        "services": ["expandService"],
        "datasets": ["expandData"]
    }
}

Property

Description

Type

Required

name

A unique identifier used for config reference

string

true

datasets

#Data-set name references, defines the root node data to load into the table.

string

true

columns

#Column-configuration name references, table column responsible to populate cell data for each row.

string [array]

true

services

#Service name references, defines the services to call initially and load data store (graph). Happens before first load/render of the table.

string [array]

true

expand

If #Expand is present allows to navigate expand each row to display related data as child rows.

object

false

Expand

Property

Description

Type

Required

datasets

#Data-set name references, defines what related data to show as child rows as you expand a row.

string [array]

false

services

#Service name references, in case data is not yet present in data store (graph) you can have services to load data on expand, before selecting and displaying the child rows.

string [array]

false

Column configuration

The column definition controls the specifics of each cell.

{
    "name": "columnExample",
    "label": "Title",
    "data": "title",
    "href": "ups-whereused-drill",
    "settings": {
        "cellRenderer": "AUTO_COLOR_RENDERER"
    }
}

{
    "name": "relatedDataColumnExample",
    "label": "Documents",
    "data": {
        "datasets": ["relatedDocs"],
        "select": "title"
    },
    "services": ["relatedDocs"],
    "settings": {
        "usesAlternateOid": true
    }
}

Property

Description

Type

Required

name

A unique identifier used for config reference

string

true

label

The table/column header

string

false

data

A Cytoscape.js#data node or edge select key used to populate values into cells.

string

false

data

An array of Cytoscape.js#data node or edge select keys used to populate values into cells. If multiple keys return values for the same cell those are added with a comma (“,”) delimiter.

string [array]

false

data

 #Column-data

object

false

data

 #Column-data

object [array]

false

services

 #Service

string [array]

false

href

A component name reference, if present defines another component to drill into when clicking a link. The clicked eles data will be used as context loading the configured component. You will be able to navigate back using a breadcrumb.

string

false

type

 #Column-types

string

false

dateFormat

sortType

settings

#Column-Settings

What is a setting vs what is on column??

object

false

Column data

Property

Description

Type

Required

datasets

 #Data-set

isEdge

 #Nomenclature

boolean

select

A Cytoscape.js#data node or edge select key used to populate values into cells.

Column Settings

Property

Description

Type

Required

cellRenderer

A name reference to advanced rendering logic (e.g. fancy styling), could be a built-in or plugin #Cellrenderer name.

string

false

cellRendererProps

Properties passed to #Cellrenderer to add configurability, see #Built-in.

object

false

datahandler

A name reference to advanced data logic (e.g. calculations), could be a built-in or plugin #Datahandler name.

string

false

dateFormatOptions

 #Date-format-options

object

false

dependantOnService

 Used

string

false

dragAllAtOnce

edgeStatement

rollup only?

headerRenderer

loadingLabel

nodeStatement

rollup only?

numberFormat

 #Number-format

object

renderAsMultiValue

boolean

false

styleCell

styleCellValue

styleHeader

usesAlternateOid

false

valueFormatter

width

false

Cell renderer props

Property

Description

Type

Required

styleProp

string

customColorMappings

object

customIconMappings

object

colorize

showFullName

string

false

Date format options

Property

Description

Type

Required

locale

options / year

options / day

options / month

convertToDays

boolean

suffix

string

Number format

Property

Description

Type

Required

fixedScale

locale

minimumFractionDigits

suffix

Column types

Built in …

Type

Description

person

Plugin code extensions

To enable custom logic (e.g. calculated values) the framework comes with a plugin architecture.

Transformer

Datahandler

Cellrenderer