# Codes (Account & Not Available Codes)

Code configuration entries are required to allow the application’s reporting functionality to recognise, match, and display descriptions for account/authorisation & ACD Not-Available codes, whenever they are entered in for calls and/or the appropriate ACD state transitions. Code entries do not affect monthly billing charges.

# Supported Operations

The list of currently supported Code configuration entry operations is provided below. Operations related to Codes start with a “Code” prefix. They will be referred to as “Code Operations” interchangeably hereafter. Note that there is no request type that supports changing an existing Code configuration entry in one operation – to effectively perform a Code change operation, you can delete the existing code and then appropriately add a new Code.

# Configuring Code Entries

# Code Capture & Usage Reporting Support

The ability to report on Account Code and ACD Not-Available (N/A) Code usage depends on the telephony platform type. Therefore the requirement to configure Code entries within the Akixi Service is implicitly dependent on the telephone platform capabilities as follows:

# PBX Platforms

# Hosted Platforms

# Code Entry Configuration

Depending on the telephony platform type, you would need to programmatically create Code entries via the Web Services API for Customer environments that need to report on code usage:

# PBX Platforms

# Hosted Platforms

# Code Request Parameters

Parameters used within CodeAdd, CodeChange, CodeDelete, CodeList, and CodeInfo 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 CodeXXX parameters, please refer to the “Code Properties” sub-section of the “Configuration-Specific Properties” chapter.

# CodeAdd

The CodeAdd request can be used to add a new Code entry within a specified Partition component.

# CodeAdd Request

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

Below shows an example of a platform-specific Code entry creation operation. This request includes all parameters supported by CodeAdd operation invoked in order to create a new Code entry for a Cisco BroadWorks® telephony platform.

Depending on your initial requirements, your actual request might be different from the sample request below.

<Request Operation="CodeAdd">
    <InvokeID>00029</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <OperationPayload>
        <Property Name="CodeGUID">a90af144db21324e:-112ab3c:18c011e2445:70cd</Property>
        <Property Name="UpdateExistingItems">false</Property>
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
        <Property Name="Code">100</Property>
        <Property Name="Description">Sales</Property>
        <Property Name="CodeType">Account Code</Property>
        <Property Name="IDOnTelSysOwner">SampleEnt3Grp1</Property>
    </OperationPayload>
</Request>

# CodeAdd Response

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

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

You will now be able to access the newly created Code entry by invoking other Code-related WS API requests. The Code entry can also be viewed & modified via the Administration Codes facility with the Akixi Web Application.

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:

# CodeChange

The CodeChange request can be used to update an existing Code entry within a specified Partition component.

# CodeChange Request

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

Below shows an example of a platform-specific Code Change operation. This request includes all parameters supported by CodeChange operation invoked in order to update a Code entry for a Cisco BroadWorks® telephony platform.

Depending on your initial requirements, your actual request might be different from the sample request below.

<Request Operation="CodeChange">
    <InvokeID>00030</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <OperationPayload>
        <Property Name="CodeGUID">a90af144db21324e:-112ab3c:18c011e2445:70cd</Property>
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
        <Property Name="Code">100</Property>
        <Property Name="Description">Sales</Property>
        <Property Name="CodeType">Account Code</Property>
        <Property Name="IDOnTelSysOwner">SampleEnt3Grp1</Property>
    </OperationPayload>
</Request>

# CodeChange Response

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

<Response Result="Success">
    <InvokeID>00030</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:

# CodeDelete

Code entries can be removed via the CodeDelete request.

# CodeDelete Request

The request below shows an example of a Code entry deletion operation. This request includes all parameters supported by CodeDelete operation invoked in order to delete an existing Code record (where the Code value is 100). Note that a code is uniquely identified by four parameters within Akixi’s configuration which are TelSysID, PartIDInTelSys, Code and CodeType.

<Request Operation="CodeDelete">
    <InvokeID>00031</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <OperationPayload>
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
        <Property Name="Code">100</Property>
        <Property Name="CodeType">Account Code</Property>
    </OperationPayload>
</Request>

# CodeDelete Response

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

<Response Result="Success">
    <InvokeID>00031</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:

# CodeList

The CodeList operation can be used to list all Akixi Code entries that are configured against a certain Telephony Server/Partition component within the Akixi Service.

# CodeList Request

By default, the body of CodeList requests is quite minimalistic: you can simply specify the Telephony Server Identifier and Partition Identifier within a Telephony Server in order to obtain the list of all underlying Code identifiers and descriptions. If you want to only list Codes containing a specific Code 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.

<Request Operation="CodeList">
    <InvokeID>00032</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <!-- Specify the number of entries to skip. -->
    <Offset>100</Offset>
    <!-- Specify how many entries to retrieve after the offset. -->
    <Limit>20</Limit>
    <OperationPayload>
        <!-- Specify a Telephony Server component Identifier. -->
        <Property Name="TelSysID">100100</Property>
        <!-- Specify a Partition Identifier within a Telephony Server. -->
        <Property Name="PartIDInTelSys">2</Property>
        <!-- Can be used to list additional parameters of each Code entry. -->
        <Property Name="CodeFields">CodeType,TelSysID,PartIDInTelSys</Property>
        <!-- Optional property to list Codes containing a specific Code or Description. -->
        <Property Name="SearchQuery">Add Code or Description to query</Property>
    </OperationPayload>
</Request>

The CodeList operation can return following Code configuration entry Properties:

• Code*
• Description *
• CodeType
• TelSysID
• PartIDInTelSys

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

# CodeList Response

If a CodeList operation is successful, then you’ll receive a list of Codes and their Properties. If additional parameters were not provided within your request, you will receive default Properties of all Codes (i.e. Code and Description values). If additional fields were requested via CodeFields Property, then corresponding values will also be returned within the operation’s response. If SearchQuery Payload Property was requested for, then operation's response will only contain Codes whose default properties match the search query provided:

<Response Result="Success">
    <InvokeID>00032</InvokeID>
    <Success>
        <Container>
            <Property Name="Code">100</Property>
            <Property Name="CodeGUID">a90af144db21324e:-112ab3c:18c011e2445:70cd</Property>
            <Property Name="Description">Break</Property>
            <!-- Parameters below were requested via CodeFields Property.-->
            <Property Name="CodeType">Account Code</Property>
            <Property Name="TelSysID">100100</Property>
            <Property Name="PartIDInTelSys">2</Property>
        </Container>
        <Container>
            <Property Name="Code">200</Property>
            <Property Name="Description">Meeting</Property>
            <!-- Parameters below were requested via CodeFields Property.-->
            <Property Name="CodeType">Account Code</Property>
            <Property Name="TelSysID">100100</Property>
            <Property Name="PartIDInTelSys">2</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.

# CodeInfo

The CodeInfo request can be used to obtain information related to a certain Code entry.

# CodeInfo Request

The request below includes parameters supported by the CodeInfo operation. This operation requests the list of all code-related Properties (where the Code Property is 100). Note that a code is uniquely identified by four parameters within Akixi’s configuration which are TelSysID, PartIDInTelSys, Code and CodeType.

<Request Operation="CodeInfo">
    <InvokeID>00033</InvokeID>
    <SessionID>EFA4902A7F61D03E42BF3222B0A246BF</SessionID>
    <OperationPayload>
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
        <Property Name="Code">100</Property>
        <Property Name="CodeType">Account Code</Property>
    </OperationPayload>
</Request>

# CodeInfo Response

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

<Response Result="Success">
    <InvokeID>00033</InvokeID>
    <Success>
        <Property Name="Code">100</Property>
        <Property Name="CodeGUID">a90af144db21324e:-112ab3c:18c011e2445:70cd</Property>
        <Property Name="CodeType">Account Code</Property>
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
        <Property Name="Description">Break</Property>
        <Property Name="IDOnTelSysOwner">SampleEnt3Grp</Property>
    </Success>
</Response>

This response includes all parameters returned by the CodeInfo operation invoked in order to obtain code-related Properties of a Cisco BroadWorks® telephony platform.

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.