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
State: <severity> Severity: <severity>	The severity of an event is determined from the State and Severity keywords present in the email content. If these keywords are missing, the default configured severity value INFO is used. The following severity values are also supported: OK MINOR MAJOR CRITICAL WARNING
Server: <mc_host> host: <mc_host>	If these keywords are missing, the default value is the from address of the email.
id: <msg_id> identifier: <msg_id>	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.ReadWrite and 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.

To configure an application policy...

Connect to Exchange Online powerShell and run the following command:
New-ApplicationAccessPolicy -AppId <AppId> -PolicyScopeGroupId <mail id or group mail id> -AccessRight RestrictAccess -Description "<description>"
Example: New-ApplicationAccessPolicy -AppId xxxx -PolicyScopeGroupId testuser@bmc.com -AccessRight RestrictAccess -Description "Restrict this app to members of distribution group EvenUsers."

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.
–c	Configures an email as an event.
-s	Starts scanning an email as an event.
–e	Stops scanning an email as an event.
–i	Use -path option to import the required certificates form any directory for Microsoft Office 365. Example: pw email2event -i -path C:\mscerts

Example

Run the following command to encrypt your mail box password. This command prompts you to enter the mail box password in plain text and gives the encrypted password as the output.
$ pw email2event -y
Assign this encrypted password value to the pronet.email2event.mailserver.password property in the pronet.conf file.
Open the pronet.conf file and configure the following properties:
pronet.email2event.mailserver.fqdn=<f.e.webmail.abc.com>
pronet.email2event.mailserver.username=<username>
pronet.email2event.mailserver.password=<encrypted password>
pronet.email2event.delete.read.messages=false
pronet.email2event.mailbox.scan.frequency.mins=5
pronet.email2event.mailserver.ssl.enabled=true
pronet.email2event.enabled=true
pronet.email2event.email.message.body.newline=true

For Microsoft Office 365
pronet.email2event.access.mails.using.oauth2=true
pronet.email2event.mailapp.clientid=<client ID>
pronet.email2event.mailapp.clientkey=<encrypted password>
pronet.email2event.mailapp.tenantid=<tenant ID>
pronet.email2event.mailapp.mailstoscan=20
pronet.email2event.mailserver.username=<username>
pronet.email2event.folder=<folder>
pronet.email2event.enabled=true
Restart the server.
$ pw sys start

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=INFO

Properties for Microsoft Office 365

pronet.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.severity

Parameter 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.folder as inbox/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 -y command 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 e8176397-9013-4ddb-a0b1-347f0bxxxxx is invalid. SMEDetailedMsg: Provide correct value for pronet.email2event.mailapp.clientid (Client/Application Id) in pronet.conf and restart TrueSight Infrastructure Management server.
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 3d0f78f1-6b78-474f-8391-3222511xxxxx is invalid. SMEDetailedMsg: Provide encrypted correct value for value for pronet.email2event.mailapp.clientkey for Client Id 3d0f78f1-6b78-474f-8391-3222511xxxxx in pronet.conf file and restart TrueSight Infrastructure Management server. Use command pw email2event -y to encrypt the Client key(secret).
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 4813ef1c-5e44-469d-bee8-cdabxxxxxxx is invalid. SMEDetailedMsg: Provide correct value for pronet.email2event.mailapp.tenantid (Tenant/Directory Id) in pronet.conf and restart TrueSight Infrastructure Management server.
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 pronet.email2event.mailserve for username in pronet.conf and restart TrueSight Infrastructure Management server.
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 pronet.email2event.folder name in pronet.conf and restart TrueSight Infrastructure Management server. 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.folder as inbox/email2event/xyz.
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: DigiCert SHA2 Secure Server CA DigiCert Global Root CA Microsoft Azure TLS Issuing CA 01 DigiCert Global Root G2 Import all the certificate in TrueSight Infrastructure Management server using command pw email2event -i. You can use keytool command to view the required certificates details in keystore %BPPM_SERVER_HOME%/pw/pronto/conf/pnserver.ks. get2net is the default store password for keystore pnserver.ks.
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: DigiCert SHA2 Secure Server CA DigiCert Global Root CA Import all the certificate in TrueSight Infrastructure Management server using command pw email2event -i. You can use keytool command to view the required certificates details in keystore %BPPM_SERVER_HOME%/pw/pronto/conf/pnserver.ks. get2net is the default store password for keystore pnserver.ks.
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: Microsoft Azure TLS Issuing CA 01 DigiCert Global Root G2 Import all the certificate in TrueSight Infrastructure Management server using command pw email2event -i. You can use keytool command to view the required certificates details in keystore "%BPPM_SERVER_HOME%/pw/pronto/conf/pnserver.ks". get2net is the default store password for keystore pnserver.ks.
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 3d0f78f1-6b78-474f-8391-3222511xxxxx expired. SMEDetailedMsg: Client(secret) key for application 3d0f78f1-3d0f78f1-6b78-474f-8391-3222511xxxxx expired. Please generate new client key on Azure portal. Provide encrypted value for newly generated Client Key(secret) in pronet.conf file and restart TrueSight Infrastructure Management server. Use command pw email2event -y to encrypt the Client key(secret).
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 mfa@bmc365test.com does not have access to the application with provided clientId 3d0f78f1-6b78-474f-8391-3222511xxxxx 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.

Limitation

A dedicated email account is required.
Only IMAP protocol is supported.
IMAP protocol is also supported over SSL or TLS.
There is no proxy support in connecting to the email server.
NTLM authentication is not supported.
The configured user account must have read and write permission for the configured folder.
Email servers with HTTP access are not supported.
The cell process must be running to create events.
Events that are created are assigned to priority 5.

Limitation for Microsoft office 365 account

A dedicated email account is required.
OAuth2.0 protocol is supported.
There is no proxy support in connecting to the email server.
The application created must have Microsoft Graph read and write permission.
The configured user account must have read and write permission for the configured folder.
The cell process must be running to create events.
Events that are created are assigned to priority 5.

Setting up unread emails as events

To configure the application in Azure Portal for Microsoft Office 365

Downloading Microsoft certificates

To configure an email as an event

Troubleshooting while configuring OAuth 2.0 authorization

On this page