API/UseCases/ServiceOrders
Contents
- 1 Overview
- 2 Prerequisites
- 3 Ordering Workflow
- 4 START YOUR ORDER
- 4.1 Create Order
- 4.2 Perform Service Qualification (SQ)
- 4.3 PACKAGE SELECTION
- 4.4 SERVICE CONFIGURATION
- 4.4.1 GET METHODS
- 4.4.2 Get Service Configuration Requirements
- 4.4.3 Get Service Feature Configuration Requirements
- 4.4.4 Get Service Contact Requirements
- 4.4.5 Get Service Identifier Requirements
- 4.4.6 Get Service Identifier Realms
- 4.4.7 Get Service Address Requirements
- 4.4.8 SET METHODS
- 4.4.9 Set Service Configuration Requirements
- 4.4.10 Set Service Feature Setup
- 4.4.11 Set Service Contacts
- 4.4.12 Set Service Identifiers
- 4.4.13 Set Service Address
- 4.5 REVIEW AND SUBMIT
- 5 Other Useful API for Orders
Overview
Emersion's APIs can be utilised to complete the onboarding of your end user customers. This article is aimed at developers to explain the required workflow for onboarding your customer via the APIs, particularly the workflow for orders themselves. For the purposes of this article, the term 'onboarding' refers to the following processes:
- starting an order for a service.
- completing a service qualification (SQ).
- selecting a package plan to subscribe to.
- configuring the service.
- submission of the order.
In order for these processes to be completed successfully, the execution of API calls must be completed in the specific order below.
Prerequisites
The following prerequisites apply to using the APIs for ordering.
Preparation
Emersion strongly recommends you step through the order process in Cumulus before attempting to programmatically replicate the process outside the system. This is the best way to gain an optimal understanding of how the order process works. It will also reduce the developer time needed and assist with troubleshooting. A solid understanding of the process is essential.
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.
Ordering Workflow
Diagrams
The following diagrams are a pictorial representation of the orders workflow for APIs.
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.
Important Note: Not all service types are currently supported by the available SQ APIs. Review the specific help page on each API call for further details. If you find that you are unable to complete a service order end-to-end because a service type you are subscribed to is not supported, please contact Emersion Sales.
Option 1
Perform Simple SQ
This API call creates an SQ entry so the user can proceed to the next step in the orders workflow. It is used for manual and semi-manually provisioned service types and for service types that do not require a service qualification.
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.
Get Service Address Requirements
This request is designed to be gather any service address requirements that may pertain to the order.
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.
Set Service Address
Add or update service address in the Order
- Set Service Address
REVIEW AND SUBMIT
Get Service Address
This call is optional for an order, but may be useful to reflect back to the user what they have entered. The method retrieves any service addresses that has been collected in the order.
- Get Service Address
Get Terms And Conditions
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.
