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

Record Importer

What format does my CSV have to be in order to use the record 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 does the importer process only one record before stopping?

This may be indicative of a common problem that occurs when using Microsoft Excel in Windows, and the Web server with X2Engine is Linux, Unix or pretty much anything that isn't Windows. What's happening is that Excel is exporting the CSV file with Windows-style line breaks only. Thus, the server interprets the file as though it were just one line long.

Why are my records 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.

How do I update existing records through import?

When updating a large portion of your records, it may be more convenient to use a familiar spreadsheet program to manipulate the data. After exporting the data to CSV, you can update your data before importing the CSV, selecting which attribute is used to lookup existing records.

1. Export a CSV file of the records to be updated, then open it in your spreadsheet program and remove the columns which will not be updated or used to match on existing records.
2. Perform all necessary updates to the data in the CSV.
3. Navigate to the import page for the module the records were exported from and upload the CSV.
4. In the importer options, select "Update Existing Records," then select the attribute to match on existing records.
5. Modify your import map as appropriate and set other import options, then proceed with the import. If you have selected a field to match on which is not marked "unique" in the Field Manager, you will need to confirm a warning message. Should multiple records be matched by the value in the match attribute, unexpected data manipulation may occur.

Updating

Compatibility Issues Detected

How can I get around this?

You can still update. If compatibility issues are detected, this will not prevent you from updating; it was merely intended to draw attention to potential issues with the update. This is especially applicable in the case of customized files. Simply click the "Apply Changes" button.

However, if you notice a message regarding conflicting fields among the compatibility issues messages, you will probably run into a database error in the update process. There is one exception to this, the "actionDescription" field in the Actions model, which was removed in 3.0 and re-added in 3.5.5 (so if you are updating from before 3.0, you can disregard this message with respect to that particular field).

Files in protected/config are going to be overwritten?

You can generally always ignore this message. These files were originally included as part of the default fileset, to provide examples of how to write them. However, due to how the average end user does not customize X2Engine at the source code level, inclusion of these files in the default codebase has been discontinued so as to avoid this unnecessary message.