Scripts in your site can be run using the Script Execution action in the Automations panel. This allows you to manually run scripts from a document, spreadsheet, or presentation.
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.
Requirements
- Workiva Scripting must be enabled for your workspace. Learn more about Workiva Scripting.
- Scripts can only be run in the same workspace where they're hosted. Learn more.
- Only file owners can create an automation.
- The Script Editor role is required to create scripts.
Create your automation
To create an automation from a file you own:
- From Home, open a document, presentation, or spreadsheet.
- In the right sidebar, click the Automations lightning bolt icon.
- Click + or Create a new automation to add a new automation.
- From the Automation trigger dropdown menu, select Manual Execution.
- (Optional) Give other users the ability to manually run this automation by entering their names and selecting them in the When run is selected by field.
- Under Action details, select Execute script.
- Enter the ID from the end of the script's URL in the Script ID field.
- (Optional) Select the spreadsheet and section that contain the script's inputs.
- Click Create to finish.
Run and manage your automation
Your new automation will appear as "Active" in the Automations panel. As the file's owner, you can perform several actions from the dropdown menu:
- Run: Manually runs the automation's script.
- Edit: Update details about the automation, such as its trigger criteria.
- Disable/Activate: Select whether an automation is available to run.
- View activity: Open the automation's activity log.
- Delete: Permanently remove the automation from the file.
Note: To prevent duplicate runs, the Run option is disabled for 20 seconds between clicks.
Information your script receives
When an automation runs, it sends information that the script reads as environment variables:
- DOCUMENT_ID: The ID of the document where the automation is run.
- INPUT_SHEET_ID: The WURL of the spreadsheet used to manage the automation's input parameters.
- INPUT_RESOURCE_ID: The WURL of the section in the aforementioned spreadsheet.
- INPUT_SPREADSHEET_ID: The ID of the aforementioned spreadsheet.
- INPUT_SPREADSHEET_SHEET_ID: The ID of the section in the aforementioned spreadsheet.
A WURL is a proprietary, Workiva-specific URL that contains the ID and other information of the spreadsheet or section.
To retrieve the IDs from the parameters, use this script:
# Welcome to Workiva Scripting
import requests
import json
import os
DOCUMENT_ID = os.getenv('DOCUMENT_ID')
SPREADSHEET_ID = os.getenv('INPUT_SPREADSHEET_ID')
SHEET_ID = os.getenv('INPUT_SPREADSHEET_SHEET_ID')
print("RAW parameters:")
print(os.environ)
print("")
print("Actual IDs:")
print(DOCUMENT_ID)
print(SPREADSHEET_ID)
print(SHEET_ID)Note: The automation does not currently send any Workiva public API credentials — such as the client ID or secret — to the script. You may need to code these credentials directly into the script.
FAQ
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 following parameters are sent
- DOCUMENT_ID: The ID of the document where the automation is run.
- INPUT_SHEET_ID: The WURL of the spreadsheet used to manage the automation's input parameters.
- INPUT_RESOURCE_ID: The WURL of the section in the "input" spreadsheet.
- INPUT_SPREADSHEET_ID: The ID of the "input" spreadsheet.
- INPUT_SPREADSHEET_SHEET_ID: The ID of the section in the "input" spreadsheet.
For more information, see the Workiva Support page Execute scripts with automations.
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.