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
• Fields
• InstallApplicationAsync
• InstallApplicationAllAsync
• GetInstallStatusAsync
• GetAllInstallStatusAsync
• CancelApplicationInstallAsync
• GetApplicationInstallDetailsAsync

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:

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.

Fields

The requests may contain the following fields for the application:

• WorkspaceIDs - the ID of the workspace.

• WorkspaceIdentifier - the identifier of the workspace.

  • ArtifactID - the Artifact ID of the workspace.
  • Guids - an array of GUIDs used to identify the workspace.

• UnlockAllApplications - setting this flag to true allows the endpoint to automatically unlock any associated applications that have locking conflicts with the application that is being installed. Setting the flag to false instead will force a user to manually resolve any locking conflicts that result from the attempted installation.

• ConflictResolutions - options to resolve an installation conflict. There are four resolution types supported:

  • RenameField - has a numeric value of 1.
  • RenameRelationalFriendlyName - has a numeric value of 2.
  • MapField - which has a numeric value of 3.
  • UnlockAssociatedApplications - unlocking any associated applications that have locking conflicts with the application that is being installed, has a numeric value of 4.
• ConflictCorrelationID - the unique ID that identifies a specific validation conflict found during application installation.
• ConflictArtifactIdentifier - represents the ID, GUID, and name of the artifact that caused the validation conflict.
• Value - if the resolution type is RenameField or RenameRelationalFriendlyName, the artifact that caused the validation conflict will be renamed to the new value that is passed in. If the resolution type is either MapField or UnlockAssociatedApplications, the value should be an empty string.
• ResolutionType - represents the four different types of Resolution Actions supported when dealing with application installation conflicts:
  • RenameField - has a numeric value of 1.
  • RenameRelationalFriendlyName - has a numeric value of 2.
  • MapField - has a numeric value of 3.
  • UnlockAssociatedApplications - unlocking any associated applications that have locking conflicts with the application that is being installed, has a numeric value of 4.
• Mode - for the InstallApplicationAllAsync endpoint, users can set the Mode attribute in the request to one of two options:
  • ForceInstall - has a numeric value of 1, will install the application in all workspaces where it doesn't already exist and upgrade all workspaces where it is already installed.
  • UpgradeOnly - has a numeric value of 2, will only upgrade workspaces where the application is already installed.
• RetryInstallAction - this action queues up another install for the specified application into the specified workspace, though there have been no changes to the application itself. This action is mainly used to resolve installation conflicts.
• RetryInstallRequestTemplate - the RetryInstallRequestTemplate serves as a request for the RetryInstallAction and contains any important details pertaining to conflict resolution, such as the workspace ID, whether or not to auto-unlock any associated applications, the conflict correlation ID, and the conflict artifact identifier.

• Endpoints that include pagination (i.e. those that require a start value and length value), return actions for users to easily navigate through each page of the returned results. The start value represents the index of the first returned result, and the length value represents how many results a user would like returned in a single page.

  • FirstPage
  • PreviousPage
  • NextPage
  • LastPage
• Results - any endpoint that returns a response containing a list of items to return refers to that list as Results. For example, if you want to get the installation status for all workspaces where a specified application is installed, you would call upon the GetAllInstallStatusAsync endpoint, which would return in its response, a list called Results of GetInstallStatusResponse objects, where each object corresponds to a unique workspace.
• ApplicationIdentifier - the identifier of the application.
• IsSuccessful - a Boolean value indicating whether the request succeeded or failed.
• ApplicationInstallID - the ID of the application installation.
• Message - a string that returns an informative message about the status of the request.

• InstallStatus - the status of the application installation.

  • Code - the status code indicating the state of the application installation
  • Message - a string that returns an informative message about the status of the request.

  • GetDetailsAction - an array of Action objects indicating operations that you have permissions to perform on this application. For example, you may not have permissions to modify a application due to your privileges. Each Action object contains the following fields that are available as extended metadata:

    • Name - name of an operation available through REST for the application, such as delete, update, and so on.
    • Href - the URL used to make an HTTP request for the operation.
    • Verb - the name of the HTTP method for the operation.
    • IsAvailable - a Boolean value indicating whether you have permissions to perform the operation on this application.
    • Reason - provides an explanation for the unavailability of an action.
• ValidationMessages - a list of messages associated with the application installation.
• InstalledBy - the user that initiated the application installation.
• StartedOn - the start time for the job.
• CompletedOn - the date and time when the application installation completed.
• Version - the version of the library application.

InstallApplicationAsync

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

InstallApplicationAllAsync

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

The client can specify one of two options for Mode:

• ForceInstall
• UpgradeOnly

GetInstallStatusAsync

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.

The body of the request is empty.

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

GetAllInstallStatusAsync

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

The body of the request is empty.

CancelApplicationInstallAsync

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

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:

The body of the request is empty.