Parameters

You can create input parameters for your scripts that will be available when scripts are executed manually. These parameters look and feel similar to the fields on a task form and you can use all of the familiar data types available minus the object reference data type. Additionally, you can make a parameter required and provide default values if you wish. Parameters are great for scripts that are intended to be executed manually where the script can react to information provided at run time. For example, you could create a script that contains a yes/no parameter that tells the script to provide more verbose output or not to help debug a script during development. You could have a matter id script parameter that would perform some kind of maintenance on the matter when executed, that way you don’t have to hard-code a value directly within the script and you wouldn’t have to give some users edit rights to scripts just to execute it.

Manual Script Execution

Parameters are intended to be for scripts that will be executed manually. They don’t make sense in an event trigger scenario, because the event trigger wouldn’t be able to fill out any of the parameters you’re expecting. However, you can still define parameters that can be used to help develop a script that you execute manually to emulate or provide data that event triggers would provide automatically, such as ids. Additionally, you can instruct the script to provide additional output data as a parameter while you’re executing them manually that an event trigger would ignore and wouldn’t have to output.

To create a parameter, you can use the "Add a Parameter…” link on the right-side action panel or you can navigate to the Parameters tab on the left and click on the “New Parameter” button.

When creating a new parameter, you will be presented with the following modal window:

The following fields are available for defining a script parameter:

• Label
  This is the friendly name of the parameter that will be present on the script execution window.

• Name
  This is the variable name of the parameter that will be available within the script. You can write your scripts that use this name to access the value of the parameter that was input while executing the script. This field will only accept letters.

• Position
  This is the placement of the parameter on the script execution window. The lower the number, the higher the priority. Negative numbers work, too.

• Required?
  This marks the parameter as required or not on the script execution window.

• Data Type
  This defines the type of input that will be available on the script execution window. See the table below for more details.

• Default Value

  You can provide a default for all data types except for single choice and multiple choices (not required). Note that default values are only provided while manually executing a script and are not provided if the script is executed via an event trigger.

Data Types

The following data types are available as script parameters:

Example: Get Matter by Matter Id with Optional JSON Structure

Create a new script and name it “Get Matter by Matter Id with Optional JSON Structure”. Provide the following script for the body:

$matter = Get-Matter $MatterId 

if ($null -eq $matter) {
    Write-Output "Unable to locate a matter with an id of $MatterId"
    exit
}

Write-Output $matter.Name

if ($ShowJSON -eq $true) {
    Write-Output ""
    $matter | ConvertTo-Json -Depth 10
}

Take note of the $MatterId and $ShowJSON variables here. We will define these variables as script parameters that can be provided while manually executing the script.

Next, click on the “Add a Parameter…” link on the right-hand action panel. Fill out the form with the following:

• Label: Matter Id

• Name: MatterId

• Position: 0

• Required? Yes

• Data Type: Whole Number

• Default Value: 1

Save the parameter and click the “Add a Parameter…” link again to create the second parameter. Fill out the form with the following:

• Label: Show JSON in the output?

• Name: ShowJSON

• Position: 10

• Required? No

• Data Type: Yes or No

• Default Value: No

Save the parameter. You should notice that the “Name” fields for the two parameters here matched the variable names that were created in the script.

Next, click on the “Execute script…” link on the right-hand action panel. You should see the following modal window:

The parameters that we defined for the script are shown in the position order we defined them in along with the proper data types, requirement, and default values.

There is a small icon next to each field label that has the letters “AB” in it. If you click on this icon, it will remind you what the variable name is within the script.

Ensure that the Matter Id is one that exists within your workspace and click the “Execute” button. You should just see the name of the matter returned.

Change the “Show JSON in the output?” value to “Yes” and execute the script.

You will notice that the values you enter in the form will be injected into the named variables for you within the script. In this last example in addition to the name, we also get the JSON structure with all of the fields for the matter. This is because the script had a conditional check for the $ShowJSON variable that if it is true, it would output the matter instance as a JSON formatted string.

As you can see, defining parameters for scripts can be a powerful way of controlling the flow of a script and allows your users to execute scripts dynamically without having to edit the script to change hard-coded values.