Manage Accounts

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

APS Types

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 boxes (PAAccount and PAAdminUser) represent the APS types of the OSS platform, while 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.

Sample Scenario

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

Initial Platform Configuration

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.

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 (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 using a Resource Query Language (RQL) filter. As soon as the external system has the APS IDs of both linked APS resources, it can run the operations available for those resources.

Search by Internal ID

When looking up for an account, the search parameter can be any property of the APS resource. This can 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.

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 omitted 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"
   }
}]

Search by Custom Attributes

If the platform is integrated with an external account management system, they can synchronize a list of accounts using custom attributes. To create a new custom attribute (for example, “crmId”) for the whole platform or for a certain sales vendor, the provider must follow the Creating Custom Attributes section in the Provider Guide. After that, this custom attribute can be configured per account using UI or API. The latter case is demonstrated in the next section.

Here is an example of request for accounts whose custom attribute crmId is “ABC123”:

GET /aps/2/collections/bss-accounts?contains(attributes,and(eq(attributeID,crmId),eq(value,ABC123)))

The above request uses the contains RQL function.

Create Customers

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

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

2. You cannot create a reseller directly using the procedure described in this section. The platform enables you to promote a customer to a reseller using the Create Resellers procedure.

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

  

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

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 OSS and BSS:

Create Resellers

Unlike customers, resellers are not created directly by a single API call, but by promoting a customer to the reseller status as described in Provider Guide . For this purpose, a customer must subscribe to a reseller service plan. When using API, the whole procedure looks as follows:

1. Identify a reseller service plan to be used for promoting a customer to the reseller status as described in Service Plans.

2. Identify an account of the customer type as described in Account Lookup or create one as described in Create Customers.

3. For the selected account, order the selected service plan as described in Sales Orders.

4. Verify that a reseller subscription is created for the account as described in List Subscriptions and the account gets the reseller status as described in Account Lookup.

5. Initialize the new reseller by calling the initializeReseller operation exposed by the BssAccountInformation APS type. This operation is required to set the currency code for the new reseller as in this example:

   POST /aps/2/resources/3719e346-fe3d-4a69-b146-7b7362ae5e6e/initializeReseller
   
   { "currency": "USD" }
   

   If successful, the response code is “204 No Content”.

Resellers can log in to the platform user panel as well as use their own external systems to manage their resources and customers in the platform through the platform API as described in the document set Partner Integration Scenarios.

Update Account Properties

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.

Change the Account Status

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.

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

   If successful, the response in either of the above POST operations will be:

   HTTP/1.1 204 No Content
   

Assign the Customer Class

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.

Get the Vendor’s 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 either customer class.

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

Reassign the 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 “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.

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 →