Extended Mail Configuration (incoming)

Background

In this article, you will be introduced to the extended configuration of the Mail Module in Highstage. This configuration enables Highstage users to store, manage and track incoming communication by mail, directly in Highstage.

The extended mail configuration enables Highstage users to:

• Initiate support- and feature requests from customers, partners and internal personal.

• Track mail conversations that are associated with existing Highstage items for full traceability.

• File, store and manage mails by associating them with new or existing items directly in Highstage.

• Add styling (Header and footer) to outgoing mails.

Prerequisites

Standard Mail Configuration

You must complete the setup of the Automatic mail notifications and reminders in Highstage, before any extended mail capabilities can be enabled in your Highstage installation.

Schema accessibility

In order to install the Highstage Mail module the user need administrative access to Highstage, as well as access to the schema files which define the functionality of Highstage.

Protocols

To retrieve e-mail messages from a mail server, a protocol is needed. The Highstage mail module makes use of the IMAP protocol. This means that the mail server need to support IMAP. Nonetheless this is one of the most popular mail protocols on the market, with support on all major platforms.

Setup of incoming mails in Highstage

Here, you will be introduced to the standard configuration related to the setup of incoming mails in Highstage.

Web config setup

The following section describes the required setup in web.config.xml using either basic authentication or OAuth authentication.

Web config configuration (Basic authentication)

1. Access the web.config.xml file from your Turbostage/TS_WebApp folder directory.

2. Add the following snippet within the <connectionStrings> element:

<add name="MAILID" connectionString="server=SERVERNAME;uid=USERID;pwd=PASSWORD;database=MAILFOLDER" />

3. Replace MAILID with any unique name value (This mail ID must also be used in the custom.schema.xml).

4. Replace SERVERNAME with an appropriate mail server name (IMAP or POP3 server name).

Tip: You can also specify a shared mailbox by replacing SERVERNAME with SERVERNAME/MAILBOX (e.g. inbox@company/sales).

3. Replace USERID with mail user name.

4. Replace PASSWORD with mail password.

5. Replace MAILFOLDER with an appropriate folder for new mails (e.g. Inbox).

Web config configuration (OAuth authentication)

Requirement: Please follow the listed instructions here to be able to utilize OAuth authentication before progressing with the instructions.

1. Access the web.config.xml file from your Turbostage/TS_WebApp folder directory.

2. Add the following snippet within the <connectionStrings> element:

xxxxxxxxxx
<add name="MAILID" connectionString="
     server=SERVERNAME;
     uid=USERID;
     clientid=XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX;
     tenantid=XXXX-XXXX-XXXX-XXXXXXXXXXXX;
     clientsecret=XXXX;
     catalog=MAILFOLDER"
     />

3. Replace MAILID with any unique name value (This mail ID must also be used in the custom.schema.xml).

4. Replace SERVERNAME with an appropriate mail server name (IMAP or POP3 server name).

Tip: You can also specify a shared mailbox by replacing SERVERNAME with SERVERNAME/MAILBOX (e.g. inbox@company/sales).

3. Replace USERID with mail user name.

4. Replace clientid with appropriate client ID.

5. Replace tenantid with appropriate tenant ID.

6. Replace clientsecret with appropriate client secret.

7. Replace MAILFOLDER with an appropriate folder for new mails (e.g. Inbox).

Custom schema configuration

1. Access the custom.schema.xml from your Turbostage/TS_WebApp/tweak folder directory.

2. Add the following snippet to enable the mail module:

xxxxxxxxxx
    <include src="/ts/schema/base/mail.schema.xml" />

3. Add the following configuration snippet:

xxxxxxxxxx
<type name="ts_mail" defaultmailtype="DEFMAILTYPE">
    <mailtype name="MAILTYPE"
              mailaddress="MAILADDRESS"
              connection="MAILID"
              ssl="SSLVALUE"
              defaultworkspace="DEFWORKSPACE"
              defaulttype="DEFTYPE"
              notification="MAILADRESSES" />
</type>

4. Replace DEFMAILTYPE with the name value of any existing <mailtype> to configure which default <mailtype> element is used by default.

5. Replace MAILTYPE with any unique name value (Should be the same value as DEFMAILTYPE in step 3 if this mailtype should be the default mailtype).

6. Replace MAILDRRESS with an appropriate mail address to receive mails.

7. Replace MAILID with the same value as specified in the web.config.xml (Should be the same ID as used in the web.config file).

8. Replace SSLVALUE with an appropriate value (Disabled, Explicit or Implicit).

9. Replace DEFWORKSPACE with an existing Workspace in Highstage where mails should be associated.

10. Replace DEFTYPE with an existing Type in Highstage where mails should be associated.

11. Replace MAILADRESSES with any number of mail addresses who should receive mail notifications when a mail is received by Highstage (e.g mail@highstage.dk;othermail@highstage.dk). Please refer to Notifications to learn about who receives notifications when new mails are received by Highstage.

You have successfully configured incoming mails from Highstage.

To get access to the default mail menu, including mail tests, please include a section to the type ts_mail in the menu-schema

Add headers and footers to outgoing mails

You can add custom text or styling to the headers and footers of the outgoing mails from Highstage.

1. In your custom.schema.xml, add the following snippet inside of the existing <type name="ts_mail"> element:

​x
        <html name="MailHeader">
        <![CDATA[ CONTENT HERE ]]>
        </html>
        <html name="MailFooter">
            <![CDATA[ CONTENT HERE ]]>
        </html>

        <txt name="MailHeader">
        <![CDATA[ CONTENT HERE ]]>
        </txt>
        <txt name="MailFooter">
            <![CDATA[ CONTENT HERE ]]>
        </txt>

2. Change the CONTENT HERE within the <html> elements with appropriate HTML/CSS to define content and styling for the header and footer of outgoing mails.

3. Change the CONTENT HERE within the <txt> elements with appropriate HTML to define basic content for the header and footer of outgoing mails.

Success! You have successfully added a standard header and footer of all outgoing mails from Highstage.

Notifications

Users will be notified via email when new mails are sent and received by Highstage.

New pending mails

For incoming mails that are received by Highstage (without a valid subject tag for it to be automatically attached to an existing item in Highstage), the mails will be readily available in the Pending mail section in the side navigation menu.

The list of users to be notified can be configured for each individual mail address (MAILTYPE). Please refer to Custom schema configuration to learn how to configure which resources to be notified.

Automatically attached mails

For incoming mails that are received by Highstage (where a valid subject tag is included as part of the mail subject line), the mail will be attached directly to the relevant item.

• On Documents, Parts, Devices (and other document derived types), Authors will be notified by mail that a new mail is available on the item.

• On Actions, resources assigned to past and current steps in the process will be notified that a new mail is available on the item.

• For other types (e.g. entity types like customers, suppliers, manufacturers etc.) resources assigned as values on columns that are listed as resourcecolumns on the type definition for the appropriate type will be notified.

Subject Line Tags

Any incoming mail sent to Highstage with an accepted token (specific contents in the mail subject line) will be automatically attached to the appropriate item.

Default Subject Token

By default, the following subject notation is accepted in the mail subject (Type refers to the relevant base- or subtype whereas ID refers to the unique item ID):

x
[type:ID] Subject line content.

Note: Please note that this subject token is only accepted if the MailIdentifierEnforcement parameter is disabled.

If the subject line token matches any existing item in Highstage, it will automatically become attached to that item and relevant resources will be notified.

Custom Subject Token (Made available in Highstage version 12.0)

The following subject token notation is accepted in the mail subject and can be customized using mail parameters:

x
[MailIdentifier / type / ID] Subject line content.

Note Please refer to SYSTEM > Parameters > Mail Parameters to configure which mail tokens are accepted by your Highstage installation.

The following mail parameters can be configured to define accepted mail tokens:

• Mailidentifier: (string) A unique configurable word to be included in the mail subject token.

• MailIdentifierEnforcement: (bit) enable or disable the acceptance of the default subject tokens ([type:ID]).

• MailIdentifierOldValues: (string list) List of supported mailidentifiers (when more mailidentifiers must be accepted).

• MailTokenDelimiterChar: (char) configure which special character must separate mailidentifier, type, and id.

If the subject line token matches any existing item in Highstage, it will automatically become attached to that item and relevant resources will be notified.

Samples

Shared mailbox with Office/Microsoft 365

Web config configuration (basic authentication)

xxxxxxxxxx
  <connectionStrings>
     <add name="SupportImapMail"    connectionString="server=outlook.office365.com;uid=companyserviceaccount@company.dk/support;pwd=*****;database=Inbox" />
     <add name="Inquiryimapmail"        connectionString="server=outlook.office365.com;uid=companyserviceaccount@company.dk/sales;pwd=*****;database=Inbox" />
  </connectionStrings>

Web config configuration (OAuth authentication)

xxxxxxxxxx
  <connectionStrings>
      <add name="SupportImapMail" connectionString="
     server=outlook.office365.com;
     uid=companyserviceaccount@company.dk/support;
    clientid=XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX;
     tenantid=XXXX-XXXX-XXXX-XXXXXXXXXXXX;
     clientsecret=XXXX;
     catalog=Inbox"
     />
      
        <add name="Inquiryimapmail" connectionString="
     server=outlook.office365.com;
     uid=companyserviceaccount@company.dk/sales;
    clientid=XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX;
     tenantid=XXXX-XXXX-XXXX-XXXXXXXXXXXX;
     clientsecret=XXXX;
     catalog=Inbox"
     />
      
</connectionStrings>

Custom schema configuration

xxxxxxxxxx
  <type name="ts_mail" defaultmailtype="support">
    <mailtype
              name="support"
              mailaddress="support@company.dk"
              connection="SupportImapMail"
              ssl="explicit"
              defaultworkspace="MAILS"
              defaulttype="SUPPORT"
              notification="employee@company.dk"
    />
      
    <mailtype name="Sales"
              mailaddress="sales@company.dk"
              connection="Inquiryimapmail"
              ssl="explicit"
              defaultworkspace="MAILS"
              defaulttype="SALES"
              notification="employee@company.dk"
    />

  </type>

Enable or disable Copy to folder button on attachments

For documents where there are referenced mails with file attachments, it is possible to enable and/or disable a Copy to folder button that automatically downloads the attachments to the associated item folder:

Configuration

Enabled (default):

xxxxxxxxxx
    <type name="ts_mail">
        <column name="Attachments" show-button="1" />
    </type>

Disabled:

xxxxxxxxxx
    <type name="ts_mail">
        <column name="Attachments" show-button="0" />
    </type>