Previous topic

Application Updates

Next topic

Backend API

DOCUMENTATION
Last updated 18-May-2016

Application Services

An application consists of one or more services. A service is a factory for resources of a specific Type Definition provided by the application.

In the simplest case an application provides just one service - which covers the whole application functionality.

Services are declared using the service section of Metadata Descriptor (APP-META.xml):

 <application>
     ...
     <service id="organization">
         <presentation>...</presentation>
         <schema path="..."/>
         <code engine="php" path="scripts/organization.php"/>
     </service>

     <service id="mailbox">
         ...
     </service>
     ...
</application>

Each service is responsible for production of resources of one type, which is identified in the service schema. The schema file is located in the package at a path provided in the path attribute of the schema element, see Type Definition schema for details.

A service may define:

  • Code which will handle service operations

  • Presentation for resources
    • resource entry point(s)
    • custom user interface

Service Summary

A service SHOULD be described by brief summary information.

<application>
    ...
    <service id="email">
        ...
        <presentation>
            <name>Email</name>
            <summary>Electronic mail address with mailbox</summary>
            <icon path="images/email.png"/>
            ...
        </presentation>
        ...
    </service>
    ...
</application>

Entry Points

The packager may declare entry points to be used for a given service. When a Controller provisions a service with entry points, it MAY provide a user with the choice of which entry points to show in the control panel interface and where.

<presentation>
    ...
        <entry-points>
            <!-- Just a link without icon -->
            <entry dst="/info">
                <label>Information service</label>
            </entry>

            <!-- Link with icon -->
            <entry dst="/guest">
                <label>Guest view</label>
                <description>View the gallery as user not logged in</description>
                <icon path="images/icon-guest.png"/>
            </entry>
       </entry-points>
    ...
</presentation>
  • entry/@dst attribute of an entry point may contain an absolute or relative URI of the entry point. Templates conforming to URI Templates are allowed. For relative URIs, an absolute URL will be generated when an entry point is being displayed, pointing to the base URL of the application + URI of the entry point.

  • entry/@method attribute allows setting a GET or POST HTTP request to be used to access the HTTP entry point. GET is assumed by default.

    <presentation>
        ...
            <entry-points>
                 <!-- Link with submission of a login form -->
                <entry dst="/admin" method="POST">
                    <label>Administrative interface</label>
                    <icon path="images/icon-admin.png"/>
                    <variable name="username" class="login">admin</variable>
                    <variable name="password" class="password" value-of-setting="admin_password"/>
                </entry>
           </entry-points>
        ...
    </presentation>
    
  • icon/@path attribute MUST contain a full path in the archive to the icon file. The icon SHOULD be a 64x64 pixel image in the PNG format using alpha transparency. The JPEG and GIF formats MAY be used as well, but their use is discouraged.

  • label and description attributes specify a shorter and a longer strings describing the entry-point link. When displaying the entry point, a Controller SHOULD use the provided label, description and icon.

  • The entry/@class attribute MAY be used to inform a Controller about the entry point designation. The Controller MAY use this information for displaying the entry point. The Controller MUST ignore unknown entry/@class and treat such entry point as being without the explicit class specification. An application MAY declare several entry points with the same class attribute.

    This attribute has the following predefined values:

    • control-panel - an entry point leads to the service control panel

    • login - an entry point leads to the login page

    • frontpage - an entry point leads to the application’s front page

    • check - an entry point leads to a page that displays application health information

      <presentation>
          ...
              <entry-points>
                  <entry class="control-panel">
                      ....
                  </entry>
              </entry-points>
          ...
      </presentation>
      

An entry point MAY declare request variables to be specified when a user clicks the entry point in the control panel interface. Variable values may be taken from actual service settings using the value-of-setting attribute or explicitly specified as the variable element value. If the specified setting has an empty value, the variable element value MUST be used.

These variables are also used for URI Templates expansion. Variables with duplicate names are allowed and, if present, MUST be used for arrays representation as defined in the URI Templates ‘prefix’ operator (4.4.4), ‘suffix’ operator (4.4.5) and ‘list’ operator.

If the POST request method is used, variables MUST be submitted using the application/x-www-form-urlencoded encoding. In case of the GET method, variables must be submitted as specified by the URI template syntax.

If a URI template is not used, variables are submitted using the application/x-www-form-urlencoded encoding. Specifying any other method value means that a controller SHOULD call that resource method prior to opening the entry point.

The variable/@class attribute MAY be used to inform a Controller about the request variable meaning. The Controller MUST ignore unknown variable/@class and treat such variable as a variable without the explicit class specification.

An application MAY declare several variables with the same class attribute. The Controller SHOULD provide equal values for variables with the same class.

Resource Provision

APS controller MUST call Provisioning Resources to provision resources.

Service Code

A service may be provisioned with help of appropriate methods of the application class defined in the code section. These methods will be invoked during application service provisioning, unprovisioning, updating and reconfiguration.

Configuration scripts MUST reside in the ./scripts directory in the package root directory. The name of a configuration script is specified with the script attribute.

A configuration script MUST declare the programming language it is written in using the engine attribute. The environment resource will use an appropriate interpreter or framework to run the code.

During the configuration script’s execution, the working directory MUST be set to the actual location of the script. All content of the scripts directory MUST also reside in the script’s current working directory.

Details of the Application API are covered in Application.

Application Update

When an application is updated, the script of the new application version is invoked as:

void upgrade(string old_version, string old_release)

where <old_version> is the old version, and <old_release> is the old release of the application being upgraded. At the moment of invocation, all resources needed by the new version of application MUST be already allocated.

Enabling/Disabling Service

A service MAY provide an ability to manipulate the service status by enabling and disabling the service. A service which status is disabled MUST NOT serve its users or operate on behalf of the service owner. The service code MUST declare the ability to manipulate the service status with the enable and disable methods. In this case, the APS controller MUST invoke these methods as:

void enable()
void disable()

to make the appropriate service status changes.