Testing

You can test and debug the code on practically all steps of the integration process, starting from the code development and up to the final application certification, including the testing phase.

This explanation of each step contains typical operations, references to Tools and Methods, and possible issues.

Code Development

Although you start developing the code much earlier than the testing phase starts, you can include some testing points into the code and even perform partial testing before the testing phase:

• Test some code parts especially widgets and data processing algorithms in the APS fiddle before including them into the application.

• Use log functions in provisioning and presentation code.

• Set breakpoints for the debugging tools.

Tools

The CLI Tools helps you validate and build the project.

Metadata Declaration

Metadata is created in the APP-META.xml file.

Possible Issues

When configuring metadata, mind the following possible issues:

• Using improper characters that break the Navigation as in the example.

• Incorrect definition of navigation trees, including:

  • Placeholder declaration

  • Missing view parameters

  • Improper definition of navigation variables

• Improper declaration of a <service> element

Resource Model Development

A resource model contains a set of APS types defined using one of the following ways or a combination of them:

• APS types defined in scripts/*.php files using special annotations in PHP classes based on APS PHP runtime. When building the project, the PHP runtime generates the final type definition in the schemas/*.schema files. If you use PHP, we recommend this method where possible, as it is less prone to syntax and semantic mistakes.

  You can verify the type defined in a PHP script by building the schema file from it using the PHP schema builder.

• APS types defined in JSON format directly in schemas/*.schema files. Follow the Type Definition rules to avoid mistakes.

The services bound to the APS types are defined in metadata inside the APP-META.xml file, in the <service> sections.

Possible Issues

• Improper declaration of a relationship as in the example.

• Improper declaration of properties, structures, and operations.

Backend Development

The provisioning logic of an integration package is implemented by scripts deployed on an endpoint host and used to integrate the APS controller with the external application.

Note

The following explanations assume that you use the APS PHP framework on your endpoint host. In any case, also follow the 3rd party recommendations for testing and debugging in your particular environment.

Identify PHP Version

Currently, APS PHP runtime requires as minimum of PHP version 5.3 on the endpoint host. Some generic PHP classes and functions, you wish to use, may require a certain version of PHP.

To identify the PHP version installed on your server, run the phpinfo function as follows.

1. Create the simplest PHP script:

   $ echo "<?php" >> test.php
   $ echo "phpinfo();" >> test.php
   $ echo "?>" >> test.php
   

2. Run the PHP script:

   $ php test.php
   

   The output will look something like this:

   phpinfo()
   PHP Version => 5.3.10
   # ... the rest of the output is omitted for brevity
   

Code Validation

The APS IDE and CLI tools validate the whole package along with PHP scripts. To exclude validation of the UI part, use the --skip-js-error option, for example:

$ aps lint --skip-js-errors basic1p/

Recommendations

The following additions can help you isolate possible errors in a complicated code or misbehavior of the environment the code will work in.

• Temporarily, switch on the development mode in the PHP script.

• In critical code fragments, use the APS PHP logger to save diagnostic messages in the Apache error log.

• Use try, catch and throw methods to avoid “Uncaught Exception …” messages generated by the system.

UI Development

Custom UI is based on using the APS JavaScript SDK. The development is tightly bound to the navigation declaration in metadata as explained earlier.

Use the following tools that help you locate or avoid some issues later:

• Use APS fiddle to verify your code as much as possible. The corresponding documents contain many references to the APS fiddle to help you build your own code and verify your concepts based on the recommended solutions.

• Use Console Log Methods to help you track the code execution in a JavaScript debugger.

Try and Catch Method

As described at JavaScript Errors, JavaScript provides the powerful try and catch methods to reveal various errors in the code, in input data, and other unforeseen things.

The method can type diagnostic messages on the browser screen.

try {
    Block of code to try
}
catch(err) {
    Block of code to handle errors
}

Validation

Validate the JavaScript code by means of the jslint or jshint utility.

1. To have the jshint utility available on your local computer, install it using the nodejs package manager:

   $ sudo npm install -g jshint
   

2. Download the APS jshint configuration file jshint-config.json.

3. Run a validation of a single file or all JavaScript files, for example:

   find folderName/ui/ -name "*.js" -exec jshint -c jshint-config.json {} \;
   

Deployment

Building Package

Once the whole application project is completed, you can build the archived APS package.

The minimal set of components includes:

• APP-META.xml - metadata with various application and package declarations

• APP-LIST.xml - list of all files in the package generated automatically when building the project

• schemas/ - the folder containing either manually created *.schema files or *.schema.gen files automatically created by the aps build command

Possible Issues

• None of the APS types implements the APS core Application type as explained in the example.

• XML metadata contains incorrect symbols as illustrated by the example.

Importing Package

Import the archived package to the management platform as explained in Package Import.

Possible Issues

• IDs of the APS types in the package are already used by other applications in the system. Applications must assign globally unique IDs to their APS types.

Creating the APS Connector

The backend part of an application is deployed on the web server of the endpoint host by running a utility such as the endpoint.sh utility on this host, for example:

# endpoint basic1p Sample_Basic_Single_Page-1.0-0.app.zip

CONGRATULATIONS! Endpoint configured SUCCESSFULLY

Endpoint url: https://endpoint.a.isv1.apsdemo.org/basic1p

This will deploy the contents of the scripts/ folder of the specified package in the specified sub-folder (basic1p/ in the example) inside the document root of Apache, which is /var/www/html/ by default. The command also exposes the application endpoint URL as printed on the screen.

Use the following command to verify the application location on the endpoint host:

# ls -l /var/www/html/basic1p
total 24
drwxr-xr-x  2 apache apache 4096 Mar 17 17:53 .
drwxr-xr-x 8 root   root   4096 Mar 17 17:53 ..
-rwxr-xr-x 1 apache apache 1131 Feb 12 18:53 clouds.php
-rwxr-xr-x 1 apache apache 1612 Feb 12 18:53 contexts.php
-rwxr-xr-x 1 apache apache  370 Mar 17 17:53 .htaccess
-rwxr-xr-x 1 apache apache 2152 Feb 12 18:53 vpses.php

After you update a file in the scripts/ folder of your project, upload it to the endpoint location. When troubleshooting an issue, you can update files directly on the server.

Installing an Application Instance

When the Docker based Deployment is used, the previous and the current steps are completed together, immediately.

If you have installed the APS connector as explained in the previous section, install an APS application instance in this environment following the Application Instance Installation section. This will add the config/ folder with SSL keys and certificates as explained in the SSL Authentication of Application Instances section.

The updated application endpoint folder looks as follows after the installation:

# ls -al /var/www/html/basic1p/
total 32
drwxr-xr-x  4 apache apache 4096 Mar 16 17:15 .
drwxr-xr-x 15 root   root   4096 Mar 18 11:00 ..
-rwxr-xr-x  1 apache apache 1131 Feb 12 18:53 clouds.php
drwxr-xr-x  2 apache apache 4096 Mar 16 17:15 config
-rwxr-xr-x  1 apache apache 1612 Feb 12 18:53 contexts.php
-rwxr-xr-x  1 apache apache  372 Mar 16 17:15 .htaccess
drwxr-xr-x  3 apache apache 4096 Mar 16 17:17 typeCache
-rwxr-xr-x  1 apache apache 2152 Feb 12 18:53 vpses.php

The typeCache/ folder caches PHP classes for various versions of instances. If an update in a PHP file does not have any effect on the application behavior, remove the typeCache/ folder and try again.

Possible Issues

• APS instance provisioning fails because the requested URL cannot be found as in the example.

• Instance installation fails because the APS connector returns an object representation in a format different from JSON.

Creating APS Resources

If you use the product initialization wizard to deploy the products for selling the application services, verify if all of the mentioned below objects are created in OSS/BSS and, probably, add or configure some of the required objects. Otherwise, you must create them one by one manually.

Ensure you create reference APS resources (also known as global resources), for example, offers, that are used to parameterize services for customers in accordance with the resource model.

In the next step, you need to create a resource type for every reference APS resource that you are going to add to the service template.

Creating Resource Types

Create all resource types you are going to include into the product on the next step. Follow the Creating Resource Types procedure.

Creating Products

To provide application services for sale, normally you should create a service template and a service plan based on the service template as follows.

Service Template

Using the provider control panel of the OSS, create a service template and add all resource types that a customer subscription may require.

Service Plan

In BSS, ensure the payment system is configured and a test customer is created on this platform, and then follow the service plan configuration procedure.

Possible Issues

• Unable to add a resource to the service template because it was not created at the previous step as in the example.

• Missing a resource type in the template. In this case, customers cannot consume the respective service or even cannot have an active subscription.

Provisioning

Subscribing

Use the BSS provider control panel as explained in the demo project to order, pay and provision a subscription.

Possible Issues

• A service cannot be auto-provided as in the example.

Customer Operations

Now you have a live subscription, the main part of application testing and debugging starts. This is what we call the test phase. You must test all designed customer scenarios in the user panel, for example:

• Creating (provisioning) resources

• Assigning and reassigning resources to service users using the system User Creation wizard and User Manager tools

• Configuring resources individually or in bulk

• Changing a resource state using custom operations

• Removing resources

If resources are assigned to service users, test all typical user scenarios by logging in to the user panel on behalf of a user.

Note

If you use JavaScript modules and methods in addition to those provided by the APS JS SDK, it is reasonable to test the scenarios in all widely used browsers.

Possible Issues

• In the Add New Users wizard, the Assign Services to New Users list does not contain the application service. The most probable cause is that the service is bound to the APS type that does not implement the UserService with the required relation to the User type.

• Unauthorized request from the application to the APS controller as in the example.

• A customer is unable to add a service user because no domains are available. This is not an APS issue. By default, the system requires a customer to have at least one domain to be used for creating user logins. For example, a customer can add the aps.test domain to create users with logins similar to jsmith@aps.test. The other way is to enable the Allow custom login for service users system property on your lab system following a procedure similar to setting development mode. When the property is set in your lab system, customers can use any domain name in a user login name.

  Warning

  Do not enable the Allow custom login for service users system property in a production system, as customers can interfere with each other when choosing unique login names for users.

Updating APS Applications

After you change the metadata, an APS type, a script, or other source data, you must update the package version, upload the package to the system, and then update the application instance.

Procedure

The Upgrade document contains a detailed explanation of all aspects of application updates. Briefly, the process includes at least the following steps:

1. Ensure the <upgrade> element is configured in the metadata, for example:

   <upgrade match="version =gt= 1.0" />
   

2. Increase the package version if an APS type has changed in the application.

3. Build the package.

4. If the provisioning logic has changed, upload the files updated in the scripts/ folder to the application endpoint folder.

5. Use the OSS provider control panel to import the updated package.

6. Open the uploaded package and update the application instance.

Possible Issues

• A resource cannot be created by any available APS type as in the example.

• The APS controller cannot find a schema for a specified URL. Typically, this means that an APS type version was increased in the schemas/*.schema or scripts/*.php file, but it was not synced with other places that refer to this type. For example, you might use it in the following places:

  • As a variable in the navigation declaration

  • As a link in other APS types

  • In requests from the application instance to the APS controller

  • As a data store or an argument in the aps/xhr method in JavaSсript code

  • In requests and links used in other applications integrated with your application

  To fix it, you go through all parts that refer to the updated APS type and replace the type version with the new one. The following example replaces all occurrences of “vps/1.0” in the basic1p/ folder with “vps/1.1”:

  $ for fl in `find basic1p/ -type f`; do vim -c '%s@vps/1.0@vps/1.1@gc' -c 'wq' $fl; done
  

Removing Applications

Potential Reasons for Removal

In some cases, you must remove an APS application from the platform, for example:

• When testing an APS application, you did such substantial changes that it is easier to remove the APS application than perform the more complicated update procedures around the application.

• You are not going to use the application on the system, and it has APS types whose ID you are going to use in another application.

• Someone with the provider permissions performed certain operations with the APS application, probably in the database, that caused inconsistency in the APS application and its resources. Therefore, you have to remove the APS application from the platform and install it again.

Typical Steps

Warning

Before you start the following procedure, identify the application you are going to remove and ensure that its removal will not impact real customers.

You must perform the deployment and provisioning steps in the reverse order.

1. Unsubscribe customers from the application services. In other words, remove all subscriptions that include any resources provided by the application as follows.

   • In the BSS provider control panel, navigate to Operations > Subscriptions and cancel each of the subscriptions containing the application resources by following the next steps.

   • Open the subscription and click Cancel Subscription. Enter a message in Comments, click Next, and then click Place Order.

   • Ensure the Service Status is stopped, switch to the Orders tab, and click on the new order.

   • Click Open Order and wait until the Order Status is Completed.

   • After all subscriptions are cancelled, navigate again to Operations > Subscriptions and destroy the terminated subscriptions one-by-one as explained in the next step.

   • Open a subscription you need to destroy and click Destroy. The Service Status of the subscription must be Removed.

   • After all subscriptions in the BSS are removed, switch to the OSS control panel by clicking on the Operations link on top right of the screen.

   • Navigate to Operations > Subscriptions and ensure the respective subscriptions disappeared in this environment as well. if they still exist, verify if all of the above steps were done as described.

2. Remove application resources from the service template as follows.

   • In the BSS provider control panel, navigate to Products > Service Plans and locate the service plan that provides the application resources.

   • If the plan contains resource rates, remove them first. For this purpose, open the service plan, switch to the Resource Rates tab, select all resource rates, and click Delete.

   • In the list of service plans, select your plan and click Delete.

   Remove the application resource types from the service template in the OSS as follows.

   • In the OSS provider control panel, navigate to Products > Service Templates, locate and open the service template.

   • On the Resources tab, select all resources and click Delete. Confirm your decision in the popup.

   Note

   (Optional) If you no longer need the service template, remove the whole service template with all resource types in it.

3. Remove the application resources.

   • In the OSS provider control panel, navigate to Services > Applications and open your application profile.

   • On the Resource Types tab, select all resources and click Delete. Confirm your decision in the popup.

4. Remove the APS application instance.

   • On the Instances tab of the open application profile, open the instance and click Uninstall.

   • Confirm your decision in the pop-up window.

5. Remove the APS application.

   • Open again the application profile. On the General tab, click Delete Application.

   • Confirm your decision in the pop-up window.

Possible issues

Some issues caused by inconsistency are possible. For example, the application instance is broken and cannot be removed as in the example. Use the Task Manager to start the troubleshooting.

← Client Side

Debugging →