Digital.ai Release Integration Python SDK Overview

The Digital.ai Release Integration Python SDK is a set of tools that developers can use to build container-based plugins. With this SDK, you can develop custom tasks in Python 3 that run as containers.

important

The container-based task functionality is not compatible with DB2.

Getting started

The Digital.ai Release Integration Python SDK template is a project on GitHub that serves as a starting point for developing a Python-based container plugins.

To develop a new integration, create a duplicate of the template project.

For a practical example, see Build Custom Container Plugin using Python SDK. This tutorial walks you through the steps to create a simple "Hello World" plugin.

Core Concepts

The SDK consists of various parts that work together to provide a complete solution for building container-based plugins.

Development Environment

The SDK comes with a pre-configured development environment that runs on Docker.

In the template project, this environment can be found in the dev-environment directory.

The development environment contains a fully functional version of Digital.ai Release with a limited license. Use this environment to test your plugin.

Plugin definition and other resources

The plugin definition is a YAML file that describes the plugin's properties, including its name, version, and input/output properties.

It can be found in resources/type-definitions.yaml. This is the part of the plugin that needs to be installed in the Digital.ai Release server. It can refer to other assets like plugin icons that can be packaged into the plugin archive.

Source code

The source code for the plugin is located in the src directory. This is where you will implement the logic of your plugin using Python.

Tests

The template project includes a test suite that uses the unittest framework. The tests are located in the tests directory. You can run the tests using the pytest command. The test suite includes unit tests for the plugin's functionality and integration tests that verify the plugin's behavior. Note that these tests do not run inside Digital.ai Release -- they test the plugin before it is deployed.

Plugin container

The Python code to implement the plugin will be packaged into a container image. The container image will be uploaded to a container registry, such as Docker Hub or a private registry. You can configure the container registry in your project.

For development purposes, the template project uses a local Docker registry.

Build scripts

The template project includes build scripts for unix and Windows that will

• Build the plugin zip file to be installed into Digital.ai Release
• Build the container image
• Upload the plugin zip into Digital.ai Release
• Upload the container image to a container registry

Coding with the Python SDK

The template project includes a src directory with a sample task implementation. Use this as a starting point to write your Python code to implement the plugin's functionality.

The BaseTask Class

The main entry point is the BaseTask class,. This class provides methods and properties that you can use to interact with Digital.ai Release.

To create a custom task implementation, you need to create a new class that extends the BaseTask class and has the same name as the task type definition in type-definitions.yaml. This class will contain the logic for your task. All you need to do is implement the execute() method, which is where you will write the code that performs the task's functionality.

Task Execution

When the task starts in Digital.ai Release, BaseTask initiates the execution by calling the execute() method of your custom task class.

Follow this general pattern to implement your task:

1. Access and validate input properties
2. Perform the logic, for example by calling an external API or executing a script.
3. While doing so, provide feedback to the Release UI with status line, comments and logs
4. The SDK handles any exceptions that occur during execution
5. Task results are processed by setting output properties and status codes

Input and Output properties

• Input property access via self.input_properties
• Output property management using set_output_property()

Feedback to the UI

There are several ways to provide feedback to the user interface during task execution:

• Status line updates through set_status_line()
• Comment addition through add_comment()
• Logging by using 'print() statements or log.debug()

Digital.ai Release

The BaseTask class provides methods to interact with Digital.ai Release, including:

• Release server URL retrieval
• Task user context information
• Release and Task ID access
• API client integration via ReleaseAPIClient

API Reference - Methods and Attributes

The BaseTask abstract class contains the following methods and attributes:

Method	Type	Description
execute(self)	None	It is an abstract method that must be implemented by the subclasses of BaseTask, and it represents the main logic of the task.
abort(self)	None	Sets the task's exit code to 1 and exits the program with a status code of 1.
set_exit_code(self, value)	None	Sets the exit code of the task's OutputContext object.
set_error_message(self, value)	None	Sets the error message of the task's OutputContext object.
get_output_context(self)	OutputContext	Returns the OutputContext object associated with the task.
get_output_properties(self)	Dict [String, Any]	Returns the output properties of the task.
get_input_properties(self)	Dict [String, Any]	Returns the input properties of the task.
add_comment(self, comment: str)	None	Adds a comment to the task that will be visible in the UI.
set_status_line(self, status_line: str)	None	Set the status line of the task. This shows live updates on the UI.
add_reporting_record(self, reporting_record: Any)	None	Adds a reporting record to the OutputContext. The reporting records are used in the Audit Report.
set_output_property(self, name: str, value: Any)	None	Sets the name and value of an output property of the task.
get_release_server_url(self)	String	Returns the Release server URL of the associated task.
get_task_user(self)	AutomatedTaskAsUserContext	Returns the details of the user who executes the task.
get_release_api_client(self)	ReleaseAPIClient	Returns a ReleaseAPIClient object with default configuration based on the task.
get_release_id(self)	String	Returns the Release ID of the task.
get_task_id(self)	String	Returns the Task ID of the task.
input_properties	Dict [String, Any]	It is the instance variable that contains the input properties for this task.