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.
Explanation of each step contains typical operations, reference to Tools and Methods, and possible issues.
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:
The following development tools also help you identify possible issues:
Metadata is created in the APP-META.xml file. To avoid syntax errors, the best approach at this step is
to use APS IDE:
When configuring metadata, mind the following possible issues.
A resource model contains a set of APS types defined using one of the 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 wherever possible, as it is less prone to syntax and semantic mistakes.
You can verify the type defined in a PHP script by buiding 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.
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 are based on assumption 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.
Currently, APS PHP runtime requires as minimum PHP version 5.3 on the endpoint host. Some generic PHP classes and functions, you wish to use, may require certain version of PHP.
To identify the PHP version installed on your server, run the phpinfo function as follows.
Create the simplest PHP script:
$ echo "<?php" >> test.php
$ echo "phpinfo();" >> test.php
$ echo "?>" >> test.php
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
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/
The following additions can help you isolate possible errors in a complicated code or misbehavior of the environment the code will work in.
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:
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 just on the browser screen.
try {
Block of code to try
}
catch(err) {
Block of code to handle errors
}
Validate the JavaScript code by means of the jslint or jshint utility.
To have the jshint utility available on your local computer, install it using the nodejs package manager:
$ sudo npm install -g jshint
Download the APS jshint configuration file jshint-config.json.
Run validation of a single file or all JavaScript files, for example:
find folderName/ui/ -name "*.js" -exec jshint -c jshint-config.json {} \;
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 declarationsAPP-LIST.xml - list of all files in the package generated automatically when building the projectschemas/ - the folder containing either manually created *.schema files or
*.schema.gen files automatically created by the aps build commandImport the archived package to the management platform as explained in Package Import.
The backend part of an application is deployed on the web server of the endpoint host, for example by running the endpoint.sh
utility on this host, as in the following 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 out 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
Once you updated 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.
When the Docker based Deployment is used, the previous and the current steps are completed at once.
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. In case, an update in
a PHP file does not have any effect on the application behavior, remove the typeCache/ folder and
try again.
If you use the product initialization wizard to deploy the products for selling the application services, you should only 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 should 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 should create a resource type for every reference APS resource that you are going to add to the service template.
Create all resource types you are going to include into the product on the next step. Follow the Creating Resource Types procedure.
To provide application services for sale, normally you should create a service template and a service plan based on the service template as follows.
Using the provider control panel of the OSS, create a service template and add all resource types that a customer subscription may require.
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.
Use the BSS provider control panel as explained in the demo project to order, pay and provision a subscription.
Once you have a live subscription, the main part of application testing and debugging starts. This is what we call test phase. You should test all designed customer scenarios in the user panel, for example:
If resources are assigned to service users, test all typical user scenarios by logging to the control panel on behalf of a user.
Note
If you use some JavaScript modules and methods in addition to those provided by the APS SDK, it is reasonable to test the scenarios in all widely used browsers.
In the Add New Users wizard, the Assign Services to New Users list does not contain the application service. 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 the procedure similar to setting the setting development mode. Once 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, since customers can interfere with each other when choosing unique logins for users.
Once you changed metadata, an APS type, a script, or other source data, you should update the package version, upload the package to the system, and then update the application instance.
The Upgrade document contains detailed explanation of all aspects of application updates. Briefly, the process includes as minimum the following steps.
Ensure the <upgrade> element is configured in metadata, for example:
<upgrade match="version =gt= 1.0" />
Increase package version if an APS type has changed in the application.
Build the package.
If the provisioning logic has changed, upload the files updated in the scripts/ folder to the application endpoint folder.
Use the OSS provider control panel to import the updated package.
Open the uploaded package and update the application instance.
A resource cannot be created by any available APS type as in the example.
Cannot find a schema for a URI. Typically, it 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:
aps/xhr method in JavaSсript codeTo fix it, you should 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
In some cases, you have to remove an application from the system, for example:
Warning
Before you start the following procedure, please exactly identify the application you are going to remove and ensure that this will not impact real customers.
You should go in reverse order as compared with the deployment and provisioning steps.
Unsubscribe customers from the application services, in other words remove all subscriptions that include any resources provided by the application as follows.
Remove application resources from the service template as follows.
Remove the application resource types from the service template in the OSS as follows.
Note
Optionally, in case you are not going to use the service template later, remove the whole service template with all resource types in it.
Remove the application resources.
Remove the APS application instance.
Remove the APS application.
Some issues caused by inconsistency are possible. Use the Task Manager to start the troubleshooting.
For example, the application instance is broken and cannot be removed as in the example.