Example: Connecting Toku Connect to MongoDB

Toku Connect integration for MongoDB is supported by the use of a plugin that we host on your Toku Connect instance. Here are details about how we implement this and other integrations.

Summary

In this example, we explain how a custom connector between Toku Connect and a MongoDB instance is configured to synchronize information between Toku Connect and MongoDB.

NOTE:

This is just an example of how the connector is configured for MongoDB. This is not a self-service installation process for MongoDB. All connectors must be configured differently, depending on the structure of each customer's MongoDB.

Table of Contents:

 

Introduction

Toku Connect provides integration with MongoDB databases. The collections structure inside each database is different, so a template cannot be provided ready for use out of the box.

Since the specific MongoDB JSON structure for your database is unknown and cannot be mapped to variables, automatically, we work with you to develop a custom mapping template that fulfills your specific needs.

The integration can support:

  • Contact Synchronization: Inbound calls from external numbers trigger a contact lookup in your database, and contact details are added to Toku Connect Contacts. This way, the caller name is automatically shown in your phone display when you receive the call.
  • Call Pop-ups: When using the Toku Connect Web Client, the customer record is brought up to you automatically when you receive an inbound call.
  • Call Journals: Calls are logged in the database.
  • Contact Creation: Create a new contact automatically when a call is received from an unknown number.

IMPORTANT!

Toku Connect is a fully-hosted service comprised of a user interface (3CX) and powered by Toku's enterprise-grade telephony infrastructure. Because Toku manages the entire solution on our customers' behalf, successful implementation of integrations requires that customers provide us with specific information about the configuration of their MongoDB instances, including information Toku Connect needs to successfully connect, login to, and perform operations on records in MongoDB, such as contact lookups, synchronization of contacts, and to journal call records.

Sample MongoDB connector template

The sample template described below is based on a MongoDB instance with two collections: one for contacts and one for contact call records. The names of the database and the collections are defined in the template parameters.

Here's a link to the full sample template: DOWNLOAD

Within the template, the example objects in the ContactsCollection have this structure:

{

    _id: "5b99567d1c9d440000d34328",

    Name: {

        FirstName: "John"

        LastName: "Doe"

    },

    Phones: {

        Work: "1155551001",

        Mobile: "1155551002"

    },

    Email: "johndoe@example.com"

}
Objects in the CallsCollection have this structure:
{

    _id: "5bf41e571be56017b4a92727",

  Subject: "Toku Connect PhoneSystem Call",

    Number: "123456",

    CallStartTime: "2018-11-20T16:40:50Z",

    CallEndTime: "2018-11-20T16:45:50Z",

    CallDuration: "05:00",

    CallType: "Inbound",

    Description: "11/20/2018 4:40 PM: Answered incoming call from 123456 John Smith "

}

To configure the template properly we need to define parameters and scenarios.

  1. Parameters: Depends on how your Toku Connect instance is set up.
  2. Scenarios: These define how Toku Connect interacts with your MongoDB in the following scenarios:
    1. (no Id specified) for contact lookup
    2. [code]Id="ReportCall" for call journaling
    3. [code]Id="CreateContactRecord" for contact creation

Contact Lookup

The provided contact lookup scenario in the sample XML template retrieves the contact details from MongoDB for a specific caller number, i.e.:

<Scenario Type="NoSQLDatabase">

    <Command DatabaseType="MongoDB" ConnectionString="[ConnectionString]"

             Database="[Database]" Collection="[ContactsCollection]" CommandType="Filter"

             Command="{ $or: }" />

    <Rules>

        <Rule Type="Any" Ethalon="">_id</Rule>

    </Rules>

    <Variables>

        <Variable Name="ContactID">_id.$oid</Variable>

        <Variable Name="FirstName">Name.FirstName</Variable>

        <Variable Name="LastName">Name.LastName</Variable>

        <Variable Name="Email">Email</Variable>

        <Variable Name="WorkPhone">Phones.Work</Variable>

        <Variable Name="Mobile">Phones.Mobile</Variable>

    </Variables>

    <Outputs AllowEmpty="false">

        <Output Type="ContactUrl" Value="http://example.com/[ContactID]" />

        <Output Type="ContactID" Value="[ContactID]"/>

        <Output Type="FirstName" Value="[FirstName]" />

        <Output Type="LastName" Value="[LastName]" />

        <Output Type="Email" Value="[Email]" />

        <Output Type="PhoneBusiness" Value="[WorkPhone]" />

        <Output Type="PhoneMobile" Value="[Mobile]" />

    </Outputs>

</Scenario>

We edit this scenario follow these steps:

  1. In the Command element, we edit the Command attribute filtering expression. In the sample, we filter objects for which the property Phone or the property Mobile end with the caller number. Note that for any connector we need to create a filtering expression that returns the correct objects from the contacts collection.
  2. The  Rules element identifies each record via the standard_id field, so editing this is not needed.
  3. The Variables element stores the values for each object returned. We need to edit the path, i.e. “Name.FirstName”“Name.LastName”, etc. according to the structure of the object returned from MongoDB. If you need to return more fields (other phones, a company name, etc.) you can add variables as needed.
  4. Finally, the Outputs element contains the data returned by the scenario, i.e. the contact lookup result. Here, we need to return a mandatory ContactUrl field, used to open the contact record in the browser and also uniquely identify the contact record, and any other output field. When we set an output value, we use the variables created in the previous step between brackets, e.g.[FirstName].

    The valid output fields are:
    • ContactUrl
    • FirstName
    • LastName
    • CompanyName
    • Email
    • PhoneMobile
    • PhoneMobile2
    • PhoneHome
    • PhoneHome2
    • PhoneBusiness
    • PhoneBusiness2
    • PhoneOther
    • FaxBusiness
    • FaxHome
    • Pager
    • PhotoUrl

Call Journaling

The call journaling scenario [code]Id="ReportCall" in the XML template is used to create call records in MongoDB and executes when the call ends, i.e.:

<Scenario Id="ReportCall" Type="NoSQLDatabase">

    <Command SkipIf="[ReportCallEnabled]!=True" DatabaseType="MongoDB" ConnectionString="[ConnectionString]"

             Database="[Database]" Collection="[CallsCollection]" CommandType="Insert">

        <CommandData>

            <Value Key="Subject" Passes="2">[[Subject]]</Value>

            <Value Key="Number">[Number]</Value>

            <Value Key="CallStartTime" Type="String">[[CallStartTimeUTC].ToString("yyyy-MM-ddTHH:mm:ssZ")]</Value>

            <Value Key="CallEndTime" Type="String">[[CallEndTimeUTC].ToString("yyyy-MM-ddTHH:mm:ssZ")]</Value>

            <Value Key="CallDuration">[Duration]</Value>

            <Value Key="CallType" Type="String">[CallType]</Value>

            <Value Key="Description" Passes="2" If="[CallType]==Inbound">[[InboundCallText]]</Value>

            <Value Key="Description" Passes="2" If="[CallType]==Missed">[[MissedCallText]]</Value>

            <Value Key="Description" Passes="2" If="[CallType]==Outbound">[[OutboundCallText]]</Value>

            <Value Key="Description" Passes="2" If="[CallType]==Notanswered">[[NotAnsweredOutboundCallText]]</Value>

        </CommandData>

    </Command>

</Scenario>

To edit this scenario follow these steps:

  1. In the Command element, you need to edit the CommandData child element, which describes how Toku Connect creates the JSON object to insert in MongoDB. In this sample, the object to insert has only string values as child properties, but you can create child objects or arrays as well.
  2. This scenario does not return any information to Toku Connect.

Contact Creation

The contact creation scenario [code]Id="CreateContactRecord" in the XML template is used to create contact records in MongoDB when the caller number is not found, i.e.:

<Scenario Id="CreateContactRecord" Type="NoSQLDatabase">

    <Command SkipIf="[CreateContactEnabled]!=True" DatabaseType="MongoDB" ConnectionString="[ConnectionString]"

             Database="Database" Collection="ContactsCollection" CommandType="Insert">

        <CommandData>

          <Object Key="Name">

            <Value Passes="1" Key="FirstName" Type="String">[CreateContactFirstName]</Value>

            <Value Passes="1" Key="LastName" Type="String">[CreateContactLastName]</Value>

          </Object>

          <Object Key="Phones">

            <Value Passes="1" Key="Work" Type="String">[Number]</Value>

          </Object>

        </CommandData>

    </Command>

    <Rules>

        <Rule Type="Any">_id</Rule>

    </Rules>

    <Variables>

        <Variable Name="ContactID" Path="_id.$oid"></Variable>

    </Variables>

    <Outputs AllowEmpty="false">

        <Output Type="ContactUrl" Value="http://example.com/[ContactID]" />

        <Output Type="ContactID" Value="[ContactID]"/>

        <Output Type="FirstName" Value="[CreateContactFirstName]" />

        <Output Type="LastName" Value="[CreateContactLastName]" />

        <Output Type="PhoneBusiness" Value="[Number]" />

    </Outputs>

</Scenario>

We edit the contact creation scenario as follows:

  1. We edit the CommandData child element of the Command element to describe how Toku Connect should create the JSON object to insert in MongoDB. In the example above, the object to insert has nested child properties, i.e. Name and Phones. We edit this according to the structure of the object you need to insert.
  2. We do not change the Rules element.
  3. We use the Variables element to get the record info.
  4. The Outputs element needs to match the data from the "contact lookup" scenario.

Implementation

Once we have created the template for your Toku Connect instance, using your MongoDB collections and objects structure, we need to install the connector on your Toku Connect account.

Connecting to MongDB

To configure the connection to your MongoDB, we need the following information:

  • Connection StringExample:
    mongodb+srv://admin:pass@testcluster.-fl4dx.mongodb.net/.test?retryWrites=true
  • Database Name  - This is self-explanatory.
  • Contacts Collection Name - the collection (database table) containing your contact records
  • Calls Collection Name - the collection (database table) that will contain call data records

Enabling Call Journaling

Toku will enable call journaling between Toku Connect and your MongoDB. We will also configure the information used to describe the different types of call events, and how they appear when synchronized with your MongoDB.

Examples:

Call Subject

Toku Connect PhoneSystem Call

Answered Inbound Call

[DateTime]: Answered incoming call from [Number] [Contact::FullName] to [Agent]([Duration])

Missed Call

[DateTime]: Missed call from [Number] [Contact::FullName] to [Agent]

Answered Outbound Call

[DateTime]: Answered outgoing call from [Agent] to [Number][Contact::FullName] ([Duration])

Unanswered Outbound Call

[DateTime]: Unnswered outgoing call from [Agent] to [Number][Contact::FullName]

Here is a complete list of the variables that can be included in these records: 

  • CallType - The type of call, it can be “Inbound”“Outbound”“Missed”, or “Unanswered”.
  • Number - The external contact number (the number dialed for outbound calls or the caller number for inbound calls).
  • Agent - The extension number of the agent handling the call.
  • Duration - The duration of the call in “hh:mm:ss” format.
  • DurationTimeSpan - The duration of the call as a TimeSpan object, which can be formatted as the user wants.
  • DateTime - The start date & time of the call, in local time zone, formatted using the local culture from the Toku Connect server.
  • CallStartTimeLocal - The start date & time of the call, in local time zone, as a DateTime object, which can be formatted as the user wants.
  • CallStartTimeUTC - The start date & time of the call, in UTC time zone, as a DateTime object, which can be formatted as the user wants.
  • CallEndTimeLocal - The end date & time of the call, in local time zone, as a DateTime object, which can be formatted as the user wants.
  • CallEndTimeUTC - The end date & time of the call, in UTC time zone, as a DateTime object, which can be formatted as the user wants.

Enable Contact Creation (Optional)

To create new contacts in MongoDB when the caller number is not found, we will enable "Contact Creation" so Toku Connect can inject new contacts when an inbound call from an unknown caller is received.

The system will create a new record in MongoDB with the Contact First and Last Names being "New", along with the number ([Number]) of the inbound caller.

Testing and Go-Live!

Once the connection to your MongoDB is configured we will test the connector to ensure that it works as expected.

At that point, Toku Connect will begin to sync call data between your Toku Connect accounts and your MongoDB database.