The get-download-status operation is used to retrieve the status of an application package download task.

The following statuses are possible:

  • "finished/error" - the task did not start because the package is not found in the APS Catalog
  • "finished/package-id" - the task is successfully completed
  • "in-progress/current" - package download task is currently in progress
  • "in-progress" lacking the "current" child node - package download task is not yet started but queued

Request Packet Structure

A request XML package that retrieves the status of an application package download task should include the get-download-status operation node:

<packet>
    <aps>
        <get-download-status>
            ...
        </get-download-status>
    </aps>
</packet>

The get-download-status node is structured as follows:

image 63521

Note: The interactive schema navigator for all request packets is available here: http://plesk.github.io/api-schemas/1.6.9.1/agent_input.svg.

  • filter, required

    Filters download tasks which status should be retrieved. Data type: none.

    If it is defined with empty value, than a list of all download tasks within the current download transaction is returned. On Windows, a separate transaction is created for each download task. Download transaction lasts as soon as lasts the download process.

  • task-id, optional

    Specifies the ID of download task (returned as a result of the <download-package> operation). Data type: id_type (common.xsd).

Response Packet Structure

The get-download-status node of the output XML packet is structured as follows:

image 63522

Note: The interactive schema navigator for all response packets is available here: http://plesk.github.io/api-schemas/1.6.9.1/agent_output.svg.

  • 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 request contained non-empty filter

    Returns the error message. Data type: string.

  • filter-id, required if the operation succeeds

    Returns the ID by which the operation was filtered. Data type: any.

  • id, required if the operation succeeds

    Returns the ID of the download task whose status is retrieved. Data type: id_type (common.xsd)

  • task, optional

    Holds a collection of data describing the download task status. Data type: none.

    Structured as follows:

image 63523

  • id, required

    Returns the ID of the download task whose status is retrieved. Data type: id_type (common.xsd).

  • finished, optional

    Specifies that the download task is finished. Data type: none.

  • in-progress, optional

    Specifies that the download task is in progress, or is placed in the download queue in case several packages are specified for download at a time. Data type: APSPackageDownloadStatusInProgress (aps.xsd).

  • error, optional

    Specifies that the download was finished with error. Contains error description. Data type: none.

  • package-id, required if the package download completed successfully

    Specifies that the download was finished successfully and returns the ID assigned to the package on your server. Data type: id_type (common.xsd).

  • total, required

    Specifies the total application size in bytes. Data type: integer.

  • completed, required

    Specifies the size of the downloaded part, also in bytes. Data type: integer.

  • current, optional

    Specifies that the download task is currently in progress, opposed to the tasks awaiting at the download queue. Data type: string.

Samples

Getting status of a particular download task

This packet requests status of download task with ID 18:

<packet>
    <aps>
        <get-download-status>
            <filter>
                <task-id>18</task-id>
            </filter>
        </get-download-status>
    </aps>
</packet>

Response A

Positive response may look as follows:

<packet>
    <aps>
        <get-download-status>
            <result>
                <status>ok</status>
                <filter-id>18</filter-id>
                <id>18</id>
                <task>
                    <id>18</id>
                    <finished>
                        <package-id>13</package-id>
                    </finished>
                </task>
            </result>
        </get-download-status>
    </aps>
</packet>

Response B

Such response is received in case a download task did not start or finished with errors.

<packet>
    <aps>
        <get-download-status>
            <result>
                <status>ok</status>
                <filter-id>18</filter-id>
                <id>18</id>
                <task>
                    <id>18</id>
                    <finished>
                        <error>Cannot download package from catalog</error>
                    </finished>
                </task>
            </result>
        </get-download-status>
    </aps>
</packet>

Response C

Such negative response is received in case a download task with the requested ID does not exist.

<packet>
    <aps>
        <get-download-status>
            <result>
                <status>error</status>
                <errcode>1013</errcode>
                <errtext>Download task with id 18 not found</errtext>
                <filter-id>181</filter-id>
            </result>
        </get-download-status>
    </aps>
</packet>

Getting status of all download tasks within a current download transaction

This packet requests status of all download tasks within a current download transaction.

<packet>
    <aps>
        <get-download-status>
            <filter/>
        </get-download-status>
    </aps>
</packet>

Response A

Such response is received from Linux server where the transaction with tree tasks is run: one task is finished, one is in progress and one is queued.

<packet>
    <aps>
        <get-download-status>
            <result>
                <status>ok</status>
                <filter-id>10</filter-id>
                <id>10</id>
                <task>
                    <id>10</id>
                    <finished>
                        <package-id>5</package-id>
                    </finished>
                </task>
            </result>
            <result>
                <status>ok</status>
                <filter-id>11</filter-id>
                <id>11</id>
                <task>
                    <id>11</id>
                    <in-progress>
                        <total>3584225</total>
                        <completed>2458</completed>
                        <current/>
                    </in-progress>
                </task>
            </result>
            <result>
                <status>ok</status>
                <filter-id>12</filter-id>
                <id>12</id>
                <task>
                    <id>12</id>
                    <in-progress>
                        <total>45888236</total>
                        <completed>0</completed>
                    </in-progress>
                </task>
            </result>
        </get-download-status>
    </aps>
</packet>

Response B

Such response is received from Windows server when a transaction is run:

<packet>
    <aps>
        <get-download-status>
            <result>
                <status>ok</status>
                <filter-id>38</filter-id>
                <id>38</id>
                <task>
                    <id>38</id>
                    <in-progress>
                        <total>0</total>
                        <completed>0</completed>
                    </in-progress>
                </task>
            </result>
        </get-download-status>
    </aps>
</packet>

Response C

Such response is received when there is no download transaction running.

<packet>
    <aps>
        <get-download-status>
            <result>
                <status>ok</status>
            </result>
        </get-download-status>
    </aps>
</packet>