Pre-check Mechanism

Introduction to the Pre-Check Mechanism

To make things easier, you will not need to implement new endpoints. Instead, you will only need to define which endpoints require a pre-check action. However, it is important to note that when an endpoint runs on “precheck” mode, no provisioning actions should be executed, and the process will continue only if our platform gets no error from the precheck call.

What kind of business rules should be evaluated?

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

• 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

Examples for supporting such scenarios can be found in the Use case section of our documentation.

Understanding the Pre-Check Mechanism

The following process is followed for endpoints supporting pre-check actions:

1. When a BSS user or a customer performs an action that triggers an pre-check-supported endpoint, that endpoint is called by setting the parameter “checkonly:true“ to get any errors that might be returned from the service manager.
2. If no error occurs, we proceed with the actual call by calling the endpoint with the parameter “checkonly:false“.
3. If a “precheck” action returns an error, we display that error and not proceed to any other call.

So, for the endpoints that support pre-check, you need to implement two modes:

• When the parameter checkonly=true is passed, your implementation must check only if the business rules you want to enforce are valid or not.
• When parameter checkonly=false is passed, your implementation must do the actual provisioning.

Check the section “Setting up the Pre-Check Mechanism” below for more details.

Setting up the Pre-Check Mechanism

You should first define for which endpoints you need to run pre-checks before the provisioning actions. Then, you should implement the “precheck” mode of your endpoints.

For endpoints with activated pre-check, the CheckOnly flag is used in the endpoints request body to distinguish whether an API call is performed by the interworks.cloud Platform for pre-check or actual provisioning purposes.

Defining which Endpoints Support Pre-Check

The pre-check feature can be enabled through BSS > Setup > Administration > System Options > Applications Setup > {My Application} > Edit Integration page under ‘Pre Check’ section:

Clicking inside the input box will reveal the list of available endpoints for which the pre-check feature can be enabled:

You can select one or more endpoints that you want the pre-check feature to be enabled for:

Pre-check can be activated in the following endpoints:

• Subscription Create URL
• Subscription Update URL
• Subscription Activate URL
• Subscription Suspend URL
• Subscription Cancel URL
• Subscription Upgrade/Downgrade URL
• Subscription UpgradeToPaid URL
• Addon Create URL
• Addon Update URL
• Addon Cancel URL
• Asset Create URL
• Asset Update URL
• Asset Cancel URL 

When the Pre-check mechanism is Triggered

The pre-check request is triggered for an endpoint when the action performed by a BSS user or a customer includes a provisioning action for the selected endpoint. The API call to the endpoint for the pre-check purposes (CheckOnly=true) is performed before any data changes are performed in interworks.cloud Platform.

Trigger Events for the Pre-check actions in BSS

For subscriptions that are supported by your Service Manager, the following actions performed by a BSS user can trigger the precheck calls:

• Creation of a new subscription (either via the execution of an order or when a BSS user creates manually a new subscription) → precheck of the “Subscription Create” endpoint
• Creation of a new trial subscription → precheck of the “Subscription Create” endpoint
• Saving an existing subscription → precheck of the “Subscription Update” endpoint
• Suspension of an active subscription → precheck of the “Subscription Suspend” endpoint
• Cancellation of an active subscription → precheck of the “Subscription Cancel” endpoint
• Increase or decrease of subscription quantity → precheck of the “Subscription Update” endpoint
• Upgrade or Downgrade a subscription → precheck of the “Subscription Upgrade/Downgrade” endpoint
• Upgrade to paid of a trial subscription → precheck of the “Subscription UpgradeToPaid” endpoint
• Addition of a new addon (either via the execution of an order, or when a BSS user adds manually an add-on to an existing subscription) → precheck of the “Addon Create” endpoint
• Increase or decrease of addon quantity → precheck of the “Addon Update” endpoint
• Cancellation of an addon → precheck of the “Addon Cancel” endpoint
• Creation of a new asset record → precheck of the “Asset Create” endpoint
• Update of an asset record → precheck of the “Asset Update” endpoint
• Cancellation of an asset record → precheck of the “Asset Cancel” endpoint

Trigger Events for the Pre-check actions in Storefront

All the precheck actions are executed during basket checkout. Depending on the “nature” of the basket items (if it is a new service, purchase of additional licenses for an existing service, purchase of add-ons, etc.), the appropriate precheck action will be called.

Implementing the Pre-Check Mechanism

The pre-check mechanism is triggered when your endpoint is called with CheckOnly = true. CheckOnly flag is used in the endpoints request body to distinguish whether an API call is performed by interworks.cloud Platform for pre-check or actual provisioning purposes.

{
 -----------------
 "CheckOnly": true,
 -----------------
}

• true value indicates a request for pre-check purposes
• false value indicates a request for provisioning purposes

The information you can use for checking if your business rules are applied is:

• The request body of each endpoint. In each endpoint, we pass in the request body all the information that is necessary for completing successfully the provisioning action.
• Extra information that can be accessed using interworks.cloud platform public API. Check Accessing interworks.cloud Public API for more details.

Execution Flow when the Pre-Check is Enabled

When a BSS user or a customer makes an action that triggers an endpoint that supports pre-check, the following flow will be executed:

1. The endpoint is called with the parameter “checkonly:true“ for running the checks you have implemented for validating the business rule you want to enforce.
2. If the “precheck” action returns an error, we display that error to the user, and the process is terminated. Your endpoint must provide an error response based on the instructions described in the section”Displaying the Pre-check Error to the User” below
3. If no error occurs, we proceed with the actual call by calling the endpoint with the parameter “checkonly:false“.

The pre-check response is only used in case an error result is returned from the performed API call and has the following outcome:

• update user for the error reported from the pre-check request
• cancels the execution of user action

The following diagram displays the steps followed for a simple subscription creation scenario that includes pre-check action.

Displaying the Pre-check Error to the User

For displaying to the user the pre-check error, you should return a response from your endpoint with the following information:

• Code: a negative number.
  • The error code is in the range -80000 and -89999: The actual error message will be displayed both to the BSS users and the Storefront users.
  • The error code is outside the range -80000 and -89999
    • The actual error message will be displayed to the BSS users
    • The generic message “please contact your support department” will be displayed to the Storefront users.
• Description: The error message that explains which business rule(s) are not met for this action.

The error messages are displayed either as a pop-up warning message (when the action is performed from a BSS user) or as inline warnings on the Storefront pages. The following picture is an example of a warning for a product that requires a minimum quantity.

Displaying the Error Message to User’s Language

If you wish to display the error message to the user’s language, you should use the value of the Accept-Language HTTP header. This parameter returns the user’s preferred language in two letters code (e.g., “en” for the English language).

POST https://bssdemo.interworkscloud.net/Dropbox/api/Subscriptions/Create HTTP/1.1
X-CloudPlatform-Token: XXXXXXX
X-CloudPlatform-BaseUri: https://bssdemo.interworkscloud.net
X-CloudPlatform-ApplicationId: XXXXXX
X-CloudPlatform-APIKey: XXXXX
Accept-Language: en
Content-Type: application/json; charset=UTF-8
Accept: Accept=application/json
Host: bssdemo.interworkscloud.net