AppMgmt.xml

<?xml version="1.0"?>
<?xml-stylesheet href="docbook.xsl" type="text/xsl" ?>
<book xmlns="http://docbook.org/ns/docbook" version="5.0">
  <info>
    <title>Application Management Service Specification</title>
    <titleabbrev>App Mgmt</titleabbrev>
    <releaseinfo>22.12</releaseinfo>
    <author>
      <orgname>ONVIF™</orgname>
      <uri>www.onvif.org</uri>
    </author>
    <pubdate>December, 2022</pubdate>
    <mediaobject>
      <imageobject>
        <imagedata fileref="media/logo.png" contentwidth="60mm"/>
      </imageobject>
    </mediaobject>
    <copyright>
      <year>2008-2022</year>
      <holder>ONVIF™ All rights reserved.</holder>
    </copyright>
    <legalnotice>
      <para>Recipients of this document may copy, distribute, publish, or display this document so
        long as this copyright notice, license and disclaimer are retained with all copies of the
        document. No license is granted to modify this document.</para>
      <para>THIS DOCUMENT IS PROVIDED "AS IS," AND THE CORPORATION AND ITS MEMBERS AND THEIR
        AFFILIATES, MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
        LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
        NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THIS DOCUMENT ARE SUITABLE FOR ANY PURPOSE;
        OR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS,
        TRADEMARKS OR OTHER RIGHTS.</para>
      <para>IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FOR ANY
        DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES, ARISING OUT OF OR
        RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT, WHETHER OR NOT (1) THE CORPORATION,
        MEMBERS OR THEIR AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR (2)
        SUCH DAMAGES WERE REASONABLY FORESEEABLE, AND ARISING OUT OF OR RELATING TO ANY USE OR
        DISTRIBUTION OF THIS DOCUMENT.  THE FOREGOING DISCLAIMER AND LIMITATION ON LIABILITY DO NOT
        APPLY TO, INVALIDATE, OR LIMIT REPRESENTATIONS AND WARRANTIES MADE BY THE MEMBERS AND THEIR
        RESPECTIVE AFFILIATES TO THE CORPORATION AND OTHER MEMBERS IN CERTAIN WRITTEN POLICIES OF
        THE CORPORATION.</para>
    </legalnotice>
    <revhistory>
      <revision>
        <revnumber>19.12</revnumber>
        <date>Dec-2019</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Initial release</revremark>
      </revision>
      <revision>
        <revnumber>21.06</revnumber>
        <date>Jun-2021</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Update backup and restore. Add configuration URI.</revremark>
      </revision>
      <revision>
        <revnumber>21.12</revnumber>
        <date>Dec-2021</date>
        <author>
          <personname>Fredrik Svensson</personname>
        </author>
        <revremark>Fix inconsistencies between appmgmt schema and doc.</revremark>
      </revision>
      <revision>
        <revnumber>22.06</revnumber>
        <date>Jun-2022</date>
        <author>
          <personname>Sujith Raman</personname>
        </author>
        <revremark>Correct namespace of event State member.</revremark>
      </revision>
      <revision>
        <revnumber>22.12</revnumber>
        <date>Dec-2022</date>
        <author>
          <personname>Sujith Raman</personname>
        </author>
        <revremark>Update Appmgmt app state enumeration.</revremark>
      </revision>
    </revhistory>
  </info>
  <chapter>
    <title>Scope</title>
    <para>This document defines an interface for managing applications on a device. This specification focuses on the network interface for managing the application lifecycle on a device. It includes installation, information retrieval as well as controlling execution. The actual runtime environment as well as the application packaging format are out of scope of this specification.</para>
  </chapter>
  <chapter>
    <title>Normative references</title>
    <para>ONVIF Core Specification</para>
    <para role="reference">&lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.onvif.org/onvif/specs/core/ONVIF-Core-Specification.pdf"></link>&gt;</para>
  </chapter>
  <chapter>
    <title>Informative references</title>
    <para>Docker Enterprise Application Container Platform</para>
    <para role="reference">&lt; <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.docker.com/"></link> &gt;</para>
    <para>Android</para>
    <para role="reference">&lt; <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.android.com/"></link> &gt;</para>
  </chapter>
  <chapter>
    <title>Terms and Definitions</title>
    <section>
      <title>Definitions</title>
      <informaltable>
        <tgroup cols="2">
          <colspec colname="c1" colwidth="24*" />
          <colspec colname="c2" colwidth="76*" />
          <tbody valign="top">
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">App</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>Application that can be installed and execute on a networked device.</para>
              </entry>
            </row>
            <row>
              <entry align="left" />
              <entry align="left" />
            </row>
            <row>
              <entry align="left" />
              <entry align="left" />
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
    <section>
      <title>Abbreviations</title>
      <informaltable>
        <tgroup cols="2">
          <colspec colname="c1" colwidth="24*" />
          <colspec colname="c2" colwidth="76*" />
          <tbody valign="top">
            <row>
              <entry valign="middle">
                <para>HTTP</para>
              </entry>
              <entry valign="middle">
                <para>Hypertext Transfer Protocol</para>
              </entry>
            </row>
            <row>
              <entry valign="middle">
                <para>TLS</para>
              </entry>
              <entry valign="middle">
                <para>Transport Layer Security</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
  </chapter>
  <chapter>
    <title>Overview</title>
    <para>A variety of standardized and proprietary application runtime formats exist. Examples for well-known standardized runtimes are Docker and Android. This specification provides network interface APIs based on the ONVIF Core Specification for uploading and controlling applications on a networked device.</para>
    <para>The following basic functionalities are defined by this specification:</para>
    <itemizedlist>
      <listitem>
        <para>Installing and uninstalling of applications.</para>
      </listitem>
      <listitem>
        <para>Starting and stopping execution of applications.</para>
      </listitem>
      <listitem>
        <para>Enumeration of installed applications</para>
      </listitem>
      <listitem>
        <para>Listing of application details </para>
      </listitem>
      <listitem>
        <para>Enrolling application licenses</para>
      </listitem>
    </itemizedlist>
    <para>An application state change event allows client to retrieve and track application state changes without need for polling.</para>
    <para>Note that both the container format as well as the runtime are outside of the scope of this specification.</para>
  </chapter>
  <chapter>
    <title>Service </title>
    <section>
      <title>General</title>
      <para>Each application has an associated state. Possible states are Installing, Active, Inactive, DeInstalling and InstallationFailed. Clients can retrieve the application state via the GetAppInfo method or by subscribing to the application state property event. The latter mechanism allows retrieving the initial state as well as updates via property events.</para>
    </section>
    <section>
      <title>Application Deployment</title>
      <section xml:id="_Ref4595104">
        <title>Install</title>
        <para>Applications are deployed to a device via http POST to the URI provided by GetServiceCapabilities. The same URI shall be used for updating an application.</para>
        <para>A device supporting this service shall support the POST operation to the upload URI provided by the UploadUri capability.</para>
        <para>When posting an image to one of the URIs, the following HTML status codes may be returned, depending on success or failure:</para>
        <itemizedlist>
          <listitem>
            <para>200 OK</para>
            <para>Image file was successfully uploaded.</para>
          </listitem>
          <listitem>
            <para>401 Unauthorized</para>
            <para>Attempted POST without authentication credentials at the WRITE_SYSTEM access policy level</para>
          </listitem>
          <listitem>
            <para>408 Request Timeout</para>
            <para>POST took too long to upload</para>
          </listitem>
          <listitem>
            <para>411 Length Required</para>
            <para>POST does not include Content-Length header</para>
          </listitem>
          <listitem>
            <para>415 Unsupported Media Type</para>
            <para>POST does not include Content-Type header, or file MIME type does not match any type in the FormatsSupported attribute's list</para>
          </listitem>
        </itemizedlist>
        <para>Note that the installation may not be completed when the upload has finished. </para>
        <para>If uploading succeeded, a device shall signal start of the installation via the state property event. If the installation fails, the device shall send a final InstallationFailed state. Otherwise the state shall change to either Active or Inactive.</para>
      </section>
      <section>
        <title>Update</title>
        <para>For updates, a device shall support the same mechanism as the installation procedure defined in <xref linkend="_Ref4595104" />. </para>
        <para>In case an application is in state Active, the device shall change its state to Inactive before signaling installation state change events as stated in <xref linkend="_Ref4595104" />. </para>
      </section>
      <section>
        <title>Uninstall</title>
        <para>A device supporting this service shall support this method to stop and remove an installed application. </para>
        <variablelist role="op">
          <varlistentry>
            <term>request</term>
            <listitem>
              <para role="param">AppID – [xs:string]</para>
              <para role="text">Application to be removed</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>response</term>
            <listitem>
              <para role="text">&lt;empty&gt;</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>faults</term>
            <listitem>
              <para role="param">env:Sender - ter:InvalidArgVal – ter:UnknownId</para>
              <para role="text">The requested application ID does not exist.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>access class</term>
            <listitem>
              <para role="access">SYSTEM_WRITE</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>Activate</title>
        <para>A device supporting this service shall support this method to start an installed application. </para>
        <variablelist role="op">
          <varlistentry>
            <term>request</term>
            <listitem>
              <para role="param">AppID – [xs:string]</para>
              <para role="text">Application to be started</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>response</term>
            <listitem>
              <para role="text">&lt;empty&gt;</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>faults</term>
            <listitem>
              <para role="param">env:Sender - ter:InvalidArgVal – ter:UnknownId</para>
              <para role="text">The requested application ID does not exist.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>access class</term>
            <listitem>
              <para role="access">SYSTEM_WRITE</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>Deactivate</title>
        <para>A device supporting this service shall support this method to stop an installed application. </para>
        <variablelist role="op">
          <varlistentry>
            <term>request</term>
            <listitem>
              <para role="param">AppID – [xs:string]</para>
              <para role="text">Application to be stopped</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>response</term>
            <listitem>
              <para role="text">&lt;empty&gt;</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>faults</term>
            <listitem>
              <para role="param">env:Sender - ter:InvalidArgVal – ter:UnknownId</para>
              <para role="text">The requested application ID does not exist.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>access class</term>
            <listitem>
              <para role="access">SYSTEM_WRITE</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>Backup and Restore</title>
        <para>A device signals support for backup and restore of individual applications by
          providing the Configuration URI in the application information items (see <xref
            linkend="_AppInfo"/>). Clients can retrieve and backup the current configuration via the
          http GET method. Note that the configuration itself is an opaque blob. A backed-up
          configuration may be restored at a later time by uploading it to the device via the http
          POST method. Refer to the individual application documentation regarding support for
          restoring of configurations across devices and versions. For general error behavior of the
          restore function see <xref linkend="_Ref4595104"/>. Additionally an application may generate 
          the following error response</para>
        <itemizedlist>
          <listitem>
            <para>521 Version mismatch The application cannot restore the provided configuration.</para>
          </listitem>
        </itemizedlist>
      </section>
      <section>
        <title>Application Interface</title>
        <para>A device should provide an interface description for applications providing a programming API 
          for configuration and monitoring purposes. For these applications a device should provide a
          link via the InterfaceDescription information item as defined in <xref linkend="_AppInfo"/>. It allows
          clients to easily integrate application configuration and information retrieval. Examples for 
        interface description languages are JSON or YAML descriptions according to OpenAPI.</para>
      </section>
    </section>
    <section xml:id="_AppInfo">
      <title>Application Information</title>
      <section>
        <title>Information Items</title>
        <para>The following items may be associated to each application and can be queried either via the GetInstalledApps method or the GetAppInfo method.</para>
        <variablelist>
          <varlistentry>
            <term>AppID</term>
            <listitem>
              <para>Unique identifier of an application</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Name</term>
            <listitem>
              <para>User readable name of the application</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Version</term>
            <listitem>
              <para>Version string assigned by the application vendor</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Licenses</term>
            <listitem><para>Licenses associated with the application</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Privileges</term>
            <listitem>
              <para>Privileges assigned to the application</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>InstallationDate</term>
            <listitem>
              <para>Date when the application was installed</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>LastUpdate</term>
            <listitem>
              <para>Date when the application was last updated</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>State</term>
            <listitem>
              <para>
              Information whether the application is currently Installing, Active, Inactive or Uninstalling (see <xref linkend="_Ref469303432" />). InstallationFailed state can be provided only in AppMgmt/State event.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Status</term>
            <listitem>
              <para>Textual description of the state. In error cases this shall contain the  	error reason. </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Autostart</term>
            <listitem>
              <para>Indication whether the application automatically starts on system boot.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Website</term>
            <listitem>
              <para>Link to an internal or external website providing supplementary   	information about the application or its vendor.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Configuration</term>
            <listitem>
              <para>Optional Uri for backup and restore of the application configuration.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>InterfaceDescription</term>
            <listitem>
              <para>Optional reference to the applications interface definition.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>OpenSource</term>
            <listitem>
              <para>Optional link to a listing of related open source licenses.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>GetInstalledApps</title>
        <para>A device supporting this service shall support this command to enumerate all installed applications. This method provides only high level information on the applications for more detailed information see GetAppInfo.</para>
        <variablelist role="op">
          <varlistentry>
            <term>request</term>
            <listitem>
              <para role="text">&lt;empty&gt;</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>response</term>
            <listitem>
              <para role="param">App – optional, unbounded [Application]</para>
              <para role="text">List of applications containing its ID as well as a user readable name.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>faults</term>
            <listitem>
              <para role="text">&lt;none&gt;</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>access class</term>
            <listitem>
              <para role="access">SYSTEM_READ</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
      <section>
        <title>GetAppsInfo</title>
        <para>A device supporting this service shall support this command to retrieve detailed information about applications. The caller may provide an application ID to retrieve the information for a single application. If no application ID is provided, the device shall report the information for all installed applications.</para>
        <variablelist role="op">
          <varlistentry>
            <term>request</term>
            <listitem>
              <para role="param">AppID – optional [xs:string]</para>
              <para role="text">Optional ID to only retrieve information for a single application</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>response</term>
            <listitem>
              <para role="param">Info – optional, unbounded [AppInfo]</para>
              <para role="text">List of detailed information about the applications.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>faults</term>
            <listitem>
              <para role="param">env:Sender - ter:InvalidArgVal – ter:UnknownId</para>
              <para role="text">The requested application ID does not exist.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>access class</term>
            <listitem>
              <para role="access">SYSTEM_READ</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
    </section>
    <section>
      <title>Licensing</title>
      <section>
        <title>InstallLicense</title>
        <para>A device signaling support via the Licensing capability shall support this command to install a license on the device. The format and structure of the license string is outside of the scope of this specification. </para>
        <para>Refer to GetAppInfo for listing installed application licenses.</para>
        <variablelist role="op">
          <varlistentry>
            <term>request</term>
            <listitem>
              <para role="param">AppID – optional [xs:string]</para>
              <para role="text">Application the license shall be associated to.</para>
              <para role="param">License – [xs:string]</para>
              <para role="text">Computer readable license string to be installed.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>response</term>
            <listitem>
              <para role="text">&lt;empty&gt;</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>faults</term>
            <listitem>
              <para role="param">env:Sender - ter:InvalidArgVal – ter:InvalidFormat</para>
              <para role="text">The device cannot interpret the license either because the format is unknown or because it has invalid syntax.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>access class</term>
            <listitem>
              <para role="access">SYSTEM_WRITE</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>
    </section>
    <section>
      <title>GetServiceCapabilities</title>
      <para>The capabilities reflect optional functions and functionality of a service. The information is static and does not change during device operation.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="text">This message is empty</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">Capabilities [Capabilities]</para>
            <para role="text">Set of indicators for function groups as described above.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="text">None</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">PRE_AUTH</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The following capabilities are available:</para>
      <variablelist>
        <varlistentry>
          <term>UploadUri</term>
          <listitem>
            <para>Mandatory upload URI for applications.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Licensing</term>
          <listitem><para>Signals support for licensing of applications.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>SupportedFormat</term>
          <listitem><para>List of application formats supported by the device.</para></listitem>
        </varlistentry>
         <varlistentry>
          <term>EventTopicPrefix</term>
          <listitem><para>Optional Event Topic prefix used when delivering app events in eventservice. </para></listitem>
        </varlistentry>
      </variablelist>
    </section>
  </chapter>
  <chapter>
    <title>Events</title>
    <section>
      <title>State Change</title>
      <para>Whenever the state of an application instance changes the following property event shall be generated. <xref linkend="_Ref469303432" /> shows the possible states and their transitions.</para>
      <para>tns1:AppMgmt/State</para>
      <programlisting><![CDATA[<tt:MessageDescription IsProperty="true"> 
  <tt:Source>
    <tt:SimpleItemDescription Name="AppID" Type="xs:string"/>
  </tt:Source>
  <tt:Data>
    <tt:SimpleItemDescription Name="State" Type="ans:AppState"/>
    <tt:SimpleItemDescription Name="Status" Type="xs:string"/>
  </tt:Data>
</tt:MessageDescription>]]></programlisting>
      <para>The Status item is optional. It shall be included whenever an error triggered the state change. </para>
      <figure xml:id="_Ref469303432">
        <title>Application state chart.</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="media/AppMgmt/states.svg" contentwidth="110mm"/>
          </imageobject>
        </mediaobject>
      </figure> 
    </section>
    <section>
      <title>Events From App</title>
      <para>Based on app's internal configuration (outside the scope of onvif), app generated event can be either delivered with a standard event topic or can be delivered with prefix like "tns1:{EvenTopicPrefix}/{AppID}/{EventName}".</para>
      <para>For example, if EventTopicPrefix is notified as "AppEvent", AppID is "DetectorApp" and event name is "FaceDetection", then the topic would look like tns1:AppEvent/DetectorApp/FaceDetection. </para>
      <para>Client interested in events from installed app, can get the updated list of supported events using event service "geteventproperties" api response, whenever there is change in "tns1:AppMgmt/State" event. </para> 
    </section>
  </chapter>
  <appendix role="revhistory">
    <title>Revision History</title>
    <para />
  </appendix>
</book>