This is a compilation of trouble tickets and knowledge base with symptoms, analysis, diagnostic steps, and possible solutions 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 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 {
...
}
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 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)
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.
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/
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-----
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.
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 (choose the appropriate one according to 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.
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.
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.
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.
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.
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
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.
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.
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.
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
The required resource does not exist.
The link to the required resource does not exist.
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.
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.
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 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
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.
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"
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.
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.
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.
The navigation panel in the 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:
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.
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.
After an 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 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