MongoDB Database Integration

Introduction

3CX provides integration with MongoDB databases via the 3CX API for CRM. The collections structure inside each database is different, so a template cannot be provided ready for use out of the box. Since your JSON structure is unknown and cannot be mapped to variables, we provide a sample template that you can easily adapt to fulfill your needs.

This sample template enables you to perform these tasks with a MongoDB database:

  • Caller ID to Contact Name – inbound calls trigger a MongoDB database contact lookup.
  • Contact Lookup in MongoDB database based on Name, Number or Email if you search for a name in the 3CX Webclient
  • Call & Chat Journalling – calls and chats are logged in the MongoDB database.
  • Create a new MongoDB database contact from the 3CX client for calls from new numbers.
  • Click to Call – Providing that your system is a web application, launch calls straight from your system via 3CX, using the 3CX Click2Call Browser extensions for Google Chrome and Microsoft Edge.

Prepare the Template

Step 1 - Download the Sample Template

You can download the sample template via the 3CX Management Console from “Settings” > “CRM Integration” > “Server Side” tab > “Database MongoDB” > “Show Template”.

This template is based on a MongoDB database with two collections, one for contacts and one for contact calls. The names of the database and the collections are defined in the template parameters. Objects in the

ContactsCollection
have this structure:

{

    _id: "5b99567d1c9d440000d34328",

    Name: {

        FirstName: "John"

        LastName: "Doe"

    },

    Phones: {

        Work: "1155551001",

        Mobile: "1155551002"

    },

    Email: "[email protected]"

}

While objects in the

CallsCollection
have this structure:

{

    _id: "5bf41e571be56017b4a92727",

    Subject: "3CX 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 "

}

Open the XML template using a text editor and note:

  1. Parameters
    : shown in the 3CX console, and let you configure your template.
  2. Scenarios
    : define how 3CX interacts with MongoDB in the sample template scenarios:
  1. (no Id specified) for contact lookup
  2. [code]Id="ReportCall" for call journaling
  3. [code]Id="CreateContactRecord" for contact creation

Step 2 - Edit the Template - 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: {{ { &quot;Phones.Work&quot;: { $regex: &quot;[Number]$&quot; } }, { &quot;Phones.Mobile&quot;: { $regex: &quot;[Number]$&quot; } } }} }" />

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

To edit this scenario follow these steps:

  1. In the
    Command
    element, you need to 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. You 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. You 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 can use the variables created in the previous step between brackets, e.g.
    [FirstName]
    . The valid output fields are:
  1. ContactUrl
  2. FirstName
  3. LastName
  4. CompanyName
  5. Email
  6. PhoneMobile
  7. PhoneMobile2
  8. PhoneHome
  9. PhoneHome2
  10. PhoneBusiness
  11. PhoneBusiness2
  12. PhoneOther
  13. FaxBusiness
  14. FaxHome
  15. Pager
  16. PhotoUrl

Step 3 - Edit the Template - 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, that describes how 3CX 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 3CX.

Step 4 - Edit the Template - Chat Journaling

The chat journaling scenario [code]Id="ReportChat" in the XML template is used to create chat records in MongoDB and executes when the chat is dealt with, i.e.:

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

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

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

        <CommandData>

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

          <Value Key="Number" If="[Number]!=&quot;&quot;">[Number]</Value>

          <Value Key="Email" If="[Email]!=&quot;&quot;">[Email]</Value>

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

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

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

          <Value Key="Description">[ChatMessages]</Value>

        </CommandData>

      </Command>

    </Scenario>

To edit this scenario follow these steps:

  1. In the
    Command
     element, you need to edit the
    CommandData
     child element, that describes how 3CX 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 3CX.

Step 5 - Edit the Τemplate - Contact Creation

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

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

      <Command SkipIf="[CreateContactEnabled]!=True"

                                       DatabaseType="MongoDB" ConnectionString="[ConnectionString]"

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

        <CommandData>

          <Object Key="Name">

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

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

          </Object>

          <Object Key="Phones" If="[Number]!=&quot;&quot;">

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

          </Object>

          <Value Passes="1" Key="Email" Type="String" If="[Email]!=&quot;&quot;">[Email]</Value>

        </CommandData>

      </Command>

      <Rules>

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

      </Rules>

      <Variables>

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

      </Variables>

      <Outputs AllowEmpty="false">

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

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

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

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

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

        <Output Type="EntityType" Value="Contacts" />

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

      </Outputs>

    </Scenario>

To edit the contact creation scenario follow these steps:

  1. In the
    Command
     element, you need to edit the
    CommandData
     child element that describes how 3CX should create the JSON object to insert in MongoDB. In this sample, the object to insert has nested child properties, i.e.
    Name
     and
    Phones
    . Edit this according to the structure of the object you need to insert.
  2. The
    Rules
     element identifies the record and can be left unchanged to get the ID of the inserted record.
  3. The
    Variables
     element is used to get the record info.
  4. The
    Outputs
     element needs to match the data from the contact lookup scenario.

Step 6 - Edit the Τemplate - Search Contacts

The search contacts scenario [code]Id="SearchContacts" in the XML template is used to search contact records in MongoDB from the 3CX client, i.e.:

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

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

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

               Command="{ $or: {{ { &quot;Phones.Work&quot;: { $regex: &quot;[SearchText]$&quot; } }, { &quot;Phones.Mobile&quot;: { $regex: &quot;[SearchText]$&quot; } }, { &quot;Email&quot;: { $regex: &quot;[SearchText]$&quot; } }, { &quot;Name.FirstName&quot;: { $regex: &quot;[SearchText]$&quot; } }, { &quot;Name.LastName&quot;: { $regex: &quot;[SearchText]$&quot; } } }} }" />

      <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="Phone">Phones.Work</Variable>

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

      </Variables>

      <Outputs AllowEmpty="false">

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

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

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

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

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

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

        <Output Type="EntityType" Value="Contacts" />

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

      </Outputs>

    </Scenario>

To edit the search contacts scenario follow these steps:

  1. In the
    Command
    element, you need to edit the
    Command
    attribute filtering expression. In the sample we filter objects for which the properties Phone, Mobile, FirstName or LastName contain the text being searched. You need to create a filtering expression that returns the correct objects from the contacts collection.
  2. The
    Rules
     element identifies the record and can be left unchanged to get the ID of the inserted record.
  3. The
    Variables
     element is used to get the record info.
  4. The
    Outputs
     element needs to match the data from the search contacts scenario.

Step 7 - Upload the Template to 3CX

Once you have finished editing the template according to your MongoDB collections and objects structure, you need to upload it via the 3CX Management Console:

  1. Go to “Settings” > “CRM Integration” > “Server Side” tab.
  2. Click “Add”, select the XML template file you edited, and upload it.
  3. Proceed to configure the connection to MongoDB.

Configure 3CX

To configure your MongoDB connection in 3CX Management Console, go to “Settings” > “CRM Integration” > “Server Side” tab and:

  1. Select MongoDB from the dropdown list.
  2. Enter the “Connection String”. You can get it from the tool you use to connect to MongoDB.
  3. Define the “Database” name.
  4. Enter the “Contacts Collection” name, i.e. the collection containing contact data.
  5. If you want to enable contact creation from the 3CX client, check this option. When the caller’s number can’t be matched to a contact, the 3CX client will let the user create the contact by filling the details in a dialog.

Configure Call & Chat Journaling

  1. To report external calls to MongoDB, check the “Enable Call Journaling” option, and configure these “Call Journaling” parameters:
  • “Calls Collection” - the collection in which calls will be inserted.
  • “Call Subject” - the call’s subject.
  • “Answered Inbound Call” - description for answered inbound calls.
  • “Missed Call” - description for missed calls.
  • “Answered Outbound Call” - description for answered outbound calls.
  • “Unanswered Outbound Call” - description for unanswered outbound calls.
  1. Please note that you can use variables in the “Call Journaling” parameters, denoted as
    [variable_name]
    , e.g. the external number is specified as
    [Number]
    . The available variables to use are listed
    here.

  1. Check the “Enable Chat Journaling” checkbox and configure the parameters below:
  • “Chats Collection”: The collection in which chats will be inserted.
  • “Chat Subject”: The subject of the chat session
  1. Please note that you can use variables in the “Chat Journaling” parameters, denoted as
    [variable_name]
    , e.g. the external number is specified as
    [Number]
    . The available variables to use are listed
    here.

See Also

Last Updated

This document was last updated on 24 September 2023

https://www.3cx.com/docs/mongodb-pbx-integration/ 

Discuss this article