Previous topic

Demo Projects

Next topic

Basic

DOCUMENTATION
Last updated 11-Aug-2016

Starter

Input data: No input data

Purposes

The project demonstrates APS package development process implementing the simplest model. It does not make any commercial sense yet. Nevertheless, it allows an APS beginner to realize the main APS principles in the Service Automation environment. The final APS package will provide VPS management environment (also often called context, please do not confuse it with the visual context used in custom UI scripts) to subscribers. It has no other resources in the provisioning logic, neither has it any custom UI for resource management. Following this demo project, you will go through the fundamentals of the development-deployment-provisioning cycle.

Following this project, you will create an APS package similar to the sample package in the APS catalog.

Resource Model

The package contains two APS types, one for creating the application resource and one for creating the customer management context. The resources must be bound with each other. In addition, the context resource relates with the Operations Automation account and the subscription as presented in the diagram.

../../../_images/starter-relations.png

Meta Description

In the project workspace, e.g. /aps/workspace/starter, create the APP-META.xml file and declare the minimum set of elements:

  • General data of the application, ISV, and APS packager
  • Application services
  • Declaration of JSON schema source for each service

The easiest way to complete the above is using Eclipse as the development tool.

The APP-META.xml file will look as follows:

<application xmlns="http://aps-standard.org/ns/2" version="2.0">
    <id>http://aps-standard.org/samples/starter</id>
    <name>Sample VPS Cloud Starter</name>
    <version>1.0</version>
    <release>1</release>
    <homepage>http://doc.apsstandard.org/pa/demo-projects/starter</homepage>
    <vendor>
    	<name>APS team</name>
    	<homepage>http://dev.apsstandard.org/</homepage>
    </vendor>
  	<packager>
           <name>APS team</name>
    	   <homepage>http://dev.apsstandard.org/</homepage>
    	   <uri>http://dev.apsstandard.org/</uri>
        </packager>
    <presentation>
    	<summary>Simplest starter multi-tenant application</summary>
    	<description>This is a demo application to demonstrate how to develop APS apps step by step</description>
        <icon path="images/icon.png"/>
    	<categories>
           <category>Samples</category>
    	   <category>Infrastructure/Management</category>
    	</categories>
    </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>
    <service id="clouds">
		<code engine="php" path="scripts/clouds.php"/>
		<presentation>
			<name>VPS cloud globals</name>
			<summary>VPS cloud application global service</summary>
		</presentation>
    </service>
    <service id="contexts">
		<code engine="php" path="scripts/contexts.php"/>
		<presentation>
			<name>VPS Management</name>
			<summary>VPS management environment</summary>
		</presentation>
    </service>
</application>

Key points:

  • Two services, clouds and contexts are declared.
  • The <code> element declares that JSON schema (APS type) for each service must be created from the corresponding PHP script.

Provisioning Logic

Service Overview

For each service declared in meta data, we need to have a provisioning script that must implement the provisioning logic of the service. Besides, the best practice is also to declare the resource type inside the script. PHP runtime allows building the JSON schema file for the service, when builiding the APS package. Each type must have own unique ID and the types are bound to each other as presented in the resource model. The table below provides the chosen type IDs and relations between them.

Type Name Type ID Relation Relation parameters
Clouds http://aps-standard.org/samples/starter/cloud/1.0 contexts Collection-Optional
Contexts http://aps-standard.org/samples/starter/context/1.0 cloud Singular-Required

Top Level Application Logic

To implement the clouds service, we create the appropriate clouds.php script, in which all needed functions are presented, but they are empty.

<?php

require "aps/2/runtime.php";

/**
 * Class cloud presents application and its global parameters
 * @type("http://aps-standard.org/samples/starter/cloud/1.0")
 * @implements("http://aps-standard.org/types/core/application/1.0")
 */
class cloud extends APS\ResourceBase {
# Link to collection of contexts. Pay attention to [] brackets at the end of the @link line.
	/**
	 * @link("http://aps-standard.org/samples/starter/context/1.0[]")
	 */
	public $contexts;

# Global connection settings will be configured by the provider
# Must be forwarded to the app end-point to set the connection with the external system
	/**
        * @type(string)
        * @title("apphost")
        * @description("Cloud management server IP or domain name")
        */
        public $apphost;
        
        /**
        * @type(string)
        * @title("Cloud Admin")
        * @description("Cloud administrator")
        */
        public $cloudadmin;

        /**
        * @type(string)
        * @title("Cloud Password")
        * @description("Cloud administrator password")
        * @encrypted
        */
        public $cloudpass;

# Functions to process link/unlink requests
/* Commented out since we don't need to redefine the parent operations
        public function contextsLink() { }
        public function contextsUnlink() { }
*/

# Functions to process CRUD operations:
/* Commented out since we don't need to redefine the parent operations
	public function provision() {  // create new instance
	# Declaration is needed
	}

	public function configure($new=null) { // change properties
	}
	
	public function retrieve() { // get data
	}
	
	public function unprovision() { delete object
	}
*/
# Custom functions should be declared here

}

Key points in the script:

  • We use decorators for declaration of the clouds type with all its properties and relations.

  • The first set of decorators, placed before the clouds class definition, declares the type and its parent type.

  • We use the other decorators inside the class to declare type properties and relations of the type with the contexts type. Declared variables, such as $contexts and $apphost, can be used by the custom UI.

    /**
     * Class cloud presents application and its global parameters
     * @type("http://aps-standard.org/samples/starter/cloud/1.0")
     * @implements("http://aps-standard.org/types/core/application/1.0")
     */
     class cloud extends APS\ResourceBase { ... }
    
  • For declaration of a link that is a collection of relations, we use a pair of brackets [ ] at the end of the type ID.

    # Link to collection of contexts. Pay attention to [] brackets at the end of the @link line.
    /**
     * @link("http://aps-standard.org/samples/starter/context/1.0[]")
     */
    public $contexts;
    
  • The declared class implements all functions from the APS core application resource and does not redefine any of them. Neither has it any custom methods declared.

Management Context Logic

The script for the contexts service, contexts.php was created following the same principles explained earlier for the clouds service:

<?php
# It is the context of the subscription, in which a customer can manage its VPSes.
# It must correspond to a tenant created for the subscriber in the remote application system.
require "aps/2/runtime.php";

/**
* Class context
* @type("http://aps-standard.org/samples/starter/context/1.0")
* @implements("http://aps-standard.org/types/core/resource/1.0")
*/

class context extends \APS\ResourceBase
{
## Strong relation (link) to the application instance
		
	/**
	* @link("http://aps-standard.org/samples/starter/cloud/1.0")
	* @required
	*/
	public $cloud;

## Strong relation with the Subscription.
## This way, we allow the service to access the operation resources
## with the limits and usage defined in the subscription.

	/**
	* @link("http://aps-standard.org/types/core/subscription/1.0")
	* @required
	*/
    public $subscription;

## Link to the account type makes account attributes available to the service,
## e.g., the account (subscriber) name, and all its other data.

	/**
	* @link("http://aps-standard.org/types/core/account/1.0")
    	* @required
    	*/
    public $account;

## Subset of attributes marked as read-only,
## which means only the application can change them.
## The password is "encrypted", which prevents customers to get its value.

	/**
	* @type(string)
	* @title("Context ID")
	* @readonly
	*/

	public $contextid;

	/**
	* @type(string)
	* @title("Context Password")
	* @readonly
	* @encrypted
	*/

	public $contextpass;

}
?>

Key differences:

  • The type context has a number of required relations (links) marked with the required attribute.
  • Besides the relation with the cloud type, the script declares relations to the Operations Automation subscription and account (subscriber). This corresponds to the resource model.

Presentation Logic

In this project, we do not implement any custom UI yet.

Deployment

Building Package

We build the package from the project folder starter by the following command:

aps build starter

The command validates the folder contents, generates the JSON schema files in the schemas directory, and then compresses the folder contents in one file, named VPS_Cloud_Starter-1.0-1.app.zip. As a result, we have the following package structure:

../../../_images/starter-package-folder.png

The JSON schema for the clouds service is presented by the clouds.schema.gen file:

// This file is generated by 'aps build' from 'scripts/clouds.php' script
// It will be regenerated next time 'aps build' command is executed
{
  "apsVersion": "2.0",
  "name": "cloud",
  "id": "http://aps-standard.org/samples/starter/cloud/1.0",
  "implements": [
    "http://aps-standard.org/types/core/application/1.0"
  ],
  "properties": {
    "apphost": {
      "type": "string",
      "title": "apphost",
      "description": "Cloud management server IP or domain name"
    },
    "cloudadmin": {
      "type": "string",
      "title": "Cloud Admin",
      "description": "Cloud administrator"
    },
    "cloudpass": {
      "type": "string",
      "encrypted": true,
      "title": "Cloud Password",
      "description": "Cloud administrator password"
    }
  },
  "relations": {
    "contexts": {
      "type": "http://aps-standard.org/samples/starter/context/1.0",
      "collection": true
    }
  }
}

Similarly, the JSON schema for the contexts service is presented by the contexts.schema.gen file:

// This file is generated by 'aps build' from 'scripts/contexts.php' script
// It will be regenerated next time 'aps build' command is executed
{
  "apsVersion": "2.0",
  "name": "context",
  "id": "http://aps-standard.org/samples/starter/context/1.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "properties": {
    "contextid": {
      "type": "string",
      "readonly": true,
      "title": "Context ID"
    },
    "contextpass": {
      "type": "string",
      "readonly": true,
      "encrypted": true,
      "title": "Context Password"
    }
  },
  "relations": {
    "cloud": {
      "type": "http://aps-standard.org/samples/starter/cloud/1.0",
      "required": true,
      "collection": false
    },
    "subscription": {
      "type": "http://aps-standard.org/types/core/subscription/1.0",
      "required": true,
      "collection": false
    },
    "account": {
      "type": "http://aps-standard.org/types/core/account/1.0",
      "required": true,
      "collection": false
    }
  }
}

Package Import

Now, the package is built, and we can import it to Operations Automation following these steps:

  • In the Operations Automation provider control panel, navigate to Services > Applications and click Import Package.
  • Select the local file option, seek for the APS package in the local computer, and then click Submit.
  • Make sure the package is imported, and its version appeared in the Latest Version column. For this purpose, click the refresh icon on top-right. If your system is slow, wait for several seconds and refresh the screen again.

Setting Application Endpoint

To set the APS application endpoint, follow the endpoint installation instructions. If you are using an APS sandbox, the easiest way is:

  1. Copy the APS package to the endpoint host.

  2. On the endpoint host, run the following command to install the endpoint:

    endpoint.sh vpscloud Sample_VPS_Cloud_Starter-1.0-1.app.zip
    

Notice and copy to the internal buffer the URL printed out, e.g. https://endpoint.a.isv1.apsdemo.org/vpscloud.

Installing Application Instance

Generally, the process is described at Application Instance Installation. In our case, it looks as follows:

  1. In the Operations Automation provider control panel, open the imported Sample VPS Cloud Starter APS package and switch to the Instances tab.

  2. Click the Install button.

  3. In the Application API end-point URI field, enter the application endpoint URL that must address to the endpoint root folder. In our example, it must be similar to https://<endpoint_domain_name>/vpscloud/.

  4. Enter any values for the requested application connection parameters, i.e. IP address or domain name for the cloud application host, administrative login, and password.

    Note

    In this demo project, the global parameters are not used in the provisioning logic, but most probably will be needed in real projects to establish a connection with the cloud application.

  5. Complete the operation.

Creating Resources

Once we have the application instance, we can create Operations Automation resource types that will represent the APS resources. In accordance with the resource map and the resource model, we need to create an Application Service Reference Operations Automation resource type for representing the application instance (cloud) and an Application Service Operations Automation resource type for representing the management context. The provider will follow these steps to create them:

  1. Open the VPS Cloud Starter application package and switch to the Resource Types tab.
  2. Click Create and select the Application Service Reference Operations Automation resource class.
  3. Assign a name to the resource, e.g. “VPS Cloud - Application - Starter Project”, and click Next.
  4. Click on the VPS cloud globals APS type and then - on the instance resource ID.
  5. Complete the operation by clicking Finish.

Repeat similar steps for creating the second Operations Automation resource type that will be used for automatic provisioning of the management contexts for customers:

  1. Click Create and select the Application Service Operations Automation resource class.
  2. Assign a name to the resource, e.g. VPS Cloud - Management Context -Starter Project, and click Next.
  3. Click on the VPS Management application service.
  4. Tick the Automatically provision service check-box and click Next.
  5. Complete the operation by clicking Finish.

Now, we have two Operations Automation resource types that can be used for creating a service template in Operations Automation.

Creating Service Template

Generally, the process is described in the Creating Operations Automation Service Template section. As we need only two resources in the service template (ST), the process is as simple, as follows:

  1. In the Operations Automation provider control panel, navigate to Products > Service Templates and click Add New Service Template.

  2. Enter the ST name, e.g. Cloud VPS Services - Starter Project, mark the Autoprovisioning box, make sure Custom is selected in the drop-down Type list, and click Next.

  3. Select the two resource types created in the previous section and click Next.

  4. Set a limit for each resource, equal 1, and click Next.

    ../../../_images/starter-st-limits.png
  5. Complete the operation by clicking Finish.

  6. Open the ST and make it active by means of the Activate button.

Provisioning

Provisioning is tested here to make sure that the Application and management context will be consumed as APS resources in a subscription.

  1. Create a subscription for an existing customer using one of valid Service Automation methods. For example, if you use Operations Automation without Business Automation, switch to the Subscriptions tab on the service template to start creating a subscription. Use all default settings, when directed by the subscription creation wizard.

  2. Open the customer control panel using one of valid Service Automation methods. For example, in the list of subscriptions, find the new subscription and click the link in the rightmost column.

  3. In the customer control panel, make sure the new subscription is selected in the Subscription drop-down box.

  4. On the Home tab, click Resource Usage-> and make sure, both APS resources are used.

    ../../../_images/starter-subscription-usage.png

This completes the APS application development cycle. If you experienced any issues when following the project steps, you can download the final package and compare it with the demo package you have created.

Basic