Complete Workflows Python Node Documentation

Copyright © 2019+ SGO (Soluciones Gráficas por Ordenador SL)
All Rights Reserved.

This documentation provides a complete guide to creating Python nodes for Workflows. It covers everything from basic concepts to advanced patterns and best practices.

Overview

Python nodes in Workflows are the core building blocks that define custom functionality within workflows. They are implemented as Python files that define specific functions to handle initialization, readiness checking, and processing logic.

Documentation Structure

This documentation is organized into several key sections:

1. Creating Python Nodes for Workflows - Basic node creation concepts
2. Workflows Node Property Schemas (.xsd) - Property Editor schemas (.xsd): visibility, ordering, and widget types
3. Workflows Node Default Values (.xml) - Node Defaults XML (.xml): default values used by Node Preferences
4. Python Node API Reference - Detailed API reference for all available methods
5. Python Node Development Patterns and Best Practices - Development patterns and best practices
6. Comprehensive Node Examples - Comprehensive examples of different node types

Getting Started

To create a new Python node:

1. Create a new Python file in the workflows library directory
2. Implement the required functions (init, isReady, process)
3. Create corresponding XSD schema file in the schemas directory
4. Test the node in the workflow editor
5. Debug and refine as needed

Required Functions

Every Python node must implement three required functions:

init(self)

Called when the node is initialized. This is where you set up the node's properties, connectors, and other configurations.

isReady(self)

Called before process to check if the node is ready to process. Returns True if ready, False if not ready, or use self.critical() for error messages.

process(self)

Contains the main logic of the node. This is where the actual work happens.

Node Properties

Properties are defined using self.addProperty(name, defaultValue) and can be accessed directly as self.property_name. Properties are exposed in the node editor through the corresponding XSD schema file.

Connectors

Connectors are used to connect nodes in a workflow:

• Cconnector.CONNECTOR_TYPE_INPUT - Input connector
• Cconnector.CONNECTOR_TYPE_OUTPUT - Output connector
• Cconnector.MODE_OPTIONAL - Optional connector
• Cconnector.MODE_REQUIRED - Mandatory connector

Node File Structure

Each node consists of:

1. Python file (e.g., MyNode.py) - Node implementation. All properties are created in code (typically in init() via addProperty(), addEncryptedProperty(), etc.). Some properties may be internal and not exposed in the GUI.
2. XSD schema file (e.g., mynode.xsd) - Property Editor schema. Defines how existing properties are presented in the GUI (visibility, grouping, ordering, and editor/control type). The XSD does not create properties.
3. XML default values file (e.g., mynode.xml) Node Defaults (Node Preferences). Defines the default values used by the Node Preferences / Node Defaults system. Without this file, node defaults cannot be edited from Node Preferences (the node will fall back to defaults defined in code)

Name Convention The .xsd and .xml base name must match the node identifier: same as the .py file name, lowercase and without spaces. The display name in the Finder can be overridden with setClassName() (must be called from init()).

Development Workflow

1. Plan your node functionality
2. Create the Python file with required functions
3. Create the corresponding XSD schema file
4. Test in workflow editor
5. Debug and refine
6. Document your node

Testing and Debugging

Nodes should be tested in actual workflows:

1. Add node to workflow
2. Connect appropriate inputs/outputs
3. Run workflow to observe behavior
4. Check logs for error messages
5. Verify that properties are correctly set and accessible

Best Practices

• Always implement all three required functions (init, isReady, process)
• Use proper error handling with self.critical() for critical errors
• Implement progress tracking for long-running operations
• Check self.isCancelled() regularly to support cancellation
• Set appropriate node colors for visual identification
• Use meaningful property names and descriptions
• Handle both input and output connectors properly
• Implement bypass functionality when appropriate
• Use self.setComplexity() for accurate progress reporting
• Follow the naming conventions used in existing nodes

Troubleshooting

Common issues:

• Missing required functions (init, isReady, process)
• Incorrect connector setup
• Property access errors
• Progress tracking issues
• External application path problems
• Schema validation errors

Always check the workflow logs for error messages when debugging node issues.

Related Documentation

• Creating Python Nodes for Workflows - Basic node creation concepts
• Workflows Node Property Schemas (.xsd) - Property Editor schemas (.xsd): visibility, ordering, and widget types
• Workflows Node Default Values (.xml) - Node Defaults XML (.xml): default values used by Node Preferences
• Python Node API Reference - Detailed API reference
• Python Node Development Patterns and Best Practices - Patterns and best practices
• Comprehensive Node Examples - Complete examples of different node types

Summary

Creating Python nodes for Workflows is a powerful way to extend functionality. By following the patterns and best practices outlined in this documentation, you can create robust, efficient, and maintainable nodes that integrate seamlessly with the existing workflows system.

The key is to understand the API, follow established patterns, and test thoroughly in actual workflow scenarios.