Placeholder

Customer Forum

Raising Workbooks Cases using Web2Case - a worked example

Workbooks Support Posted: 2011-11-17 16:34

It's a common requirement to be able to put a form on your website to capture a new support case. Fortunately the tools are there in Workbooks to make this straightforward. There are a number of steps to the implementation which are outlined here. The end result is a neat form: take a look at http://www.workbooks.com/support which uses these techniques.

Alongside this implementation you might also want to update cases when an email is received which references the case reference: a forthcoming article will explain how to do this.

Step 1: Create a web key

You need to identify a user who will be the 'creator' of cases created through this web2case form, and a decide where to assign such cases. Typically you'll have a distinct user which is used for all your web and API integration - call it "Website Integration" perhaps. You probably want a case queue called something like "Support": subscribe members of the customer support team to this and they will get notified when cases are added to it. 

With this information you can go to Configuration > Email & Web > Web Integration, use the New Case Key button to create a Web Case Key.

See also: Knowledge Base article.

Step 2: Create custom fields

Go to Configuration > Customisation > Custom Fields and create two new fields for Cases:

  • Submitter - a text field which will contain the name the submitter of the case will enter on the form.
  • Submitter Employer - what the submitter claims is there employer; again this is a text field.

These fields are needed because you do not want to expose a picklist of all your users or customers on the web form: it's public!  Instead the web2case system will notice when an email address is entered which matches someone in your Workbooks account and link the created case to that person as the Primary Contact for that case. If no match exists then the primary contact is left blank but the two custom fields will contain the user's claimed name and employer.

Step 3: Create and customise your form

Click on the Form button on the Web Case Key page. This downloads a web form which generally has many more fields than you want to invite your user to fill in, and omits a couple of fields you might expect to be there. You will need to edit the form so it meets your requirements: add style, javascript validation and remove fields and picklist options. Fields which are marked as "Required" must be submitted with the form so if you don't want to show these to the user make them hidden fields and give them a value: for example the "Source" field may always be set to "Web" for cases raised via this form.

JQuery validation is a great way to ensure your user completes fields: just add "class='required'" to each input tag.

It's a good idea to use some JavaScript to stop the user attempting to submit the form twice: users often double-click on submit buttons and you only want a single case to be created.

Add some introductory text to the form explaining who you expect to use it and what they can expect when they create a case: when will you respond to it? 

More detail here in the Knowledge Base.

Step 4: Create your success and failure pages

The success page is shown when a case was created successfully and should report the case reference number back to the user, together with an indication of "what happens next". To report the case reference number you need a little bit of code to take the case reference number from the query string - if you use PHP it would be something like this:

 

<h1>We have created <?php 
  $case_reference = $_GET["case_reference"];
  echo $case_reference;
?></h1>

<p>We have received your case and will start work on it 
shortly.</p>

<p>To send us more information about this case, please 
  use <a href="mailto:support@workbooks.com?subject=<?php 
  echo $case_reference ?>">this link</a> to send us an email including 
  the case reference: <?php echo $case_reference ?>.
</p>

 

The failure page is a little simpler - the case creation failed; this is unexpected. It's possible there was a problem with the validity of some of the input data so it's simplest to show a page inviting the user to go back and try again. A little JavaScript helps:

 

<h1>Whoops: A new Workbooks support case could 
  not be created</h1>

<p>We could not create a new support case. 
  Something went wrong - we are sorry about that.</p>

<p>Please go 
  <a onclick="history.back();return false;" href="#">back</a> 
  to the form, check your input, and try again.</p>

 

That's all you need: test and away you go!