MongoDB Database Integration
- Introduction
- Prepare the Template
- Step 1 - Download the Sample Template
- Step 2 - Edit the Template - Contact Lookup
- Step 3 - Edit the Template - Call Journaling
- Step 4 - Edit the Template - Chat Journaling
- Step 5 - Edit the Τemplate - Contact Creation
- Step 6 - Edit the Τemplate - Search Contacts
- Step 7 - Upload the Template to 3CX
- Configure 3CX
- Configure Call & Chat Journaling
- See Also
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
_id: "5b99567d1c9d440000d34328", Name: { FirstName: "John" LastName: "Doe" }, Phones: { Work: "1155551001", Mobile: "1155551002" }, Email: "[email protected]" }
While objects in the
_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:
- Parameters: shown in the 3CX console, and let you configure your template.
- Scenarios: define how 3CX interacts with MongoDB in the sample template scenarios:
- (no Id specified) for contact lookup
- [code]Id="ReportCall" for call journaling
- [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.:
<Command DatabaseType="MongoDB" ConnectionString="[ConnectionString]" Database="[Database]" Collection="[ContactsCollection]" CommandType="Filter" Command="{ $or: {{ { "Phones.Work": { $regex: "[Number]$" } }, { "Phones.Mobile": { $regex: "[Number]$" } } }} }" /> <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:
- In the Commandelement, you need to edit theCommandattribute 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.
- The Ruleselement identifies each record via the standard_idfield, so editing this is not needed.
- The Variableselement 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.
- Finally, the Outputselement contains the data returned by the scenario, i.e. the contact lookup result. Here, we need to return a mandatoryContactUrlfield, 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:
- ContactUrl
- FirstName
- LastName
- CompanyName
- Email
- PhoneMobile
- PhoneMobile2
- PhoneHome
- PhoneHome2
- PhoneBusiness
- PhoneBusiness2
- PhoneOther
- FaxBusiness
- FaxHome
- Pager
- 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.:
<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:
- In the Commandelement, you need to edit theCommandDatachild 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.
- 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.:
<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]!=""">[Number]</Value> <Value Key="Email" If="[Email]!=""">[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:
- In the Commandelement, you need to edit theCommandDatachild 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.
- 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.:
<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]!="""> <Value Passes="1" Key="Work" Type="String">[Number]</Value> </Object> <Value Passes="1" Key="Email" Type="String" If="[Email]!=""">[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:
- In the Commandelement, you need to edit theCommandDatachild 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.NameandPhones. Edit this according to the structure of the object you need to insert.
- The Ruleselement identifies the record and can be left unchanged to get the ID of the inserted record.
- The Variableselement is used to get the record info.
- The Outputselement 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.:
<Command DatabaseType="MongoDB" ConnectionString="[ConnectionString]" Database="[Database]" Collection="[ContactsCollection]" CommandType="Filter" Command="{ $or: {{ { "Phones.Work": { $regex: "[SearchText]$" } }, { "Phones.Mobile": { $regex: "[SearchText]$" } }, { "Email": { $regex: "[SearchText]$" } }, { "Name.FirstName": { $regex: "[SearchText]$" } }, { "Name.LastName": { $regex: "[SearchText]$" } } }} }" /> <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:
- In the Commandelement, you need to edit theCommandattribute 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.
- The Ruleselement identifies the record and can be left unchanged to get the ID of the inserted record.
- The Variableselement is used to get the record info.
- The Outputselement 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:
- Go to “Settings” > “CRM Integration” > “Server Side” tab.
- Click “Add”, select the XML template file you edited, and upload it.
- 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:
- Select MongoDB from the dropdown list.
- Enter the “Connection String”. You can get it from the tool you use to connect to MongoDB.
- Define the “Database” name.
- Enter the “Contacts Collection” name, i.e. the collection containing contact data.
- 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
- 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.
- 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.
- 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
- 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
- See how to integrate your CRM with the 3CX API.
- Learn how to set up Bitrix24 integration.
- Learn how to set up ConnectWise integration.
- Learn how to set up Freshdesk integration.
- Learn how to set up Jetpack CRM integration.
- Learn how to set up Zendesk integration.
- Learn how to set up Microsoft SQL Server, MySQL and PostgreSQL database integrations.
Last Updated
This document was last updated on 24 September 2023