How To: Use DECODE in Email Manager

1 What are decodes?
- 1.1 Examples of Decodes
  - 1.1.1 Example One - Matching one parameter
  - 1.1.2 Example Two - Matching two parameters
2 Example of using Decodes to add courier information to an email
- 2.1 Create the Email Template
- 2.2 Create the Email Trigger Rule
3 Testing
- 3.1 Royal Mail
4 See Also

Using Decode in Email Manager is an Advanced User feature.

Please read the whole of this page before attempting any DECODE in the Email Manager.

What are decodes?

Decodes allow advanced users to add IF statements or conditional text. The conditional expression is formatted in XML and then interpreted by Khaos Control.

Examples of Decodes

The following examples can be included in your message template.

WARNING: The DECODE tag itself must all be included on one line within the email message template. We have split it onto different lines so you can see how it is constructed

WARNING: The decode scripts do not accept & (Ampersand) as a viable character, any use of this character in your Courier Code, Courier Desc, etc. Must be removed. Leaving this character in will result in errors.

Example One - Matching one parameter

This example, will check if the COURIER_TYPE (which is the Courier Name description from the information defined in [ System Data | Couriers ]) matches against the text "CityLink":

if True it will add the fictitious URL for citylink tracking.
if False it will add the text:

"leave this blank to ignore other couriers".

if an error occurs then it will add the text:

"leave this blank to ignore errors".

<DECODE value1="&dollar;COURIER_TYPE" operator="equals" value2="CityLink" 
trueText="Look here to track your order: www.citylinkexample.com/track?=&dollar;CONSIGNMENT_REF"
falseText="leave this blank to ignore other couriers" 
errorText="leave this blank to hide errors"></DECODE>

Notes:

Equals is the only operator supported at present.
This functionality does not work when nested inside each another tag structure.
DECODE must be in capitals.
trueText, falseText, and errorText must have a capital T in Text.
If you wish to use any HTML tags within trueText / falseText / etc, all < and > symbols must be replaced with the following which will appear as valid HTML in the final email:
>
<
If using the &dollar;BOXES_CONSIGNMENT_REF tag then the second line above for both <DECODE> options should be:
```
 trueText="Look here to track your order: &dollar;BOXES_CONSIGNMENT_REF"
```
This will pull the appropriate Courier URL from [ System Data | Couriers ] and add the consignment reference at the end for each box being shipped. To set this up see How To: Setup Email Consignment References for Boxes.
Do not use special characters such as & as this will not work, this includes in the URL such as for DPD where a '&' is part of the URL and throws an error when the system attempts to send the email. Try removing the & as in testing the link still works!
If you need help with other examples please email Support.

Example Two - Matching two parameters

If you need to do different actions for other couriers you will need to add a condition for each matching courier text. Please check the Notes above and ensure you follow them for all additional parameters.

COURIER_TYPE which is the Courier Name description from the information defined in [ System Data | Couriers ].

<DECODE value1="&dollar;COURIER_TYPE" operator="equals" value2="CityLink" 
trueText="Look here to track your order: www.citylinkexample.com/track?=&dollar;CONSIGNMENT_REF" 
falseText="leave this blank to ignore other couriers" 
errorText="leave this blank to hide errors"></DECODE>

COURIER_CODE which is the Courier Code from the information defined in [ System Data | Couriers ].

<DECODE value1="&dollar;COURIER_CODE" operator="equals" value2="CityLink" 
trueText="Look here to track your order: www.citylinkexample.com/track?=&dollar;CONSIGNMENT_REF" 
falseText="leave this blank to ignore other couriers" 
errorText="leave this blank to hide errors"></DECODE>

Example of using Decodes to add courier information to an email

This example is carried out in two stages:

Create the Email Template, for more information see How To: Setup Email Templates.
Create the associated Trigger Rule, for more information see How To: Setup Email Trigger Rules.

Create the Email Template

Email message templates are used when sending emails either automatically or manually from Khaos Control.

Open an Email Manager screen (show me how).
Click in the Message Templates radio button to display existing message templates.
Press Ctrl+N or click .
In the Setup area at the top:
- Template Code: add a template code.
- Template Desc: add a template description.
- Trigger Type: INVOICE.
- CC List and BCC List: add email addresses if you wish to send copies to the email.
Available Tags grid: Selecting the appropriate Trigger Type will determine the available tags that can be entered into the email. The tags available are listed in the left hand side of the screen. Tags use a standard programming format that takes the correct information from the customer record(s) to generate emails.
Template Area
- Subject: defines the text for the subject line of the email. The upper adds the selected tag item to the subject field.
- Item Template: the item template field is ONLY used when the &dollar;ITEM_TEXT tag is being used in the body of the message template. The system will replace the &dollar;ITEM_TEXT with the "values" from the item template. The tags that can be used in conjunction with this tag are shown in blue in the available tags field. When a "blue" tag is selected, the green arrow adjacent to the Item Template field will move the tag. Several tags can be added for example: "&dollar;STOCK_CODE &dollar;ITEM_NAME &dollar;QTY_SENT &dollar;NET_TOTAL &dollar;GROSS_TOTAL" will replace the &dollar;ITEM_TEXT in the Message Template with add the stock code, stock description, quantity sent, and net and gross total for each stock item.
- To Follow Item Template: the to follow item template is ONLY used when the &dollar;TO_FOLLOW_ITEM_TEXT tag is used in the body of the message template. The system will replace the &dollar;TO_FOLLOW_ITEM_TEXT with the "values" from the item template. The tags that can be used in conjunction with this tag are shown in blue in the available tags field. When a "blue" tag is selected, the green arrow adjacent to the To Follow Item template field will move the tag into the field. Several tags can be added for example: "&dollar;STOCK_CODE &dollar;ITEM_NAME" will replace the &dollar;TO_FOLLOW_ITEM_TEXT in the Message Template with the stock code and stock description for each stock item not assigned on the order.
- Message Template: this area is used to construct the message. The lower green arrow adds items to the message template field. Add your message including your decode statement, for example:
  <DECODE value1="&dollar;COURIER_TYPE" operator="equals" value2="City Pack City Link" trueText="Click here to track your order (please note, it may take up to two hours for your delivery information to appear on the couriers web site) http://www.citylink.co.uk/pod/podfrm.php?JobNo=&dollar;CONSIGNMENT_REF" falseText="" errorText=""></DECODE>
  Note: If value1 is the same as value2 then the message will have text 'trueText' else if value1 is different to value2 then will show 'falseText' (can be left blank), else if the conditional message is setup wrong then will show 'errorText' (can also be left blank). If you set this up for each courier then which ever courier is on the order will show on the email message.
Press Ctrl+S or click to save the message template.

Create the Email Trigger Rule

Email Trigger Rules prompt the system into creating and in some instances automatically sending emails from Khaos Control. They are used in conjunction with Message Templates. The rule that is described below has a trigger that is prompted when the sales invoice is moved from one stage onto the next.

Open an Email Manager screen (show me how).
Click in the Trigger Rules radio button to display existing trigger rules.
Press Ctrl+N or click .
In the Setup area at the top:
- Rule Code: add a trigger rule code.
- Rule Description: add a trigger rule description.
- Trigger Type: INVOICE used for emails generated in relation to something happening the Invoice Manager.
- Send Email Immediately checkbox: if ticked then the email will be automatically sent and not held in the Pending emails section and will need to be sent manually.
- Message Template: the message template that is to be used with the trigger rule.
The trigger that prompts the system into processing the email is created in the lower area.
Focus on OLD INVOICE STATUS in the Available Conditions area and click on the button. This will move the condition into the Active Conditions area.
Enter = in the Comparison column.
Focus in the Lookup Value column and press the Ctrl+F8 keys.
From the options in the popup select ORDERS -SHIPPING.
Click on OK.
Focus on NEW INVOICE STATUS in the Available Conditions area and click on the button. This will move the condition into the Active Conditions area.
Enter > in the Comparison column.
Focus in the Lookup Value column and press the Ctrl+F8 keys.
From the options in the popup select ORDERS - SHIPPING.
Click on OK. When an invoice goes from invoicing to a further stage then the email will be created.
Press Ctrl+S or click to save the trigger rule.

Notes: the Document Rules generate an email when a customer has the following set-up against them:

When the customer's invoice contact has an e-mail address.
When there is no email address for the invoice contact but the invoice address' email address will be used.

Testing

It is important that you test that your trigger rule and message template work and that the link to track the package works as well.

Royal Mail

The Royal Mail consignment number consists of a 13 alphanumeric string:

Starting with 2 characters
Followed by 9 digits
Ending with 2 characters which are "GB"

For example consignment ref = ZW924750388GB