The Technical Support Agent (TSA)


We strongly recommend not using the basic authentication for IMAP and POP3 protocols. Microsoft has announced that it will stop support. Open url.png See the Note.
Definition

The Technical Support Agent (AST) is a monitoring tool that checks emails received in IT Support inboxes. Its role is to convert messages automatically to incidents, service requests, change requests, or events based on the instructions specified in the emails.

  • 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.
EndDefinition

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

Note: Emails from unknown senders may be redirected to another inbox to be manually processed by the Service Desk. Once the email contents have been checked, the Service Desk will process the email or delete it if it is spam.

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
              @ASSET@='P04319'
              @CODE_CATALOG@='Smartphone'
              @DATE@='02/07/2018'
              @URGENCY@='1'
              Attached pieces: document.txt

==> An incident is automatically generated dated 02/07/2018, 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 Immediate Solution workflow related to the category will automatically trigger.
  • The attached piece document.txt is attached to the incident, and accessible via Documents tab.

Use of the Microsoft Graph Mail API

Modern authentication is based on OAuth 2.0 and is used with Microsoft Graph and IMAP protocols (Office 365). 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. Open url.png See the procedure.

Permissions can be as follows:

  • Application permissions for access without user sign-in (CC or Client Credentials mode): This enables the Technical Support Agent to authenticate using its own credentials without any user interaction or consent.
  • Delegated permissions for access with user sign-in (ROPC or 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.
     

Permissions required by the Technical Support Agent in order to use the Microsoft Graph Mail API

  • Office 365 (IMAP) protocol:
    • Delegated permissions only
    • User.Read, IMAP.AccessAsUser.All, offline.access
  • Microsoft Graph protocol:
    • Application permissions or delegated permissions
    • User.Read, Mail.ReadWrite, offline.access

Notes

  • When the Technical Support Agent is deactivated, the mailboxes will not be consulted any longer even if they are active.
  • 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 predefined variables. Open url.png 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.
  • Update of the form processed by the TSA:
    • 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 AST 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.

Caution

  • Microsoft has announced that it will stop support for basic authentication for IMAP and POP3 protocols in Exchange Online. If you are using one of these configurations for your Technical Support Agent, connection to Office 365 inboxes will no longer be possible. You must modify the configuration and use OAuth 2.0 modern authentication.
        Open url.png See Microsoft - Basic Authentication and Exchange Online.
  • 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

  • Create a mailbox to receive the different incident types and associate a default topic 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/2018 14:30  ==>  21/10/2018 14:30
    • Replace = characters by %3D.
    • Replace quotation marks ' ' by %27.
          example  @CHOICE@='1'  ==>  @CHOICE@%3D%271%27

Screen description

         Technical agent support.png

Menu access: Administration > Parameters > Technical Support Agent

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 (Switch on icon.png) or if it is inactive (Switch off icon.png).

Type: Type of protocol used by the email server. Caution: Microsoft has announced the end of support for protocols using basic authentication. Open url.png See the Note.

  • The configuration of the Technical Support Agent depends on the selected protocol. Open url.png See the procedure for modern authentication.
  • The Office 365 protocol is IMAP4 in XOAuth2 modern authentication. It uses a secure SSL/TLS connection.
  • The Microsoft Graph protocol uses the Outlook REST API with OAuth 2.0 modern authentication via the HTTPS protocol.

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.

  • This is outlook.office365.com for the Office 365 protocol.
  • It is unspecified for the Microsoft Graph protocol. 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.

  • In modern authentication, the password:
    • Is not required for application permissions.
    • Is required for delegated 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) (Switch on icon.png) or not (Switch off icon.png).

  • Enabled for the Office 365 protocol.
  • Disabled for the Microsoft Graph protocol.

StartTLS: Used to indicate if the StartTLS protocol is used for the configuration of the Technical Support Agent (Switch on icon.png) or not (Switch off icon.png). StartTLS is used to secure a standard connection via TLS.

  • StartTLS is mainly used with SMTP, IMAP and POP. 
  • StartTLS can run with both SSL and TLS.
     

Information required for modern authentication
This information is retrieved from the Azure AD application registered on the Microsoft Azure portal. Open url.png See the procedure.

  • 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. Note: The secret is hidden using the * character to safeguard confidentiality.
     

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.

Best Practice icon.png  

  • Specify a Service Desk inbox for unknown emails, e.g. spam, instead of a Technical Support Agent inbox. The Service Desk can check this inbox on a regular basis to ensure that no valid IT Support request is ignored.
  • To help the IT Support team identify these emails in the inbox easily, you can add a prefix to the subject of these emails in the Prefixing the Subject With field.

Procedures and Wizards

How to implement the Technical Support Agent (TSA)

Step 1: Create the dedicated mailboxes.

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

2. Click Add icon.png.

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

4. Complete the other properties.

  • In modern authentication, specify the password only for delegated permissions.
  • Office 365 protocol:
    • Enable the SSL/TLS option (Switch on icon.png).
    • Specify the Application ID (client), Directory ID (tenant) and Client Secret fields. Open url.png See the detailed procedure on retrieving this information from the Azure AD application registered on the Microsoft Azure portal.
  • Microsoft Graph protocol:
    • Disable the SSL/TLS option (Switch off icon.png).
    • Specify the Application ID (client), Directory ID (tenant) and Client Secret fields. Open url.png See the detailed procedure on retrieving this information from the Azure AD application registered on the Microsoft Azure portal.

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

6. Click Save icon.png.

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 wizard.

Step 3 (optional): Configure the telnet connection.

Note: Only if you use the POP3 protocol.

    Open url.png 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.

  • As soon as a message is received in one of the mailboxes monitors by the TSA, it is processed and then deleted automatically.
  • The log file is automatically updated.

Step 6: Enter the TSA 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 TSA.

5. Click Finish.

How to configure modern authentication for the Technical Support Agent

OAuth 2.0 modern authentication is used by Microsoft Graph and Office 365 protocols. 

Step 1: Register an application on the Azure portal.

1. Create a new Azure AD application on the Azure portal.

    Open url.png See the detailed procedure

2. Retrieve the Azure AD application IDs required for configuring the Technical Support Agent.

  • Copy the new Azure AD application ID from the Application (client) ID field on the Azure portal and paste it in the Application ID (client) field in the Technical Support  Agent window.
  • Copy the tenant ID from the Directory (tenant) ID) field on the Azure portal and paste it in the Directory ID (tenant) field in the Technical Support Agent window.

         App registration - App with IDs created.png
         Azure ID information.png

3. Create the client secret for the new Azure AD application.

    Open url.png See the detailed procedure

Caution: The value of the new client secret can be retrieved only during this step. Once you move on to the next step, the client secret will be hidden using the * character. If you lose the client secret, you must regenerate a new one.

4. Retrieve the Azure AD application IDs required for configuring the Technical Support Agent.

  • Copy the client secret from the Value field in the Client Secrets section on the Azure portal and paste it in the Client Secret field in the Technical Support Agent window.

         Certificates and secrets - Secret client created.png

Step 2: Declare the user authorized to access the Azure AD application.

    Open url.png See the detailed procedure

1. Add a new user in the Azure AD application.

2. Declare the email address of the user authorized to access Technical Support Agent inbox. This is the one specified in the Login field in the Technical Support Agent window.

         Login information.png
         User management - Add user - Assignment added.png

Step 3: Add the application permissions or delegated permissions for using the Microsoft Graph Mail API.

Note: The type of permission depends on whether or not user sign-in is required. Open url.png See Microsoft Graph Mail API.

    Open url.png See the detailed procedure

1. Add a permission for the Microsoft Graph Mail API (1) and select the type of permission required (2).

  • Microsoft Graph protocol: Application permissions or delegated permissions.
  • Office 365 (IMAP) protocol: Only delegated permissions.

         API permissions.png

2. Select the permissions for using the Microsoft Graph Mail API depending on the protocol.

Note: The User.Read permission is granted by default.

  • Microsoft Graph protocol:
    • User.Read: This enables the Technical Support Agent to authenticate.
    • Mail.ReadWrite: This enables the Technical Support Agent to access emails in the inboxes. Note: This is simply a read/write access and does not include the right to send emails.
    • offline.access: This enables the Technical Support Agent to read and modify data in offline mode.
  • Office 365 (IMAP) protocol:
    • User.Read: This enables the Technical Support Agent to authenticate.
    • IMAP.AccessAsUser.All: This enables the Technical Support Agent to access emails in the inboxes.
    • offline.access: This enables the Technical Support Agent to read and modify data in offline mode.
       

Step 4: Grant administrator consent for permissions.

Note: You must have the relevant rights to perform the actions in this step. If this is not the case, you should ask the administrator of your tenant to grant consent.

         API permissions - MS Graph with Application permission - API permissions granted.png

  • The Technical Support Agent can now access the dedicated inboxes and retrieve messages.
  • Emails will be processed and imported as tickets into Service Manager.

How to configure an approval/refusal email

Approval/refusal emails are sent via validation steps workflow.

  • The user can click on one of the two hyperlinks: Accepted / Refused

         mail Approval Refusal.png

  • His response will be automatically sent to the Technical Support Agent via an email.


Step 1: Open the validation step workflow.

1. Go to the workflow.
The graphical editor will be opened.

2. Double click on the approval step.

         Workflow GUI - accepted-refused email.png

Step 2: Enter the approval/refusal email.

1. Enter the mail address of the TSA in the field Return address.

2. Specify the object reference in the field Subject.
Note: Use the @RFC_NUMBER@ predefined variable.

3. Enter the text of the email in the field Message.

Best Practice icon.png

  • Click Html Editor icon.png to switch to Html mode.
  • Create the 2 hyperlinks by inserting the instructions defined below.
    • Accepted:
               Accepted hyperlink.png
      mailto:noreply@easyvista.com?subject=Accepted&body=To%20accept%20the%20request,%20you%20only%20click%20on%20the%20button%20d%27sending%20the%20email.%0ADo%20not%20change%20the%20text%20below%20%0A%0A@OPERATION@%3D%27SOLVE%27%0A@RFC_NUMBER@%3D%27S160824_000001%27%0A@CHOICE@%3D%271%27
    • Refused:
               Refused hyperlink.png
      mailto:noreply@easyvista.com?subject=Refused&body=To%20refuse%20the%20request,%20you%20only%20click%20on%20the%20button%20d%27sending%20the%20email.%0ADo%20not%20change%20the%20text%20below%20%0A%0A@OPERATION@%3D%27SOLVE%27%0A@RFC_NUMBER@%3D%27S160824_000001%27%0A@CHOICE@%3D%270%27

How to use the CHA's Mailto Code Generator

         Open url.png  See CHA's Mailto Code Generator

         cha4 generator.png

Step 1: Enter the approval/refusal email.

1. Enter the recipients in the To, CC, BCC fields.

  • Separate addresses with commas.

2. Enter the email subject in the Subject field.

3. Enter the email content in the Body area.

example  Sending a solution email of an incident

@OPERATION@='SOLVE'
@RFC_NUMBER@='#RFC_NUMBER#'
@CHOICE@='1' pour an approval __or__ @CHOICE@='0' for a refusal _or_ @CHOICE@='2' for an information request

4. Click Create URL.

Step 2: Test the email display in the inbox.

1. Click Test URL.

2. Make the necessary corrections.

Step 3: Copy the email in the validation step workflow.

1. Copy the generated URL in the Mailto URL area.

2. Go to the validation step workflow in the GUI Worfklow.

3. Switch in the Html mode via Html Editor icon.png.

4. Paste the URL in the Message area.

Wizards

Enable: Activates the Technical Support Agent. Note: Only active mailboxes will be scanned by the agent (Enable Active Mailbox Scan box checked).

Deactivate: Deactivates the Technical Support Agent. All the mailboxes associated will not be consulted any longer.

Delete: Deletes the mailbox. 

 

Predefined variables

  • 2 variables identify the actions:
    • @ACTION_ID@='#CURRENT_ACTION_ID#': Identifier of the current action
    • @ACTION_ID@='#ACTION_ID#': Identifier of the previous action
       
Action Operation Variable Example
Creation
  • @ASSET@: Equipment code concerned by the object
  • @CI@: CI name concerned by the object
  • @CODE_CATALOG@: Category of the catalog to which is attached the object. If no category is defined, the default topic of the mailbox will be applied automatically
  • @DATE@: Date/Hour of the object creation
  • @EXTERNAL_REFERENCE@: Identifier of the object in the external application at the origin of the message
  • @PARENT_INCIDENT@: For an incident/request, incident/request number of the related inciden
  • @URGENCY@: Urgency level of the object
  • @ASSET@='P04319'
  • @CODE_CATALOG@='Smartphone'
  • @DATE@='02/07/2018'
  • @URGENCY@='1'
Modification UPDATE
  • @FIELDS_TO_UPDATE@:
    • Detail of the variables to update for the object
    • This is the physical name of the field in the database.
    • Variables must be placed between curly brackets { }.
  • @OPERATION@: Operation type to execute on the object
  • @RFC_NUMBER@ ou @EXTERNAL_REFERENCE@: Number of the object in Service Manager or Identifier of the object in the external application at the origin of the message
  • @OPERATION@='UPDATE'
  • @RFC_NUMBER@='I080104_000003'
  • @FIELDS_TO_UPDATE@='{COMMENT=Pb interne} {ASSET_TAG=ZS_010}'
Reopening RESTART
  • @OPERATION@: Operation type to execute on the object
  • @RFC_NUMBER@ ou @EXTERNAL_REFERENCE@: Number of the object in Service Manager or Identifier of the object in the external application at the origin of the message
  • @OPERATION@='RESTART'
  • @RFC_NUMBER@='I0000001'
Solution SOLVE
  • @CHOICE@: Used for approval/refusal emails as variable parameter @OPERATION@='SOLVE'
    • 0: Creates a refused link
    • 1: Creates an accepted link
  • @DATE_FORMAT@: Format to apply to the variables @START_DATE@ and @END_DATE@
  • @END_DATE@: End of intervention of the object
  • @GROUP_NAME@: Name of the IT support group handing the object
  • @OPERATION@: Operation type to execute on the object
  • @RFC_NUMBER@ ou @EXTERNAL_REFERENCE@: Number of the object in Service Manager or Identifier of the object in the external application at the origin of the message
  • @START_DATE@: Start date for the intervention on the object
  • @OPERATION@='SOLVE'
  • @RFC_NUMBER@='I0000001'
  • @GROUP_NAME@='North America Network'
  • @START_DATE@='21/10/2018 11:30'
  • @END_DATE@='21/10/2018 14:30'
  • @DATE_FORMAT@='dd/MM/yyyy HH:mm'
Storage of attached documents and the reply to the Service Manager emails MAIL
  • @OPERATION@: Operation type to execute on the object
  • @RFC_NUMBER@ ou @EXTERNAL_REFERENCE@: Number of the object in Service Manager or Identifier of the object in the external application at the origin of the message
  • @OPERATION@='MAIL'
  • @RFC_NUMBER@='E071228_000880'
On Hold STOP
  • @OPERATION@: Operation type to execute on the object
  • @RFC_NUMBER@ ou @EXTERNAL_REFERENCE@: Number of the object in Service Manager or Identifier of the object in the external application at the origin of the message
  • @OPERATION@='STOP'
  • @RFC_NUMBER@='R090529_000001'

Integration Examples

Live Chat Tools

Tags:
Last modified by Unknown User on 2020/12/22 17:34
Created by Administrator XWiki on 2013/03/25 18:27

Shortcuts

Powered by XWiki ©, EasyVista 2021