Application Packaging Standard

Last updated 18-Mar-2019

Subscribe to Services¶

In this document:

Scenario
Source Data
Preliminary Inspection
Creating Objects
Conclusion

Scenario ¶

This is a more complex process in which you will subscribe your test customer to application services. The latter can be any services deployed by you or the application services used in this document.

../../../_images/sys-user-step-customer.png

../../../_images/sys-user-step-staff.png

../../../_images/sys-user-step-service.png

In this scenario, we will use the services of the demo application User Management that imitates a system providing virtual private servers (VPSes) for users. The following diagram presents components used in the platform for provisioning services to customers.

The application exposes the following APS types:

suwizard1p/cloud - presents the application itself and normally used to set connection parameters that allow the platform to set a network connection with the application cloud system.
suwizard1p/offer - used to create offers. Every offer contains a set of limits on VPS parameters, such as amount of memory and disk space. In the above diagram, there are Silver and Gold shared offers.
suwizard1p/context - used to create a singular management context for a customer. It must be linked with the application root resource and the customer who is the owner of the resource.
suwizard1p/vps - used to create VPSes. Every VPS must be linked with an offer that sets the upper limits on VPS properties.

In the above list, the provider uses the former two types to create shared APS resources with collection of links used by other resources. A customer subscribed to the application services uses the latter two types in the list to provision application resources.

A service template used to create subscriptions must contain the following resource types:

Resource types created from the Application Service Reference resource class and presenting the shared application APS resources with limits as shown in the above diagram.
Resource types created from the Application Service resource class and presenting the application APS types with limits as shown in the above diagram. Since there is limitation on the use of the offers, the limit on virtual servers is set to -1, which means “unlimited”.

We suppose that the provider has imported the application, created the APS connector and APS application instance, and also created the required resource types as explained in the Deployment section of the demo project.

In this scenario, you will go through the rest deployment and provisioning steps:

Create a service template.
Add the required resource types to the service template and assign a limit on each.
Subscribe the test customer to the service template, that is create a subscription.

Source Data ¶

The REST requests in this scenario will need the following source data.

Service Template Properties and Relationship¶

The following data is needed to create a service template.

APS type for the service template - http://parallels.com/aps/types/pa/serviceTemplate/1.1.

Service template properties - sample values are in the table below:

Property	Type	Sample value	Notes
`appIDs`	Array of APS IDs	[“http://aps-standard.org/samples/suwizard1p”]	An array of APS IDs of the applications whose services are presented in the service template.
`autoprovisioning`	Boolean	true	After a subscription is created, it runs automatically provisioning of the resources marked as `autoprovisioning:true`.
`name`	String	“Virtual servers for end-users”	Arbitrary name of the service template.

Service template relationship - a link with the provider APS ID who is the owner of the service template. Find the APS ID by sending the following request using the provider admin’s token:
```
GET /aps/2/resources?implementing(http://parallels.com/aps/types/pa/account/1.2),eq(id,1)
```
Sample response:
```
HTTP/1.1 200 OK

[{"aps":{..."id": "a87bac8c-071e-4809-88ed-29d4d095c48d",...},...}]
```

Resource Types¶

Identify the existing resource types of the targeted application that you must add to the service template. The following procedure is based on the fact that all resource types in the platform are included automatically to the built-in subscription #1 belonging to the provider.

Identify the APS ID of the subscription #1 using the APS type PASubscription and the provider admin’s token in the request:

GET /aps/2/resources?implementing(http://aps-standard.org/types/core/subscription/1.0),eq(name,License%20key)

The response must be similar to this:

HTTP/1.1 200 OK

[{
      "aps":
      {
         "type": "http://parallels.com/aps/types/pa/subscription/1.0",
         "id": "c11522da-b459-45b4-a944-f2fe418db84e",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2016-08-11T07:19:46Z"
      },
      "description": "Parallels Automation License Key",
      "disabled": false,
      "name": "License key",
      "serviceTemplateId": 0,
      "subscriptionId": 1,
      "trial": false
}]

Note

If you wish to find the subscription by its subscriptionId, then in the above request filter specify the platform Subscription type, which contains the subscriptionId definition:

GET /aps/2/resources?implementing(http://parallels.com/aps/types/pa/subscription/1.0),eq(subscriptionId,1)

Use the APS ID of the subscription in the next request.

Call the custom resources operation of the subscription #1:

GET /aps/2/resources/c11522da-b459-45b4-a944-f2fe418db84e/resources

Select the resources whose APS type belongs to the targeted application, that is the prefix of the APS ID is the same as the application ID, in our case - “http://aps-standard.org/samples/suwizard1p”:

HTTP/1.1 200 OK

[ ...
   {
      "id": "1000052",
      "title": "User Management - App REF",
      "apsId": "6b338fe2-c693-422a-9329-ed84b5a2dd9c",
      "apsType": "http://aps-standard.org/samples/suwizard1p/cloud/1.0",
      "usage": 0,
      "unit": "unit"
   },
   {
      "id": "1000053",
      "title": "User Management - Silver VPS Configuration",
      "apsId": "8c0e2f65-8968-43f6-97ca-93ed7b7df9d1",
      "apsType": "http://aps-standard.org/samples/suwizard1p/offer/1.0",
      "usage": 0,
      "unit": "unit"
   },
   {
      "id": "1000054",
      "title": "User Management - Gold VPS Configuration",
      "apsId": "be451aef-8035-436e-b30b-757852503d8d",
      "apsType": "http://aps-standard.org/samples/suwizard1p/offer/1.0",
      "usage": 0,
      "unit": "unit"
   },
   {
      "id": "1000055",
      "title": "User Management - Management Context",
      "apsType": "http://aps-standard.org/samples/suwizard1p/context/1.0",
      "usage": 0,
      "autoprovisioning": true,
      "unit": "unit"
   },
   {
      "id": "1000056",
      "title": "User Management - Virtual Server",
      "apsType": "http://aps-standard.org/samples/suwizard1p/vps/1.0",
      "usage": 0,
      "unit": "unit"
   }
   ...
]

Note

There are two kinds of resource types:

A resource type that contains the apsId property is created from the Application Service Reference resource class. Such a resource type refers to an APS resource belonging to the provider and used by all subscriptions. For example, it might be an offer containing limitation on server parameters.
A resource type that does not contain the apsId property is created from the Application Service resource class. Such a resource type is used to provision new resources for subscribers.

2. The management context resource type is marked as autoprovisioning:true. It means that as soon as a subscription is created for a customer the platform will start provisioning of the resource from this resource type automatically. This will be a singular resource used as the starter point for provisioning manually other resources for the customer.

Preliminary Inspection ¶

Before you start creating a new service template, verify if there is one with similar properties. The following examples provide typical use cases that narrow a list of requested objects by adding an RQL filter to a request (use the provider admin’s token).

Get a list of all service templates:

GET /aps/2/resources?implementing(http://parallels.com/aps/types/pa/serviceTemplate/1.1)

Get a list of service templates that contain the targeted application services.

GET /aps/2/resources?implementing(http://parallels.com/aps/types/pa/serviceTemplate/1.1),eq(appIDs,http://aps-standard.org/samples/suwizard1p)

If there is a match with the application, which services you are going to provide through the new service template, either preliminary modify the properties that you wish to be unique or use the existing service template.

Creating Objects ¶

At this step, you should create a service template, and then add the required resource types to it. Once you have the service template, subscribe your test customer to it.

Create Service Template¶

Create a service template linked with the provider APS ID through the account link:

POST /aps/2/resources/

{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/serviceTemplate/1.1"
   },
   "appIDs": [
      "http://aps-standard.org/samples/suwizard1p"
   ],
   "autoprovisioning": true,
   "name": "Virtual servers for end-users",
   "account": {
      "aps": {
         "link":"strong",
         "href":"aps/2/resources/a87bac8c-071e-4809-88ed-29d4d095c48d",
         "id":"a87bac8c-071e-4809-88ed-29d4d095c48d"
      }
   }
}

Typical response:

HTTP/1.1 200 OK

{
   "aps":
   {
      "type": "http://parallels.com/aps/types/pa/serviceTemplate/1.1",
      "id": "058d8840-40da-4e33-ae96-11632ac04ec4",
      "status": "aps:ready",
      "revision": 4,
      "modified": "2016-09-27T12:07:49Z",
      "package":
      {
         "id": "e86ef200-5751-4c2c-b342-e65483ede6d0",
         "href": "/aps/2/packages/e86ef200-5751-4c2c-b342-e65483ede6d0"
      }
   },
   "autoprovisioning": true,
   "name": "Virtual servers for end-users",
   "serviceTemplateId": 3,
   "account":
   {
      "aps":
      {
         "link": "strong",
         "href": "/aps/2/resources/a87bac8c-071e-4809-88ed-29d4d095c48d",
         "id": "a87bac8c-071e-4809-88ed-29d4d095c48d"
      }
   },
   "resources":
   {
      "aps":
      {
         "link": "collection",
         "href": "/aps/2/resources/058d8840-40da-4e33-ae96-11632ac04ec4/resources"
      }
   }
}

The newly created service template does not have any resource types inside it yet.

Add Resource Types to Service Template¶

Call the addLimit operation of the service template resource to add the above resource types one by one. Use the source data collected earlier.

Add the Application Service Reference resource type that presents the application instance.

POST /aps/2/resources/058d8840-40da-4e33-ae96-11632ac04ec4/limits

{
   "id": "1000052",
   "title": "User Management - App REF",
   "apsId": "6b338fe2-c693-422a-9329-ed84b5a2dd9c",
   "apsType": "http://aps-standard.org/samples/suwizard1p/cloud/1.0",
   "applicationId": "http://aps-standard.org/samples/suwizard1p",
   "limit": 1,
   "unit": "unit"
}

Typical response:

HTTP/1.1 200 OK

{
   "id": 1000052,
   "title": "User Management - App REF",
   "apsId": "6b338fe2-c693-422a-9329-ed84b5a2dd9c",
   "apsType": "http://aps-standard.org/samples/suwizard1p/cloud/1.0",
   "unit": "unit",
   "limit": 1,
}

Add the Application Service Reference resource types that present the offers. We discovered two offers in the earlier request - silver and gold. This is an example of adding the silver offer with limit 10:

POST /aps/2/resources/058d8840-40da-4e33-ae96-11632ac04ec4/limits

{
   "id": "1000053",
   "title": "User Management - Silver VPS Configuration",
   "apsId": "8c0e2f65-8968-43f6-97ca-93ed7b7df9d1",
   "apsType": "http://aps-standard.org/samples/suwizard1p/offer/1.0",
   "limit": 10,
   "unit": "unit"
}

Typical response:

HTTP/1.1 200 OK

{
   "id": 1000053
   "title": "User Management - Silver VPS Configuration"
   "apsId": "8c0e2f65-8968-43f6-97ca-93ed7b7df9d1"
   "apsType": "http://aps-standard.org/samples/suwizard1p/offer/1.0"
   "unit": "unit"
   "limit": 10
}

Use the same way to add the gold offer with limit 5.

Add the management context resource type that must invoke the automatic provisioning:

POST /aps/2/resources/058d8840-40da-4e33-ae96-11632ac04ec4/limits

{
   "id": "1000055",
   "title": "User Management - Management Context",
   "apsType": "http://aps-standard.org/samples/suwizard1p/context/1.0",
   "limit": 1,
   "autoprovisioning": true,
   "unit": "unit"
}

Typical response:

HTTP/1.1 200 OK

{
   "id": 1000055,
   "title": "User Management - Management Context",
   "apsType": "http://aps-standard.org/samples/suwizard1p/context/1.0",
   "autoprovisioning": true,
   "unit": "unit",
   "limit": 1
}

Add the unlimited virtual server resource type:

POST /aps/2/resources/058d8840-40da-4e33-ae96-11632ac04ec4/limits

{
   "id": "1000056",
   "title": "User Management - Virtual Server",
   "apsType": "http://aps-standard.org/samples/suwizard1p/vps/1.0",
   "limit": -1,
   "unit": "unit"
}

Typical response:

HTTP/1.1 200 OK

{
   "id": 1000056,
   "title": "User Management - Virtual Server",
   "apsType": "http://aps-standard.org/samples/suwizard1p/vps/1.0",
   "unit": "unit"
}

Now you have a service template that the provider can use to subscriber customers to the application services. Verify it by sending the GET request:

GET /aps/2/resources/058d8840-40da-4e33-ae96-11632ac04ec4/limits

Create Subscription¶

Create a subscription based on the platform Subscription APS type. The request must specify the service template from which the subscription must be created and the customer that will be the subscription owner:

POST /aps/2/resources/

{
  "aps": {
    "type": "http://parallels.com/aps/types/pa/subscription/1.0"
  },
  "serviceTemplateId": 3,
  "name": "Virtual servers for end-users",
  "description": "Testing service assignment REST interface",
  "account": {
      "aps": {
         "id": "09534506-d795-4a36-bb3d-d2865806dbf5"
      }
   }
}

Typical response:

HTTP/1.1 200 OK

{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/subscription/1.0",
      "id": "c315f4a9-1e00-4458-b3e9-95de5659b3d7",
      "status": "aps:ready",
      "revision": 5,
      "modified": "2016-09-28T08:07:49Z",
      "package": {
         "id": "e86ef200-5751-4c2c-b342-e65483ede6d0",
         "href": "/aps/2/packages/e86ef200-5751-4c2c-b342-e65483ede6d0"
      }
   },
   "description": "Testing service assignment REST interface",
   "disabled": false,
   "name": "Virtual servers for end-users",
   "serviceTemplateId": 3,
   "subscriptionId": 9,
   "trial": false,
   "account": {
      "aps": {
         "link": "weak",
         "href": "/aps/2/resources/80e4a8ff-b14d-482c-b307-3d5c6ad9d67d",
         "id": "09534506-d795-4a36-bb3d-d2865806dbf5"
      }
   },
   "services": {
      "aps": {
         "link": "collection",
         "href": "/aps/2/resources/c315f4a9-1e00-4458-b3e9-95de5659b3d7/services"
      }
   },
   "websites": {
      "aps": {
         "link": "collection",
         "href": "/aps/2/resources/c315f4a9-1e00-4458-b3e9-95de5659b3d7/websites"
      }
   }
}

The system may take noticeable time to create a new subscription, especially when some of the resources must be auto-provisioned. Verify if the subscription is ready by calling its provisioningState custom operation:

GET /aps/2/resources/c315f4a9-1e00-4458-b3e9-95de5659b3d7/provisioningState

If the subscription was provisioned successfully, the response will be:

HTTP/1.1 200 OK

{
   "state": "SUCCESS",
   "message": ""
}

Your test customer is now subscribed to the application services. Its admin is able to create VPSes and assign them to service users.

Conclusion ¶

Following the above steps, you successfully created a service template containing the resource types presenting services of a cloud application and then you subscribed your customer to the services.

You can use additional verification of those operations:

Use the REST requests described in the Preliminary Inspection to find the newly created service template.

Verify if the new subscription is available for the customer. For example, if the service template ID is 3, use the customer admin’s token to send:

GET /aps/2/resources?implementing(http://parallels.com/aps/types/pa/subscription/1.0),eq(serviceTemplateId,3)

The response must be similar to:

HTTP/1.1 200 OK

[{
    "aps": {
       "modified": "2016-09-28T08:19:56Z",
       "id": "c315f4a9-1e00-4458-b3e9-95de5659b3d7",
       "type": "http://parallels.com/aps/types/pa/subscription/1.0",
       "status": "aps:ready",
       "revision": 3
    },
    "name": "Virtual servers for end-users",
    "serviceTemplateId": 3,
    "description": "",
    "disabled": false,
    "subscriptionId": 9,
    "trial": false
}]

Also, you can open the customer control panel (CCP) to verify if the application is presented in the navigation menu.

Table Of Contents

Application Packaging Standard

Subscribe to Services¶

Scenario¶

Source Data¶

Service Template Properties and Relationship¶

Resource Types¶

Preliminary Inspection¶

Creating Objects¶

Create Service Template¶

Add Resource Types to Service Template¶

Create Subscription¶

Conclusion¶

Scenario ¶

Source Data ¶

Preliminary Inspection ¶

Creating Objects ¶

Conclusion ¶