Simple Network Management Protocol (SNMP) Trap Adapter

The Simple Network Management Protocol Trap adapter as a trap generator to send notification through SNMPv1 traps to SNMP management stations about business process progress or as a trap receiver to start a business process upon receipt of an incoming SNMPv1 trap.

The following table provides an overview of the SNMP Trap adapter:

Category	Description
System name	None
Graphical Process Modeler (GPM) category	None
Description	You can use the SNMP Trap adapter in either of the following two ways: SNMP trap generator – The SNMP Trap adapter used as a trap generator enables business processes to send notifications through SNMPv1 traps to SNMP management stations about business process progress or faults. For more information, see How the SNMP Trap Adapter Works as a Trap Generator. SNMP trap receiver – The SNMP Trap adapter used as a trap receiver, while listening on a specified port, starts a business process upon receipt of an incoming SNMPv1 trap. For more information, see How the SNMP Trap Adapter Works As a Trap Receiver.
Preconfigured?	No
Requires third-party files?	SIv1_snmp4_10.jar
Platform availability	All supported Sterling B2B Integrator platforms
Related services	No
Application requirements	No
Initiates business processes?	No
Invocation	Runs as part of a business process.
Restrictions	See Requirements.

Requirements

To set up and use the SNMP Trap adapter, you should understand SNMP concepts, such as how to generate and receive traps, especially enterprise trap definitions.

The SNMP Trap adapter has the following limitations:

Supports the receipt and generation of SNMPv1 traps only
Does not support polling by an SNMP manager, because the SNMP Trap adapter is not a full SNMP agent
Does not support SNMP Get or Set commands
If you want to generate a custom trap, you may need to create a Management Information Base (MIB) definition for the custom trap, if one is not already defined in the SNMP manager
When using the SNMP Trap adapter as a trap generator, there is no guarantee that the SNMPv1 trap will be received, and there is no way to confirm that the trap has been received
To verify that traps generated by the SNMP Trap adapter are being received, use the SNMP Trap adapter as a trap receiver

How the SNMP Trap Adapter Works as a Trap Generator

SNMP was designed to be an application-level protocol that is part of the TCP/IP suite and runs over the User Datagram Protocol (UDP). Because SNMP relies on UDP, which is a connectionless protocol, SNMP is connectionless. Therefore, no ongoing connections are maintained between a management station and its agents. Each exchange is a separate transaction.

Because UDP is connectionless, there is no guarantee of delivery. SNMPv1 does not acknowledge traps; the SNMP trap generator reports success to the business process even when the trap is not received by the SNMP management stations. This condition prevents a business process from halting in the event the SNMP trap generator fails.

Note: To increase the chances of delivery, you can configure the SNMP trap generator to send multiple traps to the same SNMP management station.

The SNMP trap generator does not require a document for input; the adapter obtains all inputs through business process parameters that are set either during adapter configuration, business process definition, or at run time.

The following steps summarize how the trap generator works:

The business process starts the trap generator, using the following business process parameters:
- SNMP generic trap type
- Specific trap code
- Associated trap data
- One or more SNMP management station addresses (IP address and port number)
The trap generator creates the trap and sends it to each SNMP management station address specified in step 1.
The trap generator returns the status of Success to the business process, regardless of whether the trap was generated and received successfully. When trap generation fails, the status report indicates the cause of the failure.
View the status report in Sterling B2B Integrator by selecting Business Process > Monitor > Current Processes and then clicking the ID of the appropriate business process.

The following figure shows how the SNMP Trap adapter as a trap generator communicates with an SNMP manager or trap receiver during a business process:

SNMP Trap Adapter communication

Example

For example, you can use an SNMP management station to monitor your network. To monitor the progress of a business process running inside Sterling B2B Integrator, configure a trap generator with your SNMP management station as a trap receiver. Configure the trap generator to send an SNMP trap message when specific events occur.

The following steps summarize how the trap generator works in the context of this example:

Configure the trap generator within Sterling B2B Integrator.
You can also specify the needed information just before starting the business process. If you specify the information before starting the business process, you will override any values specified in the adapter configuration.
When the business process needs to inform an SNMP management station of an event, it starts the trap generator.
The trap generator takes the trap information, generates an SNMP trap message, and sends it to all the specified trap receivers.
The trap generator creates a status report and returns a status of Success to Sterling B2B Integrator.
Sterling B2B Integrator performs the next step in the business process.

Implementing the SNMP Trap Adapter as a Trap Generator

To implement the SNMP Trap adapter as a trap generator, complete the following tasks:

Create an SNMP Trap adapter configuration. For information, see Managing Services and Adapters.
Configure the SNMP Trap adapter. For information, see Configuring the SNMP Trap Adapter as a Trap Generator.
Use the SNMP Trap adapter in a business process.

Configuring the SNMP Trap Adapter as a Trap Generator

When configuring the SNMP Trap adapter, you are defining the SNMP management stations to which the trap has to be sent and the type of trap.

Because this is a stateless adapter, you can use a single configuration of the adapter to send different types of traps to different management stations in multiple business processes.

When including trap-related information, use multiple configurations of the SNMP trap generator. The configuration of trap-related variables must include a named process data parameter that contains the value to be sent for that variable. This parameter can be different between business processes.

CAUTION:

Because the SNMP Trap adapter always returns a status of Success, it can be easy to overlook errors in trap configuration. Remember to check the status report of the adapter to verify whether the trap generation was successful. The SNMP Trap adapter always generates a status report, even when the trap generation is successful. When trap generation fails, the status report indicates the cause of the failure.

To configure the SNMP Trap adapter, you must specify settings for the following fields in Sterling B2B Integrator:

Note: The field names in parentheses represent the corresponding field names in the GPM. This information is provided for your reference.

Field	Description
Name	Unique and meaningful name for the adapter configuration. Required.
Description	Meaningful description for the adapter configuration, for reference purposes. Required.
Select a Group	Select one of the options: None – You do not want to include this configuration in a group at this time. Create New Group – You can enter a name for a new group in this field, which will then be created along with this configuration. Select Group – If you have already created one or more groups for this service type, they are displayed in the list. Select a group from the list.
Trap Receivers (trapReceivers)	List of SNMP management stations to which the trap is sent. Specify as a comma- or semicolon-delimited list of host:port strings representing SNMP management stations. Specify the same address multiple times to send multiple trap messages to the same address. Required. For example, `IPAddress:Port,` where `IPAddress` is the IP address of the host and `Port` is the port number of the host on which the SNMP manager is running. The port is optional, unless the SNMP manager is running on a nonstandard port. The default value is 162.
Community Name (community)	Access environment for a group of network management stations. If left blank, defaults to `public`.
Enterprise OID (enterpriseOID)	For generic traps, the object ID of the system generating the trap. For enterprise traps, the valid object ID of the management authority that defined the trap. Value is a valid object ID of an SNMP Management Information Base (MIB) object representing an enterprise. Defaults to the IBM® enterprise OID (1.3.6.1.4.1.1733).
Generic Trap Type (genericTrap)	Type (value) of a generic SNMP trap. Required. Values are 0 - 5. Use 6 for enterprise or custom traps. The generic traps are fixed and new ones cannot be defined. The following is a list of the trap types and their corresponding values: coldStart (0) warmStart (1) linkDown (2) linkUp (3) authenticationFailure (4) egpNeighborLoss (5)
Specific Trap Type (specificTrap)	Type code for an enterprise trap. Use this in conjunction with the enterprise OID to identify (or decode) the trap. You can define multiple enterprise traps. Required for enterprise traps. Value is a valid integer representing an enterprise trap. Value for generic traps is 0.
Variable OID #`n` (variableOID_n)	Object ID of the trap variable in the MIB file, a valid MIB object ID. Specify the value through the parameter Process Data Param #`n.`
Variable Type `#n` (variableType_n)	Type of MIB object, specified in variable OID `#n`. Values are NULL, Integer, OctetString, object ID. The SNMP Trap adapter supports up to six of these name-value pairs to enable passing of trap variables.
Process Data Param `#n` (procDataParam_n)	Name of the process data parameter that contains the value for the trap variable. Values should be parseable into the type specified in Variable Type `#n`.

How the SNMP Trap Adapter Works As a Trap Receiver

The SNMPv1 trap receiver enables Sterling B2B Integrator to receive an SNMPv1 trap and start a business process to handle the trap. The trap receiver converts all the information in the SNMPv1 trap message into business process parameters and passes these to the designated business process. The SNMP Trap adapter, working as a trap receiver, is inbound only and does not respond to the SNMP agent or trap generator.

The SNMP trap receiver is not started inside a business process; therefore it does not support input data from Sterling B2B Integrator. The only input to the trap receiver is the incoming SNMPv1 trap message. The SNMP trap receiver sends no document to the business process that is running.

You can configure multiple configurations of the SNMP trap receiver to listen on different ports, and a different business process can be associated with each configuration. You can use the SNMP trap receiver to receive generic as well as custom traps. There is no limit on how many variable bindings the incoming trap can contain.

Note: Because the configuration for an SNMP trap receiver is not started within a business process, the configuration cannot be overridden.

The SNMP trap receiver operates over UDP; there is no guarantee that a trap will be received by Sterling B2B Integrator. SNMPv1 traps are not acknowledged, so there is no confirmation message sent to the SNMP agent from which the trap was received.

The following steps summarize how the trap receiver works:

The SNMP trap receiver receives an incoming SNMPv1 trap.
The trap receiver passes trap parameters as business process parameters to Sterling B2B Integrator and starts a related business process with the business process parameters for the trap.
The trap receiver continues to start business processes as it receives requests.

The following figure shows how the SNMP Trap adapter works as a trap receiver:

How the SNMP Trap adapter works as a trap receiver

Example

You can use the SNMP trap receiver to receive SNMPv1 traps that have been generated from either an SNMP trap generator or an external SNMP manager. The SNMP trap generator in one installation of Sterling B2B Integrator may generate a trap message to an SNMP Trap receiver in another installation of Sterling B2B Integrator.

The following steps explain how the SNMP Trap adapter works as a trap receiver:

Configure the SNMP trap receiver.
The trap receiver starts listening for SNMPv1 traps on the specified port.
When receiving a trap message, the trap receiver checks the community name in the incoming trap message against any included/excluded communities specified in the trap receiver configuration.
After the filter rules have been applied, and the incoming trap message meets the criteria, the trap receiver starts the specified business process.

Business Process Variables

The following table contains process data variables for business processes started from the trap receiver. Multiple variables may be passed with any SNMP trap. The Name/Value process data variables always come in pairs.

Variable	Description
SNMP_ENTERPRISE_OID	Enterprise object ID. Unique ID for the enterprise.
SNMP_SPEC_TRAP_CODE	Unique trap ID for a specific Management Information Base (MIB). Can have any meaning that the enterprise specifies.
SNMP_GENERIC_TRAP_CODE	Predefined system trap.
SNMP_SENDING_IP	IP address of the trap sender.
SNMP_TIMESTAMP	Amount of time the trap sender has been running.
SNMP_RECEIVED_TIME	Time the trap was received.
VARIABLE_OID_n	Object ID of the nth variable passed with the trap.
VARIABLE_VALUE_n	Value of the nth variable passed with the trap.
SNMP_COMMUNITY_NAME	Community name in the incoming trap message.
VARIABLE_TYPE_n	Type of the nth variable passed with the trap (Octet String, Integer, Null, or Object ID).

Implementing the SNMP Trap Adapter As a Trap Receiver

To implement the SNMP Trap adapter as a trap receiver, complete the following tasks:

Create an SNMP Trap adapter configuration. For information, see Managing Services and Adapters.
Configure the SNMP Trap adapter. For information, see Configuring the SNMP Trap Adapter As a Trap Receiver.
Use the SNMP Trap adapter in a business process.

Configuring the SNMP Trap Adapter As a Trap Receiver

To configure the SNMP Trap adapter, you must specify settings for the following fields in the Sterling B2B Integrator:

Note: The field names in parentheses represent the corresponding field names in the GPM. This information is provided for your reference.

Field	Description
Name	Unique and meaningful name for the adapter configuration. Required.
Description	Meaningful description for the adapter configuration, for reference purposes. Required.
Select a Group	Select one of the options: None – You do not want to include this configuration in a group at this time. Create New Group – You can enter a name for a new group in this field, which will then be created along with this configuration. Select Group – If you have already created one or more groups for this service type, they are displayed in the list. Select a group from the list.
Trap Receiver Port	Port number on which this configuration of the trap receiver listens for SNMPv1 traps.
Business Process Name	Business process name to be started upon receipt of the SNMPv1 trap.
Include Communities	Comma- or semicolon-separated list of valid SNMP community names. The trap receiver filters incoming SNMPv1 trap messages based on community names. Any incoming messages that do not match an entry in the list of valid community names are discarded. A wildcard of `*` indicates that all community names are to be included. All discarded trap messages are logged in the system log.
Exclude Communities	Comma- or semicolon-separated list of valid SNMP community names. The trap receiver filters incoming SNMPv1 trap messages based on any excluded community names on this list. Any incoming messages that match an entry in the list of excluded community names are discarded. A wildcard of `*` indicates that all community names are to be excluded. All discarded trap messages are logged in the system log. Optional; if left blank, no community names are excluded.

Precedence Rules

You must specify a list of valid community names when configuring the trap receiver. If a community name contained within a trap message does not match the list of included names, or matches an excluded name, the designated business process does not start. The trap receiver logs a message containing the unauthorized community name and the associated trap message.

The following rules of precedence apply to the list of included and excluded community names:

Excluded community names take precedence over included names.
If the same name appears in both lists, incoming traps with this name are discarded.
If the included list is set to a wildcard and the excluded list has a community name, all community names are allowed except for the one in the excluded list.