Workiva Scripting provides a flexible, secure platform for running Python code on the Workiva software. By writing custom scripts that automatically execute repeatable processes, you can create efficiencies at scale across multiple reports, files, and workspaces.
Note: Scripting is currently only available through Customize Workiva. Learn more.
角色和權限
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.
| 角色 | 訪問級別 |
|---|---|
| 腳本運行器 | 可以運行腳本。 |
| 腳本檢視器 | 可以查看腳本。 |
| 腳本編輯器 | 可以檢視、建立和編輯腳本。 |
Tip: Rather than use the Script Runner role, we recommend most non-technical users initiate scripts via integrated automations.
You can also control access on a per-file basis by assigning permissions. Because permissions supersede roles, script owners and creators can grant or restrict access to individual files.
| 權限 | 訪問級別 |
|---|---|
| 檢視者 | Can run and view scripts. |
| 編輯者 | Can run, edit, and view scripts. |
| 擁有者 | Can run, edit, view, and create scripts. |
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, or through chains.
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 "Run" endpoint from the Workiva Scripting API:
/v0/scripts/{script-id}/runs/{run-id} 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'll 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:
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.
We also have a number of solutions available here in the Support Center:
- Supported scripting libraries and dependencies
- Sample: Script to update spreadsheets
- Add, upload, and delete scripting source files
- Execute scripts with automations
- Store script outputs
- Workiva Scripting limits
- Sample scripts
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.
常見問題集|常見問題
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.
With that said, scripts can be widely adapted for many business needs. 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.
Are there are any scripting limits?
Yes, Workiva enforces a number of limits for both Workiva Scripting and the scripting API.
Learn more about scripting limits.
How do I trigger scripts from Chains?
This requires the Workiva Scripting connector.Contact us to have the Workiva Scripting connector enabled in your workspace.
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.
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's scripting roles (Script Viewer, Script Runner, and Script Editor) 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 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?
We've collected a number of sample scripts for your use. These scripts can also be manually created using the articles linked in the prior question.
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.
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.
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").
| 變數 | 說明 |
|---|---|
| WORKIVA_ORGANIZATION_ID | The Workiva org ID |
| WORKIVA_ACCOUNT_ID | The Workiva workspace ID |
| WORKIVA_CLUSTER_DOMAIN | The Workiva region (US, APAC, EU) of your production environment. You can verify this by comparing against the URL used to log into Workiva. |
Can I use code from one Workiva script in another Workiva script?
At this time, there is no way to package a Workiva script as a library and reuse the code across multiple scripts. The best option right now is to copy the reusable piece of code and paste it into the scripts as needed.