Placeholder

Customer Forum

Email to Case

Workbooks Support Posted: 2012-01-29 22:09

It's straightforward to set up Workbooks to create new cases, and update existing cases, via email. The idea is that users can send an email to a support email address, the email is logged in Workbooks, and an acknowledgement email is sent back to the user.  Here we'll outline the steps you'll take to implement this for yourself.

There is an Email to Case script provided in the Workbooks Script Library. It checks an email account held on an IMAP-capable email server (most email servers, including MS Exchange and Lotus Notes, support IMAP) and, if there is email:

  • Copies the email into Workbooks.
  • Either finds an existing case or creates a new one.
  • Links the email to the case.
  • Ensures the case has an appropriate status.
  • Notifies the originator of the email as appropriate, including the case number.
  • Moves the email into an archive folder.

When a user replies to the acknowledgement email the case number is included so the reply also ends up associated with the case; and the case is flagged for attention.

To set this up, first go to Configuration > Automation > Processes. Click the button at the top to create a "New Scheduled Process".

Set the script to "Script Library" > "Email to Case". Set the process to run as frequently as you want, and ensure that it is running as the Automation User. Do not enable the process yet.

email2case.png

Save the new scheduled process - you should then see the 'Parameters' tab. Navigate to this tab and set values for each parameter: 

 

  • Alternate Case Prefix - Fill this in if you previously used a different system and still receive cases that contain the ticket references for that system. You should add the whole prefix, including any colons or dashes.
  • Case Prefix - Only fill this in if you have changed the standard Workbooks Case prefix to be something other than CASE. The script uses this prefix to identify when an email should be added against an existing case with a matching case reference.
  • Case Received Status - The status that a case should change to when it has been updated with a new email, for example, we use 'Email Received'. If left blank, the process will use 'In progress'.
  • Create Case Priority - set this to the relevant priority if appropriate. Usually we would advise that this is left blank so that cases can be triaged manually.
  • Create Case Product Category - The Product Category that should be set on a new Case. Usually this parameter is not set, as each case may have a different category - unless perhaps you are setting up multiple Email to Case processes for multiple mailboxes, and each mailbox is for a specific category.
  • Create Case Queue - The name of the Queue or User that new cases should be assigned to.
  • Create Case Type - The Case Type that should be set on a new Case.
  • Created Acknowledgement Email - The body of the email that should be sent to a customer when their email creates a new case. We would advise leaving this parameter, and instead use the Created Template Name parameter.
  • Created IMAP Archive Folder - The folder to move emails if the email caused a new case to be created, e.g. 'Case Created'. If this folder does not exist, the process will create a new one with the name set in this parameter.
  • Created Template Name - Create an email template for the email that you want to send out when a new case is created. This will supersede anything that has been set in the Created Acknowledgement Email parameter. Ensure that you choose to create the template for a specific record type (Case) and do not create a 'Simple' template. Include the placeholder for the Case reference @object_ref@ within the Subject of the email.

    email2case-email-template.png

  • Email Disposition No Case - Here you can control what we do with an email if it does not relate to an existing case. Set the parameter to 'create' if you want the process to create a case for every new email that is not already associated with a case, or set it 'move' if you want to deal with each new email manually.
  • IMAP Flags - If you are using SSL connections, set this to '/novalidate-cert/ssl', else leave it blank. (For more information about setting flags with the PHP imap_open function, see here)
  • IMAP Folder - Set this to the name of the mailbox folder that the process should collect emails from. Normally this is set to INBOX, but if you have automatic rules set up that move emails into different folders, you may want to instead point the process at one of these. This also means that, if this mailbox receives a variety of emails, you could have a folder called 'Create Case' which you manually drag any relevant emails into, and the process can pick them up and create the case for you.
  • IMAP Host - the DNS name or IP address of the IMAP server the process should connect to, e.g. imap.mymailserver.com
  • IMAP Password - the password required to log into the mailbox - this should correspond with the username specified in IMAP User.
  • IMAP Port - The TCP/IP port number of the IMAP server. This is normally 143, or 993 for SSL connections.
  • IMAP User - the username of the user we are logging into the email server as. This may be in the form of an email address or in the format DOMAIN\username - check with your email providers if you are unsure.
  • Largest Message Size - the largest size of an email that can be copied into Workbooks. This should be an integer number which represents the size in bytes. Any emails larger than this will not be copied into Workbooks, and instead a placeholder will be used. The largest email size that can be created in Workbooks is 16MB (including attachments)
  • Mail From - the email address that any automatic responses are sent from. Ensure that there is an Email Account set up in Workbooks for this email address. This will normally be the same as the IMAP account, so that replies to automated emails are still picked up and attached to Cases by the Email to Case Process. If different, this can cause email loops with the automated responses - you may need to use the 'Notification Suppression Regex' parameter to avoid this.
  • Notification Suppression Regex - This parameter is optional. Fill it in if there emails that you receive that should not get an automatic response, for example, 'Out of Office' emails, as this can cause a loop. When setting this parameter, ensure that it starts and ends with a forward slash. If there are multiple options, separate them with a vertical slash |. For example, '/Mail delivery failed|Out of office|Automatic response/'
  • Processed IMAP Archive Folder - The folder to move emails to if a case with neither created nor updated, for example, if there was an error. Any emails that are moved to this folder will need to be dealt with manually.
  • Update Case Queue - Set this to the name of the User or Queue if you want Cases to be reassigned when they get updated by a new email. Leaving this parameter blank will mean that the case stays assigned to the current assignee.
  • Updated Acknowledgement Email - The body of the email that should be sent to a customer when their email updates an existing case. We would advise leaving this parameter, and instead use the UpdatedTemplate Name parameter.
  • Updated IMAP Archive Folder - The folder to move emails if the email caused an existing case to be updated, e.g. 'Case Updated'. If this folder does not exist, the process will create a new one with the name set in this parameter. This can be set to the same as the Created IMAP Archive Folder if you want them to be moved to the same folder.
  • Updated Template Name - Only set this parameter if you want automatic emails to be sent when an existing case is updated. Create an email template for the email that you want to send out when an existing case is updated. This will supersede anything that has been set in the Updated Acknowledgement Email parameter. Ensure that you choose to create the template for a specific record type (Case) and do not create a 'Simple' template. Include the placeholder for the Case reference @object_ref@ within the Subject of the email.

If you have Office 365 multi factor authentication enabled for the user that the process is running as please make sure their email has been set up in Workbooks correctly and is using an App Password instead of their normal Office 365 password. You can find out more about setting this up here.

Having set the parameters, enable the process and wait for the process to run. You should see logs appear in the Process Logs area. Each time the script runs a record is created here.  If there are errors you can find out what is going wrong by reviewing the log; perhaps a username or password is incorrect. Contact Support if you do not understand the error message.

That's all there is to it.