Frequently Asked Questions

API

Contacts

I made a contact through the API. Why doesn't the assignedTo field get set according to lead routing rules?

When creating records through the API, all fields must be explicitly defined. One can, however, obtain an assignee for a new contact that is distributed according to lead routing type via the public "getLeadRoutingType" action of AdminController. An example of this can be found in APIModel (which is a class that was written for the express purpose of creating contacts and other records via the API).

Why doesn't the "Record Created" X2Flow trigger fire when creating a contact via API?

Note, the data submitted to the server should not contain the "createDate" field. If it does not, the field will be automatically set to the current timestamp at record insertion, and the "Record Created" trigger will be activated. Otherwise, it is assumed that a data import of some sort is happening, because a non-empty creation date implies that it was created on some other system first. In the latter case, the record created trigger will not be activated, and the field will not be automatically set.

Why doesn't the "Web Lead" X2Flow trigger fire when creating a web lead via API?

The "create" API method, intended as a generic method for creating records, cannot assume that it is being used for creating a web lead in particular. One might choose instead to create a flow triggered by record creation and add the criteria that the lead type must be "Web", and set the lead type to "Web" in the submission to the API, which be practically the same as having the web lead trigger activate in the API.

Actions & Action History

How do I create a note on a record?

Creating a note (or call log, or email, or any action history record) amounts to creating an action record with its association type set to the module name and the association ID to the ID of the record to which you'll be attaching the action history item. Note, the actionDescription attribute controls the content of the action record. So, for example (if using APIModel and attaching to contact 123):

$note->type = 'note';
$note->associationId = '123';
$note->associationType = 'contacts';
$note->actionDescription = 'text in the note';
$note->modelCreateUpdate('Actions', 'create');

Customization

Custom fields

I made a custom field and it doesn't show up. Now what?

Once you create a field, you must add it to the view and form as you see fit, as follows:

1. Go to "Admin"
2. Scroll down to the section "Utilities"
3. Go to "Form Editor"
4. Open the views/forms for the model by selecting the model from the "Model" dropdown
5. Select "Form (Default)" from the "Version" dropdown
6. Drag and drop the custom field into the form where it is desired.
7. Hit "Save"
8. Repeat the process with the "View" to change the record view page for the model type.

Why isn't any data going into my custom field getting saved?

If this occurs for a user that has been assigned any role, you will need to add permissions to that field for the role:

1. Go to the "Role Manager" in Admin.
2. Select the role to be edited from the dropdown menu.
3. Under "View" and "Edit" permissions, click the "+" sign next to the field in the right panels to add them.
4. Click "Save".

Custom modules

Why don't I see anything when I go to create/view a record in a new custom module?

The first step after creating a custom module is designing a form and view for it. To do so:

1. Go to "Admin"
2. Scroll down to the section "Utilities"
3. Go to "Form Editor"
4. Open the views/forms for the model corresponding to the new module by selecting it from the "Model" dropdown
5. Select "Form (Default)" from the "Version" dropdown
6. Drag and drop the custom field into the form where it is desired.
7. Hit "Save"
8. Repeat the process with the "View" to change the record view page for the model type.

Email

Attachments and embedded media

Why are all my images broken?

The first thing you should check and double-check is whether, in "Public Info Settings", the public web root / base URI[[wikipedia:Uniform Resource Identifier]]: The part of a URL that identifies the resource on the server to be accessed. In the context of the API, this refers to the relative path within the web server based in the web root of X2Engine, i.e. ''index.php/api2/Contacts/324.json'' as opposed to the full URL, which begins with the protocol (i.e. "http") and might also contain a path relative to the web site's document root are set.

If they are not, and you access your CRM at a non-public URL when sending email, the image links will be generated such that they point to the CRM through that inaccessible URL. Thus, the images will naturally be broken in any browser accessing the web from a network that cannot access your CRM. This is what the public info settings options were meant to address. In order for campaigns to work properly, there must be some way of publicly accessing the CRM from the web. This is so that, among many things, the "unsubscribe" link works (the user is essentially visiting a page in the CRM that unsubscribes them).

This happens in GMail even if the CRM is accessible from where you're using GMail because Google tries to access and cache images in emails. Google's servers won't be able to access them on account of Google not dwelling within your subnet (or network where the CRM is accessed), so naturally, all images with non-public URLs will show up broken regardless of how you're accessing the network.

Why is there a broken image in the email, even though I didn't attach anything?

This is the tracking image, which allows X2Engine to register that the user has opened the email. It should ordinarily be invisible, but is broken because your CRM is not publicly accessible. See the answer to "Why are all my images broken?"

Campaigns

Why don't the "Unsubscribe" link and email opened tracking work?

See the answer to the above question, "Why are all my images broken?"

Importing & Exporting

Contacts Importer

What format does my CSV have to be in order to use the contacts importer?

The following prerequisites must apply to the CSV file:

1. The first line of the file must not be a record of data, but the names of the fields in the data.
2. The delimiter must be a comma, the enclosure must be a double quote ("), and the escape character must be a backslash (\).
3. All commas in the file that are not field delimeters must be escaped (preceded by a backslash).

Take for example the following first two lines of a typical contacts CSV export:

id,name,firstName,lastName,title,company,phone,phone2,email
1,"Steve Mcqueen",Steve,McQueen,"Operations Manager","Pierre Office Supplies",605-636-5634,,steve@example.com

If your CSV does not meet the second or third criterion, X2Engine recommends the following procedure:

1. Import your CSV into a spreadsheet program.
2. Export your contacts data back into a CSV with commas properly escaped and the delimiter/enclosure chosen properly.
3. Attempt to import your contacts again using the new CSV file.

It is worth noting that the contacts importer gets data by calling PHP's fgetcsv function, with only the first argument specified. Thus, the prerequisites of the input CSV's formatting and internal conventions are derived from the default behavior of that function.

Why are my contacts running into validation failures?

This is caused by legitimately "bad" data (or formatting) in the input CSV. For example, the email field might not actually be formatted like an email address, or the first and last names of certain contacts might be blank whereas they are required when creating or updating contacts and cannot be made blank. To get around this, if you want to import the full set and then fix the data once inside X2Engine, you should perform the following steps:

1. Look for the file "failedContacts.csv" on the server, after the import with contacts that failed validation.
2. If applicable, undo the existing contact imports where there were contacts that failed import due to validation errors.
3. Go to "Admin"
4. Under "X2Studio", go "Manage Fields"
5. Edit the fields whose analogues in the CSV contain invalid data. To determine which fields contain invalid data, examine the contents of the "failedContacts.csv" file.