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, make a HTTP POST request to the Initiate a script execution prototype endpoint.
The script ID is included in the endpoint; you can pass parameters by defining the names and values of the environment variables in the body of the POST request.
Script outputs are logged as stderr and stdout, along with some usage metrics to monitor the health of the product.
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. Please note, however, that our agents can only assist with questions about the platform itself -- we can't assist in writing or troubleshooting your 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 questions related to using the Workiva Public APIs to write your code to interact with the Workiva Platform programmatically utilize our Developers & APIs 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 are 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?
Absolutely. Security is our top priority at Workiva, and we've built an infrastructure that guarantees your code runs are both secure and performant. Your scripts execute on Workiva-managed, FedRAMP-compliant infrastructure — within the same trusted platform, permissions, and governance as the rest of your Workiva work.
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 that users have access only to the scripts necessary for their job. The Script Runner role, for instance, allows users to run scripts but not access any of 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 where users can retrieve the latest version of a script or update a script to a newer copy. Workiva does not currently offer automated synchronization between scripts files and your enterprise version control system (e.g. Gitlab, Github, SVN).
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 (external link) 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 org id, workspace id, and region in my scripts?
Yes, the organization id, workspace id, and region (US, APAC, EU) are accessible to your script code via environment variable. 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, 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.