Partner Integration Scenarios

This is a set of procedure guides for partners (known as resellers in the platform) of various levels that need to manage and sell cloud products through the platform using its public APS API. In particular, this is for developers who integrate various external management systems owned by partners with the platform. Some examples of such management systems are:

• E-Commerce (Marketplace)

• CRM Account & User Data

• CRM Subscription Management & Notifications

These end-to-end scenarios are based on the Using Platform Services examples that illustrate the management procedures for various parts of the platform.

Prerequisites

If you are a developer responsible for integrating an external management system with the platform, the procedure guides will be more helpful in your project life-cycle if you first study the platform concepts by reading the recommended documents below.

Documents to Study

• API Overview introduces the platform and its integration with applications and external management systems through the platform built-in RESTful API exposed as APS bus.

• Platform Data Models is an introduction to the concepts of the platform for integrators and application developers. The concepts explain the two platform parts - Operations Support System and Business Support System.

• Platform guides explain in detail the interactions between the provider and resellers on the one hand and the reseller and customers on the other hand.

Account Hierarchy

• The Provider is the owner of the platform.

• A Reseller is a direct or indirect partner of the provider; a direct partner is a layer one reseller (L1 reseller) that can have its own resellers (L2 reseller); the L2 reseller is then considered as an indirect partner; and so on. Typically, resellers resell service plans delegated to them by the provider.

• A Customer is a subscriber to service plans.

Product Components

• A Service plan is a product to sell or resell. If a service plan is used to sell cloud application services, those services are presented by resources in the service plan.

• The price in a service plan is made up of various components, for example:

  • The price assigned to various subscription periods as fixed setup and recurring (periodic) fees.

  • Rated fees assigned to some of the resources in the service plan by means of resource rates, for example, on the basis of the “pay as you go” billing model.

• Resources in a service plan and APS resources are two different things. The former are used to represent the latter in sales processes, and the latter represent real application services. Outside of service plans, APS resources represent various platform services and resource collections.

• A Subscription is an agreement between the reseller and a customer when the latter buys a service plan for a certain period. Technical, a service plan instantiates multiple subscriptions.

APS API Concepts

Ensure you understand the following most important API concepts for the scenarios considered here:

• APS bus is a RESTful endpoint exposed by the platform built-in APS controller. This is the only point at which the external systems can interact with the platform.

• All objects managed through the APS bus are APS resources based on APS types. Every APS type is a JSON schema that defines properties and operations to create and manage APS resources. An APS type also defines relationship with APS resources based on other APS types.

• All requests on the APS bus must comply with the API Reference including the following specifications:

  • APS controller operations as a general definition of operations supported by the APS controller

  • Platform services and resource collections

  • Platform Types that expose various platform services on the APS bus

  • HTTP Headers as a part of the REST protocol to be used in these scenarios

Setting Partnership

To establish a partnership with other companies, the provider must create a special service plan that partners subscribe to in order to get a reseller subscription and through it a partnership contract with the provider. In the same way, a partner can establish a partnership with its own sub-resellers.

In the scenarios considered in this set of documents, we will deal with a test reseller whose external management system will use the necessary API operations. Since it will be the same reseller in all scenarios, it will be referred to as the reseller.

Managed Components

A reseller account in most part is similar to the provider account in the way that it manages a similar set of objects:

• Own staff and service users

• Sub-resellers and customers

• Resource types and resources created in the platform

• Service templates

• Service plans that customers and sub-resellers can subscribe to

• Various other business support objects

A reseller can use the following user panels:

• The classical Reseller Control Panel (RCP) with a separate access to the Operations Support System (OSS) and Business Support System (BSS)

• The unified panel (UX1) with incorporates management of OSS and BSS components

In these scenarios, we do not pay much attention to the management technique provided by the user panels, but rather use the latter as an assistance tool.

Using API

Getting API Clients Ready

The main focus in these scenarios is the use of the platform API to achieve typical management goals. The platform authenticates API requests using the OAuth-1.0 protocol that requires REST clients supporting this protocol. Of the preparatory steps, some steps must be done by the provider, and the others by the reseller:

• The HTTPS protocol must be used to send REST requests to the platform. The provider must configure the platform properly to enable this.

• An external system must authenticate itself as a reseller’s user with proper access to the APS bus and resources to be managed. The provider and the reseller must agree which user to use for it and what privileges that user must have. After that, the provider must configure that user and generate a pair of customer key and consumer secret (required by the OAuth authentication) for the user.

• The reseller’s user to be used for authentication must be granted the rights to call those custom operations that will be required in management scenarios. For the scenarios described in this set of documents, the following screenshot presents a list of APS type and method pairs allowed to call custom operations:

  

• Choose a REST Client for the testing phase and for production.

• (Optional) Instead of providing direct access to the platform, the provider can set up an external API gateway and share a gateway URL that the reseller must use to access the platform API.

API Requests

Regardless of which REST client you use, a REST request will look the same. Its typical components are the following, listed in the order that you need to write them:

METHOD URL

HEADER1 HEADER2 ...

{ /* Body */ }

• Method, also called verb, can be one of GET, POST, PUT, or DELETE. It specifies a required action, typically:

  • GET: read a list of APS resources or get details of a specified APS resource.

  • POST: create an APS resource.

  • PUT: configure (update) a specified APS resource.

  • DELETE: delete a specified APS resource.

• URL (uniform resource locator) follows the method to specify an APS resource or a group of APS resources followed by some optional parameters. For example, if the domain name of your access point to the platform (the provider must specify it for you) is reseller1.platform.example, then the method and URL for reading all APS resources will look as follows:

  GET https://reseller1.platform.example/aps/2/resources
  

  Note

  In all documents, we use a short URL omitting the first part of the full URL (host specific) and leaving only the APS specific part, so the previous request will look as follows:

  GET /aps/2/resources
  

  A URL can be appended with various optional parameters:

  • Filter parameters based on the Resource Query Language (RQL)

  • Custom operation path with query parameters as explained in the Operations document

• HTTP headers provide some metadata about the request. They can be those that are described in the HTTP RFC-723x specifications, for example, Authorization, and in the APS specific HTTP Headers document.

  Note

  In POST requests, always send the Content-Type:application/json header.

• Body is typically used by the POST and PUT methods to specify the properties of the APS resource they deal with. The data inside the body must be in the JSON format.

A response typically contains the following components:

RETURN CODE

HEADER1 HEADER2 ...

{ /* Body */ }

• The return code shows if the request was completed successfully or not. In the latter case, the return code is followed by a message referring to the cause of failure. The returned codes are described in the HTTP Responses section.

• HTTP headers provide some metadata about the response.

• Body contains the returned data in JSON format for some operations. Typically, it is returned in response to GET, POST and PUT requests.

You will find more examples of requests throughout relevant documents in this subset.

Environment Configuration

In the platform, the reseller must be configured as described here. Although the environment considered here is for demonstration purposes, a similar configuration can be used for your own scenario.

In order for the test scenarios to work, the following components are configured by the provider.

• A service plan (reseller service plan) is available for you to obtain the reseller status. That service plan is based on the following service templates:

  • Branding service template contains customer and sub-reseller resources

  • BSS service template includes some delegated service plans

• Your test reseller account is created by subscribing you to the reseller service plan.

• The test reseller is granted a credit of $1000 to enable the reseller to resell delegated service plans.

• A special customer class “Resellers” is created for resellers and the test reseller is added to it. We need it to set discounts to resellers for delegated service plans.

• At the provider level, a discount is bound to all service plans. Add the “Resellers” customer class to it.

• At the reseller level, a test discount is configured for all of the reseller’s customers.

• At the provider and reseller level, taxation is configured using a simple configuration:

  • Each plan category is bound to a single tax category

  • Taxation rules with a tax rate added to that tax category are applicable to the provider and reseller for all types of tax zones:

    • Provider-country

    • Provider-Other-State

    • World-Rest

  The taxation rules are presented in the following example:

  

• On both levels, the provider’s and the reseller’s, a bank card payment system is activated. For testing purposes, enable the Visa dummy payment system with the fake card number “4111111111111111” for the reseller and later for every reseller’s customer when they are created. For those bank cards, allow auto payments.

Before proceeding to the next document, test if you have access to the platform API with the credentials of the reseller’s administrator. For this purpose, send the GET request to read a list of all APS resources:

If you get the “200 OK” response, your REST API client is ready to interact with the platform API.

Checklist

Below is a recap of all the requirements covered above that you must check before proceeding to use the platform API.

Requirement	Parameters	How to check
Access to the platform UI	- URL - Login name - Password	Address your browser to the specified URL and use the login name and password to log in to the platform UI. Depending on your account configuration, you will enter either UX1 or the RCP.
Access to the platform API	- OAuth base URL - OAuth consumer key - OAuth consumer secret - Allowed custom operations	In the RCP, navigate to System > Users, open the user whose credentials must be used, switch to the APS Bus Access, and check that the user is correctly configured for APS bus access. Also, verify that the list of the required custom operations is complete. For more details, refer to Getting API Clients Ready.
REST client, for example, Insomnia	- SSL certification - Encoding of special symbols - Authentication method - HTTP header	If the server SSL certificate is not authorized, the SSL verification must be disabled. Create REST requests by duplicating them from a template request with the following configuration: - Encoding of special symbols is prohibited - OAuth-1.0a is configured as the authentication method - The Content-Type:application/json HTTP header is added to all requests For more details, refer to Getting API Clients Ready. Using the REST client, call a custom operation to ensure correct end-to-end configuration.
Reseller environment in BSS	- Automatic payment system - Taxation - Discounts for customers - Own balance or credit	System > Settings > Payment Processing System > Settings > Taxation Products > Marketing > Discounts System > My Reseller Status
Delegated service plans	- Taxation - Discounts	- In Products > Service Plans, verify the service plan configuration. - Test the taxation rules for the delegated service plans at System > Settings > Taxation > Test All Taxation Rules.

← Assign DNS Services

Product Identification →