Application Install service

Through the REST API, the Application Install API allows clients to install applications into one or more workspaces, cancel pending installations, as well as get the status of any specified application installations. Additionally, this API allows support for conflict resolution for any failed application installations.

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/

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.

InstallApplicationAsync

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

1
2
3
4
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}

InstallApplicationAllAsync

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

1
2
3
4
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/installall
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{artifactID}/installall/{IncludeActions}
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/installall
https://{host}/relativity.rest/api/Relativity.LibraryApplications/workspace/-1/libraryapplications/{applicationGuid}/installall/{IncludeActions}

The client can specify one of two options for Mode:

  • ForceInstall
  • UpgradeOnly

GetStatusAsync

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.

1
2
3
4
5
6
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.

GetOutdatedWorkspacesCount

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

1
2
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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "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
    }
}

CancelAsync

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

1
2
3
4
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.

GetApplicationInstallDetailsAsync

This endpoint retrieves the installation details for a specified application and application installation ID, send a GET request with one of the following URLs:

1
2
3
4
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.

GetApplicationInstallDetailsReportAsync

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

1
2
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.

CancelAllAsync

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:

1
2
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.

SearchAsync

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.

JSON Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
{
    "Results": [
        {
            "ApplicationInstallID": 53769,
            "ApplicationIdentifier": {
                "Name": "Imaging",
                "ArtifactID": 1015285,
                "Guids": [
                    "c9e4322e-6bd8-4a37-ae9e-c3c9be31776b"
                ]
            },
            "WorkspaceIdentifier": {
                "Name": "Admin Case",
                "ArtifactID": -1,
                "Guids": []
            },
            "RootFolderID": 0,
            "InstallStatus": {
                "Code": "Completed",
                "GetDetailsAction": {
                    "Name": "GetInstallDetails-DefaultPage",
                    "Href": "Relativity.LibraryApplications/workspace/-1/libraryapplications/1015285/install/53769/details/1/10",
                    "Verb": "GET",
                    "IsAvailable": true,
                    "Reason": []
                }
            },
            "Version": "11.1.0.0",
            "IsOutOfDate": false,
            "InstalledBy": {
                "Name": "Service Account, Relativity",
                "ArtifactID": 777,
                "Guids": []
            },
            "StartedOn": "2019-12-02T17:01:32.753",
            "CompletedOn": "2019-12-02T17:01:49.923"
        },
        {
            "ApplicationInstallID": 53784,
            "ApplicationIdentifier": {
                "Name": "Imaging",
                "ArtifactID": 1015285,
                "Guids": [
                    "c9e4322e-6bd8-4a37-ae9e-c3c9be31776b"
                ]
            },
            "WorkspaceIdentifier": {
                "Name": "New Case Template",
                "ArtifactID": 1014823,
                "Guids": []
            },
            "ClientIdentifier": {
                "Name": "Relativity Template",
                "ArtifactID": 1006066,
                "Guids": []
            },
            "MatterIdentifier": {
                "Name": "Relativity Template",
                "ArtifactID": 1000002,
                "Guids": []
            },
            "RootFolderID": 1003697,
            "InstallStatus": {
                "Code": "Completed",
                "GetDetailsAction": {
                    "Name": "GetInstallDetails-DefaultPage",
                    "Href": "Relativity.LibraryApplications/workspace/-1/libraryapplications/1015285/install/53784/details/1/10",
                    "Verb": "GET",
                    "IsAvailable": true,
                    "Reason": []
                }
            },
            "Version": "11.1.0.0",
            "IsOutOfDate": false,
            "InstalledBy": {
                "Name": "Service Account, Relativity",
                "ArtifactID": 777,
                "Guids": []
            },
            "StartedOn": "2019-12-02T17:02:12.11",
            "CompletedOn": "2019-12-02T17:02:55.58"
        },
        {
            "ApplicationInstallID": 53801,
            "ApplicationIdentifier": {
                "Name": "Imaging",
                "ArtifactID": 1015285,
                "Guids": [
                    "c9e4322e-6bd8-4a37-ae9e-c3c9be31776b"
                ]
            },
            "WorkspaceIdentifier": {
                "Name": "Relativity Starter Template",
                "ArtifactID": 1015024,
                "Guids": []
            },
            "ClientIdentifier": {
                "Name": "Relativity Template",
                "ArtifactID": 1006066,
                "Guids": []
            },
            "MatterIdentifier": {
                "Name": "Relativity Template",
                "ArtifactID": 1000002,
                "Guids": []
            },
            "RootFolderID": 1003697,
            "InstallStatus": {
                "Code": "Completed",
                "GetDetailsAction": {
                    "Name": "GetInstallDetails-DefaultPage",
                    "Href": "Relativity.LibraryApplications/workspace/-1/libraryapplications/1015285/install/53801/details/1/10",
                    "Verb": "GET",
                    "IsAvailable": true,
                    "Reason": []
                }
            },
            "Version": "11.1.0.0",
            "IsOutOfDate": false,
            "InstalledBy": {
                "Name": "Service Account, Relativity",
                "ArtifactID": 777,
                "Guids": []
            },
            "StartedOn": "2019-12-02T17:02:17.017",
            "CompletedOn": "2019-12-02T17:03:00.283"
        }
    ],
    "Summary": {
        "Other": 0,
        "Pending": 0,
        "InProgress": 0,
        "Failed": 0,
        "Completed": 37,
        "Canceled": 0,
        "TotalActiveInstalls": 0,
        "Total": 37
    },
    "CurrentStartIndex": 1,
    "ResultCount": 3,
    "TotalCount": 37,
    "FirstPage": {
        "Name": "SearchStatus-FirstPage",
        "Verb": "POST",
        "IsAvailable": false,
        "Reason": []
    },
    "PreviousPage": {
        "Name": "SearchStatus-PreviousPage",
        "Verb": "POST",
        "IsAvailable": false,
        "Reason": []
    },
    "NextPage": {
        "Name": "SearchStatus-NextPage",
        "Href": "Relativity.LibraryApplications/workspace/-1/libraryapplications/1015285/install/search?start=4&length=3&includeActions=true",
        "Verb": "POST",
        "IsAvailable": true,
        "Reason": []
    },
    "LastPage": {
        "Name": "SearchStatus-LastPage",
        "Href": "Relativity.LibraryApplications/workspace/-1/libraryapplications/1015285/install/search?start=37&length=3&includeActions=true",
        "Verb": "POST",
        "IsAvailable": true,
        "Reason": []
    }
}

SearchApplicationAsync

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:

1
2
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.

IsNameAvailable

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

GetAvailableWorkspacesAsync

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:

1
2
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.