Workflows – Visual Studio Code extension

Introduction

Workflows provides a very intuitive graphical user interfaces, where users can create, update and execute workflows. This interface provides very broad details to help the user debugging failed executions, add clean-up policies, create Jinja templates, etc. For more details on Workflows framework capabilities, please read here.

However, users with a developer profile are used to interface with IDEs that facilitate code development and integration, and not to program their code via web browsers. Some situations, like connection issues/timeouts, undesired navigation or refresh of the development window can drive into lose code changes. The purpose of this Visual Studio Code extension for Workflows is to provide this type of users with a new interface to speed up their code design process/activities.

Installation

To install the visual studio code extension:

• Install directly from vsCode Marketplace

• If you wish to compile the project or modify the code, clone the project repository at Github.com
  • Clone the project.
  • Compile the project and Install the VSIX

npm install .
npm run compile
vsce package

As prerequisite, we support vsCode rel ^1.76.0.

Setup

After successfully installing the extension, you should see in you Explorer > Workspace a new folder called Workflow Manager, with actions and workflows subfolders.

For setting the extension, access vsCode Settings (workspace) > Extensions > WorkflowManager where you should see the following attributes to configure:

• Local Storage: When enabled, it automatically stores a copy of the uploaded workflow when saving changes.
• Local Storage: Folder Path to an existing folder where a copy of the saved workflows is stored (if the previous flag is enabled).
• Workflow Manager: Password : Password of your NSP system.
• Workflow Manager: Port : Port used by WFM.
• Workflow Manager: NSPIP address of your NSP system.
• Workflow Manager: User Username to access your NSP system.
• Workflow Manager: Timeout Connection timeout in seconds

After modifying these settings, vsCode requires to reload the window. The can be done either closing and reopening vsCode, or by opening the command palette and entering the Developer: Reload Window command

Main functionalities

List and visualize actions and workflows

With the installation and setup process successfully completed, the user should be able to access the Workflow Manager folder within the workspace. This folder contains three folders:

• actions: list of ad-hoc actions created in your NSP system.
• templates: list of jinja templates in your NSP system
• workflows: all workflow definitions in your NSP system

By opening any of the three, the extension dynamically loads the list of actions, templates or workflow definitions and let's you open any of them by simply clicking on the "file". Content is also dynamically loaded from the remote system.

Create, delete and rename workflows

vsCode allows users to create, rename and remove files for any local folder. Similarly, the vsCode extension allows the user to perform the very same operations within the Workflow Manager folder for actions, templates and workflows, these operations then being applied on the remote NSP Workflows system:

• Create: By clicking on the "New Folder..." button, the user can enter the name of a new workflow and click enter. This will create a new workflow in the system using a template that is defined within the extension. In addition to the workflow definition YAML, the workflow Input Form json and README files are also created. User should now be able to open and edit these files.
• Delete: Clicking on right button --> "Delete Permanently" allows the user to remove the workflow definition locally and in the remote system.
• Rename: rename allows to change the name of the workflow. By changing the workflow name, it also changed the name within the workflow definition for consistency. In addition, if a user opens a workflow definition, changes the name of the definition and saves, this will automatically create a copy of the original workflow using the new name and definition.

Edit and upload workflow changes

With a workflow/action opened in the editor, the user can modify the definition adding new tasks, changing input attributes, description, tags, etc.

All the changed content can be uploaded to the remote system by simply saving the definition. This will trigger several operations in the background to simplify the user experience, including: workflow validation against the remote server, set the workflow to draft, upload and set to published.

When the workflow has been modified locally, the user can select the Compare Changes icon from the top right corner of the editor. This will open a another frame showing the changes made compared to the saved version.

Validate your workflow definitions (local/server)

The extension includes two options for validating workflow definitions:

• Local validation via JSON Schema: When activating the extension, it automatically downloads the list of actions from Workflows and generates a JSON schema for YAML validation. For this local validation / suggest to work, the user must also install the RedHat YAML extension from vsCode marketplace. This local validation highlights invalid definition and attributes and provides suggests and autocomplete capabilities.
• Remote (sever) validation: This validation is the same as the one provided through WFM GUI. It validates a workflow definition (Mistral v2 DSL YAML).

Download your workflows locally

The extension allows a user to download workflow definitions (one, multiple, all) by right clicking on the file/folder name and selecting Download.

The user can select the destination folder where the definitions will be stored to create a backup copy or to work locally/offline.

Execute your workflows and view last result

Opening a workflow definition adds few command buttons at the top right corner of the editor. The first one (play button -> "Execute workflow") allows the user to execute the workflow in the remote system. If input attributes are required, the extension translates them into a JSON and asks the user to fill them before triggering the execution.

When sent, the extension gathers the extension ID, so users can directly access the execution site in Workflows GUI if they whish.

Additionally, the user can click the second command button (health button -> "Last Execution Result"). This will show very brief information on when the last execution was created and the status of this last execution as a system message. This provides two more options to proceed with the visualization:

• A link to Workflows GUI last execution result.
• Loading a webview within vsCode with few details for each task (see below).

Suggests and Snippets

When running the extension, it automatically creates two files for validation and suggests:

• JSON Schema: Used for local validation and to provide suggests while developing workflows.
• Snippets: User for suggests and autocomplete for Workflows actions. This file is created using the action's examples defined in Workflows.

By selecting some of the snippets suggests, the extension autocompletes an entire task definition for a given action to be used as an example.

Accessing Workflows: Embedded links

The vsCode extension for Workflows provides the right pointers to the Workflows GUI for the user to access the system whenever it is desired. Few examples:

Workflow or action definitions have the home button at the top, which drives the user to the definition in Workflows .

• When executing a workflow, the user can directly open the execution in Workflows to see more details.
• The extension allows to see in the editor few details of the last execution result and status. However, if more details are needed, the extension provides a list to the last execution for the user to review directly in Workflows GUI.
• For running actions (potentially waiting for user input), the webview also provides a link to the particular task execution to see more details.

Testing Jinja2 Templates

The vsCode extension allows Jinja2 template to be tested within the extension.

Selecting the play icon allows the user to enter the context for the template and the rendered result will be displayed.

schemaForm Generation

The vsCode extension allows input forms to be generated for the workflow

Selecting the Generate Form icon will create a schemaForm json body from the workflow inputs.

Saving this file will upload the changes to Workflows .

Yaqalator

When a YAQL expression is highlighted in the extension, "Run Yaqalator" can be select from the contextual menu.

This allows the expression to be resolved against the entered context.

Working locally: what's there?

The extension provides a similar functionalities for users working on local definitions (stored as yaml files in their computers). Few considerations:

• Save: When saving a local definition, it simply saves in the user's computer. To enable the upload to the remote system, there is an additional command button for upload.
• Local validation: Local validation is not enabled for local files. If the user wants to enable the validation for a particular file, the extension includes a new command button called "Apply schema for validation".
• Working locally on your Workflows project and definitions gives the user access to other built-in functionalities and extensions provided by vsCode. The easiest and most relevant example is source control. By hosting and cloning workflow definitions in Git and including them in your workspace, vsCode will provide the Workflows extension capabilities described in this site together with source control functionalities (revert changes, code compare, commit, etc).

Download examples from GitHub.com/nokia

At the status bar, we included a cloud icon that allows to download the workflow examples from Nokia's official GitHub.

With the community, this site will get updated with new workflows, actions, templates, etc.

Potential improvements

This first version, although covers a wide set of functionalities for helping workflow developers, could potentially incorporate additional features. Some items that we already identified:

• Enhanced error control (provide more insights on issues with workflows and executions).
• Local files are always treated as workflows (we do not identify actions stored locally).
• In-line validation only works for workflows, not for actions (requires JSON schema for actions).
• File name ending. Workflows and actions downloaded from the system do not include ".yaml" at the end. Shall we integrate ".yaml" when downloading?
• Running ad-hoc actions (only viewing and editing).

Contact

For any suggestion, potential improvement or issue, please reach out to:

• Alejandro Aguado
• Sven Wisotzky