Application Structure Discovery

The Application Structure Discovery module enables deep analysis of interconnected elements of an application or solution based on Iotellect platform.

For example, references in the expression language allow data from many different contexts to be utilized in an individual expression. As another example, bindings, whether in models, classes, dashboards, or at the server level, allow for the orchestration of complex context interactions in powerful applications. The Application Structure Discovery module allows these interconnected contexts to be identified, and the nature of their interaction investigated.

The Application Structure Discovery module offers the Structure context contains two variables, Structure Nodes and Structure Links, that provide information about interactions between different contexts. Those interactions are collected dynamically, meaning that whenever contexts interact to each other, relevant information is recorded by the Application Structure Discovery module and exposed via the Structure context.

Context interactions that have not been activated since the most recent server start or the execution of the Clear Structure function will not be recorded until they are activated.

When an application’s structure has been updated, interactions happened within its previous structure and recorded into the Application Structure Discovery database remain intact. Run the Clear Structure context function in order to clear the structure database and ensure that it will contain only the relevant interactions.

The Structure Nodes variable of the Structure context indicates the contexts which are interacting with other contexts. There are several types of relationships that can exist between nodes, each of which are explained below.

Each node represents the context of an entity (variable, event, or function) referencing or being referenced by another context. Because of this, there can be multiple links to a single node, and even nodes which link to themselves. For example, a model binding, which updates a variable in the same model, and thus in the same context.

The full description of the Structure Nodes variable can be found under the Structure context reference. The Node ID field is a unique identifier for the node, and is not repeated in the Structure Nodes table. The fields Source and Target in the Structure Links table refer to a Node ID value, and each Node ID will match at least one value in the Source or Target fields. No node will appear that does not have at least one connection.

The Structure Nodes variable can be accessed in the expression language with the following:

{structure:structureNodes}

The Structure Links table contains details for each reference, as well as a running count of how many times the reference has been activated since the start of the server or the context function Clear Structure has been called. There are several different types of references that are collected:

• Getting and setting variables is indicated by the value variable in the field kind, with action value either GET or SET. If a variable is SET, this indicates that the value of the source entity was applied to the value of the target variable. The GET action type indicates the value of the target variable was retrieved during an expression being evaluated in the source context.

• Function calls are indicated by the value function in the kind field, and the value CALL in the action field. The expression that called the function is located in the source context, and the function being called is a function of the target context. The name of the function is indicated in the entity field.

• Events being fired are indicated by the the value event in the kind field, and the value FIRE in the action field. The event named in the entity field is an event of the target context, and was fired by the context indicated in pinpoint.

Information about references is collected with different levels of detail, depending on the types of properties involved in the interaction.

• References in expressions allow the most information to be collected, including the line and column number in the expression where the reference occurs, indicated in the pinpoint field.

• References originating in transitive contexts do not include full details of the source of the reference, containing only the context and entity name of the reference origin. An example of a transitive context is when a reference calls a module function, and that function contains a reference to a variable, then the reference from the function is a transitive context. In this case, only the context and name of the function would be available, without detailed pinpoint information.

• When a device begins synchronizing, and attempts to get or set a variable, only the device's context information, and information about the variable the device interacted with, is recorded by the Structure context. Details about what device properties were involved in the synchronization are not recorded.

The Structure Links variable can be accessed in the expression language with the following:

{structure:structureLinks}

The following demonstrates the use of the Graph Component to visualize data from the Structure context. By creating clear and informative visuals, it helps uncover insights into the relationships among various data elements.

This example expects the following contexts to be configured:

• A Virtual Device named structure_example with context path users.admin.devices.structure_example

• A Model named structure_example with a single variable named var, and the context path users.admin.models.structure_example

• The model structure_example contains a binding, which is activated by the update of the variable random of the virtual device, and sets the variable var of the model to be equal to the value of random.

To check that the binding is working correctly, open the Additional Properties of the module to ensure that the variable var is regularly updated as the random value of the virtual device changes.

To effectively visualize references captured by the Structure context, create a Web UI dashboard with a Graph Component. The tutorial Creating a Dashboard to Monitor a Device offers instructions on how to create a dashboard and add components.

The Properties Editor of the graph component gives access to a few key properties for visualizing the references captured by the Structure context. Configure the indicated properties of the graph component as indicated by the table below:

{structure:structureNodes}

{structure:structureLinks}

{id}

{id}

{source}

{target}

{id}

This configuration captures all of the references currently active in the system, which produces a somewhat complex graph:

Interpreting this graph might be difficult because of the numerous interconnected nodes and edges, often with overlapping labels.

Filtering the lists of nodes and links to only include a specific subset of the graph is one way to improve the process of analysis. There are several ways to approach filtering the graph elements, but the most straightforward is to apply a filter directly to the {structure:structureNodes} and {structure:structureLinks} tables in the Node Expression and Link Expression of the graph.

In order to only show nodes and links related to the structure_example model and structure_example virtual device, it is enough to use the table processing function filter(DataTable table, String filterExpression) as shown in the following table.

filter(
  {structure:structureNodes},
  "contains(
    {path},
    'structure_example'
    )"
  )

filter(
  {structure:structureLinks},
  "contains(
    {id},
    'structure_example'
    )"
  )

The function filter(DataTable table, String filterExpression) takes two arguments, the table to be filtered, and the filterExpression that is evaluated for every row of the data table, and returns a table. The resulting table contains only rows where the filterExpression has evaluated to True.

For the Node Expression, the filter expression "contains({path},'structure_example')", evaluates to True if the path field of a row contains the string structure_example. Similarly, the Link Expression uses a filtering expression on the id field of the links table. As a result, the new graph only contains links and nodes which contain structure_example in the context path.

Another use case might be when analyzing the bindings of a Web UI dashboard, to filter out only paths that relate to that specific dashboard, for example filtering only nodes and links that include users.admin.dashboards.<dashboard name> in their Id.

Note that references in the current dashboard are automatically filtered out from the Structure variables when evaluated. In order to analyze references in a given dashboard, it is necessary to create a different dashboard to perform analysis, where the references in the dashboard to be analyzed will be visible.

The Clear Structure function allows specific interactions to be isolated within your low-code application. One primary use case is during debugging or exploration of complex expressions within models, functions or rule sets. Clearing the structure, establishes a clean slate, allowing the exact source of connections to be pinpointed and the flow of data to be understood.

For instance, if a model contains multiple rule sets with numerous expressions, some of which initiate connections you want to troubleshoot, clearing the structure helps identify the origin of those connections when the ruleset is run again. Additionally, when working with dashboards, which generate their own contexts at runtime, clearing the structure enables you to differentiate between these dynamic contexts and the preexisting contexts of the system tree, providing a clearer view of the intercommunication between them.

The pinpoint field within the Structure Links table offers valuable insights for precise source discovery, pinpointing the exact location of interactions within an application. This is particularly useful when dealing with complex expressions in models, bindings, rule sets, and other entities. The pinpoint field provides the line and column number within the expression where the interaction originates, allowing one to trace the source of connections with granular detail.

Consider the following example of a pinpoint value (line breaks and tabbing introduced for readability):

expression 'callFunction' 
  located at line 2, Column 3 
of expression originated from 
  'users.admin.models.tabList:ruleSets$rules[7].expression[2]'

The second part of the pinpoint field:

expression originated from 
  'users.admin.models.tabList:ruleSets$rules[7].expression[2]'

Indicates the precise location of the source:

• users.admin.models.tabList indicates the source context

• :ruleSets references the value of the ruleSets parameter of the source context

• $rules[7] indicates the value of the seventh row of the rules field of the ruleSets parameter

• .expression[2] indicates the value of the second row of the expression field of the data table referenced by rules[7]

The first part of the pinpoint field:

expression 'callFunction' 
  located at line 2, Column 3 

Indicates that the expression language function callFunction, located on the second line and third column of the field referenced by users.admin.models.tabList:ruleSets$rules[7].expression[2] is the source of the link.

This level of precision simplifies debugging, understanding application flow, and allows potential issues within a low-code application to be quickly identified.

Mixed context communication occurs when elements from both the server context tree and a dashboard interact with each other. A typical example could be a dashboard binding that references data both a component within the dashboard itself as well as the value of a device from the devices context.

Consider a scenario where a dashboard displays an average temperature value over a user-defined time period. In this case, there will be a binding which targets both a dashboard component (in this case a slider referenced on the dashboard with form/slider0) that collects user input and a device (in this case the context user.admin.devices.smartThermometer) that provides a history of temperature values over a given range.

In this case, the pinpoint field will contain an additional piece of information, the scope of the source. In this example, the pinpoint value as follows:

expression 'average' 
  located at line 1, Column 1
of expression originated from 
  'form/:bindings$expression[0]'
  (scope: 'users.admin.dashboards.tempDisplay')

Indicates that a binding form/:bindings$expression[0] was activated on the dashboard with context users.admin.dashboards.tempDisplay.

Was this page helpful?

Tell us more

Send

Thank you!