Let the platform do the work
SugarClubContact+1 (877) 842-7276

External Lead Form Mapping

Overview

This page explains how to map external lead forms from Sugar Market to your external CRM.

Design Considerations

When designing an external lead form with a checkbox or dropdown lists for questions, ensure the form meets the following requirements:

  • Identifies the field you are mapping to in Sugar Market.
  • Multiple selections are separated with semicolons when passing the data through to Sugar Market.
  • The dummy landing page question for the specific field can remain an EditText field type since we are just capturing the information sent to Sugar Market.
  • The thank page you direct the recipient to needs to include the Sugar Market web tracking script since this will tie the record and the web activity together.
  • To push this data to an external CRM, ensure that the field is synced down into Sugar Market, preferably as a picklist or a checkbox list field type to ensure data integrity. You should also consult with your external CRM Administrator to confirm you are using the correct return values for these fields. 

Note: The checkbox or dropdown list configuration on your website is determined by your web developer. Sugar Market is simply accepting data sent through the lead form script. 

Capturing Information from Lead Forms

Lead forms allow marketers to use existing forms on their website to capture the information in Sugar Market and still take advantage of landing page features. Information will be visible in Landing page reporting and in the Buyer's Journey. 

Creating a Dummy Landing Page

This is an optional step but is required if you want to use any landing page features and it acts as a repository for your form submissions. Without this step, form data will go directly into the CRM.

Note: Dummy landing pages can only be created with the legacy landing page builder.

  1. Use the Legacy Landing Page Builder to set up the framework of your landing page.
  2. Create a single-page dummy landing page.
  3. Make an exact replica of your web form question on the Questions tab. You must map fields to something to have them captured on a Lead Form. The field does not need to go to your external CRM, but it must be mapped within the Sugar Market CRM.
  4. Skip any HTML formatting on the Content tab since customers will be interacting with your web form, not these landing pages.
  5. Most website-hosted forms use their own logic to route to a Thank You page. Ensure that Page 1 is identified as the final page in the page properties. Having a second page prevents page completions from registering. 

Creating the External Form

  1. From the user menu, click "Admin".
  2. In the Administrator section, within the Marketing Administration tab, click "External Form Connector".
  3. Click the New button.
  4. Enter the lead form details, and then click the Next button. The location should be the URL of the web form. Although this is an optional field, it is highly recommended to help you easily identify these forms.
    externalFormConnectorStep1
  5. Establish your form options, and then click the Next button. Choose to cookie the contact, overwrite/update contact or lead data, or push the information to an external CRM.
    externalFormConnectorStep2
  6. Set actions for your externally hosted form submission, and then click the Next button. Specify the redirect URL, which determines the page your visitors are taken to after submission, assign the lead to a specific person, add the visitor into an email campaign, or push the data into the Dummy Landing Page created above.
    • To use the landing page's round-robin or Geo feature, select "All Users" as the contact and the Dummy Landing Page's lead routing will take over.
    • If you select a trigger campaign in the lead form builder, make sure that the same campaign is not configured in your Dummy Landing Page next page logic since it might send duplicate messages.
    • If you set up a Dummy Landing Page, push to the landing page and select the landing page created for the lead form.
      externalFormConnectorStep3
  7. The pre-built columns in your Dummy Landing Page will automatically populate the selected columns box. If you need to add more fields, first add the fields to the Dummy Landing Page, and then run through the lead form builder again to update the fields.
    externalFormConnectorStep4
  8. Confirm your selections on the Review page.
    externalFormConnectorStep5
  9. Select the type of form submission method your web developer prefers. Copy the code and provide it to your web developer. 
    legacyFormsCode00

You can send your data via an External Lead Form to Sugar Market by any of these request methods: GET, POST, REST URL. The method you choose should be determined by your web developer's preference. These request methods will act as a bridge between how you want to generate the data and how you want to send the data to Sugar Market.

HTML coding, webhooks, Wordpress, Gravity Forms, and Drupal are common methods used to insert data into your preferred request method with Sugar Market. The method you choose to insert data into the request methods that Sugar Market uses (or any other request methods) should be determined by the web developer's knowledge of that platform and the capabilities of the platform. Captchas, styling, or any other formatting will be handled by your web development team on your chosen platform. These request methods are simply like an open envelope with a Sugar Market return address for you to fill with data and send to Sugar Market.

Note: Any edits made to fields (additions, deletions, etc.) will need to be updated in the Dummy Landing Page as well as the lead form code.

Parameter Definitions for External Lead Forms

To connect forms you have built externally to Sugar Market through HTML code embedded on your page, use the External Form Connectors Builder.

Obtain the HTML code to place on your page in Step 6 of the External Form Connectors builder:
legacyFormsCode0

These code blocks include the set of parameters described in detail below.

Note: Not all parameters will be present upon generating the lead form script since they will vary depending on what you selected in the lead form builder.

Parameters for Form Builder

Customer ID Parameter

This parameter will auto-populate your customer ID in the value. Please do not edit the value from what is generated in your instance. The following code uses an example ID for the value parameter.

    <input type=hidden name="Customer" value="ch000099999eArad">

This parameter will determine if we cookie the person that filled out the form. Change the value accordingly if you want the form to cookie the user upon submitting the form on your page:

  • value="1" means user will be cookied.
  • value="0" means user will not be cookied.
    <input type=hidden name="cke" value="1">

Legacy Landing Page ID Parameter

This parameter determines which Landing Page ID (Dummy Landing Page) the external lead form will be associated to. Replace the value with your Landing Page ID. It is highly recommended that you create a dummy landing page to associate to the external lead form.

    <input type=hidden name="DialogID" value="152">

Redirect URL Parameter

This parameter is used as a Redirect URL. After users submit the form, they will be taken to the specified URL on your website, such as a Thank You page.

    <input type=hidden name="rurl" value="http://www.custom-website.com">

Parameters for Form Builder and External Form Connectors (Legacy)

GET Method Parameter

This parameter will perform a GET method: 

    <META HTTP-EQUIV="Content-type" CONTENT="text/html; charset=UTF-8"> 
<form action="https://www.msgapp.com/RESTForm.aspx" method="GET">

To use a POST method instead, use the following form action:

    <META HTTP-EQUIV="Content-type" CONTENT="text/html; charset=UTF-8">
<form action="https://www.msgapp.com/RestPostForm.aspx" method="POST">
Trigger Email Parameter

This parameter will associate the external lead form to the CampaignID. Upon completion of the external lead form, the client will receive the trigger listed. Replace the value with your TriggerID.

    <input type=hidden name="TriggerID" value="70">
CRM Push Parameter

Value 0 = False: It will not be pushed to the external CRM when the record is inserted/updated inside Sugar Market.

Value 1 = True: It will insert or update the record in the external CRM when the record is pushed to Sugar Market.

    <input type=hidden name="PushExternal" value="0">
User ID Parameter

This parameter is the UserID that will be assigned as the owner of the record for a new lead. In the following example, all new leads will get assigned to UserID = 1. To change this to a different default owner, then navigate to the User menu > Users to locate the OwnerID for the user.

    <input type=hidden name="ownerid" value="1">

Note: If you have chosen to link this external lead form to a dummy landing page and want to use the lead routing feature within the dummy landing page, then UserID must equal 0.

Overwrite Existing Contact/Lead Parameter

This parameter will allow you to determine if the contact or lead record should be overwritten if the contact or lead already exists. By default (Value = "0"), the lead form will always overwrite the current record. By changing the value to a 1, this will check each individual field. If the field has data, it will not overwrite the data. If the field does not have data, then it will update that data. If this checkbox is unchecked, then it will always overwrite the data.

    <input type=hidden name="overwrite" value="0">;

Ajax Form Code For Lead Forms

Sugar Market RESTful Form Submission

Endpoint:

  • US: http://www.msgapp.com/Forms/Restful.aspx
  • EU: http://wwweu.msgapp.com/Forms/Restful.aspx

 If you have a CNAME set up, you can point your submissions to <CNAME>/Forms/Submission.aspx.

You can make a GET or POST call to the endpoint. If using GET, all parameters must be query string encoded. If using POST, your Content-Type header must be application/x-www-form-urlencoded, and your payload must be a URL encoded representation of the data.

Defined Parameters

The parameters identified as required below are needed to process the submission. The omission of these requirements will result in failure. All parameters are case-insensitive.

  • Customer (required): Must be the LinkID implementation of the customer. To retrieve a valid customer LinkID, create an External Connector Form and use the parameter value in the created form.
  • Email (required): All submissions require a valid email address. Invalid email addresses will cause the submission to end. Lead/Contact records are matched by email address, so a record with this email address as its primary email address will be updated.
  • Overwrite Integer parameter to determine if the visitor's submission should overwrite data if a record already exists in Sugar Market. "0" or a missing parameter will cause an overwrite. "1" or any number other than "0" will prevent an overwrite. If the field is empty, or is a non-integer value, the contact/lead information will be overwritten.
  • TriggerID: The ID of the Trigger Email Campaign you want to send the user on a successful form submission. 
  • DialogID: The ID of the landing page to connect to the submission. Without this parameter, there will be no records of the submission created, the data will just be added to the lead/contact record. A successful connection to a landing page will allow you to use the landing page's reporting and submission actions, and will show a form submission in the lead/contact's Buyer's Journey. For more information, see below.
  • PushExternal: Indicates whether to push the submission data to your external CRM, if you have one. A value of "1" will update the lead/contact record if it already existed in the external CRM, or will create a record in your external CRM if one did not exist. Anything else will not activate the external CRM sync.
  • Cke: Indicates whether to cookie this visitor after a successful submission. "1" indicates to cookie the visitor. Anything else will result in a non-cookied submission. There are two requirements for this parameter to work successfully:
    • You must set your JavaScript code to set the withCredentials flag to "true".
    • The Origin of your submission must come from a website whose host ends with the Sugar Market-registered domain name for the customer (i.e. the Origin header for the request must meet this requirement). For example, if your Sugar Market domain name is axiomfire.com, the following would be valid Origins: http://axiomfire.com, http://test.axiomfire.com, http://newaxiomfire.com, https://forms.axiomfire.com. An invalid Origin for this example is: https://www.axiomfire.net.
  • OwnerID: The Sugar Market ID of the user to assign to the lead/contact if the record did not exist before this submission. If a value for this parameter is not provided, then the account's primary user will be assigned the new lead.
  • Company: This field is usually filled by a visitor. If a lead/contact is created, Sugar Market will look for an account with a name that matches the value of this parameter. If a match is not found, then an account record will be created with the value of this parameter as its name and the account (whether retrieved or new) will be assigned to the new lead/contact.
Other Parameters

You can add as many fields as you want to the form submission. The server will attempt to match all parameters to lead/contact fields, with the exception of the ones identified above and a few Sugar Market reserved parameters. If a match is found, then the lead/contact field will be updated with the information provided. Matches are not case-sensitive. Example fields are FirstName, LastName, City, State, and Country. If a match is not found for a field submission, then the data will be lost unless that field becomes a match for the landing page you connected to your submissions (if you connected a landing page through the DialogID parameter).

Landing Page Connections

Connecting a landing page to your RESTful form submissions allows you to take advantage of the features available to landing pages. To successfully connect a landing page to a RESTful form submission, the landing page must meet the following requirements:  

  • You must have a form.
  • This form must be set to be the Start Form of the landing page.
  • This form must be set to be a Final Page.

You can add any other landing pages to the form submission, but the connection will never be processed correctly. In case of user error, data will not be completely lost. When connecting a landing page, the server will attempt to match the submission to the landing page's form fields. It will match parameter names with form field names in order.

  • The columnMap of the form field (i.e. the lead/contact field), or
  • The Form Field Name

If a match is not found for a form field, then the form field will be recorded as empty for the submission.