RCDchannel Support Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 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 ====
  - include necessary javascript files
  - set up form using specified field names and field IDs
  - 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

====Javascript Includes====

====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
<code html>
<input value="" name="company_name" type="text" id="company_name">
</code> \\
  * First Name - the first name of the contact belonging to the company
<code html>
<input value="" name="contact_first_name" type="text" id="contact_first_name">
</code> \\
  * Last Name - the last name of the contact belonging to the company
<code html>
<input value="" name="contact_last_name" type="text" id="contact_last_name">
</code> \\
  * E-Mail - the e-mail address of the contact belonging to the company
<code html>
<input value="" name="contact_email" type="text" id="contact_email">
</code> \\
  * Phone - the phone of the contact belonging to the company
<code html>
<input value="" name="phone" type="text" id="phone">
</code> \\
  * Country - the country code for the country in which the prospective partner is located. See below for more information about standard country codes
<code html>
<select id="countryCode" name="countryCode" onchange="stateWidgetCallback();">
</select>
</code> \\


=== 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
<code html>
<input value="" name="contact_middle_name" type="text">
</code> \\
  * Fax - the fax number of the contact belonging to the company
<code html>
<input value="" name="fax" type="text">
</code> \\
  * Gross Sales - the gross sales of the company
<code html>
<input value="" name="gross_sales" type="text">
</code> \\
  * Total Staff - how many staff members work for this prospective partner
<code html>
<input value="" name="total_staff" type="text">
</code> \\
  * Establish Year - what year was this prospective partner formed
<code html>
<input value="" name="establish_year" type="text">
</code> \\
  * Street 1 - street address of prospective partner
<code html>
<input value="" name="address_street1" type="text">
</code> \\
  * Street 2 - additional street address of prospective partner if needed
<code html>
<input value="" name="address_street2" type="text">
</code> \\
  * City - city of prospective partner
<code html>
<input value="" name="address_city" type="text">
</code> \\
  * State/Province - the code for the state or province of prospective partner. See below for more information on setting up the state/province codes.
  * Postal Code - postal code of prospective partner
<code html>
<input value="" name="address_zip" type="text">
</code> \\
  * Total Locations - total number of locations for the prospective partner
<code html>
<input value="" name="total_locations" type="text">
</code> \\

=== REQUIRED hidden fields ===

The following hidden fields are required in order to save the information to the database:

  * directPostKey
    * if this field is not present on the form, the server will throw an error.  This field is used if a spammer sends too many requests to save this form.  In the event of a spammer using this form too much, you can change this value in the hidden field and also change the associated key in the setup table (directRecruitPost) to match what is used here.  As long as the values match, the form data will be saved.  If there is a spammer with an old copy of this form and this key is different to what is set in the setup table, the form data will not be saved and the server will throw an error.
      <code html><input type="hidden" name="directPostKey" value="authenticated"></code>

=== OPTIONAL hidden field ===

The following hidden field are optional for different outcomes when saving data:

  * saveRecord
    * this field tells the underlying code whether or not to save the record, or just simply display it back to the individual setting up the initial Recruit form.  In order to display the data without saving the data, set this value to 0.  If it is set to anything other than 0, or does not exist, the data will be saved and not displayed.
      <code html><input id="saveRecord" name="saveRecord" value="0" type="hidden"></code>

=== 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: \\
<code html><input type="text" name="custom_1" value="Custom field 1"></code>
<code html><input type="text" name="new_field" value="A new field"></code>
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.

=== Setting Up the Country Code Select Box===

===Setting up the State/Province Code Select Box=== 

====Testing Your Form====

==== Additional information ====

There is also a JavaScript file that you can [[StateCountryJS | copy and paste from here]] in order to have the Country to State/Province filters working.  Copy this code into JavaScript file to be included into your form.

What this JavaScript include will do is that when you select a country, the state/province drop down box will be updated based on the country that is selected.  If there is no State/Province map associated with the selected country, an edit box will be displayed so that the user can manually enter a State/Province.  Currently, it is a manual operation to setup the country to state/province mapping.  [[StateCountryMapping | Click here]] to view an example and explanation of the way this mapping needs to be created.

There is also a setup function and a method to check that all the required fields are filled in before attempting to save the information.  The setup method works in conjunction with the Country to State/Province map as it sets up the drop down box to call the above mentioned method when ever a new Country is selected.  View [[RC-includeExample| sample code here]] to see how the required fields are tested for values and how the Country drop down select box is set to call a method when ever a new Country is selected.
RCDchannel Support Wiki

User Tools

Site Tools

Page Tools
