link
Akixi Developer Portal

# 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.

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.

Note

This Akixi Service component integration strategy has one limitation in that cross- Enterprise hunt groups & call centre queues can’t be supported (i.e. support for call distribution groups that contains extension user members across multiple BroadWorks Groups). If support for Enterprise-wide group distribution devices is required, then use option 2 or 3 instead accordingly.

Also

Cross-BroadWorks-Group calls are modelled as external calls, which means that “internal” calls made between extensions users in different BroadWorks Groups does not require an Akixi Device entry to be created for the remote extension user on the Group where Akixi Supervisor reporting is not locally required for.

# 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.

Operation Name Operation Description
TelSysAdd Add a new Telephony Server entry.
TelSysChange Change an existing Telephony Server component.
TelSysDelete Delete a Telephony Server.
TelSysInfo Get information about a Telephony Server.
TelSysList List all Telephony Servers assigned to your Akixi account.

# 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

Parameter Name Cisco Broadworks Broadsoft M6 Siemens/Unify HiPath3000 Panasonic TDA/NCP Demo Simulator
TelSysID ✅ ✅ ✅ ✅ ✅
TelSysType ✅ ✅ ✅ ✅ ✅

# Fully Updatable Properties

Parameter Name Cisco Broadworks Broadsoft M6 Siemens/Unify HiPath3000 Panasonic TDA/NCP Demo Simulator
Description ✅ ✅ ✅ ✅ ✅
BillingTag ✅ ✅ ✅ ✅ ✅
TimeZone ✅ ✅ ✅ ✅ ✅
CMEnvironmentID ✅ ✅ ✅ ✅ ✅
IPAddrOrHost1 ✅ ✅ ✅ ✅ ✅
IPAddrOrHost2 ✅ ✅ ✅ ✅ ✅
IPAddrOrHost3 ✅ ✅ ✅ ✅ ✅
IPAddrOrHost4 ✅ ✅ ✅ ✅ ✅
TCPPort1 ✅ ✅ ✅ ✅ ❌
TCPPort2 ✅ ✅ ❌ ❌ ❌
TCPPort3 ✅ ✅ ❌ ❌ ❌
TCPPort4 ✅ ❌ ❌ ❌ ❌
UseSSLTLS1 ❌ ❌ ✅ ✅ ❌
UseSSLTLS2 ✅ ✅ ❌ ❌ ❌
UseSSLTLS3 ❌ ❌ ❌ ❌ ❌
UseSSLTLS4 ✅ ❌ ❌ ❌ ❌
AuthUserID1 ❌ ❌ ❌ ❌ ❌
AuthUserID2 ✅ ❌ ❌ ❌ ❌
AuthUserID3 ❌ ❌ ❌ ❌ ❌
AuthUserID4 ✅ ❌ ❌ ❌ ❌
AuthPassword1 ❌ ❌ ❌ ❌ ❌
AuthPassword2 ✅ ❌ ❌ ❌ ❌
AuthPassword3 ❌ ✅ ❌ ❌ ❌
AuthPassword4 ✅ ❌ ❌ ❌ ❌
CommsParameter1 ✅ ❌ ❌ ❌ ❌
CommsParameter2 ✅ ❌ ❌ ❌ ❌
CommsEnabled ✅ ✅ ✅ ✅ ✅
InternalDigitLen ✅ ✅ ❌ ❌ ❌
CountryCode ✅ ❌ ❌ ❌ ❌
OmniChannelPermitted ❌ ❌ ❌ ❌ ✅
CallControlOptions ❌ ❌ ❌ ❌ ✅
DeleteACDAgentsOnLicenseDowngrade ❌ ❌ ✅ ✅ ❌
SyncNow ❌ ❌ ❌ ✅ ❌
TelNoPrefixes ✅ ✅ ✅ ✅ ✅
LicensedForRptUserType ❌ ❌ ✅ ✅ ❌
AutoDeleteUsers ✅ ✅ ✅ ✅ ✅
ManageUserMFA ✅ ✅ ✅ ✅ ✅
XSPServer ✅ ❌ ❌ ❌ ❌

# Advanced Properties (Advanced Container)

Parameter Name Cisco Broadworks Broadsoft M6 Siemens/Unify HiPath3000 Panasonic TDA/NCP Demo Simulator
CTILogEnabled ✅ ✅ ✅ ✅ ✅
CTICallModelLogEnabled ✅ ✅ ✅ ✅ ✅
InternalDiagDumpEnabled ✅ ✅ ✅ ✅ ✅
CTILogIncClassNames ✅ ✅ ✅ ✅ ✅
CallModelDiagDumpEnabledForCalls ✅ ✅ ✅ ✅ ✅
CallModelDiagDumpEnabledForDev ✅ ✅ ✅ ✅ ✅
PartitionCountMax ✅ ✅ ✅ ✅ ✅
PartitionsRptingScopeAllEnabled ✅ ✅ ✅ ✅ ✅

Recommendation

It is strongly recommended to specifically set the value of the TelSysID Property when programmatically creating new Telephony Server components via external provisioning or billing systems TelSysID values, Aggregators with a dedicated Akixi Service URL will have their own Akixi-assigned start range for which they should automatically self-track & increment internally within their own automated system(s). To find out the starting range of yourTelSysID Property, sign into your Akixi Service via the web interface and view the last existing Telephony Server entry that has already been manually pre-created, either as a demonstration simulator environment, a hosted platform lab test connectivity test, or for actual live Customer environments. Then add 1 to this value.

# 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>
        <!-- Other configuration Properties. -->
        <Property Name="TelNoPrefixes"/>
        <Property Name="InternalDigitLen">4</Property>
        <Property Name="CountryCode">44</Property>
		<Property Name="ManageUserMFA">True</Property>
        <!-- Broadsoft BroadWorks-specific parameters -->
        <Property Name="XSPServer">server1.bwks.com</Property>
        <!-- Custom tag(s) that is added against the new Telephone Server component being created. -->
        <!-- Note: (1) Tag(s) must be strictly alphanumeric. -->
        <!--       (2) Each tag must not contain any spaces. -->
        <!--       (3) Each tag must be of maximum 25 characters. -->
        <!--       (4) Each tag must be separated by a comma. -->
        <!--       (5) Total limit for all tag characters is 225. -->
        <!--       (6) Default tag of provisioning method (Soap) will be added by default. -->
        <!--       (7) Once Telephone Server has been created, tag values cannot be added or changed.-->
        <Property Name="Tags">Tag1, Tag2</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>
            <Property Name="UserNotificationsEnabled">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:

Error Type Error Codes
General Error Codes 10101, 10103, 10150, 10201
Session Related Error Codes 10301, 10302
Authentication Related Error Codes 10305, 10307, 10313
Permissions Related Error Codes 10511, 10512, 10515, 10700, 10701, 10702
Telephony Server Component Related Error Codes 11010, 11011, 11014, 11021, 11022

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>
        <!-- Other configuration Properties. -->
        <Property Name="TelNoPrefixes"/>
        <Property Name="InternalDigitLen">4</Property>
        <Property Name="CountryCode">44</Property>
		<Property Name="ManageUserMFA">True</Property>
        <!-- Broadsoft BroadWorks-specific parameters -->
        <Property Name="XSPServer">server1.bwks.com</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>
            <Property Name="UserNotificationsEnabled">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:

Error Type Error Codes
General Error Codes 10101, 10103, 10150, 10201
Session Related Error Codes 10301, 10302
Authentication Related Error Codes 10305, 10307, 10313
Permissions Related Error Codes 10511, 10512, 10515, 10700, 10701, 10702
Telephony Server Component Related Error Codes 11012, 11013

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.

Warning

You will not be able to restore the deleted Telephony Server component once it is deleted. This operation will also delete all Partitions, devices, and ACD agent configuration entries that are associated & owned by the deleted Telephony Server entry.

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:

Error Type Error Codes
General Error Codes 10101, 10103, 10105, 10106, 10170
Session Related Error Codes 10301, 10302
Authentication Related Error Codes 10305, 10307, 10313
Permissions Related Error Codes 10511, 10513, 10700, 10701, 10702
Telephony Server Component Related Error Codes 11012, 11013, 11020

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). If you want to only list Telephony Servers containing a specific TelSysID or Description, you can request for it via SearchQuery Payload Property. 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,Tags</Property>
        <!-- Optional property to list Telephony Servers containing a specific TelSysID or Description. -->
        <Property Name="SearchQuery">Add TelSysID or Description to query</Property>
    </OperationPayload>
</Request>

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

  • TelSysID *
  • Description *
  • TelSysType
  • CommsStatus
  • LicensedForRptUserType
  • DateTimeCreated
  • UserCount
  • ExtCount
  • Tags

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. If SearchQuery Payload Property was requested for, then operation's response will only contain Telephony Servers whose default properties match the search query provided:

<Response Result="Success">
    <InvokeID>00007</InvokeID>
    <Success>
        <Container>
            <!-- Only TelSysID and Description parameters are returned by default. -->
            <Property Name="TelSysID">1001</Property>
            <Property Name="Description">Telephony Server 1001</Property>
            <!-- Parameters below were requested via TelSysFields Property. -->
            <Property Name="TelSysType">BroadSoft Broadworks</Property>
            <Property Name="CommsStatus">Running</Property>
            <!-- Default provisioning method tag (Soap) added by default to Telephone Server component. -->
            <Property Name="Tags">Soap,Tag1,Tag2</Property>
        </Container>
        <Container>
            <!-- Only TelSysID and Description parameters are returned by default. -->
            <Property Name="TelSysID">1002</Property>
            <Property Name="Description">Telephony Server 1002</Property>
            <!-- Parameters below were requested via TelSysFields Property. -->
            <Property Name="TelSysType">BroadSoft Broadworks</Property>
            <Property Name="CommsStatus">Out-Of-Service</Property>
            <!-- Default provisioning method tag (Soap) added by default to Telephone Server component. -->
            <Property Name="Tags">Soap</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:

Error Type Error Codes
General Error Codes 10101, 10103
Session Related Error Codes 10301, 10302
Authentication Related Error Codes 10305, 10307, 10313
Permissions Related Error Codes 10511, 10700, 10701, 10702

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="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>
            <Property Name="UserNotificationsEnabled">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:

Error Type Error Codes
General Error Codes 10101, 10103
Session Related Error Codes 10301, 10302
Authentication Related Error Codes 10305, 10307, 10313
Permissions Related Error Codes 10511, 10512, 10700, 10701, 10702
Telephony Server Component Related Error Codes 11012, 11013

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

← Partitions (Tenants) →