Meta Declaration

The APP-META.xml file must define general data about the application and declare its main components.

General Data

General data presents an application in the Application Catalog and in the provider control panel (PCP).

• Assign an APS application ID by the id element in the form of URI that must be unique among all packages published in the Application Catalog and imported to an APS-compatible platform.

  Note

  Once you started using the id for an APS application published in the catalog and installed on some platforms, do not change it unless you wish to clone the application to another one.

• Enter the application name using the name element.

• If necessary, change the package version by means of the version and release properties used together to specify a unique APS package (APS application) version. Usually, the version follows the version of the integrated application, and the release is the internal property of the APS application that changes more often than the application version. For example, if your application current version is 5.0.1, start with version=5.0.1 and release=0.

• In the vendor section, specify the properties of the application owner.

• In the packager section, specify the properties of yourself or your company whoever is responsible for the APS integration of the application.

Generally, the upgrade section is required not during the development, but rather in the application upgrade process. However, even during the development steps, you may need to improve the APS application and increase the package release. In this case, you can add temporarily the section that allows any upgrades:

<upgrade match="version=ge=1.0, release=ge=0"/>

This allows you to upgrade any version higher than 1.0.0 to any newer version.

Navigation in UI

In accordance with the scenario, only customers will need to manage the application services.

In this project, let us consider the following UX (user experience) design:

• Declare a custom UI navigation tree plugged into UX1, that is to the http://www.parallels.com/ccp/2 placeholder. Customers will use it to view a list of servers and to run the editor to update a server profile.
• Split the server creation process into two steps. For this, use a custom wizard with two views, one to configure the VPS properties and the other to overview those properties and to confirm the VPS provisioning.

Navigation Tree

A navigation tree may contain an intermediate level of navigation items that, in turn, contain views.

In the considered scenario, a customer needs UI views for the following typical operations:

• View the list of provisioned resources in the form of a grid.

  The grid shows the main properties of the resources and allows the subscriber to start some operations over them, such as edit, delete, or change the state of the selected resources.

• Edit a selected resource.

Every view, typically, contains one or more navigation controls that allow a user to cancel the current operation or move forward/backward to another view in the chain of views or finish the operation.

Any navigation element (tree, item, or view) can declare navigation variables that help you get some resources in the views. Typically, your views will need the following resources:

• The management context - it allows a view to recognize the current subscription since the context resource is a singular subscription resource lined with the subscription. That is why you should declare a variable getting this resource at the navigation tree level.
• The vps resource - the edit view will need it to start editing the VPS selected in the servers view. You should declare a variable in the edit view that will get the selected VPS.

Server Creation Wizard

A wizard is declared inside an item similar to a view. In addition, it must contain a declaration of a placeholder to plug views into.

Combined Navigation Structure

With two navigation items and all the views and the wizard mentioned above, the tree will look as follows:

Keynotes:

• In the UX1, a customer will find the “VPS Management” navigation tree with two items in it. The first item opens the servers view with the list of VPSes, and the second one opens the wizard for creating a new VPS.
• The servers view shows a list of VPSes and provides some action buttons. The New button calls the vps-wizard.
• When a customer clicks on a VPS, the respective handler must call the server-edit view to start editing the VPS properties.
• The server-new-1 and server-new-last views must plug into the wizard. A customer will navigate between the views using the Prev and Next buttons. In the last view, the Submit button allows to start provisioning of a new VPS.

The demo project illustrates the declaration of the navigation tree as presented in the above diagram.

Services

The resource model contains three APS types. Each of them requires declaration of a service. In a service declaration, you need to specify a source file that contains the APS type definition and an executable file that defines the service management (provisioning) logic. In case of using the APS PHP framework on your endpoint host, the best way is to define both parts in one PHP file. The following example illustrates the vpses service declaration:

<service id="vpses">
   <code engine="php" path="scripts/vpses.php"></code>
   <presentation>
      <name>Virtual Private Server</name>
      <summary>Cloud virtual private server</summary>
   </presentation>
</service>

The code element specifies that the scripts/vpses.php file declares the APS type and defines the service provisioning logic.

Note

Typically, we assign a name in plural form to a service, for example, vpses, and a name in singular form to the respective APS type, for example, vps. The reason is that a service is a factory of many resources.

Continue Your Demo Project

This section continues the demo project started in the previous step.

Enter General Application Data

Fill in the empty general elements in your initial APP-META.xml file following this example:

<id>http://aps-standard.org/samples/vpsdemo</id>
<name>Basic VPS Demo</name>
<version>1.0</version>
<release>0</release>
<homepage>http://doc.apsstandard.org/apps/proc</homepage>
<vendor>
   <name>Your team name</name>
   <homepage>http://dev.apsstandard.org/</homepage>
</vendor>
<packager>
   <name>Your team name</name>
   <homepage>http://dev.apsstandard.org/</homepage>
</packager>
<presentation>
   <summary>Simplest multi-tenant application</summary>
   <description>This is a demo application to demonstrate how to develop APS apps step by step.
      It also shows how to use GRID column types and filters.
   </description>
   ...
</presentation>
...
<upgrade match="version=ge=1.0, release=ge=0"/>

Note

The <upgrade> section must be below the <license-agreement> section.

Declare Navigation

Declare the navigation tree plugged into UX1 with a single navigation item and a view for managing a list of servers.

1. Create a navigation tree with the ccp ID and VPS Management label. Single page technology requires to plug it into http://www.parallels.com/ccp/2. Add a variable named context with type-id http://aps-standard.org/samples/vpsdemo/context/1.0. This will be needed to bind VPSes with the management context.
2. In the navigation tree, create an item with the servers ID and the Servers label.
3. In the navigation tree, create an item with the vps-creation-wizard ID and the VPS Creation Wizard label.
4. In the servers item, create a view with the servers ID and Servers label. Specify ui/servers.js as the source. It will present a list of servers, manage their state, and allow calling other views.
5. In the servers view, add a view with the server-edit ID and the Edit VPS label that will allow editing properties of a selected VPS. Specify ui/server-edit.js as the source. Declare two controls in it: cancel and submit. Add a variable named vps referring to type http://aps-standard.org/samples/vpsdemo/vps/1.0. This variable is needed in the view to retrieve the JSON representation of the VPS opened for editing.
6. In the vps-creation-wizard item, create a wizard element. Assign to it the ui/vps-wizard ID, the New VPS Step-by-Step label, and the VPS Creation step-label. Inside the wizard, create a placeholder element with vps-wizard ID.

Create a separate navigation structure containing the VPS creation views as follows.

1. Create a navigation element with the wizard-views ID. Declare that it plugs into the vps-wizard wizard declared earlier in another navigation tree.
2. In the wizard-views navigation element, add the first view element with the server-new-1 ID and Configure VPS properties step-label. Specify ui/wizard/server-new-1.js as the source.
3. In the wizard-views navigation element, add the second view element with the server-new-last ID and Review VPS properties step-label. Specify ui/wizard/server-new-last.js as the source.

After all of the above steps are done in the APP-META.xml file, the new <navigation> sections must appear inside the <presentation> section with the following contents:

<navigation id="ccp" label="VPS Management">
   <var type-id="http://aps-standard.org/samples/vpsdemo/context/1.0" name="context" />
   <plugs-to id="http://www.parallels.com/ccp/2" />
   <item id="servers" label="Servers">
      <view id="servers" label="Servers" src="ui/servers.js">
         <view id="server-edit" label="Edit VPS" src="ui/server-edit.js">
            <controls>
                  <cancel />
                  <submit />
            </controls>
            <var type-id="http://aps-standard.org/samples/vpsdemo/vps/1.0" name="vps" />
         </view>
      </view>
   </item>
   <item id="vps-creation-wizard" label="VPS Creation Wizard">
      <wizard id="vps-wizard" label="New VPS Step-by-Step" step-label="VPS Creation"
            src="/ui/vps-wizard.js">
         <placeholder id="vps-wizard" />
      </wizard>
   </item>
</navigation>
<navigation id="wizard-views">
   <plugs-to id="http://aps-standard.org/samples/vpsdemo#vps-wizard" />
      <view id="server-new-1" step-label="Configure VPS properties"
         src="ui/wizard/server-new-1.js">
      </view>
      <view id="server-new-last" step-label="Review VPS properties"
         src="ui/wizard/server-new-last.js">
      </view>
</navigation>

Declare Services

Make sure in the APP-META.xml file every APS type has a corresponding service declared:

<service id="clouds">
   <code engine="php" path="scripts/clouds.php"/>
   <presentation>
      <name>VPS cloud globals</name>
      <summary>VPS cloud application global service</summary>
      <infolinks>
         <link href="http://doc.apsstandard.org/apps/proc/generic/" class="deployment-guide">
            Demo project description
         </link>
         <link href="http://dev.apsstandard.org/develop/rt/tickets/new/" class="support">
            APS support
         </link>
      </infolinks>
   </presentation>
</service>
 <service id="contexts">
   <code engine="php" path="scripts/contexts.php"/>
   <presentation>
      <name>VPS Management</name>
      <summary>VPS management environment</summary>
   </presentation>
</service>
<service id="vpses">
   <code engine="php" path="scripts/vpses.php"></code>
   <presentation>
      <name>Virtual Private Server</name>
      <summary>Cloud virtual private server</summary>
   </presentation>
</service>

Conclusion

You have completed the project declarations in the file APP-META.xml that is similar to the respective file in the sample package.

← Generic Services

Provisioning Logic →