1 Overview
2 Universal Extension Task Overview
3 Implementation
- 3.1 Agent Start-up
  - 3.1.1 Python Discovery
  - 3.1.2 Extension Repository Initialization
- 3.2 Agent Registration
  - 3.2.1 Universal Extension Deployment
4 Extension Manager
- 4.1 Extension Worker Process
  - 4.1.1 Security Context
- 4.2 Starting an Extension instance
- 4.3 Worker Process Management
- 4.4 Warm Start Processing
5 UniversalExtension Base Class Package
- 5.1 UniversalExtension Interface
  - 5.1.1 def extension_start(self, state)
- 5.2 Communication Methods
  - 5.2.1 def update_extension_status(fields):
  - 5.2.2 def publish_extension_event(event_state):
- 5.3 Universal Extension Definition (module)
  - 5.3.1 Primary Operation
  - 5.3.2 Secondary Operation - Dynamic Commands
  - 5.3.3 Sample Dynamic Command Return Value
  - 5.3.4 Dynamic Command Use Cases
  - 5.3.5 Dynamic Choice Field Commands
  - 5.3.6 Sample Dynamic Choice Commands
  - 5.3.7 Dynamic Choice Field Use cases
6 Extension Repository
- - 6.1.1 Windows
  - 6.1.2 *nix
- 6.2 Extension Repository Security
  - 6.2.1 Checksums

Overview

A new dynamic "extension" subsystem in the Universal Automation Center (UAC) platform allows developers to implement custom solutions that can integrated into UAC. These “solutions” could be, for example, a task, trigger, or monitor.

The initial phase of this subsystem focuses on tasks.

This feature provides an easy way for Stonebranch, customers, and/or third party developers with special domain knowledge, to develop new solutions that can be seamlessly integrated into the UAC software stack. This is especially beneficial when the Domain knowledge required for a solution does not exist within the Stonebranch development teams and/or justification does not exist to devote the necessary resources.

While the Universal Task addresses this issue to some extent, it does not provide the level of integration and customer experience that can be achieved with the Universal Extension concept.

The main differentiators between Universal Extensions and Universal Tasks are:

Bidirectional communication between the Extension instance and the Universal Controller. This allows an Extension instance running on an Agent system to dynamically update the associated instance running in the Controller as the state changes. For example, a “Task” type extension could update output fields on a task instance in the Controller (for example, Job ID, Run Status, Distribution Status, and Percentage Complete).
Dynamic command definitions to support a complete solution (not just a single script execution). This allows an Extension solution to do things such as:
- Provide commands that can help populate task definition form fields (such as is currently done with the PeopleSoft task type),
- Provide a relative set of commands to be used on a task instance form that can be used to perform actions related to the unit of work that is specific to that task instance (such as is currently done with the SAP task type: Abort SAP job, Interrupt SAP Process Chain, etc.).
Dynamic event definition/generation (Universal Events) allow Extension instances to trigger actions in the Controller. Universal Events defined and monitored in the Controller could be raised by an Extension instance on an Agent.

Note

Universal Extension is not intended to replace Universal Task. Universal Task will remain a flexible, and perhaps more accessible, solution for many automation needs.

Universal Agent has been enhanced to support this new Universal Extension subsystem. The Extension subsystem allows various types of functionality to be developed and integrated into the UAC software stack (for example: tasks, triggers, and monitors).

The generic Extension concept supports the development of some primary operation (for example, task, along with an optional set of related secondary/supporting operations (Choice Commands, Dynamic Commands).

The initial phase (and this document) focuses on a “Task” type Extension. However, the architecture is designed with other extension types in mind.

As illustrated in the diagram above:

Developer creates Extension implementation and zips up the Extension Template, the Python Extension module and any dependent non-standard Python import modules.
The zipped package is uploaded to the marketplace.
A user downloads the extension to the Universal Controller.
The Universal Controller deploys the Extension to an Agent.
The Agent persists the Extension to the file system in the Extension Repository. (after authenticating the deployment with the Controller supplied SHA-256 checksum.
The Agent starts a Worker process to execute an Extension instance (supporting bi-directional communication).
The Agent authenticates the Extension that is to be run (comparing its SHA-256 checksum with the Controllers reported checksum) and inserts a driver script into the Worker process starts the Extension instance.

Universal Extension Task Overview

A Universal Extension Task is comprised of the following:

An Extension Task Template definition (defined in the Controller)
- Input field definitions
- Output-only field definitions
- Custom command definitions
An Extension module developed in Python (delivered/stored to the Agent system for execution)
- Contains the code that provides the functionality for the Extension’s primary operation (e.g. task)
- Contains code that provides the functionality for the Extension’s “Dynamic Commands”

Extension modules will be developed in an unspecified development environment.

Fully developed Universal Extensions are distributable (via the Stonebranch Marketplace, in-house Controller-to-Controller bundle promotion, etc.) to target Controller systems.

In a UAC deployment, the Controller serves as the primary repository and distributor of Universal Extensions. The Controller is responsible for pushing extension modules down to Agents as needed.

The deployment of Extension modules from Controller to Agent takes place via OMS messaging.

Note

For phase one of the Universal Extension platform, the deployment of Extension modules to Agent systems will be a manual process.

On the Agent side, Extension modules are stored in a cache repository (referred to as the Extension Repository throughout this document). This cache repository is simply be a directory on the Agent file system where Extensions modules passed from the Controller are stored. Extension modules are stored on the Agent file system as zipimport files (Python import modules stored as Zip archives).

For Windows systems (System Mode install), the Extension Repository is under: \Program Files\Universal\universal\UAGSrv\extensions
For *nix systems (System Mode install), the Extension Repository is under: ./var/opt/universal/uag/extensions
User mode installs use an equivalent path, for the “extension” directories above (for example, under uag in the “unvdata” install path).

The Universal Agent processes Extension tasks in much the same way as any other task type. A unit of work is executed on behalf of a Controller request. Artifacts of the unit of work are returned to the Controller (for example: standard output, standard error, return codes).

Standard output generated from the Extension task instances is directed to *_stdout files in the UAG cache directory.
Standard error generated from the Extension task instances is directed to *_stderr files in the UAG cache directory.

At a high level, the main difference between an Extension task and a Windows or Unix task is that the Agent is managing (or caching) a repository of modules that contain the functionality for the various “Extension” implementations.

Implementation

UAG has been enhanced in the following ways to support the new Extension subsystem:

Agent start-up
Agent registration
Extension Task-related messages
Extension Manager component
UniversalExtension Python Base Class
Extension Repository