# Billing Reports

In this chapter, you will learn how to programmatically retrieve billing information.

Billing reports are text-based reports that gives information about all the various billable and non- billable components within the application. Billing report files are created using the CSV (Comma Separated) format, and are best viewed in a spreadsheet application such as Microsoft Excel. The default character encoding used is Latin 1 (ISO-8859-1, see Wikipedia) where extended characters such as 'Ÿ', 'ć', 'ű', etc. are replaced with the '?' character. An alternative character encoding can however be specified within billing API requests.

# Billing Summary

This report type provides a summary of configuration information intended for manual billing purposes, or to verify that an automated billing system using the other detailed billing report is correctly calculating the appropriate totals for billable configuration items.

Note that unlike the CDR report, the Summary report is probably unsuitable for use in an automated billing system's processing logic as future versions of the applications may generate additional rows & columns of data.

Note that the summary report can show additional partition (totals) sub-sections against each telephone system configuration entry when multiple partitions are defined against it within the application. These additional partition sub-sections are displayed with an ordinal partition number text shown below as follows:

# Billing CDRs

This report type provides detailed configuration information intended to be subsequently imported into an automated billing system. The generated file is also in CSV (Comma Separated) format, and is best viewed in a spreadsheet application such as Microsoft Excel.

The actual CDR report content is specified in detail within document “Akixi Service Billing CDR Specification.pdf”, which is available separately.

Note that if you plan to use this report in an automated billing system's processing logic, you should configure or program that system to ignore unexpected columns of data that might be added to the CDR report in a future version of the application.

# Supported Operations

The list of currently supported Billing Report operations is provided below. Operations related to Akixi Billing Reports start with a “BillingReport” prefix. They will be referred to as “Billing Report Operations” interchangeably hereafter.

# Billing Request Parameters

Parameters used within BillingReportGet operations are listed within the table below, which indicates whether the corresponding Property is supported for a specific telephony platform type.

To learn more about BillingReportXXX parameters, please refer to the “Billing Report Properties” sub-section of the “Configuration-Specific Properties” chapter.

# Default properties

# Advanced properties

# BillingReportGet

The BillingReportGet request can be used to obtain a billing report related to a partition, a Telephony Server, or the whole application.

# BillingReportGet Request

By default, the body of BillingReportGet requests is quite minimalistic: you can simply specify the billing report type in order to obtain a report on all the billable components such as Extensions, ACD Agents and Users within the application.

If you want a billing report for a specific Akixi Telephony Server, then you can specify the Telephony Server Identifier within the TelSysID parameter. Additionally, if you require the report generated for a specific Partition on a specific Telephony Server, you can also specify the Partition Number (PartIDInTelSys) within the Telephony Server. Alternatively, you can specify the underlying Partition GUID (PartitionGUID) on its own in order to specify the Partition without needing to specify a Telephony Server (values for the Telephony Server ID and Partition Number within the Telephony Server will be ignored if this is the case):

<Request Operation="BillingReportGet">
    <InvokeID>00033</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <OperationPayload>
        <!-- Specify a Partition GUID, in which case the TelSysID and PartIDInTelSys -->
        <!-- Properties are ignored. -->
        <Property Name="PartitionGUID">f850b6719f95d98f:79b51bff:149bc2efbcb:-7e08
        </Property> <!-- Specify a Telephony Server component Identifier. -->
        <Property Name="TelSysID">100100</Property>
        <!-- Specify a Partition Number within a Telephony Server. -->
        <Property Name="PartIDInTelSys">2</Property>
        <!-- Specify the type of the Billing Report. -->
        <Property Name="BillingReportType">Summary</Property>
        <!-- Can be used to specify a specific encoding for the report. -->
        <Property Name="Encoding">ISO-8859-1</Property>
        <!-- Can be used to specify advanced Properties. -->
        <Container Name="Advanced">
            <!-- Property to exclude configuration for non-billable part codes. -->
            <Property Name="ExcludeNonBillableConfig">True</Property>
            <!-- Property to include system-side application users. -->
            <Property Name="IncludeSystemWideUsers">False</Property>
            <!-- Property to include demonstration telephony server configurations. -->
            <Property Name="IgnoreBillingExclusions">False</Property>
            <!-- Property to include simulation telephony server configurations. -->
            <Property Name="IncludeSimulationServerConfig">False</Property>
        </Container>
    </OperationPayload>
</Request>

# BillingReportGet Response

If a BillingReportGet operation is successful, then you’ll receive the specified billing report CSV as a SOAP attachment:

<Response Result="Success">
    <InvokeID>00033</InvokeID>
    <Success>
        <!-- Base 64 attachment data shortened for readibility. -->
        <Attachment xmime:contentType="text/csv"
                    FileName="RptBillingSummaryManual__ServerName__2017_07_07.csv">Ikx......Qi=
        </Attachment>
    </Success>
</Response>

The BillingReportGet Request also supports Message Transmission Optimization Mechanism (MTOM, see Wikipedia1 & Wikipedia2) for the transfer of the CSV attachment. For more information about attachments and MTOM, please refer to the “Handling Attachments” sub- heading in the “Introducing The Sample Code” chapter. An example of MTOM encoded attachment returned in a BillingReportGet response is shown below:

<Response Result="Success">
    <InvokeID>00033</InvokeID>
    <Success>
        <Attachment xmime:contentType="text/csv" FileName="RptBillingSummaryManual__ServerName__2017_07_07.csv">
            <xop:Include href="cid:a6b4bbbb-d46e-4516-86f8-d1549311f348@example.jaxws.sun.com"
                         xmlns:xop="http://www.w3.org/2004/08/xop/include"/>
        </Attachment>
    </Success>
</Response>

--uuid:06a099ff-9dc8-42b5-bc3d-1975d0dac665
Content-Id: <a6b4bbbb-d46e-4516-86f8-d1549311f348@example.jaxws.sun.com> Content-Type: text/csv
Content-Transfer-Encoding: binary
"","HOSTED SERVER USAGE SUMMARY REPORT","","","","","","","","","" "","Generated At:","08-Sep-2017 16:56:10 BST","","","","","","","","" ...
[Rest of CSV]
...
"","","","","","","0","AKSP200","Akixi 2000 Supervisor","","" "","","","","","","","","","",""
--uuid:06a099ff-9dc8-42b5-bc3d-1975d0dac665--

If the request was unsuccessful (i.e. the response’s Result attribute depicts the Fail value), then the response’s error code and the message description values should be parsed by the client application and then handled accordingly. Some common errors returned by this operation are provided in the table below:

Please refer to the “Error Codes” chapter for further details on specific error codes and their meaning.