Table of Contents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
Legal notes
Copyright 2022 by TECHNIA AB
All rights reserved.
PROPRIETARY RIGHTS NOTICE
This documentation is proprietary property of TECHNIA AB. In accordance with the terms and conditions of the Software License Agreement between the Customer and TECHNIA AB, the Customer is allowed to print as many copies as necessary of documentation copyrighted by TECHNIA relating to the software being used. This documentation shall be treated as confidential information and should be used only by employees or contractors with the Customer in accordance with the Agreement.
Preface
Widget as a Service (WaaS) is a configurable widget framework for the 3DEXPERIENCE platform and is a cost efficient solution to raise productivity and user acceptance.
WaaS allows configuration of tailored 3DDASHBOARD widgets presenting data from standard OOTB services in any preferred way making users more efficient and happy 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 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.
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.
Info |
---|
To control usage the logged in user name is passed (and stored) each time a widget definition is loaded from TECNNIA.cloud. Fore more detail on the data stored see the privacy policy & data processing agreement. |
Note |
---|
To avoid unauthorized use of your subscription keep your access token a secret and renew it frequently. |
Hosting
Widgets are hosted on TECHNIA.cloud (currently on AWS). For more detail please refer to the agreement.
Tip |
---|
No on-premise installation is required. The widget is fully hosted and ready to link to any 3DEXPERIENCE platform. |
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)
Adding widgets is standard functionality part of the 3DEXPERIENCE platform. To access the command you need to be logged in with an administration user with the access to “Platform Management”. Once in “Platform management” navigate to the “Members” tab and scroll down to “Additional Apps” and you will fins the “Create Additional App” command.
A dialog will appear and you should enter
Short Name - The app label as displayed to users in the compass
Type - Select “Widget”
Source code URL - Enter the widget framework host URL & access key (shared with your subscription) followed by the name of the widget you like to add.
Info |
---|
As you press Create the widget should be made available under the Compass within seconds. |
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.
Tip |
---|
Updates can be controlled by locking to a specific version, allowing validation before rolling new releases. |
Info |
---|
All improvement, including quality fixes, is delivered with the latest update only, there will be no fix packs on previous locked versions. |
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).
Note |
---|
Note that all modification to definitions is immediately reflected. Use other widget ids for development and test. |
Info |
---|
Definition is not version controlled (yet), it is recommended to source control your definitions elsewhere. |
Tip |
---|
To simplify administration, and to improve security, an admin UI with MFA is planned for later. |
List configurations
The following cURL will list the id and name of all configurations related to the admin user.
Code Block |
---|
export SERVER=https://waas.technia.cloud export USER= export PASSWORD= curl ${SERVER}/api/v1/configs -u "${USER}:${PASSWORD}" -k |
Parameter | Description |
---|---|
| An administration user with the proper access. |
| The password of the administration user. |
Create configuration
The following cURL template will create a new widget definition.
Note |
---|
Make sure that you are using a unique name without special characters or spaces. |
TECHNIA R&D need to connect a subscription controlling user access to all new widget definitions.
Code Block |
---|
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 |
---|---|
| A unique string representation of the configuration. Used when referring the widget from the “Create additional app” dialog. |
| The configuration file holding the definition. |
| An administration user with the proper access. |
| 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).
Note |
---|
Make sure that you are using a unique name without special characters or spaces. |
Code Block |
---|
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 |
---|---|
| A numeric identifier of the configuration. Can be found calling list configurations. |
| A unique string representation of the configuration. Could be changed, used when referring the widget from the “Create additional app” dialog. |
| The configuration file holding the new definition. |
| An administration user with the proper access. |
| 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.
Code Block |
---|
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 |
---|---|
| A numeric identifier of your company. Where to get this? |
| The js file holding the new resource definition. |
| An administration user with the proper access. |
| The password of the administration user. |
Plugin code extensions
To enable custom logic (e.g. calculated values) the framework comes with a plugin architecture.
TODO
Components & configuration
Concept overview
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.
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
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.
Cytoscape.js nomenclature
“nodes” → objects
“edges” → relationships
“eles” → a collection of edges and/or nodes
Framework / Core
Common configurations shared cross component.
Widget
A top level configuration. Defines a 3DDASHBOARD widget app that could be added to the compass.
Code Block |
---|
{ "$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 |
---|---|---|---|
| string | false | |
| string | ||
| string [array] | false | |
| component [array] | ||
| table [array] | ||
| table column [array] | ||
| data set [array] | ||
| service [array] | ||
| mode |
Component
Defines a UI component used by the widget.
Remove this? Move requiresContext and root def to root widget conf?
Code Block |
---|
{ "name": "??neverUsed??", "type": "table", "definition": "ups-roots-example", "root": true, "requiresContext": true } |
Property | Description | Type | Required |
---|---|---|---|
| a unique identifier used for reference (but never used?) | string | |
| the component type (e.g. table) - already by the def? | string | |
| the component identifier (e.g. table name) | string | true |
| true for the default top level component | boolean | |
| true in case the widget require a dropped context object | boolean |
Include Page | ||
---|---|---|
|
|
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 to 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 by administrators in configuration and is good to refer for detail (api’s are used internally and hidden from the administrator).
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?
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. There is an option to retain leaf nodes of that expand only.
Note |
---|
Note that the node statements also apply to the starting nodes (a difference compared to mql). Node statements need to match root nodes for expansion as well. |
Code Block |
---|
{
"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, 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 (data set type)
Filters out all eles matching a given cytoscape selector statement.
Code Block |
---|
{
"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.
Code Block |
---|
{
"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.
Code Block |
---|
{
"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.
Note |
---|
Note that the cytoscape selector statement is applied on the result set and that intermediate expansions getting there do not have to match the statement. See “Expand (data set type)”. |
Code Block |
---|
{
"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.
Note |
---|
Note that the cytoscape selector statement is applied on the result set and that intermediate expansions getting there do not have to match the statement. See “Expand (data set type)”. |
Code Block |
---|
{
"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.
Code Block |
---|
{
"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.
Code Block |
---|
{
"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.
Code Block |
---|
{
"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.
Code Block |
---|
{
"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.
Note |
---|
Note that node have to be a true root and that the cytoscape selector statement do not affect the root validation (all incoming edges even if not matching the statement could prevent the node from validating as a root). See “Expand (data set type)” |
Code Block |
---|
{
"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.
Note |
---|
Note that node have to be a true leaf and that the cytoscape selector statement do not affect the leaf validation (all outgoing edges even if not matching the statement could prevent the node from validating as a leaf). See “Expand (data set type)” |
Code Block |
---|
{
"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
|