WebStudio

WebStudio is a Web App that allows you to compile a dashboard of dynamic responsive Widgets to visualize the data from your AspenTech Inmation system in a web browser. WebStudio uses the Web API to retrieve data from the system and allows access to your data from anywhere with an internet connection.

To begin using WebStudio immediately it is recommended that you create the WebStudio Demo Data objects in your system using the Examples_WebStudio_Demo_Data_V<n.nn>.json MassConfig file available on the JumpStart Resources page. Import the JSON file into a MassConfig display and click [Apply] to create the objects. This will give you a good starting point to begin creating widgets in the workspace.

Launching WebStudio and Authentication

WebStudio connects to the system through the Web API. To launch the application, open a web browser and enter the url containing the hostname of the Web API you wish to connect to and the port (default is 8002).

Refer to "Loading WebStudio" for an explanation of all connection options.

    http://<hostname_webapi>:<port>/apps/webstudio/

When WebStudio is first opened you will be greeted by a sign-in dialog to authenticate the connection to the Web API and ultimately the core.

To connect, you will need to enter the Hostname and Port and an optional workspace Name (any previous connections will be saved and are made available for future use in the Saved Connections panel on the left).
If the Web API has been configured t, then you can turn on the _Secure communication switch.
The authentication method for connection can be chosen at the bottom of the dialog. There is the choice of using given Credentials (the built in system Profile Credentials, Active directory, machine credentials) or a Single Sign On (SSO) method (Integrate Windows Authentication).

Icon	Function
	Click this button to create a new saved connection. Once all the fields are filled in and the [Connect] button is pressed, the new entry is persisted and will be available next time the sign-in dialog is used. Note: If you already have an existing connections settings selected when the button is pressed, the Hostname, Username and Password fields are cleared, but the name field is retained. Consequently, unless the name is updated, a second item with the same name is created when you connect to the back end. Saved connection details can be managed by clicking the ellipsis (…) next to the saved items
	Shows the content of the browser console. Reviewing the console logs can be helpful when trying to diagnose connection failures.
	Copies the URL link (including authentication information) for sharing.

Icon

Function

New Connection

Click this button to create a new saved connection. Once all the fields are filled in and the [Connect] button is pressed, the new entry is persisted and will be available next time the sign-in dialog is used. Note: If you already have an existing connections settings selected when the button is pressed, the Hostname, Username and Password fields are cleared, but the name field is retained. Consequently, unless the name is updated, a second item with the same name is created when you connect to the back end. Saved connection details can be managed by clicking the ellipsis (…) next to the saved items

Console

Shows the content of the browser console. Reviewing the console logs can be helpful when trying to diagnose connection failures.

Copy Link

Copies the URL link (including authentication information) for sharing.

Complete the Sign In Dialog with details appropriate to your own system and click [Connect].

WebStudio Workspace

Once you have successfully signed in, WebStudio will open with either an index page or an empty model screen, depending on how the core you connected to is configured. We’ll return to the "index" page case in a bit.

The icons in the menubar are used to create and edit views. Views/dashboards are generally referred to as compilations in AspenTech Inmation.

Icon Function

Icon	Function
	Show the Widgets template dialog used to insert widgets into the compilation
	Load a previously saved compilation JSON file from disk.
	Save the current compilation to disk. The file name is based on the compilation "name" field. If the name field is not provided, the filename is set to "Untitled Grid"
	Display the compilation JSON document in an editor, allowing the overall compilation settings to be changed. The document `widgets` array contains the definition of all the widgets in the compilation. The editor toolbar provides access to the Compilation Snapshot Manager. NOTE: The buttons described so far will be omitted from the UI if the `showDevTools` compilation option is set to false in the JSON or the compilation is loaded from the
	Toggle between light and dark display themes. The selected setting is persisted as a user preference in local browser storage, causing WebStudio to load using the last active theme. The theme can however be explicitly overridden with url or compilation options
	Sign out from the Core server

Widget Templates Btn

Show the Widgets template dialog used to insert widgets into the compilation

Load Compilation Btn

Load a previously saved compilation JSON file from disk.

Save Compilation Btn

Save the current compilation to disk. The file name is based on the compilation "name" field. If the name field is not provided, the filename is set to "Untitled Grid"

Edit Compilation Btn

Display the compilation JSON document in an editor, allowing the overall compilation settings to be changed. The document widgets array contains the definition of all the widgets in the compilation.

The editor toolbar provides access to the Compilation Snapshot Manager.

NOTE: The buttons described so far will be omitted from the UI if the showDevTools compilation option is set to false in the JSON or the compilation is loaded from the

Toggle theme Btn

Toggle between light and dark display themes. The selected setting is persisted as a user preference in local browser storage, causing WebStudio to load using the last active theme. The theme can however be explicitly overridden with url or compilation options

Sign out btn

Sign out from the Core server

Clicking on the connection status ( connected status ) brings up a dedicates dialog showing more information about the connection. At the bottom of the panel there are three buttons which link to:

The subscription monitor, showing a list of all the widgets in the current compilation that hold tag subscription.
The list of third party libraries used by WebStudio
The browser console log

To begin adding widgets to the workspace, click on the "+" icon. This will open a Model Editor with a series of pre-configured widget template to choose from (using the WebStudio Demo Data Items).

Icon	Function
	Apply model changes made in the editor to the current in memory compilation and close the editor dialog. Note: This action does not save changes to persistent storage. If you reload the page for any reason, all in-memory state will be lost! It is therefore advised that while you are developing your compilation you export it at regular intervals, by pressing the icon at the top of the workspace.
	Format the JSON to align brackets and indent sub-elements.

Icon

Function

Apply changes

Apply model changes made in the editor to the current in memory compilation and close the editor dialog. Note: This action does not save changes to persistent storage. If you reload the page for any reason, all in-memory state will be lost! It is therefore advised that while you are developing your compilation you export it at regular intervals, by pressing the Export icon at the top of the workspace.

JSON Format

Format the JSON to align brackets and indent sub-elements.

The templates can be selected from the left hand pane and this will load the configuration into the Model Editor. Each widget configuration is entirely encapsulated in a JSON document as shown in the example above. The JSON can be edited to change the configuration. In this case the "path" field of the widget pens object was set to points directly at objects in the I/O Model of the system.

Add the widget to the compilation by clicking the [Apply]

The widget can be moved to any location in the workspace and resized using the "corner" icon in the bottom right-hand corner of the widget.

To make further configuration changes click on the {} icon in the widgets own title-bar. Note that the same config can be found in the JSON for the compilation as a whole, contained within its widgets array.

The following additional tools are available in the widget editor when loaded from a existing instance:

Icon	Function
	Compare the current configuration to the "Work model". More about this when we get to "Debugging"
	Delete this widget from the compilation

Icon

Function

Compare Work Model

Compare the current configuration to the "Work model". More about this when we get to "Debugging"

Delete widget

Delete this widget from the compilation

To learn more about how to create compilations refer top the getting started pages.

Compilation Snapshot manager

Webstudio can can be configured to automatically save snapshots of the compilation being edited, allowing documents to be recovered if you accidentally navigate away from the current content.

When activated, a copy of the compilation JSON is stored in the browser’s local storage indexedDB whenever the initial model content is changed. This happens when the compilation model is edited directly or when a widget is added, edited, deleted, moved or resized interactively by the user.

To get to the snapshot manager, click on the {} icon in the main toolbar to loads the top level compilation editor. From here the manager dialog is loaded using the provided tool button.

Snapshot Manager Icon

The manager dialog shows a table of all the available snapshots on disk.

Snapshots are associated with the current browser session. This means that they are only accessible from within the current browser tab or tabs spawned from the current one.

Snapshot manager dialog

The behavior of the top and bottom toolbar buttons is as follows:

Icon Function

Filter

Shows/Hides the filter bar from which filter conditions can be entered.

Shows/hides the search input box. All rows which have a field containing the search string are shown.

Compare

Compare the models of two selected (checked) items in the table

Snapshot Settings

Shows the snapshot settings dialog.

Snapshot settings

Snapshot enabled: When un-checked, no snapshots will be taken.
Snapshot limit: Store this many snapshot before the oldest ones get overwritten
Snapshot Max Age: Time relative expression determining how long the snapshot is kept before being deleted.
Layout change time out in milliseconds: This is the amount of time WebStudio waits to take a snapshot after the position or size of a widget was changed by dragging the caption bar or resize handle. This ensures that no unnecessary snapshots are saved while the move or resize action is taking place.

Restore last snapshot on load: When checked, the last saved snapshot is automatically loaded when the page is refreshed or WebStudio is loaded in the current browser tab.

There is an exception to this behavior which occurs when the URL parameter name=new (see Index Page) is used. In this case refreshing the page will not reload the last snapshot. A blank compilation will be shown instead. The last snapshot can however still be restored manually from the Snapshot Manager.

Clear on export: Clears all snapshot when the current model is saved (using on the main toolbar)
Create snapshot on import: Immediately create a snapshot when a compilation is loaded from disk (using on the main toolbar)
Clear snapshots: Delete all snapshots when the settings dialog is closed. Also resets the checkbox.

Waste Bin

Delete the selected snapshots.

Save

Replace the current model with the selected snapshot and close the dialog and compilation editor.

Edit

Load the selected snapshot into the compilation editor, but don’t save it yet.

Index Page

WebStudio will load an index page, rather than a blank model, when connecting to a system which contains a folder object called "WebStudio" under the core node. The current user must have EXECUTE permissions on the "WebStudio" object for this to work.

default index

When loading WebStudio with the index page enabled, the developer tools will be hidden by default. They can be re-enabled by adding the dev=1 parameter to the base URL. (See Loading Webstudio for an explanation of all the available query parameters)

    http://<hostname_webapi>:<port>/apps/webstudio/?dev=1

If a System Health Monitor has been configured, an additional link to will automatically appear in the table to load the built-in compilations used to inspect system performance counters. Note that the current logged in user needs to have READ permissions on the health monitor object for the option to be presented.

When any of the available options on the page are selected, the associated compilation is loaded into the current view area. The browser tab URL will also be updated to reflect the source. This allows users to navigate back to the index page using the browser navigation buttons.

New Compilation

The first option on the index page is used to start a new blank compilation. Note that the the url now contains an extra query parameter:

    http://<hostname_webapi>:<port>/apps/webstudio/?dev=1&name=new

This URL can be used to directly load a blank compilation, rather than going via the index page.

User defined index links

In addition to the built-in views, user defined ones can also be exposed on the index page. This is achieved by adding a script library called webstudio-index to the WebStudio folder object under the core.

The lua script body should return a function which will be invoked when the index page is loaded in WebStudio. The last parameter passed to the function is the "index" compilation JSON. It can be modified to add additional link items into the table widget. The function must return a valid compilation model. This can be either the modified one or an entirely new one.

Consider the example below, which adds a new "Hello world" link to the index.

Start by creating a simple compilation to load from the index page.

{
    "version": "1",
    "widgets": [
        {
            "type": "text",
            "text": "Hello World",
            "captionBar": false,
            "layout": { "x": 32,"y": 2,"w": 21,"h": 6,"static": true},
            "id": "txt1"
        }
    ],
    "options": {
        "stacking": "none",
        "numberOfColumns": 96
    }
}

Using DataStudio, create a new folder object in the system, say under the "WebStudio" node and call it "Hello World Compilation Holder".
Select the new folder in the tree and in the property panel add a custom property called hello-compilation. (The name is not significant other than that it allows us to refer to the value in the script below).
Then click the property value field and press Shift-F2 to bring up the field editor dialog. Click the Edit button and paste in the compilation JSON above. Remember to apply the changes on the folder’s property panel

We are finally ready to implement the webstudio-index function on the "WebStudio" folder object.

return function(arg, req, hlp, comp)
    -- get a reference to the first widget in the compilation,
    -- which is the table containing the index entries
    local tableWidget = comp.widgets[1]

    -- Make sure we have the widget we expect in hand. It should be a table widget
    -- with id = "navigationTable"
    if not ( tableWidget.type == "table" and tableWidget.id == "navigationTable" ) then
        -- It is not... Just return the compilation unchanged for now...
        return comp
    end

    local title = "Hello World"

    table.insert(tableWidget.data, {
        title = title,
        icon = "∞",

        -- Load the compilation from a named field on an object
        subType = 'object-name',

        -- Path to the object to load the compilation from
        objspec = '/System/Core/WebStudio/Hello World Compilation Holder',

        -- Optionally set the context path (See Note in the
        -- "Automatic post processing" section below for more information)
        ctx = '/System/Core/WebStudio/Hello World Compilation Holder',

        -- Property containing the compilation JSON
        name = 'hello-compilation'
    })
    return comp
end

Apart from the title and icon fields, the parameters added to the tableWidget.data correspond to those of the Load-Compilation action. Inspection of the index compilation reveals that it is precisely this action that gets invoked when an item is clicked, passing the configured table row data via the message.payload to the action. The mechanics of this process are explained here.

This means that in addition to loading a static compilation from a property field as shown above, index entries can also be configured to invoke an advanced endpoint to retrieve a dynamically generated compilation

In the example presented, the "Hello World Compilation Holder" was configured to contain a single compilation in the custom property field we added. More compilations can be added to the same object by configuring additional custom properties. In other words, each folder object can be used to hold multiple compilations.

Automatic post processing

The mechanism described above to manipulate the index page before it is returned to WebStudio can be used with our own compilations to execute post-processing logic on them. Refer to the load-compilation action documentation for more details