The generic BSS APS API allows managing accounts and other related with them objects in the platform.
In this document:
In the platform, a full-featured account (an organization/company or personal 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
that represents BSS data of the account. Besides, to be managed by a user, the account is linked with a user who
can do some 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):
customerClass
defines a customer class containing business parameters for the account.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 external system must do some BSS operations itself as explained in this scenario.
The step-py-step scenario considered in the next section assumes using one of vendors to manage its customers. That can be either the provider (always exists in the platform) or a reseller:
An external system will do the following operations in a sequence:
Note
To create an administrator for the account, refer to the Manage Users scenario.
To manage an account, no matter if it is a reseller or a customer, an external management system must preliminary
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,
most probably it will be 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 getting 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 missed out 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"
}
}]
Warning
The taxRegId
property is invisible since this is a part of sensitive personal data that cannot
be disclosed in accordance with the personal data protection rules. Neither can it be used to search for
a BssAccountInformation
resource.
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. It 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:
The customer account APS resource will be linked with the other APS resource through the bssAccountInfo
link
and the backward link on the other side is called paAccount
.
Note
Optionally, you can add the creation of an administrator to the batch request. For 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 |
---|---|---|---|
aps.type |
URI | "http://parallels.com/aps/types/ pa/account/1.2" |
Exact match with the ID specified in the PAAccount APS type. |
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. |
personal |
Boolean | false | Creating a company, not a person. |
companyName |
String | “1st APS inc.” | Assign a name to the customer company. |
addressPostal |
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. |
adminContact |
Structure | {“email”:”isv1@aps.test”, “givenName”:”Mike”, “familyName”:”Wilson”, “telVoice”:”1(888)1234567”} | Enter the administrative contacts. |
billingContact |
Structure | {“email”:”isv1@aps.test”, “givenName”:”Mike”, “familyName”:”Wilson”, “telVoice”:”1(888)1234567”} | Enter the billing contacts. |
techContact |
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 |
---|---|---|---|
aps.type |
URI | "http://parallels.com/pa/bss-account-info/1.0" |
Exact match with the ID specified in the BssAccountInformation APS type. |
taxStatus |
String enum [“PROVIDER”, “PERSONAL”, “COMPANY”] | COMPANY |
Specifies the tax status of the account, respectively, “Provider”, “Personal”, or “Company”. |
localeId |
String enum | “en_US” | Specifies a locale ID in accordance with the Locale Name rule. |
attributes |
Array of {attributeID and value } pairs |
[{
“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 thus cannot be assigned in the request, although
you see it 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, in this particular case a request must comply with the following rules:
BssAccountInformation
JSON representation must specify a unique APS ID to assign to the new resource
in order the Account (second resource in the batch) can link to it. There are multiple online
Internet resources where you can generate
a unique UUID, for example Online UUID Generator.bssAccountInfo
link with connection to the APS ID of
the first resource.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 parts, OSS and BSS:
To update an account property, send a PUT request whose URL must specify the APS ID of the account and the JSON payload must contain a set of the properties you need to update. Along with that, the JSON payload must also contain the APS section with the APS typs and APS ID of the account resource. 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 considers 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 Customer step. The external system can also find it out 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 PCP.UNPAID_SUBSCRIPTIONS
- only the services in the unpaid subscriptions will be stopped. This is similar
to the Suspend only unpaid subscriptions option in 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 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 can 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 systems, 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."
}
In case of success, 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 vendor).
When creating a child account, the vendor has to 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.
The same operations can do an external management system, once it knows 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 one or another customer class.
To determine the customer class assigned currently 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 the “Test Class” customer 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"
}}
On success, the APS controller returns a response 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.