# Telephone Systems (Telephony Servers)

In this sub-section, you will learn how to programmatically create, modify, delete and view Telephony Server entries.

Akixi Telephony Server entries can represent 1 or more client-side telephony environments and are used to configure the application so that it knows how to communicate with the underlying telephony platform in order to monitor & model real-time call & ACD state information for devices.

In order to configure an Akixi Service instance to specifically communicate to either a PBX or hosted telephony platform, a Telephony Server entry component must be configured within the Akixi Service. This defines the public IP address of the target telephony platform’s external connectivity implementation, as well as some other important communication details such as TCP/UDP port numbers, authentication details, and other internal API communication settings.

Once a Telephony Server entry is created, the Akixi Service begins communicating with the corresponding telephony platform and establishes a persistent connection with it.

Depending on whether a PBX or “hosted” telephony platform is being utilised by Customer, the configuration arrangement within Akixi can be different.

# Hosted Telephony Platform Connectivity

For hosted Customers, the Akixi Service is configured to communicate with the Telephony Provider’s core hosted platform, which is running in a data centre location. Depending on the number of Customer sites being supported, and also the platform access permissions granted by the Telephone Provider to Akixi, the Akixi Service may or may not need to maintain multiple communication sessions to the Provider’s platform for each separate Customer.

Generally speaking using the currently available communication technologies, one Akixi telephony platform communication session is also rarely capable of support more than 100 Customers. Therefore for a large number of Customers, Akixi will always maintain multiple communication sessions with the corresponding hosted telephony platform.

For BroadSoft M6 telephony platforms, it is recommended to create a single Telephony Server entry, and mount each separate Customer as an Akixi Partition component (up to about an 80 Partition pessimistic safe limit before creating another new Telephony Server entry, etc.).

For Cisco BroadWorks® telephony platforms, there are effectively 3 options as listed below. To learn more about how to specifically integrate external BroadWorks provisioning systems with the Akixi Service, refer to the corresponding sub-heading.

# Telephony Server Per BroadWorks Enterprise (Recommended)

The recommended approach is to create a separate Akixi Telephony Server entry per BroadWorks Enterprise component, and then create separate Partition elements for each individual BroadWorks Group (site) components. This approach is strongly suggested in order that the Akixi Partition level can be used as a scope permission assignment model for individual reporting supervisor Users, which might only require reporting privileges against a specific BroadWorks Enterprise Group. This option requires BroadWorks read-only administrative API credentials to be created on the telephony platform at the Enterprise level, which are then set in the AuthUserID2, AuthPassword2, AuthUserID4 & AuthPassword4 properties accordingly.

# Telephony Server Per BroadWorks Enterprise (Single Partition)

Similar to option "Telephony Server Per BroadWorks Enterprise", but where only one Akixi Service Partition component is created which is associated with the entire BroadWorks Enterprise.

# Single Telephony Server

Conversely, a single Telephony Server entry can be configured instead that has BroadWorks System/Provisioning level API access, where individual Customer Enterprises are mapped to separate Partitions. This latter approach is easier to visualise as well as configure manually, but sacrifices the ability to allow BroadWorks Group specific organisation of sites within the Akixi Service as well as the easier facility for site-specific reporting permissions. This option requires BroadWorks read-only administrative API credentials to be created on the telephony platform at the System or Provisioning level, which are then set in the AuthUserID2, AuthPassword2, AuthUserID4 & AuthPassword4 properties accordingly.

To learn more about Akixi Partition components, refer to the “Partitions (Tenants)” sub-section.

# PBXs Connectivity

For PBX Customers, the Akixi Service is configured to communicate with each individual Customer PBX telephone system, which resides in the same physical location as the Customer’s extension handsets/endpoints.

# “Site” Licensing

The Akixi application itself limits the number of Customer Site telephony environments that can be specifically monitored for Akixi Lite, 1000, 2000 & 3000 reporting. Note that you need an Akixi 1000, 2000, or 3000 assigned environment to use Akixi Presence functionality- there is no specific site license for Akixi Presence.

For PBX telephony environments, licenses are utilised & assigned at the Telephony Server component level via the LicensedForRptUserType Property in TelSysAdd & TelSysChange operations.

For hosted environments, licenses are utilised & assigned at the Partition component level via the LicensedForRptUserType Property in PartitionAdd & PartitionChange operations.

For more information on setting the LicensedForRptUserType Property in Web Services request, refer to sub-section “LicensedForRptUserType”.

# Supported Operations

The list of currently supported Telephony Server operations is provided below. Operations related to Akixi Telephone Systems/Server entries start with a “TelSys” prefix. They will be referred to as “TelSys Operations” interchangeably hereafter.

Please note that depending on your assigned telephone system privileges you may only have access to view and configure one particular Telephony Server entry. Refer back to the application administrator that created your particular User account in order to gain additional privileges.

# Telephony Server Request Parameters

Please note that some TelSysAdd & TelSysChange parameters are platform-specific - therefore, you must be entirely sure that your request includes all parameters required to create and/or modify a Telephony Server entry of a certain telephony platform/system type.

Parameters used within both TelSysAdd and TelSysChange requests can be found in the table below. You can use this table to check whether a parameter is supported by a certain telephony platform.

To learn more about TelSysXXX parameters, please refer to the “Telephony Server Properties” section.

# Read-Only Properties After Initial Creation

# Fully Updatable Properties

# Advanced Properties (Advanced Container)

# TelSysAdd

Telephony Server entries are added via TelSysAdd request. The main purpose of this request is to create a new telephony platform connection where configurational parameters are specified that depict API integration & communication settings used in order to collect real-time reporting call & ACD state data from the underlying telephony platform.

# TelSysAdd Request

As mentioned above, TelSysAdd requests are platform-specific. Therefore, you will need to provide request parameters that are relevant to the corresponding telephony platform being communicated with.

The following request body shows an example of a platform-specific Telephony Server entry creation operation. This request includes all parameters supported by TelSysAdd operation invoked in order to create new Cisco BroadWorks® telephony platform connectivity.

<Request Operation="TelSysAdd">
    <InvokeID>00004</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <OperationPayload>
        <!-- TelSysID value cannot be subsequently changed after creation. -->
        <Property Name="TelSysID">100100</Property>
        <Property Name="CMEnvironmentID">d6d6c5a5f0f90d60:-15617a00:169f533f6d5:5613</Property>
        <!-- TelSysType value cannot be subsequently changed after creation. -->
        <Property Name="TelSysType">BroadSoft BroadWorks</Property>
        <Property Name="Description">ACME Tire Company</Property>
        <Property Name="TimeZone">Europe/London</Property>
        <!-- Communication Properties. -->
        <Property Name="IPAddrOrHost1">90.90.90.90</Property>
        <Property Name="IPAddrOrHost2">90.90.90.91</Property>
        <Property Name="IPAddrOrHost3">90.90.90.90</Property>
        <Property Name="IPAddrOrHost4">90.90.90.91</Property>
        <Property Name="TCPPort2">8011</Property>
        <Property Name="TCPPort4">2208</Property>
        <Property Name="UseSSLTLS2">False</Property>
        <Property Name="UseSSLTLS4">False</Property>
        <!-- Telephony platform API communication authentication Properties. -->
        <!-- Note that password values must be AES-128 ECB encrypted and provided as -->
        <!-- Base64 text values. -->
        <Property Name="AuthUserID2">akixiuser@acmetireco.com</Property>
        <Property Name="AuthPassword2">VnFr/A7vdhjOsl7s/Gi2jQ==</Property>
        <Property Name="AuthUserID4">akixiuser@acmetireco.com</Property>
        <Property Name="AuthPassword4">VnFr/A7vdhjOsl7s/Gi2jQ==</Property>
        <!-- Broadsoft BroadWorks-specific context paths. -->
        <Property Name="CommsParameter1">/com.broadworks.xsi-events</Property>
        <Property Name="CommsParameter2">/com.broadworks.xsi-actions</Property>
        <!-- Property to enable/disable communication. -->
        <Property Name="CommsEnabled">True</Property>
        <!-- Custom tag value that is depicted against the new Telephony Server component --> <!-- by the Akixi Service billing output. -->
        <Property Name="BillingTag">ACMETireCoA0001</Property>
        <Property Name="Billable">True</Property>
        <!-- Other configuration Properties. -->
        <Property Name="TelNoPrefixes"/>
        <Property Name="InternalDigitLen">4</Property>
        <Property Name="CountryCode">44</Property>
        <!-- Advanced Properties. -->
        <Container Name="Advanced">
            <Property Name="CTILogEnabled">False</Property>
            <Property Name="CTICallModelLogEnabled">False</Property>
            <Property Name="InternalDiagDumpEnabled">False</Property>
            <Property Name="CTILogIncClassNames">False</Property>
            <Property Name="CallModelDiagDumpEnabledForCalls">False</Property>
            <Property Name="CallModelDiagDumpEnabledForDev">False</Property>
            <Property Name="PartitionCountMax">80</Property>
            <Property Name="PartitionsRptingScopeAllEnabled">False</Property>
        </Container>
    </OperationPayload>
</Request>

Depending on your initial requirements, your actual request might be shorter than the sample request above. For example, it is normally not required to explicitly specify logging settings. If logging is not required, you can exclude corresponding properties from the “Advanced” container - therefore, your actual request will become shorter and the Akixi Service will use its server-side defaults for logging & other advanced settings.

Although the main purpose of the TelSysAdd operation is to add a new Telephony Server component to the Akixi Application, the operation itself is very flexible. For example, you can use TelSysAdd operation to:

• Create a new Telephony Server entry and start communication immediately.
• Create a new Telephony Server and explicitly disable communication (it can be enabled latervia the TelSysChange request).
• Create a new Telephony Server entry with empty communication parameters (it can be edited later via TelSysChange request in order to provide correct communication parameters)

# TelSysAdd Response

If your operation was successful, you will receive a response similar to the following:

<Response Result="Success">
    <InvokeID>00004</InvokeID>
</Response>

You will now be able to access the newly created Telephony Server entry by invoking other TelSysXXX requests that will include its unique identifier (TelSysID). The Telephony Server can also be viewed & modified under the Administration “Telephony Servers” area of the Akixi Service administration portal.

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.

# TelSysChange

Akixi Telephony Server components can be modified via TelSysChange request. To modify parameters of an existing Telephony Server, you must build a request that will include corresponding component’s unique identifier (TelSysID), as well as the Properties to actually update.

Please note that changing any of the communication-related telephone system settings such as the IP address, TCP/UDP port, and other communications fields will potentially cause communication & monitoring of the corresponding telephony platform to be restarted. Tracking of any active call and/or ACD status activity will be temporarily suspended whilst communication with the target telephony platform is reinstated, which will affect reporting statistics.

# TelSysChange Request Parameters

Please note that some TelSysChange parameters are platform-specific - therefore, you must be entirely sure that your request includes all parameters required to change a Telephony Server component of a certain type.

Parameters used within the TelSysChange request can be found in the table previously given against the “Telephony Server Request Parameters” sub-heading. You can use this table to check whether a parameter is supported by a certain telephony platform type.

To learn more about TelSysXXX parameters, please refer to the “Telephony Server Properties” section.

Please note that certain Telephony Server request parameters (TelSysID, TelSysType) cannot be changed via this request. These parameters are meant to remain unchanged during a Telephony Server component’s lifetime.

# TelSysChange Request

As mentioned above, TelSysChange requests are platform-specific. Therefore, you will need to provide request parameters that are relevant to your telephony platform.

The following request body shown below can be used as an example of a platform-specific Telephony Server updating operation. This request includes all parameters supported by TelSysChange operation invoked in order to modify an existing Cisco Broadworks® Telephony Server entry.

<Request Operation="TelSysChange">
    <InvokeID>00004</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <OperationPayload>
        <!-- TelSysID value cannot be subsequently changed after creation. -->
        <Property Name="TelSysID">100100</Property>
        <Property Name="CMEnvironmentID">d6d6c5a5f0f90d60:-15617a00:169f533f6d5:5613</Property>
        <Property Name="Description">ACME Tire Company</Property>
        <Property Name="TimeZone">Europe/London</Property>
        <!-- Communication Properties. -->
        <Property Name="IPAddrOrHost1">90.90.90.90</Property>
        <Property Name="IPAddrOrHost2">90.90.90.91</Property>
        <Property Name="IPAddrOrHost3">90.90.90.90</Property>
        <Property Name="IPAddrOrHost4">90.90.90.91</Property>
        <Property Name="TCPPort2">8011</Property>
        <Property Name="TCPPort4">2208</Property>
        <Property Name="UseSSLTLS2">False</Property>
        <Property Name="UseSSLTLS4">False</Property>
        <!-- Telephony platform API communication authentication Properties. -->
        <!-- Note that password values must be AES-128 ECB encrypted and provided as -->
        <!-- Base64 text values. -->
        <Property Name="AuthUserID2">akixiuser@acmetireco.com</Property>
        <Property Name="AuthPassword2">VnFr/A7vdhjOsl7s/Gi2jQ==</Property>
        <Property Name="AuthUserID4">akixiuser@acmetireco.com</Property>
        <Property Name="AuthPassword4">VnFr/A7vdhjOsl7s/Gi2jQ==</Property>
        <!-- Broadsoft BroadWorks-specific context paths. -->
        <Property Name="CommsParameter1">/com.broadworks.xsi-events</Property>
        <Property Name="CommsParameter2">/com.broadworks.xsi-actions</Property>
        <!-- Property to enable/disable communication. -->
        <Property Name="CommsEnabled">True</Property>
        <!-- Custom tag value that is depicted against the corresponding Telephony Server --> <!-- component by the Akixi Service billing output. -->
        <Property Name="BillingTag">ACMETireCoA0001</Property>
        <Property Name="Billable">True</Property>
        <!-- Other configuration Properties. -->
        <Property Name="TelNoPrefixes"/>
        <Property Name="InternalDigitLen">4</Property>
        <Property Name="CountryCode">44</Property>
        <!-- Advanced Properties. -->
        <Container Name="Advanced">
            <Property Name="CTILogEnabled">False</Property>
            <Property Name="CTICallModelLogEnabled">False</Property>
            <Property Name="InternalDiagDumpEnabled">False</Property>
            <Property Name="CTILogIncClassNames">False</Property>
            <Property Name="CallModelDiagDumpEnabledForCalls">False</Property>
            <Property Name="CallModelDiagDumpEnabledForDev">False</Property>
            <Property Name="PartitionCountMax">80</Property>
            <Property Name="PartitionsRptingScopeAllEnabled">False</Property>
        </Container>
    </OperationPayload>
</Request>

Depending on your initial requirements, your actual request might be shorter than the sample request above.

# TelSysChange Response

If your operation was successful, you will receive a response similar to the following:

<Response Result="Success">
    <InvokeID>00005</InvokeID>
</Response>

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.

# TelSysDelete

Akixi Telephony Server component can be removed via TelSysDelete request. To delete a specific Telephony Server entry, you must build a request that will include the corresponding entry’s unique identifier value (TelSysID), as well as any required optional deletion parameters.

Only inactive (i.e. out-of-service) Telephony Server components can be deleted. Therefore, you must ensure that the CommsEnabled parameter of the designated Telephony Server(s) is/are set to False (e.g. by submitting appropriate TelSysChange request(s) first).

# TelSysDelete Request

The example request below is an example of a Telephony Server deletion operation. This request includes all parameters supported by TelSysDelete operation invoked in order to delete an existing entry (where TelSysID=100100).

<Request Operation="TelSysDelete">
    <InvokeID>00006</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <OperationPayload>
        <Property Name="TelSysID">100100</Property>
        <Property Name="AutoDeleteUsers">True</Property>
    </OperationPayload>
</Request>

Depending on your initial requirements, your actual request might be shorter than the sample request shown above.

# TelSysDelete Response

If your operation was successful, you will receive a response similar to the following:

<Response Result="Success">
    <InvokeID>00006</InvokeID>
</Response>

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.

# TelSysList

TelSysList operation can be used to list all Telephony Server components that are configured against a certain Administrative account.

# TelSysList Request

By default, the TelSysList request body is quite minimalistic: you can simply provide correct SessionID and InvokeID values in order to obtain TelSysID and Description parameters of Telephony Server components configured against your Administrative account:

<Request Operation="TelSysList">
    <InvokeID>00007</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
</Request>

You can obtain additional TelSys-related parameters by providing their names within a TelSysFields Payload Property (as a comma-separated string). The Offset and Limit parameters can also be specified to request a specific subsection of the listed entries (if not specified these values are assumed to be 0 and 1000 respectively). Offset defines how many entries to skip over (i.e. which entry to start on if the first entry is entry 0) and Limit defines how many entries to retrieve. The example below will return all additional parameters supported by the TelSysList operation (as well as default parameters, i.e. TelSysID and Description), and retrieve 20 entries after skipping the first 100.

<Request Operation="TelSysList">
    <InvokeID>00007</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <Offset>100</Offset>
    <Limit>20</Limit>
    <OperationPayload>
        <Property Name="TelSysFields">TelSysType,CommsStatus</Property>
    </OperationPayload>
</Request>

The TelSysList operation can only return the following Telephony Server component Properties:

• TelSysID *
• Description *
• TelSysType
• CommsStatus

Parameters marked with an asterisk (*) are returned by default (i.e. it is not required to specify them via the TelSysFields Property).

# TelSysList Response

If a TelSysList operation was successful, you will receive a list of Telephony Servers and their properties. If additional parameters were not provided within your request, you will receive default properties of all Telephony Servers (i.e. TelSysID and Description). If additional fields were requested (via the TelSysFields Property), corresponding values will also be returned in operation’s response:

<Response Result="Success">
    <InvokeID>00007</InvokeID>
    <Success>
        <Container>
            <Property Name="TelSysID">1001</Property>
            <Property Name="Description">Telephony Server 1001</Property>
            <Property Name="TelSysType">BroadSoft Broadworks</Property>
            <Property Name="CommsStatus">Running</Property>
        </Container>
        <Container>
            <Property Name="TelSysID">1002</Property>
            <Property Name="Description">Telephony Server 1002</Property>
            <Property Name="TelSysType">BroadSoft Broadworks</Property>
            <Property Name="CommsStatus">Out-Of-Service</Property>
        </Container>
    </Success>
</Response>

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.

# TelSysInfo

The TelSysInfo request can be used to obtain information related to a specific Telephony Server entry. You must simply provide a correct component identifier number value (TelSysID) within your request in order to get all underlying parameters of the corresponding Telephony Server entry.

# TelSysInfo Request

The TelSysInfo request body is quite minimalistic: it includes two operation-specific parameters, as shown below:

<Request Operation="TelSysInfo">
    <InvokeID>00008</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <OperationPayload>
        <Property Name="TelSysID">1001</Property>
        <Property Name="AdvancedFields">True</Property>
    </OperationPayload>
</Request>

Please note that AdvancedFields parameter is optional and can be skipped (in this case, advanced parameters like logging settings will not be returned).

# TelSysInfo Response

If a TelSysInfo operation is successful, you will receive a list of all the corresponding Telephony Server component’s main Property values, accordingly to which ones are supported & updatable for that particular entry’s telephony platform/system type. The particular properties that will be returned for different telephony platform types are shown within the table previously given against the “Telephony Server Request Parameters” sub-heading.

Note that advanced fields are only returned within the response (via the Advanced container), when a value of True was deliberately specified for the AdvancedFields parameter within the original request.

<Response Result="Success">
    <InvokeID>00008</InvokeID>
    <Success>
        <Property Name="TelSysID">1</Property>
        <Property Name="CMEnvironmentID">d6d6c5a5f0f90d60:-15617a00:169f533f6d5:5613</Property>
        <Property Name="Description">Demonstration Simulator 01</Property>
        <Property Name="TelSysType">Demonstration Simulator</Property>
        <Property Name="TimeZone">Europe/London</Property>
        <Property Name="CommsEnabled">True</Property>
        <Property Name="TelNoPrefixes">9</Property>
        <Property Name="BillingTag"/>
        <Property Name="OmniChannelPermitted">True</Property>
        <Property Name="Billable">True</Property>
        <Property Name="CallControlOptions">All</Property>
        <Container Name="Advanced">
            <Property Name="CTILogEnabled">False</Property>
            <Property Name="CTICallModelLogEnabled">False</Property>
            <Property Name="InternalDiagDumpEnabled">False</Property>
            <Property Name="CTILogIncClassNames">False</Property>
            <Property Name="CallModelDiagDumpEnabledForCalls">False</Property>
            <Property Name="CallModelDiagDumpEnabledForDev">80</Property>
            <Property Name="PartitionCountMax">80</Property>
            <Property Name="PartitionsRptingScopeAllEnabled">False</Property>
        </Container>
    </Success>
</Response>

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.