X2Engine - User contributions [en]

REST API Reference

2015-10-29T21:16:33Z

Jake: /* Access Credentials */

[[Category:Development]]
X2Engine's second-generation HTTP-based API, '''available as of version 4.1''', is (for the most part) REST-ful, and includes many improvements over the original API.

The source code of the main components used in this API are:
* [https://github.com/X2Engine/X2Engine/blob/master/x2engine/protected/controllers/Api2Controller.php protected/controllers/Api2Controller.php]
* [https://github.com/X2Engine/X2Engine/blob/master/x2engine/protected/components/util/ResponseUtil.php protected/components/ResponseBehavior.php]
* [https://github.com/X2Engine/X2Engine/blob/master/x2engine/protected/components/util/ResponseUtil.php protected/components/util/ResponseUtil.php]
Functional tests for the API can be found alongside the tests for the legacy API, in [https://github.com/X2Engine/X2Engine/tree/master/x2engine/protected/tests/api protected/tests/api].

= Introduction =

This API within X2Engine, can be accessed via the URI
index.php/api2
It also:
* Exclusively uses JSON for data input and output
* Tends to use similar URIs for both input and output (distinguishing operations via the request method)
* Uses a variety of server response codes to distinguish error scenarios in the case of an unsuccessful transaction
* Uses the "HTTP Basic Auth" method for authentication

For example, to create a contact, one would send a <tt>POST</tt> request with its body a JSON-encoded attributes list to the URI
index.php/api2/Contacts
with the <tt>Content-Type</tt> header set to <tt>application/json</tt>, and the request body as (for example):
<syntaxhighlight lang="javascript">
{"firstName":"John","lastName":"Smith","visibility":1,"email":"johnsmith@example.com"}
</syntaxhighlight>

If creation of the contact is successful, the server should respond with status code <tt>201</tt> ("Created"), and the response should contain a <tt>Location</tt> header with the full URL (including protocol) of the newly created contact (in addition to all the attributes of the new contact). If for example the new contact's ID is 123, that URI would be
index.php/api2/Contacts/123.json
and a GET request to that URI would elicit a response from the server whose body contains a JSON-encoded list of attributes.

== URI Formats, Terminology and Conventions ==
Note, the above example, the URI to which the <tt>POST</tt> request is sent (to create the contact) is referred to in this documentation as a '''base URI'''. Base URIs, when requested using the <tt>GET</tt> method, return a JSON-encoded array, each entry in the array corresponding to a record and being a dictionary of column:value pairs. So for example, if sending <tt>GET</tt> to the contacts model base URI
index.php/api2/Contacts
the response would look like this:
<syntaxhighlight lang="javascript">[...,{"email": "johnsmith@example.com","firstName": "John","lastName": "Smith",...},...]</syntaxhighlight>
Whenever a URI points to an object or resource uniquely identified with a specific database record, that URI is referred to as a '''direct URI'''. Direct URIs end in ".json" and respond to <tt>GET</tt> requests with JSON-encoded dictionary objects of column values for the record as it is in the database. So, the URI in the above example (<tt>index.php/api2/Contacts/123.json</tt>) would respond with:
<syntaxhighlight lang="javascript">{"email": "johnsmith@example.com","firstName": "John","lastName": "Smith",...}</syntaxhighlight>

Direct URIs will almost always end in ".json", and base URIs will not. '''In general, the following convention applies''' almost universally within the API: ''If the URI ends in ".json", the resource will be a JSON-encoded dictionary object. Otherwise, it will be a JSON-encoded array. In the latter case, if each element of the array is a dictionary object, the dictionary objects should have uniform structure.''

== Access Credentials ==
To use the API, you will need to obtain X2Engine API credentials, which include a username and an API key. An X2Engine user with administrative privileges can get or set API keys in the Users module, by going to the edit page for that user. To summarize:
# As the administrator, go to the user management module. You'll find it under "Users"
# Click on the desired user
# Click "Update User"
# See the "API Key" field.

While there is a user in this section called "API User" you should not use it for this version of the API. That user exists to maintain backwards compatibility for a very old version of the API so that users who have set up API connectors with those endpoints will not have their code break. This user will not function with the current API and attempting to use it will generate a 403 error.

== Explore the API Using Your Web Browser ==
Once you have API credentials, you can examine the web API using your web browser by making <tt>GET</tt> requests to locations within <tt>index.php/api2</tt> (simply by typing them into your browser's location bar). You can get a nicer view of the data returned by the server by installing a JSON viewing plugin in your web browser. A recommended plugin for this purpose is [http://jsonview.com/ JSONView], which is available [https://addons.mozilla.org/en-us/firefox/addon/jsonview/ for Firefox] and [https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc for Google Chrome] (it's an unofficial port, but the developer of the API and author of this article uses it).

=== Example 1: hello, world ===
Try visiting the following URI within X2Engine:
index.php/api2/appInfo.json
Initially you will be prompted to enter the username and password to complete authentication; enter the API key corresponding to the user in the password field. The above URL should respond with a JSON string containing some basic info about the X2Engine application.

=== Example 2: direct access ===
You can get the ID of any given account record by going to it inside X2Engine as you normally would and examining the URI. It should generally look something like this:
index.php/accounts/32
or:
index.php/accounts/id/32
In both of the above examples, the primary key value (id) of the record in question is 32. '''To view it in the API:'''
index.php/api2/Accounts/32.json

Note how in the API, the first letter of "Accounts" in the direct URI is capitalized. This is because active record data in the API is accessed not via specifying the module containing the active record class, or to which the class corresponds, but by specifying the actual ''class name'' to use when accessing (or querying) data.

=== Example 3: querying ===
index.php/api2/Actions?_order=-id&_limit=3
This will show you the last 3 action records (i.e. emails, call logs, to-do's) created in the system (which the current acting API user has permission to view), in descending order of their primary key values (column "id"). If you have no action records in your system, you should receive an empty array.

== Prerequisites for API Applications ==
When writing an application to interface with X2Engine via the API, it is required or strongly recommended that your language/coding environment of choice:

* Have a JSON parsing and encoding library available
* Have a library for making HTTP requests which can:
** Set request headers
** Parse response headers and read the response status code
** Natively support requests using HTTP Basic Auth for access
** Read responses even when the response code is not in the "success" category (2xx)
** Make <tt>POST</tt>, <tt>PATCH</tt>/<tt>PUT</tt> and <tt>DELETE</tt> requests
* Can access the network

Many high-level languages, such as Perl, PHP, Python and Ruby, meet these requirements. The specific usage of these languages is beyond the scope of this article; you will need to refer to the documentation of the library/libraries in use.

It is expected in the near future that a growing number of official API access classes (each in a different programming language) will be available for quick and easy development of API applications.

== Authentication ==
As stated before, the API uses "HTTP Basic" authorization. Many HTTP client libraries will have native methods of setting headers for HTTP basic auth. It is recommended that you use such a method for authentication and read the relevant documentation, rather than setting headers manually, as that will save time and more likely lead to quicker success.

In all other cases, to authenticate and access the API using this method, each request must include the <tt>Authorization</tt> header. To compose the header, first combine the username and API key into a single string with a colon, as:
{username}:{userKey}
Next, obtain the string in Base-64 encoding. For example, '''<tt>username:password</tt>''' in base 64 is <tt>dXNlcjpwYXNzd29yZA==</tt>. Thus, the resulting header would look like this:
Authorization: Basic dXNlcjpwYXNzd29yZA==

See also the [[wikipedia:Basic access authentication#Client side|the Wikipedia article on this topic]].

=== Caveats ===
'''Note, firstly:''' because headers are sent without any built-in encryption, it is highly recommended that you use the API over HTTPS (HTTP encrypted using TLS), if available, or make API requests only within a network where packets are not easily intercepted.

Furthermore, if you have password-protected any web directories that contain X2Engine, you will need to make a "Satisfy any" exception for URIs within the API, or clients may not be able to authenticate.

= Model-based Input and Output =
Most of the modules in X2Engine (i.e. Contacts) will each have a corresponding active record model. This model is what is customized whenever adding a custom field. It is essentially a PHP class that is a child of [[x2doc:X2Model|X2Model]] (see: [[X2Model and Dynamic Fields]] for more information). Almost all API-based functions involving such data objects will contain the name of that class in the URL, i.e.
index.php/api2/Accounts
index.php/api2/Contacts/135/Actions
index.php/api2/Contacts/112.json
In general, the base URI for functions pertaining to models is
index.php/api2/{_class}
where <tt>{_class}</tt> is the class. The direct URI is generally:
index.php/api2/{_class}/{_id}.json
where <tt>{_id}</tt> is the ID of the record to access.

== Getting Model Classes ==
From the following URI one can obtain a list of models:
index.php/api2/models
Each model in the list is a dictionary containing:

{|class="wikitable"
|-
! scope="row" |<tt>modelName</tt>
|The class of the model
|-
! scope="row" |<tt>title</tt>
|The human-readable name of the model
|-
! scope="row" |<tt>attributes</tt>
|An array of attribute names
|-
|}

To include only fully-supported classes versus partially-supported model classes, include the "partialSupport" parameter and have it equal zero:
index.php/api2/models?partialSupport=0

== Fully-Supported Model Classes ==
As of this writing, X2Engine by default has the following model classes that are fully supported in the API — meaning, all or nearly all of the most essential functionality that is possible in X2Engine via a web browser, in terms of manipulation of persistent data storage, is also possible via the API.
* <tt>Accounts</tt>
* <tt>BugReports</tt>
* <tt>Contacts</tt>
* <tt>Campaign</tt>
* <tt>Opportunity</tt>
* <tt>Product</tt>
* <tt>Services</tt>

Additionally, any custom modules will also have corresponding active record models fully supported by the API. This should usually be the same name as the module, but without spaces and the first letter always capitalized. If in doubt, to find the model class corresponding to a given module (i.e. a custom module), look in the "models" sub-directory of that module. The name of the file excluding the extension (<tt>.php</tt>) should be the name of the class. For instance, in the file <tt>protected/modules/contacts/models/Contacts.php</tt> there should be the following line:
<syntaxhighlight lang="php">
class Contacts extends X2Model {
</syntaxhighlight>

== Partially-Supported Models ==
Manipulation of data using the following models (or certain aspects of the following models) is not fully supported in the API as of this writing — meaning, while most operations are possible, some important functionality is not yet possible:

{|class="wikitable"
|-
! scope="row" | <tt>Actions</tt>
|Actions can be created, updated, viewed, queried and deleted as all other model types. However:
* Action completion and backdating (setting or overwriting the completion date) is not yet supported unless one enables "raw input" (Platinum Edition only), because <tt>completeDate</tt> is a "read-only" field
* Associated "action timer" records (applicable only to Professional/Platinum edition) cannot be accessed or manipulated
* Comparisons based on action description in queries:
** They are unaffected by options that control comparisons; the comparison is un-escaped "LIKE" and the criteria combination operator is effectively "AND" (<tt>_partial=1&_escape=0</tt>).
** They will also be very slow; effectively, the comparison in the query is being performed on a <tt>TEXT</tt> column in a joined table

The limitations of filtering by action description are endemic to how the "field" is actually stored in a different database table than the contacts, and the type of the column is <tt>TEXT</tt>.
|-
! scope="row" | <tt>Docs</tt>
|Can be accessed/manipulated as with other models. However, "edit permissions" do not work the same way as they do in the application.
|-
! scope="row" | <tt>Groups</tt>
|Groups can be queried, viewed and created, albeit only by an administrative user, and in a very limited capacity. Users cannot be added to or removed from groups; manipulating the associated "group-to-user" data is not yet possible.
|-
! scope="row" | <tt>Media</tt>
|Media records can be accessed and manipulated as with any other model, but the API does not yet support directly uploading files to go with them.
|-
! scope="row" | <tt>Quote</tt>
|Quote records can be accessed and manipulated, but associated "line items" data cannot be viewed or manipulated.
|-
! scope="row" | <tt>X2Leads</tt>
|This data type can be fully accessed and manipulated, but there is not yet any built-in action available for directly converting a lead to an opportunity.
|-
! scope="row" | <tt>X2List</tt>
|This data type (contact lists in X2Engine) can be accessed and manipulated, but the actual contents of the list (whether dynamic or static) cannot.
|}

== Creating, Viewing Updating and Deleting Records ==
To create a record, perform a <tt>POST</tt> request to the base URI for the model, i.e.
index.php/api2/Contacts
to create a contact. As mentioned in the example in the [[#Introduction]], the body of the request must be a JSON-encoded library of attributes to set in the model, and the <tt>Content-Type</tt> header must be set to <tt>application/json</tt>.

To view, update or delete a record, first determine its direct URI within the API, as set in the <tt>Location</tt> header if creation was successful, or as determined via its class and id, i.e.
index.php/api2/Contacts/33.json
to specify a contact record with its id equal to 33.

To update a record, send a <tt>PUT</tt> or <tt>PATCH</tt> request to a direct URI, and set the body and <tt>Content-Type</tt> header as one would in a <tt>POST</tt> request to create such a record. Finally, to delete the record, send a DELETE request to that same direct URI. It is not necessary in the case of deletion to include a body or set the <tt>Content-Type</tt> header.

== Direct Manipulation by Attributes ==
Given a set of uniquely-identifying attribute names and values, it is possible to directly access and manipulate an existing X2Model-based record by without first querying it. The direct URI for this use case is:

index.php/api2/{_class}/by:{_findBy}.json

where the query parameter <tt>{_findBy}</tt> is a list of key and value pairs formatted as <tt>key1=value1;key2=value2</tt>.

For example: provided the email address "james@example.com" and first name "James" uniquely identify the contact with ID of 457, the following two direct access URIs are equivalent:

index.php/api2/Contacts/by:email=james@example.com;firstName=James.json
index.php/api2/Contacts/457.json

Furthermore, note what happens in the following scenarios:

'''If the set of attributes (i.e. email address) is not unique to a single record:''' the find-by-attributes direct URI will return with a 300 status and an [[#Error Objects|error object]] containing the two special properties: ''queryUri'', the URI to query for records by the attributes given, and: ''directUris'', a list containing the direct URI of each matching record.

''' If no contact matches the attributes given:''' the URI will respond with a 404 status.

=== Using the first matching record ===
If one wants to forcefully select and use the first record matching the attributes, regardless of how many match, append the <tt>_useFirst</tt> parameter and set equal to 1, i.e.

index.php/api2/Contacts/by:email=james@example.com;firstName=James.json?_useFirst=1

== Working With Associated Actions ==
The Actions model is unique in that it can be "associated" with almost any other type of model record. Actions records comprise all "history" items on any given record, i.e. emails, calls logged, notes, calendar events and also plain actions. Actions that have an association with another model can be used via clean URIs that point to "within" the associated model.

=== URI Formats ===

To view/query all actions associated with an active record model of class <tt>{_class}</tt> and id <tt>{_id}</tt>, use the following base URI:
index.php/api2/{_class}/{_id}/Actions

For instance, one could find all actions, including emails, on contact id=1233, via:
index.php/api2/Contacts/1233/Actions

To view an individual action of id <tt>{_actionId}</tt>, one can use this direct URI:
index.php/api2/{_class}/{_id}/Actions/{_actionId}.json

=== Creating, Updating and Deleting Actions ===
Similar to the the basic model access API function, <tt>PATCH</tt>, <tt>POST</tt>, <tt>PUT</tt> and <tt>DELETE</tt> requests can be sent to associated action URIs to create/modify/delete records just as those URIs can also be used to view data. <tt>POST</tt> to the base URI,
index.php/api2/{_class}/{_id}/Actions
to create a new action associated with model record of class <tt>{_class}</tt> and id <tt>{_id}</tt>. Then, using the direct URI,
index.php/api2/{_class}/{_id}/Actions/{_actionId}.json
<tt>PATCH</tt>/<tt>PUT</tt>/<tt>DELETE</tt> requests can be used to modify/delete an existing associated action record.

= Metadata Functions =
There is "structural" metadata that one can retrieve through the API to more effectively determine how to proceed with future API transactions. There are also some functions in the API that pertain to functionality associated with model records, but do not modify data within the records themselves, and create associated metadata.

== Fields ==
One can access field metadata for a given model class by using the following base URI (which supports querying):
index.php/api2/{_class}/fields
One can directly access the metadata of a field by its name via the following direct URI format:
index.php/api2/{_class}/fields/{_fieldName}.json
For instance, this URI
index.php/api2/Contacts/fields/leadSource.json
would respond with:

<tt>
{"id":"88", "modelName":"Contacts", "fieldName":"leadSource", "attributeLabel":"Lead Source", "modified":"0", "custom":"0", "type":"dropdown", "required":"0", "uniqueConstraint":"0", "safe":"1", "readOnly":"0", "linkType":"103", "searchable":"0", "relevance":"", "isVirtual":"0","defaultValue":null,"keyType":null}
</tt>

== Field-Level Permissions ==
Any given user's access level to a field can be controlled by assigning them to a role and then setting field permissions for that role via ''Manage Roles'' under ''Admin''.

A <tt>GET</tt> to the following will respond with a dictionary of active record model attributes, each value corresponding to field-level access permissions for that field granted the current acting API user.
index.php/api2/{_class}/fieldPermissions.json
For example, as the default administrator, for model Contacts, getting the following:
index.php/api2/Accounts/fieldPermissions.json

will respond with:

<tt>{"leadtype":2, "leadSource":2, "leadstatus":2, "leadDate":2, "leadscore":2, "interest":2, "dealvalue":2, "closedate":2, "rating":2, "dealstatus":2, "name":2, "nameId":1, "id":1, "website":2, "type":2, "visibility":2, "annualRevenue":2, "phone":2, "tickerSymbol":2, "address":2, "city":2, "state":2, "country":2, "zipcode":2, "parentAccount":2, "primaryContact":2, "employees":2, "assignedTo":2, "createDate":1, "description":2, "lastUpdated":1, "lastActivity":1, "updatedBy":1}</tt>

For each of these entries, the number associated with the field indicates the following:
{|class="wikitable"
|-
! scope="row" |0
|No access; when directly accessing a model record, the response data will not include the content of that field
|-
! scope="row" |1
|Read-only access; responses will include the content of that field, but any input to that field will be discarded
|-
! scope="row" |2
|Read/write access. The current API user can both view and edit data in the field.
|-
|}

== Zapier-Friendly Fields ==
There is similarly a dynamic fields API action that returns an array of fields intended for use by Zapier. The object format returned from this action is described in [https://zapier.com/developer/documentation/reference/#action-fields-custom Action Fields (Custom)] in the Zapier developer documentation.

The base URI is:
index.php/api2/{_class}/zapierFields

This action is generally useful for API usage insofar as it will also return ranges of acceptable values for each field, if applicable, in the '''<tt>choices</tt>''' property. For example, if the type of a field is <tt>dropdown</tt>, the dropdown options will be returned in the <tt>choices</tt> property of each element in the returned array. Similarly, if the type of the field is <tt>assignment</tt>, the element's <tt>choices</tt> property will include a list of users and groups. Furthermore, it has the ability to easily select only fields of a given permission level or greater. For this, use the <tt>_permissionLevel</tt> parameter. For example, to get all writable fields in Contacts:
index.php/api2/Contacts/zapierFields?_permissionLevel=2
(see [[#Field-Level Permissions]] for more information)

Unfortunately, the action does not support querying, although it does not need to for its intended purpose.

== Dropdowns ==
Note, to get a list of acceptable values for a given model in cases when the field type is not <tt>dropdown</tt>, use the <tt>choices</tt> property of data returned by [[#Zapier-Friendly Fields]].

Some fields, i.e. lead source in contacts, are of type "dropdown"; their content is intended to be either blank, or an option in a static list. Dropdown menus can be queried at base URI
index.php/api2/dropdowns
Dropdown fields can also be directly accessed via
index.php/api2/dropdowns/{_id}.json
To find out if a field is of type dropdown, and which dropdown menu it uses: the value for <tt>type</tt> in the field's metadata record should be "dropdown", and the <tt>linkType</tt> field should contain the dropdown's ID. So, using the example in [[#Fields]], the corresponding dropdown record is at
index.php/api2/dropdowns/103.json
which contains:

<tt>{"id":"103", "name":"Lead Source", "options":{"None":"None", "Google":"Google", "Facebook":"Facebook", "Walk In":"Walk In"}, "multi":"0", "parent":null, "parentVal":null}</tt>

Note, for convenience's sake the "options" field won't be returned verbatim as the raw JSON (that's how the options are stored). Rather, that field will be decoded into a sub-dictionary of the overall object.

== Relationships ==
It is possible to create, view, and delete relationships between supported API models in X2Engine via the API.

=== URI Formats ===
Relations functionality is in general accessed within the following base URI:
index.php/api2/{_class}/{_id}/relationships

So, to view all relationships going to or from account 131:
index.php/api2/Accounts/131/relationships

To view the contents (related model class and ID) of a specific relationship on the account (let's say the relation record has its id=304281 for instance):
index.php/api2/Accounts/131/relationships/304281.json

The <tt>Relationships</tt> active record model has the following attributes that can be used in queries:
;id
: Unique numeric identifier for the relationship
;<tt>firstType</tt>, <tt>firstId</tt>
: The model class and record ID at one end of the relationship, respectively
;<tt>secondType</tt>, <tt>secondId</tt>
: The model class and record ID at the other end of the relationship, respectively

For instance, to find all outgoing relationships with Accounts to contact id=126:
index.php/api2/Contacts/126/relationships?secondType=Accounts

=== Adding/Removing Relationships ===
To create a new relationship, sent <tt>POST</tt> to the base URI.

To remove a relationship, send <tt>DELETE</tt> to the direct URI of the record, i.e. <tt>index.php/api2/Accounts/131/relationships/304281.json</tt> in the earlier example.

== Tags ==
All basic, fully-supported models in X2Engine should support tagging. Tags cannot be individually modified, but can only be created, viewed, queried and removed, in order to enforce preservation of the important metadata such as who added the tag and at what date.

=== URI Formats ===
Tags on a given model record can be retrieved via <tt>GET</tt> at the following base URI:
index.php/api2/{_class}/{_id}/tags
The response should be a flat array of tag names. For example, if account 51 has tags "#customer" and "#local", sending <tt>GET</tt> to the following URI
index.php/api2/Accounts/51/tags
will yield:
<syntaxhighlight lang="javascript">["#customer","#local"]</syntaxhighlight>

To view more extensive metadata of the tag, i.e. who added the tag and at what date:
index.php/api2/{_class}/{_id}/tags/{_tagName}.json
i.e.
index.php/api2/Accounts/51/tags/local.json
The above will return a dictionary of <tt>x2_tags</tt> column names and values. Note, the tag name in the URI must either exclude the preceding hash mark or include it via its corresponding URL encoding sequence, <tt>'''%23'''</tt>. This is because the hash mark is a special character in the HTTP protocol and will interfere with proper resolution of the URI. Using the above example:
index.php/api2/Accounts/51/tags/%23local.json
That URI will return the exact same data as the previous URI; they are considered equivalent.

=== Adding Tags to a Record ===
Adding tags also utilizes that same URI scheme as with viewing tags. To add one or more tags, send them as string elements in a flat JSON-encoded array via <tt>POST</tt> to that location. For example, to use the previous example, one can apply the tags "#customer" and "#local" from "record 51" to record 52 by <tt>POST</tt>-ing the same JSON returned from a <tt>GET</tt> at:
index.php/api2/Accounts/51/tags
to:
index.php/api2/Accounts/52/tags

=== Removing Tags ===
To delete a tag, send a <tt>DELETE</tt> request to the direct viewing location of the tag. So, for instance, to delete "#local" from account 51, send <tt>DELETE</tt> to <tt>index.php/api2/Accounts/51/tags/local.json</tt>

= Querying Data =
Almost any "base" URI, which can be used for accessing all records of a type or for creating new records of a type, can also be used for querying records of that type. Responses to queries (and <tt>GET</tt> requests to these URIs in general) will always be JSON-encoded arrays of records, each record represented as an attribute dictionary.

Options for searching, as well as attributes to match column values against (for filtering), are all specified as query parameters (a.k.a. "get parameters"). The search options, to protect against name collisions with column names, each have names that begin with an underscore, i.e. <tt>_order</tt>.

== General Search Option Parameters ==
In queries, one can use a variety of advanced options that include sorting, pagination, partial matching, and in some cases tags.

{|class="wikitable"
|-
! scope="col" | Parameter
! scope="col" | Meaning
! scope="col" | Default
! scope="col" | Usage
|-
! scope="row" | <tt>_escape</tt>
|Wildcard usage
|<tt>1</tt>
|Set 0 in parameters to allow characters like "%" and "_" to be used as SQL wildcards in search filter attributes. Controls the resultant value of the <tt>$escape</tt> argument sent to [[yii:CDbCriteria#compare-detail|CDbCriteria.compare()]] in configuring the search. Note, to perform wildcard searches properly, the parameter <tt>_partial</tt> must be set to <tt>1</tt> so that <tt>CDbCriteria</tt> uses <tt>LIKE</tt> for the value comparison. For info on SQL wildcards and comparisons, see: [http://dev.mysql.com/doc/refman/5.0/en/string-comparison-functions.html MySQL: String Comparison Functions]
|-
! scope="row" | <tt>_limit</tt>
|Page size
|may vary
|Set to a number to control the maximum number of records to include in the results of the search. The default and maximum page size is <tt>1000</tt>, and in ''Platinum Edition'' this default amount is user-configurable.
|-
! scope="row" | <tt>_or</tt>
|Use "OR" operator
|<tt>0</tt>
|Set to <tt>1</tt> to make the operator used for combining search criteria <tt>OR</tt> instead of the default, <tt>AND</tt>.
|-
! scope="row" | <tt>_order</tt>
|Sorting
|none
|Set equal to the name of a column to sort by, optionally prefixed with a plus or minus sign to specify ascending or descending order (respectively). For example, <tt>_order=-leadScore</tt> in a Contacts query sorts contacts by lead score with the highest-scored contacts first. Note, sorting applies not only to the current page but to the data set spanning all pages. Thus, if the total number of possible results is larger than the page size, the set of results shown in the current page will be affected.
|-
! scope="row" | <tt>_page</tt>
|Page number
|<tt>0</tt>
|The zero-starting-point page number of the data. Useful for when the query would return more results than the page size specified.
|-
! scope="row" | <tt>_partial</tt>
|Partial match
|<tt>0</tt>
|Set to <tt>1</tt> to enable partial matching in search filters. This parameter controls the value sent to [[yii:CDbCriteria#compare-detail|CDbCriteria.compare()]] as the <tt>$partialMatch</tt> argument. If true, the <tt>LIKE</tt> comparison will be used; otherwise, full equality will be used as the comparison.
|-
! scope="row" | <tt>_tagOr</tt>
|Inclusive tag search
|<tt>0</tt>
|When performing tag-based searches, set to <tt>1</tt> to indicate to include records with ''any'' of the specified tags rather than all of them.
|-
! scope="row" | <tt>_tags</tt>
|Has tag(s)
|none
|When querying tag-supporting [[x2doc:X2Model|X2Model]] sub-classes (meaning, those which can be tagged), this can be included and set to a comma-delineated list of tags. This will restrict results to records having all of said tags, or if <tt>_tagOr</tt> is enabled, any of the tags. Note, tag names should not contain their preceding "#" (or, at least should not contain it without URL-encoding it) because "#" is a special character in the HTTP protocol that will interfere with how your request to the server is interpreted.
|-
|}

== Adding Query Parameters ==
Appending option parameters proceeds as it would for any script that can receive URL-encoded variables via the request: follow the base URI with a question mark, and delineate <tt>[name]=[value]</tt> parameter declarations with ampersands ''(note: this might be different, depending on your web server's configuration, but the nearly-ubiquitous default is ampersand-delineation)''. For example:
index.php/api2/Contacts?_limit=10&firstName=Harry&lastName=P%25&_partial=1&_escape=0&_order=+lastName
This will return the first ten contacts out the list of contacts having first name "Harry" and last name beginning with "P", sorted alphabetically by last name.

== Searching For Models By Tag ==
In addition to the <tt>_tags</tt> search option, there is a "pretty" dedicated base URI format for tag searching:
index.php/api2/tags/{_tags}/{_class}
So, for instance, to find all contacts with the tags "#customer" and "#important":
index.php/api2/tags/customer,important/Contacts
The above is equivalent to
index.php/api2/Contacts?_tags=customer,important
Note, additional search parameters can also be included. For instance, to return the first ten most recently updated contacts with the above tags:
index.php/api2/tags/customer,important/Contacts?_order=-lastUpdated&_limit=10

The reason for this is to express tags as categories, and thus in a loose sense "folders" in which one would find records.

= Web Hooks =
To develop real-time integration, that is to say, to have data sent from X2Engine to a third-party service immediately when a triggering event occurs, the best method is web hooks. Note, there is also the means of sending web requests to external URLs via the "Remote API Call" X2Flow action. For more information about this feature, see [http://www.x2engine.com/x2flow_user_manual/#remoteAPI the X2Flow documentation] for this action.

While said X2Flow action may suffice in many basic use cases, there are limitations to it that are addressed by web hooks:
* Configuring X2Flow cannot be performed via the API
* The action (making a web request) cannot be performed on a per-user basis (i.e. making a different request for each user)
* The X2Flow user interface is not available in the open source edition of X2Engine

In cases where the remote end, which will receive data from X2Engine, can be modified with custom code, web hooks are a method of "subscribing" to events in X2Engine via the API. Whenever an event would happen in X2Engine, X2Engine will submit payload data to a return URL specified in the original webhook request, as JSON-encoded data in the request body.

== Creating Web Hooks ==
To create a hook with an event that depends on a model type (i.e. contact updated vs. account updated), send a JSON-encoded list of hook attributes via <tt>POST</tt> to the following URI:
index.php/api2/{_class}/hooks
Or, to create a web hook associated with a generic event (that does not depend on model type), or a model of determined/unambiguous type (i.e. "Action Complete"):
index.php/api2/hooks

The POST-ed JSON-encoded dictionary object should contain the following properties:
{|class="wikitable"
|-
! scope="row" | <tt>event</tt>
| An event name; see [[#Events Reference]]
|-
! scope="row" | <tt>target_url</tt>
| The remote URL to receive the payload
|-
! scope="row" | <tt>directPayload</tt>
| (optional): a 1 or 0 (or true/false). See [[#Interpreting Payload Data]]
|-
|}

Upon successful creation of a web hook, note that the server will respond with a '''201''' status. The body will be the JSON-encoded attributes of the new hook record, and the <tt>Location</tt> header of the response will be set to a URL that can be used to remove the web hook when it is no longer needed (see [[#Deleting Web Hooks]]).

== Supported Event Names and X2Flow ==
Events for which web hooks can be created are all named after X2Flow trigger class names. Trigger classes (whose files are named after them, like all other class files) are stored in the directory
protected/components/x2flow/triggers

In fact, any time that <tt>[[x2propdoc:X2Flow.html#_trigger|X2Flow::trigger]]</tt> is called, a corresponding call to <tt>[[x2propdoc:ApiHook.html#_runAll|ApiHook::runAll]]</tt> is also made, to execute all web hooks associated with that trigger event. The payload that is sent for all web hooks corresponding to that event is based on the value of the <tt>$params</tt> argument that is sent to <tt>X2Flow::trigger</tt>. In all cases, the payload is first converted to a pure array, i.e. not containing any objects or resource handles, so that it can be JSON-encoded and sent to the web hook target URL. The exact payload data will differ depending on the action; see "[[#Interpreting Payload Data]]" (coming soon) for further information.

== Interpreting Payload Data ==
When you create a hook, you will have the option of setting its <tt>directPayload</tt> property to 1. A value of 0/false (the default value) for this field implies that if one of the trigger parameters is named "model" and is a subclass of X2Model (i.e. contact, account, opportunity), the (JSON-encoded) payload data will contain a property <tt>'''resource_url'''</tt> pointing to the URL on X2Engine of that model record. Thus, upon receiving the webhook request from X2Engine, the client end should then make a <tt>GET</tt> request from that URL to retrieve the model part of the payload data. If, on the other hand, <tt>directPayload</tt> is set to 1/true, what will instead happen is that the model will be included in the payload's <tt>'''model'''</tt> property as a dictionary of attribute-value pairs.

Note, the two most common possible properties <tt>resource_url</tt> and <tt>model</tt> are mutually exclusive; which one if any will get included depends on the <tt>direcPayload</tt>, other properties of the payload include but may not be limited to the following:

The class of model (and thus the structure of data) that should be expected to come from any given web hook generally depends on the model class to which the event corresponds. For example, the model is of class <tt>Actions</tt> in an <tt>ActionCompleteTrigger</tt> event, but they could be any general record type (contacts, actions, accounts, etc.) in a <tt>RecordCreateTrigger</tt> event.

== Events Reference ==
'''As of version 4.1.1''', the following trigger events are available in X2Flow:
{|class="wikitable"
|-
! scope="col" | Event
! scope="col" | Description
! scope="col" | Payload
|-
|ActionCompleteTrigger
|An action has been marked as complete
|'''model'''/'''resource_url''': An action; '''user''': username of the user who completed the action
|-
|ActionOverdueTrigger
|An action is overdue (cron required)
|'''model'''/'''resource_url''': an action; '''duration''': the amount of time that has passed since the due date of the action
|-
|ActionUncompleteTrigger
|An action has been marked as uncomplete
|'''model'''/'''resource_url''': An action; '''user''': username of the user who marked the action as uncomplete
|-
|CampaignEmailClickTrigger
|A tracking link in a campaign has been clicked
|'''model''': the contact who clicked the link in their campaign email; '''campaign''': Name of the email campaign
|-
|CampaignUnsubscribeTrigger
|A contact has unsubscribed from email campaigns
|'''model''': the contact; '''campaign''': Name of the email campaign
|-
|CampaignWebActivityTrigger
|''(Professional Edition only)'' A contact who was part of a campaign is visiting your website
|'''model'''/'''resource_url''': the contact; '''campaign''': Name of the email campaign; '''url''': URL of the page that the contact is visiting
|-
|NewsletterEmailClickTrigger
|''(Professional Edition only)'' A newsletter subscriber has clicked a tracking link
|'''item''': The list item record (<tt>{"emailAddress":<email address>,"opened":<timestamp opened>,"clicked":<timestamp clicked>,"unsubscribed":<has unsubscribed>}</tt>); '''email''': email address of subscriber; '''campaign''': name of the newsletter campaign; '''url''': URL visited by the subscriber
|-
|NewsletterEmailOpenTrigger
|''(Professional Edition only)'' A newsletter subscriber has opened an email
|'''item''': The list item record (<tt>{"emailAddress":<email address>,"opened":<timestamp opened>,"clicked":<timestamp clicked>,"unsubscribed":<has unsubscribed>}</tt>); '''email''': email address of subscriber; '''campaign''': name of the newsletter campaign
|-
|NewsletterUnsubscribeTrigger
|''(Professional Edition only)'' A newsletter subscriber has unsubscribed
|'''item''': The list item record (<tt>{"emailAddress":<email address>,"opened":<timestamp opened>,"clicked":<timestamp clicked>,"unsubscribed":<has unsubscribed>}</tt>); '''email''': email address of subscriber; '''campaign''': name of the newsletter campaign
|-
|RecordCreateTrigger
|A record of one of the main types (contact, action, account, opportunity, etc.) has been created
|'''model'''/'''resource_url''': The data that was inserted
|-
|RecordDeleteTrigger
|A record of one of the main types (contact, action, account, opportunity, etc.) has been deleted
|'''model'''/'''resource_url''': The data that was inserted
|-
|RecordTagAddTrigger
|A record has been tagged
|'''model'''/'''resource_url''': The record that was tagged; '''tags''': an array of strings (tags) that were added.
|-
|RecordTagRemoveTrigger
|Tags have been deleted from a record
|'''model'''/'''resource_url''': The record whose tags were changed; '''tags''': an array of strings (tags) that were removed
|-
|RecordUpdateTrigger
|A record of one of the main types (contact, action, account, opportunity, etc.) has been updated
|'''model'''/'''resource_url''': The data that was updated
|-
|RecordViewTrigger
|A record of one of the main types (contact, action, account, opportunity, etc.) has been viewed
|'''model'''/'''resource_url''': The data that was viewed
|-
|TargetedContentRequestTrigger
|''(Professional Edition Only)'' Targeted content is being accessed on your website
|'''model'''/'''resource_url''': The contact on your website; '''url''': the URL being viewed; '''flowId''': internal parameter (not of much use outside X2Engine)
|-
|UserLoginTrigger
|A user has logged in
|'''user''': the username of the user who has logged in
|-
|UserLogoutTrigger
|A user has logged out
|'''user''': the username of the user who has logged out
|-
|WebActivityTrigger
|''(Professional Edition Only)'' A contact is viewing your website
|'''model'''/'''resource_url''': the contact; '''url''': the URL being viewed; '''probability''' ''(Platinum Edition only)'' percentage confidence of browser-fingerprinting-based match between a web client and a contact
|-
|WebleadTrigger
|A new web lead has come in
|'''model'''/'''resource_url''': the contact associated with the form submission; '''tags''': a list of tags added to the contact through the submission, if applicable
|-
|WorkflowCompleteStageTrigger
|A process stage has been completed
|'''workflow''': The workflow template model (has properties name, isDefault, lastUpdated and colors); '''model'''/'''resource_url''': the record (i.e. Opportunity/Contact) for which the stage was completed; '''workflowId''': internal use (not very useful outside X2Engine); '''stageNumber''': the number of the stage in the process that was completed.
|-
|WorkflowCompleteTrigger
|A process has been fully completed
|'''workflow''': The workflow template model (has properties name, isDefault, lastUpdated and colors); '''model'''/'''resource_url''': the record (i.e. Opportunity/Contact) for which the stage was completed; '''workflowId''': internal use (not very useful outside X2Engine)
|-
|WorkflowRevertStageTrigger
|A process stage has been reverted.
|Same as WorkflowCompleteStageTrigger
|-
|WorkflowStartStageTrigger
|A process stage has been started
|Same as WorkflowCompleteStageTrigger
|-
|WorkflowStartTrigger
|A process has been started
|Same as WorkflowCompleteTrigger
|-
|}

== Deleting Web Hooks ==
Given the numeric identifier of a web hook, it can be deleted by sending a <tt>DELETE</tt> to a URI formatted as follows:
index.php/api2/hooks/:{_id}
So, for a web hook with id=74:
index.php/api2/hooks/:74

The full URL should have been given to the API client in the <tt>Location</tt> header in the response to the original web hook creation request. Upon successful deletion, the server will respond with status code '''204'''.

= Interpreting Server Responses =

== HTTP Response Codes ==
It is important to be able to read and interpret status codes (and for that matter, response headers) because in all success scenarios, the API does not respond with data envelopes. By this it is meant the act of wrapping a data model's attributes inside another array containing metadata about the status of the request. This is in effort to streamline and make more elegant code that handles response data. It is also for consistency's sake. A contacts model accessed as a resource object with name ending with <tt>.json</tt> is expected to be ''that contact'', and not rather an array with server response info or other metadata.

In general, the meanings of response codes closely or exactly follow the formal definitions as defined in [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html RFC2616], as well as the informal definitions of unconventional status codes (See [[wikipedia:List of HTTP status codes]]). The following table lists each of the possible status codes that the API will respond with, the contexts in which they would appear, and what they indicate.

{|class="wikitable"
|-
! scope="col" | Code
! scope="col" | Request type or usage scenario
! scope="col" | Meaning
|-
! colspan="3" | '''Success''' (<tt>2XX</tt>)
|-
! scope="row" | <tt>200</tt>
|<tt>GET</tt>, <tt>PATCH</tt>, <tt>PUT</tt>
Also, when adding tags via <tt>POST</tt>
|''OK.'' General success status
|-
! scope="row" | <tt>201</tt>
|<tt>POST</tt>
|''Created.'' A record was created; see the value of the <tt>Location</tt> response header for its URL in the API
|-
! scope="row" | <tt>204</tt>
|<tt>DELETE</tt>
|''No content.'' An action was completed but the server does not need to return any content. The body of the response will be empty.
|-
! colspan="3" | '''Redirection''' (<tt>3XX</tt>)
|-
! scope="row" | <tt>300</tt>
|When using the "[[#Direct Manipulation by Attributes|find by attributes]]" direct access URI
|''Multiple choices.'' There criteria specified for direct access (as opposed to querying) match more than one record.
|-
! scope="row" | <tt>303</tt>
|<tt>GET</tt>
When requesting an object that exists but is not actually associated with the record specified in the request
|''See other.'' The requested resource is somewhere else. The <tt>Location</tt> header should contain the correct, full URL to the resource.
|-
! colspan="3" | '''Client Error''' (<tt>4XX</tt>)
|-
! scope="row" | <tt>400</tt>
|All request methods/actions
|''Invalid request.'' General status code for when something is missing, malformed or incorrect in the request headers/body.
|-
! scope="row" | <tt>401</tt>
|All request methods/actions.
|Authentication failure or missing authentication credentials.
|-
! scope="row" | <tt>403</tt>
|All request methods/actions.
|''Forbidden.'' This may be because the user in API authentication does not actually have permission in X2Engine to perform the specified action. In Platinum Edition, this code can also indicate that the IP address of the API client has been blocked.
|-
! scope="row" | <tt>404</tt>
|All request methods/actions.
|''Not found,'' or invalid URI. It is used whenever a specified record to retrieve directly does not exist, but also as a catch-all for a location that the API was not configured to interpret.
|-
! scope="row" | <tt>405</tt>
|All request methods/actions
|''Method not allowed.'' The URI is not malformed, but the method of the request being sent to the server is not permitted. An example would be sending a POST request, which is intended for creating new records, to the URI of an existing record, or sending a <tt>DELETE</tt>/<tt>POST</tt>/<tt>PUT</tt> request to a "read-only" resource.
|-
! scope="row" | <tt>408</tt>
|All methods; server-generated
|''Request timeout.'' This code is not as of this writing not produced by the API; it might be returned by the web server itself.
|-
! scope="row" | <tt>413</tt>
|All methods; server-generated
|''Request entity too large.'' This code is not as of this writing not produced by the API; it might be returned by the web server itself.
|-
! scope="row" | <tt>415</tt>
|<tt>PATCH</tt>, <tt>POST</tt>, <tt>PUT</tt>
|''Unsupported media type.'' As of this writing, this happens only whenever the request is sent with a body and the <tt>Content-Type</tt> header is not set to "application/json"
|-
! scope="row" | <tt>422</tt>
|<tt>PATCH</tt>, <tt>POST</tt> and <tt>PUT</tt>
When creating or updating a record
|''Unprocessable entity.'' This always indicates a data validation error when attempting to set fields of and save an active record model. The client is expected to resolve these issues and resubmit the data with all of the fields formatted in such a way that it is acceptable.
|-
! scope="row" | <tt>429</tt>
|''Platinum Edition only''
All request methods/actions
|''Too many requests.'' When rate limiting is enabled in the API settings, the server will use this code to indicate that the API client has been making requests to the API too frequently. When this status is sent, the response should also contain a <tt>Retry-After</tt> header specifying the number of seconds to wait before trying again.

There is one exception to this, however: when attempting to create a web hook for a given user, event and model name, if the hook limit has already been reached for a user, event and model name, a 429 without <tt>Retry-After</tt> would be sent, and this implies that no more hooks for that combination should be created.
|-
! colspan="3" | '''Server Error''' (<tt>5XX</tt>)
|-
! scope="row" | <tt>500</tt>
|All request methods/actions
|''Internal server error.'' General status for when something isn't right on the server. PHP and database errors will produce this status code.
|-
! scope="row" | <tt>501</tt>
|All request methods/actions
|''Not implemented.'' The API should use this code to denote that a given method, action, etc. is not yet available, but may be in the future.
|-
! scope="row" | <tt>503</tt>
|''Professional and Platinum Editions''
All request methods/actions
|''Unavailable.'' X2Engine and/or its API service has been disabled/locked by an administrator.
|-
|}

== Error Objects ==
In all error responses produced by the API and not by the server itself, the body of the response will be a JSON containing metadata about the error and the response. This is for compatibility with less-than-satisfactory client libraries which cannot read the actual response code or headers, but might be able to read the response body when the code is not in the success (<tt>2XX</tt>) range. In such cases, the response will be a JSON-encoded object with at least the following properties:

{|class="wikitable"
|-
! scope="row | httpHeaders
|A dictionary of HTTP headers that were set deliberately by the API (as opposed to automatically, by the web server software) in the response.
|-
! scope="row | message
|A general message about what happened and why. This will in most cases also be saved in the API log.
|-
! scope="row | error
|Boolean true/false; will generally be true.
|-
! scope="row | status
|The HTTP status code that was sent in the response header
|-
|}
In some cases, the response JSON may include the following additional properties:
{|class="wikitable"
|-
! scope="row | errors
| A dictionary of validation errors encountered when attempting to save an active record model; included with responses of status code '''422'''.
The structure will be indexed by attribute name, each entry containing a list of applicable validation errors. It is essentially the resulting value of the [[yii:CModel#errors-detail|CModel.errors]] property.
|-
|}

Web Lead Capture via API (legacy)

2013-11-05T21:55:14Z

Jake: /* The Basics */

[[Category:Development]]
== Introduction ==
'''This version the Web Lead API is only compatible with X2CRM versions at or after 3.6'''

Much of what was written in the [[Web Lead API (legacy)|old version]] is the same, but there are some fairly key differences, namely the way our web tracker (professional feature) works. This will be addressed in its own section, but the back-end of it will be included in the capture form documentation.

Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to no development knowledge is required, and the form integrates perfectly with X2 from a web lead standpoint as well as our web tracker. But for some users, this isn't enough. Many websites already have forms in use that they don't want to sacrifice or change, but still want all of the features of X2 integration. The good news is that with some basic development knowledge this is a very doable project. This article will walk you through setting up a custom web lead capture script which will take POST data from your web lead form and enter it into X2 via API. The later sections of the article will cover some advanced customizations to make the form work better for you.

== The Basics ==
The first thing you'll need to do is create some form of capture script, and call it whatever you like. I tend to use things like "contactForm" to be very clear what it is. '''This script can go anywhere you want as the new web tracker is much more flexible than the old version.''' You'll also need to make sure that the "APIModel.php" class file is somewhere accessible. This file is provided in protected/models/ of your X2 installation, and can be copied to anywhere you like. So, what does this capture script currently look like?

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
</syntaxhighlight>

That's about it for now. The first thing we do is include the APIModel class, which will allow for easy use of X2's API. This class is heavily documented and provides a variety of wrapper methods for common X2 API functions. It also behaves in many ways just like a regular model, so if you have any X2 development experience you'll likely feel right at home.

The next steps in this process are to initialize the API Model correctly. To do that, you'll need three things:
* The username of a user with permission to create Contacts
* The user API key of that same user
* The URL of your X2 installation.

The first is easy to obtain, and I recommend using "admin" as it's simpler. From there, go to the "Users" page, click on "admin" in the grid, and select "Update User" from the left sidebar menu. You should see a field called API Key. You can set this to whatever you want, but they're randomly generated upon user creation. For example, mine on my development server at the time of this writing is "7uoHGRIBlb0lKym56ieiDf3c7idzCCP7"

The API Model takes 3 parameters for its constructor. You may be able to guess that they are the username, API key, and URL of the server. So now our code should look something like this:

<syntaxhighlight lang="php">
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
</syntaxhighlight>

That's the most important step to get right. If you don't properly set up your API model, all of the requests will fail and this whole process will be useless. '''Please double check you have entered in the information correctly.'''

Now we need to be able to set the data of our Contact. Most pre-built forms do not follow the same naming conventions of the database columns in X2. As such, I like to build a field map that will translate the information in the POST data into usable information by X2. If all your field names match ours exactly, then this step isn't required and you can simply say <tt>$contact->attributes = $attributes;</tt>

<syntaxhighlight lang="php">
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
</syntaxhighlight>

This code will now loop through your POST data and set them to the Contact attributes based on your field map. Note that if a match isn't found in the map, it assumes the names are the same in your form as they are in X2.

You'll also want to include the tracking key, if it exists. This is now provided up front instead of returned after creation, so this code should just be a few extra lines before you submit the data to the API.
<syntaxhighlight lang="php">
if(isset($_POST['x2_key'])){
$contact->trackingKey=$_POST['x2_key'];
}
</syntaxhighlight>

The last component of the custom form is submitting the data and redirecting. You can do these like so:

<syntaxhighlight lang="php">
$contact->contactCreate(); // Call API to create contact
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And be sure to replace '/path/to/x2' with your web path, 'host.domain' with your server URL, and the redirect with whatever URL you want visitors to be sent to after filling out the form. Now, if we put it all together, the final product should look something like this:

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
if(isset($_POST['x2_key'])){
$contact->trackingKey=$_POST['x2_key'];
}
$contact->contactCreate(); // Call API to create contact
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And that's it! For a basic web lead capture script, this is all we need. The code listed here should be totally functional to copy and paste over to your own server, as long you define your own field map, configure the APIModel constructor, and replace URLs properly. However, it's pretty basic and there's at least one extra feature that might be required to work correctly.

Also, you may have noticed that $_POST['x2_key'] was referenced, but it was not explained where we got that from. Please see the [[#Web Tracker Front End|Web Tracker Front End]] section for an explanation.

== Advanced Topics ==
TODO: Add this section
=== Web Tracker Front End===
The new web tracker is significantly more reliable and flexible to work with. However, you'll need to make a slight change to your HTML form to make it work. What you'll want to do is create a hidden input in your form with the name "x2_key" and that's it! Our web tracker JS will automatically detect this field and fill it with the correct tracking key.

The advantages of the new JS based web tracker are numerous, but the biggest one is that you no longer need an IFrame to your X2 installation! The tracker tracks on your web servers domain now, which removed a lot of the hassle involved with getting the tracker to function properly.
=== Duplicate Handling ===
The basic script doesn't have any sort of handling for finding people who submit the form more than once. Instead of simply creating duplicate records, you can do a few little tricks to make this part of the lead script smarter. First things first, we need a way to check for a duplicate Contact. Before you set any attributes on the Contact model which is the code that has: <tt>foreach($attributes as $key=>$value){</tt> you'll want to add this:
<syntaxhighlight lang="php">
$contact->email=$attributes['email'];
$contact->contactLookup();
if($contact->responseCode!='404'){
// Code to handle duplicates here.
}
</syntaxhighlight>

First, we set the email of the Contact because that's the primary way to look for duplicates. Then we call the "contactLookup" function which does exactly what it says--looks up a Contact. If we can't find any, the response code will be a 404. So all we do then is make our if statement check if the response was something other than a 404 and handle the duplicate in here! There's a few different ways we can deal with that. '''All of the code in the following blocks starts at the response code check.''' The first is a simple redirect, ignoring the duplicate record, which would look like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
Header("Location: host.domain");
}
</syntaxhighlight>
Replacing "host.domain" with your own redirect location. The next step is a little more advanced, which would be to instead detect empty fields in the Contact record and fill them with any submitted data, while preserving data already on the record. The code to do that would look something more like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
foreach($attributes as $key => $value){ // Try to set any empty attributes
if(isset($fieldMap[$key]) && empty($contact->{$fieldMap[$key]})){ // Check if value is empty + found in field map
$contact->{$fieldMap[$key]} = $value; // Found in field map, used mapped attribute
}elseif(empty($contact->$key)){ // Just check if value is empty
$contact->$key = $value; // No match in field map, assume it's a Contact attribute
}
}
$contact->contactUpdate();
}
</syntaxhighlight>
=== Adding Tags ===
=== Lead Logging ===
=== Custom Redirects ===
== Advanced Final Product ==
With all the bells and whistles!
TODO: Add this

Web Lead Capture via API (legacy)

2013-11-05T21:54:27Z

Jake: /* Introduction */

[[Category:Development]]
== Introduction ==
'''This version the Web Lead API is only compatible with X2CRM versions at or after 3.6'''

Much of what was written in the [[Web Lead API (legacy)|old version]] is the same, but there are some fairly key differences, namely the way our web tracker (professional feature) works. This will be addressed in its own section, but the back-end of it will be included in the capture form documentation.

Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to no development knowledge is required, and the form integrates perfectly with X2 from a web lead standpoint as well as our web tracker. But for some users, this isn't enough. Many websites already have forms in use that they don't want to sacrifice or change, but still want all of the features of X2 integration. The good news is that with some basic development knowledge this is a very doable project. This article will walk you through setting up a custom web lead capture script which will take POST data from your web lead form and enter it into X2 via API. The later sections of the article will cover some advanced customizations to make the form work better for you.

== The Basics ==
The first thing you'll need to do is create some form of capture script, and call it whatever you like. I tend to use things like "contactForm" to be very clear what it is. '''This script can go anywhere you want as the new web tracker is much more flexible than the old version.''' You'll also need to make sure that the "APIModel.php" class file is somewhere accessible. This file is provided in protected/models/ of your X2 installation, and can be copied to anywhere you like. So, what does this capture script currently look like?

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
</syntaxhighlight>

That's about it for now. The first thing we do is include the APIModel class, which will allow for easy use of X2's API. This class is heavily documented and provides a variety of wrapper methods for common X2 API functions. It also behaves in many ways just like a regular model, so if you have any X2 development experience you'll likely feel right at home.

The next steps in this process are to initialize the API Model correctly. To do that, you'll need three things:
* The username of a user with permission to create Contacts
* The user API key of that same user
* The URL of your X2 installation.

The first is easy to obtain, and I recommend using "admin" as it's simpler. From there, go to the "Users" page, click on "admin" in the grid, and select "Update User" from the left sidebar menu. You should see a field called API Key. You can set this to whatever you want, but they're randomly generated upon user creation. For example, mine on my development server at the time of this writing is "7uoHGRIBlb0lKym56ieiDf3c7idzCCP7"

The API Model takes 3 parameters for its constructor. You may be able to guess that they are the username, API key, and URL of the server. So now our code should look something like this:

<syntaxhighlight lang="php">
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
</syntaxhighlight>

That's the most important step to get right. If you don't properly set up your API model, all of the requests will fail and this whole process will be useless. '''Please double check you have entered in the information correctly.'''

Now we need to be able to set the data of our Contact. Most pre-built forms do not follow the same naming conventions of the database columns in X2. As such, I like to build a field map that will translate the information in the POST data into usable information by X2. If all your field names match ours exactly, then this step isn't required and you can simply say <tt>$contact->attributes = $attributes;</tt>

<syntaxhighlight lang="php">
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
</syntaxhighlight>

This code will now loop through your POST data and set them to the Contact attributes based on your field map. Note that if a match isn't found in the map, it assumes the names are the same in your form as they are in X2.

You'll also want to include the tracking key, if it exists. This is now provided up front instead of returned after creation, so this code should just be a few extra lines before you submit the data to the API.
<syntaxhighlight lang="php">
if(isset($_POST['x2_key'])){
$contact->trackingKey=$_POST['x2_key'];
}
</syntaxhighlight>

The last component of the custom form is submitting the data and redirecting. You can do these like so:

<syntaxhighlight lang="php">
$contact->contactCreate(); // Call API to create contact
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And be sure to replace '/path/to/x2' with your web path, 'host.domain' with your server URL, and the redirect with whatever URL you want visitors to be sent to after filling out the form. Now, if we put it all together, the final product should look something like this:

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
if(isset($_POST['x2_key'])){
$contact->trackingKey=$_POST['x2_key'];
}
$contact->contactCreate(); // Call API to create contact
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And that's it! For a basic web lead capture script, this is all we need. The code listed here should be totally functional to copy and paste over to your own server, as long you define your own field map, configure the APIModel constructor, and replace URLs properly. However, it's pretty basic and there's at least one extra feature that might be required to work correctly.

Also, you may have noticed that $_POST['x2_key'] was referenced, but it was not explained where we got that from. Please see the Web Tracker Front End section for an explanation.

== Advanced Topics ==
TODO: Add this section
=== Web Tracker Front End===
The new web tracker is significantly more reliable and flexible to work with. However, you'll need to make a slight change to your HTML form to make it work. What you'll want to do is create a hidden input in your form with the name "x2_key" and that's it! Our web tracker JS will automatically detect this field and fill it with the correct tracking key.

The advantages of the new JS based web tracker are numerous, but the biggest one is that you no longer need an IFrame to your X2 installation! The tracker tracks on your web servers domain now, which removed a lot of the hassle involved with getting the tracker to function properly.
=== Duplicate Handling ===
The basic script doesn't have any sort of handling for finding people who submit the form more than once. Instead of simply creating duplicate records, you can do a few little tricks to make this part of the lead script smarter. First things first, we need a way to check for a duplicate Contact. Before you set any attributes on the Contact model which is the code that has: <tt>foreach($attributes as $key=>$value){</tt> you'll want to add this:
<syntaxhighlight lang="php">
$contact->email=$attributes['email'];
$contact->contactLookup();
if($contact->responseCode!='404'){
// Code to handle duplicates here.
}
</syntaxhighlight>

First, we set the email of the Contact because that's the primary way to look for duplicates. Then we call the "contactLookup" function which does exactly what it says--looks up a Contact. If we can't find any, the response code will be a 404. So all we do then is make our if statement check if the response was something other than a 404 and handle the duplicate in here! There's a few different ways we can deal with that. '''All of the code in the following blocks starts at the response code check.''' The first is a simple redirect, ignoring the duplicate record, which would look like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
Header("Location: host.domain");
}
</syntaxhighlight>
Replacing "host.domain" with your own redirect location. The next step is a little more advanced, which would be to instead detect empty fields in the Contact record and fill them with any submitted data, while preserving data already on the record. The code to do that would look something more like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
foreach($attributes as $key => $value){ // Try to set any empty attributes
if(isset($fieldMap[$key]) && empty($contact->{$fieldMap[$key]})){ // Check if value is empty + found in field map
$contact->{$fieldMap[$key]} = $value; // Found in field map, used mapped attribute
}elseif(empty($contact->$key)){ // Just check if value is empty
$contact->$key = $value; // No match in field map, assume it's a Contact attribute
}
}
$contact->contactUpdate();
}
</syntaxhighlight>
=== Adding Tags ===
=== Lead Logging ===
=== Custom Redirects ===
== Advanced Final Product ==
With all the bells and whistles!
TODO: Add this

Web Lead Capture via API (legacy)

2013-11-05T21:51:45Z

Jake: Created page with "Category:Development == Introduction == '''This version the Web Lead API is only compatible with X2CRM versions at or after 3.6''' Much of what was written in the old ver..."

[[Category:Development]]
== Introduction ==
'''This version the Web Lead API is only compatible with X2CRM versions at or after 3.6'''

Much of what was written in the old version is the same, but there are some fairly key differences, namely the way our web tracker (professional feature) works. This will be addressed in its own section, but the back-end of it will be included in the capture form documentation.

Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to no development knowledge is required, and the form integrates perfectly with X2 from a web lead standpoint as well as our web tracker. But for some users, this isn't enough. Many websites already have forms in use that they don't want to sacrifice or change, but still want all of the features of X2 integration. The good news is that with some basic development knowledge this is a very doable project. This article will walk you through setting up a custom web lead capture script which will take POST data from your web lead form and enter it into X2 via API. The later sections of the article will cover some advanced customizations to make the form work better for you.

== The Basics ==
The first thing you'll need to do is create some form of capture script, and call it whatever you like. I tend to use things like "contactForm" to be very clear what it is. '''This script can go anywhere you want as the new web tracker is much more flexible than the old version.''' You'll also need to make sure that the "APIModel.php" class file is somewhere accessible. This file is provided in protected/models/ of your X2 installation, and can be copied to anywhere you like. So, what does this capture script currently look like?

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
</syntaxhighlight>

That's about it for now. The first thing we do is include the APIModel class, which will allow for easy use of X2's API. This class is heavily documented and provides a variety of wrapper methods for common X2 API functions. It also behaves in many ways just like a regular model, so if you have any X2 development experience you'll likely feel right at home.

The next steps in this process are to initialize the API Model correctly. To do that, you'll need three things:
* The username of a user with permission to create Contacts
* The user API key of that same user
* The URL of your X2 installation.

The first is easy to obtain, and I recommend using "admin" as it's simpler. From there, go to the "Users" page, click on "admin" in the grid, and select "Update User" from the left sidebar menu. You should see a field called API Key. You can set this to whatever you want, but they're randomly generated upon user creation. For example, mine on my development server at the time of this writing is "7uoHGRIBlb0lKym56ieiDf3c7idzCCP7"

The API Model takes 3 parameters for its constructor. You may be able to guess that they are the username, API key, and URL of the server. So now our code should look something like this:

<syntaxhighlight lang="php">
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
</syntaxhighlight>

That's the most important step to get right. If you don't properly set up your API model, all of the requests will fail and this whole process will be useless. '''Please double check you have entered in the information correctly.'''

Now we need to be able to set the data of our Contact. Most pre-built forms do not follow the same naming conventions of the database columns in X2. As such, I like to build a field map that will translate the information in the POST data into usable information by X2. If all your field names match ours exactly, then this step isn't required and you can simply say <tt>$contact->attributes = $attributes;</tt>

<syntaxhighlight lang="php">
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
</syntaxhighlight>

This code will now loop through your POST data and set them to the Contact attributes based on your field map. Note that if a match isn't found in the map, it assumes the names are the same in your form as they are in X2.

You'll also want to include the tracking key, if it exists. This is now provided up front instead of returned after creation, so this code should just be a few extra lines before you submit the data to the API.
<syntaxhighlight lang="php">
if(isset($_POST['x2_key'])){
$contact->trackingKey=$_POST['x2_key'];
}
</syntaxhighlight>

The last component of the custom form is submitting the data and redirecting. You can do these like so:

<syntaxhighlight lang="php">
$contact->contactCreate(); // Call API to create contact
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And be sure to replace '/path/to/x2' with your web path, 'host.domain' with your server URL, and the redirect with whatever URL you want visitors to be sent to after filling out the form. Now, if we put it all together, the final product should look something like this:

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
if(isset($_POST['x2_key'])){
$contact->trackingKey=$_POST['x2_key'];
}
$contact->contactCreate(); // Call API to create contact
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And that's it! For a basic web lead capture script, this is all we need. The code listed here should be totally functional to copy and paste over to your own server, as long you define your own field map, configure the APIModel constructor, and replace URLs properly. However, it's pretty basic and there's at least one extra feature that might be required to work correctly.

Also, you may have noticed that $_POST['x2_key'] was referenced, but it was not explained where we got that from. Please see the Web Tracker Front End section for an explanation.

== Advanced Topics ==
TODO: Add this section
=== Web Tracker Front End===
The new web tracker is significantly more reliable and flexible to work with. However, you'll need to make a slight change to your HTML form to make it work. What you'll want to do is create a hidden input in your form with the name "x2_key" and that's it! Our web tracker JS will automatically detect this field and fill it with the correct tracking key.

The advantages of the new JS based web tracker are numerous, but the biggest one is that you no longer need an IFrame to your X2 installation! The tracker tracks on your web servers domain now, which removed a lot of the hassle involved with getting the tracker to function properly.
=== Duplicate Handling ===
The basic script doesn't have any sort of handling for finding people who submit the form more than once. Instead of simply creating duplicate records, you can do a few little tricks to make this part of the lead script smarter. First things first, we need a way to check for a duplicate Contact. Before you set any attributes on the Contact model which is the code that has: <tt>foreach($attributes as $key=>$value){</tt> you'll want to add this:
<syntaxhighlight lang="php">
$contact->email=$attributes['email'];
$contact->contactLookup();
if($contact->responseCode!='404'){
// Code to handle duplicates here.
}
</syntaxhighlight>

First, we set the email of the Contact because that's the primary way to look for duplicates. Then we call the "contactLookup" function which does exactly what it says--looks up a Contact. If we can't find any, the response code will be a 404. So all we do then is make our if statement check if the response was something other than a 404 and handle the duplicate in here! There's a few different ways we can deal with that. '''All of the code in the following blocks starts at the response code check.''' The first is a simple redirect, ignoring the duplicate record, which would look like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
Header("Location: host.domain");
}
</syntaxhighlight>
Replacing "host.domain" with your own redirect location. The next step is a little more advanced, which would be to instead detect empty fields in the Contact record and fill them with any submitted data, while preserving data already on the record. The code to do that would look something more like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
foreach($attributes as $key => $value){ // Try to set any empty attributes
if(isset($fieldMap[$key]) && empty($contact->{$fieldMap[$key]})){ // Check if value is empty + found in field map
$contact->{$fieldMap[$key]} = $value; // Found in field map, used mapped attribute
}elseif(empty($contact->$key)){ // Just check if value is empty
$contact->$key = $value; // No match in field map, assume it's a Contact attribute
}
}
$contact->contactUpdate();
}
</syntaxhighlight>
=== Adding Tags ===
=== Lead Logging ===
=== Custom Redirects ===
== Advanced Final Product ==
With all the bells and whistles!
TODO: Add this

Web Lead API

2013-11-05T19:14:56Z

Jake: Jake moved page Web Lead API to Web Lead API (legacy): No longer supported as of version 3.6

#REDIRECT [[Web Lead API (legacy)]]

Web Lead Capture via API (legacy; pre-3.5.6)

2013-11-05T19:14:55Z

Jake: Jake moved page Web Lead API to Web Lead API (legacy): No longer supported as of version 3.6

[[Category:Development]]
== Introduction ==
'''This version the Web Lead API is only compatible with X2CRM versions at or before 3.5.6'''

Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to no development knowledge is required, and the form integrates perfectly with X2 from a web lead standpoint as well as our web tracker. But for some users, this isn't enough. Many websites already have forms in use that they don't want to sacrifice or change, but still want all of the features of X2 integration. The good news is that with some basic development knowledge this is a very doable project. This article will walk you through setting up a custom web lead capture script which will take POST data from your web lead form and enter it into X2 via API. The later sections of the article will cover some advanced customizations to make the form work better for you.

== The Basics ==
The first thing you'll need to do is create some form of capture script, and call it whatever you like. I tend to use things like "contactForm" to be very clear what it is. '''This script should go onto the same webserver as your X2CRM installation''' so that cookies can be properly set, but it doesn't need to be in the same folder. You'll also need to make sure that the "APIModel.php" class file is somewhere accessible. This file is provided in protected/models/ of your X2 installation, and can be copied to anywhere you like. So, what does this capture script currently look like?

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
</syntaxhighlight>

That's about it for now. The first thing we do is include the APIModel class, which will allow for easy use of X2's API. This class is heavily documented and provides a variety of wrapper methods for common X2 API functions. It also behaves in many ways just like a regular model, so if you have any X2 development experience you'll likely feel right at home.

The next steps in this process are to initialize the API Model correctly. To do that, you'll need three things:
* The username of a user with permission to create Contacts
* The user API key of that same user
* The URL of your X2 installation.

The first is easy to obtain, and I recommend using "admin" as it's simpler. From there, go to the "Users" page, click on "admin" in the grid, and select "Update User" from the left sidebar menu. You should see a field called API Key. You can set this to whatever you want, but they're randomly generated upon user creation. For example, mine on my development server at the time of this writing is "7uoHGRIBlb0lKym56ieiDf3c7idzCCP7"

The API Model takes 3 parameters for its constructor. You may be able to guess that they are the username, API key, and URL of the server. So now our code should look something like this:

<syntaxhighlight lang="php">
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
</syntaxhighlight>

That's the most important step to get right. If you don't properly set up your API model, all of the requests will fail and this whole process will be useless. '''Please double check you have entered in the information correctly.'''

Now we need to be able to set the data of our Contact. Most pre-built forms do not follow the same naming conventions of the database columns in X2. As such, I like to build a field map that will translate the information in the POST data into usable information by X2. If all your field names match ours exactly, then this step isn't required and you can simply say <tt>$contact->attributes = $attributes;</tt>

<syntaxhighlight lang="php">
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
</syntaxhighlight>

This code will now loop through your POST data and set them to the Contact attributes based on your field map. Note that if a match isn't found in the map, it assumes the names are the same in your form as they are in X2.

The last component of the custom form is submitting the data, setting the tracking cookie, and redirecting. The tracking cookie is used for the web tracker which is a part of our professional edition. Even if you're running open source it might be worth setting this so you can have the cookies stored in case you upgrade in the future. You can do these like so:

<syntaxhighlight lang="php">
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And be sure to replace '/path/to/x2' with your web path, 'host.domain' with your server URL, and the redirect with whatever URL you want visitors to be sent to after filling out the form. Now, if we put it all together, the final product should look something like this:

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And that's it! For a basic web lead capture script, this is all we need. The code listed here should be totally functional to copy and paste over to your own server, as long you define your own field map, configure the APIModel constructor, and replace URLs properly. However, it's pretty basic and there's at least one extra feature that might be required to work correctly.

== Advanced Topics ==
TODO: Add this section
=== Duplicate Handling ===
The basic script doesn't have any sort of handling for finding people who submit the form more than once. Instead of simply creating duplicate records, you can do a few little tricks to make this part of the lead script smarter. First things first, we need a way to check for a duplicate Contact. Before you set any attributes on the Contact model which is the code that has: <tt>foreach($attributes as $key=>$value){</tt> you'll want to add this:
<syntaxhighlight lang="php">
$contact->email=$attributes['email'];
$contact->contactLookup();
if($contact->responseCode!='404'){
// Code to handle duplicates here.
}
</syntaxhighlight>

First, we set the email of the Contact because that's the primary way to look for duplicates. Then we call the "contactLookup" function which does exactly what it says--looks up a Contact. If we can't find any, the response code will be a 404. So all we do then is make our if statement check if the response was something other than a 404 and handle the duplicate in here! There's a few different ways we can deal with that. '''All of the code in the following blocks starts at the response code check.''' The first is a simple redirect, ignoring the duplicate record, which would look like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
Header("Location: host.domain");
}
</syntaxhighlight>
Replacing "host.domain" with your own redirect location. The next step is a little more advanced, which would be to instead detect empty fields in the Contact record and fill them with any submitted data, while preserving data already on the record. The code to do that would look something more like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
foreach($attributes as $key => $value){ // Try to set any empty attributes
if(isset($fieldMap[$key]) && empty($contact->{$fieldMap[$key]})){ // Check if value is empty + found in field map
$contact->{$fieldMap[$key]} = $value; // Found in field map, used mapped attribute
}elseif(empty($contact->$key)){ // Just check if value is empty
$contact->$key = $value; // No match in field map, assume it's a Contact attribute
}
}
$contact->contactUpdate();
}
</syntaxhighlight>
=== Adding Tags ===
=== Lead Logging ===
=== Custom Redirects ===
== Advanced Final Product ==
With all the bells and whistles!
TODO: Add this

Web Lead Capture via API (legacy; pre-3.5.6)

2013-11-05T19:14:17Z

Jake: /* Introduction */

Web Lead Capture via API (legacy; pre-3.5.6)

2013-11-05T19:14:07Z

Jake:

[[Category:Development]]
== Introduction ==
'''This version the Web Lead API is only compatible with X2CRM versions <= 3.5.6'''

Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to no development knowledge is required, and the form integrates perfectly with X2 from a web lead standpoint as well as our web tracker. But for some users, this isn't enough. Many websites already have forms in use that they don't want to sacrifice or change, but still want all of the features of X2 integration. The good news is that with some basic development knowledge this is a very doable project. This article will walk you through setting up a custom web lead capture script which will take POST data from your web lead form and enter it into X2 via API. The later sections of the article will cover some advanced customizations to make the form work better for you.

== The Basics ==
The first thing you'll need to do is create some form of capture script, and call it whatever you like. I tend to use things like "contactForm" to be very clear what it is. '''This script should go onto the same webserver as your X2CRM installation''' so that cookies can be properly set, but it doesn't need to be in the same folder. You'll also need to make sure that the "APIModel.php" class file is somewhere accessible. This file is provided in protected/models/ of your X2 installation, and can be copied to anywhere you like. So, what does this capture script currently look like?

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
</syntaxhighlight>

That's about it for now. The first thing we do is include the APIModel class, which will allow for easy use of X2's API. This class is heavily documented and provides a variety of wrapper methods for common X2 API functions. It also behaves in many ways just like a regular model, so if you have any X2 development experience you'll likely feel right at home.

The next steps in this process are to initialize the API Model correctly. To do that, you'll need three things:
* The username of a user with permission to create Contacts
* The user API key of that same user
* The URL of your X2 installation.

The first is easy to obtain, and I recommend using "admin" as it's simpler. From there, go to the "Users" page, click on "admin" in the grid, and select "Update User" from the left sidebar menu. You should see a field called API Key. You can set this to whatever you want, but they're randomly generated upon user creation. For example, mine on my development server at the time of this writing is "7uoHGRIBlb0lKym56ieiDf3c7idzCCP7"

The API Model takes 3 parameters for its constructor. You may be able to guess that they are the username, API key, and URL of the server. So now our code should look something like this:

<syntaxhighlight lang="php">
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
</syntaxhighlight>

That's the most important step to get right. If you don't properly set up your API model, all of the requests will fail and this whole process will be useless. '''Please double check you have entered in the information correctly.'''

Now we need to be able to set the data of our Contact. Most pre-built forms do not follow the same naming conventions of the database columns in X2. As such, I like to build a field map that will translate the information in the POST data into usable information by X2. If all your field names match ours exactly, then this step isn't required and you can simply say <tt>$contact->attributes = $attributes;</tt>

<syntaxhighlight lang="php">
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
</syntaxhighlight>

This code will now loop through your POST data and set them to the Contact attributes based on your field map. Note that if a match isn't found in the map, it assumes the names are the same in your form as they are in X2.

The last component of the custom form is submitting the data, setting the tracking cookie, and redirecting. The tracking cookie is used for the web tracker which is a part of our professional edition. Even if you're running open source it might be worth setting this so you can have the cookies stored in case you upgrade in the future. You can do these like so:

<syntaxhighlight lang="php">
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And be sure to replace '/path/to/x2' with your web path, 'host.domain' with your server URL, and the redirect with whatever URL you want visitors to be sent to after filling out the form. Now, if we put it all together, the final product should look something like this:

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And that's it! For a basic web lead capture script, this is all we need. The code listed here should be totally functional to copy and paste over to your own server, as long you define your own field map, configure the APIModel constructor, and replace URLs properly. However, it's pretty basic and there's at least one extra feature that might be required to work correctly.

== Advanced Topics ==
TODO: Add this section
=== Duplicate Handling ===
The basic script doesn't have any sort of handling for finding people who submit the form more than once. Instead of simply creating duplicate records, you can do a few little tricks to make this part of the lead script smarter. First things first, we need a way to check for a duplicate Contact. Before you set any attributes on the Contact model which is the code that has: <tt>foreach($attributes as $key=>$value){</tt> you'll want to add this:
<syntaxhighlight lang="php">
$contact->email=$attributes['email'];
$contact->contactLookup();
if($contact->responseCode!='404'){
// Code to handle duplicates here.
}
</syntaxhighlight>

First, we set the email of the Contact because that's the primary way to look for duplicates. Then we call the "contactLookup" function which does exactly what it says--looks up a Contact. If we can't find any, the response code will be a 404. So all we do then is make our if statement check if the response was something other than a 404 and handle the duplicate in here! There's a few different ways we can deal with that. '''All of the code in the following blocks starts at the response code check.''' The first is a simple redirect, ignoring the duplicate record, which would look like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
Header("Location: host.domain");
}
</syntaxhighlight>
Replacing "host.domain" with your own redirect location. The next step is a little more advanced, which would be to instead detect empty fields in the Contact record and fill them with any submitted data, while preserving data already on the record. The code to do that would look something more like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
foreach($attributes as $key => $value){ // Try to set any empty attributes
if(isset($fieldMap[$key]) && empty($contact->{$fieldMap[$key]})){ // Check if value is empty + found in field map
$contact->{$fieldMap[$key]} = $value; // Found in field map, used mapped attribute
}elseif(empty($contact->$key)){ // Just check if value is empty
$contact->$key = $value; // No match in field map, assume it's a Contact attribute
}
}
$contact->contactUpdate();
}
</syntaxhighlight>
=== Adding Tags ===
=== Lead Logging ===
=== Custom Redirects ===
== Advanced Final Product ==
With all the bells and whistles!
TODO: Add this

Web Lead Capture via API (legacy; pre-3.5.6)

2013-09-30T23:09:31Z

Jake:

[[Category:Development]]
== Introduction ==
Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to no development knowledge is required, and the form integrates perfectly with X2 from a web lead standpoint as well as our web tracker. But for some users, this isn't enough. Many websites already have forms in use that they don't want to sacrifice or change, but still want all of the features of X2 integration. The good news is that with some basic development knowledge this is a very doable project. This article will walk you through setting up a custom web lead capture script which will take POST data from your web lead form and enter it into X2 via API. The later sections of the article will cover some advanced customizations to make the form work better for you.

== The Basics ==
The first thing you'll need to do is create some form of capture script, and call it whatever you like. I tend to use things like "contactForm" to be very clear what it is. '''This script should go onto the same webserver as your X2CRM installation''' so that cookies can be properly set, but it doesn't need to be in the same folder. You'll also need to make sure that the "APIModel.php" class file is somewhere accessible. This file is provided in protected/models/ of your X2 installation, and can be copied to anywhere you like. So, what does this capture script currently look like?

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
</syntaxhighlight>

That's about it for now. The first thing we do is include the APIModel class, which will allow for easy use of X2's API. This class is heavily documented and provides a variety of wrapper methods for common X2 API functions. It also behaves in many ways just like a regular model, so if you have any X2 development experience you'll likely feel right at home.

The next steps in this process are to initialize the API Model correctly. To do that, you'll need three things:
* The username of a user with permission to create Contacts
* The user API key of that same user
* The URL of your X2 installation.

The first is easy to obtain, and I recommend using "admin" as it's simpler. From there, go to the "Users" page, click on "admin" in the grid, and select "Update User" from the left sidebar menu. You should see a field called API Key. You can set this to whatever you want, but they're randomly generated upon user creation. For example, mine on my development server at the time of this writing is "7uoHGRIBlb0lKym56ieiDf3c7idzCCP7"

The API Model takes 3 parameters for its constructor. You may be able to guess that they are the username, API key, and URL of the server. So now our code should look something like this:

<syntaxhighlight lang="php">
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
</syntaxhighlight>

That's the most important step to get right. If you don't properly set up your API model, all of the requests will fail and this whole process will be useless. '''Please double check you have entered in the information correctly.'''

Now we need to be able to set the data of our Contact. Most pre-built forms do not follow the same naming conventions of the database columns in X2. As such, I like to build a field map that will translate the information in the POST data into usable information by X2. If all your field names match ours exactly, then this step isn't required and you can simply say <tt>$contact->attributes = $attributes;</tt>

<syntaxhighlight lang="php">
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
</syntaxhighlight>

This code will now loop through your POST data and set them to the Contact attributes based on your field map. Note that if a match isn't found in the map, it assumes the names are the same in your form as they are in X2.

The last component of the custom form is submitting the data, setting the tracking cookie, and redirecting. The tracking cookie is used for the web tracker which is a part of our professional edition. Even if you're running open source it might be worth setting this so you can have the cookies stored in case you upgrade in the future. You can do these like so:

<syntaxhighlight lang="php">
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And be sure to replace '/path/to/x2' with your web path, 'host.domain' with your server URL, and the redirect with whatever URL you want visitors to be sent to after filling out the form. Now, if we put it all together, the final product should look something like this:

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And that's it! For a basic web lead capture script, this is all we need. The code listed here should be totally functional to copy and paste over to your own server, as long you define your own field map, configure the APIModel constructor, and replace URLs properly. However, it's pretty basic and there's at least one extra feature that might be required to work correctly.

== Advanced Topics ==
TODO: Add this section
=== Duplicate Handling ===
The basic script doesn't have any sort of handling for finding people who submit the form more than once. Instead of simply creating duplicate records, you can do a few little tricks to make this part of the lead script smarter. First things first, we need a way to check for a duplicate Contact. Before you set any attributes on the Contact model which is the code that has: <tt>foreach($attributes as $key=>$value){</tt> you'll want to add this:
<syntaxhighlight lang="php">
$contact->email=$attributes['email'];
$contact->contactLookup();
if($contact->responseCode!='404'){
// Code to handle duplicates here.
}
</syntaxhighlight>

First, we set the email of the Contact because that's the primary way to look for duplicates. Then we call the "contactLookup" function which does exactly what it says--looks up a Contact. If we can't find any, the response code will be a 404. So all we do then is make our if statement check if the response was something other than a 404 and handle the duplicate in here! There's a few different ways we can deal with that. '''All of the code in the following blocks starts at the response code check.''' The first is a simple redirect, ignoring the duplicate record, which would look like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
Header("Location: host.domain");
}
</syntaxhighlight>
Replacing "host.domain" with your own redirect location. The next step is a little more advanced, which would be to instead detect empty fields in the Contact record and fill them with any submitted data, while preserving data already on the record. The code to do that would look something more like this:
<syntaxhighlight lang="php">
if($contact->responseCode!='404'){
foreach($attributes as $key => $value){ // Try to set any empty attributes
if(isset($fieldMap[$key]) && empty($contact->{$fieldMap[$key]})){ // Check if value is empty + found in field map
$contact->{$fieldMap[$key]} = $value; // Found in field map, used mapped attribute
}elseif(empty($contact->$key)){ // Just check if value is empty
$contact->$key = $value; // No match in field map, assume it's a Contact attribute
}
}
$contact->contactUpdate();
}
</syntaxhighlight>
=== Adding Tags ===
=== Lead Logging ===
=== Custom Redirects ===
== Advanced Final Product ==
With all the bells and whistles!
TODO: Add this

Web Lead Capture via API (legacy; pre-3.5.6)

2013-09-30T19:51:17Z

Jake: /* Final Product */

[[Category:Development]]
== Introduction ==
Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to no development knowledge is required, and the form integrates perfectly with X2 from a web lead standpoint as well as our web tracker. But for some users, this isn't enough. Many websites already have forms in use that they don't want to sacrifice or change, but still want all of the features of X2 integration. The good news is that with some basic development knowledge this is a very doable project. This article will walk you through setting up a custom web lead capture script which will take POST data from your web lead form and enter it into X2 via API. The later sections of the article will cover some advanced customizations to make the form work better for you.

== The Basics ==
The first thing you'll need to do is create some form of capture script, and call it whatever you like. I tend to use things like "contactForm" to be very clear what it is. '''This script should go onto the same webserver as your X2CRM installation''' so that cookies can be properly set, but it doesn't need to be in the same folder. You'll also need to make sure that the "APIModel.php" class file is somewhere accessible. This file is provided in protected/models/ of your X2 installation, and can be copied to anywhere you like. So, what does this capture script currently look like?

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
</syntaxhighlight>

That's about it for now. The first thing we do is include the APIModel class, which will allow for easy use of X2's API. This class is heavily documented and provides a variety of wrapper methods for common X2 API functions. It also behaves in many ways just like a regular model, so if you have any X2 development experience you'll likely feel right at home.

The next steps in this process are to initialize the API Model correctly. To do that, you'll need three things:
* The username of a user with permission to create Contacts
* The user API key of that same user
* The URL of your X2 installation.

The first is easy to obtain, and I recommend using "admin" as it's simpler. From there, go to the "Users" page, click on "admin" in the grid, and select "Update User" from the left sidebar menu. You should see a field called API Key. You can set this to whatever you want, but they're randomly generated upon user creation. For example, mine on my development server at the time of this writing is "7uoHGRIBlb0lKym56ieiDf3c7idzCCP7"

The API Model takes 3 parameters for its constructor. You may be able to guess that they are the username, API key, and URL of the server. So now our code should look something like this:

<syntaxhighlight lang="php">
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
</syntaxhighlight>

That's the most important step to get right. If you don't properly set up your API model, all of the requests will fail and this whole process will be useless. '''Please double check you have entered in the information correctly.'''

Now we need to be able to set the data of our Contact. Most pre-built forms do not follow the same naming conventions of the database columns in X2. As such, I like to build a field map that will translate the information in the POST data into usable information by X2. If all your field names match ours exactly, then this step isn't required and you can simply say <tt>$contact->attributes = $attributes;</tt>

<syntaxhighlight lang="php">
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
</syntaxhighlight>

This code will now loop through your POST data and set them to the Contact attributes based on your field map. Note that if a match isn't found in the map, it assumes the names are the same in your form as they are in X2.

The last component of the custom form is submitting the data, setting the tracking cookie, and redirecting. The tracking cookie is used for the web tracker which is a part of our professional edition. Even if you're running open source it might be worth setting this so you can have the cookies stored in case you upgrade in the future. You can do these like so:

<syntaxhighlight lang="php">
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And be sure to replace '/path/to/x2' with your web path, 'host.domain' with your server URL, and the redirect with whatever URL you want visitors to be sent to after filling out the form. Now, if we put it all together, the final product should look something like this:

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And that's it! For a basic web lead capture script, this is all we need. The code listed here should be totally functional to copy and paste over to your own server, as long you define your own field map, configure the APIModel constructor, and replace URLs properly. However, it's pretty basic and there's at least one extra feature that might be required to work correctly.

== Advanced Topics ==
TODO: Add this section
=== Duplicate Handling ===
=== Adding Tags ===
=== Lead Logging ===
=== Custom Redirects ===
== Advanced Final Product ==
With all the bells and whistles!
TODO: Add this

Web Lead Capture via API (legacy; pre-3.5.6)

2013-09-30T19:51:03Z

Jake:

[[Category:Development]]
== Introduction ==
Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to no development knowledge is required, and the form integrates perfectly with X2 from a web lead standpoint as well as our web tracker. But for some users, this isn't enough. Many websites already have forms in use that they don't want to sacrifice or change, but still want all of the features of X2 integration. The good news is that with some basic development knowledge this is a very doable project. This article will walk you through setting up a custom web lead capture script which will take POST data from your web lead form and enter it into X2 via API. The later sections of the article will cover some advanced customizations to make the form work better for you.

== The Basics ==
The first thing you'll need to do is create some form of capture script, and call it whatever you like. I tend to use things like "contactForm" to be very clear what it is. '''This script should go onto the same webserver as your X2CRM installation''' so that cookies can be properly set, but it doesn't need to be in the same folder. You'll also need to make sure that the "APIModel.php" class file is somewhere accessible. This file is provided in protected/models/ of your X2 installation, and can be copied to anywhere you like. So, what does this capture script currently look like?

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
</syntaxhighlight>

That's about it for now. The first thing we do is include the APIModel class, which will allow for easy use of X2's API. This class is heavily documented and provides a variety of wrapper methods for common X2 API functions. It also behaves in many ways just like a regular model, so if you have any X2 development experience you'll likely feel right at home.

The next steps in this process are to initialize the API Model correctly. To do that, you'll need three things:
* The username of a user with permission to create Contacts
* The user API key of that same user
* The URL of your X2 installation.

The first is easy to obtain, and I recommend using "admin" as it's simpler. From there, go to the "Users" page, click on "admin" in the grid, and select "Update User" from the left sidebar menu. You should see a field called API Key. You can set this to whatever you want, but they're randomly generated upon user creation. For example, mine on my development server at the time of this writing is "7uoHGRIBlb0lKym56ieiDf3c7idzCCP7"

The API Model takes 3 parameters for its constructor. You may be able to guess that they are the username, API key, and URL of the server. So now our code should look something like this:

<syntaxhighlight lang="php">
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
</syntaxhighlight>

That's the most important step to get right. If you don't properly set up your API model, all of the requests will fail and this whole process will be useless. '''Please double check you have entered in the information correctly.'''

Now we need to be able to set the data of our Contact. Most pre-built forms do not follow the same naming conventions of the database columns in X2. As such, I like to build a field map that will translate the information in the POST data into usable information by X2. If all your field names match ours exactly, then this step isn't required and you can simply say <tt>$contact->attributes = $attributes;</tt>

<syntaxhighlight lang="php">
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
</syntaxhighlight>

This code will now loop through your POST data and set them to the Contact attributes based on your field map. Note that if a match isn't found in the map, it assumes the names are the same in your form as they are in X2.

The last component of the custom form is submitting the data, setting the tracking cookie, and redirecting. The tracking cookie is used for the web tracker which is a part of our professional edition. Even if you're running open source it might be worth setting this so you can have the cookies stored in case you upgrade in the future. You can do these like so:

<syntaxhighlight lang="php">
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And be sure to replace '/path/to/x2' with your web path, 'host.domain' with your server URL, and the redirect with whatever URL you want visitors to be sent to after filling out the form. Now, if we put it all together, the final product should look something like this:

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And that's it! For a basic web lead capture script, this is all we need. The code listed here should be totally functional to copy and paste over to your own server, as long you define your own field map, configure the APIModel constructor, and replace URLs properly. However, it's pretty basic and there's at least one extra feature that might be required to work correctly.

== Advanced Topics ==
TODO: Add this section
=== Duplicate Handling ===
=== Adding Tags ===
=== Lead Logging ===
=== Custom Redirects ===
== Final Product ==
With all the bells and whistles!
TODO: Add this

Web Lead Capture via API (legacy; pre-3.5.6)

2013-09-27T23:56:52Z

Jake: /* The Basics */

[[Category:Development]]
== Introduction ==
Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to no development knowledge is required, and the form integrates perfectly with X2 from a web lead standpoint as well as our web tracker. But for some users, this isn't enough. Many websites already have forms in use that they don't want to sacrifice or change, but still want all of the features of X2 integration. The good news is that with some basic development knowledge this is a very doable project. This article will walk you through setting up a custom web lead capture script which will take POST data from your web lead form and enter it into X2 via API. The later sections of the article will cover some advanced customizations to make the form work better for you.

== The Basics ==
The first thing you'll need to do is create some form of capture script, and call it whatever you like. I tend to use things like "contactForm" to be very clear what it is. '''This script should go onto the same webserver as your X2CRM installation''' so that cookies can be properly set, but it doesn't need to be in the same folder. You'll also need to make sure that the "APIModel.php" class file is somewhere accessible. This file is provided in protected/models/ of your X2 installation, and can be copied to anywhere you like. So, what does this capture script currently look like?

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
</syntaxhighlight>

That's about it for now. The first thing we do is include the APIModel class, which will allow for easy use of X2's API. This class is heavily documented and provides a variety of wrapper methods for common X2 API functions. It also behaves in many ways just like a regular model, so if you have any X2 development experience you'll likely feel right at home.

The next steps in this process are to initialize the API Model correctly. To do that, you'll need three things:
* The username of a user with permission to create Contacts
* The user API key of that same user
* The URL of your X2 installation.

The first is easy to obtain, and I recommend using "admin" as it's simpler. From there, go to the "Users" page, click on "admin" in the grid, and select "Update User" from the left sidebar menu. You should see a field called API Key. You can set this to whatever you want, but they're randomly generated upon user creation. For example, mine on my development server at the time of this writing is "7uoHGRIBlb0lKym56ieiDf3c7idzCCP7"

The API Model takes 3 parameters for its constructor. You may be able to guess that they are the username, API key, and URL of the server. So now our code should look something like this:

<syntaxhighlight lang="php">
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
</syntaxhighlight>

That's the most important step to get right. If you don't properly set up your API model, all of the requests will fail and this whole process will be useless. '''Please double check you have entered in the information correctly.'''

Now we need to be able to set the data of our Contact. Most pre-built forms do not follow the same naming conventions of the database columns in X2. As such, I like to build a field map that will translate the information in the POST data into usable information by X2. If all your field names match ours exactly, then this step isn't required and you can simply say <tt>$contact->attributes = $attributes;</tt>

<syntaxhighlight lang="php">
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
</syntaxhighlight>

This code will now loop through your POST data and set them to the Contact attributes based on your field map. Note that if a match isn't found in the map, it assumes the names are the same in your form as they are in X2.

The last component of the custom form is submitting the data, setting the tracking cookie, and redirecting. You can do these like so:

<syntaxhighlight lang="php">
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And be sure to replace '/path/to/x2' with your web path, 'host.domain' with your server URL, and the redirect with whatever URL you want visitors to be sent to after filling out the form. Now, if we put it all together, the final product should look something like this:

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And that's it! For a basic web lead capture script, this is all we need. The code listed here should be totally functional to copy and paste over to your own server, as long you define your own field map, configure the APIModel constructor, and replace URLs properly. However, it's pretty basic and there's at least one extra feature that might be required to work correctly.

== Advanced Topics ==
=== Duplicate Handling ===
=== Adding Tags ===
TODO: Add this section

Web Lead Capture via API (legacy; pre-3.5.6)

2013-09-27T23:36:52Z

Jake:

[[Category:Development]]
== Introduction ==
Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to no development knowledge is required, and the form integrates perfectly with X2 from a web lead standpoint as well as our web tracker. But for some users, this isn't enough. Many websites already have forms in use that they don't want to sacrifice or change, but still want all of the features of X2 integration. The good news is that with some basic development knowledge this is a very doable project. This article will walk you through setting up a custom web lead capture script which will take POST data from your web lead form and enter it into X2 via API. The later sections of the article will cover some advanced customizations to make the form work better for you.

== The Basics ==
The first thing you'll need to do is create some form of capture script, and call it whatever you like. I tend to use things like "contactForm" to be very clear what it is. '''This script should go onto the same webserver as your X2CRM installation''' so that cookies can be properly set, but it doesn't need to be in the same folder. You'll also need to make sure that the "APIModel.php" class file is somewhere accessible. This file is provided in protected/models/ of your X2 installation, and can be copied to anywhere you like. So, what does this capture script currently look like?

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
</syntaxhighlight>

That's about it for now. The first thing we do is include the APIModel class, which will allow for easy use of X2's API. This class is heavily documented and provides a variety of wrapper methods for common X2 API functions. It also behaves in many ways just like a regular model, so if you have any X2 development experience you'll likely feel right at home.

The next steps in this process are to initialize the API Model correctly. To do that, you'll need three things:
* The username of a user with permission to create Contacts
* The user API key of that same user
* The URL of your X2 installation.

The first is easy to obtain, and I recommend using "admin" as it's simpler. From there, go to the "Users" page, click on "admin" in the grid, and select "Update User" from the left sidebar menu. You should see a field called API Key. You can set this to whatever you want, but they're randomly generated upon user creation. For example, mine on my development server at the time of this writing is "7uoHGRIBlb0lKym56ieiDf3c7idzCCP7"

The API Model takes 3 parameters for its constructor. You may be able to guess that they are the username, API key, and URL of the server. So now our code should look something like this:

<syntaxhighlight lang="php">
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
</syntaxhighlight>

That's the most important step to get right. If you don't properly set up your API model, all of the requests will fail and this whole process will be useless. '''Please double check you have entered in the information correctly.'''

Now we need to be able to set the data of our Contact. Most pre-built forms do not follow the same naming conventions of the database columns in X2. As such, I like to build a field map that will translate the information in the POST data into usable information by X2. If all your field names match ours exactly, then this step isn't required and you can simply say <tt>$contact->attributes = $attributes;</tt>

<syntaxhighlight lang="php">
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
</syntaxhighlight>

This code will now loop through your POST data and set them to the Contact attributes based on your field map. Note that if a match isn't found in the map, it assumes the names are the same in your form as they are in X2.

The last component of the custom form is submitting the data, setting the tracking cookie, and redirecting. You can do these like so:

<syntaxhighlight lang="php">
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And be sure to replace '/path/to/x2' with your web path, 'host.domain' with your server URL, and the redirect with whatever URL you want visitors to be sent to after filling out the form. Now, if we put it all together, the final product should look something like this:

<syntaxhighlight lang="php">
<?php
require 'APIModel.php';
$attributes = $_POST;
$contact = new APIModel('admin','7uoHGRIBlb0lKym56ieiDf3c7idzCCP7','www.host.domain/path/to/x2');
$fieldMap = array( // This map should be of the format 'your_fieldname'=>'x2_fieldname',
'first_name'=>'firstName',
'last_name'=>'lastName',
'mobile'=>'phone2',
'information'=>'backgroundInfo',
);
foreach($attributes as $key=>$value){
if(isset($fieldMap[$key])){
$contact->{$fieldMap[$key]}=$value; // Found in field map, used mapped attribute
}else{
$contact->$key=$value; // No match anywhere, assume it's a Contact attribute
}
}
$contact->contactCreate(); // Call API to create contact
if(!empty($contact->trackingKey)){
setcookie('x2_key',$contact->trackingKey,time()+31536000,'/path/to/x2','host.domain'); // Set cookie
}
Header('Location: host.domain/redirect'); // Redirect to homepage
</syntaxhighlight>

And that's it! For a basic web lead capture script, this is all we need. The code listed here should be totally functional to copy and paste over to your own server, as long you define your own field map properly. However, it's pretty basic and there's at least one extra feature that might be required to work correctly.

== Advanced Topics ==
=== Duplicate Handling ===
=== Adding Tags ===
TODO: Add this section

Web Lead Capture via API (legacy; pre-3.5.6)

2013-09-27T23:32:08Z

Jake:

Web Lead Capture via API (legacy; pre-3.5.6)

2013-09-27T23:31:54Z

Jake:

Web Lead Capture via API (legacy; pre-3.5.6)

2013-09-27T23:18:22Z

Jake:

Web Lead Capture via API (legacy; pre-3.5.6)

2013-09-27T23:03:03Z

Jake: Created page with "Category:Development == Introduction == Our web lead from editor allows for some solid forms that the average user can put on their website without much issue. Little to n..."

Customization Framework

2013-08-26T20:34:55Z

Jake: /* Custom App Configuration */

[[Category:Development]]
= Introduction =
X2CRM's source code is completely transparent and totally under your control. There's no need to compiled PHP, so altering your software is a simply a matter of hacking around in the files. Traditionally, this meant directly altering the source code within X2Engine's file structure. But this could be problematic to keep track of, given the vast number of files. On top of that, automatic updates to any of those files would wipe out all of your changes, so you would have to choose between customization and receiving updates.

X2Engine provides a means to alter classes and templates without modifying the original source files. You can create an alternate version of any PHP file, while preserving the original, which makes it much easier to keep track of your changes as well as preserving your alterations through updates. You may still need to rework your custom code when an update is incompatible, but it will be much easier.

= Overriding Files =
[[File:Custom_folder.gif|right]]
Practically any php file used in X2Engine can be overridden. X2Engine's customization framework resides in the <tt>/custom</tt> directory, which mirrors the structure of the source code. For example, <tt>/custom/protected/components</tt> corresponds to <tt>/protected/components</tt>. Any php file placed in <tt>/custom</tt> will be used instead of the original.
{{clear}}
= Extending Controllers =
X2Engine is built on Yii, which uses MVC (model-view-controller) architecture. Overriding an entire file is practical when dealing with views or smaller classes (such as models), but controllers can present a greater challenge. It's only a matter of time before we update one of the 1500+ lines of code in a controller. This means you have to manually find and transfer your changes from the old version, which is time-consuming. To remedy this, we allow substitution of any controller in X2Engine with an extended class.

Whenever a controller is loaded, X2Engine checks for the same filename with "My" at the beginning. For example, if you want to override a single action to ContactsController, you can create a file called MyContactsController in <tt>/custom/protected/modules/contacts/controllers</tt> containing the following:
<syntaxhighlight lang="php">
<?php
class MyContactsController extends ContactsController {
function actionIndex() {
echo 'Hello World!';
}
}
?>
</syntaxhighlight>

This file will automatically be used instead of ContactsController and should still work if ContactsController is changed in an update. You may still need to manually merge changes if an update alters the same part of the controller that you changed, but it will be much easier to find.

= Custom App Configuration =
The configuration for the Yii application can also be customized through the files "web.php", "console.php" and "test.php" in <tt>custom/protected/config</tt>. These files will be included and run in the default configuration files for X2CRM running as a web application, console application or unit testing environment (respectively).

An array which mirrors the modified parts of main.php (the default configuration file) should be returned within the custom config file. To customize the configuration of the application, i.e. to add parameters to <tt>Yii::app()->params</tt>, one only need add/remove/alter the values and keys within <tt>$config</tt>.

= Known Issues =
* Currently, only PHP files can be substituted. To change a CSS or Javascript file you would have to edit the original file.

* There is no guarantee a customized installation will still work after an update. You will still have to manually merge changes if you want (or need) to use an updated version of a customized file. Depending on the file, you may have to do this for most automatic updates (since some files are changed far more often than others). Luckilly, most of our changes are usually in controller files, which can be extended rather than just replaced, so the updates are less likely to be incompatible with your modifications.

Interacting with the Database

2013-08-23T21:19:37Z

Jake:

[[Category:Development]]
{TODO: Finish CDbCommand, Models,How To's for all sections}
== Introduction ==

X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

== Raw SQL ==
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the software solely with Raw SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria. Obviously this is the only method of interaction with the database through an administrative interface like phpMyAdmin or Virtualmin, and no parameter binding is available.

=== Examples ===
Raw SQL can (for the most part) be used in 3 ways within X2CRM. The first two are both similar and are exclusively ways of accessing rows of data from the database. These are CSqlDataProvider, and the Model's findBySql method. The purposes of these examples are to show how to get effectively the same set of data using three different methods, even though this is not the ideal situation to use Raw SQL. Thus, some of these queries are excessively simplistic and do not return very useful data, but an example of how to use SQL in this context is demonstrated.

'''CSqlDataProvider'''
<syntaxhighlight lang="php">
$count = Yii::app()->db->createCommand('SELECT COUNT(*) FROM x2_contacts WHERE firstName IS NOT NULL')->queryScalar();
$sql = "SELECT * FROM x2_contacts WHERE firstName IS NOT NULL";
$dataProvider = new CSqlDataProvider($sql, array(
'totalItemCount' => $count,
'sort' => array(
'attributes' => array(
'id', 'lastName', 'email',
),
),
'pagination' => array(
'pageSize' => 10,
),
));
</syntaxhighlight>

This code will get a Data Provider populated with all records from the Contacts table where the First Name field is not blank. Parameters to be bound can be provided as a "params" array. The fields listed in the "sort" array specify which columns can be sorted on, and providing a "totalItemCount" is required for pagination. The CSqlDataProvider has a few places where it can be very useful, like for creating a Grid View of data from a table with no associated model. However, it is often easier to simply make a model and gain access to a lot of other features in the process.

'''Find By SQL'''
<syntaxhighlight lang="php">
$sql = 'SELECT * FROM x2_contacts WHERE firstName IS NOT NULL';
$contacts = X2Model::model('Contacts')->findAllBySql($sql);
</syntaxhighlight>

This code will return an array of Contact models where the First Name field is not blank. As with the CSqlDataProvider, parameters can be bound as an optional second function parameter of findAllBySql. This is fairly simplistic and not really all that useful, unless you're looking to loop through and perform data operations on the models. There are better ways to do this particular task. However, these can be loaded into a CActiveDataProvider by calling its setData method on this array.

'''CDbCommand'''
<syntaxhighlight lang="php">
$sql = 'SELECT * FROM x2_contacts WHERE firstName IS NOT NULL';
$contacts = Yii::app()->db->createCommand($sql)->queryAll();
</syntaxhighlight>

This code will return an array of arrays, where each secondary array is an associative array of Contact attributes. Parameters can be bound as an optional second function parameter of queryAll, the first being a flag of whether to return an associative array (which defaults to true). This is also not particularly useful because it will be difficult to get any data changes you make back into the database, and there are again better ways to obtain this kind of data.

== CDbCommand ==
[[yii:CDbCommand|CDbCommand]] is a class provided by the Yii Framework which allows for one layer of abstraction from writing raw SQL to run queries. As seen in the documentation, wrapper methods for most SQL commands are available so that a query which may look like: <tt>SELECT * FROM x2_contacts WHERE name='John Smith'</tt> turns into:
<syntaxhighlight lang="php">
$result = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('name=:name', array(':name' => 'John Smith'))
->queryAll();
</syntaxhighlight>
This looks more complicated at first glance, and it is slightly--but it doesn't involve writing any SQL. On top of that, some of the more complicated queries get simpler with this class, and also queries with dynamic information are easier. Let's say I wanted to grab every column except "createDate" from an arbitrary model we don't know the type of. First off, this isn't possible with raw SQL. You need to do pre-processing in PHP to get the query correct. You'd have to loop through all of the attributes, build the select statement, and then lookup the table name and pass that into the string. But for a CDbCommand:
<syntaxhighlight lang="php">
$attributes = $model->attributes;
unset($attributes['createDate']);
$attributes = array_keys($attributes);
$result = Yii::app()->db->createCommand()
->select($attributes)
->from($model->tableName())
->queryAll();
</syntaxhighlight>

'''Pros'''
* Security. CDbCommand allows for parameter binding, which prevents SQL injection so long as you set up your command properly.
* Speed. Still fairly quick, as CDbCommand simply converts the command object into a string SQL query.
* Some complex queries like joins are easier to do with CDbCommand than Raw SQL.
'''Cons'''
* Some simple queries like basic selects are more complicated than Raw SQL.
* Still requires some SQL knowledge, as most of the command methods are just aliases for SQL commands.
* Most of Yii's Data Providers / data display objects aren't inherently compatible with CDbCommands (though as of 1.1.13 CSqlDataProvider can take a CDbCommand).

In general, I prefer to use CDbCommand only when there is no Model for the table I am working with, or if I only need 1-2 columns of data and loading the full model would be a waste of memory. It has its uses in some very specific situations but Models should usually be used in favor of this.
== Models ==
Models are the primary method of interaction with the database in X2CRM. All Models in the software extend one of two classes: [[x2doc:X2Model|X2Model]] or [[yii:CActiveRecord|CActiveRecord]]. X2Model is a special model class that extends CActiveRecord and is used for Models which have dynamic fields rather than a fixed set of attributes. Examples of this include Contacts, Accounts, and most of the major modules. CActiveRecord models are for tables with static field definitions and don't need the advanced functionality of X2Model. Examples of this include models like Fields, Profiles, and most non-major module related models.

Models provide the easiest method of interaction with database records. For example, if we wanted to load a model into a form, allow a user to edit the data, and then update the database record, here is how it would be done in each of the three methods:

'''Raw SQL'''
<syntaxhighlight lang="php">
// Code to get the database ID
$attributes=Yii::app()->db->createCommand('SELECT * FROM x2_contacts WHERE id='.$id)->queryRow();
// Code to pass $attributes into the form and load new attributes into $_POST['Contacts']
$update='';
foreach($_POST['Contacts'] as $attribute=>$value){
$update.=$attribute."='".$value."', ";
}
if(!empty($update)){
$update=substr($update,0,-2);
Yii::app()->db->createCommand('UPDATE x2_contacts SET '.$updateQuery.' WHERE id='.$id);
}
</syntaxhighlight>

'''CDbCommand'''
<syntaxhighlight lang="php">
// Code to get the database ID
$attributes = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('id=:id', array(':id' => $id))
->queryRow();
// Code to pass $attributes into the form and load new attributes into $_POST['Contacts']
Yii::app()->db->createCommand()
->update('x2_contacts', $_POST['Contacts'], 'id=:id', array(':id' => $id));
</syntaxhighlight>

'''Model'''
<syntaxhighlight lang="php">
// Code to get the database ID
$model = X2Model::model('Contacts')->findByPk($id);
$attributes = $model->attributes;
// Code to pass $attributes into the form and load new attributes into $_POST['Contacts']
$model->attributes = $_POST['Contacts'];
$model->save();
</syntaxhighlight>
As can be seen, the Model method is by far the simplest. What's more, none of the 3 listed methods above will actually work with the X2CRM codebase. This is because the way data is stored is not always the same as it is entered by or displayed to a user. For example, date fields display in a nice, localized format and are entered via a Date Picker widget. However, they are stored in the database as UNIX Timestamps for ease of conversion to other formats and mathematical operations. So simply setting
<syntaxhighlight lang="php">
$model->attributes = $_POST['Contacts'];
</syntaxhighlight>
will not work, but X2Model has a special method written to handle cases like this. If we instead call
<syntaxhighlight lang="php">
$model->setX2Fields($_POST['Contacts']);
</syntaxhighlight>
The Model class itself will properly format user input data into a database-friendly format. This is because information on each Model attribute is stored in the x2_fields table and can be easily accessed within the Model class. Performing a similar operation via CDbCommand or Raw SQL would be very lengthy and tedious. Models and X2Model in particular really deserve their own page, so an in-depth discussion on that will be left for elsewhere.

'''Pros'''
* Ease of use. Models are incredibly easy to work with and require little to no SQL knowledge to use.
* Functionality. Models have a very large number of built in functions to make your life easier, and we've made even more of these available through X2Model and its related behaviors.
* Flexibility. Yii's code has an absolute ton of functionality designed to work with Models. Many, many things are available to load models, get lists of them and render those lists, etc.
'''Cons'''
* Size. Models involve loading all of the data for a row from the database table, but have a lot of associated overhead. There are a large number of method calls and pieces of other information stored in the model that can increase overhead.
* Limited Purpose. Models are mostly intended to be a representation of a row of data, which is fantastic if that's what you need (and for most of what X2 does, it is) but for complicated or specific queries (especially ones collecting aggregate data or statistics) they are not particularly useful.
* Learning Curve. There are a lot of things Models can do, and it certainly took me a while to figure out a lot of the more interesting or obscure features and methods.

Interacting with the Database

2013-08-20T22:41:31Z

Jake:

[[Category:Development]]
{TODO: Finish CDbCommand, Models,How To's for all sections}
== Introduction ==

X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

== Raw SQL ==
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the software solely with Raw SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria.

=== Examples ===
Raw SQL can (for the most part) be used in 3 ways within X2CRM. The first two are both similar and are exclusively ways of accessing rows of data from the database. These are CSqlDataProvider, and the Model's findBySql method.

'''CSqlDataProvider'''
<syntaxhighlight lang="php">
$count = Yii::app()->db->createCommand('SELECT COUNT(*) FROM x2_contacts WHERE firstName IS NOT NULL')->queryScalar();
$sql = "SELECT * FROM x2_contacts WHERE firstName IS NOT NULL";
$dataProvider = new CSqlDataProvider($sql, array(
'totalItemCount' => $count,
'sort' => array(
'attributes' => array(
'id', 'lastName', 'email',
),
),
'pagination' => array(
'pageSize' => 10,
),
));
</syntaxhighlight>

This code will get a Data Provider populated with all records from the Contacts table where the First Name field is not blank. Parameters to be bound can be provided as a "params" array. The fields listed in the "sort" array specify which columns can be sorted on, and providing a "totalItemCount" is required for pagination. The CSqlDataProvider has a few places where it can be very useful, like for creating a Grid View of data from a table with no associated model. However, it is often easier to simply make a model and gain access to a lot of other features in the process.

'''Find By SQL'''
<syntaxhighlight lang="php">

</syntaxhighlight>

== CDbCommand ==
[[yii:CDbCommand|CDbCommand]] is a class provided by the Yii Framework which allows for one layer of abstraction from writing raw SQL to run queries. As seen in the documentation, wrapper methods for most SQL commands are available so that a query which may look like: <tt>SELECT * FROM x2_contacts WHERE name='John Smith'</tt> turns into:
<syntaxhighlight lang="php">
$result = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('name=:name', array(':name' => 'John Smith'))
->queryAll();
</syntaxhighlight>
This looks more complicated at first glance, and it is slightly--but it doesn't involve writing any SQL. On top of that, some of the more complicated queries get simpler with this class, and also queries with dynamic information are easier. Let's say I wanted to grab every column except "createDate" from an arbitrary model we don't know the type of. First off, this isn't possible with raw SQL. You need to do pre-processing in PHP to get the query correct. You'd have to loop through all of the attributes, build the select statement, and then lookup the table name and pass that into the string. But for a CDbCommand:
<syntaxhighlight lang="php">
$attributes = $model->attributes;
unset($attributes['createDate']);
$attributes = array_keys($attributes);
$result = Yii::app()->db->createCommand()
->select($attributes)
->from($model->tableName())
->queryAll();
</syntaxhighlight>

'''Pros'''
* Security. CDbCommand allows for parameter binding, which prevents SQL injection so long as you set up your command properly.
* Speed. Still fairly quick, as CDbCommand simply converts the command object into a string SQL query.
* Some complex queries like joins are easier to do with CDbCommand than Raw SQL.
'''Cons'''
* Some simple queries like basic selects are more complicated than Raw SQL.
* Still requires some SQL knowledge, as most of the command methods are just aliases for SQL commands.
* Most of Yii's Data Providers / data display objects aren't inherently compatible with CDbCommands (though as of 1.1.13 CSqlDataProvider can take a CDbCommand).

In general, I prefer to use CDbCommand only when there is no Model for the table I am working with, or if I only need 1-2 columns of data and loading the full model would be a waste of memory. It has its uses in some very specific situations but Models should usually be used in favor of this.
== Models ==
Models are the primary method of interaction with the database in X2CRM. All Models in the software extend one of two classes: [[x2doc:X2Model|X2Model]] or [[yii:CActiveRecord|CActiveRecord]]. X2Model is a special model class that extends CActiveRecord and is used for Models which have dynamic fields rather than a fixed set of attributes. Examples of this include Contacts, Accounts, and most of the major modules. CActiveRecord models are for tables with static field definitions and don't need the advanced functionality of X2Model. Examples of this include models like Fields, Profiles, and most non-major module related models.

Models provide the easiest method of interaction with database records. For example, if we wanted to load a model into a form, allow a user to edit the data, and then update the database record, here is how it would be done in each of the three methods:

'''Raw SQL'''
<syntaxhighlight lang="php">
// Code to get the database ID
$attributes=Yii::app()->db->createCommand('SELECT * FROM x2_contacts WHERE id='.$id)->queryRow();
// Code to pass $attributes into the form and load new attributes into $_POST['Contacts']
$update='';
foreach($_POST['Contacts'] as $attribute=>$value){
$update.=$attribute."='".$value."', ";
}
if(!empty($update)){
$update=substr($update,0,-2);
Yii::app()->db->createCommand('UPDATE x2_contacts SET '.$updateQuery.' WHERE id='.$id);
}
</syntaxhighlight>

'''CDbCommand'''
<syntaxhighlight lang="php">
// Code to get the database ID
$attributes = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('id=:id', array(':id' => $id))
->queryRow();
// Code to pass $attributes into the form and load new attributes into $_POST['Contacts']
Yii::app()->db->createCommand()
->update('x2_contacts', $_POST['Contacts'], 'id=:id', array(':id' => $id));
</syntaxhighlight>

'''Model'''
<syntaxhighlight lang="php">
// Code to get the database ID
$model = X2Model::model('Contacts')->findByPk($id);
$attributes = $model->attributes;
// Code to pass $attributes into the form and load new attributes into $_POST['Contacts']
$model->attributes = $_POST['Contacts'];
$model->save();
</syntaxhighlight>
As can be seen, the Model method is by far the simplest. What's more, none of the 3 listed methods above will actually work with the X2CRM codebase. This is because the way data is stored is not always the same as it is entered by or displayed to a user. For example, date fields display in a nice, localized format and are entered via a Date Picker widget. However, they are stored in the database as UNIX Timestamps for ease of conversion to other formats and mathematical operations. So simply setting
<syntaxhighlight lang="php">
$model->attributes = $_POST['Contacts'];
</syntaxhighlight>
will not work, but X2Model has a special method written to handle cases like this. If we instead call
<syntaxhighlight lang="php">
$model->setX2Fields($_POST['Contacts']);
</syntaxhighlight>
The Model class itself will properly format user input data into a database-friendly format. This is because information on each Model attribute is stored in the x2_fields table and can be easily accessed within the Model class. Performing a similar operation via CDbCommand or Raw SQL would be very lengthy and tedious. Models and X2Model in particular really deserve their own page, so an in-depth discussion on that will be left for elsewhere.

'''Pros'''
* Ease of use. Models are incredibly easy to work with and require little to no SQL knowledge to use.
* Functionality. Models have a very large number of built in functions to make your life easier, and we've made even more of these available through X2Model and its related behaviors.
* Flexibility. Yii's code has an absolute ton of functionality designed to work with Models. Many, many things are available to load models, get lists of them and render those lists, etc.
'''Cons'''
* Size. Models involve loading all of the data for a row from the database table, but have a lot of associated overhead. There are a large number of method calls and pieces of other information stored in the model that can increase overhead.
* Limited Purpose. Models are mostly intended to be a representation of a row of data, which is fantastic if that's what you need (and for most of what X2 does, it is) but for complicated or specific queries (especially ones collecting aggregate data or statistics) they are not particularly useful.
* Learning Curve. There are a lot of things Models can do, and it certainly took me a while to figure out a lot of the more interesting or obscure features and methods.

Interacting with the Database

2013-08-15T22:56:06Z

Jake:

[[Category:Development]]
{TODO: Finish CDbCommand, Models,How To's for all sections}
== Introduction ==

X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

== Raw SQL ==
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the software solely with Raw SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria.

== CDbCommand ==
[[yii:CDbCommand|CDbCommand]] is a class provided by the Yii Framework which allows for one layer of abstraction from writing raw SQL to run queries. As seen in the documentation, wrapper methods for most SQL commands are available so that a query which may look like: <tt>SELECT * FROM x2_contacts WHERE name='John Smith'</tt> turns into:
<syntaxhighlight lang="php">
$result = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('name=:name', array(':name' => 'John Smith'))
->queryAll();
</syntaxhighlight>
This looks more complicated at first glance, and it is slightly--but it doesn't involve writing any SQL. On top of that, some of the more complicated queries get simpler with this class, and also queries with dynamic information are easier. Let's say I wanted to grab every column except "createDate" from an arbitrary model we don't know the type of. First off, this isn't possible with raw SQL. You need to do pre-processing in PHP to get the query correct. You'd have to loop through all of the attributes, build the select statement, and then lookup the table name and pass that into the string. But for a CDbCommand:
<syntaxhighlight lang="php">
$attributes = $model->attributes;
unset($attributes['createDate']);
$attributes = array_keys($attributes);
$result = Yii::app()->db->createCommand()
->select($attributes)
->from($model->tableName())
->queryAll();
</syntaxhighlight>

'''Pros'''
* Security. CDbCommand allows for parameter binding, which prevents SQL injection so long as you set up your command properly.
* Speed. Still fairly quick, as CDbCommand simply converts the command object into a string SQL query.
* Some complex queries like joins are easier to do with CDbCommand than Raw SQL.
'''Cons'''
* Some simple queries like basic selects are more complicated than Raw SQL.
* Still requires some SQL knowledge, as most of the command methods are just aliases for SQL commands.
* Most of Yii's Data Providers / data display objects aren't inherently compatible with CDbCommands (though as of 1.1.13 CSqlDataProvider can take a CDbCommand).

In general, I prefer to use CDbCommand only when there is no Model for the table I am working with, or if I only need 1-2 columns of data and loading the full model would be a waste of memory. It has its uses in some very specific situations but Models should usually be used in favor of this.
== Models ==
Models are the primary method of interaction with the database in X2CRM. All Models in the software extend one of two classes: [[x2doc:X2Model|X2Model]] or [[yii:CActiveRecord|CActiveRecord]]. X2Model is a special model class that extends CActiveRecord and is used for Models which have dynamic fields rather than a fixed set of attributes. Examples of this include Contacts, Accounts, and most of the major modules. CActiveRecord models are for tables with static field definitions and don't need the advanced functionality of X2Model. Examples of this include models like Fields, Profiles, and most non-major module related models.

Models provide the easiest method of interaction with database records. For example, if we wanted to load a model into a form, allow a user to edit the data, and then update the database record, here is how it would be done in each of the three methods:

'''Raw SQL'''
<syntaxhighlight lang="php">
// Code to get the database ID
$attributes=Yii::app()->db->createCommand('SELECT * FROM x2_contacts WHERE id='.$id)->queryRow();
// Code to pass $attributes into the form and load new attributes into $_POST['Contacts']
$update='';
foreach($_POST['Contacts'] as $attribute=>$value){
$update.=$attribute."='".$value."', ";
}
if(!empty($update)){
$update=substr($update,0,-2);
Yii::app()->db->createCommand('UPDATE x2_contacts SET '.$updateQuery.' WHERE id='.$id);
}
</syntaxhighlight>

'''CDbCommand'''
<syntaxhighlight lang="php">
// Code to get the database ID
$attributes = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('id=:id', array(':id' => $id))
->queryRow();
// Code to pass $attributes into the form and load new attributes into $_POST['Contacts']
Yii::app()->db->createCommand()
->update('x2_contacts', $_POST['Contacts'], 'id=:id', array(':id' => $id));
</syntaxhighlight>

'''Model'''
<syntaxhighlight lang="php">
// Code to get the database ID
$model = X2Model::model('Contacts')->findByPk($id);
$attributes = $model->attributes;
// Code to pass $attributes into the form and load new attributes into $_POST['Contacts']
$model->attributes = $_POST['Contacts'];
$model->save();
</syntaxhighlight>
As can be seen, the Model method is by far the simplest. What's more, none of the 3 listed methods above will actually work with the X2CRM codebase. This is because the way data is stored is not always the same as it is entered by or displayed to a user. For example, date fields display in a nice, localized format and are entered via a Date Picker widget. However, they are stored in the database as UNIX Timestamps for ease of conversion to other formats and mathematical operations. So simply setting
<syntaxhighlight lang="php">
$model->attributes = $_POST['Contacts'];
</syntaxhighlight>
will not work, but X2Model has a special method written to handle cases like this. If we instead call
<syntaxhighlight lang="php">
$model->setX2Fields($_POST['Contacts']);
</syntaxhighlight>
The Model class itself will properly format user input data into a database-friendly format. This is because information on each Model attribute is stored in the x2_fields table and can be easily accessed within the Model class. Performing a similar operation via CDbCommand or Raw SQL would be very lengthy and tedious. Models and X2Model in particular really deserve their own page, so an in-depth discussion on that will be left for elsewhere.

'''Pros'''
* Ease of use. Models are incredibly easy to work with and require little to no SQL knowledge to use.
* Functionality. Models have a very large number of built in functions to make your life easier, and we've made even more of these available through X2Model and its related behaviors.
* Flexibility. Yii's code has an absolute ton of functionality designed to work with Models. Many, many things are available to load models, get lists of them and render those lists, etc.
'''Cons'''
* Size. Models involve loading all of the data for a row from the database table, but have a lot of associated overhead. There are a large number of method calls and pieces of other information stored in the model that can increase overhead.
* Limited Purpose. Models are mostly intended to be a representation of a row of data, which is fantastic if that's what you need (and for most of what X2 does, it is) but for complicated or specific queries (especially ones collecting aggregate data or statistics) they are not particularly useful.

Interacting with the Database

2013-08-15T22:02:21Z

Jake:

Interacting with the Database

2013-08-14T21:32:21Z

Jake:

Interacting with the Database

2013-08-14T20:57:05Z

Jake:

Interacting with the Database

2013-08-08T22:57:33Z

Jake:

[[Category:Development]]
{TODO: Finish CDbCommand, Models,How To's for all sections}
= Introduction =

X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

= Raw SQL =
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the software solely with Raw SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria.

= CDbCommand =
CDbCommand [http://www.yiiframework.com/doc/api/1.1/CDbCommand] is a class provided by the Yii Framework which allows for one layer of abstraction from writing raw SQL to run queries. As seen in the documentation, wrapper methods for most SQL commands are available so that a query which may look like: <tt>SELECT * FROM x2_contacts WHERE name='John Smith'</tt> turns into:
<syntaxhighlight lang="php">
$result = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('name=:name', array(':name' => 'John Smith'))
->queryAll();
</syntaxhighlight>
This looks more complicated at first glance, and it is slightly--but it doesn't involve writing any SQL. On top of that, some of the more complicated queries get simpler with this class, and also queries with dynamic information are easier. Let's say I wanted to grab every column except "createDate" from an arbitrary model we don't know the type of. First off, this isn't possible with raw SQL. You need to do pre-processing in PHP to get the query correct. You'd have to loop through all of the attributes, build the select statement, and then lookup the table name and pass that into the string. But for a CDbCommand:
<syntaxhighlight lang="php">
$attributes = $model->attributes;
unset($attributes['createDate']);
$attributes = array_keys($attributes);
$result = Yii::app()->db->createCommand()
->select($attributes)
->from($model->tableName())
->queryAll();
</syntaxhighlight>
= Models =

Interacting with the Database

2013-08-08T22:56:46Z

Jake:

[[Category:Development]]
= Introduction =
{TODO: Finish CDbCommand, Models,How To's for all sections}
X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

= Raw SQL =
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the software solely with Raw SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria.

= CDbCommand =
CDbCommand [http://www.yiiframework.com/doc/api/1.1/CDbCommand] is a class provided by the Yii Framework which allows for one layer of abstraction from writing raw SQL to run queries. As seen in the documentation, wrapper methods for most SQL commands are available so that a query which may look like: <tt>SELECT * FROM x2_contacts WHERE name='John Smith'</tt> turns into:
<syntaxhighlight lang="php">
$result = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('name=:name', array(':name' => 'John Smith'))
->queryAll();
</syntaxhighlight>
This looks more complicated at first glance, and it is slightly--but it doesn't involve writing any SQL. On top of that, some of the more complicated queries get simpler with this class, and also queries with dynamic information are easier. Let's say I wanted to grab every column except "createDate" from an arbitrary model we don't know the type of. First off, this isn't possible with raw SQL. You need to do pre-processing in PHP to get the query correct. You'd have to loop through all of the attributes, build the select statement, and then lookup the table name and pass that into the string. But for a CDbCommand:
<syntaxhighlight lang="php">
$attributes = $model->attributes;
unset($attributes['createDate']);
$attributes = array_keys($attributes);
$result = Yii::app()->db->createCommand()
->select($attributes)
->from($model->tableName())
->queryAll();
</syntaxhighlight>
= Models =

Interacting with the Database

2013-08-08T22:55:37Z

Jake:

Interacting with the Database

2013-08-08T22:55:12Z

Jake:

[[Category:Development]]
= Introduction =
[[Category:Development]]
X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

= Raw SQL =
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the software solely with Raw SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria.

= CDbCommand =
CDbCommand [http://www.yiiframework.com/doc/api/1.1/CDbCommand] is a class provided by the Yii Framework which allows for one layer of abstraction from writing raw SQL to run queries. As seen in the documentation, wrapper methods for most SQL commands are available so that a query which may look like: <tt>SELECT * FROM x2_contacts WHERE name='John Smith'</tt> turns into:
<syntaxhighlight lang="php">
$result = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('name=:name', array(':name' => 'John Smith'))
->queryAll();
</syntaxhighlight>
This looks more complicated at first glance, and it is slightly--but it doesn't involve writing any SQL. On top of that, some of the more complicated queries get simpler with this class, and also queries with dynamic information are easier. Let's say I wanted to grab every column except "createDate" from an arbitrary model we don't know the type of. First off, this isn't possible with raw SQL. You need to do pre-processing in PHP to get the query correct. You'd have to loop through all of the attributes, build the select statement, and then lookup the table name and pass that into the string. But for a CDbCommand:
<syntaxhighlight lang="php">
$attributes = $model->attributes;
unset($attributes['createDate']);
$attributes = array_keys($attributes);
$result = Yii::app()->db->createCommand()
->select($attributes)
->from($model->tableName())
->queryAll();
</syntaxhighlight>

Interacting with the Database

2013-08-08T22:54:54Z

Jake:

[[Category:Development]]
{TODO: CDbCommand, Models, How To's for all sections.}

= Introduction =

X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

= Raw SQL =
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the software solely with Raw SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria.

= CDbCommand =
CDbCommand [http://www.yiiframework.com/doc/api/1.1/CDbCommand] is a class provided by the Yii Framework which allows for one layer of abstraction from writing raw SQL to run queries. As seen in the documentation, wrapper methods for most SQL commands are available so that a query which may look like: <tt>SELECT * FROM x2_contacts WHERE name='John Smith'</tt> turns into:
<syntaxhighlight lang="php">
$result = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('name=:name', array(':name' => 'John Smith'))
->queryAll();
</syntaxhighlight>
This looks more complicated at first glance, and it is slightly--but it doesn't involve writing any SQL. On top of that, some of the more complicated queries get simpler with this class, and also queries with dynamic information are easier. Let's say I wanted to grab every column except "createDate" from an arbitrary model we don't know the type of. First off, this isn't possible with raw SQL. You need to do pre-processing in PHP to get the query correct. You'd have to loop through all of the attributes, build the select statement, and then lookup the table name and pass that into the string. But for a CDbCommand:
<syntaxhighlight lang="php">
$attributes = $model->attributes;
unset($attributes['createDate']);
$attributes = array_keys($attributes);
$result = Yii::app()->db->createCommand()
->select($attributes)
->from($model->tableName())
->queryAll();
</syntaxhighlight>

Interacting with the Database

2013-08-08T22:53:44Z

Jake:

[[Category:Development]]
{TODO: CDbCommand, Models, How To's for all sections.}

= Core Structure =

X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

= Raw SQL =
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the software solely with Raw SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria.

= CDbCommand =
CDbCommand [http://www.yiiframework.com/doc/api/1.1/CDbCommand] is a class provided by the Yii Framework which allows for one layer of abstraction from writing raw SQL to run queries. As seen in the documentation, wrapper methods for most SQL commands are available so that a query which may look like: <tt>SELECT * FROM x2_contacts WHERE name='John Smith'</tt> turns into:
<syntaxhighlight lang="php">
$result = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('name=:name', array(':name' => 'John Smith'))
->queryAll();
</syntaxhighlight>
This looks more complicated at first glance, and it is slightly--but it doesn't involve writing any SQL. On top of that, some of the more complicated queries get simpler with this class, and also queries with dynamic information are easier. Let's say I wanted to grab every column except "createDate" from an arbitrary model we don't know the type of. First off, this isn't possible with raw SQL. You need to do pre-processing in PHP to get the query correct. You'd have to loop through all of the attributes, build the select statement, and then lookup the table name and pass that into the string. But for a CDbCommand:
<syntaxhighlight lang="php">
$attributes = $model->attributes;
unset($attributes['createDate']);
$attributes = array_keys($attributes);
$result = Yii::app()->db->createCommand()
->select($attributes)
->from($model->tableName())
->queryAll();
</syntaxhighlight>

Interacting with the Database

2013-08-08T22:53:11Z

Jake:

[[Category:Development]]
{TODO: CDbCommand, Models, How To's for all sections.}

== Core Structure ==

X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

== Raw SQL ==
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the software solely with Raw SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria.

== CDbCommand ==
CDbCommand [http://www.yiiframework.com/doc/api/1.1/CDbCommand] is a class provided by the Yii Framework which allows for one layer of abstraction from writing raw SQL to run queries. As seen in the documentation, wrapper methods for most SQL commands are available so that a query which may look like: <tt>SELECT * FROM x2_contacts WHERE name='John Smith'</tt> turns into:
<syntaxhighlight lang="php">
$result = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('name=:name', array(':name' => 'John Smith'))
->queryAll();
</syntaxhighlight>
This looks more complicated at first glance, and it is slightly--but it doesn't involve writing any SQL. On top of that, some of the more complicated queries get simpler with this class, and also queries with dynamic information are easier. Let's say I wanted to grab every column except "createDate" from an arbitrary model we don't know the type of. First off, this isn't possible with raw SQL. You need to do pre-processing in PHP to get the query correct. You'd have to loop through all of the attributes, build the select statement, and then lookup the table name and pass that into the string. But for a CDbCommand:
<syntaxhighlight lang="php">
$attributes = $model->attributes;
unset($attributes['createDate']);
$attributes = array_keys($attributes);
$result = Yii::app()->db->createCommand()
->select($attributes)
->from($model->tableName())
->queryAll();
</syntaxhighlight>

Interacting with the Database

2013-08-08T22:37:22Z

Jake:

{TODO: CDbCommand, Models, How To's for all sections.}

== Core Structure ==

X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

== Raw SQL ==
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the software solely with Raw SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria.

== CDbCommand ==
CDbCommand [http://www.yiiframework.com/doc/api/1.1/CDbCommand] is a class provided by the Yii Framework which allows for one layer of abstraction from writing raw SQL to run queries. As seen in the documentation, wrapper methods for most SQL commands are available so that a query which may look like: <tt>SELECT * FROM x2_contacts WHERE name='John Smith'</tt> turns into:
<syntaxhighlight lang="php">
$result = Yii::app()->db->createCommand()
->select('*')
->from('x2_contacts')
->where('name=:name', array(':name' => 'John Smith'))
->queryAll();
</syntaxhighlight>
This looks more complicated at first glance, and it is slightly--but it doesn't involve writing any SQL. On top of that, some of the more complicated queries get simpler with this class, and also queries with dynamic information are easier. Let's say I wanted to grab every column except "createDate" from an arbitrary model we don't know the type of. First off, this isn't possible with raw SQL. You need to do pre-processing in PHP to get the query correct. You'd have to loop through all of the attributes, build the select statement, and then lookup the table name and pass that into the string. But for a CDbCommand:
<syntaxhighlight lang="php">
$attributes = $model->attributes;
unset($attributes['createDate']);
$attributes = array_keys($attributes);
$result = Yii::app()->db->createCommand()
->select($attributes)
->from($model->tableName())
->queryAll();
</syntaxhighlight>

Interacting with the Database

2013-08-06T22:56:17Z

Jake: Created page with "== Core Structure == X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow ..."

== Core Structure ==

X2CRM uses MySQL for its database architecture. All tables are prefixed with 'x2_' to differentiate them from any other tables in the database and allow for users to install X2CRM without having to create a database specifically for it. Nearly all tables have an 'id' column which serves as the primary key. Relational data is handled through the x2_relationships table which allows for the specification of model types and IDs rather than through join tables. Tables which are used to store records or other user data generally have associated Model classes to allow for easier data manipulation, while some of the more technical and system data focused tables often have no model record and must be accessed/modified in other ways. There are three ways for a developer to access data stored in one of the tables.

== Raw SQL ==
This is the most simplistic and tedious way to access data. Requires knowledge of the SQL programming language, but allows for the most flexibility and power.

'''Pros'''
* Speed. Using raw SQL is often the fastest way to retrieve data from the database, there's none of the overhead associated with the other methods.
* Flexibility. There are several places in the software which generate a large SQL query using a variety of conditionals to dynamically attach and remove pieces of the query. This sort of flexibility is much harder to attain with the other methods.
* Power. The amount of data and the kind of data you can extract with raw SQL is often much greater than the other methods. There are a variety of MySQL functions which exist that don't really translate well into PHP wrappers.
'''Cons'''
* Difficulty. SQL is notoriously difficult to work with due to poorly documented error messages and very little feedback as to if a query is returning the proper data.
* Messiness. Writing the whole software in SQL would make the codebase look like a mess. SQL queries tend to become lengthy and verbose, and many of the wrapper functions available make the code much cleaner.
* Security. Improperly used SQL can create vulnerabilities in the software. Raw SQL should be avoided for user entered data if possible to prevent SQL injection. The other methods have easier ways of handling this.

Personally I try to use this only when I need something that can't easily be accessed via CDbCommands or Models, or when I need to write a query that will have lots of dynamic parts and doesn't really fit well as a CDbCriteria.

== CDbCommand ==
{TODO: CDbCommand, Models, How To's for all sections.}

Google Integration

2013-07-24T20:05:50Z

Jake:

[[Category:Support]]
Enabling Google Integration will let users into X2CRM using their Google accounts. Furthermore, they will be able synchronize their Google Calendars with content from their X2CRM user calendars, as well as access their Google Drive files.

= Creating an API Project =
To enable Google integration, you will first need to create a Google API project for your X2CRM installation. To do this:
# Go to your [https://code.google.com/apis/console/ Google APIs Console] while logged into your Google account.
# Click "Create Project". You should be directed to the ''Services'' tab.
# Turn on the "Calendar", "Drive", and "Google+" items by clicking on the toggle switch button next to their names and agreeing to the usage terms and conditions..
# Go to the ''API Access'' tab and click "Create an OAuth 2.0 client ID".
# Enter a product name. This is what users will see when they are prompted to allow the application to access their Google account.
# For the type of the application, select "Web Application."
# You should see a section entitled "Client ID for Web Applications". In that section, select "Edit Settings."
# In the ''Authorized Redirect URIs'' box, put in the following three URIs, replacing <tt>domain.name/webroot</tt> with the domain name and web directory where X2CRM is installed:
<nowiki>http://domain.name/webroot/index.php/calendar/syncActionsToGoogleCalendar</nowiki>
<nowiki>http://domain.name/webroot/index.php/site/googleLogin</nowiki>
<nowiki>http://domain.name/webroot/index.php/site/upload</nowiki>
# Furthermore, in the ''Authorized Javascript Origins'' put in the following URI, replacing <tt>domain.name</tt> with the domain name where X2CRM is installed:
<nowiki>http://domain.name/</nowiki>

= Configuring X2CRM =
# In X2CRM, go to "Google Integration" under the '''System Settings''' section of the '''Admin''' page.
# Check the box to enable integration, and paste the Client ID and Client Secret from the "Client ID for Web Applications" on the API Access page of your Google Console.

= Individual User Login =
Each user wishing to log in using their Google account should first go to '''Update Profile''', which can be found in the left menu when they are viewing their profile, and set the '''Google ID''' field to their GMail address. Then, to login:
# Log out
# Click "Login with Google" at the login screen, and follow the link "Login with Google ID"
# Click the necessary button button to permit X2CRM to access your Google account.

Google Integration

2013-07-10T21:24:22Z

Jake:

[[Category:Support]]
Enabling Google Integration will let users into X2CRM using their Google accounts. Furthermore, they will be able synchronize their Google Calendars with content from their X2CRM user calendars, as well as access their Google Drive files.

= Creating an API Project =
To enable Google integration, you will first need to create a Google API project for your X2CRM installation. To do this:
# Go to your [https://code.google.com/apis/console/ Google APIs Console] while logged into your Google account.
# Click "Create Project". You should be directed to the ''Services'' tab.
# Turn on the "Calendar", "Drive", and "Google+" items by clicking on the toggle switch button next to their names and agreeing to the usage terms and conditions..
# Go to the ''API Access'' tab and click "Create an OAuth 2.0 client ID".
# Enter a product name. This is what users will see when they are prompted to allow the application to access their Google account.
# For the type of the application, select "Web Application."
# You should see a section entitled "Client ID for Web Applications". In that section, select "Edit Settings."
# In the ''Authorized Redirect URIs'' box, put in the following two URIs, replacing <tt>domain.name/webroot</tt> with the domain name and web directory where X2CRM is installed:
<nowiki>http://domain.name/webroot/index.php/calendar/syncActionsToGoogleCalendar</nowiki>
<nowiki>http://domain.name/webroot/index.php/site/googleLogin</nowiki>
<nowiki>http://domain.name/webroot/index.php/site/upload</nowiki>
# Furthermore, in the ''Authorized Javascript Origins'' put in the following URI, replacing <tt>domain.name</tt> with the domain name where X2CRM is installed:
<nowiki>http://domain.name/</nowiki>

= Configuring X2CRM =
# In X2CRM, go to "Google Integration" under the '''System Settings''' section of the '''Admin''' page.
# Check the box to enable integration, and paste the Client ID and Client Secret from the "Client ID for Web Applications" on the API Access page of your Google Console.

= Individual User Login =
Each user wishing to log in using their Google account should first go to '''Update Profile''', which can be found in the left menu when they are viewing their profile, and set the '''Google ID''' field to their GMail address. Then, to login:
# Log out
# Click "Login with Google" at the login screen, and follow the link "Login with Google ID"
# Click the necessary button button to permit X2CRM to access your Google account.

Google Integration

2013-07-10T18:46:08Z

Jake:

[[Category:Support]]
Enabling Google Integration will let users into X2CRM using their Google accounts. Furthermore, they will be able synchronize their Google Calendars with content from their X2CRM user calendars, as well as access their Google Drive files.

= Creating an API Project =
To enable Google integration, you will first need to create a Google API project for your X2CRM installation. To do this:
# Go to your [https://code.google.com/apis/console/ Google APIs Console] while logged into your Google account.
# Click "Create Project". You should be directed to the ''Services'' tab.
# Turn on the "Calendar" item by clicking on the toggle switch button next to its name and agreeing to the usage terms and conditions of the Calendar API.
# Go to the ''API Access'' tab and click "Create an OAuth 2.0 client ID".
# Enter a product name. This is what users will see when they are prompted to allow the application to access their Google account.
# For the type of the application, select "Web Application."
# You should see a section entitled "Client ID for Web Applications". In that section, select "Edit Settings."
# In the ''Authorized Redirect URIs'' box, put in the following two URIs, replacing <tt>domain.name/webroot</tt> with the domain name and web directory where X2CRM is installed:
<nowiki>http://domain.name/webroot/index.php/calendar/syncActionsToGoogleCalendar</nowiki>
<nowiki>http://domain.name/webroot/index.php/site/googleLogin</nowiki>
<nowiki>http://domain.name/webroot/index.php/site/upload</nowiki>
# Furthermore, in the ''Authorized Javascript Origins'' put in the following URI, replacing <tt>domain.name</tt> with the domain name where X2CRM is installed:
<nowiki>http://domain.name/</nowiki>

= Configuring X2CRM =
# In X2CRM, go to "Google Integration" under the '''System Settings''' section of the '''Admin''' page.
# Check the box to enable integration, and paste the Client ID and Client Secret from the "Client ID for Web Applications" on the API Access page of your Google Console.

= Individual User Login =
Each user wishing to log in using their Google account should first go to '''Update Profile''', which can be found in the left menu when they are viewing their profile, and set the '''Google ID''' field to their GMail address. Then, to login:
# Log out
# Click "Login with Google" at the login screen, and follow the link "Login with Google ID"
# Click the necessary button button to permit X2CRM to access your Google account.