Application Packaging Standard

Last updated 14-Nov-2018

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.

Service Declaration

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 points <entry-points> used in CCP v1 auto-generated dashboards
    • Links to documents <infolinks>

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 in the CCP v1 auto-generated page as links to various views of the application UI. The Auto-generated Widgets section explains the entry point declaration in APP-META.xml.

Resource Management

APS controller MUST call a service operation to manage its resources, for example, it can call the following standard operations:

  • Provision - to provision a resource.
  • Get - to get a list of resources or details of a resource.

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 by implementing the Suspendable APS type and defining the enable and disable methods. The APS controller must call those methods to change the appropriate service status.