2021.4 Light My Way - Product Documentation

The format is a subject of change and requires close collaboration with R&D as of this release.

Legal Notes

Copyright 2021 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

Light My Way is a software installed client side in browser as a web extension with the purpose of boosting user PRODUCTIVITY and ADOPTION to a low COST, this by providing VISUAL GUIDANCE and USER TRAINING directly IN-APP. To display the right instruction at the right time each instruction is bound to application state using html identifiers such as XPATH & CSS selectors. New instructions are also recorded through the web extension. Data is stored and retrieved in external service using http(s) and web sockets called from the extension background script.

  • 3DEXPERIENCE in-app user training

    • The right instruction at the right time

    • App state sensitive

    • Complex / dynamic processes supported

  • 3DEXPERIENCE in-app training creation

    • Create instruction by point and click

    • Relate instructions to app state (object type, UI components etc)

    • Best practices built in

  • Up and running with 3DEXPERIENCE in a minute!

    • Cloud subscription (no infra structure required)

    • No server deployment or dependency to normal release cycle (cloud also supported)

    • No service required (pure software deal / instant value)

Platforms

Light My Way is a generic software that works with all html based applications with the right configurations (described in the administration chapter).

An extra effort has been put into making it work well with 3DEXPERIENCE platform. Configurations to identify UI elements of 3DSPACE, 3DDASHBOARD and Value Components are built in.

 

 

 

 

Supported Platforms

  • 3DEXPERIENCE (3DSPACE & 3DDASHBAORD)

    • 2013x until latest

  • DELMIA Apriso

  • Value Components (TVC & Helium)

    • Latest

Configurations making the Consumer and Author roles work well are built in for the supported platforms. No project specific administration required to get started recording standard use cases using a rich set of built in conditions and configs.

This release still require R&D collaboration (to ensure the product works well for you and so we fully understand common need). Product development has mainly been driven with 3DSPACE 2018x - 2021x Create Part and Change Process use cases so far. A long detailed list of supported targets, conditions and focus elements can be shared on request.

System Requirements

Server

The server will be hosted as a cloud service sometime 2021. Meanwhile the server can be installed in private networks or external servers. The server is based on https://nodejs.org and nodejs system requirements applies.

Client

Supported browsers

  • Chrome (85 or later)

  • Microsoft Edge (85 or later)

Installation

The extension architecture allows to provide user guidance without dependency to normal release cycles. No access to the server of the target application is required and guides recorded and distributed for CLOUD hosted solutions is supported. Light My Way has no footprint on the target server application what so ever and no server side deployment is required.

Server

As CLOUD service

The normal setup is that TECHNIA will host the data service in the CLOUD and all you have to do is to connect to the account you get with your subscription.

Server on premises

If you for some reason unable to use the CLOUD service there is also the option to install and host the server locally on premises.

There are two options for this. Either you use a Docker image which can be provided by us and added to your environment, or you install the server manually by following these steps:

  1. Install latest (LTS) https://nodejs.org/en/download/

  2. Expand lmw-server-VERSION.zip into desired directory

  3. Run start.cmd

Port configuration

Server is started by default using the port 8080 - http://localhost:8080  

The port can be configured the following ways:

  • by setting the Environment Variable PORT=1234

  • starting the server with an argument -p or --port e.g. node server/src/index.js --port 1234 

Note that a web socket connection is opened on the configured port ws://localhost:<port>/lmw/socket.io

As a windows service

Light My Way (and other nodejs apps) can be set up as a service using https://www.npmjs.com/package/qckwinsvc

Apache config

If you want to set it up with apache, here are some example configs.

Connect to a PostgreSQL database

Connect to a PostgreSQL database by setting the following environment variables on the LMW server’s machine

Environment variable

Details

Example value

Environment variable

Details

Example value

LMW_DB_TYPE

Type of the DB, possible values are “postgres” and “sqlite”

postgres

LMW_DB_HOST

URL under which the DB is hosted, without https:// and port

lmw_postgres

LMW_DB_PORT

Port for the DB

5432

LMW_DB_DB

Database name

postgres

LMW_DB_USER

Database user

admin

LMW_DB_PW

Database password

KakjdifHSDIF745lasfp

LMW_DB_RETRY

On startup LMW server will try to connect to the DB every {…} ms. Helpful when LMW server and the DB are started together.

3000

If no environment variable is defined, the internal SQLite database is used. We are currently only supporting PostgreSQL.

DNS Service

To access Instructions, the Browser Extension needs to request them from the Light My Way Server. This can be done by adding the Server URL in the Browser Extension Settings Popup. Due to restrictions of Browser Extensions, it is not possible to set the Server URL from "outside". Meaning that this URL cannot be provided during an Installation.

To avoid that every single User has to provide the Server URL on his own, we implemented the Light My Way DNS Service. A simple Server with a configuration file which contains a mapping from the Browser URL to a Light My Way Server URL.

e.g.

Browser URL: 3dspace.customer.com
DNS Configuration file:

1 2 3 { "3dspace.customer": "<https://lmw-server.customer.com"> }

The key 3dspace.customer is searched in the Browser URL for a match and if it is found, the Server URL will be returned.

As the DNS Server Address needs to be available in the Extension. It is fixed and set to https://marketplace.technia.net/dns
This means, we are hosting the DNS Server for you, if you need this functionality.

How does it work for you:

  1. Install the Browser Extension from the Chrome Store

  2. Start Chrome/Edge and open a Website where Light My Way is enabled

  3. If no Server URL is defined in the Settings Popup, the Browser Extension will automatically contact the global DNS Server

  4. You can manually overwrite the Server URL at any time, to reset the URL to the one defined by the DNS Server, simply remove the Server URL

  5. The DNS Server is only contacted if the Server URL is empty

What you need to do:

If you want to use the DNS Service, please provide us your local Platform URL for e.g. 3DSpace and the URL of your local Light My Way Server. The DNS mapping can also be edited in the Admin UI.

Client

The client extension comes in 2 versions: The consumer and the author application. The Author extension also includes the consumer app.

  • Consumer

    • Display instructions

  • Author

    • Display instructions

    • Create instructions

Installation Option 1 - Installer (.msi)

For IT teams to be able to distribute the extension to large user groups and prevent excessive support an .msi file is provided.

The .msi installer adds registry entries for automatic side loading of the chrome store hosted extension.

Installation Option 2 - Chrome web store

The web extensions are hosted on chrome store and is actually what the .msi file side loads into the browser. One option is to manually install the extension directly from chrome store. The result will be the same.

  1. Open in Chrome or MS Edge

    1. Click open Author in chrome store

    2. Click open Consumer in chrome store

  2. Click “Add to Chrome”

 

Installation Option 3 - Microsoft Edge Add-ons

  1. Open In MS Edge

    1. Click open Author in Microsoft Edge Add-ons

    2. Click open Consumer in Microsoft Edge Add-ons

    3. Click “Get”

 

Connecting to the server space

  1. Click the extensions menu

  2. Click “Light My Way“ icon

  3. Enter server URL with domains and press TAB

  4. “Connected successfully” should appear in green

 

 

Roles

Light My Way supports 3 different roles or types of users. The ‘User guide’ covers the Consumer and Author roles while the ‘Administration guide’ covers the Administrator role.

Consumer

Author

Administrator

User

User

System

Needs guidance using a web application

(user, engineer or similar)

Knows how to use a web application

(process owner, teacher or support)

Knows HTML/XPATH/CSS

(developer / system administration)

  • Consumes in app user guides.

  • Gets the right instruction at the right time (based on app state).

  • Easily finds and toggles valid process guides relevant for him.

  • Records instructions in app by clicking the UI.

  • Chooses from a list of conditions to tie instructions to app state.

  • Lists & maintains instructions over time.

  • Configures the tool to better support (hide complexity) the author.

  • Extend element selection (3DX standards built in).

  • Extends conditions (3DX standards built in).

User guide

Finding the application

The Light My Way layer is added to the right side in the target application. Depending on role one or two tabs will be visible. The tabs are rendered on top and will not interfere with the UI. If the tabs for some reason are in the way you can move them by drag and drop. Clicking a tab will expand and display its content so that you can access its features. By clicking the tab again it will collapse to its original state.

The Consumer

The consumer will find the ‘LIGHT MY WAY’ tab at the right of the application. This tab will be used to access all content and control preference.

Groups

All instructions belongs to a group. A group allows you to manage multiple instructions in one go and is often equal to a use case.

Toggle on/off

The consumer can toggle instruction groups to be displayed on/off. The toggle state is persisted over time (browser local storage) and allows the user to keep his favorite guides always on so that the right instruction automatically appears as the application state is right.

Available now!

To make it easy for users to find help relevant to the current view the guides, with at least one instruction valid for the current view (app state) is displayed on top.

The user also get aware there is help to get in case the panel tab is minimized. If there is a guide available but it is disabled a shining indication appears on the panel tab.

 

 

Finding guides

Users can find instruction groups by a filtering functionality. The filter field opens by clicking the search icon. Entered text will filter down the group labels matching the text. The filter function is cancelled by pressing the arrow and any entered text is cleared by pressing the x.

 

Tags

The tags are accessed under the preference icon at the top right corner. By enabling at least one tag all groups will be filtered down to only include those matching the selected tags. Tag filtering is a good way to hide the guides not of value to you and allow you to focus on the ones that are.

E.g. Tags can be used to filter instructions by role, experience level or language.

Instructions

Instructions appear

The visual callout element that guides the user at the end we call instructions. To ensure that the right instruction appear at the right time, all callouts reacts and validates as the application state change.

Instructions valid for the current view and application state automatically appears on screen. With the condition that its group is toggled active.

In case of multiple instructions appearing on top of each other. The hovered instruction would go on top.

Dismissing instructions

In case an instruction callout is in the way it can be dismissed by clicking it. Instruction dismissal is temporary and will appear next session as long as application state and group toggle state still say it should .

 

Some instructions can contain links. When a link is clicked the content will open in a new browser tab.

 

The Author

The author will find the ‘LIGHT MY WAY’ tab at the right of the application so he can see how the consumer view would be.

On top of that the ‘AUTHOR’ tab is available for content management.

Groups

Listing Groups

In the authors tab all groups will be be listed.

Deleting Groups

To delete a group click the trash icon next to it

Modifying Groups

Clicking the edit icon next to a group will open the create form an allows you to modify group definition.

 

Creating Groups

Click ‘Create Group’ button to open the create form, give the group a label and click save.

Tags

A group can be tagged with one or more tags allowing the consumer to filter out the guides that matters to him. Simply type the desired tags in the tags field to tie the group with it.

Tags can be maintained in the preference menu later on.

Color

The color of the callouts can be defined. Blue is the default color.

 

 

Instructions

Creating instructions

To create an instruction go to the authoring tab and click the ‘create callout’ button or press the plus icon next to a group directly

Modifying instructions

Find the instruction in the group tree list and click the edit icon next to it.

Ordering instructions

To change the order of instructions simply move the mouse over an instruction until you see the movement cursor. You can now use drag and drop to move the instruction up or down in the list.

 

Controlling type

You can change type of the instruction to ‘Info’ to render instructions more compact. Then the user will have to actively click the small info symbol to render the full callout.

Selecting group

You can select the group an instruction should belong to. By pressing the group plus icon the group will be prefilled.

Enter instruction text

Instructions has two fields. The title renders in bold and the description renders as paragraph and is suitable for longer texts.
The description field features a rich text editor which allows you to apply basic formatting with links, lists.

Conditions (when to show/evaluate the instruction)

An instruction can be tied with application state so that it appears only when it should. This is achieved by selecting among a set of built in conditions. The administrator can provide more conditions to choose from if needed.

E.g. an instruction could be tied to a specific type or state so it only appears as these conditions are met.

Note: If more conditions are needed to record your use case extending the list is possible by configuration. Contact you administrator. TECHNIA is also interested in building in standard conditions in products.

 

Callout positioning

A callout is possible to position in a number of ways. To select the position, use the drop down. Default position is bottom.

 

 

Conditional elements

If the built in conditions is not sufficient to control when an instruction should appear one or more elements could be used as conditions.

E.g. To control that an instruction should only appear when logged in user text is not ‘Tom Waits’ you could log in as that user and click that element holding that text. Conditions can be inverted using the NOT option.

 

Selecting target elements

To select the target element click the ‘SELECT’ button below the ‘Target element’ label. A visual indication will appear (the green rectangle around “Home Dashboard”).

If the XPATH of the selection and the targeted element doesn’t match, a different visual indication will appear (the red rectangle around “Issue Categories”) and also another indication to indicate which element will be selected.

To complete selection hold control key and left click mouse or press space (ctrl+click/space).

Note: If a target is not possible to record the proper configurations to support it is not in place. Contact you administrator. TECHNIA is also interested in building in more standard target support.

 

 

Target element conditions

Some target elements change state itself. Such elements can be configured with a condition that controls instruction visibility based on its state.

e.g. Tabs can be configured with a target element condition so that the author can control instruction visibility depending on if it is active or not.

Note: If more conditions are needed to record your use case extending the list is possible by configuration. Contact you administrator. TECHNIA is also interested in building in more target element conditions in product.

 

Preview instructions

While creating or modifying instruction an instant preview is made available. The preview instantly reacts and displays changes in text just as the consumer would see it.

Links

To add a link to an instruction simply enter the link text and then click on the link icon in the editor to add the url.

Validation

To ensure proper data some validation is applied to the instruction create / edit form.

  • At least 1 condition is needed otherwise a warning is displayed (can be overridden by author)

  • Title and instruction is mandatory

  • Recorded XPATH have to be valid (details found when expanding target element)

 

 

 

Password

To ensure unauthorized authoring a password is required the first time the author tab is used. The password will be stored in local storage so you don't have to enter it the next time authoring using the same machine.

Administration guide

Background

Since the release of Light My Way 2021.3 the former JSON based configuration is now stored in the same database as the instructions.

JSON Format

It is still possible to edit the configurations manually as in previous releases. When is this useful? To do this

  1. export the database content to the json format

  2. change the files manually

  3. delete the database

  4. import the json data into a new database

Import / Export Configurations

TODO

Import / Export Data

TODO

 

Admin UI

To edit the configurations there is an Admin UI where you can easily create, edit and remove configuration items (e.g. conditions) directly in your browser without the need of any special software (IDE).

Should you have any questions or suggestions contact TECHNIA support.

To access the Admin UI go to <server path>/adminui/

 

Edit & Delete

To edit or remove a configuration item simply choose the target platform in the tree list and the configuration item you want to edit or remove.

Add

To add a new configuration item ether click on the add button in the tree list under the chosen configuration type or click “+ Add” in the top bar.

Targets

To create a new target ether clone an existing one or add a new one by clicking on the “+ Add” in the top bar and choose “Create New Target”.

Target elements are identified using XPATH. How XPATH’s are constructed can be controlled in the Admin UI.

The generated XPATH is controlled using starting elements and exclusion patterns and can be scoped by parent element so that e.g. tables have its own ignore pattern.

Describe the fields more in detail so that a customer admin understands what to put there

Update target 3DX screenshot

Server mappings

To edit the server mappings (to match each target with the correct environment) select “Server Mappings” under the chosen target or click “+ Add” in the top bar.

 

Describe the fields more in detail so that a customer admin understands what to put there

 

Conditions

The list of conditions (used by authors to control when an instruction should show/evaluate and for performance) can be controlled in the Admin UI.

 

Describe the fields more in detail so that a customer admin understands what to put there

 

Add screenshot from admin UI condition form?

 

 

Target element conditions

The conditions specific to a target element can be controlled in the Admin UI.

Describe the fields more in detail so that a customer admin understands what to put there

Check the checkbox.. only for target..

Add screenshot from admin UI condition form?

 

Focus

Focus conditions can be used to limit evaluation to the focused element if present. Very useful to make all other callouts not in the focus group automatically hide as long as the focus condition is fulfilled (e.g. hide background callouts when search is open). Focus is a silent feature and the author is not aware this actually happens behind the scenes.

Focus is controlled in the Admin UI.

Focus conditions are configured using css selectors and are added during recording (when adding new focus conditions recording have to be updated).

Describe the fields more in detail so that a customer admin understands what to put there

Add screenshot from admin UI condition form?

 

Overriding the built-in default configuration

TODO

Add screenshot from admin UI condition form?

 

View data

TODO

Add screenshot from admin UI condition form?

 

Ignore anchors

TODO

Add screenshot from admin UI condition form?

 

Password

Password are controlled in the Admin UI.

What is it used for? Add screen from Admin UI

Licenses (3rd party libraries)

Light My Way uses open source libraries. All used software licenses are listed in the attached markdown file.

Release notes

2021.4

Extensions

  • Clear data directly after Target switch

  • Fixed: Multi Author broken for one browser - multi window

  • Fixed: Missing innerText in xpaths

  • Fixed: Callouts/Infos get stripped off if container width is too small

  • Fixed: URL in Rich Text does not work if it does not start with http(s)

Author

  • Author key input password

  • Evaluate UI Conditions only while selecting the target
    Fixed: License Key not found after Target Renaming

Consumer

  • None

Server

  • Authorize author on mutations

  • Restrict Access to LMW Server

  • Track the current Consumer/Author count

  • Improve the log detail if DB Connection cannot be established

  • Fixed: Frequent Server Disconnection

Admin UI

  • Add Login

  • Change innerText to default true

  • Illustrate icons for conditions and ignorelist

  • Add loader component

  • Improve visibility of notifications

  • Make Author keys editable from the AdminUI

  • Move license.json into DB

  • Create new Target

  • Create new Target based on existing Target (Clone)

  • Delete Targets

  • Rename Targets

  • Manage DNS config mappings

  • Import and export of configurations

  • Enable Caching

  • Add success and failure notifications in admin ui

  • Add expand/collapse all commands

  • Add info texts/description for fields

  • Autocompletion for fields

  • Fixed: Undefined booleans in Admin UI should default false