Application Install (REST)

The Application Install service includes endpoints 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 service through .NET. For more information, see Application Install (.NET).

This page contains the following information:

Client code sample

To use the Application Install service, send requests by making calls with the required HTTP methods. See the following base URL for this service:

<host>/Relativity.REST/API/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationID}/install/

Note: For the workspace identifier in the URL, use -1 to indicate the admin-level context. This value is required for all URLs in the Application Install service. For additional guidelines, see Application Install API.

Field descriptions for JSON requests

The Application Install service uses many common fields for JSON requests.

Install an application library to specific workspaces

To install an application to one or more workspaces, send a POST request with one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{IncludeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{IncludeActions}

Install an application library to all workspaces

To install an application to all workspaces, send a POST request with one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/all
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/all/{IncludeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/all
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/all/{IncludeActions}

The client can specify one of two options for Mode:

  • ForceInstall
  • UpgradeOnly

Retrieve the installation status of an application

To get the installation status of an application, send a GET request with one of the following URLs. The request URL can take either the application's ArtifactID or the Guid.

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID}/{IncludeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID}/{IncludeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/{workspaceID}/libraryapplications/{artifactID}/install?{IncludeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/{workspaceID}/libraryapplications/{applicationGuid}/install?{IncludeActions}

The body of the request is empty.

If the installation failed due to validation errors (duplicate name or locked app conflicts), the endpoint is invoked with the includeActions flag, then the JSON response will have the conflicts listed and with a sample request to retry the installation.

Retrieve the number of workspaces with an outdated application

To retrieve the number of outdated workspace installations associated with an application, send a GET request with the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/outdated-workspaces-count
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactGuid}/install/outdated-workspaces-count

The body of the request should be empty.

If the count of outdated workspace installations is greater than zero, the response will include an action to update all outdated applications to the latest version available in the Application Library, as well as the payload associated with the action. The JSON response would look like this:

{
    "ApplicationIdentifier": {
        "ArtifactID": 1017669,
        "Guids": [
            "c9e4322e-6bd8-4a37-ae9e-c3c9be31776b"
        ]
    },
    "IsGlobalApplication": false,
    "OutdatedWorkspacesCount": 2,
    "UpdateOutdatedApplications": {
        "Name": "UpdateOutdatedApplications",
        "Href": "Relativity.LibraryApplications/workspace/-1/libraryapplications/1017669/install/all",
        "Verb": "GET",
        "IsAvailable": true,
        "Reason": []
    },
    "UpdateOutdatedApplicationsPayload": {
        "Mode": "UpgradeOnly",
        "UnlockApplications": true
    }
}

Cancel pending application installations

To cancel one or more application installations, send a DELETE request with one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install

If the endpoint is invoked with a single application installation ID, the JSON request should be empty.

Retrieve installation details for an application

To retrieve installation details for an application, use the GetApplicationInstallDetailsAsync() method.

This endpoint has four different implementations:

  • With ID but no actions
  • With GUID but no actions
  • With ID and actions
  • With GUID and actions

To get details of an install,, send a GET request with one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID}/details/{start}/{length}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID}/details/{start}/{length}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID}/details/{start}/{length}/{includeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID}/details/{start}/{length}/{includeActions}

The body of the request is empty.

Generate an installation report

This endpoint has two different implementations. To get a report, send a GET request with one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/{applicationInstallID}/details/csv
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/{applicationInstallID}/details/csv

The response will be an IKeplerStream object. In a browser context, this will be turned into a file download.

Cancel pending application installations

This endpoint cancels all pending application installs associated with a specified application. To cancel all pending application installations, send a DELETE request with one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/install/all
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/install/all

The JSON request should be empty.

Retrieve installation status by workspace

This endpoint has one implementation with optional query fields start (default: 1), length (default: 10), and includeActions (default: false). To search application installations, send a POST request the following URL:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/install/search?start={start}&length={length}&includeActions={includeActions}

Note: The includeActions parameter controls whether the pagination properties are populated. If your workflow requires iterating through pages of results using these properties, you need to include the includeActions parameter in your method call with the value set true on in the request. For more information, see Actions and pagination.

Query for application installations by identifier

This endpoint has two implementations with optional query fields start (default: 1), length (default: 10), and includeActions (default: false). To search application installations, send a POST request to one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationID:int}/install/search?start={start}&length={length}&includeActions={includeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid:guid}/install/search?start={start}&length={length}&includeActions={includeActions}

Note: The includeActions parameter controls whether the pagination properties are populated. If your workflow requires iterating through pages of results using these properties, you need to include the includeActions parameter in your method call with the value set true on in the request. For more information, see Actions and pagination.

Validate new artifact names

This endpoint has one implementation. To validate one or more name requests, send a POST request with one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/install/conflict/validate-names

Query for application installations with additional fields

This endpoint has two implementations with optional query fields start (default: 1), length (default: 10), and includeActions (default: false). To search application installations, send a POST request to one of the following URLs:

https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationID:int}/install/available-workspaces?start={start}&length={length}&includeActions={includeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid:guid}/install/available-workspaces?start={start}&length={length}&includeActions={includeActions}

Note: The includeActions parameter controls whether the pagination properties are populated. If your workflow requires iterating through pages of results using these properties, you need to include the includeActions parameter in your method call with the value set true on in the request. For more information, see Actions and pagination.

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.