Manage Accounts

The generic BSS APS API allows managing accounts and other related with them objects in the platform.

APS Types

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):

• An APS resource based on the PAAccount APS type represents a company or a personal account (do not confuse with a user) with all necessary contacts and the links with various other resources not shown here, for example, with its own subscriptions, parent account, and child accounts.
• 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 (do not confuse with ISV - 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.

Scenario

An external system must do some BSS operations itself as explained in this scenario.

Initial Platform Configuration

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:

• 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.

Operations

An external system will do the following operations in a sequence:

1. 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.
2. Create a customer with BSS properties.
3. 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.
4. 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.

Account Lookup

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.

Create Customer

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:

• 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 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.

Source Data for Account APS Resource

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.

Source BSS Data

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:

  

Create APS Resources

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:

1. 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.
2. The 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.
3. The Account JSON representation must specify the bssAccountInfo link with connection to the APS ID of the first resource.
4. 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 parts, OSS and BSS:

Update Account Properties

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.

Change Account Status

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.

1. 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."
   }
   

2. 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

3. 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
   

Assign Customer Class

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.

Get Vendor’s Own Customer Classes

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.

Determine Assigned 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.

Reassign Customer Class

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.

Conclusion

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.

← Manage Payments

Manage Users →