Meta Declaration

In the previous phase, we completed the main design tasks of the demo project. Here, we will start the development phase with the metadata declaration.

The APP-META.xml file must define the metadata of the APS application.

General Data

General data presents an application in a product catalog and in the provider control panel.

1. Assign an APS application ID by the <id> element in the form of a URI that must be unique to all APS applications imported to the platform.

   <id>http://aps-standard.org/samples/github/</id>
   

   Note

   Once you start using an ID for an APS application, do not change it unless you want to clone that application to another one.

2. Enter the application name using the <name> element, for example:

   <name>GitHub with Upsell and Single ST</name>
   

3. If necessary, change the package version by means of the <version> and <release> elements used together to specify a unique APS package (APS application) version. Usually, the version corresponds to 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.

4. In the <vendor> section, specify the properties of your company or department.

5. In the <packager> section, specify the properties of yourself or your company whoever is responsible for the integration of the application. For simplicity, you can use the same values as in the <vendor> section.

Generally, the upgrade section is required not during development, but rather in the application upgrade process. However, even while completing the development steps, you may need to improve the APS application and therefore you must increase the package release to upgrade the deployed application. In this case, allow any upgrades by temporarily adding the following element after the <license-agreement> section:

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

With this definition, you can upgrade any version higher than 1.0.0 to any newer version.

Navigation in UI

In accordance with our scenario, the APS application must provide a user interface in two user panels:

• In the provider control panel (PCP) to configure licenses representing SKUs.

• In UX1 for customers to manage the application services.

For that purpose, declare the required UI navigation trees inside the <presentation> section:

1. Declare a UI navigation tree plugged into PCP, that is to the http://www.aps-standard.org/ui/application placeholder. The provider will use it to configure a list of licenses. The navigation tree will contain three views:

   • licenses: to present a list of license APS resources

   • license-new: to create a new license APS resource

   • license-edit: to edit an existing license APS resource

   With the above requirements, the <navigation> must look as follows:

   <navigation id="pcp" label="License Management">
      <var type-id="http://aps-standard.org/samples/github/app/1.0" name="app" />
      <plugs-to id="http://www.aps-standard.org/ui/application" />
      <item id="licenses" label="License Management">
          <view id="licenses" label="Licenses">
              <view id="license-new" label="New License">
                  <controls>
                      <cancel />
                      <submit />
                  </controls>
              </view>
              <view id="license-edit" label="License {license.name}">
                  <controls>
                      <cancel />
                      <submit />
                  </controls>
                  <var type-id="http://aps-standard.org/samples/github/license/1.0"
                       name="license" />
              </view>
          </view>
      </item>
   </navigation>
   

   In the above declaration, you will find two navigation variables:

   • app represents the APS application instance. The declared views will need it to correctly find the collection of licenses.

   • license represents the license APS resource selected for editing in the license-edit view.

2. Declare a UI navigation tree plugged into UX1, that is to the http://www.parallels.com/ccp/2 placeholder. Customers will use it to view the obtained license and manage their repositories. Declare it as follows:

   <navigation id="ux1" label="Using application services">
      <view id="services" label="Application Services" src="ui/services.js"/>
      <var name="tenant" type-id="http://aps-standard.org/samples/github/tenant/1.0"
           filter = "select(license)"/>
      <plugs-to id="http://www.parallels.com/ccp/2"/>
   </navigation>
   

   The navigation variable tenant will bring the relevant tenant APS resource to the declared view. The specified filter adds the linked license APS resource to that variable through the license link.

Services

The designed 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. If using the APS PHP framework on your endpoint host, the best way is to define both parts in one PHP file. However, this is not always possible as you will find in one of the following steps.

So, the goal of a service declaration is to define the following two things:

• The service ID used by the platform as a part of the URL to send HTTP requests to. For example, if the application APS connector base URL is https://endpoint.platform.example/github and the service ID is tenants, the platform will address that service using the https://endpoint.platform.example/github/tenants URL.

• The location of the APS type definition whose APS resources the declared service will manage.

Note

Typically, we assign a name in plural form to a service, for example, licenses, and a name in singular form to the respective APS type, for example, license. The reason is that a service is a factory of many resources. One such possible exception is the root application service that manages the application instance. Usually there is only one APS application instance used by the platform to interact with an original cloud application.

Use the following steps to define all three services: app, licenses, and tenants.

1. Declare the application root service that implements an instance of the APS application:

   <service id="app">
      <code engine="php" path="scripts/app.php"/>
      <presentation>
         <name>Application instance service</name>
         <summary>Connects to the application with the provider credentials</summary>
      </presentation>
   </service>
   

   The <code> section specifies that the scripts/app.php file is the source of the APS type to be auto-generated by the PHP engine during the package building process. The auto-generated APS type will be represented by the app.schema.gen file inside the schemas/ folder.

2. Similarly, declare the service which will manage APS resources based on the license APS type:

   <service id="licenses">
       <code engine="php" path="scripts/licenses.php"/>
       <presentation>
           <name>License</name>
           <summary>A service profile offered to customers</summary>
       </presentation>
   </service>
   

   The PHP generator will use the scripts/licenses.php file to generate the schemas/license.schema.gen file representing the license APS type.

3. For the tenants service, we cannot use the PHP engine to generate a schema file, because we need to subscribe tenants to the Resource Limit Change event using the declarative way, which is not supported by the APS PHP runtime.

   <service id="tenants">
      <schema path="schemas/tenant.schema"/>
      <presentation>
         <name>Customer service - main tenant service</name>
         <summary>Corresponds to a repository in the cloud application</summary>
      </presentation>
   </service>
   

   The <schema> element declares the path to the schema file where the tenant APS type must be defined.

Conclusion

You have completed the project metadata declarations in the file APP-META.xml that you can compare with this sample APP-META.xml file:

<application xmlns="http://aps-standard.org/ns/2" version="2.0">
    <id>http://aps-standard.org/samples/github/</id>
    <name>GitHub Integration Demo</name>
    <version>1.0</version>
    <release>0</release>
    <vendor>
        <name>APS Team</name>
        <homepage>http://docs.cloudblue.com/oa/8.0/sdk/apps/github/</homepage>
    </vendor>
	<packager>
        <name>APS Team</name>
    	<homepage>http://docs.cloudblue.com/oa/8.0/sdk/apps/github/</homepage>
    </packager>
    <presentation>
        <summary>Integrates an external system based on REST API</summary>
        <description>This demo package is a part of the respective demo-project illustrating
            step-by-step design and development of an APS package for integrating
            a GitHub account with the CloudBlue platform. SKUs are simulated by GitHub
            access tokens with different scopes assigned to those tokens.
            Within the obtained scope, subscribers can manage GitHub repositories.
        </description>
        <categories>
           <category>Samples</category>
    	</categories>
        <navigation id="pcp" label="License Management">
            <var type-id="http://aps-standard.org/samples/github/app/1.0" name="app" />
            <plugs-to id="http://www.aps-standard.org/ui/application" />
            <item id="licenses" label="License Management">
                <view id="licenses" label="Licenses">
                    <view id="license-new" label="New License">
                        <controls>
                            <cancel />
                            <submit />
                        </controls>
                    </view>
                    <view id="license-edit" label="License {license.name}">
                        <controls>
                            <cancel />
                            <submit />
                        </controls>
                        <var type-id="http://aps-standard.org/samples/github/license/1.0"
                             name="license" />
                    </view>
                </view>
            </item>
        </navigation>
        <navigation id="ux1" label="Using application services">
            <view id="services" label="Application Services" src="ui/services.js"/>
            <var name="tenant" type-id="http://aps-standard.org/samples/github/tenant/1.0"
                 filter = "select(license)"/>
            <plugs-to id="http://www.parallels.com/ccp/2"/>
        </navigation>
    </presentation>
    <license-agreement must-accept="true">
		<free/>
		<text>
			<name>End-User License Agreement</name>
			<file>http://opensource.org/licenses/bsd-license</file>
		</text>
    </license-agreement>
    <upgrade match="version=ge=1.0, release=ge=0"/>
    <service id="app">
        <code engine="php" path="scripts/app.php"/>
        <presentation>
            <name>Application instance service</name>
            <summary>Connects to the application with the provider credentials</summary>
        </presentation>
    </service>
    <service id="licenses">
        <code engine="php" path="scripts/licenses.php"/>
        <presentation>
            <name>License</name>
            <summary>A service profile offered to customers</summary>
        </presentation>
    </service>
    <service id="tenants">
        <schema path="schemas/tenant.schema"/>
        <presentation>
            <name>Customer service - main tenant service</name>
            <summary>Corresponds to a repository in the cloud application</summary>
        </presentation>
    </service>
    <service id="resellers">
        <code engine="php" path="scripts/resellers.php"/>
        <presentation>
            <name>Reseller profile</name>
            <summary>Product customization for resellers</summary>
        </presentation>
    </service>
</application>

← Real Services Integration Example

Provisioning Logic →