Application Install (.NET)

The Application Install API includes methods for installing applications into one or more workspaces, cancel pending installations, as well as retrieving the status of application installations. Additionally, it supports conflict resolution for failed application installations.

You can also use the Application Install API through REST. For more information, see Application Install service.

This page contains the following information:

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

Guidelines for the Application Install API

Review the following guidelines for working with the Application Install API.

Admin-level context

The value for the workspaceID parameter in the path should always be -1. Any other value will return an error.

Permissions

For all endpoints in the IApplicationInstall API, users are required to be system administrators in order to have sufficient permissions.

Sample use cases

The Application Install API can be used by R1 Operations or ISVs to manage third-party applications in their Relativity instances. For example, a provisioning pipeline may update a new environment with supported third-party applications. Note that this API can be used in conjunction with the Library Application API.

Create a proxy

The Application Install API includes the following endpoints. To set up a proxy to interact with the IApplicationInstall API, call the CreateProxy() method on the object returned by the GetServiceManager() method.

Install an application library to specific workspaces

To install an application from the library into one or more workspaces, use the InstallApplicationAsync() method of the IApplicationInstallManager interface. The response reports the installation status for each workspace, and a failure to queue an installation request for one workspace will not prevent the others from being queued.

Install an application library to all workspaces

To install an application into all workspaces or upgrade all workspaces where the application is already installed, use the InstallApplicationAllAsync() method of the IApplicationInstallManager interface.

Retrieve the installation status of an application

To query for the status of a particular application installation request, use the GetStatusAsync() method of the IApplicationInstallManager interface. After invoking InstallApplicationAsync, clients are required to poll until the installation status reaches a terminal state (completed or failed) before the application can be consumed in the target workspace. 

Retrieve the number of workspaces with an outdated application

To retrieve the total number of workspaces containing an outdated version of a specified application, use the GetOutdatedWorkspacesCount() method. A version is considered "outdated" if it is lower than the version installed in the Application Library.

Cancel pending application installations

To cancel one or more pending application installations, use the CancelAsync() method of the IApplicationInstallManager interface. If an installation is already in progress or complete, its corresponding result object will indicate an unsuccessful cancellation with a message explaining why.

Retrieve installation details for an application

To retrieve the installation details for a specified application and application installation ID, use the GetApplicationInstallDetailsAsync() method of the IApplicationInstallManager interface.

Generate an installation report

Use the GetApplicationInstallDetailsReportAsync() method to retrieves the the installation details for a specified application and application installation ID and creates a CSV report.

Cancel pending application installations

Use the CancelAllAsync() method to cancel all pending application installs associated with a specified application.

Retrieve installation status by workspace

Use the SearchAsync() method to returns the installation status of one or more applications by workspace. Callers can provide a condition string (with the same format as Object Manager) and a list of sort fields as search criteria. The results are paged using the provided page start index and length.

Supported Condition Fields

Field Name Data Type
Application Text
Application Artifact ID Integer
Application GUID GUID
Case Artifact ID Integer
Client Name Text
Completed On Date
Current Application Install ID Integer
Installed By Text
Is Installed Boolean
Library Origin Signature Text
Library Version GUID
Matter Name Text
Message Text
Origin Signature GUID
Started On Date
Status Code Integer
Version Text
Workspace Text

Note: Acceptable values for Status Code are 1 (Pending), 2 (InProgress), 3 (Failed), 4 (Completed), and 5 (Canceled).

Query for application installations by identifier

The SearchApplicationAsync() method returns the installation status by workspace, but it further filters the results by a supplied application identifier. The application filter is a common use case that warrants its own endpoint. The condition string, sort fields, and paging work like SearchAsync.

Validate new artifact names

Use IsNameAvailable() method to validates any new names requested for artifacts causing name or friendly name conflicts.

Query for application installations with additional fields

Use the GetAvailableWorkspacesAsync() method to retrieve a list of workspaces and indicates whether or not the specified application is installed in each workspace. If the application is installed, the version, status, and other installation information will be populated. This endpoint shares the request and response contracts with the SearchAsync and SearchApplicationAsync endpoints.

Workflow-Based code samples

The following code samples provide example scenarios on how the Application Install API and Library Application API endpoints can be used together.

Additional Resources

DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.