Examples¶

This is a compilation of trouble tickets and knowledge base with symptoms, analysis, diagnostic steps, and possible solutions for each case.

In this document:

Improper characters
A package must implement the APS Application type
Unauthorized request in endpoint host log
Application instance provisioning failure
Unable to add a resource to a service template
A service cannot be auto-provisioned
No types available
Trying to get a property of a non-object
Access violation
Removal of broken application instance
Navigation element not found
Application tab is missing in the user panel
Button from aps/Button or aps/ToolbarButton widget stays disabled after it is clicked

Improper characters ¶

Symptom¶

The validation utility returns the following:

$ aps lint sso-starter
/data/APS-2/workspace/sso-starter/APP-META.xml: Error: /data/APS-2/workspace/sso-starter/APP-META.xml XML structure
is broken.
The entity name must immediately follow the '&' in the entity reference.

Probable cause¶

Inside APP-META.xml, the utility met improper characters, reserved by W3C. This breaks the Rules and Limitations.

Diagnostics¶

In the APP-META.xml, find the ‘&` character. In the following example, the ‘&’ character is used in summary:

<summary>Simplest starter multi-tenant & SSO based application</summary>

Solution¶

To fix the issue, replace ‘&’ with ‘&’ and run the validation utility again.

A package must implement the APS Application type ¶

Symptom¶

When building a project, the aps build utility fails with the error message:

One of APS Types in a package must implement http://aps-standard.org/types/core/application/1.0 type

Probable cause¶

Each APS application must contain the root APS type that implements the APS core Application type. The considered project does not implement it.

Diagnostics¶

Verify schema declarations by performing one of these actions:

Look through the built /schemas/*.schema or /schemas/*.schema.gen file that declares the required service. Verify if it contains the implements declaration in the proper place. The following schema illustrates a correct implements declaration (most of other strings are omitted for brevity):

{
   "apsVersion": "2.0",
   "name": "cloud",
   "id": "http://aps-standard.org/samples/suwizard1p/cloud/1.0",
   "implements": [
      "http://aps-standard.org/types/core/application/1.0"
   ],
   "properties": {
   ...
   }
   ...
}

If the backend scripts are based on the APS PHP runtime and you define the types in PHP files, look through the PHP script where you define the application root service. The following is an example of a correct implements declaration (most of other strings are omitted for brevity):

require "aps/2/runtime.php";

/**
 * Class cloud presents application and its global parameters
 * @type("http://aps-standard.org/samples/suwizard1p/cloud/1.0")
 * @implements("http://aps-standard.org/types/core/application/1.0")
 */
class cloud extends APS\ResourceBase {
...
}

Solution¶

Ensure the application root APS type implements the APS core Application type as presented in the examples at the diagnostics step.

Unauthorized request in endpoint host log ¶

Symptom¶

When I work with the custom UI of my APS application, I see requests failing with error 500. The Apache error log on the endpoint host contains the following error message:

ERROR Exception: code=500,
type=Rest\RestException, message=Failed to parse aps object: Request to
APS controller failed: APS::Util::Exception: Unauthorized request#0
/usr/share/aps/php/aps/2/rest.php(343)

Probable cause¶

The application instance cannot authenticate itself on the APS controller.

As explained in Message Flows in the APS Environment, an application instance must add its SSL certificate in each REST request it sends to the APS controller. For this purpose, each APS application instance during its installation receives a pair of files named after the instance ID and containing the SSL certificate and the keys:

<application_instance_id>
<application_instance_id>.pem

Most probably, one or both of the files were lost or damaged.

Diagnostics¶

To prove the assumption, log in to the endpoint host by SSH and verify if the application endpoint environment contains both files:

# ls -l /var/www/html/<app-end-point-folder>/config/

Solution¶

If both files are missing, you need to restore them from the host backup or generate the new certificates using the Restoration of an Application Instance procedure. It is also possible to remove the instance and then repeat the Installing an Application Instance step.

If only the <application_instance_id>.pem file is lost, you can restore it from the <application_instance_id> file that contains the application private key and both certificates in JSON format (a single, very long string) - application certificate and APS controller certificate, for example, (most of the text is omitted for brevity):

{"appCertificate":
"-----BEGIN CERTIFICATE-----\nMIID...GEwJS\nVTESM...cM8D\/gTr\n
-----END CERTIFICATE-----\n
-----BEGIN RSA PRIVATE KEY-----\nMII...olTm\n
-----END RSA PRIVATE KEY-----\n",
"controllerURI":"https:\/\/10.28.110.145:6308\/",
"controllerCertificate":
"-----BEGIN CERTIFICATE-----\nMIID...I4Y=\n
-----END CERTIFICATE-----\n"}

To restore the <application_instance_id>.pem file, copy the private key and the SSL certificate from the <application_instance_id> file and save them both in the new <application_instance_id>.pem file. Then, convert the data from the JSON format to the plain text and replace each “\n” pair with the line feed to make it look similar to this:

-----BEGIN CERTIFICATE-----
MIIDIDCCAgigAwIBAgIETAIzSTANBgkqhkiG9w0BAQUFADA+MQswCQYDVQQGEwJS
...
TCxTobDYEW3JRKEYeS9/KNd9VE7P3sqR81Rf6yX7cM8D/gTr
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA3lMpmd6UbLli9UnFZR9aEtIkWx5EFH8iyXQ+zxj73mX43r4m
...
L4H+Shn4TqvpOl9NMpQ7vq6G82No2Igx3bkQDxj/pgobpx2iolTm
-----END RSA PRIVATE KEY-----

Application instance provisioning failure ¶

Symptom¶

When installing an APS application instance in the provider control panel, the provisioning task fails with the following error message:

The requested URL /<endpoint_folder>/<application_service> was not found on this server

In that message:

<endpoint_folder> is the APS application endpoint folder.
<application_service> is the application root service used for creating APS application instances. Its name, for example, clouds, is generally the same as the name (without the extension) of the PHP file clouds.php that implements the service.

Probable cause¶

The endpoint host or the APS application endpoint environment is not configured correctly. The web server cannot find the required PHP script.

Diagnostics¶

Call the same URL in the command line or in your browser.
- Most probably, the response will contain the “404 Not Found” return code:
- The correct response would be:
If your endpoint host is new and you are installing the first application on it, verify the Web Host Setup.
Verify the APS Connector Setup.

Solution¶

Go through the Web Host Setup or APS Connector Setup procedure (choose the appropriate one according to the diagnostics).

Unable to add a resource to a service template ¶

Symptom¶

An attempt to add a resource type based on the Application Service Reference resource class to a service template fails with the following message:

No resources were selected

Probable cause¶

The respective resource type for this application was not created in the system.

Diagnostics¶

In the provider control panel, navigate to Services > Applications, locate the application, and open the application profile. On the Resource Types tab, verify if the required resource type is there.

Solution¶

Follow the Creating Resource Types procedure to create the required resource type.

A service cannot be auto-provisioned ¶

Symptom¶

When trying to create a subscription, the provisioning task in the Task Manager fails with an error message similar to:

Service 'SERVICE_NAME' cannot be auto-provided.

Probable cause¶

The resource type set as Automatically provision service is based on an APS resource with a strong relation to another resource that is missing. For example, the resource must have a link with the APS core application resource that is missing in the service template and consequently in the subscription.

Diagnostics¶

In the provider control panel, verify the list of resource types in the service template. One of the resource types must be based on the required APS resource.

Possible Solutions¶

If the required resource type is missing in the service template, add it. Then run the failed task again.
If the relation must not be required, update the resource model by changing the required attribute in the APS resource. Update the application on the platform. Cancel the failed task and repeat the subscription creation.

No types available ¶

Symptom¶

A provisioning task fails with a message similar to the following:

[APSC] resource of type http://mycompany.com/types/hyperv/offers/1.0 cannot be created by available brokers

Probable causes¶

The proper APS application service or APS application service reference resource type does not exist in the customer subscription.
The proper APS type was upgraded to another major version, but a script still requires the old version.

Diagnostics¶

In the provider control panel, find the subscription and verify if the required resource type is there.
If it does not exist in the subscription, most probably it does not exist in the respective service template. Verify if the respective resource type is in the service template.

Possible solution¶

If the resource type is not in the service template go through the following steps:

If the resource type does not exist in the system at all, create the resource type.
Add the required resource type to the service template.
Update the customer subscription.

If the proper APS type was upgraded to another major version:

Upgrade the respective script.
Upload the script to the server.

Trying to get a property of a non-object ¶

Symptom¶

When provisioning a resource, the provision() method records an error message in the Apache error log:

Internal Server Error: Trying to get property of non-object at /usr/share/aps/php/aps/2/aps.php:584

Probable causes¶

The required resource does not exist.
The link to the required resource does not exist.

Diagnostics¶

If the provision() method is quite complicated and it is hard to identify the exact place where the error was captured, call the APS PHP Logger in proper places to isolate the error.
Use the Client Tools client to verify if the required resource exists.
Verify if, in the suspected PHP code, the required resource is called through a link. If so, verify if the link is declared as required (strong) in the respective APS type (in the schemas/*.schema file). In the following PHP code example, the $subscription_id is defined through the subscription link:
```
$subscription_id = $this->subscription->subscriptionId;
```
If the subscription relation is defined as weak (required:false), the execution of the code will lead to this error.

Possible solutions¶

The solution depends on results of the diagnostics.

If a weak relationship is the cause, make it strong. This means that in the schema file it must be declared as required:true.
If the required resource was not created before the provision() method calls it, then you need to analyze the code and the error log more thoroughly on the diagnostics step to isolate the error. Then update the provisioning logic accordingly.

Access violation ¶

Symptom¶

When working on behalf of a service user and trying to update a resource property, the system throws an error message similar to this:

'AccessViolation' error when trying to update a linked resource

Probable causes¶

By default, when a customer assigns a resource to a service user, the latter obtains the resource referrer role that does not grant write permissions to resource properties.

Diagnostics¶

Verify if the respective APS type grants access to the required resource or resource property for the referrer role.

You can also use the Client Tools to verify the access lists by getting the following collection:

/aps/2/resources/{resource}/aps/access - list of actors (with permissions) who can access these resources. For example:

GET http://a.isv1.apsdemo.org:8080/aps/2/resources/dd50b19d-9912-4c69-8be8-7a31a440ad7d/aps/access

[
    {
       "actor": "ec8b49ed-7da0-4de4-92e7-21cd7afc413b",
       "access":
       {
          "owner": true
       }
    },
    {
       "actor": "f7fbf93f-08a3-4ea8-b92d-61bfa745ec0c",
       "access":
       {
          "owner": true
       }
    }
]

Every actor in the platform gets a collection of permissions - /aps/2/resources/{resource}/aps/permissions - with a list of accessible resources and their permissions.

GET http://a.isv1.apsdemo.org:8080/aps/2/resources/f7fbf93f-08a3-4ea8-b92d-61bfa745ec0c/aps/permissions


[
    {
       "resource": "7858aeaf-7e30-464e-ae47-9f2d52408eed",
       "access":
       {
          "referrer": true
       }
    },
    {
       "resource": "dd50b19d-9912-4c69-8be8-7a31a440ad7d",
       "access":
       {
          "owner": true
       }
    },
]

Note

Only the provider staff can access and manage those collections

Solution¶

Use one of these ways:

Create a custom method that will update the required property. This is the most secured way as it does not provide direct access to the resource properties.
Use the access:true attribute in the resource declaration or the property declaration to change the default value for the referrer role.
Assign the resource owner role to the service user to whom the customer will assign the resource.

Removal of broken application instance ¶

Symptom¶

Neither the resources nor the application instance can be removed from the provider control panel. If you force uninstall in the panel, the Task Manager returns:

ERROR: update or delete on table "aps_application" violates foreign key constraint "FK_aps_resource_aps_application"
on table "aps_resource"

Probable causes¶

Some tasks in the deinstallation process were cancelled improperly. If the provider improperly cancelled some tasks, especially the “finalizing operation”, the deinstallation cannot be finished.
An application is in a crucial inconsistency, for example, SSL certificate of the application instance is lost and there are some resources dependent on the application instance.

Diagnostics¶

In Task Manager, verify if there are cancelled tasks in the queue with the name aps_application_instance<instance_id>, where the <instance_id> is the ID assigned by the platform to the APS application instance.
In the APS application endpoint folder, verify if the files with SSL certificates and keys exist in the config/ subfolder.

Solution¶

If the diagnostic step discovered cancelled tasks that prevents the completion of the uninstallation, try to run those tasks.

If this way does not help, and you still cannot uninstall the application instance, switch the application to another endpoint environment, usually fake endpoint, in order to remove the existing application instance.

Note

Every platform installation contains a fake APS endpoint, demonstrated later, that responds with “200 OK” to any REST request for provisioning or configuration.

Determine which of the following fake endpoints you will use. For example, you can use https://localhost:8081/pa/rest/fake/ referring to a fake endpoint on the management node that exists in all installations.
In the database, edit the endpoint URL for your applicaion:
- In the provider control panel, navigate to Services > Applications and on the Application Instances tab, identify the application instance ID in the first column of the list.
- Open the database client and in the aps_application table, find the record containing the discovered application instance ID. In the following example, the ID is 15:
```
# su postgres -c psql
postgres=# \l
postgres=# \connect oss;
oss=# SELECT id,endpoint_uri FROM aps_application WHERE uid =
       (SELECT uuid FROM aps_application_instances WHERE app_instance_id = 15);
id |                     endpoint_uri
----+------------------------------------------------------
17 | https://endpoint.a.isv1.apsdemo.org/endpoint75674
```
- Edit the endpoint URI for the application instance. In the following example, the first of the above listed fake endpoints is used:
```
oss=# update aps_application set endpoint_uri =
    'https://localhost:8081/pa/rest/fake/' where id = 17;
```
Resubmit all pending and canceled tasks in the queue discovered at the diagnostics phase.

Navigation element not found ¶

Symptom¶

Dynamic navigation using aps.apsc.gotoView does not work. The error message is:

Navigation element not found (View: http://a.isv1.apsdemo.org/application/account.edit-notify#41;)

Probable cause¶

The destination view, usually a resource editor, requires a resource to open. In the custom code, the resource APS ID was not sent as the second argument in the gotoView call.

Diagnostics¶

Open the respective JavaScript file and verify if the method call passes the resource APS ID to the destination view.

Solution¶

Fix the code properly, for example, pass the resource APS ID as in the following example:

aps.apsc.gotoView("server-edit", vpsID);

Application tab is missing in the user panel ¶

Symptom¶

The navigation panel in the UX1 does not show the application tab although the customer has subscribed to the application services.

Probable cause¶

The application navigation tree cannot plug into the UX1 navigation panel due to the following probable errors:

The application tries to plug its navigation tree in to an improper placeholder.
The navigation tree declares a navigation variable that cannot be resolved by the time when UX1 must embed the application tab.

Diagnostics¶

Investigate the declaration of the navigation tree in the APP-META.xml file for the probable causes.

Solution¶

Fix the navigation tree in accordance with the diagnostics results.

Button from aps/Button or aps/ToolbarButton widget stays disabled after it is clicked ¶

Symptom¶

After an aps/Button or aps/ToolbarButton widget is clicked, it stays disabled even after the requested operation is completed.

Probable cause¶

By default, the widgets behave this way to protect themselves from repeated submissions while the required operation is still in progress as explained in the Disable Button on Click section.

Diagnostics¶

Look through the code and verify if the button is released after the required operation is completed.

Solution¶

Resolve it using one of these ways:

Add the autoBusy, busyLabel, and timeout property as described in the aps/Button document.
Add the cancel() method at the end of the required operation to release the button.
To release all navigation buttons in a view, call the aps.apsc.cancelProcessing() method. For example, a user presses the Next button in a wizard to go to the next step. The button handler verifies the data in the current view. If the verification fails, the user stays on the same view, and the handler releases the button.

onNext: function() {
   var page = registry.byId("apsPageContainer");
   page.get("messageList").removeAll();
   if (!page.validate()) {
     aps.apsc.cancelProcessing();
     return;
   }
   aps.apsc.next({ objects: [getPlainValue(self.model.data)]});
},      // End of onNext

← Procedures

Getting Support →

CloudBlue Commerce API

Previous topic

Next topic

Examples¶

Symptom¶

Probable cause¶

Diagnostics¶

Solution¶

Symptom¶

Probable cause¶

Diagnostics¶

Solution¶

Symptom¶

Probable cause¶

Diagnostics¶

Solution¶

Symptom¶

Probable cause¶

Diagnostics¶

Solution¶

Symptom¶

Probable cause¶

Diagnostics¶

Solution¶

Symptom¶

Probable cause¶

Diagnostics¶

Possible Solutions¶

Symptom¶

Probable causes¶

Diagnostics¶

Possible solution¶

Symptom¶

Probable causes¶

Diagnostics¶

Possible solutions¶

Symptom¶

Probable causes¶

Diagnostics¶

Solution¶

Symptom¶

Probable causes¶

Diagnostics¶

Solution¶

Symptom¶

Probable cause¶

Diagnostics¶

Solution¶

Symptom¶

Probable cause¶

Diagnostics¶

Solution¶

Symptom¶

Probable cause¶

Diagnostics¶

Solution¶