Web Event Service Webjects
The following Web Event Service (WES) webjects can be used in conjunction with a third-party MOM for handling Info*Engine events:
• Emit-Event
• Subscribe-Event
• Unsubscribe-Event
All Web Event Service webjects use the WEStype attribute value in the webject tag.
|
|
These webjects can be used only after your environment has been set up to use the Web Event Service.
|
Emit-Event
DESCRIPTION
Causes Info*Engine to send a named event through the Java Messaging Service (JMS) to be handled by any subscribers. When the execution of the webject completes successfully, an empty status group with a status of 0 is returned with a message stating that the event was successfully sent. If the execution of the webject is unsuccessful, an appropriate exception is thrown.
SYNTAX
<ie:webject name="Emit-Event" type="WES">
<ie:param name="DBUSER" data="username"/>
<ie:param name="EVENT" data="my_event"/>
<ie:param name="GROUP_IN" data="group1"/>
<ie:param name="GROUP_OUT" data="results"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="PRIORITY" data="numeric_value"/>
<ie:param name="PROPERTY" data="name=value"/>
<ie:param name="PUT_BOOLEAN" data ="[TRUE | FALSE]"/>
<ie:param name="PUT_BYTE" data ="byte"/>
<ie:param name="PUT_BYTES" data ="bytes"/>
<ie:param name="PUT_CHAR" data ="char"/>
<ie:param name="PUT_DOUBLE" data ="double"/>
<ie:param name="PUT_FLOAT" data ="float "/>
<ie:param name="PUT_INT" data ="int"/>
<ie:param name="PUT_LONG" data ="long"/>
<ie:param name="PUT_SHORT" data ="short"/>
<ie:param name="PUT_STRING" data ="string"/>
<ie:param name="TIME_TO_LIVE" data="minutes"/>
<ie:param name="TYPE" data="[InfoEngine | BytesMessage |
TextMessage | MapMessage | Unknown]"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
EVENT
|
PUT_BOOLEAN
|
DBUSER
|
|
PUT_BYTE
|
GROUP_IN
|
|
PUT_BYTES
|
GROUP_OUT
|
|
PUT_CHAR
|
PASSWD
|
|
PUT_DOUBLE
|
PRIORITY
|
|
PUT_FLOAT
|
PROPERTY
|
|
PUT_INT
|
TIME_TO_LIVE
|
|
PUT_LONG
|
SERVICE
|
|
PUT_SHORT
|
|
|
PUT_STRING
|
|
|
TYPE
|
|
DBUSER
Specifies the username to use when connecting to the MOM. If this parameter is specified, the parameter value takes precedence over any existing credentials mapping for the authenticated user, or any value specified in the
.wes.username and
.jms.username properties of the service that is used to connect to the MOM. For more information, see
Credentials Mapping for MOMs.
If this parameter is omitted, the mapped credentials for the Web Event Service (WES) are used. If no such mapping is found, then the mapped credentials for the Java Messaging Service (JMS) are used. If neither of these mapped credentials are found, then the value set in the .wes.username property is used. If the .wes.username property is not set, then the value set in the .jms.username property is used. If neither property is set and you do not specify a value for this DBUSER parameter, Info*Engine does not specify a username when connecting to the MOM, and an anonymous connection is attempted.
This parameter is optional.
EVENT
Specifies the LDAP distinguished name of the event to emit. The value is an LDAP distinguished name relative to a configured base URI. A syntax of <event_name>@<domain> is recommended to give additional meaning and avoid name conflicts. If relative, the cn= (common name attribute) is implicit if not explicitly specified.
This parameter is required.
GROUP_IN
Specifies the name of a group to be sent along with the event. This parameter should only be specified if the TYPE is InfoEngine. If GROUP_IN is specified and the TYPE is set to a different value, then GROUP_IN is ignored.
Multiple GROUP_IN values may be specified. A value of “*” causes the entire VDB to be sent. The default for this parameter is to send an empty VDB collection.
This parameter is optional.
GROUP_OUT
Specifies the name of the status group to create upon success. The default for this parameter is to create a group named emit-results.
This parameter is optional.
PASSWD
Specifies the password to use when connecting to the MOM. If this parameter is specified, the parameter value takes precedence over existing credentials mapping for the authenticated user, or any value specified in the
.wes.password and
.jms.password properties of the service that is used to connect to the MOM. For more information about credentials mapping, see
Credentials Mapping.
If this parameter is omitted, the mapped credentials for the Web Event Service (WES) are used. If no such mapping is found, then the mapped credentials for the Java Messaging Service (JMS) are used. If neither such mapped credentials are found, then the value set in the .wes.password property is used. If the .wes.password property is not set, then the value set in the .jms.password property is used. If neither property is set and you do not specify a value for this PASSWD parameter, Info*Engine does not specify a password when connecting to the MOM.
This parameter is optional.
TIME_TO_LIVE
Specifies in minutes how long the event should be valid. The default value for this parameter is 0, which is a special case indicating that the message does not expire.
This parameter is optional.
SERVICE
Specifies the name of the Info*Engine property set that is configured for connectivity to a specific JMS service. This allows you to configure more than one JMS service per Info*Engine Virtual Machine (VM).
This parameter is optional.
PRIORITY
Specifies an integer priority to be set on the outgoing messages. The valid range for JMS Queue priorities is from 0 – 9, with 4 the typical default value. Priorities are ignored by Info*Engine, but can be used by third-party software receiving events sent by Info*Engine. This parameter is optional.
PROPERTY
Specifies a name and value pair to set on the outgoing JMS message. These properties are ignored by Info*Engine, but can be used by third-party software. The format for the PROPERTY value is
name=value
where:
name—The property name.
value—The corresponding value of the property.
The default behavior for this parameter is to not set any additional properties on the outgoing message.
This parameter is optional.
PUT_BOOLEAN
Places a Java Boolean value into the JMS message. The value may be specified as True or False. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_BYTE
Places a single byte into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_BYTES
Places multiple bytes into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_CHAR
Places a single Java character into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_DOUBLE
Places a Java double value into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_FLOAT
Places a floating point number into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_INT
Places an integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_LONG
Places a long integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_SHORT
Places a short integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage or MapMessage.
PUT_STRING
Places an instance of java.lang.String into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, TextMessage, or MapMessage.
TYPE
Specifies the type of message to be sent by selecting the processor used to generate the outgoing message. Message types are case-sensitive.
The default value for this parameter is InfoEngine, which means that an Info*Engine request is serialized and placed in the queue. Serialized in this case can mean actual Java serialization or serialization of an Info*Engine request to XML (this is the case when BLOB data needs to be queued as well).
Possible message types are:
◦ InfoEngine—Used for Info*Engine to Info*Engine communication. VDB groups serialized are governed by the GROUP_IN parameter.
◦ BytesMessage—For outgoing messages, this type supports several PUT_type parameters for building a message that may be specific to a third-party recipient. Incoming messages are processed in the same manner as Unknown. The contents of a BytesMessage is supplied as BLOB data on an input stream to the calling task.
◦ TextMessage—Supports only a PUT_STRING parameter. Multiple PUT_STRING parameter values are concatenated together to create the outgoing TextMessage.
◦ MapMessage—For outgoing messages, this type supports several PUT_type parameters with values in the form of name=data, where name is the key used to place data in the MapMessage.
◦ Unknown—Turns BLOB data into a BytesMessage. For incoming messages, a new, empty Info*Engine request is created and the contents of the message are attached as BLOB data.
The following table indicates which PUT_type parameters can be specified with which message types:
|
BytesMessage
|
TextMessage
|
MapMessage
|
|
PUT_BOOLEAN
|
X
|
|
X
|
|
PUT_BYTE
|
X
|
|
X
|
|
PUT_BYTES
|
X
|
|
X
|
|
PUT_CHAR
|
X
|
|
X
|
|
PUT_DOUBLE
|
X
|
|
X
|
|
PUT_FLOAT
|
X
|
|
X
|
|
PUT_INT
|
X
|
|
X
|
|
PUT_LONG
|
X
|
|
X
|
|
PUT_SHORT
|
X
|
|
X
|
|
PUT_STRING
|
X
|
X
|
X
|
|
|
Support for the type STRING in BytesMessage actually causes the value of the string to be written as a byte array; it is not actually written as a string.
|
EXAMPLE
The following example emits a specified event to be handled by any subscribers:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Emit-Event" type="WES">
<ie:param name="DBUSER" data="$(@FORM[]dbuser[])"/>
<ie:param name="PASSWD" data="$(@FORM[]passwd[])"/>
<ie:param name="GROUP_IN" data="$(@FORM[]group_in[])"/>
<ie:param name="GROUP_OUT" data="$(@FORM[]group_out[])"/>
<ie:param name="EVENT" data="$(@FORM[]event[])"/>
<ie:param name="TIME_TO_LIVE" data="0"/>
<ie:param name="PRIORITY" data="$(@FORM[]priority[])"/>
</ie:webject>
To actually run this example, you need to provide a form where the DBUSER, PASSWD, GROUP_IN, GROUP_OUT, EVENT, and PRIORITY variables are identified.
Subscribe-Event
DESCRIPTION
Causes the Info*Engine process where this webject is executed to subscribe to listen for a particular event. When an event is caught, Info*Engine builds an execution environment from the request or available data and executes a configured task. When the execution of the webject completes successfully, an empty status group with the status of 0 is returned with a message relaying successful subscription to the event. If the execution of the webject completes unsuccessfully, an appropriate exception is thrown.
SYNTAX
<ie:webject name="Subscribe-Event" type="WES">
<ie:param name="DBUSER" data="username"/>
<ie:param name="EVENT" data="event_name"/>
<ie:param name="EXECUTE_TASK" data="task_name"/>
<ie:param name="FAILURE_TASK" data="task_name"/>
<ie:param name="GROUP_IN" data="event_handlers"/>
<ie:param name="GROUP_OUT" data="results"/>
<ie:param name="PASSWD" data="password"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
EVENT
|
DBUSER
|
|
EXECUTE_TASK
|
GROUP_OUT
|
|
FAILURE_TASK
|
PASSWD
|
|
GROUP_IN
|
SERVICE
|
DBUSER
Specifies the username to use when connecting to the MOM. If this parameter is specified, the parameter value takes precedence over any existing credentials mapping for the authenticated user, or any value specified in the
.wes.username and
.jms.username properties of the service that is used to connect to the MOM. For more information, see
Credentials Mapping for MOMs.
If this parameter is omitted, the mapped credentials for the Web Event Service (WES) are used. If no such mapping is found, then the mapped credentials for the Java Messaging Service (JMS) are used. If neither of these mapped credentials are found, then the value set in the .wes.username property is used. If the .wes.username property is not set, then the value set in the .jms.username property is used. If neither property is set and you do not specify a value for this DBUSER parameter, Info*Engine does not specify a username when connecting to the MOM, and an anonymous connection is attempted.
This parameter is optional.
EVENT
Indicates the LDAP distinguished name of the event for which to listen. The value is an LDAP distinguished name relative to a configured base URI. A syntax of <event_name>@<domain> is recommended to give additional meaning and avoid name conflicts. If relative, the cn= (common name attribute) is implicit if not explicitly specified.
This parameter is required if GROUP_IN is not supplied.
EXECUTE_TASK
Indicates the task to be executed upon event notification. This parameter is required if GROUP_IN is not supplied.
FAILURE_TASK
Indicates the task to be executed if EXECUTE_TASK is not executed. This parameter can only be specified if GROUP_IN is not specified. The default for this parameter is to log the error.
GROUP_IN
Specifies the name of a group from which to extract EVENT, EXECUTE_TASK and FAILURE_TASK. The group must have EVENT and EXECUTE_TASK columns. It can also have a FAILURE_TASK column. A subscription occurs for each row in the input group. This parameter is required if EVENT and EXECUTE_TASK are not specified.
GROUP_OUT
Specifies the name of the status group to be created upon success. The default for this parameter is to create a group named subscription-results. This parameter is optional.
PASSWD
Specifies the password to use when connecting to the MOM. If this parameter is specified, the parameter value takes precedence over existing credentials mapping for the authenticated user, or any value specified in the
.wes.password and
.jms.password properties of the service that is used to connect to the MOM. For more information see
Credentials Mapping for MOMs.
If this parameter is omitted, the mapped credentials for the Web Event Service (WES) are used. If no such mapping is found, then the mapped credentials for the Java Messaging Service (JMS) are used. If neither such mapped credentials are found, then the value set in the .wes.password property is used. If the .wes.password property is not set, then the value set in the .jms.password property is used. If neither property is set and you do not specify a value for this PASSWD parameter, Info*Engine does not specify a password when connecting to the MOM.
This parameter is optional.
SERVICE
Specifies the name of the Info*Engine property set that is configured for connectivity to a specific JMS service. This allows you to configure more than one JMS service per Info*Engine Virtual Machine (VM).
This parameter is optional.
EXAMPLE
The following example subscribes the current Info*Engine process to the specified event:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Subscribe-Event" type="WES">
<ie:param name="DBUSER" data="$(@FORM[]dbuser[])"/>
<ie:param name="PASSWD" data="$(@FORM[]passwd[])"/>
<ie:param name="EVENT" data="$(@FORM[]event[])"/>
<ie:param name="GROUP_IN" data="$(@FORM[]group_in[])"/>
<ie:param name="GROUP_OUT" data="$(@FORM[]group_out[])"/>
</ie:webject>
To actually run this example, you need to provide a form where the DBUSER, PASSWD, EVENT, GROUP_IN, and GROUP_OUT variables are identified.
Unsubscribe-Event
DESCRIPTION
Causes Info*Engine to cease listening for a particular event that is currently being monitored. When the execution of the webject completes successfully, an empty status group with the status of 0 is returned with a message relaying successful unsubscription from the event. If the execution of the webject completes unsuccessfully, an appropriate exception is thrown.
SYNTAX
<ie:webject name="Unsubscribe-Event" type="WES">
<ie:param name="EVENT" data="event_name"/>
<ie:param name="GROUP_OUT" data="results"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
EVENT
|
|
GROUP_OUT
|
|
|
SERVICE
|
EVENT
Specifies the LDAP distinguished name of the event from which to unsubscribe. The value is an LDAP distinguished name relative to a configured base URI. A syntax of <event_name>@<domain> is recommended to give additional meaning and avoid name conflicts. If relative, the cn= (common name attribute) is implicit if not explicitly specified.
This parameter is required if GROUP_IN is not supplied.
GROUP_OUT
Specifies the name of the status group to create upon success. The default behavior for this parameter is to create a group named unsubscribe-results.
This parameter is optional.
SERVICE
Specifies the name of the Info*Engine property set that is configured for connectivity to a specific JMS service. This allows you to configure more than one JMS service per Info*Engine Virtual Machine (VM).
This parameter is optional.
EXAMPLE
The following example unsubscribes the current Info*Engine process to the specified event:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Unsubscribe-Event" type="WES">
<ie:param name="EVENT" data="$(@FORM[]event[])"/>
<ie:param name="GROUP_OUT" data="$(@FORM[]group_out[])"/>
</ie:webject>
To actually run this example, you need to provide a form where the EVENT and GROUP_OUT variables are identified.
