Scripting Overview

Scripts are powerful and fast as they run on Vitruvi's servers and can access data and perform actions far quicker than calling remote APIs.

Aside from performance, the other advantage of scripts are they are very tightly integrated with Vitruvi so that they can be triggered automatically upon certain actions in the application. These include:

Custom actions - Scripts that are added to drop down menus in Vitruvi in the item grids.
Events - Scripts that are triggered automatically when data in Vitruvi is added, updated or deleted.
Service Hooks - Scripts that get executed on a set schedule or triggered from an external API call.

When thinking about requesting a script, it is important to think carefully about the steps that you would like it to perform and the data it will need to complete that automation.

Vitruvi's 7 Steps to Scripting Ecstacy

Scripts cannot prompt the user for additional data, so the data will have to exist in the items it is operating on, or it will have to be configured (hard coded) inside the script.
Scripts can automate any workflow or data changes in the system, as long as the action can also be performed in the application itself.

Scripts are not magic! If an action cannot be performed in the UI, it is unlikely it will be able to be scripted. For example, in the user interface you cannot move a Production Report from approved back to submitted - a script also cannot perform that action as the workflow is prohibited by the core application.

When defining the script requirements, try to speak in the same terms as how you would perform the action if guiding someone through the user interface to do the same thing. If it isn't clear how to do the actions manually, it probably won't be enough detail for the script writer to code the script.
When defining the script request, be specific about what data fields you are referring to in the automation script. For example, provide screenshots of the application with labels and arrows pointing to the fields that you want to read from or push data into.
If the scripts need to provide any feedback back to the user, consider how this will be provided. The usual method is to email a user. This can include the current active user, a hard coded configured user, or an email address contained within the data object the script is operating on. These emails can contain information in the body of the email, or attached to the email as files such as Excel or CSV files.

With the addition of the Custom Action script type, it is possible to generate a file such as an Excel or CSV file with the necessary information and trigger the file download in the browser at the end of the script execution.
If the scripts need to interact with an external system such as through an API or file transfer, be specific about these interactions. If it is from an API, we will need a sandbox or test account set up in order to investigate what APIs are available and whether we can get at the data for the requirement. If it is from a file transfer, provide the specific file we will need to process. These need to be set up and provided prior to any scripting requests in order to scope and quote on any work.
Always consider error handling - things don't always run as expected. If there is an error, consider how the error should be handled. It can either be ignored, or it can be logged and emailed to a specific user to be looked into further.

Consideration should also be given to where in the process an error occurs. For example, if the script is importing a large file and an error occurs on a row of data - should the process stop entirely and send the error information. Or should it just log that one row, skip it and carry on with the rest?
Outline any permission or security requirements. By default, the script will execute under the user context of the person that triggered the script. If the script attempts to change an item that the current user does not have access to, it will fail.

If the script needs to execute as a superuser, this needs to be specified and why. Also specify if a particular script should only be executed for certain users or users that belong to specific groups.