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 integration SDK, you can run tasks as containers using any language or third-party libraries.

important

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

Installation

The Digital.ai Release Python SDK is available in the PyPI repository.

Template Project

The Digital.ai Release Integration Python SDK template project serves as a template for developing a Python-based container plugin.

Core Concepts

Here is an overview of some of the core concepts of the Python SDK.

The BaseTask Class

The BaseTask is an abstract class in the SDK that acts as a blueprint for defining tasks. To create a custom task:

1. Create a new class that extends the BaseTask abstract class
2. Implement the required execute() method
3. Define your task logic within the execute() method

Task Execution Flow

The SDK executes tasks through the following process:

1. The execute_task() method in BaseTask initiates the execution
2. Your implemented execute() method runs the task logic
3. The SDK handles any exceptions that occur during execution
4. Task results are processed through output properties and status codes

For a practical example, see our tutorial which demonstrates a simple Hello class implementation.

Core Features

Here is the list of features supported by the Python SDK.

Task Management

• Exit code and error handling via set_exit_code() and set_error_message()
• Task abortion support through the abort() method
• Status updates using set_status_line()

Data Handling

• Input property access via self.input_properties
• Output property management using set_output_property()
• Comment addition through add_comment()

Context Access

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

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.

Release API Client

The ReleaseAPIClient is a client class introduced in digitalai-release-sdk version 25.1.0. It provides an interface to interact with the Digital.ai Release server using REST API calls. The class is a wrapper around the requests library, allowing users to customize configurations such as timeouts and retries in the same way as requests.

Additionally, the BaseTask class provides the get_release_api_client() method, which returns a pre-configured ReleaseAPIClient instance with the Release server URL and authentication credentials set up automatically.

Usage Example with BaseTask

Below is an example of how to use ReleaseAPIClient within a BaseTask class.

from digitalai.release.integration import BaseTask

class ReleaseAPIExample(BaseTask):
    """
    Example usage of ReleaseAPIClient.
    
    Preconditions:
    - The 'Run as user' property must be set on the release.
    - The executing user must have valid credentials.
    """

    def execute(self) -> None:
        # Obtain an instance of the Release API client
        release_api_client = self.get_release_api_client()

        # Step 1: Create a new global variable
        global_variable = {
            "id": None,
            "key": "global.newVar",
            "type": "xlrelease.StringVariable",
            "requiresValue": "false",
            "showOnReleaseStart": "false",
            "value": "new value"
        }
        response = release_api_client.post("/api/v1/config/Configuration/variables/global", json=global_variable)
        global_variable_id = response.json()["id"]
        print(f"Global variable created with ID: {global_variable_id}")

        # Step 2: Update the global variable
        update_global_variable = response.json()
        update_global_variable["value"] = "updated value"
        response = release_api_client.put(f"/api/v1/config/{global_variable_id}", json=update_global_variable)
        print("Global variable updated:", response.json())

        # Step 3: Retrieve the updated global variable
        response = release_api_client.get(f"/api/v1/config/{global_variable_id}")
        print("Retrieved global variable:", response.json())

        # Step 4: Delete the global variable
        response = release_api_client.delete(f"/api/v1/config/{global_variable_id}")
        print(f"Global variable deleted successfully. Status code: {response.status_code}")

        # Close the Release API client
        release_api_client.close()