Script Manager (.NET)

In Relativity, you can execute SQL scripts through the UI that act on the databases backing an instance. You can implement these scripts to customize and extend Relativity functionality. For more information, see Scripts on the RelativityOne Documentation site.

The Relativity Script Manager API exposes methods for interacting with scripts as follows:

  • Using CRUD operations on a script
  • Retrieving script input parameters
  • Previewing a script and its input parameters
  • Importing a scripting
  • Running jobs on a script, such as retrieving its status, exporting results, and others.

Use this API to create standalone applications that manage scripts across multiple environments or across workspaces in a single environment.

You can also use the Script service through REST. For more information, see Script service.

The Relativity.Extensibility.SDK contains this API. For compatibility and package installation instructions, see Download the SDKs and NuGet packages.

Script Manager API fundamentals

Key concepts

Note: For a script to be run (once queued) a Script Run Manager agent must be running in the environment.

Methods - the following gives a brief list of the methods available in the service

Models - the following lists data models used in the Script Manager service.

Troubleshooting information

For more complicated scripts, it is often easier to implement and debug the script body using SQL Server Management Studio directly.

Add a script

To add a script to Relativity, call the CreateAsync method by passing in the following parameters:

  • workspaceID - the ArtifactID of the workspace where the script should be created. Use -1 to indicate the admin workspace.
  • scriptRequest - a request object containing the data used to create the script.

This method returns the Artifact ID of the new script.

Retrieve script metadata

Note: Method is overloaded for optional metadata and action data.

The ReadAsync method retrieves basic metadata for a script, including its name, body and other parameters.

  • workspaceID - the ArtifactID of the workspace where the script should be created. Use -1 to indicate the admin workspace.
  • scriptID - the Artifact ID of the script to retrieve.

Modify a script

The UpdateAsync () method modifies a script by passing the following parameters to it:

  • workspaceID - the ArtifactID of the workspace where the script should be updated. Use -1 to indicate the admin workspace.
  • scriptID - the Artifact ID of the script.
  • scriptRequest - a request object containing the data used to update the script.

Delete a script

The DeleteAsync method deletes a script by passing it the following parameters:

  • workspaceID - the ArtifactID of the workspace where the script should be deleted. Use -1 to indicate the admin workspace.
  • scriptID - the Artifact ID of the script.

Import a script

The ImportAsync method imports a script from the admin library to the workspace script library when you pass it the following parameters:

  • workspaceID - the ArtifactID of the workspace where the script should be imported to. Use -1 to indicate the admin workspace.
  • scriptID - the Artifact ID of the script.
  • scriptImportRequest - a request object containing the data used to import the script from the script library.

The method returns the Artifact ID of the imported script in the workspace.

Retrieve script input parameters

The GetScriptParametersAsync method retrieves a list of the input parameters defined in a given script when you pass it the following parameters:

  • workspaceID - the ArtifactID of the workspace containing the script. Use -1 to indicate the admin workspace.
  • scriptID - the Artifact ID of the script.

The method returns a list of ScriptParameterDetail objects containing information about the inputs for the script.

Preview a script

The PreviewScriptAsync method is used to examine a script body (with input values applied) before running it, by passing it the following parameters:

  • workspaceID - the ArtifactID of the workspace containing the script. Use -1 to indicate the admin workspace.
  • inputs - a list of values for all defined inputs of the script.

The method returns a string representing the SQL query that will be executed when the script is run (with input values applied).

Queue a script to run

The EnqueueRunJobAsync method queues a script to be run when you pass it the following parameters:

  • workspaceID - the ArtifactID of the workspace containing the script. Use -1 to indicate the admin workspace.
  • inputs - a list of inputs required by the script.
  • timeZoneOffet - specifies a time zone offset value (referenced in the script body with #TimeZoneOffset#).
  • Return value - an EnqueueRunJobResponse object containing a script run job unique identifier used to obtain run job status and script results.

Note: You should call the CleanupRunJobAsync method once querying the results of your script job has finished.

Retrieve status of a script run job

The ReadRunJobAsync method returns the status of the script run job and each action contained in the script when you pass it the following parameters.

  • workspaceID - the ArtifactID of the workspace containing the script. Use -1 to indicate the admin workspace.
  • runJobID - run job identifier contained in the EnqueueRunJobResponse object.

The method returns the status of each action in the queued script.

Run Job Status:

  • Queued - the job has been successfully submitted and is queued to be run.
  • InProgress - the job is actively being run.
  • Completed - all actions have been run and completed without error.
  • CompletedWithErrors - all actions have been run and one or more have errored.
  • FailedToComplete - the job failed to complete.
  • AgentHasNotCheckedIn - the Agent has missed multiple consecutive check-ins.

Action Job Status:

  • Queued - the job has been successfully submitted and is queued to be run.
  • InProgress - the job is actively being run.
  • Completed - the job has successfully completed without error.
  • Errored - the job has been run and has errored.

Query action results

The QueryActionJobResultsAsync method returns completed script action results that match query filter and sort criteria when you pass in the following parameters:

  • workspaceID - the ArtifactID of the workspace containing the script. Use -1 to indicate the admin workspace.
  • runJobID - run job identifier contained in the EnqueueRunJobResponse object.
  • actionIndex - zero-based index of script action to query. Scripts can have multiple action sections, which are executed in sequence. The actionIndex parameter refers to these actions. A value of 0 refers to the first action in the script, 1 refers to the second action, etc. All scripts have at least one action section; 0 will always work. If 1 is entered for a script with only a single action section, an error will be returned.
  • actionQueryRequest - query condition criteria. See Object Manager query syntax for details.
  • start - used for pagination. Zero-index of first row in the response.
  • length - used for pagination. Number of rows in response.

The method returns results from script actions matching query criteria and pagination values.

Export action results

The ExportActionResultsAsync method returns completed script action results that match query filter/sort conditions when you pass in the following parameters:

  • workspaceID - the ArtifactID of the workspace containing the script. Use -1 to indicate the admin workspace.
  • runJobID - run job identifier contained in the EnqueueRunJobResponse object.
  • actionIndex - zero-based index of script action to query.
  • actionExportRequest - contains an ActionQueryRequest parameter to provide filter and sort criteria to be applied to returned results.

The method exports a stream containing results from script action matching query criteria and pagination values to a CSV formatted text file.

Export script report

The ExportScriptReportAsync method returns completed script results (for all actions) that match query filter/sort conditions when you pass in the following parameters:

  • workspaceID - the ArtifactID of the workspace containing the script. Use -1 to indicate the admin workspace.
  • runJobID - run job identifier contained in the EnqueueRunJobResponse object.
  • scriptExportRequest - used to specify the file type of the exported script results (HTML, CSV, PDF, XLS, XLSX, RTF, PNG).

The method returns a stream containing script results in the specified file format.

Clean up script results

The CleanupRunJobAsync method cleans up all temporary tables created as part of a script run job when you pass in the following parameters:

  • workspaceID - the ArtifactID of the workspace containing the script. Use -1 to indicate the admin workspace.
  • runJobID - run job identifier contained in the EnqueueRunJobResponse object.

Note: Once this method has been called the script results are no longer available for querying or export.