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.
In this document:
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.
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:
An application package must contain general information about the application, its vendor (ISV), and the packager.
Package metadata must contain a URL of the application home page (application/homepage metadata element) that contains application details.
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).
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).
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.
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.
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.
For a custom tile in UX1, an application icon should comply with the following recommendations:
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.
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.
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
A package must contain change log for all released versions of the package (application/presentation/changelog metadata element).
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.
A package must contain information about the application license.
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).
A license agreement must be characterized as free or commercial (by using an appropriate free or commercial element).
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.
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.
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.
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.
Properties, operations, and structures used in *.schema
files must comply with the
restrictions documented in Type Definition.
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.
The properties of type string
must be encoded in UTF-8.
It must be possible for a user to access all declared application entry points.
The application may declare entry points to be used in the CP auto-generated page as links to
various views of the application UI. Follow the Auto-generated Widgets section that explains the entry point declaration
inside APP-META.xml
.
The package must have a valid infolink to the support service site in the
root service declaration (application/service/presentation/infolinks/link[@class="support"]
metadata element).
The package must contain the provider deployment guide and optionally subscriber guide. The root service of the application package must declare at least one infolink that points to the deployment document (application/service/presentation/infolinks/link[@class=”deployment-guide”] metadata element).
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.
If the enable and disable operations are defined in the package, the package scripts must correctly enable and disable the services in application subscriptions.
A subscription that includes the application resources must be able to coexist with other subscriptions belonging to the same account.
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.
On application subscription removal in the hosting system, the package scripts must correctly remove corresponding objects from the application.
The unprovision()
function of the resource implementing the APS Application type must remove
completely the APS application instance.
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.
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.
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.
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.
To provision and unprovision services for service users, the application should integrate with the Service User Wizard.
The application must provide UI for service users to view and manage the assigned services in their control panel (MyCP).
When designing the APS application connector, keep in mind the following performance-sensitive requirements.
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.
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.
On-screen notifications consume database and cause UI refresh. That is why, applications should send only important on-screen notifications to the users.
The application should avoid or minimize the number of subscriptions on APS events when the event source is an APS type, not a resource.
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.
If resource counters are defined in the package, they must comply with the following requirements:
APS application endpoint must be accessed through the HTTPS protocol. It must allow connections from the APS controller only.
Application must ensure that provider-level and reseller-level settings are not accessible in customer and anonymous contexts.
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.
Application authentication system must support the following requirements to passwords:
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:
For the APS application connectors that use the APS PHP Runtime library, the following requirements apply.
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.
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.
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.
In application subscriptions, the UI must display correctly all views as described in the package and application documentation.
The UI screens must be reasonable, rational, and errorless. It means:
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.
The following recommendations and restrictions must be followed to reduce the chance of creating insane code.
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:
Direct processing of CSS classes in a widget using the class
or style
property
as in the following prohibited snippet:
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:
It is allowed to extend only the aps/output
widget as in the following example:
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
use
registry.byId(‘editAdminFieldset’).set(‘visible’, true);
or, for UX1, use
this.byId(‘editAdminFieldset’).set(‘visible’, true);
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:
window.top
and window.parent
.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:
When working with jshint, use this jshint configuration
to validate your code against the criteria in the above list.
To avoid severe effect on the overall platform performance, pay attention to the Frontend Connections and Best Practice when developing the UI.
Follow these requirements to the UI design:
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.
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.
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.
The deployment documentation must contain instructions for setting and supporting the APS application connectors.
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.
The deployment guide must provide specifics of preparing the application for sale and provisioning:
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.
In cases, when application resource configuration at the subscriber’s side is not evident, the documentation must provide specifics of this process:
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.
In an APS package, file names must comply with the File Naming convention.