Page tree
Skip to end of metadata
Go to start of metadata

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: 

     Click here to expand...
    Measurement keyWill return
    used.USERSThe current number of users linked to the customer.
    running.CPUThe current number of CPUs used by all the running servers of the customer.
    used.RAMThe current RAM, in megabytes, allocated to the customer.
    used.SERVERThe current number of servers in the customer account.
    running.SERVERThe current number of running servers in the customer account.
    running.RAMThe current RAM, in megabytes, used by all the running servers of the customer.
    used.CPUThe current number of CPUs allocated to the customer.
    used.DISKThe current number of disks allocated to the customer.
    used.IMAGEThe current number of images in the customer account.
    used.SNAPSHOTThe current number of snapshots used by the customer.
    used.STORAGEGBThe current storage, in gigabytes, allocated to the customer.
    used.IPv6_SUBNETSThe current number of IPv6 subnets allocated to the customer.
    used.IPv4_ADDRESSESThe current number of IPv4 addresses allocated to the customer.
    used.VDCThe current number of VDCs used by the customer.
    used.NETWORK_TRAFFIC_EXTERNAL_INThe total network traffic, in megabytes, received by all of the customer's public/ip networks.
    used.NETWORK_TRAFFIC_INTERWORKING_OUTThe total network traffic, in megabytes, transmitted by the customer's interworking networks.
    used.NETWORK_TRAFFIC_PUBLIC_INThe total network traffic, in megabytes, received by the customer's public networks.
    used.NETWORK_TRAFFIC_IP_OUTThe total network traffic, in megabytes, transmitted by the customer's IP only networks.
    used.NETWORK_TRAFFIC_PUBLIC_OUTThe total network traffic, in megabytes, transmitted by the customer's public networks.
    used.NETWORK_TRAFFIC_PRIVATE_OUTThe total network traffic, in megabytes, transmitted by the customer's private networks.
    used.NETWORK_TRAFFIC_EXTERNAL_OUTThe total network traffic, in megabytes, transmitted by the all of the customer's public/ip networks.
    used.NETWORK_TRAFFIC_INTERWORKING_INThe total network traffic, in megabytes, received by the customer's interworking networks.
    used.NETWORK_TRAFFIC_OUTThe total network traffic, in megabytes, transmitted by the all of the customer's networks.
    used.NETWORK_TRAFFIC_IP_INThe total network traffic, in megabytes, received by the customer's IP only networks.
    used.NETWORK_TRAFFIC_PRIVATE_IPThe total network traffic, in megabytes, received by the customer's private networks.
    used.NETWORK_TRAFFIC_INThe total network traffic, in megabytes, received by all of the customer's networks.
    used.DISK_IO_WRITEThe total data, in megabytes, written to disk by the customer.
    used.DISK_IO_READThe total data, in megabytes, read from disk by the customer.
    used.NETWORK_IPThe total number of IP only networks allocated to the customer.
    used.NETWORK_PRIVATEThe total number of private networks allocated to the customer.
    used.NETWORK_PUBLICThe total number of public networks allocated to the customer.
    used.NETWORK_INTERWORKINGThe total number of interworking networks allocated to the customer.
    traffic_outThe traffic, in megabytes, transmitted from the NIC.
    traffic_inThe traffic, in megabytes, received by the NIC.
    disk_readThe disk read data, in megabytes, done by the server.
    disk_writeThe disk write data, in megabytes, done by the server.
    ramThe RAM, in megabytes, used by the server.
    cpuThe number of CPUs used by the server.
    runningAn indication of whether the server is running (1), or stopped (0)
  • 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: 

     Click here to expand...

    Component

    Description

    Example valueInformationDescriptionExample value

    resourceType

    The type of the resource

    Can be any of the following:
      • CLUSTER
      • CUSTOMER
      • USER
      • DISK
      • SNAPSHOT
      • FIREWALL
      • NIC
      • IMAGE
      • SERVER
      • SUBNET
      • VDC
      • NETWORK
      • SSHKEY
      • JOB
      • PRODUCTOFFER
      • FIREWALL_TEMPLATE
      • BILLING_ENTITY
      • GROUP
      • ANY
      • PAYMENTCARD
      • PAYMENTMETHOD
      • INVOICE
      • PROMOTION
      • REFERRAL_PROMOTION
      • DEPLOYMENT_TEMPLATE
      • DEPLOYMENT_INSTANCE
      • BILLING_METHOD
      • PRODUCT
      • PRODUCT_COMP_TYPE
      • FDL
      • UNIT_TRANSACTION
      • UNIT_TRANSACTION_SUMMARY
      • PRODUCT_PURCHASE
      • CURRENCY
      • TRANSACTION_LOG
      • PERMISSION
      • PROMOCODE
      • PURCHASED_UNITS
      • REFERRAL_PROMOCODE
      • IMAGEINSTANCE
      • FETCH_RESOURCE
      • MEASUREMENT








     



































    timestampThe timestamp of the measurement, as a Unix timestamp measuring the number of seconds from 00:00:01, 1 January 1970.1379674148
    resourceUUIDThe UUID of the resource from which the measurement was taken

    3d5b1b87-9bd9-40e0-8b43-34923960de47

    customerUUID

    The UUID of the customer owning the resource.

    ab3574d3-1cd9-49f8-ae82-f554e652ac08

    billingEntityUUID

    The UUID of the billing entity owning the customer.

    814e66ac-b243-4e91-b39e-b176cf0071ec
    measureKey

     

    The unique name identifying the measurement taken and acting as a key.used.DISK_IO_READ
    measurement

     

    The numeric representation of the measurement value, if appropriate.23
    measurementTypeThe type of unit used with the measured value.

    This can be one of the following:

     Click here to expand...
    InformationDescription

    KB

    Kilobytes

    MB

    Megabytes

    GB

    Gigabytes

    NUMERIC

    A numeric unitless value

    STRING

    String value

    RESOURCE_UUID

    The UUID of a resource

    UNIT

    Units

    CURRENCY

    Currency

    TB

    Terabytes

    B

    Bytes

    measurementAsValue

    The measured value.Contains the following information:InformationDescriptionExample value





















    description

    The description of the value.The total data read from disk by the customer.
    hiddenThe boolean value used to determine whether the value is hidden or shown. Possible values are TRUE and FALSE.
    key

    The name of the value.

    used.DISK_IO_READ
    measureTypeThe type of unit used with the measured value.

    This can be one of the following:

     Click here to expand...
    InformationDescription

    KB

    Kilobytes

    MB

    Megabytes

    GB

    Gigabytes

    NUMERIC

    A numeric unitless value

    STRING

    String value

    RESOURCE_UUID

    The UUID of a resource

    UNIT

    Units

    CURRENCY

    Currency

    TB

    Terabytes

    B

    Bytes

    nameA user-friendly version of the value's name.Disk I/O read.
    validatorA validator object. Only values that match the validator can be set.  This contains the following information:
    • validateString - the string being validated.
    • validatorType - the type of the validator. This can be one of the following:
      • enum.
      • Regular expression.
      • Numeric integer.
      • Numeric double.
    valueThe measured value.0.0

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.

The 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 is IS_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 be customerUUID, 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 your searchFilter 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:
      • aggregationFunctionEither null, or (if specified) the aggregationFunction 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: 

       Click here to expand...

      Component

      Description

      Example valueInformationDescriptionExample value InformationDescription Example value 

      resourceType

      The type of the resource

      Can be any of the following:
        • CLUSTER
        • CUSTOMER
        • USER
        • DISK
        • SNAPSHOT
        • FIREWALL
        • NIC
        • IMAGE
        • SERVER
        • SUBNET
        • VDC
        • NETWORK
        • SSHKEY
        • JOB
        • PRODUCTOFFER
        • FIREWALL_TEMPLATE
        • BILLING_ENTITY
        • GROUP
        • ANY
        • PAYMENTCARD
        • PAYMENTMETHOD
        • INVOICE
        • PROMOTION
        • REFERRAL_PROMOTION
        • DEPLOYMENT_TEMPLATE
        • DEPLOYMENT_INSTANCE
        • BILLING_METHOD
        • PRODUCT
        • PRODUCT_COMP_TYPE
        • FDL
        • UNIT_TRANSACTION
        • UNIT_TRANSACTION_SUMMARY
        • PRODUCT_PURCHASE
        • CURRENCY
        • TRANSACTION_LOG
        • PERMISSION
        • PROMOCODE
        • PURCHASED_UNITS
        • REFERRAL_PROMOCODE
        • IMAGEINSTANCE
        • FETCH_RESOURCE
        • MEASUREMENT




















































































      billingEntityUUID

      Billing Entity UUID of the customer

      814e66ac-b243-4e91-b39e-b176cf0071ec

      chargedFromDate

      The start of the period to which the subject matter of the transaction relates

      2013-09-13 00:00:00

      chargedToDate

      The end of the period to which the subject matter of the transaction relates

      2013-09-30 00:00:00

      closingBalance

      The closing balance after the unit transaction

      42

      customerUUID

      The UUID of the customer

      397108d8-9fa3-41db-ba42-d3d0be463b46

      description

      The textual description of the transaction

      Image Fetch

      descriptionDetail

      The textual description of the detail of the transaction

      Charge for fetching 0.01GB of data.
      linkedPurchase

      The Product Purchase which is linked with the Transaction

      Contains the following information:InformationDescriptionExample value

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

       

      active

      A flag indicating whether the product purchase is currently active

      Possible values are TRUE and FALSE.

      billingEntityUUID

      The UUID of the billing entity associated with the product purchase

      b93fc673-7186-4f63-bfa5-0997d428534e

      customerUUID

      The UUID of the customer associated with the product purchase

      f99771ff-32f4-49a0-b122-9617516acd7b

      description

      A textual description of the product purchase

      Image Fetch

      donotRebill

      A flag to indicate billing further billing periods should not be run

      Possible values are TRUE and FALSE.

      endDate

      The end date/time of the product period

      2013-09-19 14:23:00

      lastBillPeriod

      The end date/time of the last billing period

      2013-09-19 14:23:00

      nextBillPeriod

      The start date/time of the next billing period

      2013-09-19 14:38:00

      productID

      The underlying productid of the product offer which linked with the current purchase

      0

      productOfferUUID

      The UUID of the associated product offer

      183af1e1-449e-47b9-b69e-5a98b5341517

      purchaseDate

      The date/time the product purchase was made

      2013-09-12 11:13:00

      purchasedConfig

       

       

       

       

       

      This will hold the configuration of the resource at the purchased time. Note this can not be used for FQL filtering

      Contains the following information:




      InformationDescriptionExample value

      lastBillingTime

      The last billing time of this component when linked with a purchase, this is a readonly value2013-09-19 14:23:00

      billingConfiguredValues

      The list of configurable values inherited from the Billing Method

      Contains the following information:

        • description - the description of the value.
        • hidden - the boolean value used to determine whether the value is hidden or shown. Possible values are TRUE and FALSE.
        • key - the name of the value.
        • measureType - the type of unit used with the measured value. This can be one of the following:

           Click here to expand...
          InformationDescription

          KB

          Kilobytes

          MB

          Megabytes

          GB

          Gigabytes

          NUMERIC

          A numeric unitless value

          STRING

          String value

          RESOURCE_UUID

          The UUID of a resource

          UNIT

          Units

          CURRENCY

          Currency

          TB

          Terabytes

          B

          Bytes

        • name - a user-friendly version of the value's name.
        • validator - a validator object. Only values that match the validator can be set. This contains the following information:
          • validateString - the string being validated.
          • validatorType - the type of the validator. This can be one of the following:
            • enum.
            • Regular expression.
            • Numeric integer.
            • Numeric double.
        • value - the measured value.

      billingMethodUUID

      The billing method which is selected for this component

      601d9494-73ec-40fd-a379-2f8ec4fff064

      componentTypeUUID

      The UUID of the product component type linked with the ProductComponent

      fc1878de-00f7-49c5-b337-6712d3ee51c8

      productConfiguredValues

      The list of configurable values inherited from the Product Component Type

      Contains the following information:

        • description - the description of the value.
        • hidden - the boolean value used to determine whether the value is hidden or shown. Possible values are TRUE and FALSE.
        • key - the name of the value.
        • measureType - the type of unit used with the measured value. This can be one of the following:

           Click here to expand...
          InformationDescription

          KB

          Kilobytes

          MB

          Megabytes

          GB

          Gigabytes

          NUMERIC

          A numeric unitless value

          STRING

          String value

          RESOURCE_UUID

          The UUID of a resource

          UNIT

          Units

          CURRENCY

          Currency

          TB

          Terabytes

          B

          Bytes

        • name - a user-friendly version of the value's name.
        • validator - a validator object. Only values that match the validator can be set. This contains the following information:
          • validateString - the string being validated.
          • validatorType - the type of the validator. This can be one of the following:
            • enum.
            • Regular expression.
            • Numeric integer.
            • Numeric double.
        • value - the measured value.

      referenceUUID

      The UUID of the object

      194664af-8780-45ac-a5c9-77738ced69e6








































      resourceUUID

      The UUID of the resource associated with the product purchase

      225bb297-bfbc-4175-9a84-f474d329beba

      startDate

      The start date/time of the product purchase

      2013-09-12 11:13:00

      vdcUUID

      The UUID of the VDC associated with the product purchase

      663ab597-964d-4dc3-a8c6-80f263eb1678

      linkedResourceName

      The name of the resource linked with the unit transaction

      Example NIC


























      linkedResourceUUID

      The UUID of the resource linked with the unit transaction

      95ddb7e9-8600-4a7f-be15-4498e8a20346

      linkedServerName

      The name of the server linked with the unit transaction

      Example Server

      linkedServerUUID

      The server UUID, if the link resource was part of a server at that time

      d24daca8-97f6-4480-8bd4-4a96aa3bd3d4

      openingBalance

      The open balance before the unit transaction

      45

      transactionAmount

      The amount of the unit transaction

      -3

      transactionDate

      The date on which the unit transaction occurred

      2013-09-12

      unitsType

      The unit type associated with the unit transaction

      CARRYOVER

      vdcUUID

      The UUID of the vdc which is linked with the transaction

      15d5c9f4-c930-4f11-8295-b23f4f66b4cd

    • totalCount - the total number of results.
    • listFrom - the index of the first field returned. For example, if your searchFilter 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.

The 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 is IS_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 be customerUUID, 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 your searchFilter 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:
      • aggregationFunctionEither null, or (if specified) the aggregationFunction 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 your searchFilter 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.

  • No labels