Examples

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

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>

Resolution

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

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 following one of the actions:

1. 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 shows 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": {
      ...
      }
      ...
   }
   

2. 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 example shows 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 {
   ...
   }
   

Resolution

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 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 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 proof the assumption, log in 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/

Resolution

• If both files are missing, you have to restore them from the host backup or generate the new certificates using the Restoration of Application Instance procedure. It is also possible to remove the instance and then repeat the Installing 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 part 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 fails

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. Normally, its name, for example, clouds is the same as the name (without 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

1. 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:

     

2. If your endpoint host is new and you are installing the first application on it, verify the Web Host Setup.

3. Verify the APS Connector Setup.

Resolution

Go through the Web Host Setup or APS Connector Setup procedure whichever is appropriate in accordance with the diagnostics.

Unable to add resource to 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.

Resolution

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

Service cannot be auto-provided

Symptom

On attempt to create a subscription, the provisioning task in the Task Manager fails with the 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 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 resource types must be based on the required APS resource.

Possible resolutions

• 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 like 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

1. In the provider control panel, find the subscription and verify if the required resource type is there.
2. 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 resolution

If the resource type is not in the service template:

1. If the resource type does not exist in the system at all, you should create the resource type first and then add it to the service template.
2. Add the required resource type to the service template.
3. Update the customer subscription.

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

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

Trying to get property of 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

1. If the provision() method is pretty complicated and it is hard to identify the place where exactly the error was captured, call the APS PHP Logger in proper places to isolate the error.

2. Use the Client Tools client to verify if the required resource exists.

3. 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 example of PHP code, 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 the considered error.

Possible resolutions

The resolution depends on the diagnostics results.

• If a weak relationship is the cause, make it strong. It means 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 have to analyze the code and the error log closer on the diagnostics step to isolate the error. Then update the provisioning logic properly.

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 of in system gets permissions collection - /aps/2/resources/{resource}/aps/permissions - with 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

Resolution

Use one of the 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 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

1. 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.
2. 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

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

Resolution

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

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

Note

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

1. Determine which of the following fake endpoints you will use:

   • https://localhost:8081/pa/rest/fake/ - on the management node, exists in all installations.
   • https://endpoint.<sandbox>.apsdemo.org/dummy/ - on the endpoint host in the development sandbox
   • https://doc.apsstandard.org/endpoint - on the APS documentation site

2. 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 plesk;
     plesk=# 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:

     plesk=# update aps_application set endpoint_uri =
         'https://localhost:8081/pa/rest/fake/' where id = 17;
     

3. Resubmit all pending and cancelled tasks in the queue discovered at the diagnostics phase.

Navigation element not found

Symptom

Dynamic navigation via 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.

Resolution

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 control panel

Symptom

The navigation panel in 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 into 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.

Resolution

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

Once a 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.

Resolution

Resolve it using one of the 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 →