Abiquo Documentation Cookies Policy

Our Documentation website uses cookies to improve your experience. Please visit our Cookie Policy page for more information about cookies and how we use them.


Abiquo 5.0

Skip to end of metadata
Go to start of metadata

Zuora

Connector Overview

This guide assumes a basic knowledge of the Zuora accounting product. If you are new to Zuora then please first spend some time making yourself familiar with it, before proceeding with the connector configuration.

Abiquo Uploads its Billing Data to Zuora via the Zuora API

The Billing Data is uploaded as Zuora Units Of Measure (UOMs). Note that Zuora UOMs are defined for the entire Zuora Billing system (i.e. UOMs span all Zuora products and accounts). Therefore it is very important that the UOM names are unique to Abiquo - otherwise Abiquo may update the wrong usage record for an account! For that reason, the default UOM names used by the Abiquo Zuora Billing Connector all begin with 'ABQ_'.

Additionally, the Abiquo Zuora Connector expects to map an Abiquo Enterprise/VDC ID using the Zuora 'Account Number'.

Configuring Zuora

Create a Zuora User Account

The Zuora Billing Connector requires you to provide a username and password, which is used to connect to the Zuora server via the Zuora API.
Therefore, the first thing that needs to be done is to create a Zuora User, which needs to be granted the Zuora Platform Role of 'API Only User'.

Define Zuora UOMs

It is essential to configure the Zuora UOMs that the Abiquo Connector will be attempting to upload. The UOMs must be configured via the Zuora UI (via the Settings\Z-Billing Settings\Customize Units of Measure screen), as there is currently no way to configure them using the Zuora API - so this must be a manual process. By default, you must create UOMs for each usage metric that needs to be charged.

The default UOM names used by the Abiquo Connector are:

UOM Name

Notes

ABQ_CPU

 

ABQ_Memory

The uploaded quantity is in Megabytes (MB)

ABQ_IP

 

ABQ_VLAN

 

ABQ_LocalStorage

The uploaded quantity is in Gigabytes (GB)

ABQ_ExternalStorage

The uploaded quantity is in Gigabytes (GB)

ABQ_HAHigh-availability VM
ABQ_ReservedServerCPU 
ABQ_ReservedServerMemoryThe uploaded quantity is in Megabytes (MB)
ABQ_Repository 

 

Note that these default values can be overridden in the Connector configuration.

Additionally, you will need to define UOMs for any Storage Tiers, Cost Codes, or Custom Usages that you are collecting. The UOM names for these items are automatically generated by the Zuora Connector, by combining a usage-type specific prefix with the usage name, as covered in the table below:

Usage Type

UOM Prefix

Example

Storage Tier

ABQ_TIER_

ABQ_TIER_Default Tier 1

Cost Code

ABQ_CC_

ABQ_CC_Monowall

Custom

ABQ_CUSTOM_

ABQ_CUSTOM_ESXHypervisors

Create Products and Rate Plans

Once the UOMs have been defined, it is possible to define Zuora Products in the Product Catalog, and product Rate Plans which reference the UOMs. When doing so, it is important to remember that the UOM quantities supplied by the Connector are all 'per hour'. So for example a 1 CPU VM which ran for a full 24 hour account period will report a CPU usage quantity of 24. Zuora costings should consider this point carefully when defining a Zuora Rate Plan.

Configuring the Abiquo Billing Integration Zuora Connector

Create Account Mappings

In order to map the Abiquo ID to a Zuora account, it is essential to populate the Abiquo 'billing_account_mapping' table with attributes named ZUORA_ACCOUNT_NUMBER, and with the attribute value containing the Zuora Account Number itself.

url

_e.g. url=https://my.own.address.or.ip.here.com/apps/services/a/34.0_
This specifies the location of the Zuora server which the Billing Connector will upload its data to. Note that the Abiquo Billing Connector currently uses version 34 of the Zuora API, therefore the URL must always end with 'apps/services/a/34.0'.

username

e.g. username=apiuser@myCompany.com
This is the name of the Zuora user account that the Billing Account will connect as.

password

e.g. password=myPassword
This is the password of the Zuora user account that the Billing Account will connect as.

adjustUploadTZ

e.g.adjustUploadTZ=true
Zuora will convert all timestamps passed to it by the Billing Connector into PST. For example, a Billing Connector which uploads usage data at 15:00(UTC) will appear as 07:00(PST) on the Zuora server. If set to 'true', this setting allows you to adjust this behaviour so that the Zuora server reports the time as seen by the Billing Connector (i.e. usage Data uploaded at 15:00(UTC) appears as 15:00(PST) also. The default value for this setting is 'true'.

uom_cpu

e.g. uom_cpu=ABQ_CPU

uom_mem
uom_ip
uom_vlan
uom_local
uom_external

uom_ha

uom_reserved_server_cpu

uom_reserved_server_memory

uom_repository

These settings allow you to override the default UOM names used for the 'core' usage values for CPU. Memory, IP, VLAN, Local Storage and External Storage.

Note that the Zuora Connector automatically generates the UOM names for Storage Tier, Cost Code, and Custom usages, so they cannot be configured/overridden in the zuora.properties file.

Example zuora.properties file
##############
#
# ZUORA specific properties
#
##############

url=https://zuora.mycompany.com/apps/services/a/34.0
username=apiuser@mycompany.com
password=myPassword

# If true, this setting adjusts the usage start/end time so that the times appear on the
# Zuora server as the local time generated.
# e.g. with 'true' then 15:00 (UTC) appears as 15:00 (PST) on the Zuora Server,
# whereas with 'false' it appears as 07:00 (PST)
adjustUploadTZ=true

# These values define the UOMs for each of our usage metrics
# (so they can be customised if required)
uom_cpu=ABQ_CPU
uom_mem=ABQ_Memory
uom_ip=ABQ_IP
uom_vlan=ABQ_VLAN
uom_local=ABQ_LocalStorage
uom_external=ABQ_ExternalStorage

uom_ha=ABQ_HA
uom_reserved_server_cpu=ABQ_ReservedServerCPU
uom_reserved_server_memory=ABQ_ReservedServerMemory
uom_repository=ABQ_Repository

Zuora troubleshooting

Problem: Zuora UOMs not appearing in Invoice data.

Solution: Check that the Zuora UOM data does not 'predate' the Zuora Account Subscription start date.

  • When creating a Zuora subscription, make sure it begins at your Usage data period
  • When generating a Bill Run, set the run date to the first day of the month after the month containing the data. E.g. set to March 1st if your data was collected in February.