Skip to main content

CustomScript

Custom Script Node

The Custom Script Node allows you to create and run custom Python scripts within your TheoBuilder workflows. This powerful node enables you to perform complex data processing, calculations, and business logic that goes beyond standard workflow nodes.

What This Node Does​

The Custom Script Node executes Python code that you write, allowing you to:

  • Process and transform data from previous workflow steps
  • Perform complex calculations and business logic
  • Integrate with external systems and APIs
  • Create custom data validation and filtering
  • Generate reports and analytics

Your script receives data from connected nodes and can output results to subsequent workflow steps.

When to Use This Node​

Perfect For:​

  • Complex Data Processing: When you need calculations or transformations that standard nodes can't handle
  • Custom Business Logic: Implementing specific rules unique to your organization
  • External System Integration: Connecting to APIs or services not covered by existing nodes
  • Advanced Analytics: Creating custom reports, metrics, or data analysis
  • Data Validation: Building complex validation rules for incoming data

Business Scenarios:​

  • Calculate complex pricing models with multiple variables
  • Process customer data according to specific business rules
  • Generate custom reports combining data from multiple sources
  • Validate data against complex business requirements
  • Transform data formats for external system integration

Configuration Parameters​

Script Content​

  • Field Name: Script Editor
  • Type: Code editor with syntax highlighting
  • Default Value: Empty script template
  • Simple Description: The Python code that will execute when this node runs
  • When to Change This: Every time you set up this node - this is where you write your custom logic
  • Business Impact: The script determines exactly what processing happens to your data

Programming Language​

  • Field Name: language
  • Type: Dropdown menu with options:
    • Python: Standard Python scripting (recommended for most users)
    • JavaScript: Alternative scripting option for web-based logic
  • Default Value: Python
  • Simple Description: Choose which programming language to use for your script
  • When to Change This: Only change if you specifically need JavaScript functionality
  • Business Impact: Python is more suitable for data processing and business logic

Data Orientation​

  • Field Name: orient
  • Type: Dropdown menu with options:
    • Records: Data organized as a list of individual records (recommended)
    • Index: Data organized by row index numbers
    • Values: Data as raw values only
    • Columns: Data organized by column names
  • Default Value: Records
  • Simple Description: How your input data is structured when it reaches your script
  • When to Change This: Change based on how you want to access the data in your script
  • Business Impact: Records format is easiest to work with for most business scenarios

Script Encryption​

  • Field Name: encryption
  • Type: Toggle switch (On/Off)
    • On: Script content is encrypted and password-protected
    • Off: Script content is stored in plain text
  • Default Value: Off
  • Simple Description: Protects your script code with password encryption
  • When to Change This: Enable when your script contains sensitive business logic or credentials
  • Business Impact: Prevents unauthorized viewing of proprietary algorithms or sensitive data

Encryption Password​

  • Field Name: password
  • Type: Password field
  • Default Value: Empty
  • Simple Description: Password required to view and edit encrypted scripts
  • When to Change This: Set when enabling script encryption
  • Business Impact: Ensures only authorized team members can modify critical business logic

Setting Up Your Custom Script​

Adding the Node:​

  1. Drag the Custom Script node from the left panel onto your workflow canvas
  2. Connect it to previous nodes that will provide input data
  3. Click on the Custom Script node to open the configuration panel

Basic Configuration:​

  1. Choose Your Language: Select "Python" from the language dropdown (recommended)
  2. Set Data Format: Keep "Records" selected for the data orientation
  3. Open Script Editor: Click the "Open Script Editor" button to write your code

Writing Your Script:​

  1. The script editor opens in a full-screen dialog
  2. Write your Python code using the syntax highlighting editor
  3. Access input data through the data variable
  4. Return results using the return statement
  5. Click "Save" to store your script and close the editor

Testing Your Script:​

  1. Use the workflow's test mode to run your script with sample data
  2. Check the output to ensure your logic works correctly
  3. Modify and re-test as needed

Real-World Use Cases​

Customer Loyalty Points Calculator​

Business Situation: An e-commerce company needs to calculate loyalty points based on complex rules involving purchase amount, customer tier, and seasonal bonuses.

What You'll Configure:

  • Set language to "Python"
  • Keep data orientation as "Records"
  • Write a script that calculates points based on multiple factors
  • Return the calculated points for each customer

Script Logic Example: Your script receives customer purchase data and calculates points based on:

  • Base points: 1 point per dollar spent
  • Tier multiplier: Bronze (1x), Silver (1.5x), Gold (2x)
  • Seasonal bonus: 25% extra during holidays
  • Minimum 10 points per purchase

Business Value: Automates complex loyalty calculations that would take hours manually, ensuring consistent point awards and improving customer satisfaction.

Invoice Data Validation​

Business Situation: A manufacturing company receives invoices in various formats and needs to validate data before processing payments.

What You'll Configure:

  • Use Python for robust data validation
  • Set up validation rules for required fields
  • Check data formats and ranges
  • Flag suspicious or incomplete invoices

What Happens: Each invoice is automatically checked against your business rules, with valid invoices proceeding to payment processing and invalid ones flagged for manual review.

Business Value: Reduces payment errors by 89% and saves 12 hours per week on manual invoice review.

Sales Performance Analytics​

Business Situation: A sales organization wants to calculate custom performance metrics that combine multiple data sources.

What You'll Configure:

  • Process sales data, quota information, and territory assignments
  • Calculate custom metrics like quota attainment, growth rates, and rankings
  • Generate performance scores for each sales representative

Business Impact: Provides real-time sales insights that help managers identify top performers and coaching opportunities, leading to 23% improvement in team performance.

Industry Applications​

Financial Services​

Common Challenge: Complex interest calculations, risk assessments, and regulatory compliance calculations.

How This Node Helps: Create custom scripts for loan calculations, investment returns, and compliance reporting that match your specific business requirements.

Configuration Recommendations:

  • Enable script encryption for sensitive financial algorithms
  • Use detailed error handling for regulatory compliance
  • Implement audit trails within your scripts

Healthcare Organizations​

Common Challenge: Processing patient data according to specific medical protocols and privacy requirements.

How This Node Helps: Build custom data processing that follows HIPAA requirements and medical calculation standards.

Configuration Recommendations:

  • Always enable encryption for patient data processing
  • Implement strict data validation and error handling
  • Use secure password management for script access

Manufacturing Companies​

Common Challenge: Complex inventory calculations, production scheduling, and quality control metrics.

How This Node Helps: Create custom algorithms for production optimization, inventory management, and quality analysis.

Results: Manufacturers report 15-30% improvement in production efficiency and 40% reduction in inventory carrying costs.

Best Practices​

Script Development:​

  • Start with simple logic and test frequently
  • Use clear variable names and comments
  • Handle errors gracefully with try/catch blocks
  • Test with various data scenarios

Security Considerations:​

  • Enable encryption for scripts containing sensitive business logic
  • Use strong passwords for encrypted scripts
  • Limit script access to authorized team members only
  • Avoid hardcoding sensitive credentials in scripts

Performance Optimization:​

  • Keep scripts focused on specific tasks
  • Process data in batches when handling large datasets
  • Use efficient algorithms for better workflow performance
  • Monitor script execution time and optimize as needed

Data Handling:​

  • Validate input data before processing
  • Handle missing or invalid data appropriately
  • Return consistent data formats for downstream nodes
  • Document your data transformations clearly

Troubleshooting Common Issues​

Script Won't Save:​

  • Check for syntax errors in your code
  • Ensure all required fields are completed
  • Verify you have proper permissions

Unexpected Results:​

  • Test with sample data to verify logic
  • Check data orientation settings
  • Review input data format and structure
  • Add debugging output to identify issues

Performance Problems:​

  • Optimize loops and data processing
  • Consider breaking complex scripts into smaller parts
  • Review data size and processing requirements
  • Monitor workflow execution times

The Custom Script Node provides unlimited flexibility for your business automation needs. While it requires some technical knowledge, the visual editor and testing tools make it accessible for users who need to implement custom business logic in their workflows.