The generic BSS APS API allows managing accounts and other related objects in the platform.
In this document:
In the platform, a full-featured account is represented by an APS resource
based on the PAAccount
APS type and linked through the one-to-one bssAccountInfo
link to an APS resource based on
the BssAccountInformation APS type.
Besides this, to be managed by a user, the account is linked with a user who
can perform particular administrative operations on behalf of the account in the platform control panel.
In the diagram, the blue colored boxes (PAAccount and PAAdminUser) represent the APS types of the OSS platform and the other boxes represent APS types exposed by BSS (BssAccountInformation and CustomerClass):
An APS resource based on the PAAccount APS type represents a company or a personal account (not to be confused with a user) with all necessary contacts and the links with various other resources. The latter (not shown here) are the links with the subscriptions owned by the account, the parent account, child accounts, and other resources.
An APS resource based on the BssAccountInformation APS type represents commercial data of the account, for example, the currency to pay the purchased services. The resource is linked with other BSS APS resources, for example with an APS resource based on the CustomerClass APS type.
An APS resource based on the CustomerClass APS type represents a minimal set of properties that the respective customer class actually has. You can find the full set of properties in the provider (or reseller) control panel. For example, a class defines credit terms, a statement cycle, and billing type as various parts of the account’s contract with the parent account, also known as vendor in BSS (not to be confused with ISV, an independent software vendor). The BssAccountInformation APS type has the following relationship with the CustomerClass APS type:
A link named customerClass
defines a customer class containing business parameters for the account.
An optional collection of links, ownCustomerClasses
, relevant for the provider and resellers
(in BSS, they are generally called vendors)
defines the vendor’s own collection of customer classes to be assigned to the vendor’s customers or sub-resellers.
An APS resource based on the PAAdminUser APS type represents an administrator who can manage the account properties.
An external system must do some BSS operations itself as explained in this scenario.
In the step-by-step scenario considered in the next section, an external system operates on behalf of a vendor to manage its customers. That can be either the provider (always exists in the platform) or a reseller:
If the vendor in your scenario is a reseller, ensure your test platform contains at least one reseller.
The vendor must have at least two customer classes configured in BSS. By default, every vendor has a customer class called “Default” in its collection.
An external system will do the following operations in a sequence:
Lookup accounts in the platform. The aim is to define a list of vendors and to check if among the existing accounts none has the same properties that you want to be unique in an account you are going to create.
Create a customer with BSS properties.
Change a customer status by means of two operations. One puts a customer on credit hold and stops providing the services the customer is subscribed to. The other releases the customer from the credit hold.
Reassign a customer class for a customer. In that step, it is also necessary to define the customer class currently assigned to the customer and the vendor’s collection of available customer classes.
Note
To create an administrator for the account, refer to the Manage Users scenario.
To manage an account (whether reseller or customer), an external management system must first
find the account APS resource based on the PAAccount APS type
and the linked APS resource based on the BssAccountInformation APS type. The search parameter
can be any property of the APS resource;
it is most likely the account ID assigned internally in the platform and synced with the external system.
For example, if you need the APS resource representing the provider, filter out the list of accounts with an account ID
of 1
.
APS allows external systems to get the JSON representation of a required account and the linked BSS resource in one request or in separate
requests, in either case using a Resource Query Language (RQL) filter. For example,
if the account ID of a customer in the platform is 1000002
, a request to get both APS resources -
PAAccount
and BssAccountInformation
- will be:
GET /aps/2/collections/accounts?eq(id,1000002),select(bssAccountInfo)
If the external system needs the BssAccountInformation
resources
only, use the bss-accounts
alias instead of accounts
in the URL,
and the other functions (select
and eq
) must be changed accordingly.
The response will look similar to the following (some data is missing for brevity):
HTTP/1.1 200 OK
[{
"aps": {
"type": "http://parallels.com/aps/types/pa/account/1.2",
"id": "f654862a-4903-4151-b2b4-ed65c055d120",
...
},
"companyName": "John Smith",
"id": 1000002,
"locked": false,
"personal": true,
"type": "CLIENT",
"addressPostal": { /* ... */ },
"adminContact": { /* ... */ },
"billingContact": { /* ... */ },
"techContact": { /* ... */ },
"bssAccountInfo": {
"aps": {
"type": "http://parallels.com/pa/bss-account-info/1.0",
"id": "7cad381f-0daf-4557-a53f-b5ea64566622",
"status": "aps:ready",
/* ... */
},
"branchId": "",
"accountCurrencyCode": "USD",
"taxStatus": "PERSONAL",
"accountId": 1000002,
"taxZoneId": "Provider-Country",
"salesId": "",
"taxRegIdStatus": "NOT_VERIFIED",
"creditTerm": {
"duePeriod": 10,
"holdPeriod": 30
},
"externalARManagement": false,
"taxRegId": "*****",
"fullyRegistered": true,
"localeId": "en",
"status": "ACTIVE"
}
}]
Once the external system knows the APS IDs of both linked APS resources, it can run the operations available for those resources.
As explained in the APS Types section, for every account APS resource, there is a linked APS resource representing the BSS data of that account. This means, when creating a customer through the APS API, it is necessary to create both APS resources linked to each other in a batch request:
Use the PAAccount APS type to create the customer APS resource.
Use the BssAccountInformation APS type to add an APS resource representing the BSS data of the customer.
The customer account APS resource will be linked with the other APS resource through the bssAccountInfo
link.
The backward link on the other side is called paAccount
.
Note
Optionally, you can add the creation of an administrator to the batch request. To do this, add the user JSON representation from the Manage Users scenario.
From all available properties, the following table contains only the properties required to create an APS resource representing a customer.
Property |
Type |
Sample value |
Notes |
---|---|---|---|
|
URI |
"http://parallels.com/aps/types/ pa/account/1.2" |
Exact match with the ID specified in the PAAccount APS type. |
|
String enum [“ADMIN”, “RESELLER”, “CLIENT”, “SYSTEM”] |
“CLIENT” |
Specifies the type of the new account, respectively, provider, reseller, or customer. The last value, “SYSTEM”, is used only in GET requests. |
|
Boolean |
false |
Create a company, not a person. |
|
String |
“1st APS inc.” |
Assign a name to the customer company. |
|
Structure |
{“streetAddress”:”11, APS”, “locality”:”APS”, “region”:”VA”, “countryName”:”us”, “postalCode”:”12345”} |
Enter full postal address as specified by the Address structure inherited by the Account type. |
|
Structure |
{“email”:”isv1@aps.test”, “givenName”:”Mike”, “familyName”:”Wilson”, “telVoice”:”1#888#1234567”} |
Enter the administrative contacts. |
|
Structure |
{“email”:”isv1@aps.test”, “givenName”:”Mike”, “familyName”:”Wilson”, “telVoice”:”1#888#1234567”} |
Enter the billing contacts. |
|
Structure |
{“email”:”isv1@aps.test”, “givenName”:”Mike”, “familyName”:”Wilson”, “telVoice”:”1#888#1234567”} |
Enter the technical contacts. |
From all available properties, the following table contains only the properties required to create an APS resource representing BSS data of the customer.
Property |
Type |
Sample value |
Notes |
---|---|---|---|
|
URI |
|
Exact match with the ID specified in the BssAccountInformation APS type. |
|
String enum [“PROVIDER”, “PERSONAL”, “COMPANY”] |
|
Specifies the tax status of the account, respectively, “Provider”, “Personal”, or “Company”. |
|
String enum |
“en_US” |
Specifies a locale ID in accordance with the Locale Name rule. |
|
Array of { |
[{
“attributeID”: “external_id”,
“value”: “1111-2222-3333”
}]
|
Creates a set of custom attributes of the account in BSS. |
Keynotes:
The accountCurrencyCode
property is readonly
and therefore cannot be assigned in the request, although
visible in the Account Lookup section.
The attributes
array must include all account applicable BSS custom attributes that are marked as Required
.
You can identify them in the BSS provider control panel:
Both of the above-mentioned APS resources must be created at once, that is why the external system must use the Batch Provisioning request.
Since the resources must be bound to each other, a request must comply with the following rules:
The BssAccountInformation resource must go first in the batch. It is typical for the OSS/BSS platform, when a required operation first starts in BSS and then continues in OSS.
The BssAccountInformation
JSON representation must specify a unique APS ID to assign to the new resource
for the Account (second resource in the batch) to link to it. There are multiple online
Internet resources where you can generate
a UUID, for example Online UUID Generator.
The Account JSON representation must specify the bssAccountInfo
link with connection to the APS ID of
the first resource.
If the new account must be placed under a certain reseller, the Account JSON representation must
specify the APS ID of the reseller in the parent
link. By default, the account will be created under the provider.
The above rules are illustrated in the following example:
POST /aps/2/resources
[
{ "aps":{
"type":"http://parallels.com/pa/bss-account-info/1.0",
"id":"ceeeffac-d2f2-4e36-ae4a-3fe27ed58097"
},
"taxStatus": "COMPANY",
"localeId": "en_US",
"attributes": [
{
"attributeID": "external_id",
"value": "1111-2222-3333"
}
]
},
{ "aps":{
"type":"http://parallels.com/aps/types/pa/account/1.2"
},
"type":"CLIENT",
"personal":false,
"companyName":"1st APS inc",
"bssAccountInfo":{
"aps": {
"id":"ceeeffac-d2f2-4e36-ae4a-3fe27ed58097"
}
},
"parent":{
"aps":{
"id":"4935d68d-4d26-4930-acf7-3871557305a9"
}
},
"addressPostal":{
"countryName":"us",
"locality":"APS",
"postalCode":"12345",
"region":"VA",
"streetAddress":"11, APS"
},
"adminContact":{
"email":"isv1@aps.test",
"givenName":"Mike",
"familyName":"Wilson",
"telVoice":"1#888#1234567"
},
"billingContact":{
"email":"isv1@aps.test",
"givenName":"Mike",
"familyName":"Wilson",
"telVoice":"1#888#1234567"
},
"techContact":{
"email":"isv1@aps.test",
"givenName":"Mike",
"familyName":"Wilson",
"telVoice":"1#888#1234567"
}
}
]
In response, the APS controller must return the “200 OK” code along with the JSON representation of the created APS resources. The provider control panel must show the new customer in both OSS and BSS:
To update an account property, send a PUT request. The request’s URL must specify the APS ID of the account. The JSON payload must contain a set of the properties you need to update and the APS section with the APS type ID and the account resource APS ID. For example, to update the company name, send:
PUT /aps/2/resources/6344049b-8763-417d-837b-490ba0896f41
{
"aps": {
"type": "http://parallels.com/aps/types/pa/account/1.2",
"id": "6344049b-8763-417d-837b-490ba0896f41"
},
"companyName": "John Smith and brothers"
}
In response, the APS controller will send the full JSON representation of the updated account.
This section covers the operations that must be performed in accordance with credit terms, which are a part of the agreement between the provider and the customer. To change an account status, the external system must send the proper REST request addressed to the APS ID identified in the previous Create Customers step. The external system can also find it by following the Account Lookup section.
The BssAccountInformation APS type provides two custom operations to manage the account status in BSS:
putOnCreditHold
puts an account on credit hold similarly to the Put On Credit Hold operation in the
Provider Control Panel (PCP). The operation sets some restrictions on the commercial operations
for the account as well as it stops some services in accordance with the required policy
passed
as an input parameter with the following possible values:
ALL_SUBSCRIPTIONS
: the services in all subscriptions will be stopped. This is similar to the Suspend all
subscriptions option in the PCP.
UNPAID_SUBSCRIPTIONS
- only the services in the unpaid subscriptions will be stopped. This is similar
to the Suspend only unpaid subscriptions option in the PCP.
The operation also requires a sender to specify a reason
for the required action and a comment
.
releaseFromCreditHold
releases the account from the credit hold similarly to the Release From Credit Hold operation
in the PCP. As in the previous operation, it requires
the sender to specify a policy
and a comment
. The policy can be either, DEFAULT
or TEMPORARY
.
In the latter case, the account
is released from the credit hold until the date and time specified by the activeUntil
input parameter.
The sequence of operations will look as follows.
Put the account on credit hold using the ALL_SUBSCRIPTIONS
policy:
POST /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097/putOnCreditHold
{
"policy": "ALL_SUBSCRIPTIONS",
"reason": "ACCOUNT_OVERDUE",
"comment": "Account put on hold due to unpaid invoices, ID #1000123 and #1000125."
}
Check the current status of the account:
GET /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097
The response must show the CREDIT_HOLD
status:
HTTP/1.1 200 OK
{
"aps": {
"type": "http://parallels.com/pa/bss-account-info/1.0",
"id": "ceeeffac-d2f2-4e36-ae4a-3fe27ed58097",
"status": "aps:ready",
/* ... */
},
"accountCurrencyCode": "USD",
"accountId": 1000001,
"status": "CREDIT_HOLD"
}
The operation must change the account status and the status of the account’s subscription in both OSS and BSS:
OSS |
BSS |
Release the account from credit hold temporarily:
POST /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097/releaseFromCreditHold
{
"policy": "TEMPORARY",
"activeUntil": "2017-09-07T13:44:01Z",
"comment": "Account temporarily released from hold per approval ID #23231."
}
If successful, the response in either of the above POST operations will be:
HTTP/1.1 204 No Content
Every account, except for the provider, is created by its parent (also known as the sales vendor).
When creating a child account, the vendor must assign it to a customer class. In the APS API,
the parent can choose an APS resource linked to the parent’s ownCustomerClasses
collection
and assign it to the child through the child’s customerClass
link.
When needed, the vendor can reassign a child account to another customer class by relinking the respective BssAccountInformation resource to another customer class from the vendor’s collection.
External management systems can do the same operations. For that, they must know the APS ID of the PAAccount and BssAccountInformation resources as explained in the Account Lookup section.
Using the APS ID of the vendor’s BssAccountInformation resource , get the list of available customer classes, as in the following example:
GET /aps/2/resources/b7aba5b5-0516-4ad1-aec9-b31c77d74296/ownCustomerClasses
The response must look like this:
HTTP/1.1 200 OK
[
{
"aps": {
"type": "http://www.odin.com/billing/CustomerClass/1.0",
"id": "208e4172-1fdc-6ce9-aebd-1f4152889255",
"status": "aps:ready",
"revision": 2,
"modified": "2017-10-13T12:03:32Z"
},
"classId": 0,
"name": "Default"
},
{
"aps": {
"type": "http://www.odin.com/billing/CustomerClass/1.0",
"id": "6e465116-637c-4977-9524-f1c52a00633e",
"status": "aps:ready",
"revision": 2,
"modified": "2017-10-16T08:37:49Z"
},
"classId": 1,
"name": "Test Class"
}
]
The above operation shows the vendor has two customer classes, so it is possible to switch customers to either customer class.
To determine the customer class currently assigned to an account, request that account for
the customer class linked with the BssAccountInformation resource through the customerClass
link.
In the following example, the GET request refers to the customerClass
link of the BssAccountInformation
resource belonging to the required account:
GET /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097/customerClass
The response contains the representation of the customer class.
HTTP/1.1 200 OK
[
{
"aps": {
"type": "http://www.odin.com/billing/CustomerClass/1.0",
"id": "208e4172-1fdc-6ce9-aebd-1f4152889255",
"status": "aps:ready",
"revision": 2,
"modified": "2017-10-13T12:03:32Z"
},
"classId": 0,
"name": "Default"
}
]
In accordance with the aps.id
, classId
, and name
fields, the customer is currently linked with the “Default”
customer class from the vendor’s list identified in the previous step.
Now, switch the customer from the “Default” class to the “Test Class” customer class from the vendor’s list.
For this purpose, use the standard Relink resources
operation. The following request relinks the BssAccountInformation resource
through the customerClass
link to “Test Class”. The APS ID of the latter is specified in the message body, as follows:
POST /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097/customerClass
{
"aps": {
"type": "http://www.odin.com/billing/CustomerClass/1.0",
"id": "6e465116-637c-4977-9524-f1c52a00633e"
}}
If successful, the response is similar to this:
HTTP/1.1 200 OK
{
"aps": {
"type": "http://www.odin.com/billing/CustomerClass/1.0",
"id": "6e465116-637c-4977-9524-f1c52a00633e",
"status": "aps:ready",
"revision": 2,
"modified": "2017-10-16T08:37:49Z",
"package":
{
"id": "f8521d26-a3a9-4f1a-a48c-a3bcc96b7921",
"href": "/aps/2/packages/f8521d26-a3a9-4f1a-a48c-a3bcc96b7921"
}
},
"classId": 1,
"name": "Test Class"
}
Now, the customer is assigned to another customer class.
The explanations and step-by-step instructions in this document help you gain experience in managing accounts in the platform through the APS REST interface.