Implementation Roadmap

This page explains the steps you need to take for delivering a service manager for your recurring services at a fixed cost. Each step comes with links to our official knowledge base that explain the flows and the functionality of each step as well as with links to the implementation guide for the related endpoints.

Step #1 – Register your application

To start integrating a new external provisioning system via the Service Management API, you must first register the new application so that it becomes available on the Applications Set-Up page. This creates the ‘shell’ of the implementation that will be hosted in the platform. The definition of the service manager will follow next.

For the detailed process of registering your application, please, click here.

Step #2 – Implement your Authentication Mechanism

It is crucial to define how each instance of your Service Manager (either within the same platform tenant or across different ones) will be authenticated against the vendor’s provisioning engine.

For example, imagine a vendor who issues credentials for each distributor that needs to access their API so that the vendor can understand who is using that API. Those credentials will be configured at this step in a way that when the instance of the platform is set up, and the API is called, the vendor can identify the request and respond appropriately. It is essential to remember that the same vendor may use the same set of credentials for the same distributor across all vendor infrastructure or issue different credentials that the same distributor will use for different infrastructures. 

For the detailed process of using the authentication endpoint to authorize the calls to the integration service, please check here.

Step #3 – Define your Product Catalog

You are now ready to define your product catalog. You should start by defining your services using a product type for each service. The product type is the most fundamental entity for determining a service in our platform. It establishes the properties and attributes of the service that affect the provisioning, billing, and ordering aspects of services on the platform. Then, you will need to define the plans of your services. This is done in our platform by defining products that belong to a specific product type.

For a detailed explanation of how our platform manages the recurring products, please check the Defining your Product Catalog page.

When you have a good understanding of how you can describe your products in our platform, you can then check the Get Services Definition Endpoint page for the implementation details.

Step #4 – Managing your Customers

Subscriptions are usually purchased by customers. The customer entity (called ‘Account‘ at our platform nomenclature) will need to be synchronized with your system. This means that a specific account in BSS needs to be linked to a particular entity in your system.

In our platform, to create an account, you need to fill in some mandatory fields of information. Similarly, there may be some such prerequisites before creating an account entity in your system. Those prerequisites are called ‘Synchronization Options’ at interworks.cloud platform jargon and they should be defined in the “Get Account Synchronization Options” endpoint. For example, when a customer buys a Microsoft O365 subscription, Microsoft needs a unique ‘domain’ before creating the tenant (Microsoft account). So, the domain has been defined as one of Microsoft’s account synchronization options.

The customer will be created in your system when this customer places his first order or when the account manager will manually synchronize him. In both cases, the “Account Synchronize” endpoint will be called for creating the customer in your system.

There are two more endpoints you will need to implement:

• Account Delete: This endpoint is called when an account is deleted in our platform. Whether you will also delete it, or archive it, or ignore the call it is up to you.
• Account Exists: The purpose of this endpoint is to determine whether an account already exists in your system. This is endpoint is used before every provisioning action we will perform for confirming that the customer is still valid in your system.

Implementation details for the endpoints explained above can be found in Customers Management Endpoints

Step #5 – Managing Distributor Resellers

The way you distribute your services directly impacts the configuration of your service manager as it is related to how the various involved parties are synchronized with each other. If you offer a distribution program (tier 2 model), your distributors will sell your services using their resellers. Our platform allows the resellers of a distributor to place orders on behalf of their customer in the Distributor’s Storefront.

Depending on your underlying implementation, you may need to synchronize the resellers with your system or keep track of which end-customer belongs to which reseller. For both scenarios, the implementation details are described in Resellers Provisioning.

Step #6 – Provision the Services to the Customers

A recurring service bought by a customer is presented as a subscription on our platform. The subscription entity handles:

• The generation of recurring invoices along with the terms that have been defined on the customer of the subscription and the product of the subscription
• The provisioning life-cycle management between the platform and the vendor’s provisioning application (initial provisioning of the service, resources amendment, cancellations etc.)

Our Service Manager API includes a set of Subscriptions and Add-ons endpoints that are called when a subscription is created or modified in our system.

Initial Provisioning of a Service

In our system, a subscription is created when an order for a recurring service is executed either from an account manager in BSS Portal or from the customer in the Storefront. More specifically, when a subscription is created:

• The billing elements defined on the account (e.g. billing and payment information) and product levels (price, billing cycle, etc.) are brought together according to the parameters of the specific order
• Our system transmits the instructions for what needs to be provisioned to your service manager.
• The provisioning process is initiated and the service is made available.

The subscription creation is the trigger for calling your service manager implementation to provision the service to your system. We call the “Subscription Create” endpoint, where all the necessary information is passed to your service manager for understanding what the customer has purchased.

For getting familiarized with the ordering process in our system, you can check the training videos “Placing a new Order” and “Ordering on Behalf of your Customers” on the page Training Videos on Ordering. Although these videos are specific for the Microsoft cloud services, they will help you understand the ordering flow and when the actual provisioning of the services takes place.

Modifying the Service Licenses and Resources

The customer or the account manager can modify a subscription in our system for:

• Increasing or descreasing the licenses. The available licenses a customer has purchased are the subscription quantity and they can be modifed by both the account manager or the customer. We call the “Subscription Update” endpoint when the licenses are updated.
• Add or cancel an add-on. An add-on in our platform reflects an additional feature or option that can be enabled on top of the main service of a subscription, enhancing or complementing the main service. We call the endpoints “Addon Create” and “Addon Cancel” for informing your system for addition or cancellation of addons for the primary service.
• Increasing or decreasing the add-on licenses. If an add-on supports user licenses, the add-on quanity is the purchased licenses and they can be modified by both the account manager or the customer. We call the “Addon Update” endpoint when the addon licenses are updated.

For getting familiarized with the subscription management process in our system, you can check the training videos “Buying Extra Licenses or Add-ons for their Subscriptions” and “Managing Customer Subscriptions” on the page Training Videos on Ordering. Although these videos are specific for the Microsoft cloud services, they will help you understand the subscription management flow.

Services Trials

Our platform support trials for the customers to test a product before buying it. If you offer trials for your services, you should implement the following:

• Define for which of your products you offer a trial. This is done as part of the definition of your product catalog (step 2), and it can be done if you decide to create your products automatically.
• Provisioning of a trial subscription. When a customer requests a trial, we create a trial subscription and the “Subscription Create” endpoint is called with the IsTrial option enabled.
• Upgrade a trial subscription to a paid one. When the customer or the account manager upgrades a trial subscription to a paid one, we will call the “Subscription Upgrade to Paid” endpoint to inform your system about the upgrade.

Subscription Status Change

To accommodate various business workflows, the subscription can assume various states, each reflecting a specific condition for the subscription: 

Status	Description
Active	A subscription that is under active billing and provisioning. Active subscriptions produce regular invoices according to their billing terms and allow for life-cycle management actions between the platform and the provisioning application (e.g., increase or decrease licenses, suspend or cancel the subscription, etc.)
Inactive	A subscription that is not active due to some ongoing process. The subscription will not issue invoices, nor will any action be transmitted to the provisioned application.
Canceled	A subscription that has been terminated (meaning that both billing and provisioning are effectively discontinued) and cannot be reactivated. Our platform supports the following cancellation flows: – Immediate cancellation without approval: A customer can cancel his subscription with immediate effect. – Cancellation of a subscription at the end of the current billing cycle without approval. A customer can schedule his subscription not to be renewed but canceled when the current billing cycle ends. – Immediate or Scheduled Cancellation with approval. The above two scenarios with the difference that the cancellation request must be approved first by the customer’s account manager. You don’t need to consider these flows when you implement the “Subscription Cancel” endpoint since we will call your service manager only when the actual cancellation of the subscription takes place.
Suspended	a subscription that has a suspended provisioning connection but active billing. The invoices will be issued as usual.

Whenever a subscription changes status in our platform, the corresponding endpoint is called to inform your system about the status change. You will need to implement all these endpoints for reflecting correctly in your system the current status of the subscription.

Implementation details for the endpoints explained above can be found in Subscription Management Endpoints and Addon Management Endpoints.

Step #7 – Business Rules Implementation

If you have business flows/gaps that our platform cannot support, you will need to include these rules in your implementation. Although we continuously introduce new options for supporting new business rules in our platform, it is not always possible to cover all the business rules you might need for your service. For this reason, we have introduced the pre-check mechanism that could be used to evaluate and enforce your custom business rules before any actual provisioning action takes place.

The following list presents some common examples of business rules that the pre-check mechanism can cover:

• There should be only one active subscription per customer for your service.
• The service should not be activated if X service (i.e.,prerequisite service) is not already activated for the customer
• the number of licenses should not be more than X
• the number of licenses should not be less than X
• A subscription cannot be cancelled after X days from the intial purchase

You can check the Pre-Check Mechanism for details on how to enforce your business rules.