Table Of Contents

Previous topic

Implementation Review

Next topic

Certifying Updated Packages

Application Packaging Standard

Last updated 18-Mar-2019

Technical Review

We appreciate your desire to integrate applications with the platform. This document contains criteria that help package developers and the APS support team create packages compliant with the APS guidelines.

../../../_images/cert-step4.png

Purposes

This section provides the certification criteria for APS packages and applications. We continue to work on improving and evolving the APS certification criteria and process, therefore this document is subject to change. In order to ensure that applications are up-to-date with the APS certification criteria, every certificate has a limited validity period. Package developers are encouraged to repeat the certification whenever the requirements are updated.

Note

When you meet a reference to metadata in this document, we mean XML elements and their attributes in the APP-META.xml file as described in the Metadata Descriptor (APP-META.xml) section.

Note

You can validate your package against some of the certification requirements using the aps build or aps lint command as described in the Package Validation section.

1. Rejection policy

APS team hopes your application will NOT get in the following list containing reasons for rejecting a package. We do not want to certify packages of applications with contents similar to following:

  • Package executables or application communicates with local environment on the hosting platform in a way that can be harmful for the environment, for example, interacting with local files and registry, or trying to start or stop local services, or compromising the system security.
  • Package executables or application extends its code by downloading executable binary or script files.
  • The package or application breaks personal information (contacts, photos, phone numbers, payment method properties, etc.) convention by publishing personal or company data without corresponding permission.
  • The package or application includes hatred or violence content based on racial, ethnic, national, linguistic, or religious discrimination, or based on a person’s gender, age, or sexual orientation.
  • The package or application contains content or functionality that encourages, facilitates or glamorizes illegal activity, extreme or human right violations in the real world.
  • The package or application contains or references to obscene or pornographic content.

2. Application, vendor, and packager

An application package must contain general information about the application, its vendor (ISV), and the packager.

2.1. Application home page

Package metadata must contain a URL of the application home page (application/homepage metadata element) that contains application details.

2.2. Vendor name and home page

Package metadata must contain both the complete application vendor name and a URL of the home page (application/vendor/name and application/vendor/homepage metadata elements).

2.3. Packager name and home page

Package metadata must contain both the complete packager name and a URL of the home page (application/packager/name and application/packager/homepage metadata elements).

3. Application presentation

3.1. Application summary

Package metadata must contain a one-sentence summary of the application (application/presentation/summary metadata element) exposing clearly the purposes of the application. Application summary should not contain line feed characters and should not be longer than 256 UTF-8 characters. When a package is published the APS catalog, its application summary is displayed in the list of packages.

3.2. Application description

Package metadata must contain a one-paragraph description of the application (application/presentation/description metadata element). The application description must be not shorter than 256 UTF-8 characters and not longer than 1024 UTF-8 characters. This field is displayed in the APS catalog, when the package is opened for viewing details.

3.3. Icons

In accordance with the Package Structure, APS JS API, and Application Icon Design, custom icons of an application can be displayed in various parts of user panels. The requirements to icons in different types of user panels (UX1 and CP) are different.

3.3.2. Custom tiles in UX1

For a custom tile in UX1, an application icon should comply with the following recommendations:

  • File format - SVG or PNG with mono-colored elements
  • File size - less than 35 KB
  • Image size - up to 250x250 px

3.3.3. Auto-generated screens in CP

The icon format for auto-generated screens in CP should be one of the following MIME types:

  • images/gif (not animated)
  • images/jpeg
  • images/png
  • images/svg

The image dimensions should be 64x64 pixels.

3.3.4. Custom buttons in CP

An application can add icons to its own buttons in a view plugged into CP. The icon format should be one of the following MIME types:

  • images/gif (not animated)
  • images/jpeg
  • images/png
  • images/svg

The image dimensions should be 16x16 pixels.

3.4. Screenshots

A package must contain a screenshot of an application view (application/presentation/screenshot metadata element). The screenshot must be 640 pixels wide. The image should be of one of the following MIME types:

  • images/jpeg
  • images/png

3.5. Full change log

A package must contain change log for all released versions of the package (application/presentation/changelog metadata element).

3.6. Categories

Package metadata must contain information about the categories the package belongs to (application/presentation/categories metadata element). You can find predefined categories in the APS Application Categories section of the APS Specification.

4. License

A package must contain information about the application license.

4.1. End-user license agreement

A package must contain the license agreement text or a link to the license agreement for the services aimed for customers and end users (application/license-agreement metadata element).

4.2. End-user license type

A license agreement must be characterized as free or commercial (by using an appropriate free or commercial element).

5. Services

5.1. Resource definitions

A package must define at least one APS type and corresponding service used for provisioning resources for customers. The resources must present provisionable items on the service and can be provisioned in the customer context through the platform Application Service resource class or in the provider context through the platform Application Service Reference resource class.

5.2. Provisioning scripts

The provisioning scripts must perform the provisioning, configuration, upgrade, and de-installation of an application instance and application services.

The application packager must provide a script to make deployment of provisioning scripts on an endpoint host fully automated as described in Application Deployment. If any manual steps are required, they should be explained in detail as specified in the 15. Documentation section.

5.3. Service summary

Every declared service must have summary information (application/service/presentation/summary metadata element). The service summary should not contain line feed characters and should not be longer than 256 UTF-8 characters.

5.4. Domains

If the application works with domain names, it must support the standard domain naming conventions including IDN (internationalized domain names) as described, for example, at the Domain name site.

6. JSON schema

6.1. Compliance with APS specification

Properties, operations, and structures used in *.schema files must comply with the restrictions documented in Type Definition.

6.2. Array of structures

In a case an APS type needs to have a long array of structures, the recommended way is to define a separate APS type instead of a structure and then specify Relationship between the two APS types. This is caused by the limit on property size.

7. Strings encoding

The properties of type string must be encoded in UTF-8.

9. Provisioning logic

9.1. Create, read, update, and delete operations

The package scripts and the multitenant application must correctly perform the create, read, update, and delete (CRUD) operations over all application services defined in the package.

9.2. Enable and disable operations

If the enable and disable operations are defined in the package, the package scripts must correctly enable and disable the services in application subscriptions.

9.3. Subscription management

9.3.1. Coexistence with other subscriptions

A subscription that includes the application resources must be able to coexist with other subscriptions belonging to the same account.

9.3.2. Multiple subscriptions with application resources

If the APS application allows 2 or more subscriptions, all those subscriptions must co-exist under one account without interfering with each other. In a case when only one subscription is allowed per customer, the application must notify its subscribers about this restriction.

9.3.3. Subscription removal

On application subscription removal in the hosting system, the package scripts must correctly remove corresponding objects from the application.

9.4. Application instance removal

The unprovision() function of the resource implementing the APS Application type must remove completely the APS application instance.

9.5. Application and package updates

If the package does not intend to update any other packages, the application name and application ID must be unique in the APS development portal. If the package is an update of some packages stored in the APS development portal, its <version><release> combination in the package metadata must be higher compared with the previous packages and it must be declared as upgrade or patch.

The package must be able to update application instances provisioned from the previous certified version of the package.

9.5.1. Upgrades

If an application supports upgrades from previous versions this must be declared in the package by the application/upgrade/@match element and the appropriate upgrade operation must be implemented.

9.5.2. Patches

If an application supports updates from previous versions in the patch mode, this must be declared in the package by the application/patch/@match element.

9.6. Integration with the platform service users

9.6.1. Strong relations with service users

Any application that assigns services per seat, versus per instance, must declare a strong relation of these services with the Service User type or another type derived from it.

9.6.2. Service user wizard

To provision and unprovision services for service users, the application should integrate with the Service User Wizard.

9.6.3. Service user UI

The application must provide UI for service users to view and manage the assigned services in their control panel (MyCP).

9.7. Performance aspects

When designing the APS application connector, keep in mind the following performance-sensitive requirements.

9.7.1. Data flow

The application should minimize large data fetches as they incur high server load. For example, requesting a particular account resource is safe, while requesting all tenant resources can overload the system. Always apply a sane limit(…) clause when requesting mass data, and do small batch processing instead of using huge batches. Batches with 100-500 resources are usually safe. Larger batches can take significant time and memory, and even fail due to timeout.

The application should minimize ‘complex’ queries which include ‘joining’ several object collections, filtering, and sorting data by ‘joined’ properties. When applied on large systems, these operations can be very slow. Instead, application can split a complex request into several simpler requests and do the logic on its side, or de-normalize data, or keep some data cached locally.

9.7.2. Custom operations

The provisioning or update of resources based on slow backend processes must be handled in the asynchronous mode. The same is required for slow custom operations.

To allow the application to access only the resources of the current customer, the recommended way for an application to operate its resources is to impersonate the current subscriber in the respective operation as explained in Security Context. This is important from both, security and performance perspectives.

9.7.3. Notifications

On-screen notifications consume database and cause UI refresh. That is why, applications should send only important on-screen notifications to the users.

9.7.4. Events

The application should avoid or minimize the number of subscriptions on APS events when the event source is an APS type, not a resource.

9.7.5. Upgrades

Updates in an APS type used to create huge number of resources (thousands or more) can cause the substantial delay of the upgrade process. At least, all those resources must be rebound to the new version of the APS type.

10. Functionality of counters

If resource counters are defined in the package, they must comply with the following requirements:

  • On a request from the APS controller, the application must return correct resource usage data as fast as possible, for example, by using caches, because resource usage collection is a mass procedure and has time boundaries.
  • Counters used in the pay-as-you-go scenarios must be additive, that is return monotonously increased values. Overflow must be handled as for unsigned integer (ULONG 64), that is the counter value is cycled through zero.

11. Application security

11.1. Endpoint security

APS application endpoint must be accessed through the HTTPS protocol. It must allow connections from the APS controller only.

11.2. Security of provider- and reseller- settings

Application must ensure that provider-level and reseller-level settings are not accessible in customer and anonymous contexts.

11.3. Processing of security sensitive data

Application UI scripts must not use plain text to operate security sensitive data such as passwords, API keys, and data used for API authentication. The exception is the very first time when the data is entered. It should not be possible to get security sensitive data from a web browser.

11.4. Password requirements

Application authentication system must support the following requirements to passwords:

  • Any symbols in a password are allowed.
  • Password length up to 256 symbols is allowed.
  • All application properties used for passwords should be encrypted.

12. Application logs

Package scripts must log application service operations at least in the APS application connector as specified in the 15.1.1. General requirements section. In case of an error, the log record must precisely indicate the issue and suggest a solution. When reporting about an error, the log record must contain at least the following data:

  • Date and time when the error was detected
  • Name of the script function and file name where the error was detected
  • Input data and environment that caused the error

13. APS PHP Runtime

For the APS application connectors that use the APS PHP Runtime library, the following requirements apply.

13.1 Library Version

Applications have to function properly with the latest released version of APS PHP Runtime. Certification is always performed with the latest released version of the PHP Runtime Library.

14. Custom user interface

Starting with platform version 7.0, we encourage the APS application UI developers to build their custom UI on the newest user panel, that is on the UX1 basis due to its substantial advantages over the older CP.

14.1. Compliance with different browsers

Custom user interface (UI) must work correctly in provider and customer control panels using different web browsers: Internet Explorer starting from version 10, latest versions of Firefox, Chrome, and Safari.

14.2. Functionality of user interface

In application subscriptions, the UI must display correctly all views as described in the package and application documentation.

14.3. User interface screen sanity

The UI screens must be reasonable, rational, and errorless. It means:

  • User navigation should provide access to all views as declared in metadata.
  • All declared views and control elements must be functional.
  • Labels on control elements must correspond to the activity they trigger.
  • Control elements must be activated and deactivated or appear and disappear in accordance with the configuration and consumption logic as described in the deployment documentation of this package.
  • The views should not generate error messages on the screen indicating bugs in the UI or provisioning code.

14.4. Bug free user interface

Custom UI must be validated with an open browser debugger to catch possible error or warning messages. The JavaScript code must be free of such messages when verified on deployment, provision, and consumption of the services as described in the package and application documentation.

14.5. JavaScript validation

The following recommendations and restrictions must be followed to reduce the chance of creating insane code.

14.5.1. General restrictions

Use the APS JS SDK to create, update, and remove JavaScript (JS) modules, widgets, and corresponding HTML DOM nodes. In the certified APS packages, the following operations in HTML/JS files are prohibited.

  • Inclusion and usage of custom CSS classes by adding separate files or inline attributes as in the following prohibited snippets:

    <head>
    <link rel=”stylesheet” href=”../css/default.css” type=”text/css” media=”all”/>
    …
    </head>
    <style>
    .syncButton{
    display: inline-block;
    }
    …
    </style>

  • Direct processing of CSS classes in a widget using the class or style property as in the following prohibited snippet:

    [“aps/ToolbarButton”, {
    “class”: data.apsID,
    label: _(“Update Total Qty”),
    …
    }]

  • Usage of private fields and methods of APS JS SDK controls whose names start with _

  • Disabling the escape of the HTML code by means of the escapeHTML property

  • Extension of the APS JS SDK widgets as in the following prohibited snippet:

    [“aps/TextBox”, {
    id:”licAdd_” + data.buttonName + data.apsID,
    label: _(“MS Licenses”),
    value: data.quantity,
    value2: data.buttonName+data.apsID // Widget is extended by this property
    }]

    It is allowed to extend only the aps/output widget as in the following example:

    [“aps/Output”, {
    vps: vpses.data.length,
    cpu: cpu,
    ram: ram,
    disk: disk,
    content: “VPSes: ${vps}, CPU: ${cpu} cores, Memory: ${ram} MB, Disk: ${disk} GB”
    }]

  • Declaration of custom widgets that inherit any APS JS SDK widgets, as in the following prohibited snippet:

    declare(TextBox, { … });

  • Direct usage of HTML code in JavaScript and direct modification of APS JS SDK generated HTML code by creating, deleting, or modifying DOM nodes by means of the innerHTML or other DOM node properties

    For example, instead of

    domStyle.set(
    registry.byId(‘editAdminFieldset’).domNode, ‘display’, ‘block’
    );

    use

    registry.byId(‘editAdminFieldset’).set(‘visible’, true);

    or, for UX1, use

    this.byId(‘editAdminFieldset’).set(‘visible’, true);

14.5.2. HTTP Requests to External Services

If an application needs to send an HTTP request to an external application either to open the application view, or to login, or just to send some data in the HTTP request use the officially recommended externalHttpRequest method. The use of the following methods for the same goal are prohibited:

  • Any access to DOM elements outside the current IFrame, such as window.top and window.parent.
  • Access to global variables top and parent.
  • Creation of and access to cookies.

14.5.3. JavaScript code validation rules

JavaScript and HTML codes in the package must pass validation performed by aps build or by aps lint commands. Alternatively, use jshint, APS fiddle , or jslint against the following criteria:

  • Prohibit variable use before definition
  • Prohibit declaration of variables that are not used in the code
  • Require capitalization of all constructor functions, for example, new F()
  • Prohibit trailing white spaces
  • Prohibit debugger statements, for example, browser breakpoints
  • Prohibit function eval()
  • Prohibit missing semicolons when it is omitted for the last statement in a one-line block
  • Prohibit unsafe line breaks, for example, return [n] x without semicolons
  • Prohibit usage of the __iterator__ property
  • Prohibit the deprecated __proto__ property
  • Prohibit definitions like new function () { … }; and new Object;
  • Prohibit the use of this in a non-constructor function when the strict mode is on

When working with jshint, use this jshint configuration to validate your code against the criteria in the above list.

14.6. Performance aspects

To avoid severe effect on the overall platform performance, pay attention to the Frontend Connections and Best Practice when developing the UI.

14.6.2. Data flow

Follow these requirements to the UI design:

  • At all costs avoid calling custom methods or fetch large volumes of data on frequently-displayed views, such as view plugins plugged into the home dashboard and user list.
  • Carefully design navigation and views plugged into CP placeholders to minimize data requested.
  • Request large non-critical data asynchronously and only if necessary.
  • Pay attention how many resources a request can involve, and remember about the default limit of 1000 items per result. A view must request no more resources than it is going to process. For this, it must use the limit(…) clause when requesting mass data.
  • Avoid the use of APS types with global or public access specified in the Security Roles section unless this is a business requirement.

Pay attention that typically not more than 6 HTTP requests (depends on the browser) can run in parallels. The 7th request will wait for the release of a connection.

14.6.3. Loading state

In the onContext method of a view used in UX1, ensure the widgets are visible only after all asynchronous operations are completed. Before that, the view must show the “Loading…” state.

15. Documentation

The package must contain the guidelines for deployment of the application on the platform. Optionally it can have the subscriber guidelines.

Deployment documentation must provide comprehensive description of package deployment as required in the following sections.

Note

The instructions must not contain any license-sensitive information, such as login and password or a license key, except for trials.

15.1. APS connector deployment

15.1.1. General requirements

The deployment documentation must contain instructions for setting and supporting the APS application connectors.

  • Requirements to hardware: CPU, RAM, disk space
  • Requirements to OS and additional packages specifying exact versions of OS and third-party packages the application was tested with (for example, the application was tested on: CentOS 6 with PHP 5.3 and CentOS 7 with PHP 5.4)
  • Instructions on getting license information (API credentials, keys, and other.) if it is required for deployment and provisioning
  • Step-by-step setup instructions
  • Instructions on verification of the APS connector
  • Path to application log files and instructions on the data that should be collected from the logs and sent to the application support team (ISV) in case of failure

15.1.2. Docker based deployment

Starting with platform version 7.1, the recommended way of APS connector deployment is its installation from a Docker image. The Get Started document explains the creation of a Docker image on the public Docker hub.

15.2. Product deployment

15.2.1. General requirements

The deployment guide must provide specifics of preparing the application for sale and provisioning:

  • Global parameters for installation of an application instance or where to get them from
  • Instructions for setting global reference objects, known as service profiles, offers, or samples
  • Instructions for setting resources, service templates, service plans, and other objects as appropriate for the hosting platform

15.2.2. Product initialization wizard

Starting with platform version 7.1, the recommended way of the product deployment is Using Initialization Wizard. The Deployment Configuration document explains the details of the product deployment configuration. The Docker Image section of the Get Started procedure provides a simple example of adding a deployment configuration to a package.

15.3. Subscriber guide

In cases, when application resource configuration at the subscriber’s side is not evident, the documentation must provide specifics of this process:

  • Requirements to the environment, for example, a subscriber should have hosted domains, service users, and mailboxes
  • Step-by-step setup instructions
  • Instructions on verification of application service functionality

15.4 Documentation of required Platform Open API methods

In cases when the application requires the use of Odin Automation Open API methods, all required methods and reasoning for their use must be provided.

Note

In cases when functionality achieved with Open API methods can be achieved using APS API methods, the application must use corresponding APS API functionality.

16. Files naming

In an APS package, file names must comply with the File Naming convention.