Integration of Flexiant Cloud Orchestrator with external billing solutions is accomplished using the API. The most suitable API call to use is largely dependent on which roles are to be performed by Flexiant Cloud Orchestrator and which are to be performed by the external billing solution. This page is intended to provide a guide to selecting the most appropriate API call for your chosen integration scenario. For more information, see the scenarios below.
The following terms are used in the scenarios:
- Resource usage metering - the measurement of resource usage, for example amount of disk I/O or bandwidth used, amount of RAM in use, or total storage space used.
- Metered usage rating (units) - the cost of the metered resource usage in Flexiant Cloud Orchestrator's internal billing engine. The internal billing engine uses units to measure resource consumption; customers can track their resource consumption using the Unit Balance widget on the dashboard.
- Product pricing - how the products used by the customers are priced.
- Resource consumption aggregation - the aggregation of the monitored resource consumption data. This can take the form of a total amount for a time period, or a maximum and minimum for the time period.
- Resource consumption monitoring - the provision of detailed billing information which allows customers to check their resource usage in detail.
- Invoicing and payment collection - the collection of payment from the customer.
Configuration | |||
Scenario number | 1 | 2 | 3 |
Scenario 1
In this example, Flexiant Cloud Orchestrator is used for resource usage metering only, with the external billing system handling all other aspects of product billing, as below:
The API call which we suggest using in this case is getMeasuredValues
, which returns a list of measured values for the specified resources, customers, and billing entities.
The getMeasuredValues
call requires the following information:
measureKeys
- defines which measurements are taken. Can be one or more of the following:resourceUUID
- the UUID(s) of the resource(s) to measure values for.customerUUID
- the UUID(s) of the customer(s) to measure values for.billingEntUUID
- the UUID(s) of the billing entity/entities to measure values for. This setting is only applicable if you authenticate to the API as the master billing entity. For information about API authentication, see Authenticating to the APIs.timestamp
- Unix timestamp.
The output consists of the following information:
measuredValue - essentially a container element for the output data. The measuredValue type contains the following information:
Scenario 2
In this example, Flexiant Cloud Orchestrator is used for resource usage metering, product pricing, metered usage rating using the units system, and jointly monitoring the consumption of resources with the external billing system. The external billing system handles aggregation of resource consumption information, metered usage rating using currency, and invoicing, as below:
The API call which we suggest using in this case is listUnitTransactions
, which returns a list of unit transactions matching the specified search criteria.
listUnitTransactions
call requires the following information:searchFilter
- defines the list of unit transactions to return. Contains the following information:filterCondition
- specifies the conditions for the filter. Contains the following information:condition
- the operator for the filter. The default isIS_EQUAL_TO
. The condition can be one of the following:IS_EQUAL_TO
IS_NOT_EQUAL_TO
IS_GREATER_THAN
IS_LESS_THAN
IS_GREATER_THAN_OR_EQUAL_TO
IS_LESS_THAN_OR_EQUAL_TO
CONTAINS
NOT_CONTAINS
STARTS_WITH
NOT_STARTS_WITH
ENDS_WITH
NOT_ENDS_WITH
BETWEEN
NOT_BETWEEN
LATER_THAN
EARLIER_THAN
field
- the field to apply the filter to. For example, this could becustomerUUID
, which would return any transactions for which the customer UUID matched the condition and value.value
- the value of the filter.
queryLimit
- specifies a limit on the number of transactions that can be returned. Contains the following information:from
- the index of the first field to return. For example, if yoursearchFilter
returned a list of 20 objects, the index of the first object would be 0, the second object's index would be 1, and so on.loadChildren
- a boolean value which specifies whether or not to return the child objects of an object. For example, you can choose whether or not to return the NICs within a server. This value can be eitherTRUE
orFALSE
.maxRecords
- the maximum number of records to return.orderedBy
- the field to order the results by. Contains the following information:aggregationFunction
- Either null, or (if specified) theaggregationFunction
associated with the aggregated query. This can be one of the following:SUM
COUNT
MAX
MIN
AVERAGE
fieldName
- the name of the field to order by.sortOrder
- the order in which to sort the results. This can be either ASC or DESC.
to
- the index of the last field to return.
The output consists of the following information:
listResult
- the list of unit transactions. Contains the following information:list
- the list of results. Each result contains the following information:
totalCount
- the total number of results.listFrom
- the index of the first field returned. For example, if yoursearchFilter
returned a list of 20 objects, the index of the first object would be 0, the second object's index would be 1, and so on.listTo
- the index of the last field returned.
Scenario 3
In this example, Flexiant Cloud Orchestrator handles all aspects of product billing apart from metered usage rating using currency and invoicing, which are handled by the external billing system as below:
The API call which we suggest using in this case is listUnitTransactionSummary
, which returns a list of unit transactions matching the specified search criteria.
listUnitTransactionSummary
call requires the following information:searchFilter
- defines the list of unit transactions to return. Contains the following information:filterCondition
- specifies the conditions for the filter. Contains the following information:condition
- the operator for the filter. The default isIS_EQUAL_TO
. The condition can be one of the following:IS_EQUAL_TO
IS_NOT_EQUAL_TO
IS_GREATER_THAN
IS_LESS_THAN
IS_GREATER_THAN_OR_EQUAL_TO
IS_LESS_THAN_OR_EQUAL_TO
CONTAINS
NOT_CONTAINS
STARTS_WITH
NOT_STARTS_WITH
ENDS_WITH
NOT_ENDS_WITH
BETWEEN
NOT_BETWEEN
LATER_THAN
EARLIER_THAN
field
- the field to apply the filter to. For example, this could becustomerUUID
, which would return any transactions for which the customer UUID matched the condition and value.value
- the value of the filter.
queryLimit
- specifies a limit on the number of transactions that can be returned. Contains the following information:from
- the index of the first field to return. For example, if yoursearchFilter
returned a list of 20 objects, the index of the first object would be 0, the second object's index would be 1, and so on.loadChildren
- a boolean value which specifies whether or not to return the child objects of an object. For example, you can choose whether or not to return the NICs within a server. This value can be either TRUE or FALSE.maxRecords
- the maximum number of records to return.orderedBy
- the field to order the results by. Contains the following information:aggregationFunction
- Either null, or (if specified) theaggregationFunction
associated with the aggregated query. This can be one of the following:SUM
COUNT
MAX
MIN
AVERAGE
fieldName
- the name of the field to order by.sortOrder
- the order in which to sort the results. This can be either ASC or DESC.
to
- the index of the last field to return.
The output consists of the following information:
listResult
- the list of unit transactions. Contains the following information:list
- the list of results. Each result contains the following information:Component
Description
Example value billingEntityUUID
Billing Entity UUID of the customer
74c0ddc7-d7e9-43ef-86c2-ccebecffcd3d customerUUID
The UUID of the customer associated with the transaction summary
3968826b-e66c-4902-9549-2b3790e1a2e4 freeUnits
The total free units within the summary period
0 transactionDate
The date associated with the transaction summary
2013-09-23 unitCredits
The total credits within the summary period
40 unitDebits
The total debits within the summary period
20 totalCount
- the total number of results.listFrom
- the index of the first field returned. For example, if yoursearchFilter
returned a list of 20 objects, the index of the first object would be 0, the second object's index would be 1, and so on.listTo
- the index of the last field returned.