Setting up unread emails as events
This topic describes how you can set up and convert an email from the email server to an event.
TrueSight Infrastructure Management server connects to the email server periodically by using configured credentials to retrieve emails. These emails are then converted into events. The subject of the received email is updated in the Message (msg) event slot. The content of the email is updated in the Detailed Message (mc_long_msg) event slot.
Important
- Only an email in the plain text or the HTML format can be set as an event.
For an email in the HTML format, only the content is extracted and the tags are removed.
If an email is in the plain text and HTML formats, then the text of the content that appears first in the email is converted as an event.
- Emails that are already read, or are in draft or deleted modes are not converted into events.
The following table describes the keywords that might be present in an email:
| Keywords | Description |
|---|---|
| The severity of an event is determined from the If these keywords are missing, the default configured severity value The following severity values are also supported:
|
| If these keywords are missing, the default value is the from address of the email. |
| If these keywords are missing, 0 (zero) is provided as the message ID. |
To configure the application in Azure Portal for Microsoft Office 365
If you are using Microsoft Office 365 that uses OAuth 2.0 authorization, you need to configure the application in Azure Portal to set an email as an event. A user with the Admin permissions can perform this task.
Perform the following steps:
Log in to the Azure Portal.
Navigate to the Enterprise application section and then create a new application. Add a name to the application.
- Go to Home> Azure Active Directory > App registration, and from All application, search by the name of the created application.
- Click the application.
From the left menu bar, go to Certificates and secrets > Client secrets and click New client secret.
On the Add a client secret window, add a description for your application and set the expire time.
What is Client secrets?
A secret string that the application uses to prove its identity when requesting a token. Also can be referred as application password.
Click Add to save the settings.
A value is generated.
Important: Copy and save the client secret
Value generated while adding a new client secret is displayed only once. Copy and save the client secret for future reference in the properties.
- From API permission > Add a permission, select Microsoft Graph and then select Application permission.
From the search bar, search for
Mail.ReadWriteand select the check box.Click Add permission and select Yes for Admin consent.
From Owners, add the users as owners to view and edit the application registration.
These users can view the application in the App registration > Owned application section.
Configure an application access policy to limit the scope of application permissions.
For more information about application access policy, see Microsoft documentation
.Restart the TrueSight Infrastructure Management server.
Important
- Changes to application access policies can take up to 30 minutes to reflect.
- Restart TrueSight Infrastructure Management server when you do any changes in the Azure Portal.
Downloading Microsoft certificates
Download the required certificates and their root certificates from the following links.
To configure an email as an event
You can configure an email as an event through the command line interface by running the pw email2event command:
pw email2event
usage:
pw email2event [-y]|[-c]|[-s]|[-e] [-i]The following table lists the parameters available in the pw email2event command :
| Options | Description |
|---|---|
–y | Encrypts the mailbox password. |
| Configures an email as an event. |
| -s | Starts scanning an email as an event. |
–e | Stops scanning an email as an event. |
–i | Use Example: |
Only emails that are in the configured folder of the email server are read. The following properties can be configured in the pronet.conf property file:
pronet.email2event.mailserver.fqdn=<email server>
pronet.email2event.mailserver.port=143
pronet.email2event.protocol=imap
pronet.email2event.mailserver.username=<user name>
pronet.email2event.mailserver.password=<encrypyted password>
pronet.email2event.mailserver.ssl.enabled=false
pronet.email2event.folder=inbox
pronet.email2event.delete.read.messages=true
pronet.email2event.mailbox.scan.frequency.mins=15
pronet.email2event.enabled=false
pronet.email2event.email.message.body.newline=false
pronet.email2event.default.severity=INFOpronet.email2event.access.mails.using.oauth2
pronet.email2event.mailapp.clientid
pronet.email2event.mailapp.clientkey
pronet.email2event.mailapp.tenantid
pronet.email2event.mailapp.mailstoscan
pronet.email2event.mailserver.username
pronet.email2event.folder
pronet.email2event.delete.read.messages
pronet.email2event.mailbox.scan.frequency.mins
pronet.email2event.enabled
pronet.email2event.default.severityParameter description
- pronet.email2event.enabled: Enable email2event feature by setting this value to true. By default, this value is set to false.
- pronet.email2event.mailserver.port: Default port number is 143. If you want to enable SSL/TLS, change the port number accordingly.
pronet.email2event.folder: Create a folder in the email server and assign the folder name to this parameter. Configure rules in the email server to direct the unread emails to this folder. By default, this parameter is set to INBOX.
Only for Microsoft Office 365 account
If a child folder is present in the mail box , then provide the complete path.
Example: If you want to configure Email2Event to read mails from the folder xyz, which is located in inbox>email2event>xyz folder, then provide input for property
pronet.email2event.folderasinbox/email2event/xyz.- pronet.email2event.email.message.body.newline: Enable the email new line feature by setting this value to true. By default, this value is set to false. When set to false, the entire email message is displayed on the same line. When set to true, the displayed message resembles the email format.
- pronet.email2event.mailbox.scan.frequency.mins: Specifies the frequency in minutes at which the Infrastructure Management Server scans the mail box. By default, the Infrastructure Management Server scans the mail box in every 15 minutes. Emails that are already read, or are in draft or deleted modes are not considered.
- pronet.email2event.delete.read.messages: If you set this value to false, the emails that are already read by the server and marked as seen are not deleted from the email server. If you set this value to true, the emails that are already read by the server and marked as seen are deleted from the email server. By default, this value is set to true. All other Multipurpose Internet Mail Extensions (MIME) content such as attachments, images, and so on are ignored.
- pronet.email2event.mailserver.ssl.enabled: If you set this value to true, the communication between email server to the Infrastructure Management server is in SSL/TLS mode. If you set this value to false, the communication between the email server to the Infrastructure Management server is in plain text mode. By default, this value is set to false.
- pronet.email2event.imap.tls.version: TLSv1 and 1.2 are supported. You must enable SSL property to set the TLS version property. When you enable the SSL to true, by default the TLS v1.0 is enabled. Using this property, you can set the version to 1.2. For example,
pronet.email2event.imap.tls.version=TLSv1.2.
- pronet.email2event.access.mails.using.oauth2: If you set this value to true, it uses OAUTH2.0 protocol to authenticate to read and update emails. By default, value is set to false.
- pronet.email2event.mailapp.clientid: This is the unique identifier which assigned to an application created in Azure Portal.
- pronet.email2event.mailapp.clientkey: A secret string which user generates for application in Azure Portal . The application uses this id to prove it's identity when requesting a token. Also referred as application password. Use
$ pw email2event -ycommand to encrypt the client key value before adding to the configuration file.
- pronet.email2event.mailapp.tenantid: This is the ID of the Azure Active Directory in which application is created.
- pronet.email2event.mailapp.mailstoscan: Number of unread emails to be processed in one scan period. By default, 50 unread emails will be read and processed by Email2Event thread in one scan.
Troubleshooting while configuring OAuth 2.0 authorization
By default, Email2Event log file is not created and all the info and error messages are logged into Truesight.log.
To enable the logging, use command pw debug on -p jserver -s Email2Event. This creates a new log file with the name Email2Event.
Scenario | Message on console | Log file message | SME details |
|---|---|---|---|
Invalid clientId value provided in pronet.conf file for property pronet.email2event.mailapp.clientid | Error: Invalid input - Client(Application) Id | Authentication failed with error: AADSTS700016, error description: Application with identifier 'e8176397-9013-4ddb-a0b1-347f0bxxxxx' was not found in the directory '4813ef1c-5e44-469d-bee8-cdabxxxxxxxx'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant. | SMEMsg: Client(Application) Id
|
Invalid clientKey value provided in pronet.conf file for property pronet.email2event.mailapp.clientkey | Error: Invalid input - Client(Secret) Key | Authentication failed with error: AADSTS7000215, error description: Invalid client secret is provided. | SMEMsg: Client key(secret) entered for Client Id SMEDetailedMsg: Provide encrypted correct value for value for |
Invalid tenantId value provided in pronet.conf file for property pronet.email2event.mailapp.tenantid | Error: Invalid input - Tenant(Directory) Id | Authentication failed with error: AADSTS90002, error description: Tenant '4813ef1c-5e44-469d-bee8-cdabxxxxxxx' not found. This may happen if there are no active subscriptions for the tenant. Check to make sure you have the correct tenant ID. Check with your subscription administrator. | SMEMsg: Tenant(Directory) Id SMEDetailedMsg: Provide correct value for |
Invalid username provided in pronet.conf file for property pronet.email2event.mailserver.username | Error: Invalid input - Username | Error: ErrorInvalidUser occurred while getting id for the mail folder: inbox, reason: Invalid input - Username. | SMEMsg: Username mf@bmc365test.com is invalid. SMEDetailedMsg: Provide correct value for |
Invalid folder name provided in pronet.conf file for property pronet.email2event.folder | Error: Invalid input - Folder Name | Error: folder name is invalid. | SMEMsg: Mail folder name shtest is invalid. SMEDetailedMsg: Provide correct value for |
If the required Microsoft certificates are missing | Error: One or more required Microsoft certificates are not imported. | SSLHandShake Exception will be logged into the log file. | SMEMsg: One or more Microsoft certificates required are missing. SMEDetailedMsg: One or more Microsoft certificates required are missing. Please download required certificate from the following links:
|
On Microsoft certificate expiry (Token Rest Endpoint) | Error: One or more required Microsoft certificates have expired | SSLHandShake Exception will be logged into the log file | SMEMsg: One or more Microsoft certificates required have expired. SMEDetailedMsg: One or more Microsoft certificates required to obtain access token have expired. Please download a new certificate from the following links:
|
On Microsoft certificate expiry (Microsoft Graph rest endpoint) | Error: One or more required Microsoft certificates have expired | SSLHandShake Exception will be logged into the log file | SMEMsg: One or more Microsoft certificates required have expired. SMEDetailedMsg: One or more Microsoft certificates required to obtain access token have expired. Please download a new certificate from the following links:
|
Client Key expired | Error: Client(Secret) Key input is invalid/expired | Authentication failed with error: AADSTS7000222, error description: InvalidClientSecretExpiredKeysProvided - The provided client secret keys are expired. Visit the Azure portal to create new keys for your app, or consider using certificate credentials for added security: https://aka.ms/certCreds | SMEMsg: Client(secret) key for application SMEDetailedMsg: Client(secret) key for application 3 |
Application access policy is set and the entered username does not have access to the application | Error: Provided username does not have access to the application with clientId. For more details, refer to the Azure portal configuration section in the attached readme. . | Error: ErrorAccessDenied occurred while getting id for the mail folder: inbox, reason: Provided username does not have access to the application with clientId. For more details, refer to the Azure portal configuration section in the attached readme. | SMEMsg: Username SMEDetailedMsg: Application access policy is set and provided username does not have access to the application. For application access policy details, For more details, refer to the Azure portal configuration section in the attached readme. |
Comments
Hi,
The statement below contains one additional dot at the end. For example,pronet.email2event.imap.tls.version=TLSv1.2.
This should be updated with: For example: pronet.email2event.imap.tls.version=TLSv1.2
Regards, Alex. Papadopulos
Log in or register to comment.