The install operation is used to install an application on a domain/subdomain.

Request Packet Structure

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.

• domain-id, optional

  Specifies the ID of domain where the application should be installed. Data type: id_type (common.xsd).

• domain-name, optional

  Specifies the name of domain where the application should be installed. Data type: string.

• subdomain-id, optional

  Specifies the ID of subdomain where the application should be installed. Data type: id_type (common.xsd).

• subdomain-name, optional

  Specifies the name of subdomain where the application should be installed. Data type: string.

Either package-id or package is required.

• package-id, optional

  Specifies the ID of package on the server from which an application should be installed. Data type: id_type (common.xsd).

• package, optional

  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.

• ssl, optional

  Specifies whether the application accessible via the HTTPS protocol or not. Data type: boolean.

  If not specified, the application is accessible via HTTP.

• url-prefix, optional

  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).

• database, optional

  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.

• settings, optional

  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:

• name, required

  Specifies the application package name. Data type: string.

• version, optional

  Specifies the application version.Data type: string.

• release, optional

  Specifies the package release.Data type: string.

• vendor, optional

  Specifies the application vendor. Data type: string.

• packager, optional

  Specifies the application packager. Data type: string

• is_uploaded, optional

  Specifies whether a package is uploaded to the server manually by the Administrator (not from Application Catalog). Data type: string

• is_visible, optional

  Specifies if a package is visible to customers and resellers. Data type: string

• id, required

  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:

• reduced provides only application name, and in that case application if the highest version and release is installed
• extended provides all package detail: name, version, release, vendor and packager

The database node is presented by type APSDatabaseInputType (aps.xsd), and its graphical representation is as follows:

• name, required

  Specifies the database name. Should be unique in the system. Data type: string.

• login, required

  Specifies the database user login name. Should be unique in the system. Data type: string.

• password, required

  Specifies the database user password. Data type: string.

• prefix, optional

  Specifies the prefix for the names of the tables used by the application. Data type: string.

• server, optional

  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:

• setting, required

  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.

• name, required

  Specifies the setting ID. Should be the same as the setting ID in APP-META.xml ("//setting[@id]"). Data type: string.

• value, required

  Specifies the setting value. Data type: string.

Response Packet Structure

The install node of the output XML packet is structured as follows:

• result, required

  Wraps the response retrieved from the server. Data type: resultType (common.xsd).

• status, required

  Specifies the execution status of the operation. Data type: string. Allowed values: ok | error.

• errcode, required if the operation fails

  Returns the error code. Data type: integer.

• errtext, required if the operation fails

  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

Samples

Installing the Serendipity application

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>odin.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>

Installing the LinkPoint application

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>

‘1013 object not found’ errors

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>

‘1019 bad settings’ errors

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>

‘1100 requirements not met’ error

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>

Other errors

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/TLS support implementation</errtext>
      </result>
    </install>
  </aps>
</packet>