Python Script Node (Administrators): Run Custom Logic with File I/O

What it is

The Script node (also shown as "Python Script Node" in the designer) lets an administrator embed a custom code step directly in a workflow. When a workflow instance reaches this node, the code runs in a sandboxed environment and can:

• Read files uploaded during the workflow (for example, a timesheet or biometric report uploaded by the requester).
• Read data values collected by any earlier step in the workflow (form field values, task decisions, AI agent outputs).
• Write output files that later steps — such as an Email node — can attach and send automatically.
• Return named output values (a dictionary of key-value pairs) that become workflow variables available to every downstream node.

This node is the escape hatch for any custom business logic that cannot be expressed with the built-in nodes alone: data transformation, file format conversion, calculations, validation against external rules, and so on.

Why it's useful / Key benefits

• Handle any custom business logic or data transformation mid-process. If built-in nodes cannot express a rule, the script node can. There are no limits on what the code can compute.
• Convert file formats automatically. Transform an uploaded CSV or Excel file into a PDF summary, or extract a subset of rows — the script runs, produces the output file, and the workflow continues.
• Validate data against complex rules before it reaches approvers. Run a check that cannot be expressed in a simple condition node, and route the workflow accordingly based on the result.
• Produce files that later Email nodes attach and send. The output files produced by a script are stored in the document library and can be referenced in email nodes — completing a full data-to-email automation chain.
• Keep secrets out of the workflow. The script runs server-side in a controlled environment. Credentials, API keys, and sensitive logic stay on the server and are never visible to end users or in the browser.
• Set a timeout to prevent runaway scripts. A configurable timeout (5 seconds to 1 hour) ensures that a script that hangs does not block a workflow instance indefinitely.

Administrator-only. The Script node is hidden from non-administrator users in the designer sidebar and cannot be saved by non-administrator accounts. This access control is enforced on the server, not just in the interface.

Before you start

• You must have an Administrator role. Saving a Script node from a non-administrator account will be rejected.
• You should understand Python programming. Code entered in this node runs as-is in a server environment with access to common libraries.
• Review which file picker widgets are used in the workflow's Start node (Applications form integration) so you know the exact widget names to reference in the script.
• Open the workflow from the Workflow Management screen and click Edit.

How to use it — step by step

Step 1: Place the node on the canvas

1. In the visual designer, open the Logic tab in the left sidebar.

   Note: The Script node appears in the sidebar only for Administrator users. If you do not see it, verify your role.

2. Drag the Python Script Node onto the canvas after the step that collects the files or data the script needs.

3. Connect the preceding node's output handle to the Script node's input.

4. Double-click the node (or click the gear icon on hover) to open the Python Script Node configuration dialog.

Step 2: Set the label, description, and timeout

5. In the Node title field at the top, enter a name that describes what the script does (for example, "Timesheet Processor" or "Invoice Validator"). This name appears on the canvas.

6. In the Description field, enter an optional short note explaining the script's purpose.

7. In the Timeout (s) field, set how long the script is allowed to run before it is forcibly stopped. The range is 5 to 3600 seconds (up to 1 hour). The default is 300 seconds (5 minutes).

   Set a timeout appropriate to the expected runtime. A very long timeout means a stuck script blocks the workflow instance for that long before the failure is surfaced.

Step 3: Write the code (Code tab)

8. Click the Code tab (selected by default).

9. Write your Python code in the editor. The environment provides three built-in objects you can use directly:

   Object	How to use it
   input_files["widgetName"][0]	The file uploaded through the file picker widget named widgetName. Returns a file-like object.
   output_files["outputKey"]	A writable file path for the output file registered under the key outputKey. Write to this in your script to produce the output file.
   workflow_data.get("key", default)	The value of the workflow variable named key. Supply a default value for the case where the key is not present.

   A minimal example:

   import openpyxl
   
   # Read the uploaded Excel file
   wb = openpyxl.load_workbook(input_files["uploadBiometricFile"][0])
   ws = wb.active
   
   # Count non-empty rows (excluding header)
   row_count = sum(1 for row in ws.iter_rows(min_row=2) if any(c.value for c in row))
   
   # Save the processed workbook as the output
   wb.save(output_files["timesheet"])
   
   # Return values to use in downstream nodes
   return {"rows_processed": row_count}
   

   The return statement at the end of your script exposes a dictionary of key-value pairs as workflow variables. For example, return {"rows_processed": 42} makes {{rows_processed}} available to every downstream node.

Step 4: Configure Input Files (Input Files tab)

10. Click the Input Files tab.

File Picker Widgets:

11. The upper section lists all file picker widgets detected in the workflow's Start node (if an Applications form integration is configured). Each widget is shown as a selectable button.

12. Click the button for each widget whose uploaded file the script should receive. Selected widgets turn cyan with a checkmark. In your code, access the file as input_files["widgetName"][0].

13. If the widget you need is not in the list, click Add manually and type the widget name exactly as it appears in the form.

Workflow Data Variables:

14. The lower section ("Workflow Data Variables") shows all text and input widgets whose values are available via workflow_data.get("key"). This section is read-only — it is informational, showing you the exact key names to use in your script. No action is needed here.

Step 5: Define Output Files (Output Files tab)

15. Click the Output Files tab.

16. Click Add output file for each file the script will write.

17. For each output file, configure:

• Key (used in code) — the key you use in output_files["yourKey"] in the script (for example, timesheet). Keep this short and lowercase with no spaces.
• Display label — a human-readable name for the file (for example, "Timesheet Output"). This label is used when selecting the output in later workflow steps.
• Save to Documents toggle — when on (default), the file produced by the script is automatically stored in the document library and can be attached by a downstream Email node. Turn off if you do not need the file saved.

18. Click the red trash icon to remove an output file entry.

Step 6: Save and connect

19. Click Save in the dialog footer. The dialog closes.

20. In the designer, draw edges from the Script node's output handle to the next step.

21. Click Save (or press Ctrl+S).

Options & settings explained

Header fields

Code tab

Input Files tab

Output Files tab

Tips & best practices

• Keep scripts focused and short. A script that does one thing well is easier to maintain and debug than one that does everything. Chain multiple Script nodes for complex multi-step transformations.
• Always provide defaults in workflow_data.get() — for example, workflow_data.get("amount", 0) — to prevent KeyError crashes if an optional field was left blank.
• Use descriptive keys in your return dictionary. The keys become variable names in the workflow. Clear names like invoice_total or approval_status are easier to reference in downstream conditions and prompts than result or val1.
• Test with edge cases. Run the workflow manually with an empty file, a zero value, or a missing optional field. Errors in the script mark the workflow instance as failed and stop it at this node.
• Set the timeout generously for file-intensive scripts but not excessively. A 5-minute timeout is generous for most transformations; a 1-hour timeout should be reserved for genuinely heavy processing.
• Enable "Save to Documents" on output files if any downstream step (an Email node, for example) needs to attach the file. The file must be persisted in the document library to be attachable.
• Name your output keys consistently with your email node. If you name the output invoice_pdf, you will find it under that name in the Email node's attachment options.
• Document what the script does in the Node Description field and in code comments. This is important for maintainability — the next administrator who edits the workflow may not be familiar with the original intent.

Frequently asked questions

Q: I do not see the Script node in the sidebar. What is wrong? The Script node is hidden from non-administrator users. Only accounts with the Administrator role can see, add, or save Script nodes. Verify your role in the top navigation bar.

Q: Can I import external Python libraries? The script runs in a pre-configured server environment. Standard library modules and common data-processing libraries (such as openpyxl, pandas, and similar) are typically available. Contact your system administrator for the full list of available libraries or to request additional packages.

Q: What happens if the script raises an exception? The workflow instance is marked as failed at the Script node. Open the instance from All Instances and review its Workflow Detail View and operational records. Fix the script, save the design, and trigger a new controlled run.

Q: Can the script make HTTP requests to external systems? This depends on the server's network configuration. The code itself can include HTTP requests, but whether outbound network calls are permitted is a system-level setting. Check with your infrastructure administrator.

Q: Can I use the return value from a Script node in an If/Else condition later in the workflow? Yes. Every key in the returned dictionary becomes a workflow variable. If your script returns {"status": "approved"}, you can reference {{status}} in a downstream If/Else condition.

Q: How do I attach a script-generated file to an email? Enable Save to Documents on the output file in the Output Files tab. Then in the downstream Email node's attachment settings, select "Specific output files" and choose the file by its display label.

Q: Can multiple Script nodes exist in the same workflow? Yes. Each is configured independently. Variables returned by one Script node are available to all subsequent nodes, including later Script nodes.