Prefect Cloud
Disclaimer
Your use of this download is governed by Stonebranch's Terms of Use.
Overview
Prefect is an open-source workflow management system designed to orchestrate data pipelines in Python. This integration provides the capability to trigger from UAC a Prefect Flow Run and monitor its execution providing useful metadata.
Key Features
Feature | Description |
---|---|
Launch Flow Runs | Launch Flow Runs on Prefect Cloud and monitor until the flow gets completed with success or failure. Flow Run metadata can be provided as part of Extension Output. |
Version Information
Template Name | Extension Name | Version | Status |
---|---|---|---|
Prefect | ue-prefect | 1.0.0 | Fixes and new Features are introduced. |
Refer to Changelog for version history information.
Software Requirements
This integration requires a Universal Agent and a Python runtime to execute the Universal Task.
Area | Details |
---|---|
Python Version | It requires Python 3.11. |
Universal Agent Compatibility |
|
Universal Controller Compatibility | Universal Controller Version >= 7.6.0.0. |
Network and Connectivity | Network connectivity towards Prefect Cloud is required. |
Prefect Cloud and Rest API versions | Compatible with Prefect Cloud version 2.18.1 with REST API version 0.8.4 . It should be compatible on later versions as long as backwards compatibility is guaranteed on the API level. |
Supported Actions
Action: Prefect Cloud - Launch Flow Run
This action allows to launch a Flow Run on Prefect Cloud. The task author has to provide the required Credentials, the Workspace ID and the Deployment ID that relates to the Flow and some additional parameters related to the flow execution (more information can be found on the Fields Description section). Task author can decide whether the task will just launch the flow, or in addition wait until a final success or failure state is reached. The last execution Flow Run metadata can be published as part of the Extension Output, while the Flow Run ID, the Flow Run Name and the Flow Run State can be visible directly as output fields during task instance execution.
Configuration examples
Simple Launch Flow Execution using Workspace ID or Name and Deployment ID or Name as dynamic choice fields to retrieve the necessary names from the Prefect Cloud Platform. | Simple Launch Flow Execution using Workspace ID or Name and Deployment ID or Name as IDs that can be copy pasted from Prefect Console. For example purposes, dummy IDs are used. |
Launch Flow by providing Flow Parameters and Tags. In this case it is assumed that the Flow expects a Boolean and an integer parameter. | Launch Flow and wait until the Flow ends in Success or in Failure. The latest Flow Run metadata is configured to be included as part of the Extension Output. |
Action Output
Output Type | Description | Examples |
---|---|---|
EXTENSION | The extension output provides the following information:
|
Input Fields
Name | Type | Description | Version Information |
---|---|---|---|
Action | Choice | The action performed upon the task execution.
| Introduced in 1.0.0 |
Credentials | Credential | Credentials for Prefect Cloud. The Credentials definition should be as follows.
| Introduced in 1.0.0 |
Workspace ID or Name | Dynamic Choice | Defines the Workspace for Flow Run execution. Task authors can use directly the Workspace ID by copy pasting it from Prefect UI, enter the name of the Workspace or use the Dynamic Choice functionality to list the available Workspaces names that are applicable under the specific Account. | Introduced in 1.0.0 |
Deployment ID or Name | Dynamic Choice | Defines the Deployment of Flow. Task authors can use directly the Deployment ID by copy pasting it from Prefect UI, enter the name of the Deployment or use the Dynamic Choice functionality to list the available Deployments. | Introduced in 1.0.0 |
Flow Run Name | Text | The name of the flow run. Defaults to a random slug if not specified. | Introduced in 1.0.0 |
Additional Optional Parameters | Checkbox | Used to show/hide additional optional parameters for the Flow Run. | Introduced in 1.0.0 |
Parameters (JSON) | Large Text | This is a JSON structure that provides additional optional parameters that can be passed. A default value is provided so users can easily edit the required parameters if required, and it is not intended to be used as-is. The default value provides the following elements. parameters: it is an object that represents the parameters of the Flow Run. As an object it can contain JSON elements of any type. context: it is an object that represents the context of the Flow Run. As an object it can contain JSON elements of any type. job_variables: it is an object that represents the job variables of the Flow Run. As an object it can contain JSON elements of any type. tags: it is a list of strings that represents a list of tags associated with this Flow Run. Available if “Additional Optional Parameters” is checked. | Introduced in 1.0.0 |
Wait for Success or Failure | Checkbox | If selected, the task will continue running until Job reaches the "COMPLETED" or "FAILED" state. "CRASHED", "CANCELLED" are also considered "FAILED" states. | Introduced in 1.0.0 |
Polling Interval (sec) | Integer | The polling interval in seconds for the Flow Run State check. Defaults to 60 seconds. Required when Wait for Success or Failure is checked. | Introduced in 1.0.0 |
Max Number of Polls | Integer | Maximum number of polls. Can be used to control the approximate expected duration of the Flow Run (in relation also to Polling Interval (sec)). If left empty the UAC Task will poll indefinitely checking whether the Flow Run is completed or resulted in failure. If the Maximum Number of Polls is reached the exit code of the task will be 40. Available if Wait for Success or Failure is checked. | Introduced in 1.0.0 |
Extension Output Options | Choice | User can decide the content of Extension Output using the following options.
| Introduced in 1.0.0 |
Output Fields
Field | Type | Description | Introduced in Version |
---|---|---|---|
Flow Run ID | Text | The Flow Run ID provided by Prefect. | 1.0.0 |
Flow Run Name | Text | The Flow Run Name. If input field Flow Run Name is not provided, then a random slug is generated by Prefect. | 1.0.0 |
Flow Run State | Text | The latest Flow Run execution state retrieved by Prefect. | 1.0.0 |
Cancelation and Rerun
In case of cancellation, the Flow Run is not canceled on Prefect. In case of Re-Run, the Flow Run will be re-executed from scratch.
Exit Codes
Code | Status | Status Description | Meaning |
---|---|---|---|
0 | Success | “Task executed successfully.“ | Successful Execution.
|
1 | Failure | “Execution Failed: <<Error Description>>” | Failed Execution.
|
20 | Failure | “Data Validation Error: <<Error Description>>“ | Input fields validation error. |
40 | Failure | “Polling Timeout: maximum polling timeout reached.“ | The Flow Run is executed out of the normal duration boundaries. |
STDOUT and STDERR
STDOUT is empty, while STDERR provides additional information to the user.
Backward compatibility is not guaranteed for the content of STDOUT/STDERR and can be changed in future versions without notice.
How To
Import Universal Template
To use the Universal Template, you first must perform the following steps.
This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow these instructions.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.
Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.
Configure Universal Task
For a new Universal Task, create a new task, and enter the required input fields.
Integration Modifications
Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.
Python code modifications should not be done.
Template Modifications
General Section
"Name", "Extension", "Variable Prefix", and "Icon" should not be changed.
Universal Template Details Section
"Template Type", "Agent Type", "Send Extension Variables", and "Always Cancel on Force Finish" should not be changed.
Result Processing Defaults Section
Success and Failure Exit codes should not be changed.
Success and Failure Output processing should not be changed.
Fields Restriction Section
The setup of the template does not impose any restrictions. However, concerning the "Exit Code Processing Fields" section.
i. Success/Failure exit codes need to be respected.
ii. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining the success or failure of a task.
Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.
Document References
This document references the following documents:
Document Link | Description |
---|---|
Universal Templates | User documentation for creating, working with and understanding Universal Templates and Integrations. |
Universal Tasks | User documentation for creating Universal Tasks in the Universal Controller user interface. |
Changelog
ue-prefect-1.0.0 (2024-07-19)
Initial Release supporting Flow Run executions on Prefect Cloud.