Scripting FAQ

Note: Scripting is currently only available through Customize Workiva.  Learn more.

Scripting setup and overview

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:

• Workiva Scripting connector
• Workiva Scripting commands

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.

Using the scripting editor

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").

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.

Using scripts from automations

Can I execute a script hosted in another workspaces, org, or environment (APAC, EU,US)?

The automations feature in Workiva can only execute scripts in the same workspace where the file is located. However, the Workiva Scripting connector or the Workiva Scripting API can be used to execute a script hosted in another location.

If using the scripting API, you must create and host a script in the main workspace whose sole purpose is to call the Scripting API and execute the script in the secondary workspace.

Can I send runtime inputs/parameters on script execution?

At this time, the automations feature doesn't allow runtime inputs that are sent to the script when the script is executed.

What metadata is sent to a script execution from an automation?  Is the workspace id sent?

When a script is executed from an automation, the only parameter sent is the ID of the document where the automation is configured.

How do I access credentials to Workiva and non-Workiva systems from the script execution?

When a script is executed from an automation, the only option is to hardcode the credentials in the code itself.

Can the same script be executed simultaneously from two or more files?

Yes, a script can be executed simultaneously from either the same file or multiple files.

Using scripts from chains

Can I execute a script hosted in another workspaces, org, or environment (APAC, EU,US)?

Yes, a script hosted in one workspace can be executed by a chain hosted in a different workspace, organization, or environment.

To do this, the Workiva Scripting connector used in the chain must be set up with an API grant created in the host workspace, and the scripting/IAM URLs used must correspond to the correct workspace.

See the articles below to learn more:

• Workiva Scripting connector
• Workiva Scripting commands

Can the same script be executed simultaneously from two nodes?

The same script can be executed simultaneously from multiple nodes within the same Chain and/or multiple Chains.  

How do I use the output from a script in another chain node?

The Run Script command allows you to enter a sample payload for each output that produces JSON, which can then be used in other nodes.

Can a temporal file be created in a chain by parameters in the script?

You can set binaries as parameters as long as they do not exceed 128KB.

APIs and libraries

Which APIs and libraries are supported?

Workiva Scripting currently supports:

• Workiva Public APIs
• Non-Workiva APIs
• Python's Standard Library
• The Python Package Index (PyPI)

Support for additional languages is still under consideration and could be implemented in the future.

Learn more: Supported Workiva Scripting libraries and dependencies

Which version of Python is used in Workiva Scripting?

Workiva Scripting currently uses Python 3.9.7. 

There are no plans to upgrade to a newer version at this time, but should this change, we will notify all scripting users of the planned update.

Does Workiva provide API clients with popular languages like Python or Java?

We do not currently provide public SDKs for Python or Java.

However, we provide open API specifications for Workiva APIs so you can generate these libraries yourself. For example, you can obtain the Workiva Platform API's OAS file and generate a client library.

Are there scripting-specific APIs available?

Scripting API endpoints are available as prototype endpoints within the Workiva's Prototype Platform API.

How do I create and view API grants for the Workiva Public APIs?

You'll need to obtain a client ID and secret by following the instructions here.

How do I authorize into the Workiva Public APIs using Python?

The following code snippet makes a call to the IAM service to generate an access token that is then used to authenticate into the Scripting prototype endpoints. It will get a list of all the scripts that the API grant (i.e., client) has access to in the workspace where the grant was created.

import requests import json import os AUTH_URL = "https://api.app.wdesk.com/iam/v1/oauth2/token" SCRIPTING_API_URL = "https://api.app.wdesk.com/prototype/platform/scripts/" CLIENT_ID = os.getenv('CLIENT_ID') CLIENT_SECRET = os.getenv('CLIENT_SECRET') tokenResponse = requests.post( AUTH_URL, data = 'client_id=' + CLIENT_ID + '&client_secret=' + CLIENT_SECRET + '&grant_type=client_credentials', headers = {'Content-Type': 'application/x-www-form-urlencoded; \ charset=UTF-8'}) accessToken = 'Bearer ' + json.loads(tokenResponse.text)['access_token'] dataRes = requests.get(SCRIPTING_API_URL, headers = {'Authorization': accessToken}) print(json.loads(dataRes.text)) 

How do I update the format of cells using Python?

The Update Sheet Content prototype endpoint allows updating the format of cells using Python code.  

Can I read/write or upload non-Workiva files stored in Workiva?

At this time, there are no endpoints available to read/write or upload non-Workiva files stored in Workiva.

Can I programmatically create and manage automations?

At this time, there are no endpoints available to programmatically create or manage automations.