In this phase, you will make the application service available for customers.
In this document:
According to the Sales Model, the provider must have a service template that contains resource types presenting APS resources and APS types of the application. The application Resource Model contains three APS types:
The app
and license
APS types must be used to create reference APS resources to be linked with many
APS resources instantiated from the tenant
APS type.
Reference APS resources must be created first, after which, you can create resource types representing those reference APS resources in a service template.
Unlike the above-mentioned resource types, a resource type representing a tenant (an application service) must be
bound to the tenant
APS type before instantiating APS resources from it. A tenant
APS resource must be
created when creating a subscription.
This resource mapping looks as follows:
APS Service |
Description |
||
---|---|---|---|
Application instance |
Application Service Reference |
GitHub - App REF |
A global resource representing the application instance |
License |
Application Service Reference |
GitHub - License |
Use this to represent application offers - SKUs |
Tenant |
Application Service |
GitHub - Tenant |
Local representation of a customer’s tenant in the remote cloud application |
To assist service providers in product configuration, you should add the getInitWizardConfig
method to the
root service definition as explained in Deployment Configuration.
Typically, this method returns a set of products (represented by service plans) along with other components
that those products are based on.
Those accompanying components are a service template with resource types and some business components used
to arrange the product sales process.
In addition, the app
service must also have the testConnection
method to test a connection
with the application to be integrated with the platform.
Follow these steps to define the required methods:
In the scripts/
folder, create a file containing the JSON definition of the data
that the getInitWizardConfig
method must return. The file format is explained
in the Configuration for OSS document. To simplify the process,
download the wizard_data.json
file
to the scripts/
folder:
{
"defaults": {
"appId": "http://aps-standard.org/samples/github/app/1.0",
"apsName": "GitHub Integration Demo",
"apsVersion": "2.2",
"apsResources": [
{
"apsType":"http://aps-standard.org/samples/github/license/1.0",
"type": "http://aps-standard.org/types/core/profile/service/1.0",
"id": "idc2922c137c7a58",
"fields": {
"profileName": "Basic access level",
"name": "Basic",
"scopes": [
"repo"
]
},
"relations": {
"app": "idglobals"
}
},
{
"apsType":"http://aps-standard.org/samples/github/license/1.0",
"type": "http://aps-standard.org/types/core/profile/service/1.0",
"id": "idc2922c137c7a60",
"fields": {
"profileName": "Premium access level",
"name": "Premium",
"scopes": [
"repo",
"delete_repo"
]
},
"relations": {
"app": "idglobals"
}
}
],
"resellerProfiles": [{
"id": "idcced499b78e4d8",
"apsType": "http://aps-standard.org/samples/github/reseller/1.0",
"type": "http://aps-standard.org/types/core/profile/reseller/1.0",
"fields": {
"login": "login",
"passwd": "passwd"
},
"relations": {
"app": "idglobals"
}
}],
"resourceTypes": [
{
"name": "GitHub Integration Demo - App REF",
"id": -500001,
"resClass": "rc.saas.service.link",
"required": true,
"actParams": {
"app_id": "idOAID",
"resource_uid": "idglobals"
}
},
{
"name": "GitHub Integration Demo - Basic access level",
"id": -500002,
"resClass": "rc.saas.service.link",
"required": false,
"rtfor": "http://aps-standard.org/types/core/profile/service/1.0",
"actParams": {
"resource_uid": "idc2922c137c7a58"
}
},
{
"name": "GitHub Integration Demo - Premium access level",
"id": -500004,
"resClass": "rc.saas.service.link",
"required": false,
"rtfor": "http://aps-standard.org/types/core/profile/service/1.0",
"actParams": {
"resource_uid": "idc2922c137c7a60"
}
},
{
"name": "GitHub Integration Demo - Tenant Environment",
"id": -500005,
"resClass": "rc.saas.service",
"required": true,
"actParams": {
"service_id": "tenants",
"autoprovide_service": 1
}
},
{
"name": "GitHub Integration Demo - Value added reseller",
"id": -500006,
"resClass": "rc.saas.service.link",
"required": false,
"rtfor": "http://aps-standard.org/types/core/profile/reseller/1.0",
"actParams": {
"resource_uid": "idcced499b78e4d8"
}
}
],
"serviceTemplate": {
"id": -600001,
"name": "GitHub Integration Demo",
"resources": [
{
"limit": 1,
"unlimited": false,
"rtID": -500001
},
{
"limit": 0,
"unlimited": false,
"rtID": -500002
},
{
"limit": 0,
"unlimited": false,
"rtID": -500004
},
{
"limit": 1,
"unlimited": false,
"rtID": -500005
},
{
"limit": 1,
"unlimited": false,
"rtID": -500006
}
]
},
"billing": {
"planCategory": {
"id":-21,
"name": "GitHub Integration Demo",
"description": "Testing the integration with the GitHub API"
},
"salesCategory": {
"id":-22,
"inCCP": true,
"name": "GitHub Integration Demo",
"expand": true,
"description": "Testing the integration with the GitHub API"
},
"resourceCategory": {
"id":-23,
"optional": false,
"name": "GitHub Integration Demo",
"description": "Testing the integration with the GitHub API",
"displayType": "radio"
}
},
"servicePlans": [
{
"name": "GitHub Integration Demo - Basic Access Level",
"id": -20,
"stId": -600001,
"shortDescription": "GitHub Integration - Basic Access Level",
"longDescription": "Testing the integration with the GitHub API - Basic Access Level",
"planBillingPeriod": 1,
"renewOrderInterval": 0,
"renewPointDays": 0,
"subscrPeriodType": 2,
"subscrRefundType": 0,
"subscrPeriod": 1,
"subscrRenewalFee": 0,
"subscrRecurringFee": 4.25,
"subscrDepositFee": 0,
"subscrTrial": false,
"subscrSetupFee": 2.0,
"subscrTransferFee": 0,
"resources": [{
"id": -700002,
"rtID": -500002,
"inCP": true,
"instore": true,
"incl": 3,
"min": 3,
"max": -1,
"sFeePerUnit": true,
"rFeePerUnit": true,
"setupFee": 0,
"recFee": 1.5,
"overFee": 2,
"measurable": false
}]
},
{
"name": "GitHub Integration Demo - Premium Access Level",
"id": -21,
"stId": -600001,
"shortDescription": "GitHub Integration - Premium Access Level",
"longDescription": "Testing the integration with the GitHub API - Premium Access Level",
"planBillingPeriod": 1,
"renewOrderInterval": 0,
"renewPointDays": 0,
"subscrPeriodType": 2,
"subscrRefundType": 0,
"subscrPeriod": 1,
"subscrRenewalFee": 0,
"subscrRecurringFee": 4.25,
"subscrDepositFee": 0,
"subscrTrial": false,
"subscrSetupFee": 2.0,
"subscrTransferFee": 0,
"resources": [{
"id": -700004,
"rtID": -500004,
"inCP": true,
"instore": true,
"incl": 3,
"min": 3,
"max": -1,
"sFeePerUnit": true,
"rFeePerUnit": true,
"setupFee": 0,
"recFee": 2.5,
"overFee": 3.0,
"measurable": false
}]
}
]
}
}
In the scripts/app.php
file, find the app
class definition and add the getInitWizardConfig
method
inside it:
/**
* @verb(GET)
* @path("/getInitWizardConfig")
* @access(admin, true)
* @access(owner, true)
* @access(referrer, true)
*/
public function getInitWizardConfig()
{
$myfile = fopen("./wizard_data.json", "r") or die("Unable to open file!");
$data = fread($myfile,filesize("./wizard_data.json"));
fclose($myfile);
return json_decode($data);
}
This method returns the contents of the scripts/wizard_data.json
file created in the previous step.
In the same app
class, add the testConnection
method as follows:
/**
* @verb(GET)
* @path("/testConnection")
* @param(object,body)
* @access(admin, true)
* @access(owner, true)
* @access(referrer, true)
*/
public function testConnection($body)
{
return "";
}
The above configuration makes the APS package ready for the final Create Products for Sale step in the deployment phase. But before going to that step, you must prepare the APS package for the APS application deployment as the next section explains.
The APS package must provide some data to be used for deploying an APS connector. The best practice is to install an APS connector from an image using the Docker virtualization technology as explained in this document.
Let us look at the deployment schema in more detail taking into account the Docker technique.
In this schema, every APS connector is functioning inside its own Docker container. The latter must be installed from an image stored in the Docker registry. The management node must be aware of the Docker registry address to be used for deploying Docker containers. During installation, the management node is configured to use the default Docker registry supported by the APS team.
When preparing an APS application for deployment, you must have access to a Docker registry where you are going to save the APS application image that the system will use during the application deployment.
In the platform configuration, check the Docker registry connection parameters configured currently. For this, in the provider control panel, navigate to System > Settings and in the Integration section click on the Docker Registry Settings link. You will find the domain name or IP address of the Docker registry, as in the example below:
You should replace it with a Docker registry available for your development environment
and for the platform you are going to use. In most cases, it must be the Docker official hub docker.io
.
To upload your APS application images there, you should have an account registered
at Docker Hub.
In the following examples, we suppose that the account name (login) is “isv1”.
With these assumptions, do the following:
In addition to the OSS management node, the deployment schema contains a separate endpoint host based on a virtual machine or a physical server for installation of APS connectors inside Docker containers. If your platform does not have it yet, follow the below instructions in this section to register such a node.
The endpoint host must meet the following requirements:
The CentOS-7 operating system is on it.
The SELinux
service is disabled as explained in the respective CentOS
document.
The host must be available for the management node on its backend interface.
It must have access to the Docker registry that provides the necessary images for installing Docker containers.
There is no Docker engine on the host, since you will add it during the service node registration as explained in the next section.
The following instruction helps you register your CentOS-7 host as an APS Endpoint Node:
In the provider control panel, navigate to Infrastructure > Service Nodes.
Click Add New Node.
Select the APS Endpoint Node role.
Enter the host name and authentication parameters:
Click Next.
Configure the other parameters:
Optionally, assign a convenient Hostname
Specify the Backnet IP address
Wait for a couple of minutes until the management node adds the server as a service node and installs the Docker engine on it.
The best way to deploy the provisioning (backend) logic of an APS application in the platform is to use a Docker image of the backend part (APS connector contents) of the APS application. To create an image, you will need to use the Docker engine in one of these two ways:
Use the Docker engine on the APS endpoint host that you have registered already in the platform. In this case, you do not need to install the Docker engine on your local computer.
Install the Docker engine on the same computer you use for development. For example, follow the Install Docker on CentOS document to install the Docker engine in CentOS.
The project template
includes the deploy-image/
folder that contains the
Apache with APS PHP framework configuration
structure in the etc/
folder and data structure in the var/
folder. This typical data set
makes APS provisioning scripts available on the /endpoint/
alias.
The Docker build command will use the Dockerfile
configuration, the deploy-image/
contents,
and the APS application scripts/
contents to build an image containing the APS application provisioning logic,
that is the APS application connector image.
Follow these steps to create an image:
Ensure the whole project package is on the host that has the Docker engine, for example, by copying it to the host registered as the endpoint service node:
$ scp -r github root@docker-endpoint.a.isv1.apsdemo.org:
In the host where the Docker engine is running, change your current directory to the github/
folder,
that is the top folder of your project.
Run the Docker build command to build an image locally:
# docker build -f deploy-image/Dockerfile -t isv1/github:1.0-0 .
Note
1. The “isv1” prefix is a placeholder for your actual account registered at the Docker official hub.
2. The image tag version, for example, 1.0-0
, must be the same as the APS package version specified
in the APP-META.xml
file.
3. Do not miss the dot .
at the end of the command. It specifies the current folder as
the Docker build context.
Log in to the Docker hub:
# docker login ## You will be prompted for the login name (for example, "isv1") and password
Push the image to the Docker registry:
# docker push isv1/github:1.0-0
Note
Do not forget to replace “isv1” with your actual account at the Docker hub.
Build your APS package on a computer with the installed APS tools and APS PHP runtime. Change your current directory one level above the project folder and build the APS package, for example:
# cd ..
# aps build github/
Import the APS package to the platform as follows.
Log in to the platform Provider Control Panel (PCP). For example, if the OSS management node is a.isv1.apsdemo.org, enter http://a.isv1.apsdemo.org:8080 in the browser address field. Log in as admin.
In PCP, navigate to Services > Applications and click Import Package.
Browse your local storage for the APS package, select it, and then click Submit to import the package to the platform. Click the Refresh icon on top right of the screen.
You will see the imported application on the bottom of the list.
In PCP, follow these steps to deploy an APS application instance.
Open the imported application and on the Instances tab, click Add Instance.
Make sure the following deployment options are chosen:
The Automatically deploy application’s backend option is selected
The Accept the impersonation level box is checked:
Click Next and configure the GitHub access parameters:
Click Next and then Finish.
Wait until the new instance appears and its status is Ready periodically refreshing the screen contents by clicking the Refresh button in the upper right corner.
If it takes longer than 2 minutes, navigate to Operations > Tasks to clarify the cause of the delay.
A service template and the service plan based on it are used to create subscriptions for customers. A service template must contain all resource types representing the application services defined in the APS package. Every resource type is limited or unlimited in a service template.
The root app
service of the APS application contains the getInitWizardConfig
method that
returns the default configuration of the products to be sold, including all of the components mentioned above.
To use the wizard, open the imported APS package on the Instances tab and click the Configure Product button.
Follow the wizard steps as explained here.
In the Application Instance Selection step, ensure that your demo application instance is selected.
In the Application Instance Settings step, the application access parameters must show up again in case
you want to change them.
You can click the Test connection button.
This calls the testConnection
method you have configured in the app
service.
In the Service Profiles step, you will find the two license resources you have configured in your default product configuration:
In the Service Template step, find the default service template configuration proposed by the application:
In the Billing Configuration step, leave all settings intact.
In the Service Plans step, ensure there are the expected two service plans as in the default configuration:
Also, open those service plans one by one to ensure every plan contains only one resource rate representing a license.
In the Summary step, review the final configuration of the service template and click Finish.
The new service plans must appear in the list of service plans. To verify this, switch to the BSS provider control
panel and navigate to Products > Service Plans. Open the new service plans one by one and make sure
their configuration corresponds to the default configuration the APS application package provides in the
scripts/wizard_data.json
file, for example:
You have created an APS application package and a Docker image of the respective APS connector. You used these things to deploy the application on the platform and then configured two application-based products for sale. Now the system is ready to provision the application services to customers.