Categories

Follow our news:

Follow canonburysvcs on Twitter Follow Canonbury Services on Facebook Follow Canonbury Services' news by RSS Follow Canonbury Services' news by Atom Follow Canonbury Services' news by email

NEWS & TECH BLOG

Using web imports

05/11/2012 – in Techniques

GoldMine has had the ability to import data from web forms for many years now. Not many people make use of this feature though, mainly because it is perceived to be at the complicated end of spectrum.

It’s actually pretty easy, and is a very useful tool. You can create new records, update existing ones and fire off automated processes. It’s useful for lead capture and (admittedly fairly limited) self-service support.

The Email

The key to it all is sending GoldMine an email in a very precise format. And, because GoldMine is simply responding to an email, then it’s very easy to test just by manually creating an email that has the correct ‘to’ address and the correct format.

Here’s how it’s done:

Firstly, you need to enable the Web Import options under the ‘advanced’ tab of your email preferences.

Next, you need to make sure that the emails are sent to a very specific address. If your normal email address is:

fred@somewhere.com

then you would need to send the emails to:

{$GM-WEBIMPORT$} fred@somewhere.com.

It is the {$GM-WEBIMPORT$} part that tells GoldMine to intercept the email and to treat it as a set of instructions.

The subject line can be anything.

The next thing to think about is the format of the email. Here is a simple example:

[Instructions]
DupCheck1 = Company
DupCheck2 = Contact
DupLogic = AND
SaveThis = Web Import
OnNewSendGMEmail = ROB,New submission
OnDupSendGMEmail = ROB,Duplicate submission
OnNewAttachTrack = My_AP1
OnDupAttachTrack = My_AP2
Password = 1234

[Data]
Company = Another test 4
Contact = Test person 3
EMail = fred@test
Address 1 = 10 Gasworks Rd
City = Aberdeen
Zip = AB1
USERDEF01 = 1234

[Contsupp]
CS1_rectype = P
CS1_contact = Website
CS1_contsupref = www.awebaddress.com

CS2_rectype = A
CS2_contact = Bill
CS1_contsupref = Accounts person

The [Instructions] section tells GoldMine what it should do with the information:

1. In this case it is going to check Company and Contact together (‘AND’) to see if the record already exists. You could replace AND with OR if you like, and can use any of the fields in the [data] section for duplicate checking. Whether or not fields on the existing record will be updated if a match is found depends on settings in GM.INI (see below);

2. It is going to save the contents of the email as a history record against the new or matched record with a reference of ‘Web import’;

3. For both new and matched records it is going to send an internal GoldMine message to the user ROB with an appropriate subject line. These messages will be automatically linked to the record;

4. It is going to attach one of two automated processes (given by name) depending on whether it is a new or matched record;

5. It is going to use a password to prevent bad lads spamming us. This password matches an entry in GM.INI.

Being able to attach automated processes gives us a lot of scope; for example, these processes may be a sequence of lead-follow-up events or they may create a new case in the service centre.

The next section is [Data]. These are the fields on the record that you want to populate. Nothing complicated there.

The [Contsupp] section is a little more involved. Using it, you can create details and/or additional contact entries. Each entry (numbered 1 to 8) must specify the contsupp rectype and other relevant fields. To use this successfully you must have a good grasp of the way that GoldMine holds and uses this information.

Obviously you don’t have to use all of the options! If you’re not collecting contsupp data, don’t have a [contsupp] section. Likewise for automated processes etc.

The web import password and record update settings may be set in Web > Set Up Web Import.

Once you’ve tested your email by sending it manually then you can have your webform create it for you.

GM.INI

There are some entries required in the GM.INI:

[WebImpPassword]
Password=XXXX
[WebImportOverwrite]
IAgree=I Want To Allow Fields To Be Updated By WebImport
Fields=KEY2, KEY3, KEY5, ADDRESS1, ADDRESS2, ADDRESS3, CITY, STATE, ZIP

The password must match the password in the incoming email.

If you want fields on existing records to be updated when a match is found then you have to do two things:

1. The IAgree entry must appear exactly as above, and

2. you must specify the fields that you will allow to be updated. If a field is not in the list then it is protected.

The Web Form

Web forms have two parts: a page of HTML which determines the field layout etc and which gathers input from the user, and a script file which processes the information and sends the email. The script may be written in any one of a number of scripting languages such as PHP, PERL, ASP etc. Your choice of language will often be determined by your web server and whether it’s running on Windows or Linux.

Setting up forms and creating emails from those forms is something that your web developers should be able to do for you, following the guidelines above. It doesn’t actually matter what they do, or how they do it, as long as the resulting emails follow the rules.

A very simple example form, with an associated ASP script suitable for use on a Windows web server, can be found at the bottom of this post.

Using The Wizard

The Web > Set Up Web Import menu can take you through a wizard which will return both a functioning form and an associated script file in the language of your choice. On the one hand this can be a great time saver but, on the other, it can reduce the process to one of ‘ooh…black magic!’. Use it by all means, but I think that it’s still important to know how it all works under the bonnet.

Personally my preference is still to create the form and script manually. That way I know exactly what’s in there!

Download example webform.zip

Share