API/UseCases/ServiceOrders

From Emersion
Revision as of 17:06, 29 June 2016 by Scarpenter (talk) (→‎Start Your Order)
Jump to: navigation, search

Overview

Emersion's APIs can be utilised to complete the onboarding of your end user customers. This article explains the required workflow for onboarding your customer, particularly the workflow for orders themselves. For the purposes of this article, 'onboarding' refers to the following processes:

  • completing a service qualification (SQ).
  • selecting a package.
  • configuring the service(s), service feature(s) and service contact(s) where applicable.
  • submission of the order.

This process and workflow matches closely with Emersion's Customer Sign Up portal process.

This article is to guide developers who wish to use the API to complete the above processes end-to-end using only the API. In order for these processes to be completed successfully, the execution of API calls must be completed in the specific order below.

We also recommend performing the process in Cumulus UI using a test account to gain an understanding on how the process works from an user perspective.

Order Workflow

Create the Account

Before you can commence an order, an account needs to exist in the system. This article focuses primarily on the workflow of the order, but in an end-to-end onboarding case scenario, it includes the creation of an account as a first step. If users may place orders for existing accounts, you may want to leverage off the GetAccount or GetAccountFromUsernameAndPassword methods to validate the customer.

START YOUR ORDER

Create Order

Start the order process with this API call in order to be able to progress to performing an SQ.

Perform Service Qualification (SQ)

After starting an order, the user needs to perform an SQ to confirm the service's availability. There are 3 choices for service providers to use depending on the service types being sold.

Option 1

Perform Simple SQ
Many service types fit into the profile of a 'Simple SQ' where there is no SQ needed. For example, any service type that is manually or semi-manually provisioned. For these service types, this API call simply creates an SQ entry so the user can proceed to the next step.

Option 2

Perform General Phone SQ
This method provides the ability to perform an SQ for a service type that is defined as using the checktype GeneralPhone.

Option 3

Option 3 contains two methods to perform an address-based SQ.

Perform NWB SQ - Find Address
This method provides the ability to perform an SQ for AAPT NwB services. This part of the SQ is designed as a prerequisite for address based service qualifications for AAPT.

Perform NWB SQ - SQ
This API call takes the output from the Find NWB SQ Address and performs a service qualification (SQ) for the AAPT NwB service type.

PACKAGE SELECTION

Once the order has been started and a successful SQ result is known, the next step in the process is around package choice and selection. Use these two APIs to display a list of available packages for the user to choose from. After the user has selected a package, you can move onto the next phase of the order or optionally present further information regarding the package by using the method GetPackagePlanDetails.

Get Available Packages

This method will return a list of packages that are available to order once a successful SQ has been obtained.

Select Package Plan

The system needs to know what package is selected. This can only be done once per order. The order will error if subsequent submissions via this call are received.

SERVICE CONFIGURATION

For each service contained a package, information needs to be collected for a variety of purposes, including but not limited to authentication, provisioning and reporting. The following section contains several GET and SET functions that will handle all these service configuration requirements. Emersion may need to change the requirements for a service type from time to time without notice. These methods are designed to handle such evolutionary adaptations by gathering the up-to-date set of requirements each time.

GET METHODS

Get Service Configuration Requirements

This request will return all data fields that needs to be completed as part of configuring each service contained in the selected package, along with whether they are mandatory or not.

Get Service Feature Configuration Requirements

This call retrieves a list of service features that are mandatory or optional.

Get Service Contact Requirements

Some service types require one or more service-level contacts as part of the configuration. This method will retrieve any business rules pertaining to service contact requirements so that they can be included with an order. Service level contacts should not be confused with those that are associated with an account (i.e. primary, billing).

Get Service Identifier Requirements

This request is designed to advise of any service identifier requirements beyond service-based identifiers which are part of the SQ process. E.g. Those used for authentication purposes.

Get Service Identifier Realms

This request is designed to be gather requirements related to realms, which are an aspect of service identifiers. This will return a list of available identifier realms that are presently associated against the parent account.

SET METHODS

Set Service Configuration Requirements

Based on the requirements gathered in Get Service Configuration Requirements, this is used to configure any service configuration which is part of the service. Note: This cannot be configured until the 'Package Plan' is selected.

Set Service Feature Setup

Based on the requirements (optional or mandatory) gathered in Get Service Feature Configuration Requirements, this API call is used to configure any service features. Note: This cannot be configured until the 'Package Plan' is selected.

Set Service Contacts

Based on the requirements gathered in Get Service Contact Requirements this method will populate the service contact information that is required for an order.

Set Service Identifiers

Based on the requirements gathered in Get Service Contact Requirements this method will populate the service contact information that is required for an order.

REVIEW AND SUBMIT

GetTermsAndConditions

This call is mandatory for an order by a service provider who subscribes to the Terms and Conditions module. The method retrieves any terms and condition text blocks.

Submit (Create) Order

For the submission of an order. All information that has been previously submitted will be validated and if the order passes it will be accepted into the system. Package subscription(s), service subscription(s) and service(s) in a PreActive state will be created.

Other Useful API for Orders

While these do not directly form part of the primary workflow for an order, service providers may find the following API functions worth considering to improve the user experience with your applications.

Create Note

During the ordering process there may be reasons to put additional notes in the system against a customer.

Create Payment

The Create Payment function can collect a payment for you if you wish that to be part of the order process.

Retrieved from "https://mediawiki.emersion.com.au/wiki/index.php?title=API/UseCases/ServiceOrders&oldid=4748"