Creating User Instructions with the Remedy Email Engine

Version 2
    Share This:

    This week's theme:  Cool Tech Tips
    This week's topic was recommended by a member of the AR System Developer Community.


    Creating User Instructions with the Remedy Email Engine

    Last month, we published two Tips and Tricks articles on sending Query, Submit, and Modify instructions to the Remedy Email Engine. This article describes how to use the Remedy Email Engine to create User Instructions or custom actions.

    The Remedy Email Engine expects a specific syntax to process incoming messages. You can make email engine interaction easier for your end users by creating custom actions that reduce the need to learn the email engine syntax.

    Custom actions are called User Instructions. Every User Instruction must be associated with an email template. Templates provide generic layout for similar emails that are either sent out of or sent into the email engine, simplifying email engine interactions for end users.

    To use User Instructions you must:

    • Create a template by creating an .arm file
    • Attach the .arm file to an entry in the AR System Email Templates form
    • Provide a User Instruction name to the content templates in the User Instruction form
    • Re-start the email engine

    Creating a Template

    As an administrator, you can use a text editor to define templates by creating a text file with an extension of .arm, and then attaching the .arm file to an entry in the AR System Email Templates form.

    As an example, let's create a template file that queries all records submitted by user Harry HR in the Employee Information form. We will name this file template1.arm:

    Schema: Employee Information
    Qualification: 'Submitter' = "Harry HR"

    A template called Template1 is created by creating an entry in the AR System Email Templates form and attaching the above template1.arm file.

    Note: Click images for full screen view.

    Figure 1 – Attaching the template1.arm file in the AR System Email Templates form

    Naming the User Instruction

    Next, you can associate a name to the User Instruction by creating an entry in the AR System User Instruction Templates form. The User Instruction name will be used as a value for the Action Label.

    To continue the example already introduced, let's call the User Instruction FetchHarrysEntries and associate it with Template1 that we created earlier. We will also indicate that this template is available on the mailbox called AREmail_In.

    Figure 2 - Naming the User Instructions

    After you restart the email engine, all authorized users can send an email to the incoming mailbox of the email engine with the name of the User Instruction as the value of the Action Label.

    Login: Frank Frontline
    Password: mypassword
    Action: FetchHarrysEntries

    The email above will use the FetchHarrysEntries User Instruction to return all entries submitted by Harry HR. As you can see, templates and User Instructions can make it easier for your end users to interact with the email engine, reducing the need for them to learn the email engine syntax. Instead, all they need to do is use the User Instruction name as the value of the Action Label.

    Using Variables

    You can also use variables in templates. One example might be when you need to be able to send different values for the fields to submit an entry. Using variables enables you to submit those different values to the appropriate fields.

    The syntax for variables is #$$Variable Name$$#. If you expect the value of a variable to span multiple lines, then it needs to be enclosed by brackets [http://$$...$$|http://$$...$$]. Please note: If you do have variables spanning multiple lines, make sure that you also enclose the data sent in the email with brackets [http://$$...$$|http://$$...$$].

    Here is an example of a template file (.arm file) to submit a new employee name into the Employee Information form:

    Schema: Employee Information
    Server: server1
    Action: Submit
    Short Description ! 8!: $DATABASE$
    Submitter !2!:$USER$
    Employee Name !Employee Name!: [$$#$$VEmployee_Name$$#$$]

    Note that the characters between exclamation marks exactly match the field id or database name of the field on the form. The variable is called "VEmployee_Name". And since we expect it may span multiple lines, we have enclosed it between [http://$$....$$|http://$$....$$].

    After creating the template, we create a User Instruction called SubmitIntoEmployeeInformation in the User Instruction form.

    The email sent by the end user using the template above will look something like this:

    Login:Frank Frontline
    Action: SubmitIntoEmployeeInformation
    !VEmployee_Name!: [$$Joe Smith$$]

    Note that the characters between the exclamation marks match the variable name in the template. The email engine will then:

    1. Match the string between exclamation marks in the email received with the variable name in the template
    2. Get the database name or field id between the exclamation marks in the template
    3. Substitute the field with that database name with the value sent in the email

    Enhancing Outgoing Mails From the Email Engine

    Formatting the content of outgoing messages can enhance mails sent out of the email engine. Templates are used to format outgoing messages. These templates can be Header Templates, Footer Templates, Result Templates and Status Templates.

    Header Templates

    Header Templates are used to embed text or graphics in the beginning of mail. Header Templates can be either pure text or HTML format. Graphic images, such as your company logo, can be included in HTML header templates but not text header templates.

    Footer Templates

    Footer templates are used to add generic information at the end of every email that is sent out of the email engine. Footer Templates can be either plain text or HTML format. HTML formatted Foot Templates can contain graphics.

    Result Templates

    Result Templates define the format of the content of the reply sent out of the email engine. Here is an example of a result template that groups fields of the Employee Information form:

    The following was generated by Results Template:
    This #$$Action.Form$$# was acted upon by #$$Submitter$$# and relevant information for instruction is as follows:

    RequestId: #$$Request ID$$#
    Submitter ! 2!: #$$Submitter$$#
    Short Description ! 8!: #$$Short Description$$#

    Employee Personal Information
    Employee Name !536870920!: #$$Employee Name$$#

    The database name of the field must be specified between #$$...$$# in the result template. Variable names begin with and are substituted by values based on action performed on the incoming message.

    Status Templates

    If the processing of incoming messages results in an error, then the error status is returned back to the sender. The error status can be formatted using a Status Templates. Here is a sample status template:

    The following was generated by Status Template:
    Error Number: #$$ActionStatus.Number$$#
    Error Type: #$$ActionStatus.Type$$#
    Error Text: #$$ActionStatus.Text$$#
    Error Appended Text: #$$ActionStatus.AppendedText$$#

    The ActionStatus variables are substituted by the values of error returned.

    Using Header, Footer, Results and Status Templates with User Instructions

    The email template file that was created earlier, template1.arm, can be updated to use all the above templates as follows:

    Schema: Employee Information
    Qualification: 'Submitter' = "Harry HR"

    The reply message of the query will include the contents of the Header1 template at the beginning of the message, as well as the contents of the Footer1 template at the end of message; the content itself will be formatted as per the ResultTemplate1. If errors occur, the errors will be formatted using the Status Template.

    In summary, you can make interaction with the email engine easier for your end users by creating User Instructions that can format emails and allow email engine actions to occur without requiring users to learn specific syntax.

    Senior QA Engineer, AR Server Automation Group
    Joined Remedy one year ago