How to Enhance Web Console with Documentation & Suggested Value

In our latest release, we've introduced several new capabilities designed to improve the Inmanta Service Orchestrator experience. This blog post will break down some of these key changes to the Web Console. While typically northbound APIs are used to interact with the orchestrator, it’s not the only method. Our Web Console also functions as an operational view and a direct user interface. To enhance the user experience of the Web Console, we've developed two new features that significantly boost its usability.

Documentation tabs 

The first feature is to show documentation about the service instance such names, IP addresses, identifiers, links to other systems, etc. in the Web Console.   

This documentation can be generated from the orchestration model using a template or plugin. It supports markdown with mermaid diagrams. 

The documentation is created during a compilation of the model and stored in a root-level attribute of the service. This attribute needs to be properly annotated to ensure the Web Console recognizes it.  

The following attribute definition has such annotations added: 

entity Service extends lsm::ServiceBase: 
    string documentation = "# Lab documentation" 
    lsm::attribute_modifier documentation__modifier = "r" 
    dict documentation__annotations = { 
        "web_presentation": "documentation", 
        "web_title": "Lab overview", 
        "web_icon": "FaInfo", 
    } 
end 

1. An attribute of type string needs to be defined. We recommend giving it a default value so that the tab is not empty when the documentation has not yet been generated by the compiler. 
2. The attribute modifier must be r, which means that it is not defined by the user and only by the orchestrator. 
3. Annotations are used to control how the attribute is rendered in the web console: 
4. 1. web_presentation is set to documentation 
   2. Optionally web_title is set to the title that is shown in the tab. This title is only used when multiple attributes are defined as documentation. This title will be used on the card that contains the content of this attribute. 
   3. Optionally web_icon specifies a font awesome icon name (the second part without fa, for example FaTv). This icon is also only used when multiple attributes are defined as documentation. 

A call to lsm::update_read_only_attribute in the orchestration model uploads the content of the documentation tab. For example: 

instance.documentation = lsm::update_read_only_attribute( 
    instance, 
    "documentation", 
    value=std::template( 
        "./documentation.md.j2", 
        instance=instance, 
    ), 
) 

The documentation shows some other examples that also render a mermaid diagram. 

Suggested values 

The second feature is the ability to have suggested values and autocomplete in form fields. Fields with an enum type already offered this in a limited way: a select control with a fixed number of options. For example, an attribute of this type: 

typedef connection_type as string matching self in ["POINT_TO_POINT", "MULTIPOINT"] 

Results in a form control like this: 

The suggested values feature allows you to suggest values but at the same time also accepts other values. It exists in two flavors. 

The first flavor uses a static list defined in the model. The following example adds a number of suggestions to a field that accepts a cron like expression. These are non-trivial to write and having a number of command suggestions assists the user. It also still allows for a constrained string type with custom validation: 

entity Service extends lsm::ServiceBase: 
    cron_type? restart_on_calendar = null 
    lsm::attribute_modifier restart_on_calendar__modifier = "rw+" 
 
    dict restart_on_calendar__annotations = { 
      "web_suggested_values": { 
        "type": "literal", 
        "values": ["*-*-* 00:00:00", "Sun *-*-* 00:00:00", "*-*-01 00:00:00"], 
      }, 
    }
end 

This results in a form control like this, that also provide search and autocompletion: 

The annotation that controls this is web_suggested_values which as a value also needs a dict with two fields: 

• type which must be set to the value literal 
• values which is a list of string values that the Web Console should suggest to the user. 

Because they are defined as a default value in the model, you can only provide literal strings here. It is not possible to generate the list using a plugin. The second flavor offers dynamic suggested values based on a parameter in the orchestrator API. 

It is possible to have the Web Console load the list of values from a parameter registered in the orchestrator. These parameters can then be populated by the compiler or any other external system that has access to the orchestrator. The following example is taken from a service that supports a number of topology files that are part of a folder in an inmanta module. When the orchestrator compiles the model, it updates the list based on what is available in the module. This is defined as follows: 

entity Service extends lsm::ServiceBase: 
    string topology_file 
    lsm::attribute_modifier topology_file__modifier = "rw+" 
    dict topology_file__annotations = { 
        "web_suggested_values": { 
            "type": "parameters", 
            "parameter_name": "topology_files", 
        }, 
    } 

This results in a form control like this, which also provides search and autocompletion: 

The annotation that is required is also web_suggested_values which is also a dict that requires two fields: 

• type which has to be parameters 
• parameter_name which points to the parameter name in our parameter API endpoint. 

The suggested values are uploaded by adding the following code to the compiler: 

import lsm 
 
# Set the suggested values for the topology files 
lsm::set_suggested_values( 
    "topology_files", 
    custom_module::all_matching_files("docker-compose.*.yml"), 
) 

Conclusion 

These new features use annotations to provide developers of orchestration models with enhanced Web Console control, resulting in improved usability and situational awareness. This empowers developers to create more informative and user-friendly Web Console interfaces. We encourage you to explore these new annotation capabilities and discover how they can streamline your orchestration workflows.