The install operation is used to install an application on a domain/subdomain.
A request XML package that installs an application on domains/subdomains should include the install operation node:
<packet>
<aps>
<install>
...
</install>
</aps>
</packet>
The install node is structured as follows:
Either domain-id, or domain-name, or subdomain-id, or subdomain-name is required.
Specifies the ID of domain where the application should be installed. Data type: id_type (common.xsd
).
Specifies the name of domain where the application should be installed. Data type: string.
Specifies the ID of subdomain where the application should be installed. Data type: id_type (common.xsd
).
Specifies the name of subdomain where the application should be installed. Data type: string.
Either package-id or package is required.
Note: Information identifying a package is obtained with the get-packages-list operation.
Specifies the ID of package on the server from which an application should be installed. Data type: id_type (common.xsd
).
Holds a collection of data describing the package on the server from which the application should be installed. Data type: APSIdentifierType (aps.xsd
). See the type definition below.
Specifies whether the application accessible via the HTTPS protocol or not. Data type: boolean.
If not specified, the application is accessible via HTTP.
Specifies the URL relative to the domain/subdomain, by which the installed application will be accessible on the Web. Data type: APSUrlPrefixType (aps.xsd
).
If not specified, the default prefix defined in the package will be used ("/application/default-prefix"
element in the package APP-META.xml
file).
Holds a collection of data describing properties of a database that will be created for the application, in case it requires any. Data type: APSDatabaseInputType (aps.xsd
), see the type definition below.
If an application requires a database and the database element is not specified in the request, it is created with the name, user login and password generated automatically. Database server (MySQL, PostgreSQL or Microsoft SQL Server) is selected automatically to better fit the application requirements.
Holds a collection of application installation settings. Data type: APSSettingsInputType (aps.xsd
), see the type definition below.
Must present in case the application being installed has settings (the application package metadata file APP-META.xml
contains at least one element "//setting"
).
The package node is structured as follows:
Specifies the application package name. Data type: string.
Specifies the application version.Data type: string.
Specifies the package release.Data type: string.
Specifies the application vendor. Data type: string.
Specifies the application packager. Data type: string
Specifies whether a package is uploaded to the server manually by the Administrator (not from Application Catalog). Data type: string
Specifies if a package is visible to customers and resellers. Data type: string
Specifies the ID of the package assigned to it on the server. Data type: id_type (common.xsd
).
Package should be specified in either reduced or extended form:
The database node is presented by type APSDatabaseInputType (aps.xsd
), and its graphical representation is as follows:
Specifies the database name. Should be unique in the system. Data type: string.
Specifies the database user login name. Should be unique in the system. Data type: string.
Specifies the database user password. Data type: string.
Specifies the prefix for the names of the tables used by the application. Data type: string.
Specifies the server (host and port or IP address) where the database is created. Data type: string.
The settings node is presented by type APSSettingsInputType (aps.xsd
), and its graphical representation is as follows:
Holds an application setting definition. Data type: APSSettingInputType (aps.xsd
).
Information on the application setting names and possible values should be obtained from the application package metadata file APP-META.xml
(the "//setting"
elements).
Request must contain the setting element for each application setting specified without default value in the application package metadata file.
Specifies the setting ID. Should be the same as the setting ID in APP-META.xml
("//setting[@id]"
). Data type: string.
Specifies the setting value. Data type: string.
Important: When creating request packets, put nodes and elements in the order they follow in the packet structure.
The install node of the output XML packet is structured as follows:
Wraps the response retrieved from the server. Data type: resultType (common.xsd
).
Specifies the execution status of the operation. Data type: string. Allowed values: ok | error.
Returns the error code. Data type: integer.
Returns the error message. Data type: string.
Operation specific errors
1013 - specified object (domain, subdomain, package) is not found
1019 - application cannot be installed with the settings specified
1100 - application requirements are not satisfied
The following packet installs application called Serendipity on domain example.com. The required parameters list is reduced.
<packet>
<aps>
<install>
<domain-name>example.com</domain-name>
<package>
<name>serendipity</name>
<version>1.1.2</version>
<release>33</release>
<vendor>s9y.org</vendor>
<packager>plesk.com</packager>
</package>
<database>
<name>s9DB</name>
<login>s9user</login>
<password>s9password</password>
<server>10.52.78.201:3306</server>
<prefix>s9_</prefix>
</database>
<settings>
<setting>
<name>admin_p_name</name>
<value>admin</value>
</setting>
</settings>
</install>
</aps>
</packet>
Response:
<packet>
<aps>
<install>
<result>
<status>ok</status>
</result>
</install>
</aps>
</packet>
The following packet installs the LinkPoint application (which package ID on server is 5) on a subdomain. Such request is possible only when installing applications which do not require a database and have no settings.
<packet>
<aps>
<install>
<subdomain-name>subdomain.example.com</subdomain-name>
<package-id>5</package-id>
</install>
</aps>
</packet>
Response:
<packet>
<aps>
<install>
<result>
<status>ok</status>
</result>
</install>
</aps>
</packet>
1. Such negative response is received in case a specified domain or subdomain does not exist.
<packet>
<aps>
<install>
<result>
<status>error</status>
<errcode>1013</errcode>
<errtext>Domain not found.</errtext>
</result>
</install>
</aps>
</packet>
2. Such negative response is received if a requested package is not found on the server.
<packet>
<aps>
<install>
<result>
<status>error</status>
<errcode>1013</errcode>
<errtext>Package does not exist</errtext>
</result>
</install>
</aps>
</packet>
1. Such negative response is received in case some application settings do not have default values and the request packet does not contain the settings specification.
REQUEST PACKET
<packet>
<aps>
<install>
<domain-name>example.com</domain-name>
<package>
<name>AutoIndex</name>
</package>
</install>
</aps>
</packet>
RESPONSE PACKET
<packet>
<aps>
<install>
<result>
<status>error</status>
<errcode>1019</errcode>
<errtext>Some errors occurred during installation:
Value of setting "admin_password" is invalid: '' is less than 1 characters long
Value of setting "user_password" is invalid: '' is less than 1 characters long</errtext>
</result>
</install>
</aps>
</packet>
2. Such response is received in case the application settings specified in the request are not validated against APP-META.xml
.
REQUEST PACKET
<packet>
<aps>
<install>
<domain-id>10</domain-id>
<package>
<name>joomla</name>
</package>
<settings>
<setting>
<name>admin_name</name>
<value>admin</value>
</setting>
<setting>
<name>admin_password</name>
<value>dfkjEEtbgg</value>
</setting>
<setting>
<name>admin_email</name>
<value>johndoe@example.com</value>
</setting>
<setting>
<name>locale</name>
<value>en-US</value>
</setting>
<setting>
<name>title</name>
<value>Joomla</value>
</setting>
</settings>
</install>
</aps>
</packet>
RESPONSE PACKET
<packet>
<aps>
<install>
<result>
<status>error</status>
<errcode>1019</errcode>
<errtext>Some errors occurred during installation:
The value of "locale" should be one of (en-GB, fr-FR, de-DE)</errtext>
</result>
</install>
</aps>
</packet>
3. Such negative response is received in case the Web directory specified as URL prefix already exists and is used for some content:
<packet>
<aps>
<install>
<result>
<status>error</status>
<errcode>1019</errcode>
<errtext>Some errors occurred during installation:
Destination directory already exists and is used by another Web application.</errtext>
</result>
</install>
</aps>
</packet>
4. Such negative response is received in case the database specified in the request packet already exists:
<packet>
<aps>
<install>
<result>
<status>error</status>
<errcode>1019</errcode>
<errtext>Some errors occurred during installation:
Database with requested name already exists</errtext>
</result>
</install>
</aps>
</packet>
Such negative response is received if the application requirements are not satisfied:
<packet>
<aps>
<install>
<result>
<status>error</status>
<errcode>1100</errcode>
<errtext>The following problems with requirements were found: Unable to meet ASP.NET version requirements. ASP.NET version 2.0 is required.; Unable to meet ASP.NET version requirements. ASP.NET version 2.0 is required.; Unable to meet database server requirements: Database server with type 'mssql' and version not less 9.0 not found</errtext>
</result>
</install>
</aps>
</packet>
Such negative response is received in case request packet specifies the application should be available via HTTPS (<ssl>true</ssl>), but HTTPS is not supported on domain/subdomain.
REQUEST PACKET
<packet>
<aps>
<install>
<domain-id>2</domain-id>
<package>
<name>joomla</name>
</package>
<ssl>true</ssl>
<settings>
<setting>
<name>admin_name</name>
<value>admin</value>
</setting>
<setting>
<name>admin_password</name>
<value>dfkjEEtbgg</value>
</setting>
<setting>
<name>admin_email</name>
<value>johndoe@example.com</value>
</setting>
<setting>
<name>locale</name>
<value>en-GB</value>
</setting>
<setting>
<name>title</name>
<value>Joomla</value>
</setting>
</settings>
</install>
</aps>
</packet>
RESPONSE PACKET
<packet>
<aps>
<install>
<result>
<status>error</status>
<errcode>1023</errcode>
<errtext>The IP address associated with this domain is already used by another domain for SSL support implementation</errtext>
</result>
</install>
</aps>
</packet>