# Directory Entries

A Directory Entry defines a description for a given telephone number, allowing for easier identification of the number within reports.

# Supported Operations

The supported Directory Entry operations are listed below. Operations related to Directory Entries start with a DirectoryEntry prefix.

# Directory Entry Request Parameters

Parameters used within DirectoryEntryXXX operations are listed in the tables below.

To learn more about DirectoryEntryXXX parameters, please refer to the section Configuration Specific Properties > Directory Entry Properties or click here.

# Read-Only properties after initial creation

Properties listed in the table below cannot be changed after the initial creation of the Directory Entry. If any of these properties are passed into the DirectoryEntryChange operations' request body, it will be ignored.

# General properties

These properties are common and can be changed as needed, provided the user has access to the target component.

# DirectoryEntryAdd

The DirectoryEntryAdd request operation can be used to add a new Directory Entry.

# DirectoryEntryAdd Request

Below shows an example of a Directory Entry creation operation. This request includes all parameters supported by the DirectoryEntryAdd operation invoked to create a new Directory Entry.

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

# DirectoryEntryAdd Request

<Request Operation="DirectoryEntryAdd">
    <InvokeID>7</InvokeID>
    <SessionID>19397C980B72D043EEE18B58AE687263</SessionID>
    <OperationPayload>
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
        <Property Name="TelephoneNumber">01234567890</Property>
        <Property Name="Description">Derek Trotter</Property>
    </OperationPayload>
</Request>

# DirectoryEntryAdd Response

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

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

You will now be able to access the newly created Directory Entry by invoking other Directory Entry-related WS API requests. The Directory Entry can also be viewed and modified via the Administration > Directory facility on 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 listed in the table below:

# DirectoryEntryChange

The DirectoryEntryChange request operation can be used to change an existing Directory Entry.

# DirectoryEntryChange Request

The request below shows an example of a Directory Entry change operation. This example includes all parameters supported by the DirectoryEntryChange operation invoked to change the properties of an existing Directory Entry.

<Request Operation="DirectoryEntryChange">
    <InvokeID>12</InvokeID>
    <SessionID>19397C980B72D043EEE18B58AE687263</SessionID>
    <OperationPayload>
        <!-- Properties to identify a Partition. -->
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
        <!-- TelephoneNumber Property is used to identify an existing Directory Entry. -->
        <Property Name="TelephoneNumber">01234567890</Property>
        <!-- NewTelephoneNumber Property is used to specify a new telephone number for the Directory Entry. -->
        <Property Name="NewTelephoneNumber">09876543210</Property>
        <Property Name="Description">Derek Trotter</Property>
    </OperationPayload>
</Request>

# DirectoryEntryChange Response

If your operation was successful, you will receive a response like the following.

<Response Result="Success">
    <InvokeID>12</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 listed in the table below:

# DirectoryEntryDelete

Directory Entries can be deleted using the DirectoryEntryDelete request operation.

# DirectoryEntryDelete Request

The request below shows an example of a Directory Entry deletion operation. This request includes all parameters supported by the DirectoryEntryDelete operation invoked in order to delete an existing Directory Entry (where the CallRecIntGUID value is 67e10ae5bbb0dd46:-2442a791:17c5635ac06:-7e26)

<Request Operation="DirectoryEntryDelete">
    <InvokeID>13</InvokeID>
    <SessionID>19397C980B72D043EEE18B58AE687263</SessionID>
    <OperationPayload>
        <!-- Properties to identify a Partition. -->
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
        <!-- TelephoneNumber property is used to identify an existing Directory Entry. -->
        <Property Name="TelephoneNumber">01234567890</Property>
    </OperationPayload>
</Request>

# DirectoryEntryDelete Response

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

<Response Result="Success">
    <InvokeID>13</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 listed in the table below:

# DirectoryEntryList

The DirectoryEntryList operation can be used to list all Akixi Directory Entries that are configured against a certain Partition component within the Akixi Service.

# DirectoryEntryList Request

A sample request body of the DirectoryEntryList operation is shown below. The list of underlying Directory Entries can be fetched using the combination of the Telephony Server ID (TelSysID) and partition ID in the Telephony Server (PartIDInTelSys). If you want to only list Directory Entries containing a specific TelephoneNumber 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="DirectoryEntryList">
    <InvokeID>14</InvokeID>
    <SessionID>19397C980B72D043EEE18B58AE687263</SessionID>
    <!-- Specify the number of entries to skip. -->
    <Offset>100</Offset>
    <!-- Specify how many entries to retrieve after the offset. -->
    <Limit>20</Limit>
    <OperationPayload>
        <!-- Returns all Directory Entries scoped to provided TelSysID and PartIDInTelSys. -->
        <Property Name="TelSysID">1</Property>
        <Property Name="PartIDInTelSys">1</Property>
        <!-- Optional property to list Directory Entries containing a specific TelephoneNumber or Description. -->
        <Property Name="SearchQuery">Add TelephoneNumber or Description to query</Property>
    </OperationPayload>
</Request>

# DirectoryEntryList Response

If the DirectoryEntryList operation is successful, then you will receive a list of Directory Entries and their properties. By default, the response of the DirectoryEntryList operation includes all properties. If SearchQuery Payload Property was requested for, then operation's response will only contain Directory Entries whose TelephoneNumber or Description match the search query provided:

<Response Result="Success">
    <InvokeID>14</InvokeID>
    <Success>
        <Container>
            <Property Name="TelephoneNumber">01234567890</Property>
            <Property Name="Description">Derek Trotter</Property>
            <Property Name="TelSysID">100100</Property>
            <Property Name="PartIDInTelSys">2</Property>
        </Container>
        <Container>
            <Property Name="TelephoneNumber">09876543210</Property>
            <Property Name="Description">Lewis Stone</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 listed in the table below:

# DirectoryEntryInfo

The DirectoryEntryInfo operation can be used to obtain complete information related to a certain already existing Directory Entry.

# DirectoryEntryInfo Request

The request below includes parameters supported by the DirectoryEntryInfo operation. This operation requests the list of all properties of a Directory Entry.

<Request Operation="DirectoryEntryInfo">
    <InvokeID>15</InvokeID>
    <SessionID>19397C980B72D043EEE18B58AE687263</SessionID>
    <OperationPayload>
        <!-- Properties to identify a Partition. -->
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
        <!-- TelephoneNumber property is used to identify an existing Directory Entry. -->
        <Property Name="TelephoneNumber">01234567890</Property>
    </OperationPayload>
</Request>

# DirectoryEntryInfo Response

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

<Response Result="Success">
    <InvokeID>15</InvokeID>
    <Success>
        <Property Name="TelephoneNumber">01234567890</Property>
        <Property Name="Description">Derek Trotter</Property>
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
    </Success>
</Response>

This response includes all parameters returned by the DirectoryEntryInfo operation invoked to obtain all properties of a Directory Entry.

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 listed in the table below:

# DirectoryEntryBulkUpload

The DirectoryEntryBulkUpload operation can be used to upload multiple Directory Entries at once from an attached CSV.

The bulk upload process is initiated with a request that has the OperationType parameter set as Start and requires an attached CSV file containing information about the Directory Entries to be added. The template CSV can be downloaded from the Directory Entry admin page on the Akixi portal, then once filled out it can be attached to the Start request or converted the Base64 and included in the OperationPayload container.

If the Start request is successful then the Directory Entries can be added by sending another request with the OperationType parameter set to Confirm, or the process can be cancelled by setting the OperationType parameter to Cancel.

# DirectoryEntryBulkUpload Request

The request below includes parameters supported by the DirectoryEntryBulkUpload operation. This operation starts the bulk upload process and in this instance has the attachment in the request as encoded Base64.

<Request Operation="DirectoryEntryBulkUpload">
    <InvokeID>15</InvokeID>
    <SessionID>19397C980B72D043EEE18B58AE687263</SessionID>
    <OperationPayload>
        <!-- Properties to identify a Partition. -->
        <Property Name="TelSysID">100100</Property>
        <Property Name="PartIDInTelSys">2</Property>
        <!-- TelephoneNumber property is used to identify an existing Directory Entry. -->
        <Property Name="OperationType">Start</Property>
        <!-- Attached CSV file encoded as Base64. -->
        <Attachment contentType="text/csv" FileName="filename.csv">VGVsZXBob25lIE51bWJlcixEZXNjcmlwdGlvbg0KMTIzNDU2Nzk5OSxUZXN0IHVzZXIgMw0KOTg3NjU0MzIyMixUZXN0IHVzZXIgNA0K</Attachment>
    </OperationPayload>
</Request>

# DirectoryEntryBulkUpload Response

If the DirectoryEntryBulkUpload operation is successful, then you will receive a list of the added Directory Entries and their properties.

<Response Result="Success">
    <InvokeID>15</InvokeID>
    <Success>
        <Container Name="ValidRows">
            <Container>
                <Property Name="TelephoneNumber">01234567890</Property>
                <Property Name="Description">Derek Trotter</Property>
            </Container>
            <Container>
                <Property Name="TelephoneNumber">09876543210</Property>
                <Property Name="Description">Lewis Stone</Property>
            </Container>
        </Container>
        <Container Name="ValidationErrors"/>
    </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. Errors with the individual entries within the csv attachment will be listed within the ValidationErrors container:

<Response Result="Fail">
    <InvokeID>45856</InvokeID>
    <Success>
        <Container Name="ValidRows"/>
        <Container Name="ValidationErrors">
            <Container>
                <Property Name="LineNumber">2</Property>
                <Property Name="ID">01234567890</Property>
                <Property Name="HasPlaceholder">true</Property>
                <Property Name="ErrorCode">11712</Property>
                <Property Name="ErrorMessage">A directory entry with '01234567890' telephone number already existing in partition with PartIDInTelSys '2'.</Property>
            </Container>
            <Container>
                <Property Name="LineNumber">3</Property>
                <Property Name="ID">09876543210</Property>
                <Property Name="HasPlaceholder">true</Property>
                <Property Name="ErrorCode">11712</Property>
                <Property Name="ErrorMessage">A directory entry with '09876543210' telephone number already existing in partition with PartIDInTelSys '2'.</Property>
            </Container>
        </Container>
    </Success>
</Response>

Some common errors returned by this operation are listed in the table below: