Universal Extension 1.0.0 API
UniversalExtension class
Base class for Stonebranch Universal Extension module implementations
Methods
extension_start(fields)
This method must be overridden by the custom Extension class that derives from the UniversalExtension class. It is called by UniversalExtension base class in response to a JSS-LAUNCH message sent from the Controller.
This is essentially the main() function for an Extension implementation and is the starting point for work that will be performed. The fields parameter passes in a dictionary of Extension instance fields that were defined in the Extension template.
| Input | Parameters:
|
| Output | ExtensionResult |
update_extension_status(fields)
This method can be called at any time by the Extension instance. It is used to propagate state changes back to the associated extension instance in the Controller. Essentially, any/all output fields defined in the associated Extension Template can be updated using this method.
This method results in an ESS-STATUS-UPDATE message being sent from the Worker process to the UAG Extension Manager, followed by a JSS-STATUS(JOB UPDATE) message being sent from UAG Extension Manager to the Controller (via OMS server).
| Input | Parameters:
|
| Output | None |
ExtensionResult class
class ExtensionResult(**kwargs)
The constructor for the ExtensionResult class takes different forms depending on the context. See the notes below.
Extension Start
The form of the ExtensionResult constructor when instantiated in the context of Extension Start, is as follows:
ExtensionResult(rc=0, message='', output_fields=None, unv_output=None, **kwargs)
| Parameter | Type | Default | Description |
| rc | int, optional | 0 | This parameter represents the return code of the task instance that initiated the extension_start operation. The value returned is implementation-defined and therefore left up to the Extension developer. The value can be used by the “return code processing” of the task instance in the Controller to determine if the Extension task instance is perceived as completing with Success or Failed. |
| message | str, optional | Empty string | This parameter specifies a short status string (error message or success message) to be sent to the “Status Description” field on the task instance form. |
| output_fields | dict, optional | None | Dictionary containing output fields. The parameter is a dictionary of output fields to be sent back to the controller for the associated Extension instance. Field names are implementation dependent and correlate with the Universal Template field names in the Controller's Template definition. |
| unv_output | str, optional | None | This parameter specifies the data that will be returned to the Controller for the command execution. It is interpreted as a UTF-8 encoded text object. If the output parameter is True, the output_data will be persisted in the Controller as a record under table ops_exec_output, and appearing as Universal Command output type from the task instance Output tab. |
Choice Command
The form of the ExtensionResult constructor when instantiated in the context of Choice Command, is as follows:
ExtensionResult(rc=0, message='', values=None, **kwargs)
| Parameter | Type | Default | Description |
| rc | int, optional | 0 | This parameter represents the return code of the ‘choice’ operation and determines whether the command is perceived as completing with success or failure by the Controller. A value of 0 indicates success. All other values indicate an error condition and will be ignored by the Controller for form field population. However, the Controller will log the command response. The non-zero value used to represent the error condition is implementation defined and therefore left up to the extension developer. |
| message | str, optional | Empty string | This parameter allows the extension to pass a completion message back to the Controller. The message will be logged by the Controller. |
| values | list, optional | Empty List | This parameter specifies a list of string values to be returned to the Controller and used to populate the associated dynamic choice field on the Extension task form. |
Dynamic Command
The form of the ExtensionResult constructor when instantiated in the context of Dynamic Command, is as follows:
ExtensionResult(rc=0, message='', output=False, output_data=None, output_name=None, **kwargs)
| Parameter | Type | Default | Description |
| rc | int, optional | 0 | This parameter represents the return code of the Dynamic Command operation and determines whether the command is perceived as completing with success or failure by the Controller. A value of 0 indicates success. All other values indicate an error condition and the command result will not be added to the Controller's Output tab. However, the Controller will log the command response. The non-zero value used to represent the error condition is implementation defined and therefore left up to the extension developer. |
| message | str, optional | Empty string | The message parameter specifies a short status string (error message or success message) that will be logged by the Controller. |
output | bool, optional | False | This parameter is a Boolean value that specifies if the command produced output that should be persisted and displayed under the task instance Output tab in the Controller task instance associated with the dynamic command invocation. The default value is False. This flag allows distinguishing between a command that does not produce output and a command that produces output but the output returned was empty. |
output_data | str, optional | None | This parameter specifies the data that will be returned to the Controller for the command execution. It is interpreted as a UTF-8 encoded text object. If the output attribute is True, the output_data will be persisted in the Controller as a record under table ops_exec_output, and appearing as Universal Command output type from the task instance Output tab. The default value is None. |
output_name | str, optional | None | This parameter is used to provide a custom name for the associated output data. The output_name (if provided) will be used in the presentation of the output_data by the Controller. |
ExtensionLogger class
class ExtensionLogger(name)
Class for providing logging functionality for Universal Extensions. Do not instantiate this class directly. UniversalExtension instantiates this class via a call to the logging.getLogger API call.
Universal Extension Decorator
Methods
dynamic_choice_command(field_name)
Register a dynamic choice command.
| Input | Parameters:
|
| Output | ExtensionResult |
dynamic_command(command_name)
Register a dynamic command.
| Input | Parameters:
|
| Output | ExtensionResult |
Universal Extension 1.1.0 API
UniversalExtension class
Base class for Stonebranch Universal Extension module implementations
Methods
extension_cancel(self)
Implement in derived class.
extension_start(self, fields)
Implement in derived class.
update_extension_status(self, fields)
Propagate state changes back to the associated extension instance in the Controller.
- Can be called at any time by an Extension instance.
- Any/all output fields defined in the associated Extension Template can be updated using this method.
Parameters
fields : dict. The fields parameter expects a dictionary of output fields to be sent back to the controller for the associated Extension instance. Field names are implementation dependent and correlate with the Universal Template field names in the Controller's Template definition for the associated task.
Returns: None
Examples:
>>> my_ext = MyExt() # my_ext is an instance of a (derived) extension class called MyExt >>> fields = {"foo": "bar"} >>> my_ext.update_extension_status(fields)
ExtensionResult(**kwargs) class
Depending on the context of the initialization, different parameters need to be passed to the constructor. See the notes below.
Dynamic Command
The form of the ExtensionResult constructor when instantiated in the context of Dynamic Command, is as follows:
Constructor Signature
(rc = 0, message = '', output = False, output_data = None, output_name = None, call_frame = None, **kwargs)
| Parameter | Type | Default | Description |
| rc | int, optional | 0 | This parameter represents the return code of the Dynamic Command operation and determines whether the Extension task instance is perceived as completing as Success or Failed by the Controller. |
| message | str, optional | Empty string | This parameter allows the extension to pass a completion message back to the Controller. If rc is set to 0, the message will be considered informational and will be logged by the Controller. |
output | bool, optional | False | This parameter specifies if the command produced output that should be persisted and displayed under the task instance Output tab in the Controller task instance associated with the dynamic command invocation. |
output_data | str, optional | None | This parameter specifies the data that will be returned to the Controller for the command execution. It is interpreted as a UTF-8 encoded text object. If the output attribute is True, the output_data will be persisted in the Controller as a record under table ops_exec_output, and appearing as Universal Command output type from the task instance Output tab. |
output_name | str, optional | None | This attribute is used to provided a custom name for the associated output data. The output_name (if provided) will be used in the presentation of the output_data by the Controller. |
| call_frame | frame, optional | None | Frame of a function call where previous activity of interest occurred. |
Choice Command
The form of the ExtensionResult constructor when instantiated in the context of Choice Command, is as follows:
Constructor Signature
(rc = 0, message = '', values = None, call_frame = None, **kwargs)
| Parameter | Type | Default | Description |
| rc | int, optional | 0 | This parameter represents the return code of the 'choice' operation and determines whether the command is perceived as completing with success or failure by the Controller. A value of 0 indicates success. All other values indicate an error condition and will be ignored by the Controller for form field population. However, the Controller will log the commnd response. The non-zero value used to represent the error condition is implementation defined and therefore left up to the extension developer. |
| message | str, optional | Empty string | This parameter allows the extension to pass a completion message back to the Controller. The message will be logged by the Controller. |
| values | list, optional | Empty List | This parameter specifies a list of string values to be returned to the Controller and used to populate the associated dynamic choice field on the Extension task form. |
| call_frame | frame, optional | None | Frame of a function call where previous activity of interest occurred. |
Extension Start
The form of the ExtensionResult constructor when instantiated in the context of Extension Start, is as follows:
Constructor Signature
(rc = 0, message = '', output_fields = None, unv_output = None, call_frame = None, **kwargs)
| Parameter | Type | Default | Description |
| rc | int, optional | 0 | This parameter represents the return code of the extension_start operation. The associated Universal Task instance in the Controler can use this value to determine the completion status of the Extension instance. The value is implementation defined and therefore left up to the extension developer. |
| message | str, optional | Empty string | This parameter allows the extension to pass a completion message back to the Controller. If rc is set to 0, the message will be considered informational and will be logged by the Controller. |
| output_fields | dict, optional | None | Dictionary containing output fields. |
| unv_output | str, optional | None | The value for this parameter is considered the payload of the task execution. It appears on the task instance Output tab as Universal output type. |
| call_frame | frame, optional | None | Frame of a function call where previous activity of interest occurred. |
ExtensionLogger class
Class for providing logging functionality for Universal Extensions. Do not instantiate this class directly. UniversalExtension instantiates this class via a call to the logging.getLogger API call. See the example above for instructions on obtaining the logger instance.
The following log levels are officially supported:
- CRITICAL
- ERROR
- WARNING
- INFO
- DEBUG
In addition to the levels listed above, there is another level, TRACE, which is used by the Universal Extension internal API. It is NOT available for use in developing Extensions.
Logger: Global Variable
- global logger instance that can be imported in other modules.
- Example:
>>> # This example demonstrates how to import the global logger in other Python modules.
>>> # Assume that logger is imported below in test.py that resides in the same folder as extension.py
>>> from universal_extension import logger
>>> logger.info('sample info message from test.py')
>>> logger.warning('sample warning message from test.py')
>>> logger.critical('sample critical message from test.py')Universal Extension Decorator
dynamic_command(command_name)
Register a dynamic command.
| Input | Parameters:command_name : strthe command name |
| Output | None |
dynamic_choice_command(field_name)
Register a dynamic choice command.
| Input | Parameters: field_name : strthe field name |
| Output | None |