Documentation
Documentation
This is an old revision of the document!
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.
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 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.
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 <head> section of your html
<!-- CHANNELSUITE REQUIRED --> <script type="text/javascript" src="http://yourChannelsuiteURL/API/js/prototype.js"></script> <script type="text/javascript" src="http://yourChannelsuiteURL/API/js/recruiterForm.js"></script> <script type="text/javascript" src="http://yourChannelsuiteURL/API/js/stateProvinceMap.js.cgi"></script> <script type="text/javascript" src="http://yourChannelsuiteURL/API/js/stateWidget.js"></script> <!-- end CHANNELSUITE REQUIRED -->
The following fields are required in order to create a prospective partner:
<input value="" name="company_name" type="text" id="company_name">
<input value="" name="contact_first_name" type="text" id="contact_first_name">
<input value="" name="contact_last_name" type="text" id="contact_last_name">
<input value="" name="contact_email" type="text" id="contact_email">
<input value="" name="phone" type="text" id="phone">
<select id="countryCode" name="countryCode" onchange="stateWidgetCallback();"> <option> tags go here, see below </select>
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:
<input value="" name="contact_middle_name" type="text">
<input value="" name="fax" type="text">
<input value="" name="gross_sales" type="text">
<input value="" name="total_staff" type="text">
<input value="" name="establish_year" type="text">
<input value="" name="address_street1" type="text">
<input value="" name="address_street2" type="text">
<input value="" name="address_city" type="text">
<span id="statecell"></span>
<input value="" name="address_zip" type="text">
<input value="" name="total_locations" type="text">
The following hidden fields are required in order to save the information to the database:
<input type="hidden" name="directPostKey" value="someRandomKey">
The following hidden field is used for testing your form:
<input id="saveRecord" name="saveRecord" value="0" type="hidden">
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:
<input type="text" name="custom_1" value="Custom field 1">
<input type="text" name="new_field" value="A new field">
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.
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 <option> tags (or a subset if you don't recruit globally) into the countryCode <select> container.
If you recruit in countries such as US and Canada where states or provinces are commonly used, you'll want to use the channelSUITE list of normalized stateProvinceCode values for that country. But this is even trickier than the countryCode select box, since the list of states/provinces is country-specific. The good news is, all the steps necessary to make this work have already been covered above:
Now your form will dynamically provide the correct state/province field options for the chosen country, based on the list of supported countries in your copy of the channelSUITE database.
set the hidden field saveRecord value=0 and submit. you should see the correct form values echoed back. make sure to check that the state/province field options look right for countries that use standard states or provinces (by default we support US, Canada, and Mexico, but you may request others). when you're ready to go live, change saveRecord to value=1.