Definition

EndDefinition

• Instructions are specified using predefined variables.
• This may result in the creation of a new object or the update of an object described in the message.
• File attachments sent with the email can be attached to the object.

To access the inboxes, you must configure the protocol used by the email server depending on the selected authentication method.

Operating principle

1. The Technical Support Agent connects to the IT Support inboxes on a regular basis.

• Inboxes receiving user messages that report incidents or submit requests to IT Support
• Inboxes receiving automatically created events when a failure is detected for an equipment or configuration item (CI)

2. The Technical Support Agent retrieves emails from two sources.

• Emails sent by Service Manager, via approval workflow steps or wizards
• Emails sent by an external application via the email server

3. The actions described in the email are automatically performed.

• A new object is created. Its category is the subject associated with the message. If this is not available, then it is the subject associated with the inbox.
  or
• The object described in the message is updated, e.g. fields passed in parameters are modified, tickets are put on hold, reopened or resolved, approval/rejection emails are processed, attachments are stored, etc.

4. The email is automatically deleted once it is processed in order to reduce the volume of the inbox.

Example

• An email is transmitted by a user to the mailbox for incidents of the IT support.
  • Title: Description of the problem on my smartphone
  • Message: Impossible to start the application. See the attached screen captures
              Recipient / Requesting person : fleblanc@aef.com
              @ASSET@='P04319'
              @CODE_CATALOG@='Smartphone'
              @DATE@='02/07/2022'
              @URGENCY@='1'
              Attached pieces: document.txt

    ==> An incident is automatically generated dated 02/07/2022, with a High urgency, for the equipment P04319.

    • The variable @CODE_CATALOG@ is completed: the default topic of the mailbox is replaced by the category Incidents/Equipment/Other Peripherals/Smartphone.
    • The standard workflow Incident: Standard Process related to the category will automatically trigger.
    • The attached piece document.txt is attached to the incident, and accessible via Documents tab.

• The message is sent from the email address, gsmith@aef.com.

  ==> The Technical Support Agent will not process the message received because the email address of the recipient, fleblanc@aef.com, is different from the email address of the sender, gsmith@aef.com.

Modern authentication based on OAuth 2.0

Modern authentication is based on OAuth 2.0 and is used with Office 365 and Microsoft Graph protocols. It requires an Azure AD application to be registered on the Microsoft Azure portal with the relevant permissions for using the Microsoft Graph Mail API.  See the procedure.

API permissions are required to authorize the Azure AD application to access API resources.

• Application permissions for CC (Client Credentials) mode. This enables the Technical Support Agent to authenticate using its own credentials without any user interaction or consent (access without user sign-in).
• Delegated permissions for ROPC (Resource Owner Password Credentials) mode. This enables the Technical Support Agent to access the API via the consent granted by the user when signing in (access with user sign-in).
   

Permissions required by the Technical Support Agent in order to use the Microsoft Graph Mail API (modern authentication)

• Office 365 protocol:
  • Only delegated permissions (ROPC mode)
  • User.Read, IMAP.AccessAsUser.All, offline.access

• Microsoft Graph protocol:
  • Degated permissions (ROPC mode) or application permissions (CC mode)
  • User.Read, Mail.ReadWrite, offline.access and optionally Mail.ReadWrite.Shared

Notes

• Protocols not supported by the Technical Support Agent:
  •  Multifactor authentiication (MFA): sms, phone, mobile app
  • Code d’autorisation OAuth avec écran de consentement

• For security reasons, the password and the client secret will not be displayed when you open an existing form. They are nevertheless stored in the database and it is not necessary to re-enter them.
• The Application ID (client), Directory ID (tenant) and Client Secret fields are dedicated to the modern authentication. The may not be displayed on the form. In this case, you have to add them manually on the form.  See the detailed procedure.

• Update of the form processed by the Technical Support Agent:
  • The topic and the message body are reported to the Description.
  • The responses to the emails of Service Manager and the attachments can be attached to the object; then they can be accessed via the Documents tab in the forms (provided that you have enter the Technical Support Agent email adress in the other parameter {TSA} Support return email address).

• A log file allows checking the history of the operations executed by the service SmoServer.

• Predefined variables.  See the list.
  • They must to be placed between @ characters.
             example  Event generated at @DATE@
  • Each value of the variable must to be put between apostrophes ' ' .
             example  @ASSET@='P04319'
  • If a variable includes several values, each one must be placed between curly brackets { }.
             example  @FIELDS_TO_UPDATE@={COMMENT=Internal Problem} {ASSET_TAG=ZS_010}
  • If the variable allowing to identify the object number is completed, the existing record is updated; otherwise a new record will be created.
             example  The incident @RFC_NUMBER@)='100622_000027' has been updated.

Caution

• When the Technical Support Agent is deactivated, the mailboxes will not be consulted any longer even if they are active.
• If you modify the inbox configuration from POP3 or IMAP protocol towards Microsoft Graph protocol, you must clear the content of the Password field to ensure that the Technical Support Agent will be able to connect the inbox and process the emails received.
• To prevent integration errors from the Technical Support Agent and the saturation of the hard-disk of the platform, you should create a mailbox to receive the different incident types and associate a default topic.

• To prevent out-of-office emails from inadvertently generating tickets, all messages whose header contains the following tags will systematically be rejected by the Technical Support Agent. Check that your email server is correctly configured.
  • Auto-response messages:
    • auto-submitted: auto-replied
  • Report messages:
    • content-Type: multipart/report
    • disposition-notification
    • delivery-status

• Html interpretations:
  • Office 365 and Outlook Web Access (OWA) clients have limitations regarding Html interpretations. To make sure your emails are interpreted by all the email clients, respect the best practice. 
  • Only use ' character (right quotation mark) and never ‘ character (left quotation mark) in the body part of the approval/refusal emails.
    Note: If you do a copy-paste from Word or Outlook, right quotation marks are automatically replaced by left quotation marks. You will have to replace them back to right quotation marks for them to be correctly interpreted.

Best Practice

• Associate a default topic of the different incident types quit general such as Incident Front Office. Once the message has been analyzed, the technical support has the possibility to re-qualify the incident more precisely (Example: Incidents / Equipment / Laptop / Battery).

• To ensure that the body part of the approval/refusal emails is correctly interpreted by all the email clients:
  • Only use ' character (right quotation mark).
  • Replace spaces by %20, except for the values of the predefined variables.
        example
    • To approve  ==>  To%20approve
    • 21/10/2022 14:30  ==>  21/10/2022 14:30
  • Replace = characters by %3D.
  • Replace quotation marks ' ' by %27.
        example  @CHOICE@='1'  ==>  @CHOICE@%3D%271%27

• To assist you with entering an approval/refusal email, you should use this CHA's Mailto Code Generator.   See the procedure

Menu access

Administration > Parameters > Technical Support Agent

Screen description

Mailbox: Name of the inbox specific to IT Support.

Enable Active Mailbox Scan: Used to indicate if the inbox is active and can receive messages () or if it is inactive ().

Type: Type of protocol used by the email server. The configuration of the Technical Support Agent depends on the selected protocol.

• Only the following protocols are supported by the Technical Support Agent.
  • POP3: Basic authentication via a login and password.
  • IMAP4: Basic authentication via a login and password.
  • Office 365: XOAuth modern authentication for the IMAP4 protocol only in ROPC mode (delegated permissions). The protocol uses a secure SSL/TLS connection.
  • Microsoft Graph: OAuth 2.0 modern authentication in ROPC mode (delegated permissions) and CC mode (application permissions). The protocol uses the Outlook REST API via the HTTPS protocol.

• Modern authentication based on OAuth (Office 365 and Microsoft Graph protocols) requires to register an Azure AD application on the Microsoft Azure portal with the relevant permissions for using the Microsoft Graph Mail API.  See the procedure.
   

Read Interval (in Min): Frequency (in minutes) based on which the inbox is checked for new messages received.

Mail Server: IP address of the email server.

• Office 365 protocol: This is outlook.office365.com.
• Microsoft Graph protocol: It is unspecified. It automatically uses the Microsoft server specific to the Microsoft Graph Mail API.

Port: Port number for accessing the email server.

Login/Password: Login and password for accessing the inbox.

• POP3 and IMAP4 protocols: These fields are required.
• Office 365 protocol: These fields are required.
• Microsoft Graph protocol:
  • The login is required.
  • The password is required for the ROPC mode (delegated permissions).
  • The password must be empty for the CC mode (application permissions).

SSL/TLS: Used to indicate if the email server connection method is secured using an SSL (Secure Socket Layer) or TLS protocol (Transport Layer Security) () or not ().

• Office 365 protocol: Enabled .
• Microsoft Graph protocol: Disabled .

StartTLS: Used to indicate if the StartTLS protocol is used for the configuration of the Technical Support Agent () or not ().

• StartTLS protocol is used to secure a standard connection via TLS.
• It is mainly used with SMTP, IMAP and POP.
• It can run with both SSL and TLS.
   

Information required only for modern authentication

• Application ID (client): Unique ID (GUID) of the Azure AD application in the Active Directory.

• Directory ID (tenant): Unique ID of the Active Directory in Microsoft Azure.

• Client Secret: Secret associated with the application ID.
  • The secret is hidden using the * character to safeguard confidentiality.
  • Office 365 protocol: The field is optional.
  • Microsoft Graph protocol:
    • The field is optional with the ROPC mode (delegated permissions).
    • The field is required with the CC mode (application permissions).
       

Default Category: Default subject of the generated object.

Origin: Method by which the current object is reported to IT Support.
    example  Phone, email

Create Unknown Requestors: Used to indicate if senders of emails should be created if they do not exist in Service Manager (box is checked) or not (box is not checked).

• The existence of the sender is checked using the email address.

Redirect Unknown Emails to: Email address for redirecting emails if senders do not exist in Service Manager and if the automatic creation of unknown senders is disabled.

Procedures and Wizards

How to implement the Technical Support Agent

Prerequisites: Create an Azure AD application for modern authentication.

Modern authentication based on OAuth (Office 365 and Microsoft Graph protocols) requires to register an Azure AD application on the Microsoft Azure portal with the relevant permissions for using the Microsoft Graph Mail API.

      See the procedure.
 

Step 1: Create the dedicated mailboxes.

1. Select Administration > Parameters > Technical Support Agent in the menu.

2. Click .

3. Select the default topic of the mailbox. This is an incidents/requests/events catalog entry.

4. Select the type of protocol. The properties to complete depen on the value you select.

• POP3 and IMAP protocols (basic authentication):
  • Specify the Login / Password fields.

• Office 365 protocol (modern authentication based on XOAuth):
  • Enable the SSL/TLS option ().
  • Specify the Login / Password fields.
  • Specify the Application ID (client) and Directory ID (tenant) fields.
  • Specify the Client Secret field according to your needs.

• Microsoft Graph protocol (modern authentication based on OAuth 2.0):
  • Disable the SSL/TLS option ().
  • Specify the Application ID (client) and Directory ID (tenant) fields.
  • For the ROPC mode (delegated permissions):
    • Specify the Client Secret field according to your needs.
  • For the CC mode (application permissions):
    • Clear the Password field.
    • You must specify the Client secret field.

5. Activate the mailbox by checking the Enable Active Mailbox Scan box.

6. Click .

7. Repeat these actions to create each mailbox dedicated to the process of incidents/requests/events.

Step 2: Enable the Technical Support Agent.

1. Launch the Enable / Disable wizard.

Step 3 (optional): Configure the telnet connection.

      See  Installation Guide > Troubleshooting POP3 connections.

Step 4: Configure EasyVista Monitoring.

1. Connect to Easyvista Monitoring: http://SERVEREZV/Monitoring/.

2. Select the page Easyvista SGBDR > Parameters > Edit table A_PARAMETERS.

3. Select the connection EZV_ADMIN (For SQL Server) or EVO_ADMIN (For Oracle).

4. Check and update if necessary the value of the parameter ASTSERVER in the section [OTHERS] (Not specified in a_parameter.ini).

• ASTSERVER = name NETBIOS (or IP or DNS name) of the system hosting the service SMO Server
• If there are several network interfaces, only use the IP address to which the service SMO Server listens.

5. Click Save Changes.

6. Re-start the service SMOServer.

Step 5: Configure the log file.

1. Open the smoserver.ini file on the application server.

2. Complete the Log_Typevariable = lt_All.

Step 6: Enter the Technical Support Agent email address to store elements in the Document tab.

1. Select Administration > Parameters > Other Parameters in the menu.

2. Select {TSA} Support return email address.

3. Run the Update wizard.

4. Enter the return email address. Note: This must correspond to one of the email accounts used by the Technical Support Agent.

5. Click Finish.

How to configure modern authentication for the Technical Support Agent