Submitting a request through email

You can use email as a client of AR System to submit entries on the server. To execute submit instructions to the Email Engine, the following information must be included:

• AR System server name
• AR System server login and password to authenticate a user
• Form name on which to execute the instruction
• Submit action
• Any mandatory fields

To submit a request through email

1. Create a new email message in your mail tool.
2. Address the email message to the incoming mailbox.

3. To execute a Submit action that creates an entry Printer not working in the Short Description field of the HD Incident form, enter the following information in your email message to the Email Engine:

   Schema: HD Incident
   Server: polycarp
   Login: Francie Frontline
   Password: <userPassword>
   Action: Submit
   !Submitter!: Francie Frontline
   !Short Description!: Printer not working

   The field name between the exclamation marks must exactly match the field name as stored in the database. The field name is case sensitive.
   As with a Query action, Submit actions can also use the field ID instead of the database field name. The following syntax will return the same results if the Short Description field ID equals 8:

   *!8!: Printer not working

   You can add a comment before the exclamation mark used with field names as in the following example. The Email Engine will parse only the characters between the exclamation marks, for example, the field ID (8) of the Short Description field:

   Schema: HD Incident
   Server: polycarp
   Login: Francie Frontline
   Password: <userPassword>
   Action: Submit
   What is the problem!8!: Printer not working
   Who is submitting!2!: Francie Frontline

   If the value for the field is more than one line, enclose it between [$$ and $$]. For example, if you have a longer value for the Short Description, it could be sent to the Email Engine as:

   ! Short Description!: [$$This is a longer description that spans multiple lines, so use this syntax.$$]

   The Email Engine will correctly parse the syntax when the email is submitted.

4. Send your email.
   If you successfully submitted your email, the email returned will look something like this:

   Instruction 1 has successfully created a new record with Request ID : 000000000000001

If the incoming mailbox is configured to Reply With Entry, all the fields of the newly created entry are returned to the sender. For more information about this configuration option, see Configuring-incoming-mailboxes.

If the entry cannot be created, the Email Engine returns an error message as shown in the following figure that indicates missing parameters. Make sure your incoming email includes all required fields, for example, Submitter: 

Keywords in query instructions

You can use keywords such as $USER$ to supply the actual value for the field. Instead of specifying a text value, you can use keywords, as the following example shows:

For more information about the keywords that you can use when building a qualification, see Keywords.

To include attachments

Submit instructions can also include attachments. 

1. Create a new email message in your mail tool.
2. Address the email message to the incoming mailbox.

3. To include an attachment in an email, use the attachment field name or field ID:

   Schema: HD Incident
   Server: polycarp
   Login: Francie Frontline
   Password: <password>
   Action: Submit
   !Submitter!: Francie Frontline
   !Short Description!: I am including the filter.log file.
   Attachment field !536880912!: filter.log

   Your label/value pair syntax must refer to the attachment field and not to the attachment pool.

   Important

   If you are using message/rfc822 attachments with a submit template, make sure the mail client you use is sending the file name of the attached message properly. To test this, send an incoming mail with a message attachment, and view the Attachment tab on the Email Messages form for the name of the attached file. If you use Outlook Express to submit the message to the Email Engine and save the attachment by using the .msg extension, the file name remains intact. 

4. Insert your attachment file anywhere in the email.
   If the attachment name including the extension is not supplied, the email submission will not map the attachment to the appropriate attachment field.
   Do not include two attachment files with the same name, as shown in the following example:

   Attachment field 1 !536880912!: filter.log
   Attachment field 2 !536880913!: filter.log

   The Email Engine will accept the email submit instruction. However, the Email Engine cannot recognize which of the two filter.log files to insert into the 536880912 attachment field.

Specifying the fields to be included in a confirmation email by using the Format label 

Like the Query instruction, the Format label can specify whether a confirmation email from a Submit instruction should include all fields from the form or only the fields in the results list. By default, the Format label is set to Full, which means all fields in the form are included in the confirmation email. 

To use the Format label, configure the incoming mailbox Reply With Entry parameter to Yes. If Reply With Entry is set to No, the Format label is ignored and the confirmation email will contain only the Request ID number.

Join forms do not send values of fields on Submit when the Reply with Entry parameter is set to Yes for the incoming mailbox.

1. Create a new email message in your mail tool.
2. Address the email message to the incoming mailbox.
3. To include only fields from the results list in the confirmation message, set the Format label to Short: