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 BMC Atrium Orchestrator 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

  1. Log on to the BMC Atrium Orchestrator Grid Manager.
  2. To access the adapters page, click the Manage tab and then click the Adapters tab.
  3. 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.
  4. Click Add to Grid to include the adapter in the Adapters on Grid list.
  5. Click Configure corresponding to the newly added adapter.
  6. 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:
    1. Enter a name for the adapter.
    2. Use ServiceNowMonitor as the actor adapter name, which is the default adapter name used by the processes in the AO-AD-ServiceNow module.
    3. Enter a description for the adapter.
    4. Under Properties, enter or select values for the configuration elements. Include all required elements indicated with an asterisk (*).
    5. (Optional) Click Switch to XML View and use the following steps to specify elements and attributes that are not in the form view.
  7. (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.

    1. Enter a name and a description for the adapter.
    2. Click Switch to XML View.
    3. On the Warning message that appears, click Switch View.
    4. 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.

  8. 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: 110

    No

    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: 30

    No

    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> element

    Max 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: 20

    Conditional; used only when the <delete-after-read> is true

    Ignore 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/1196967357

    No

    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> element

    File 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 (question) 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> element

    File 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 BMC Atrium Orchestrator 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>

Was this page helpful? Yes No Submitting... Thank you

Comments