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.
Note: Scripting is currently only available through Customize Workiva. Learn more.
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.
- On the far-right side of the screen, select Automations from the panel.
- Click + or Create to add a new automation.
- From the Automation trigger dropdown menu, select Manual Execution.
- Under When run is selected by, optionally give other users the ability to manually run this automation.
- Under Action details, select Execute script.
- Under Script ID, enter the ID from the end of the script's URL.
- Select the spreadsheet and section that contain the script's inputs. This is optional.
- 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 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.