Light My Way - Documentation

Page Content

1 The Administrator
- 1.1 General
- 1.2 Insight
  - 1.2.1 Light My Way usage
  - 1.2.2 Platform usage
  - 1.2.3 Subscription
- 1.3 Config
  - 1.3.1 Edit & Delete
  - 1.3.2 Add
  - 1.3.3 History
  - 1.3.4 Targets
    - 1.3.4.1 Target elements (green targets)
      - 1.3.4.1.1 CSS-based target formulas
        1.3.4.1.1.1 Example:
      - 1.3.4.1.2 XPATH-based target formulas
        1.3.4.1.2.1 Examples:
      - 1.3.4.1.3 Fields
    - 1.3.4.2 XPATH based (yellow) targets
      - 1.3.4.2.1 Starting Elements
      - 1.3.4.2.2 Fields
      - 1.3.4.2.3 Ignore Lists
      - 1.3.4.2.4 Fields
      - 1.3.4.2.5 Ignore By Parent
      - 1.3.4.2.6 Fields
    - 1.3.4.3 Ignore Anchors
      - 1.3.4.3.1 Fields
  - 1.3.5 Controlling when instructions are shown
    - 1.3.5.1 Contexts
      - 1.3.5.1.1 Fields
    - 1.3.5.2 Target states
    - 1.3.5.3 Focus conditions
      - 1.3.5.3.1 Fields
  - 1.3.6 Parent Contexts
  - 1.3.7 Overriding the built-in default configuration
  - 1.3.8 Server Mappings
- 1.4 Repository
  - 1.4.1 Create
  - 1.4.2 Root repository
  - 1.4.3 Edit
  - 1.4.4 Settings
  - 1.4.5 Read Only
- 1.5 User management
  - 1.5.1 Granting access to TECHNIA users
  - 1.5.2 Repository access
- 1.6 Data management
  - 1.6.1 Document view
  - 1.6.2 Export guides
- 1.7 AI Settings
  - 1.7.1 Add AI Settings
  - 1.7.2 Default prompt
  - 1.7.3 Vector store files
- 1.8 Import & export
  - 1.8.1 Configuration export
  - 1.8.2 Data import / export

The Administrator

To enable authors to record guides easily by point and click, without getting into the technical details, pre-set configurations are used to control how things are recorded for different platform target elements and contexts.

As example these configurations control

How target elements are identified
The contexts used to control when instructions should show

For the supported platforms, such as 3DEXPERIENCE, rich and build-in default configuration are included with the product.

To allow authors to record new, customized or for other reason modify or override configurations to better fit customer specific needs it is possible to extend these configurations.

TECHNIA is interested in extending the built-in configurations and standard platform product support.

General

To overview all recorded data, export/import or to better support your authors specific recording needs, there is an Admin UI. In the admin UI you can easily create, edit and remove configuration items (e.g. contexts). The admin UI is web based and available with any supported browser.

To access the Admin UI go to https://lmw.technia.cloud/admin

The Admin UI is protected by login authentication using your username and password (that you get with your subscription).

Insight

The client evaluation data can be used to provide valuable statistics and insights for administrators.

Privacy

Privacy policy was updated 2024.1.0 to cover insight data updates.

Insight logging is anonymous by default, but real user names can be enabled to make visible in subscription overview.

Real user names is not available for LMW or platform usage.

Insight logging is enabled by default but can be turned off completely or partly using repo settings.

Light My Way usage

For administrators to see anonymized light my way usage statistics, such as the number of times an instruction has been viewed. This information can be useful to identify popular or unused guides, and even identify misconfigured instructions or trends.

The Light My Way usage insight is found in the Data tab.

Platform usage

For administrators to see anonymized target platform usage statistics, such as how many times the different apps has been used. This information can be used to understand true user behaviour, identify misuse, training needs or unused parts of the application.

Platform usage is found in the Insight tab.

Platform contexts logging is controlled in the Config tab. TECHNIA maintained configs can be toggled of with Repo settings.

Subscription

For TECHNIA and administrators to audit the install base of Light My Way.

The information includes an anonymized User Id (browser install), their last use date and language settings. There are also some visuals displaying weekly users and a accumulated users chart over the full subscription period, this can be used to understand the trend and if the current subscription will cover the need for the full period.

Subscription user detail will be found in the Subscription tab.

Optionally the DS and/or Windows user can be included. See managed storage keys for details.

Config

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 either click on the add button in the tree list under the chosen configuration type or click “+ Add” in the top bar.

History

Check configurations history, e.g. who and when created or modified a context or Target Element.

Targets

Targets are the html elements that an instruction is tied with. The instruction callout is positioned relative to the target and is displayed if the target html element is present only. There are two different methods to identify a target element.

Target elements (green targets)

This is the preferred method for authors to select target elements and will only store key value identifiers of the target with the instruction data. The selector used to identify the target is maintained as configuration and makes it possible to improve over time.

This is the method of the built in and with product supported green targets.

Targets defined this way will be presented in highlight and green to authors (as the supported targets).

Administrators could extend the list of target elements to indicate good target selections to their users.

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

CSS-based target formulas

Target elements defined using CSS-based formulas.

Example:

Formula: form[name='frmFormView'] tr{0} td.field
Read value: id

In this case the stored data on the instruction is the id of the parent tr but the selected element will be the child td.field.

This can be done with multiple read values and multiple formulas enabling platform independent targets with different css selectors but same matching unique identifier (read values)

XPATH-based target formulas

Target elements can also be defined using XPATH-based formulas.

XPATH should be used only where a CSS formula is not possible, as XPATH formulas are more complex and slower to evaluate, they should only be used when necessary.

Reasons to use XPATH formulas could be that the desired target element has styling: 'pointer-events: none', an overlapping element is blocking the target element with unique identifier or there is some other advanced pathing needed.

Defining a target element using xpath formulas and readvalues is done the same way as with css formulas, however there are some considerations to make a valid xpath.

When using readvalues in xpath formula the index '{0}' is replaced by ` and contains(@attribute, 'attributevalue')` for each readvalue in the formula.

The xpath formula with readvalues must contain some base identifier to make it evaluable without a readvalue.

Examples:

//div[{0}] => //div[ and contains(@attribute,'value')]

//div[@id='topbar' {0}] => //div[@id='topbar' and contains(@attribute,'value')]

//div[contains(@class,'topbar') {0}] => //div[contains(@class,'topbar') and contains(@attribute,'value')]

Fields

Name	a unique id to identify this type of target
Display	how to present the target to the author
CSS Formulas	css selector-based formulas used to match the target element and read value
XPATH Formulas	xpath selector formula used to match the target element and read value
Read Values	the unique data used to match the selected target value with the data present it in display to the author
Inner Text	if checked the inner text of the target will be stored as a read value and matched with the selected target
Parent Context	An array of parent context ids. During evaluation, one of the parent contexts need to be found for the target element to be evaluated. See below for more information on Parent Context.

Focus configuration will affect green or highlighted target elements

XPATH based (yellow) targets

To provide flexibility there is also a fall back target recording method using xpath. Using the flexibility of xpath authors can record anything they want but will also tie instruction closer to the html and it will be more sensitive to change. When selecting a yellow fall back element an xpath is automatically generated. Multiple configuration types are used to control how xpaths are generated.

Built in with the product is a set of ignored classes attributes etc to generate a good xpath starting point.

Starting Elements

Starting elements are used to truncate all XPATH before the matching starting element. This to make the stored XPATH nice, clean and less sensitive to context, changes or version.

Starting elements are defined using XPATH.

Fields

Name	A description used to understand what the starting element does
Xpath	an xpath expression, if matched somewhere in the parent structure during target element selection, the recorded data address will start from this point and all xpath beyond this point will be omitted

Using the Focus feature, it is mandatory for target element's selection to start within the focus area. I.e. starting elements have to start on or within the focused area or it will be excluded from evaluation.

Making a too short XPATH would require to control more of when to show the instruction using contexts.

For the staring element to match, the data have to be part of the generated xpath (can not be in the ignored list)

Ignore Lists

Ignore lists are used to define the class or attribute names to exclude from the recorded XPATH. This to make the stored XPATH nice, clean and less sensitive to context, session, changes over time or version.

Fields

Class	the class to be ignored in the recorded data
Attribute	the attribute to be ignored in the recorded data

The ignore list configurations are global and will affect all view and target element XPATH selection. Only class and attributes that should be avoided in all cases should go here.

Ignore By Parent

Ignore by parent is used as ignore lists but will make the configuration valid within the scope of a specific parent only. This would be useful if you like to exclude common attributes like name in a specific scope only but retain it in other places. The name and details fields are used to identify parent elements. Attribute, Classes and Inner text to control ignore behavior in scope of that parent.

Fields

Description	used by admins to understand what is covered
Parent Name	the element type used to identify the parent element
Details Name	the attribute name used to identify the parent element
Details Value	the value of the matched attribute used to identify the parent element
Attributes	the list of attributes to ignore in scope of the matched parent element
Classes	the list of classes to be ignored in the scope of the matched parent element
Inner Text	if checked the inner text of targets within the scope of the matched parent will be included

To avoid the risk of ignore configuration affecting recordings for other parts of the application in a negative way, using by parent scope is good practice.

Ignore Anchors

Ignoring anchors points during target selection could be useful for cases when it does not work well. Anchor points could be problematic for very small targets or if the target by script automation disappear as you hover an anchor point and then it makes sense to inactivate it. In these cases you could instead define a default and the author could always control this in the next step using the advanced settings for the instruction.

Fields

Ignore	a list of classes to identify elements that should be ignored
Position	the default position to be used in case of match

Controlling when instructions are shown

To make instructions show at the right time, the recordings have to react properly to application state. For this to happen there are some different configurations related. While ‘Contexts’ and ‘Target states’ are presented for the author to choose, the ‘Focus’ condition is silently used in the background.

Contexts

The list of contexts is used by authors to control when an instruction is shown/evaluated. The list of contexts is controlled in the Admin UI and is only presented to the author if available for inclusion with the current target selection.

The contexts are configured using CSS selectors.

Fields

Name	a unique id
Display	how to present the context to the author
Container	the element to use as base for the context evaluation
Type	exist to see if one target element is present option to allow author to choose (often used for target states)
Default	the default condition name
Only for target	evaluate the context for selected target element only (see target states)
Read	the unique data used to store the selected context value with the data present it in display to the author
Conditions Name	a unique id for the condition option
Conditions Display	Displayed to author in drop down in case of option type
Conditions Selection Selector	css selector to match the element
Conditions From	The evaluation technology
Visible	Require the context element to also be visible otherwise excluded
Default Enabled	Defaults the context to be toggled for inclusion as the author records
Hidden	Hides the context under expandable more section
Parent Context	An array of parent context ids. During evaluation, one of the parent contexts need to be found for the context to be evaluated. See below for more information on Parent Context.

Using contexts is good for performance as it filters out instructions for evaluation based on matching context state for the current view.

Target states

State specific to the selected target element is used to control when a callout should display when the target itself carries state.

The target states are configured using CSS selectors the same way as contexts, but you simply check only for target checkbox.

Focus conditions

Focus conditions are used to limit evaluation within 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 conditions are configured using CSS selectors.

Fields

Name	a unique identifier
Description	used by admins to understand why it was added
Layer Index	defines priority in case of multiple focus elements is found
From	css query selector currently only supported
Selector	css selector to identify the focus element
Visible	if the focus element have to be visible to be valid
Only Inside Parent Condition	If checked/true, the focus condition will only affect callouts inside the same parent condition.

Using focus is good for performance as it limits the evaluation to happen within the focus element.

Focus configuration will affect green or highlighted target elements during selection

It is mandatory for target element's selection to start within the focus area. I.e. starting elements have to start on or within the focused area or it will be excluded from evaluation.

Parent Contexts

Parent Contexts control if a target element or context should be evaluated or not.

If a target element or context has parent contexts then one or more of those parent contexts needs to be available in order for that target element/context to be evaluated.

For target elements this is mainly a performance improvement for authors, but for contexts this limits (scopes) the evaluation of all contexts to only evaluate those that have a possibility to be present.
This improves the performance for all users.

E.g. 3DDashboard widgets should only be evaluated in 3DDashboard and not 3DSpace.

Additionally authors also need to enable the parent context first in order for the rest of the contexts to show up. This also improves performance for all users.

Overriding the built-in default configuration

Light My Way comes with a rich set of built-in and supported configurations for target platforms. If for some reason like to override behavior of a built-in configuration it is possible to clone it into your target configuration.

Cloned definitions will be styled italic in the admin UI.

By cloning a configuration you will take over that definition and will not benefit of potential updates to the built-in definition.

Server Mappings

Server mappings will be deprecated

Instead of server mappings customers are advised to use registry settings to auto-connect new installations to the correct account and repository - Client Installation.

Repository

Repositories are commonly used for separating guides and/or config based on state. E.g. one repository could contain “released“ guides for use in production and one could contain guides that are “in progress“ or not completed yet, before they are moved to the production repo to be used by the consumers. (companyName/prod & companyName/dev).

Switch between repositories from extension is done in extension settings.

Create

Create a new repository by clicking the toolbar “+ Add” command, then selecting “Create New Repository“.

Create new repository

Root repository

If a repository has root repository toggled on then that repository will be included in the root server URL e.g. https://lmw.technia.cloud/<customer-name>.

This makes it possible to have separate repositories for separate domains, processes etc. and the consumer would simply connect to the root repository to access all guides.

Authors will still have to connect to the specific repository to edit the guides e.g. https://lmw.technia.cloud/<customer-name>/3dx

Edit

Edit a repository by clicking the edit icon next to the repository name.

Edit existing repository

Settings

Example:

{
  "evaluateToggledGuidesOnly": false,
  "delays": {
    "mutationCallback": 250,
    "mutationListener": 100,
    "scrollListener": 100,
    "inputListener": 250
  }
}

Debounce settings

Setting (key)	Description	Type	Default

Setting (key)	Description	Type	Default
`delays`	Used to tune debounce for performance based on your env specifics. A low debounce gives a quick response to the user but a higher performance footprint as evaluation happens more often. All evaluation debounce is controlled inside `delays` key. Debounce time is specified in milliseconds.	`object`
`delays.inputListener`	Input fields. e.g. debounce when typing text	`number`	`250`
`delays.mutationCallback`	The time between evaluation	`number`	`250`
`delays.mutationListener`	How often html DOM updates is communicated (per document / iframe)	`number`	`100`
`delays.scrollListener`	When scrolling how long to wait until reposition	`number`	`100`
`delays.usageListener`	Debounce for usage actions used by usage insight feature	`number`	`1000`
`evaluateToggledGuidesOnly`	Depending on your authors recording methodology you might consider a different evaluation strategy. In case you want to record guides in the context it belong only and use the available now feature you will go by the default and evaluate all by context. In case you want to guide users from anywhere to everywhere the available now feature makes no sense but the extra evaluation would only drive load and you should evaluate toggled guides only.	`boolean`	`false`
`logUsage`	Toggle off or on usage logging	`boolean`	`true`
`logUsageLocation`	Set this to `false` to not exclude location from usage logs.	`boolean`	`true`
`logEvaluationStats`	Set this to `true` to log evaluation times for debugging.	`boolean`	`false`
`logUsageConfigs`	Used to select what configs should be logged into the platform insight.

The Administrator (LMW)

Light My Way - Documentation

Page Content

The Administrator

General

Insight

Light My Way usage

Platform usage

Subscription

Config

Edit & Delete

Add

History

Targets

Target elements (green targets)

CSS-based target formulas

Example:

XPATH-based target formulas

Examples:

Fields

XPATH based (yellow) targets

Starting Elements

Fields

Ignore Lists

Fields

Ignore By Parent

Fields

Ignore Anchors

Fields

Controlling when instructions are shown

Contexts

Fields

Target states

Focus conditions

Fields

Parent Contexts

Overriding the built-in default configuration

Server Mappings

Repository

Create

Root repository

Edit

Settings