This is a compilation of trouble tickets and knowledge base with symptoms, analysis, diagnostic steps, and possible resolutions for each case.
In this document:
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.
Inside APP-META.xml
, the utility met improper characters, reserved by W3C.
This breaks the Rules and Limitations.
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>
To fix the issue, replace ‘&’ with ‘&’ and run the validation utility again.
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
Each APS application must contain the root APS type that implements the APS core Application type. The considered project does not implement it.
Verify schema declarations following one of the 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 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": {
...
}
...
}
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 {
...
}
Ensure the application root APS type implements the APS core Application type as presented in the examples at the diagnostics step.
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)
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.
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/
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-----
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:
clouds
is the same as the name (without extension) of the PHP file clouds.php
that implements the service.The endpoint host or the APS application endpoint environment is not configured correctly. The web server cannot find the required PHP script.
Call the same URL in the command line or in your browser.
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.
Go through the Web Host Setup or APS Connector Setup procedure whichever is appropriate in accordance with the diagnostics.
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
The respective resource type for this application was not created in the system.
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.
Follow the Creating Resource Types procedure to create the required resource type.
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.
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.
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.
required
attribute
in the APS resource. Update the application on the platform. Cancel the failed task
and repeat the subscription creation.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
If the resource type is not in the service template:
If the proper APS type was upgraded to another major version:
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
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.
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 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.
The resolution depends on the diagnostics results.
weak
relationship is the cause, make it strong
. It means in the schema file it must be declared
as required:true
.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.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
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.
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
Use one of the ways:
access:true
attribute in the resource declaration or the property declaration to change the default value
for the referrer
role.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"
aps_application_instance<instance_id>
,
where the <instance_id> is the ID assigned by the Operations Automation system to the application instance.config/
subfolder.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.
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 sandboxhttps://doc.apsstandard.org/endpoint
- on the APS documentation siteIn 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;
Resubmit all pending and cancelled tasks in the queue discovered at the diagnostics phase.
The navigation panel in UX1 does not show the application tab although the customer has subscribed to the application services.
The application navigation tree cannot plug into the UX1 navigation panel due to the following probable errors:
Investigate the declaration of the navigation tree in the APP-META.xml
file for the probable causes.
Fix the navigation tree in accordance with the diagnostics results.
Once a aps/Button
or aps/ToolbarButton
widget is clicked, it stays disabled even after the requested operation
is completed.
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.
Look through the code and verify if the button is released after the required operation is completed.
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