Setting up and configuring the ITPAM Trigger feature.

Document ID : KB000049580
Last Modified Date : 14/02/2018
Show Technical Document Details

Description:

Triggers in ITPAM allow for certain activities, such as receiving an email, to kick off a Process run.

ITPAM Triggers are disabled at both Environment and Orchestrator levels by default.

Solution:

Enable ITPAM Triggers:

  1. Open Configuration Browser and click on the Environment and lock the Environment using option in right-click menu.

  2. Go to Triggers tab on the right.

  3. Select Inherit from Domain option from the drop-down in the Status field for the trigger you want to enable.

    Figure 1

    NOTE: You can also select Enable for the Triggers you want enabled here. The filters which are setup in Domain will NOT be inherited to Environment in that case and new filters need to be created for the selected Environment.

  4. Click on the Orchestrators palette on the bottom left. Choose the Orchestrator you want the trigger enabled from the list of Orchestrators and lock the Orchestrator.

  5. Go to Triggers tab on the right.

  6. Select Inherit from Environment option from the drop-down.

    Figure 2

    NOTE: You can also select Enable for the Triggers you want enabled here. The filters which are setup in Environment or inherited to Environment from Domain will NOT be inherited to this Orchestrator in that case and new filters need to be created for the selected Orchestrator.

  7. Save the configuration.

  8. Unlock the Orchestrator.

  9. Also unlock the Environment.

Setup ITPAM Triggers:

Filters for ITPAM triggers can be set at Domain level and inherited to Environments and Orchestrators. Optionally Environments and even Orchestrators can have their own set of filters for Triggers which will override the filters set at higher levels.

Steps below show examples of setting up trigger at the Domain level. Switch view to Configuration Browser, Lock the Domain and click on Triggers tab on the right before setting up the filters for Triggers. The same steps can be use to setup ITPAM Triggers at any level.

Setup SNMP Trigger:

ITPAM Processes can be started using SNMP traps by configuring SNMP Trigger Properties. Once SNMP Trigger is enabled and filters are added to trigger properties, ITPAM Orchestrator will start listening on port 162 (by default) for SNMP Traps. Any SNMP trap that matches the filtering criteria will trigger the corresponding process. The default 162 port can be changed by modifying the value of the following property in <itpam_install_dir>/server/c2o/.config/OasisConfig.properties file:

oasis.snmptrigger.service.port=162

You will need to restart ITPAM Service after changing the port.

SNMP Trigger Properties Window has options to Add [ Figure 3 ], Delete [ Figure 4 ] and Edit filters. Following fields are available in a Filter for SNMP Trigger:

Description: Small description of the filter which is being configured.

Source IP: IP Address of the source of SNMP trap in CIDR format. Eg: 124.11.11.0/24 will match source IPs from 124.11.11.1 to 124.11.11.255. To accept traps from all sources put 0.0.0.0/0 in this field.

Trap OID: Regular expression matching the Enterprise OID of the trap. Enterprise OID identifies the managed object that generates the trap. Leave blank to accept trap with any OID.

Payload Match: Regular expression to match any of the payload values of the trap. Leave blank to accept trap with any content in payload.

Process Path: Full path of the Process to run if the filter criteria match.

NOTE: Filters higher on the list will have precedence. You can change the filter precedence by using Up and Down arrows.

Figure 5

The example above will start "/Test/RunNotepad" Process if a trap is received from a Class A subnet 138.0.0.0/8 with Enterprise OID that matched the regular expression 1.2.4.* and at least one payload value that matches the literal string "Test Payload for trigger".

Once the required filters are configured, hit Apply and Save the configurations.

There are a set of variables that are created in the instance of Process triggered for a matching SNMP trap. The variables are Process level variables and are populated under SNMP page in Process Dataset. These variables are as follows:

SenderAddress: IP Address of the source.

AgentIPAddres: IP Address of the SNMP Agent, if available in the trap.

SNMPVersion: Version of SNMP trap.

ErrorIndex: Error Index of the trap.

AgentUptime: Uptime of the agent sending the trap.

EnterpriseOID: OID of managed object that generated the SNMP trap.

PayloadOIDs: OIDs present in the payload of the trap. This is an ITPAM String Array type variable.

PayloadValues: Corresponding values in payload of the OIDs in PayloadOIDs. This is also an ITPAM String Array type variable.

Setup Mail Trigger:

ITPAM Processes can also be started by using Email triggers. Once Mail Trigger is enabled and required parameters are added to trigger properties, ITPAM Orchestrator will start polling the Mail Server for new emails on a particular account and trigger a process with some data from the Email. ITPAM Mail Trigger requires IMAP enabled on the mail server. Mail Trigger currently does not support POP3 Protocol. If your corporate policies do not allow enabling IMAP protocol on the mail server and you need to configure Mail Trigger, setup an additional mail server dedicated to this function and forward the emails that require to trigger ITPAM Processes to an account in the new server.

Triggering emails can be sent with email messages or attachments as specified in "Trigger XML content" section. An acknowledgement email is sent back to the sender if an email with either valid message body or attachment is received from the IMAP server. If message body or the attachment does not contain a valid XML content for triggering a Process, the Process defined as Default process handler will be started.

Mail Trigger Properties Window has following fields that need to be configured:

Secure SMTP connection: Option to enable secure connection to mail server. This is checked by default. If your mail server does not allow secure connection, uncheck this option.

Default process handler: Full path of Process to start when an email is received in an account that ITPAM is configured to poll. This is used if valid XML content is not found in the message body or attachment of a triggering email. When this process is used, acknowledgement email is NOT sent to the sender. Leave this field blank if you want to ignore emails with no valid XML trigger content.

Incoming mail server (IMAP): Mail server hostname or IP Address for incoming emails. This server must have IMAP protocol enabled. POP3 is currently NOT supported for Mail Trigger.

User Name: Username to connect to the IMAP server. Some servers might require using full email address as usernames rather than aliases. Eg: itpamadmin@ca.com instead of simply itpamadmin.

Password: Password of the user configured above.

IMAP server port: TCP port of IMAP server. Put 143 if default IMAP port is being used in your environment. Check with system admin for the right port if non-default port is used or secure communication is setup on a different port.

Frequency (sec): Polling interval in seconds. This is the interval ITPAM will wait to poll the IMAP server for new incoming emails.

Outgoing mail server and SMTP server port: These are parameters for outgoing emails which are used to send acknowledgement emails, when a triggering email with valid XML content in message body or attachment is received.

Figure 6

There are a set of variables that are created in the instance of Process triggered for an incoming email. The variables are Process level variables and are populated under SMTP page in Process Dataset.

These following variables are present when the triggering email has a valid XML content in either the message body or the attachment:

senderAdd: Email address of the account from which the triggering email is sent.

senderTime: Time when the email was sent. This is corresponding to the email server time rather than ITPAM Orchestrator time.

<additional_parameters>: Other additional parameters that were passed under the <params> tag in the triggering XML content.

These following variables are present when the triggering email does not have a valid XML content in neither the message body nor the attachment:

senderAdd: Email address of the account from which the triggering email is sent.

senderTime: Time when the email was sent. This is corresponding to the email server time rather than ITPAM Orchestrator time.

MailBody: The complete content of the email.

Setup File Trigger:

ITPAM Processes can also be started using File Trigger. Once enabled and configured, ITPAM Orchestrator will look for existence of a file at the location and at intervals defined by the user and trigger ITPAM processes. When a matching file is found, ITPAM tries to parse the content and trigger the process specified in the file content. For the format of the file content refer to the "Trigger XML content" section. If process is successfully started, the triggering file is moved to Processed directory and if the process cannot be started, the triggering file is moved to Error directory and a *.err file is created along with it which gives a summary of why the trigger failed.

File Trigger Properties Window has following fields that need to be configured:

Input directory: Directory where ITPAM should look for new files for triggering processes. This can be a full path or a relative path starting with a dot "." (eg: ./triggers). If relative path is used the location of the directory would be relative to <itpam_install_dir>/server/c2o directory. So in the example above, triggering files should be present in <itpam_install_dir>/server/c2o/triggers folder. The input directory folder must be created manually and have write permissions for users allowed to push trigger files in this folder. It is often tied to a FTP folder to allow remote triggering.

Processed directory: Directory where all files that successfully triggered processes are moved. This can also be a full path or a relative as for Input directory. This directory will be created by ITPAM if not already present. Old files will be replaced if files with same names are used.

Error directory: Directory where all files that failed to trigger processes are moved. This can also be a full path or a relative as for Input directory. This directory will be created by ITPAM if not already present. Old files will be replaced if files with same name are used.

Stability timer (sec): Minimum number of seconds since last modification before a file can be picked up for processing.

Frequency (sec): Scanning interval for input directory in seconds.

Input file name pattern: Pattern to match the file name for triggering processes. Eg: setting this to " .*.trigger" would mean that the trigger will only look for files with extension .trigger.

Figure 7

Once the required filters are configured, hit Apply and Save the configurations.

There are a set of variables that are created in the instance of Process triggered for a matching File. The variables are Process level variables and are populated under FileTrigger page in Process Dataset. These variables are as follows:

FileName: Name of the file which had the content to trigger the process.

<additional_parameters>: Other additional parameters that were passed under the <params> tag in the triggering XML content of the file.

Trigger XML content:

Mail and File Triggers require content of the triggering email or file with certain information in a valid XML format in order to trigger a Process in ITPAM as in the example below. For Mail Trigger you can put this content as the body of the email or as an attachment. If you send the content as body, you cannot add more content other than what is required to trigger a Process. For File Trigger, the triggering file should have the entire content.

<c2oflow version="1.0">
      <flow name="/Test/RunNotepad" action="start">    <!-- Full path of the process -->
      <auth>
            <user>itpamadmin</user>           <!-- ITPAM Username -->
            <password>itpamdemo</password>    <!-- ITPAM Password -->
      </auth>
      <options>                               <!-- Optional parameters for delayed execution -->
            <startDate></startDate>           <!-Start Date in [MM/dd/yyyy] format -->
            <startTime></startTime>           <!-- Start Time in [HH:mm] format; HH in 24 hrs -->
      </options>
      <params>                                <!-- Process initialization parameters, if needed -->
            <param name="ParamOne">Using file trigger</param>
            <param name="ParamTwo">Second parameter from file trigger</param>
      </params>
      </flow>
</c2oflow>   

SOAP Trigger:

ITPAM Orchestrator exposes WebServices that allow external applications to start and control Processes in ITPAM library. The WebServices methods and parameters exposed are described in the WSDL, which can be retrieved from the URL below:

   http://<itpamserver:port>/itpam/soap?wsdl  

In addition to that, there are a few example scripts that are present in <itpam_install_dir>/server/c2o/.c2orepository/public/scripts/trigger folder. These scripts use SOAP calls to ITPAM Orchestrator to start processes.