====== Recruiter Integration Guide ====== The ChannelSUITE Recruiter function helps facilitate and organize your partner recruiting efforts. It provides a list of open “in process” partner recruit applications, along with useful features for collecting and organizing data on each recruit. When a recruit is approved, the data is used to create a new Partner record in channelADMIN, along with a new Location record and a new Contact record. Historical data for both approved and rejected recruit applications is available. ==== Technical Overview ==== The approach is this: you supply a "Join our Partner Program" form on your website, and POST the form to our server. The information entered on the form will then be stored and placed in the queue of prospective partners. There are certain required fields (see "required fields" below) that we require in order to get the process started. There are optional fields that are available to you if you want to capture extra information about the prospective partner (see "optional fields" below). View [[RC-example| sample code here]] for a form that utilizes all fields available. There are also required hidden fields that need to be added into the form in order for our server to be able to process the information. ==== Integration Steps ==== - request a free directRecruitPost key from your channelSUITE account manager - include the necessary javascript files - set up form using specified field names and field IDs - add the hidden yourEmail field to the form to discourage spambots - set the form ACTION to send form submissions to your channelSUITE install - test the form using the built-in test mode - turn off test mode more details on these steps are shown below ====Javascript Includes==== several javascript files are needed to set up client-side validation and the country-specific state/province select box. all the files can be loaded from the channelsuite server as shown, or if you prefer you can download the files and host them on your server. //Note: The stateProvinceMap technically contains dynamic data, but it only changes if support for states/provinces is added for an additional country in your channelsuite database, so in practice you may treat it as a static file.// add this in the section of your html

====Form Contents==== === REQUIRED fields === The following fields are required in order to create a prospective partner: * Company Name - the name of the company looking to become a partner

\\ * First Name - the first name of the contact belonging to the company

\\ * Last Name - the last name of the contact belonging to the company

\\ * E-Mail - the e-mail address of the contact belonging to the company

\\ * Phone - the phone of the contact belonging to the company

\\ * Country - the country code for the country in which the prospective partner is located. See below for more information about standard country codes. //Note: the "onchange" event handler is only required if you use a state/province field in your form (recommended if you recruit in US or Canada)//

\\ === OPTIONAL standard fields === Severeal standard fields are optional, and may be used to record more information about the prospective partner. You may also define your own fields (see the Custom Fields section below). The optional standard fields are: * Middle Name - the middle name of the contact belonging to the company

\\ * Fax - the fax number of the contact belonging to the company

\\ * Gross Sales - the gross sales of the company

\\ * Total Staff - how many staff members work for this prospective partner

\\ * Establish Year - what year was this prospective partner formed

\\ * Street 1 - street address of prospective partner

\\ * Street 2 - additional street address of prospective partner if needed

\\ * City - city of prospective partner

\\ * State/Province - the code for the state or province of prospective partner. Leave an empty element with ID "statecell", this will be filled in dynamically by the stateWidget javascript. See below for more information on setting up the state/province codes.

* Postal Code - postal code of prospective partner

\\ * Total Locations - total number of locations for the prospective partner

\\ === REQUIRED hidden fields === The following hidden fields are required in order to save the information to the database: * directPostKey * The value of this field must match the directRecruitPost key assigned to you on the server. Please ask your account manager to get you a "Recruiter direct Post Key". === OPTIONAL hidden field === * saveRecord * this hidden field is used for testing your form. when this hidden field is set to 0, submitted form contents are echoed back to the screen and are NOT submitted to the channelsuite recruit database. if this field doesn't exist or is set to any value other than 0, the form is processed normally. * source * this field is used when you have multiple public forms submitting new recruit records. once a form is submitted, the forwarding URL is retrieved from the recruitDirectPostThankYouURL setting in your channelSUITE configuration. the source variable is then appended to this URL as a parameter so that your public web site that processes this URL can distinguish from which page this recruit has been submitted. an example of how this URL would look with the source attached is as follows: \\ if your config setting is: recruitDirectPostThankYouURL = 'http://myPublicWebsite.com/recruit_return/' and your form's source variable is set in a hidden field like this: then after submitting the form, the user will be redirected to this URL on your site: http://myPublicWebsite.com/recruit_return/?source=publicSite1 === CUSTOM fields === In the even that you want to capture more information than the fields outlined above, you can also add in your own custom fields which will be saved into the Comments field in the table. Should you have two custom fields, namely: \\ The following will be appended to the Comments field: \\ custom_1: Custom field 1 \\ new_field: A new field \\ \\ The name of the field will be entered first, followed by a colon (:) and then the value the user entered. Any of these extra fields will be added to the end of any existing Comments already entered. A new line will separate multiple user defined custom fields. === Anti-spam: the 'comments' hidden field === Forms on public websites are often targets for "spambots" -- automated "spiders" that wander around the web looking for forms. The spambot puts its irrelevant message in whatever fields it can find, and submits the form in the hopes that the posted content will show up somewhere where it will be seen. These submissions would show up as bogus entries in your recruit database. Quite annoying. Spambots aren't very sophisticated, and they can be effectively defeated by using a "captcha", the most common example being to ask your users to type in the text from a distorted text image. This works, but it's irritating to your users. We're using a simpler method called a "honeypot". We add a field to your form that users can't see, but that the spambots can't easily identify as a hidden field. The spambots will typically insert content into this field. If the field isn't empty, it's usually a spambot submission, and we reject it with an appropriate error message. It contains a label that instructs users of alternative browsers (handicapped-accessible screen readers, for example) to leave the field empty. This method is very effective, and causes no problems for legitimate users. To implement the honeypot, simply add the following hidden span containing the empty field 'comments' in your form:


                          
			     
			     Ignore this text box. It is used to detect spaambots.
			     If you enter anything into this text box, your submission
			     will be rejected.

Note: prior to October 2010, the form element name for the honeypot field was 'yourEmail'. This was deemed problematic because some automatic form population tools (like the one built into the Google Chrome browser) were over ambitious and were putting an email in the honeypot field as well, generating false positives. === Setting Up the Country Code Select Box=== Channelsuite uses a normalized list of standard country codes. Using these same codes in the Recruit form allow us to easily convert recruit applications to Partner records after they've been processed and approved. The list of country codes used in your channelSUITE install can be found by running the "country list" API as described in [[api_helper_functions]]. Just copy and paste this list of html