Panel | ||||
---|---|---|---|---|
|
Introduction
To demonstrate the process of Extension development, a sample Extension will be created and deployed using Visual Studio Code with the UIP Visual Studio Code Extension. The UIP Visual Studio Code Extension relies heavily on functionality provided by the uip-cli
tool to enhance the UIP development experience. Therefore, a similar experience can be achieved with other code editors using uip-cli manually. This alternative use scenario will be documented as well.
...
Note that it is assumed the UIP Visual Studio Code Extension (or uip-cli
) is already installed. See the previous document for installation instructions.
Step 1 - Create a New Extension Project using the UIP VS Code Extension
As mentioned in Development Environment Set-Up, this tutorial will be using Visual Studio Code running in Windows and connected to a WSL (Windows Subsystem for Linux) project environment.
...
To begin, create a project directory (for example, ~/dev/extensions/sample-task) in the WSL file system where the Universal Extension will be created.
Select project folder
Next, Use Visual Studio Code to open the sample-task folder in WSL:
...
Note that, this dialog can be used to navigate to another folder. This is useful if you start the UIP: Initialize New Project process when VS Code is opened on a folder other than the target of initialization.
Selecting a starter template
After selecting "OK", the UIP project initialization process starts on the selected folder and you are presented with a list of available "starter templates" for the UIP project. Starter templates contain boiler plate code to kick-start a project. At the time of this writing, two starter templates are available: ue-task and ue-publisher. For now, we will be working with ue-task (ue-publisher will be demoed later in the tutorial series), so go ahead and click on the ue-task template.
Setting template parameter values for selected starter template
Starter templates contain parameters that allow you to supply project specific values into boilerplate template code at creation time.
...
Expand | ||
---|---|---|
| ||
Step 1 supplemental - Create a New Extension Project using the CLICreate a project directory (for example, ~/dev/extensions/sample-task) where the sample-task Extension will be created, and cd into the directory. Both the starter Extensions above can be configured before they are initialized. Shown below are the list of variables for the ue-task starter template: As shown in the image above, there are quite a few ways to configure the Extension. As for the sample Extension developed for this tutorial, we will work with ue-task, and only the owner_name option will be configured. Everything else will be set to the default value.
Pick one of the three ways shown above; it does not matter which one. Note that an optional, positional argument can be provided at the end of each of the three commands that specifies the directory in which the Extension will be initialized to. If the directory does not exist, the CLI will create it. To verify that the Extension was configured as intended, open the extension.yml file (see directory structure below), and ensure the owner_name is SampleOwner. This is the directory structure of the sample-1 Extension:
|
Step 2 - Deploy the Initial Extension using the UIP VS Code Extension
Before deploying the Extension, let's take a look at the code to get a sense of the expected output. Open the ~/dev/extensions/sample-task/src/extension.py in VS Code (It should already be open in the editor following the project initialization):
...
To connect to the Controller, the CLI needs the Controller's URL along with userid and password. To avoid typing the same information multiple times, the URL and userid can be stored in the local configuration file (~/dev/extensions/sample-task/.uip/config/uip.yml), and the password can be stored as an environment variable. Alternatively, all values can be set as environment variables and, using the UIP VS Code Extension, those values can be persisted with the project and reloaded as needed.
Set Project specific Environment Variables
Open the VS Code command pallet (ctrl+shift+p) and type "uip set". This will show a list of UIP commands for setting environment variables:
...
Expand | ||
---|---|---|
| ||
Step 2 Supplemental - Deploy the Initial Extension using the CLITo connect to the Controller, the CLI needs the Controller's URL along with userid and password. To avoid typing the same information multiple times, the URL and userid will be stored in the local configuration file, and the password will be stored as an environment variable.
|
Step 3 - Create and launch a new 'ue-task-test' task
We are now ready to create a new task to test the initial ue-task Extension. In order to make the new UE Task task type available in the Integrations section of the Controller’s Services menu, we must first refresh the Navigation Tree.
...
Expand | ||
---|---|---|
| ||
Step 3 Supplemental - Create and launch a new 'ue-task-test' taskThe task creation process is exactly the same as above. As for launching the task, run the command shown in the GIF animation above. |
Step 4 - Modify the Extension and Deploy using the UIP VS Code Extension
So far, we have pushed the initial Extension, created a task for it, and tested the Extension code. Now, the extension.py file will be slightly modified to demonstrate the process of deploying a modified Extension using the UIP VS Code Extension.
...
Notice that this time, the STDERR output is empty and STDOUT output is not. This is expected since we changed the value of the "Action" field in the task form.
Step 5 - Reset the Extension Changes
The For-Loop changes that prints out the 'Hello' message multiple times were added to demonstrate the process of modifying and deploying the Extension. The next few tutorials assume that the For-Loop changes aren't in extension.py, so either undo the For-Loop changes or copy the code shown below to extension.py before moving on to the next guide:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
from __future__ import (print_function) from universal_extension import UniversalExtension from universal_extension import ExtensionResult from universal_extension import logger class Extension(UniversalExtension): """Required class that serves as the entry point for the extension """ def __init__(self): """Initializes an instance of the 'Extension' class """ # Call the base class initializer super(Extension, self).__init__() def extension_start(self, fields): """Required method that serves as the starting point for work performed for a task instance. Parameters ---------- fields : dict populated with field values from the associated task instance launched in the Controller Returns ------- ExtensionResult once the work is done, an instance of ExtensionResult must be returned. See the documentation for a full list of parameters that can be passed to the ExtensionResult class constructor """ # Get the value of the 'action' field action = fields.get('action', [""])[0] if action.lower() == 'print': # Print to standard output... print("Hello STDOUT!") else: # Log to standard error... logger.info('Hello STDERR!') # Return the result with a payload containing a Hello message... return ExtensionResult( unv_output='Hello Extension!' ) |