Workiva Scripting provides a flexible, secure environment for running Python code on the Workiva platform. By writing custom scripts that automatically execute repeatable processes, you can create efficiencies at scale across multiple reports, files, and workspaces. And as more work becomes AI-assisted, Scripting gives that work a reliable, governed foundation to build on — pairing flexibility with the control needed to turn automation into repeatable outcomes you can trust.
Scripting is included with Customize Workiva. To use Scripting, your workspace must have Customize Workiva/Scripting enabled, and users will need the appropriate Scripting role(s) and file permissions.
Roles and permissions
Roles are a system-wide setting in Workiva, meaning they establish a standard level of access for every script in a workspace. There are three Workiva Scripting roles that can be assigned by your Workspace Admin.
| Role | Level of access |
|---|---|
| Script Runner | Can run scripts. |
| Script Viewer | Can view scripts. |
| Script Editor | Can view, create, and edit scripts. |
For more information, see the Scripting roles and permissions Support page.
How to use Workiva Scripting
Once enabled in your workspace, scripts will appear on your home screen alongside the other spreadsheets, documents, and presentations in your site. You can either create a new script or select an existing one from your file list.
The script editor is where you'll build, edit, and run the scripts within your site.
It includes:
- A center canvas where you'll compose the script
- An output section at the bottom where you'll view the results of the script's run
- A menu bar across the top where you'll save or run the script
- A properties panel on the right to manage script properties and run history
- A sources panel on the left side
Once built, scripts can be executed manually, programmatically, through chains, or from within a Workiva File.
To run a script manually:
- Click Run Script in the menu bar at the top of the screen.
- Click + Add Variable.
- Enter the names and values of the environment variables to pass as parameters.
- Click Run Script.
To run a script programmatically, use an API grant with:
-
script:executeto start the script. -
script:readto retrieve its run status, logs, or output.
Send an HTTP POST request to POST /scripts/{scriptId}/execution with the X-Version: 2026-01-01 header. The request body is required. Define runtime inputs as string-valued JSON properties, or send an empty JSON object ({}) if the script does not require inputs.
The endpoint returns 202 Accepted with an operationLocation. Poll that URL until the operation reaches completed, failed, or cancelled. The operation’s resourceUrl identifies the resulting script run.
Script logs include standard output, standard error, and execution details.
For more information, see the Workiva Developers Scripting API overview.
To run a script through chains:
You will need to use the Workiva Scripting connector. Before doing so, an org security administrator must enable the connector through the Configurations screen.
See the articles below to learn more:
To run a script within a Workiva file, you'll need to follow the steps below:
In the Automations panel of a document, spreadsheet, or presentation, create a new automation and choose Manual Execution as the trigger.
Add an Execute script action, select the script you want to run, and optionally define which users or roles are authorized to execute it.
Note: Only those specified users will see and be able to run the automation within the file.
Learn more about Execute scripts with automations.
Create a practice script
Before creating live scripts in your site, we recommend creating a practice script within the script editor. This will help familiarize you with the process before handling live data.
Follow these steps to create a simple script that calculates the time value of money:
- From Home, click + Create => Script.
- On the right side, enter a name and brief description for the script.
- Go the the script editor in the middle of the screen and delete any existing code. You should have a blank canvas.
-
Paste this code into the editor:
"import os, sys # https://www.investopedia.com/terms/t/timevalueofmoney.asp # Formula for Time Value of Money # FV = PV x [1 + (i / n)]^(n x t) # Assume a sum of $10,000 is invested for one year at 10% interest compounded annually. # The future value of that money is: # FV = $10,000 x [1 + (10% / 1)] ^ (1 x 1) = $11,000 compounding_periods = {"annual" : 1, "monthly" : 12, "quarterly" : 4, "daily" :365} if 'INVESTMENT' not in os.environ: print("Cannot run the script. Investment is missing.") sys.exit() if 'INTEREST_RATE' not in os.environ: print("Cannot run the script. Interest rate is missing.") sys.exit() if 'COMPOUNDING_PERIOD' not in os.environ: print("Cannot run the script. Compounding period is missing.") sys.exit() if 'YEARS' not in os.environ: print("Cannot run the script. Number of years are missing.") sys.exit() compounding_period = os.getenv('COMPOUNDING_PERIOD') if compounding_period not in compounding_periods.keys(): print("Cannot run the script.", compounding_period," is not a valid period") sys.exit() investment = int(os.getenv('INVESTMENT')) interest_rate = float(os.getenv('INTEREST_RATE')) years = int(os.getenv('YEARS')) n = compounding_periods[compounding_period] FV = investment * pow((1 + ((interest_rate/100) / n)),n * years) print("Assume a sum of",investment,"is invested for",years,"year(s) at",\ interest_rate,"% interest compounded on",compounding_period,"basis. ") print("The future value of that money is:") print(FV) - Click Run Script at the top left.
- Click +Add Variable and enter any parameters you'd like to use.
- Click Run Script to finish.
The script results can now be viewed in the Output panel at the bottom of the screen.
How to get support with Workiva Scripting
You can contact Workiva Support for any questions about Workiva Scripting. Workiva Support can help with Scripting platform behavior, but cannot write or debug custom Python code.
You can also explore the Workiva Scripting section of the Support Center to learn more — including the basics of scripting, creating and managing scripts, samples, troubleshooting, and best practices.
These resources will help you get started with Workiva Scripting. For additional help, visit the Workiva APIs Community or the Workiva Scripting Community.
FAQ
How are scripts commonly used?
Workiva Scripting can automate many repeatable, time-consuming tasks that would otherwise be completed by hand. Some common use cases include zero-row suppression, report layouts, and the application of custom formatting to multiple documents.
More broadly, scripts can be adapted to your unique business needs — letting you tailor and scale workflows to the way your organization works, with governed execution you can rely on. The code is your own; what you do with it largely depends on your script developer, workspace setup, and the current number of manual processes in your business. And as more work becomes AI-assisted, Scripting gives that work a reliable, repeatable foundation to act on.
Are there any scripting limits?
Yes, Workiva enforces a number of limits for both Workiva Scripting and the scripting API.
Learn more about Workiva Scripting limits.
How do I trigger scripts from Chains?
This requires the Workiva Scripting connector.
See the articles below to learn more:
Is Workiva Scripting FedRAMP compliant?
Yes. Scripts execute on Workiva-managed, FedRAMP-compliant infrastructure, with the same platform permissions and governance controls as other Workiva content.
How can I guard access to scripts?
There are several ways you can protect your code from being accessed by unauthorized users:
- Create a dedicated workspace or organization for authorized users: Creating a workspace, or even an entire organization, of only authorized users is the most secure option. For example, partners can create a workspace for Workiva Scripting in your organization and have customers run scripts from their own org.
- Use roles: Workiva Scripting roles—Script Editor, Script Viewer, and Script Runner—are tiered so users can access only the scripts needed for their work. The Script Runner role allows users to run scripts without viewing the code.
- Use permissions: Scripting files can be restricted at the file level so that only specific users can edit or view your code.
Learn more about Workiva Scripting roles and permissions.
Is there a list of allowed IPs for scripting?
Yes, allowed IPs for the scripting program are included here.
Is there a script library available?
Yes. We've collected a number of sample scripts for your use. You can also build your own using the how-to articles in the Create and manage scripts section of the Support Center.
How do I manage script versions?
At this time, Workiva stores only the latest version of a script.
You can create copies of your script files in Workiva and organize them in folders, but we recommend using a separate version control system — especially if you have an enterprise version control system, see Workiva Scripting: Development Process Best Practices.
How do I sync Workiva code with an enterprise version control system (e.g., GitHub)?
The Workiva Scripting API provides source-management endpoints for retrieving and updating script source files. Retrieving sources requires script:read; creating, updating, uploading, or synchronizing sources requires script:write. Workiva does not automatically synchronize scripts with external version-control systems such as GitHub, GitLab, or SVN.
For instructions on creating or updating an API grant, see Workiva API Setup.
How do I access credentials to Workiva and non-Workiva systems from a script?
There are two ways to access credentials to Workiva and non-Workiva systems:
- Send credentials as runtime inputs (preferred)
- Hardcode the credentials in the code
Why are the values of the script runtime inputs not displayed in the log output during execution?
This is a security precaution. Because input parameters can contain sensitive data, we remove them from user-facing logs.
How can I store temporary data during script executions?
Workiva scripts may use the Python Open function to read and write files temporarily in the /tmp folder. Other paths are restricted.
Every time a script is run, a container is spun up in Workiva's cloud infrastructure. That container has linux installed, and all the paths are restricted except /tmp (which is empty). Data can be written and read temporarily in that path. Once the run is over, the container gets trashed.
Can I define global variables to use across multiple scripts, à la Chains?
Not at this time. However, if your script runs as part of a Chains workflow, you can use Chains variables and pass their values to the script as runtime inputs.
Can I send files as parameters?
Binaries can be sent as parameters as long as they do not exceed 128KB and are encoded to text (i.e., binary to text encoding).
Can I access the organization ID, workspace ID, and region in my scripts?
Yes, the organization ID, workspace ID, and region (US, APAC, CA, EU) are available to your script through environment variables. For example, os.getenv("WORKIVA_ORGANIZATION_ID").
| Variable | Description |
|---|---|
| WORKIVA_ORGANIZATION_ID | The unique ID of the Workiva organization where the script is hosted. |
| WORKIVA_ACCOUNT_ID | The unique ID of the Workiva workspace where the script is hosted. |
| WORKIVA_CLUSTER_DOMAIN | The Workiva region (US, APAC, CA, or EU) of the production environment where the script is hosted. |
| WORKIVA_SCRIPTING_SCRIPT_ID | The unique ID of the Scripting script being run. |
| WORKIVA_SCRIPTING_RUN_ID | The unique ID of the current script run. |
| WORKIVA_SCRIPTING_MEMORY_LIMIT | The maximum amount of RAM available to the script during a single run. |
| WORKIVA_SCRIPTING_DISK_LIMIT | The maximum disk storage that the script can use in the /tmp directory during a single run. |
Can I use code from one Workiva script in another Workiva script?
You can't directly import or call one Workiva script from another. For a small piece of reusable code, you can copy and paste it into each script that needs it.
For code you reuse across many scripts, a better approach is to package it as a shared dependency. You can build a dependencies.zip bundle that includes your shared libraries — and even client code generated from the Workiva public API specification — then upload that same bundle to each script that needs it. This lets you maintain common code in one place and reuse it across scripts instead of copying it into each one.
For steps on building and uploading dependencies, see Supported scripting libraries and dependencies.