To create and test an application package in compliance with APS, perform the following steps:
Note: it is intended that you already have a working application.
Application may dictate type of environment the Controller should provision it to in clear. On the other hand, the Controller may select an environment basing on application services hardware and software requirements. One may single out the following types of hosting environment:
Selecting the provisioning model application vendor should consider the level of application management by Controller and application services hierarchy. Namely, one should correctly map application services on application. One may single out the following models of service provisioning:
Note: both models can be implemented for shared environment and for dedicated one as well.
An application may comprise main module and additional ones. The main module represents core functions, whereas additional modules provide extra services. For example, a content management application may come as a main module, and the skins or localizations may be offered as add-ons.
If your application has such additional modules, consider packaging them individually like a general package with dependency to their main module. In other words, metadata of packaged add-ons must reference to their master package, so the Controller could check whether the package is really an additional module to an application installed in hosting environment and its version meets condition (if any) in add-on's metadata file.
For details on packaging add-ons, refer to the 5.1.5. Master package reference section of the Specification.
In general, an application purpose is to provide services to end-users. Application services hierarchy should reflect order of application services provisioning and level of application services management by Controller.
For example, let's consider multi-tenant application. The top-level application service represents a tenant. Under top-level service an application context is declared (second-level service) that is provisioned inside of the tenant. Then one may declare a number of application features (third-level services). Another way is to declare users and specify features for a user.
APS supports licensing applications by means of license keys. Each application instance or service may require license keys. To get keys, a well-formed license request should be send to respective authority. After the license is issued it is installed to the application.
If your application requires license to be installed, you should specify this in its metadata file. A special script should perform all involved operations, like querying application, installing and removing license.
For details on license requirement declaration, refer to the APS Licensing Aspect document.
Your application may utilize various scripting languages, specific server modules, databases, mailboxes, DNS records in application domain and the like. Application technologies form the list of requirements to be satisfied to provision application. In general, requirements usually request some resource to be allocated or specific configuration to be performed.
A Controller can handle these requirements as qualified technologies – software, resources (e.g. databases, mailboxes or DNS records) or executable code described in the aspect included in the Specification. For details on aspects that describe qualified technologies, refer to the 8. Common aspects section of the Specification.
Note: If the application uses non-qualified technologies, write an aspect for each such technology and make it public. You may then submit a request to extend the Specification (recommended scenario), or otherwise include the information into the package release notes. This will help control panel developers to configure Controllers to provision the package properly. For details on what data should be included in an aspect, refer to the 7. Points of Extensibility section of the Specification.
Tip: For common understanding, please, use the terms given in the Specification.
Your package metadata may include details and settings of the application interface. If an application is multi-tenant, for example, it should meet requirements of a number of tenants that use this application for absolutely different purposes. In other words, the more settings you declare for an application, the more flexible it becomes. This way you may set up automated generation of setting values ensuring their uniqueness within the required scope. Some settings may be prefilled automatically with a Customer's login, password, email or domain of the application without requesting the data from end-user. For details, refer to the 5.1 Common Application Properties, 5.2 Services and 5.2.5 Service Settings sections of the Specification.
Tip: For common understanding, please, use the terms given in the Specification.
Content delivery method defines the way application files are deployed to hosting environment. For now APS allows using the following methods:
Each package must contain a well-formed XML file (called
APP-META.xml) that includes all the metadata required to manage the application. Metadata file includes application common properties like name, version, description as well as list of application services and resources required. The XML presentation of the metadata is described by the RELAX NG schema. Some schema elements are defined by aspects. It means that you must use aspects when adding the elements. For details on metadata file and its elements, refer to the 4.3. Metadata File and 5. Metadata Descriptor sections of the Specification.
The Specification defines the following provisioning methods: URL mapping and configuration script. These methods are not mutually exclusive and are not interdependent. Thus, both of them can be declared for a service provisioning. URL mapping configures access to service through web, and configuration script performs service installation. The selection of method is determined by the hosting environment which is required for the Application. APS Package may contain multiple sets of requirements to meet the environment in case either set of requirements may not be satisfied. For details on provisioning methods, refer to the 5.3. Service Provision Methods section of the Specification.
You may develop a number of scripts that serve different purposes:
disablearguments. Verification script is invoked twice: during installation and reconfiguration of an application. Initially, it is executed prior to prompting a user for setting values. At this stage the application settings receive auto-generated and default values. Second time it is invoked to validate the submitted settings values. If the return value is not zero, the script is invoked again. For details on verification script invocation, its arguments and environment variables, refer to the 5.3.3. Verification Script section of the Specification.
The script should be able to back up all sensitive application data to file specified and all involved resources, if required; restore backed up data to location specified.
Script-writing language must be a qualified technology defined in the Specification and must be declared in the metadata file. Application data is passed to scripts by means of environment variables. The variables contain all information about resources and settings of application instance you defined on the 7th step of the instruction.
Scripts execution is not always going without a hitch. Consider making script output structure matching XML schema defined in the Specification. A Controller catches such structured output, reads instructions and quickly reacts, in case some errors occur. These instructions may include identifiers of settings with erroneous values accompanied by localized error messages or problems detailed descriptions as well as warnings and errors related to the requirements. For details on forming structure of script output, refer to the 184.108.40.206 Configuration script output section of the Specification.
After necessary scripts are implemented, update metadata file with scripts declarations, according to the Specification. For details, refer to the 5.3. Service Provision Methods and 8. Common Aspects sections of the Specification.
Each package must contain a well-formed XML file named APP-LIST.xml in the package root directory. The file must contain the list of all files in the package, but itself. Size in bytes and SHA256 digest value must be specified for each file in the list. This file may be digitally signed by a packager or certification authority.
Presence of packager signature assures package integrity and helps to prevent counterfeit. If a package is signed by certification authority, for example APS organization, the package contains a certificate as well.
For details on listing structure, refer to the 4.4 Package contents listing and 6. Package contents listing sections of the Specification
Package structure must comply with the content organization requirements declared in the Specification. Check your package structure before archiving and update the application content if needed. Make sure, that APP-META.xml and APP-LIST.xml files are well-formed and contain all necessary information about an application.
For details on the requirements, refer to the 1. Introduction, 4. Basic Package Format and 6.5. Additional scripts sections of the Specification.
The package should be a ZIP archive with the
.app.zip extension, according to the 4.1. File format section of the Specification.
The package validation may comprise two steps: checking whether package structure conforms to APS and then checking whether package is properly managed by Controllers. Package structure can be validated using APSLint command-line utility. If the application package is APS-compatible, then you can check how it is managed by Controllers. To do this, examine the Controller operations that require application package data. For details, refer to the Validating Application Package chapter further in this guide.
Please send us your feedback on this help page