ServiceNow monitor adapter
The monitor adapter for ServiceNow checks for messages in a specified account on a POP3 mail server. The account information is designated in the configuration node for the adapter in Grid Manager. This adapter does not support multiple configuration nodes; however, multiple adapters can be configured within Grid Manager, each with a unique configuration.
The ServiceNow application monitor adapter is a mail-based monitor, which checks for messages on a specified account on the POP3 mail server. Ensure that the email notifications are configured for appropriate events on the Service-now application. You configure an adapter in TrueSight Orchestration Grid Manager. The configuration provides information about how the adapter interacts with the Service-now application.
The form view provides an easy-to-use interface for configuring adapters. The form view prevents human errors that might occur as a result of copying the configuration XML from the adapter user documentation into the UI when configuring an adapter. You can switch to the XML view to configure those elements and attributes that are not available as fields or to configure all the elements and attributes by using XML only. However, after you switch to the XML view, and save the configuration in the XML from that view, you cannot use the form view for modifying the configuration.
The following video (9:20) describes how to configure the ServiceNow monitor adapter.
https://www.youtube.com/watch?v=FBwILOKM4bA
To configure the monitor adapter
- Log on to the TrueSight Orchestration Grid Manager.
- To access the adapters page, click the Manage tab and then click the Adapters tab.
- In the Adapters in Repository list, select the bmc-adapter-service-now-monitor [conbaosnow:20.12.02.00] check box corresponding to the type of adapter to be added.
- Click Add to Grid to include the adapter in the Adapters on Grid list.
- Click Configure corresponding to the newly added adapter.
- On the Add an Adapter Configurationpage, perform the following sub-steps to configure the adapter by using the form view or skip to step 7 to configure the adapter by using the XML view:
- Enter a name for the adapter.
- Use ServiceNowMonitor as the actor adapter name, which is the default adapter name used by the processes in the AO-AD-ServiceNow module.
- Enter a description for the adapter.
- Under Properties, enter or select values for the configuration elements. Include all required elements indicated with an asterisk (*).
- (Optional) Click Switch to XML View and use the following steps to specify elements and attributes that are not in the form view.
(Optional) Configure the adapter in the XML view by using the following sub-steps:
Note
Switching to the XML view to specify those elements and attributes not included in the form means that you cannot thereafter use the form for modifying that configuration.
- Enter a name and a description for the adapter.
- Click Switch to XML View.
- On the Warning message that appears, click Switch View.
In the Properties text box, use XML format to enter the configuration elements and attributes, and then click OK.
Note
If the default value for an optional element is acceptable, omit the element. Do not include empty elements.
On the Warning message that appears, click Save.
The adapter configuration with settings is saved in the XML view permanently. The newly configured adapter is now listed in the Adapters on Grid list.
The following table describes the adapter configuration elements and attributes for the monitor adapter for Service-now that you can specify by using the form view, XML view, or both. You cannot use the form view to configure elements and attributes that do not have an entry in the UI label column.Configuration Node Elements - monitor adapter
UI label
Element
Description
Required
None
<config>
Specifies a container element for all other elements
Yes
Target
<target>
Specifies the host name or IP address of the POP3 server
Yes
Port
<port>
Specifies the port on which the pop3 server listens
Default value: 110No
User Name
<user-name>
Specifies the user name for the email account to be monitored
For example, if the email account being monitored is user.name@company.com, then the user name is user.name.Yes
Password
<password>
Specifies the password that corresponds to the specified
<user-name>
The password element can contain an encryption-type attribute.Yes
Encryption Type
encryption-type
Indicates whether the password specified is encrypted
Valid values: Base64, Plain (default)No
Javamail Debug
<javamail-debug>
Indicates that javamail debug message logging must be turned on
Valid values: true, false
In the absence of this element, a default value of false is assigned.No
Email Address
<email-address>
Specifies the email address of the account to be monitored
Yes
Protocol
<protocol>
Specifies the email protocol to be used
Valid value: pop3 (default)Yes
Refresh
<refresh>
Specifies the frequency, in seconds, to check for new messages
Valid format: Any valid integer
Default value: 300 (5 minutes)No
Mail Timeout
<mail-timeout>
Specifies the duration of time, in seconds, to maintain an established connection
Valid format: Any valid integer
Default value: 60 (1 minute)No
Connection Timeout
<connection-timeout>
Specifies the duration of time, in seconds, to wait when establishing a connection
Valid format: Any valid integer
Default value: 30No
Disable Auth Login
<disable-auth-login>
Prevents the use of a non-standard AUTHENTICATE LOGIN command with the IMAP servers
Valid values: true, false (default)No
Disable Auth Plain
<disable-auth-plain>
Prevents the use of AUTHENTICATE PLAIN command with the IMAP servers
Valid values: true, false (default)No
Delete After Read
<delete-after-read>
Determines whether a message can be deleted from the server after being read by the adapter
Valid values: true, false (default)Conditional; required if you want to use the
<max-messages-per-connection>
elementMax Messages Per Connection
<max-messages-per-connection>
Specifies the maximum number of messages to be pulled per connection attempt
If there are more messages on the server than the number specified, they will be retrieved during the next polling.
Valid format: Any number Default value: 20Conditional; used only when the
<delete-after-read>
is trueIgnore Attachments
<ignore-attachments>
Indicates whether attachments can be ignored and excluded from the adapter event
Valid values: true, false (default)No
Create Subdirectory
<create-subdirectory>
Indicates whether each attachment can be downloaded into a separate directory
Valid values: true, false (default)
Subdirectory name format: <attachment-download-directory>/<emailaddress>/message ID/timestamp of download in epoch time. Sample subdirectory value: /mail/downloads/user@company.com/Message1/1196967357No
Attachment Download Directory
<attachment-download-directory>
Specifies the path and directory into which attachments on monitored email messages will be downloaded.
Note
This directory must exist on each peer on which the adapter is enabled. If this directory is not present, the configuration is considered invalid and the adapter is not be enabled. In the absence of this element, attachments will be downloaded to the Java temp directory.
No
Attachment Overwrite Existing
<attachment-overwrite-existing>
Specifies whether to overwrite the existing attachment with the current one if the file name is same
Valid values: True, False (default)Note
If the
<create-subdirectory>
element is true, then the attachments are downloaded ignoring the<attachment-overwrite-existing>
value.No
Attachment Ttl
<attachment-ttl>
Specifies the time for which an attachment is permitted to reside in the download directory before being deleted
The value is specified as a numeric value and time designator.
Valid time designators: m - minutes, h - hours, d - days
By default, 10d will be assigned, allowing attachments to remain in the directory for 10 days.No
Max Attachment Size
<max-attachment-size>
Specifies the maximum file size, in MB, that can be downloaded from a mail message
Note
This value is defined per attachment; the total of all files can be greater, provided each file is less than or equal to this value. By default, 10 MB is assigned.
No
Max Pool Threads
<max-pool-threads>
Specifies the maximum number of threads to be used to download attachments in parallel
By default, 1 is assigned.No
Delete Attachments On Exit
<delete-attachments-on-exit>
Specifies whether to delete all downloaded attachments when the adapter is stopped or disabled
Valid values: True, False (default)No
Disk Cleanup Interval
<disk-cleanup-interval>
Specifies the interval at which the attachments that have exceeded the
<attachment-ttl>
period must be deleted
The value is specified as a numeric value and a time designator.
Valid time designators: m - minutes, h - hours, d - days
By default, 10m is assigned, initiating cleanup after every 10 minutes.No
None
<file-name-filter>
Contains one or more
<file-name>
elements
Only file names that satisfy the criteria specified using the<file-name>
element can be downloaded.Conditional; required if you specify the
<file-name>
elementFile Name Filter
<file-name>
Specifies the file name filter for the attachment files that can be downloaded
One or more file name filters can be defined using wildcard characters. You can use an asterisk (*) or question mark character to represent multiple characters, respectively, when defining a file name filter.
By default, an attachment with any file name is downloaded.No
None
<file-type-filter>
Contains one or more
<file-type>
elements
Only file types specified by using the<file-type>
element can be downloaded.Conditional; required if you specify the
<file-type>
elementFile Type Filter
<file-type>
Specifies the file type of an attachment that can be downloaded
You can specify one or more file types.
Sample values: doc, xls, xml, pdf, html, exe
By default, an attachment of any type will be downloaded.No
Use Ssl Certificate
<use-ssl-certificate>
Specifies whether SSL certificates are used for authentication
Valid values: True, False (default)No
Allow Unsigned Certificates
<allow-unsigned-certificates>
Specifies whether unsigned certificates are permitted for the SSL authentication
Valid values: True, False (default)Note
This element is ignored unless the value of the
<use-ssl-certificate>
element is True.No
Install Certificate
<install-certificate>
Specifies whether to update the default keystore file (<java.home>\jre\lib\security\cacerts) with the certificates sent by the target URL during the SSLHandshake
Valid values: True, False (default)Note
To successfully install certificates, you must ensure that the peer that will execute the request must have read or write access to the keystore file.
Certificates will be uninstalled when the adapter is disabled on the peer. If a BMC Run Book Automation peer is uninstalled without the adapter being disabled, any certificates installed by the adapter will remain. If the verification of a certificate fails, that certificate will not be installed.
Note
This element is ignored unless the
<use-ssl-certificate>
value is True.No
Passphrase
<passphrase>
Specifies the passphrase for the keystore file, used for installation of certificates.
Note
This value must match the passphrase in the keystore.
The passphrase can be changed by using a key tool. If a change is made, this value must be updated to reflect the new passphrase.
Default value: changeit.Note
This element is ignored unless the
<use-ssl-certificate>
value is True.No
The XML template for the monitor adapter configuration is given in the following figures:
Sample XML template for configuring the monitor adapter with a plain password
<config>
<target>pop3mailserver.com</target>
<user-name>user.name</user-name>
<password>password</password>
<javamail-debug>false</javamail-debug>
<email-address>user.name@xyz.com</email-address>
<protocol>pop3</protocol>
<refresh>5</refresh>
<mail-timeout />
<connection-timeout>60</connection-timeout>
<disable-auth-login>false</disable-auth-login>
<disable-auth-plain>false</disable-auth-plain>
<delete-after-read>false</delete-after-read>
<max-messages-per-connection>20000</max-messages-per-connection>
</config>
Sample XML template for configuring the monitor adapter with an encrypted Base64 password
<config>
<target>pop3mailserver.com</target>
<user-name>user.name</user-name>
<password encryption-type = "Base64">cGFzc3dvcmQ=</password>
<javamail-debug>false</javamail-debug>
<email-address>user.name@xyz.com</email-address>
<protocol>pop3</protocol>
<refresh>5</refresh>
<mail-timeout />
<connection-timeout>60</connection-timeout>
<disable-auth-login>false</disable-auth-login>
<disable-auth-plain>false</disable-auth-plain>
<delete-after-read>false</delete-after-read>
<max-messages-per-connection>20000</max-messages-per-connection>
</config>
A sample event generated by the monitor adapter for the TrueSight Orchestration adapter manager is given in the following figure:
Sample monitor adapter event
<email-message>
<from>
<email-address>demo-mail@service-now.com</email-address>
</from>
<sent-date>Wed May 26 17:59:18 UTC 2010</sent-date>
<sent-epoch-milliseconds>1274896758000</sent-epoch-milliseconds>
<reply-to>
<email-address>demo-mail@service-now.com</email-address>
</reply-to>
<recipients>
<email-address>user.name@xyz.com</email-address>
</recipients>
<subject>--The Change has been approved--</subject>
<body>
<bodypart>--This email contains the details for a change record created.--
Approval: Rejected
Approval history:
Created by: admin
Description:
Number: CHG0030820
Correlation ID: My30
Ref:MSG0006239
</bodypart>
</body>
</email-message>
Enabling custom logging
To enable custom logging for the adapter, you must specify a log file name. You can also provide additional parameters for logging.
Note
You must be using TrueSight Orchestration version 8.1 or later to use the custom logging feature. These parameters will be ignored in earlier versions of TrueSight Orchestration Platform.
These parameters are available with supported adapter versions. See TrueSight Orchestration Content documentation for details.
- Log File Name: Provide a name for the log file.
This file will be stored in the AO_HOME/tomcat/logs directory. If Log File Max Backup Index value is greater than 0, the log file name is suffixed with the backup index. For example, if the parameter value is a.log, backup log files will have names, such as a.log.1, a.log.2. - Log File Size: Specify a size limit for the log file.
If the value specified for Log File Max Backup Index is greater than 0, when the specified size is reached, the current file is renamed with the suffix .1. Otherwise, the log file will be reset and over-written. The default value is 10MB. The available units are KiloBytes (KB), MegaBytes (MB) or GigaBytes (GB). - Log File Max Backup Index: Enter the maximum number of backup files allowed. The default value is 10.
- Log File Append: Select this option to append new log information to the existing information in the file. If unselected, the file will be overwritten with new log information.
Log Level: Enter the logging level using one of the following choices:
Logging level
Description
DEBUG
The most detailed logging level; logs low-level messages, normal execution, recoverable erroneous conditions, and unrecoverable erroneous conditions
INFO
(default)
Logs normal execution, recoverable erroneous conditions, and unrecoverable erroneous conditions
WARN
Logs recoverable erroneous conditions and unrecoverable erroneous conditions
ERROR
The least detailed logging level; logs only error conditions that are not usually recoverable
Encrypting an element's contents
You can add the attribute secure="true"
to an XML adapter element XML view to ensure that the element's contents is encrypted when displayed.
Note
You must be using TrueSight Orchestration Platform version 8.1 or later to use this encryption attribute.
Comments
Log in or register to comment.