MongoDB Database Integration – Server Side

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:

  • Contact Synchronization – Inbound calls from external numbers trigger a contact lookup in your database, and contact details are added to 3CX Contacts. This way, the caller name is automatically shown in your phone display when you receive the call.
  • Call Pop-ups – When using the 3CX 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.
  • Create a new contact automatically when a call is received from an unknown number.

This guide takes you through the steps required to configure this sample template and setup your MongoDB database with 3CX.

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

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

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

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 Τemplate – 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.:

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 5 – 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.

3CX CRM Server Side Configuration

General Settings

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. Enter the “Calls Collection” name, i.e. the collection containing call data.

Call Journaling

To report external calls to MongoDB:

  1. Check the “Enable Call Journaling” checkbox and configure the associated fields, i.e. the Call Subject, and the text to use for the different call types (answered, missed, answered outbound or unanswered outbound).
  2. Please note that you can use variables in the fields above. Variables are specified between [ ], e.g. the external number is specified as [Number]. The available variables are:
    • 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 3CX 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.

Contact Creation

To create new contacts in MongoDB when the caller number is not found:

  1. Check the “Enable Contact Creation” checkbox and configure the “New Contact First Name” and “New Contact Last Name” fields.
  2. Note that you can use variables in the fields above, specified between [ ], i.e. the external number is specified as [Number]. The available variables are:
    • Number – The external contact number, i.e. the number dialed for outbound calls or the caller number for inbound calls.