Skip to content
Last updated

Configurable API in BillingPlatform

The Configurable API feature makes it easier to handle business processes in BillingPlatform by combining multiple CRUD (Create, Read, Update, Delete) API calls into one simplified business-facing API. Normally, tasks like creating an account require several API calls, such as creating an account and then linking it to a billing profile. Any API client may require a single logical operation to be broken down into multiple basic operations. Integrations, such as the Netsuite or Salesforce connector, often require a single logical operation composed of several basic operations. For example, creating an account may involve creating both an account and a billing profile in BillingPlatform, or creating a product in the product catalog may require creating a product, pricing plan, and rating methods.

In the absence of configurable APIs, this issue is typically addressed by creating a custom entity, such as a LogicalAccount, which combines fields from both the account and billing profile. An "on create" workflow is then configured to insert each entity individually. The client triggers this workflow by inserting a record into the LogicalAccount entity, which prompts the creation of both the account and billing profile.

However, this approach has inherent overhead: intermediate records inserted into LogicalAccount accumulate in the system, and workflows are limited in their ability to perform complex transformations, such as referencing the outcomes of prior actions. Additionally, since workflows cannot return results directly to the calling application, the API client must query BillingPlatform entries after the operation completes to retrieve IDs of processed records or any other necessary information.

The Configurable API approach provides a structured way to create APIs by building on familiar concepts like entities and workflows, making it intuitive for those with experience in BP and minimizing the learning curve.

Creating a Configurable API involves two main steps. First, a specialized entity - called a configurable entity - is defined to serve as the API interface, specifying the input and output parameters. Unlike standard entities, operations on configurable entities are not stored in the system; instead, they are routed to a specialized workflow known as a data transformation workflow. This workflow applies business logic to transform the input from the configurable entity into actions on BP entity records, such as updates, creations, and upserts.

To support more advanced transformation scenarios, the workflow engine has been enhanced with additional capabilities. Once the operation completes, the Configurable API returns essential information, such as the IDs of affected records, directly in the response to the client (see the response format section for further details).

Step 1: Creating a Configurable Entity

To get started with the Configurable API, the first thing you need to do is create a Configurable entity, which serves as the foundation for your business-facing API. This entity allows you to define the fields and data structure it will handle. You can create the Configurable entity either through the API or directly via the UI. The example below demonstrates how to create a Configurable entity called ConfigurableAccount.

Method: POST

URL: https://my.billingplatform.com/myOrg/rest/2.1/ENTITY

Request body:

{
    "brmObjects": [
        {
            "EntityLabel": "ConfigurableAccount",
            "EntityName": "ConfigurableAccount",
            "ConfigurableEntityFlag": "1"
        }
    ]
}

In this request:

  • EntityLabel and EntityName both refer to the name of your Configurable entity, in this case, ConfigurableAccount.
  • ConfigurableEntityFlag is set to 1 to indicate that this is a Configurable entity rather than a regular one.

Response:

After successfully sending the request, you'll receive the identifier for your newly created Configurable entity, which you’ll need for future operations:

{
    "createResponse": [
        {
            "ErrorCode": "0",
            "ErrorElementField": " ",
            "ErrorText": " ",
            "Id": "4301"
        }
    ]
}

Step 2: Creating Fields for the Configurable Entity

Once you’ve created a сonfigurable entity, you need to define the fields it will use. These fields specify the data structure for the Configurable entity and determine what information the API will accept or require.

In the example below:

  • DataType defines the type of data that the field will store (e.g., TEXT, SELECT1 for dropdown options).
  • EntityIdObj.EntityName references the Configurable entity (ConfigurableAccount) you created in Step 1.
  • FieldName specifies the name of each field (e.g., AccountName, Address, CurrencyCode).
  • RequiredFlag indicates whether the field is mandatory (1 for required fields).

Method: POST

URL: https://my.billingplatform.com/myOrg/rest/2.1/ENTITY_FIELD

Request body:

{
    "brmObjects": [
        {
            "DataType": "TEXT",
            "EntityIdObj": {
                "EntityName": "ConfigurableAccount"
            },
            "FieldName": "AccountName",
            "RequiredFlag": 1
        },
        {
            "DataType": "TEXT",
            "EntityIdObj": {
                "EntityName": "ConfigurableAccount"
            },
            "FieldName": "Address",
            "RequiredFlag": 1
        },
        {
            "DataType": "SELECT1",
            "EntityIdObj": {
                "EntityName": "ConfigurableAccount"
            },
            "FieldName": "CurrencyCode",
            "RequiredFlag": 1
        },
        {
            "DataType": "TEXT",
            "EntityIdObj": {
                "EntityName": "ConfigurableAccount"
            },
            "FieldName": "ParentAccountName",
            "RequiredFlag": 1
        },
        {
            "DataType": "TEXT",
            "EntityIdObj": {
                "EntityName": "ConfigurableAccount"
            },
            "FieldName": "OTCProduct1",
            "RequiredFlag": 1
        },
        {
            "DataType": "TEXT",
            "EntityIdObj": {
                "EntityName": "ConfigurableAccount"
            },
            "FieldName": "OTCProduct2",
            "RequiredFlag": 1
        },
        {
            "DataType": "TEXT",
            "EntityIdObj": {
                "EntityName": "ConfigurableAccount"
            },
            "FieldName": "SubscriptionProduct",
            "RequiredFlag": 1
        }
    ]
}

Response:

After submitting the request, you’ll receive a response confirming that each field has been created. The response includes the ID for each field that has been added to the ConfigurableAccount entity:

{
    "createResponse": [
        {
            "ErrorCode": "0",
            "ErrorElementField": " ",
            "ErrorText": " ",
            "Id": "46087"
        },
        {
            "ErrorCode": "0",
            "ErrorElementField": " ",
            "ErrorText": " ",
            "Id": "46088"
        },
        {
            "ErrorCode": "0",
            "ErrorElementField": " ",
            "ErrorText": " ",
            "Id": "46089"
        },
        {
            "ErrorCode": "0",
            "ErrorElementField": " ",
            "ErrorText": " ",
            "Id": "46090"
        },
        {
            "ErrorCode": "0",
            "ErrorElementField": " ",
            "ErrorText": " ",
            "Id": "46091"
        },
        {
            "ErrorCode": "0",
            "ErrorElementField": " ",
            "ErrorText": " ",
            "Id": "46092"
        },
        {
            "ErrorCode": "0",
            "ErrorElementField": " ",
            "ErrorText": " ",
            "Id": "46093"
        }
    ]
}

Step 3: Creating an External Field

In this step, you’ll create an external field that allows the configurable entity to link to data from external sources like CRM or ERP systems using a consistent identifier.

To create an external field, proceed as described in Adding a New Field and make sure to select the External Key checkbox.

Step 4: Creating a Workflow for the Configurable Entity

Next, you need to create a workflow for your configurable entity to define how the input is processed into records within BillingPlatform. A workflow outlines the steps and logic that must be followed when certain actions, such as creating or updating records, occur on the virtual entity to which this workflow is attached. It can include transformations, validations, and conditional logic that helps to automate business process.

For example, if you are creating a configurable entity for handling account data, the workflow can dictate that whenever a new account is created, a corresponding billing profile should also be generated. Workflows automate and enforce these processes, ensuring consistency and reducing manual intervention.

For configurable entities, we have a specific workflow type called Configurable API (see Configurable API Workflows for details). This workflow type is designed for configurable entities and is triggered by all key CRUD operations: CREATE, UPDATE, and UPSERT.

When you choose the Configurable API workflow type, the system restricts available entities to only Configurable entities and automatically hides unnecessary actions like HTTP Call Out and Document Generation.

To create a Data Transformer workflow proceed as follows:

  1. Navigate to the Setup > Develop > Workflow section.
  2. Click New to create a new workflow.
  3. In the Workflow Type section, select Configurable API.
  4. In the Entities field, select the Configurable entity you want to link the workflow to.
  5. In the Name field, enter a descriptive name for the workflow.
  6. Ensure that the Status is set to Active, so the workflow will be triggered during runtime.
  7. You can set the Order of Evaluation to determine the order in which this workflow should be executed if multiple workflows exist for the same entity. By default, this is set to 1.
  8. Under On Failure, check Rollback and Raise Alert to ensure that the system either rolls back changes or raises an alert if something goes wrong during workflow execution.
  9. Click Save to complete the setup.

Step 5: Creating Workflow Actions

Workflow actions are the steps executed by the system when certain events, like creating or updating records, occur. In the Data Transformer workflow for Configurable entities, actions define what transformations and operations need to happen automatically. Each action can involve creating, updating, or upserting related entities (such as accounts, billing profiles, or products) based on the Configurable entity’s data.

The key principles for Data Transformer workflow actions are:

  • Dynamic Data Population: Workflow actions dynamically populate fields using data from the Configurable entity. This ensures that any information provided during the API call is used consistently across all related entities (accounts, billing profiles, products).
  • Linked Entities: Entities like accounts, billing profiles, and products are linked through their external keys. This ensures proper relationships between parent and child accounts and associated records.
  • Batch Processing: Multiple operations (such as upserting accounts, billing profiles, and products) can be processed in a single workflow, reducing the need for multiple API calls.
  • Using a Function to Pass Data Between Actions: To pass information between workflow actions (e.g., if an entity record in step 4 needs an ID created in step 1), BillingPlatform provides the GetWorkflowActionResponse function.

These actions ensure that when a Configurable entity is processed (e.g., through CREATE or UPDATE), all related entities are also created or updated automatically, keeping your business data synchronized and consistent.

Let's illustrate the key principles using the following examples.

Upserting Accounts

[
  {
    "ACCOUNT": {
      "AccountTypeIdObj": { "AccountType": "ACCOUNT GROUP" },
      "ActivityTimeZone": "0",
      "CustomExternalKey": "{!{!ConfigurableAccountObj.ExternalKey} || '-parent'}",
      "Name": "{!ConfigurableAccountObj.ParentAccountName}",
      "Status": "ACTIVE"
    }
  },
  {
    "ACCOUNT": {
      "AccountTypeIdObj": { "AccountType": "ACCOUNT" },
      "ActivityTimeZone": "0",
      "CustomExternalKey": "{!{!ConfigurableAccountObj.ExternalKey} || '-child'}",
      "Name": "{!ConfigurableAccountObj.AccountName}",
      "ParentAccountIdObj": {
        "CustomExternalKey": "{!{!ConfigurableAccountObj.ExternalKey} || '-parent'}"
      },
      "Status": "ACTIVE"
    }
  }
]

Upserting a Billing Profile

[
  {
    "BILLING_PROFILE": {
      "AccountIdObj": {
        "CustomExternalKey": "{!{!ConfigurableAccountObj.ExternalKey} || '-child'}"
      },
      "Address1": "{!ConfigurableAccountObj.Address}",
      "BillTo": "{!ConfigurableAccountObj.AccountName}",
      "Country": "USA",
      "CurrencyCode": "{!ConfigurableAccountObj.CurrencyCodeObj}",
      "InvoiceTemplateIdObj": { "Name": "Default Invoice Template" },
      "PaymentTermDays": "30",
      "Status": "ACTIVE",
      "TimeZoneIdObj": { "Tzname": "US/Mountain" }
    }
  }
]

Creating Account Products

[
  {
    "ACCOUNT_PRODUCT": {
      "AccountIdObj": {
        "CustomExternalKey": "{!{!ConfigurableAccountObj.ExternalKey} || '-child'}"
      },
      "CustomExternalKey": "{!{!ConfigurableAccountObj.ExternalKey} || '-OTC1'}",
      "ProductIdObj": { "Name": "{!ConfigurableaccountObj.OTCProduct1}" },
      "Quantity": "1",
      "StartDate": "{!to_char(sysdate,'YYYY-MM-DD')}",
      "Status": "ACTIVE"
    }
  },
  ...
]

Using GetWorkflowActionResponse

[
  {
    "RATING_METHOD": {
      "ProrateSubscription": "All",
      "AccountProductId": "{!GetWorkflowActionResponse('Create Account Products', 'Id', 3)}"
    }
  }
]

Response Format

Return IDs of Created Entities

{
  "createResponse": [
    {
      "ErrorCode": "0",
      "ErrorText": " ",
      "ResultEntities": ["Account", "Billing_Profile", "Account_Product"],
      "Results": [
        {
          "Account": [{ "Id": "15646", "Name": "ROOT", "Status": "ACTIVE" }],
          "Billing_Profile": [{ "Id": "75446", "CurrencyCode": "USD", "Status": "ACTIVE" }],
          "Account_Product": [{ "Id": "133689", "Name": "Test Usage", "Status": "ACTIVE" }]
        }
      ]
    }
  ]
}

Return IDs for Multiple Records

{
  "createResponse": [
    {
      "ErrorCode": "0",
      "ErrorText": " ",
      "ResultEntities": ["Account"],
      "Results": [
        {
          "Account": [
            { "Id": "15646", "Name": "ROOT", "Status": "ACTIVE" },
            { "Id": "76456", "Name": "ROOT", "ParentAccountID": "15646", "Status": "ACTIVE" },
            { "Id": "85465", "Name": "ROOT", "ParentAccountID": "76456", "Status": "ACTIVE" }
          ]
        }
      ]
    }
  ]
}
Previous page
Next page