Message Webjects
The following webjects can be used in conjunction with a third-party MOM for generic messaging and task queuing functions:
• Browse-Queue
• Call-RemoteProcedure
• Call-SOAPService
• Create-Object
• Delete-Object
• Delete-Results
• Query-Object
• Query-Results
• Queue-Task
• Send-Mail
• Subscribe-Queue
• Unsubscribe-Queue
All message webjects use the MSGtype attribute value in the webject tag.
Browse-Queue
Selects a message or set of messages in a queue, allowing the properties on messages to be viewed while not actually returning message content.
|
|
This webject can be used only after your environment has been set up for messaging or for queuing tasks.
|
SYNTAX
<ie:webject name="Browse-Queue" type="MSG">
<ie:param name="ATTRIBUTE" data="attribute_name"/>
<ie:param name="DBUSER" data="username"/>
<ie:param name="GROUP_OUT" data="group_name"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="QUEUE" data="managed_queue_name"/>
<ie:param name="WHERE" data="message_selector"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
QUEUE
|
|
ATTRIBUTE
|
|
|
DBUSER
|
|
|
SERVICE
|
|
|
GROUP_OUT
|
|
|
PASSWD
|
|
|
WHERE
|
ATTRIBUTE
Specifies which JMS properties should be added to the output group as attributes. In addition to properties manually set on a message at the time of queuing the following JMS-specific properties can be returned as well:
◦ JMSDestination
◦ JMSDeliveryMode
◦ JMSMessageID
◦ JMSTimestamp
◦ JMSCorrelationID
◦ JMSReplyTo
◦ JMSRedelivered
◦ JMSExpiration
◦ JMSPriority
◦ JMSType
The default for this parameter is “*”, in which case all properties set as attributes are returned. This parameter is optional.
DBUSER
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
.msg.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 Info*Engine messaging software 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 .msg.username property is used. If the .msg.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.
SERVICE
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.
GROUP_OUT
The name of the group to create that contains the queue identifiers of the objects in the message queue. The default for this parameter is browse-results. This parameter is optional.
PASSWD
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
.msg.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 Info*Engine messaging software 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 .msg.password property is used. If the .msg.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.
QUEUE
The LDAP relative distinguished name of the managed queue to be browsed. The value is an LDAP distinguished name relative to a configured base URI. If relative, the cn= (common name attribute) is implicit if not explicitly specified. This parameter is required.
WHERE
The JMS where clause used to select the messages from the queue. If no where clause is specified, all messages in the queue are returned. This parameter is optional.
EXAMPLE
The following example browses a specified queue for all attributes, then returns the default “browse-results” group using the Return-Groups webject:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Browse-Queue" type="MSG">
<ie:param name="QUEUE" data="$(@FORM[]QUEUE[0])"/>
</ie:webject>
<ie:webject name="Return-Groups" type="GRP">
<ie:param name="GROUP_IN" data="*"/>
</ie:webject>
To actually run this example, you must provide a form where the QUEUE variable is identified.
Call-RemoteProcedure
Makes a remote procedure call (RPC) to a third-party Simple Object Access Protocol (SOAP) service. Results from an RPC invocation are returned to the Info*Engine task or JSP author in the form of a group. The group mimics the XML structure of the SOAP response. In simple cases, where an RPC invocation results in a single value or array of simple values, a basic Info*Engine group containing one attribute per element is returned. It is possible for an RPC service to return a complex data structure in response. In this case a group, possibly containing multiple elements with multiple attributes, is returned. If the return XML is deeply nested, then the resulting Info*Engine group is also deeply nested, containing attributes whose values are elements. Dealing with such responses might require the use of scriptlet code within the handling task or JSP.
SYNTAX
<ie:webject name="Call-RemoteProcedure" type="MSG">
<ie:param name="WSDL" data="url"/>
<ie:param name="OPERATION" data="operationName"/>
<ie:param name="GROUP_OUT" data="groupName"/>
<ie:param name="GROUP_IN" data="groupName"/>
<ie:param name="SERVICE" data="soapServiceName"/>
<ie:param name="PORT" data="soapPortName"/>
<ie:param name="PARAM" data="name=data"/>
<ie:param name="DBUSER" data="username"/>
<ie:param name="PASSWORD" data="password"/>
<ie:param name="AUTHORIZATION" data="Base64"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
OPERATION
|
|
AUTHORIZATION
|
|
WSDL
|
|
DBUSER
|
|
|
GROUP_IN
|
|
|
GROUP_OUT
|
|
|
PARAM
|
|
|
PASSWD
|
|
|
PORT
|
|
|
SERVICE
|
AUTHORIZATION
A base64-encoded username and password passed from a web browser to a web server through the Authorization HTTP header. This parameter is used if the SOAP endpoint is http or https. If supplied, the credentials are used in establishing a connection to the SOAP endpoint. If DBUSER and PASSWORD are specified, they are used instead of the AUTHORIZATION value. This parameter is optional.
DBUSER
The user name entered when making a connection to the SOAP endpoint, if the endpoint’s supporting protocol is http or https. If DBUSER is specified then PASSWORD must also be specified or it is ignored. This is an optional parameter.
GROUP_IN
An Info*Engine group that represents the SOAP request to be sent. All attributes found in the input group are added as XML elements. Attribute values are added as values of those XML elements. XML elements can be nested by setting attribute values to elements. This parameter can be used to generate arbitrarily complex SOAP requests. All elements generated from the input group are added to the standard RPC top-level element whose name is the operation name. This is an optional parameter. If specified, no validation of input is performed by the webject.
GROUP_OUT
The name of the Info*Engine group that the RPC invocation results should be stored in. Data found in the output group is strongly typed, based on type information found in the SOAP response. This is an optional parameter. The default value is rpcOutput.
OPERATION
The name of the operation to be executed. This is a required parameter. The operation name must be exposed by the WSDL document referenced by the WSDL parameter.
PARAM
A parameter name and value that should be sent with the RPC. The value must be in the form of name=data. Call-RemoteProcedure verifies the supplied parameters against the supplied WSDL to make sure that all required parameters are present, that the specified parameters are known to the service, that maximum and minimum occurrences of parameters are adhered to, and that parameter values are typed appropriately. It is possible that an operation requires no input parameters, and so this parameter is optional. If a web service requires specific parameters for the operation in question, then this parameter is required. If not specified, an exception is issued.
PASSWORD
Password to use when making a connection to the SOAP endpoint if the endpoint’s supporting protocol is http or https. If PASSWORD is specified then DBUSER must also be specified or it is ignored. This is an optional parameter.
PORT
The name of the SOAP port that should be used. A SOAP service might be tied to multiple ports in a WSDL document. If the selected SERVICE is tied to more than one port then this parameter is required. If the selected SERVICE is only tied to a single port then that port is used.
SERVICE
The name of the SOAP service that should be used. A WSDL document might expose multiple SOAP services. If the WSDL document referenced by the WSDL parameter exposes multiple services, then this parameter is required. If the WSDL document referenced by the WSDL parameter exposes only a single service, then that service is used.
WSDL
References a Web Services Definition Language (WSDL) document. The value must be a URL whose contents can be read by Call-RemoteProcedure. A WSDL document describes a web service; what service names it supports, what operations each service supports, what parameters each operation requires or supports, how the SOAP request should be generated (parameter order, name spaces to use). This is a required parameter. If a specific SOAP service does not have a WSDL document that describes it, then one must be made. If the URL specified is http or https and requires authorization, it can be specified as follows:
http://<user>:<password>@host/path/to/wsdl/.
EXAMPLE
<%@page language="java"
%><%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"
%><html>
<head><title>Weather by Zip</title></head>
<body>
<%
String zip = request.getParameter ( "zipCode" );
if ( zip != null ) {
%><ie:webject name="Call-RemoteProcedure" type="MSG">
<ie:param name="WSDL"
data="http://www.vbws.com/services/weatherretriever.asmx?WSDL"/>
<ie:param name="OPERATION" data="GetWeather"/>
<ie:param name="PORT" data="WeatherRetrieverSoap"/>
<ie:param name="PARAM" data="zipCode=$(@FORM[]zipCode[])"/>
</ie:webject><%
} %>
<form method="GET">
Zip: <input type=text size=10 name=zipCode value="<%=
(zip==null?"":zip)%>">
<input type=submit value="Get Weather" name=temp>
</form>
<%
if ( zip != null ) {
%><br><br>
<table>
<tr><td colspan=2 align=middle><img src="<ie:getValue name=
"IconUrl"/>"></td></tr>
<tr><td align=right><strong>Last Updated:<strong><td><td><ie:getValue
name="LastUpdated"/></td><tr>
<tr><td align=right><strong>Conditions:
</strong></td><td><ie:getValue name="Conditions"/></td></tr>
<tr><td align=right><strong>CurrentTemp:
<strong><td><td><ie:getValue name="CurrentTemp"/></td></tr>
<tr><td align=right><strong>Humidity:
</strong><td><td><ie:getValue name="Humidity"/></td></tr>
<tr><td align=right><strong>Barometer:</strong><td><td><ie:getValue
name="Barometer"/></td></tr>
<tr><td align=right><strong>Barometer Direction:
<strong><td><td><ie:getValue
name="BarometerDirection"/></td></tr>
</table><%}%></body></html>
Call-SOAPService
Makes a request to a third-party Simple Object Access Protocol (SOAP) service. This webject uses an Info*Engine group and an XSL template to format a SOAP request. The webject output can be directly generated as an Info*Engine group that mimics the SOAP response body, or an XSL template can be specified to translate the SOAP response into an Info*Engine group.
If a SOAP fault occurs, then an instance of com.infoengine.exception.fatal.IERemoteException is generated.
SYNTAX
<ie:webject name="Call-SOAPService" type="MSG">
<ie:param name="DBUSER" data="username"/>
<ie:param name="ENDPOINT" data="url"/>
<ie:param name="GROUP_IN" data="groupName"/>
<ie:param name="GROUP_OUT" data="groupName"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="SOAP_ACTION" data="operationName"/>
<ie:param name="XSL_URL" data="url"/>
<ie:param name="XSL_RESPONSE_URL" data="url"/>
<ie:param name="XSL_DBUSER" data="username"/>
<ie:param name="XSL_PASSWD" data="passwd"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
ENDPOINT
|
|
DBUSER
|
|
GROUP_IN
|
|
EXCEPTION_ON_FAULT
|
|
XSL_URL
|
|
GROUP_OUT
|
|
|
PASSWD
|
|
|
SOAP_ACTION
|
|
|
XSL_DBUSER
|
|
|
XSL_PASSWD
|
|
|
XSL_RESPONSE_URL
|
DBUSER
The username to use to authenticate to ENDPOINT. This parameter is used in conjunction with PASSWD if the SOAP endpoint specified on the ENDPOINT parameter requires authentication. This parameter is optional.
ENDPOINT
The URL of the SOAP endpoint to which the SOAP request should be sent. This parameter is required.
EXCEPTION_ON_FAULT
Specifies whether an exception is thrown if the service responds with a SOAP fault. The default value is true. If the parameter is set to false, then no exception is thrown if a fault occurs. If XSL is being used to transform the results, then an XSL template can be used to translate the fault into Info*Engine data (including the contents of the detail element), and other actions taken. If XSL is not being used, then the webject translates the fault into an Info*Engine group. This parameter is optional.
GROUP_IN
The Info*Engine group containing data to combine with the XSL template specified on XSL_URL. This parameter is required.
GROUP_OUT
The name of the Info*Engine group representing the SOAP response. If XSL_RESPONSE_URL is specified, then it is used to translate the SOAP response into an Info*Engine group named with the GROUP_OUT value. If XSL_RESPONSE_URL is not specified, then this group contains a single element and one attribute per XML element in the response. The value of an attribute can be an object, representing element data; or an Info*Engine element, representing additional nested XML elements. The name of an attribute matches the corresponding XML element name. The default value for this parameter is SOAPResponse. This parameter is optional.
PASSWD
The password corresponding to DBUSER. This parameter is optional.
SOAP_ACTION
The value (if any) of the SOAPAction header that should be sent. This parameter is optional.
XSL_DBUSER
The username to used to authenticate to XSL_URL and XSL_RESPONSE_URL. This parameter is used in conjunction with XSL_PASSWD if the XSL templates to be used by the webject reside on a remote HTTP server that requires authentication. This parameter is optional.
XSL_PASSWD
The password corresponding to XSL_DBUSER. This parameter is optional.
XSL_RESPONSE_URL
The location of an XSL template used to process the SOAP response. The XSL template is combined with the SOAP response to create the GROUP_OUT. This parameter is optional.
Fully qualified URLs are dereferenced using Auth-Map context group data. The Auth-Map is searched for a username and password based on the domain name found in the fully qualified URL. For example, if the fully qualified URL is:
http://machine.com/infoengine/servlet/IE/tasks/createGroupData.xml
the Auth-Map context group is searched for a username and password that has an INSTANCE name of http://machine.com. If a username and password are found, BASIC authentication information is used when accessing the URL. If no username and password are found, no authentication information is sent to the remote web server.
If the data value contains the :// string, it is assumed to be a fully qualified internet URL. If the data value does not contain the string, it is assumed to be a local file relative to the current task root directory.
XSL_URL
The location of the XSL template used to generate the SOAP request. The XSL template is combined with the GROUP_IN to generate the SOAP request.
When authoring the XSL documents used to translate the SOAP request and response, if the example request and response pair for the XML documents are available they can be used as templates for the XSL. If there are no such example request and response documents available, then the XSL author needs to pay close attention to the schema provided by the web service’s WSDL document. Complying with the WSDL document is necessary to provide valid and acceptable XML to the web service. Depending on how the service is implemented, it might or might not be flexible in terms of what it accepts. However, the schema provided in the WSDL should be taken literally and be used to craft XML that validates against that schema by complying with the order, case, optionality, cardinality, and data type for all XML elements and attributes.
Fully qualified URLs are de-referenced using Auth-Map context group data. The Auth-Map is searched for a username and password based on the domain name found in the fully qualified URL. For example, if the fully qualified URL is:
http://machine.com/infoengine/servlet/IE/tasks/createGroupData.xml
the Auth-Map context group is searched for a username and password that has an INSTANCE name of http://machine.com. If a username and password are found, BASIC authentication information is used when accessing the URL. If no username and password are found, no authentication information is sent to the remote web server.
If the data value contains the :// string, it is assumed to be a fully qualified internet URL. If the data value does not contain the string, it is assumed to be a local file relative to the current task root directory.
This parameter is required.
EXAMPLE: TRANSLATE-GROUP AND XSL
|
|
Info*Engine SOAP comments are used in the example code for clarity. For more information on SOAP and SOAP comments, see SOAP Services. |
This example uses the Translate-Group webject and XSL to simplify a SOAP response that was returned from the Call-SOAPService webject as a complex Info*Engine group.
hostlookup.xml
<%@page language="java" import="java.util.StringTokenizer,com.infoengine.
object.
IeMultipartInputStream,java.io.ByteArrayInputStream"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<!--com.infoengine.soap.rpc.def
Resolves information about a host name.
@param string host The hostname
@return INFOENGINE_GROUP $(output)-->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT" data="host=$(@FORM[]host[])"
default="www.google.com"/>
<ie:param name="CLASS" data="parameters"/>
<ie:param name="GROUP_OUT" data="parameters"/>
</ie:webject>
<ie:webject name="Call-SOAPService" type="MSG">
<ie:param name="ENDPOINT"
data="http://www.esynaps.com/webservices/YourHostInfo.asmx"/>
<ie:param name="SOAP_ACTION"
data="http://tempuri.org/GetHostInfoByName"/>
<ie:param name="XSL_URL"
data="/com/company/hostlookup/ hostlookupRequest.xsl"/>
<ie:param name="GROUP_IN" data="parameters"/>
<ie:param name="GROUP_OUT" data="response"/>
<ie:param name="CLASS" data="response"/>
</ie:webject>
<ie:webject name="Translate-Group" type="GRP">
<ie:param name="GROUP_IN" data="response"/>
<ie:param name="XSL_URL"
data="/com/company/hostlookup/
hostlookupResponse.xsl"/>
<ie:param name="GROUP_OUT" data="$(@FORM[]group_out[])"
default="output"/>
<ie:param name="CLASS" data="lookupResponse"/>
</ie:webject>
hostlookupRequest.xsl
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
xmlns:wc="http://www.ptc.com/infoengine/1.0">
<xsl:template match="/wc:COLLECTION/parameters/wc:INSTANCE">
<soap:Envelope xmlns:s0="http://tempuri.org/"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<s0:GetHostInfoByName>
<s0:Name><xsl:value-of select="host"/></s0:Name>
</s0:GetHostInfoByName>
</soap:Body>
</soap:Envelope>
</xsl:template>
</xsl:stylesheet>
hostlookupResponse.xsl
EXAMPLE: XSL_RESPONSE_URL
This example uses the XSL_RESPONSE_URL parameter to translate the SOAP response into a group identical to that produced by the previous example:
hostlookup2.xml
<%@page language="java" import="java.util.StringTokenizer,com.
infoengine.object.
IeMultipartInputStream,java.io.ByteArrayInputStream"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<!--com.infoengine.soap.rpc.def
Resolves information about a host name, goes straight from SOAP
response to group.
@param string host The hostname
@return INFOENGINE_GROUP $(output)
-->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT" data="host=$(@FORM[]host[])"
default="www.google.com"/>
<ie:param name="CLASS" data="parameters"/>
<ie:param name="GROUP_OUT" data="parameters"/>
</ie:webject>
<ie:webject name="Call-SOAPService" type="MSG">
<ie:param name="ENDPOINT"
data="http://www.esynaps.com/webservices/YourHostInfo.asmx"/>
<ie:param name="SOAP_ACTION"
data="http://tempuri.org/GetHostInfoByName"/>
<ie:param name="XSL_URL"
data="/soap/document/hostlookup/hostlookupRequest.xsl"/>
<ie:param name="XSL_RESPONSE_URL"
data="/soap/document/hostlookup/hostlookupResponseSOAP.xsl"/>
<ie:param name="GROUP_IN" data="parameters"/>
<ie:param name="GROUP_OUT" data="output"/>
<ie:param name="CLASS" data="output"/>
</ie:webject>
hostlookupResponseSOAP.xsl
Create-Object
Creates a JMS message and places that message in a JMS message queue. The type and contents of the message are governed by its parameters.
|
|
This webject can be used only after your environment has been set up for messaging.
|
SYNTAX
<ie:webject name="Create-Object" type="MSG">
<ie:param name="DBUSER" data="username"/>
<ie:param name="GROUP_IN" data ="group_name"/>
<ie:param name="GROUP_OUT" data ="status_group_name"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="PRIORITY" data ="numeric_value"/>
<ie:param name="PROPERTY" data ="name_value_pair"/>
<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="QUEUE" data ="managed_queue_name"/>
<ie:param name="TIME_TO_LIVE" data="minutes"/>
<ie:param name="TYPE" data ="message_type"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
QUEUE
|
PUT_BOOLEAN
|
DBUSER
|
|
PUT_BYTE
|
GROUP_IN
|
|
PUT_BYTES
|
GROUP_OUT
|
|
PUT_INT
|
PASSWD
|
|
PUT_CHAR
|
PRIORITY
|
|
PUT_DOUBLE
|
PROPERTY
|
|
PUT_FLOAT
|
TIME_TO_LIVE
|
|
PUT_LONG
|
SERVICE
|
|
PUT_SHORT
|
|
|
PUT_STRING
|
|
|
TYPE
|
|
DBUSER
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
.msg.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 Info*Engine messaging software 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 .msg.username property is used. If the .msg.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.
GROUP_IN
The name of an Info*Engine group to serialize with the request. A value of “*” means serialize all groups. This parameter only makes sense if the TYPE parameter is Info*Engine. This parameter is optional.
GROUP_OUT
The name of the status group to create upon success. The default for this parameter is to created a group named “create-results”. This parameter is optional.
PASSWD
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
.msg.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 Info*Engine messaging software 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.msg.password property is used. If the .msg.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.
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 messages queued 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.
This default behavior for this parameter is not to 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 can be specified as TRUE or FALSE. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_BYTE
Places a single byte into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_BYTES
Places multiple bytes into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_CHAR
Places a single Java character into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_DOUBLE
Places a Java double value into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_FLOAT
Places a floating point number into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_INT
Places an integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_LONG
Places a long integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
PUT_SHORT
Places a short integer into the JMS message. This parameter can only be used if the TYPE is specified as BytesMessage, MapMessage, or StreamMessage.
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, MapMessage, or StreamMessage.
QUEUE
The LDAP relative distinguished name of the JMS Queue to which to submit the new message. The value is an LDAP distinguished name relative to a configured base URI. If relative, the cn= (common name attribute) is implicit if not explicitly specified. This parameter is required.
TIME_TO_LIVE
Specifies how long, in minutes, the queued message should be valid. The default for this parameter is 0, in which case the message remains valid indefinitely. This parameter is optional.
SERVICE
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.
TYPE
Indicates the type of JMS message to create. Message types are case-sensitive. 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 might 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. The name portion of the value is the key used to place data in the MapMessage.
◦ StreamMessage—For outgoing messages, this type supports several PUT_type parameters for building a message that might be specific to a third-party recipient.
◦ Unknown—Turns BLOB data into a BytesMessage. For incoming messages, a new empty IeRequest is created and the contents of the message are tacked on as BLOB data.
The following table indicates which PUT_type parameters can be specified with which message types:
|
BytesMessage
|
TextMessage
|
MapMessage
|
StreamMessage
|
|
PUT_BOOLEAN
|
X
|
|
X
|
X
|
|
PUT_BYTE
|
X
|
|
X
|
X
|
|
PUT_BYTES
|
X
|
|
X
|
X
|
|
PUT_CHAR
|
X
|
|
X
|
X
|
|
PUT_DOUBLE
|
X
|
|
X
|
X
|
|
PUT_FLOAT
|
X
|
|
X
|
X
|
|
PUT_INT
|
X
|
|
X
|
X
|
|
PUT_LONG
|
X
|
|
X
|
X
|
|
PUT_SHORT
|
X
|
|
X
|
X
|
|
PUT_STRING
|
X
|
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.
|
The default value for this parameter is InfoEngine, meaning 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).
EXAMPLES
The following example creates a JMS message and submits it to the specified queue:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Create-Object" type="MSG">
<ie:param name="DBUSER" data="$(@FORM[]dbuser[])"/>
<ie:param name="PASSWD" data="$(@FORM[]passwd[])"/>
<ie:param name="QUEUE" data="$(@FORM[]queue[])"/>
<ie:param name="TIME_TO_LIVE" data="$(@FORM[]time[])"/>
<ie:param name="PRIORITY" data="$(@FORM[]priority[])"/>
<ie:param name="TYPE" data="TextMessage"/>
<ie:param name="PUT_STRING" data="$(@FORM[]string[])"/>
<ie:param name="GROUP_OUT" data="results"/>
</ie:webject>
To actually run this example you must provide a form where the dbuser, passwd, queue, time, priority, and string variables are identified.
The following example shows how the Create-Object webject could be used to queue a TextMessage containing XML data to be processed by a third-party application:
<%@page language="java"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<!-- get an "employee object from JDBC/JNDI or where ever,
for the purposes of example just using Create-Group -->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT"
data="name=joe:email=joe@somewhere.nice"/>
<ie:param name="ELEMENT" data="name=bob:email=bob@nowhere.net"/>
<ie:param name="GROUP_OUT" data="employees"/>
</ie:webject>
<!-- xml-ize the parts -->
<ie:webject name="Format-Group" type="GRP">
<ie:param name="GROUP_IN" data="employees" />
<ie:param name="GROUP_OUT" data="formatted"/>
<ie:param name="ATTRIBUTE" data="name"/>
<ie:param name="ATTRIBUTE" data="email"/>
<ie:param name="FORMAT"
data="<employee><name>{0}</name><email>{1}</email></employee>"/>
</ie:webject>
<!-- turn them into an XML document and put in in a TextMessage on
my queue -->
<ie:webject name="Create-Object" type="MSG">
<ie:param name="PUT_STRING" data="<?xml version='1.0'> "/>
<ie:param name="PUT_STRING" data="<employees> "/>
<ie:param name="PUT_STRING"
data="$(formatted[*]nameemail[0]) "
valueSeparator=";" delim=";" />
<ie:param name="PUT_STRING" data="</employees> "/>
<ie:param name="TYPE" data="TextMessage"/>
<ie:param name="QUEUE" data="cn=The.Q"/>
</ie:webject>
Delete-Object
Removes a message from a JMS queue.
|
|
This webject can be used only after your environment has been set up for messaging.
|
SYNTAX
<ie:webject name="Delete-Object" type="MSG">
<ie:param name="DBUSER" data="username"/>
<ie:param name="GROUP_OUT" data="group_name"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="QUEUE" data="managed_queue_name"/>
<ie:param name="WHERE" data="message_selector"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
QUEUE
|
|
DBUSER
|
|
|
SERVICE
|
|
|
GROUP_OUT
|
|
|
PASSWD
|
|
|
WHERE
|
DBUSER
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
.msg.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 Info*Engine messaging software 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 .msg.username property is used. If the .msg.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.
SERVICE
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.
GROUP_OUT
The name of the status group to create and return upon success. The default for this parameter is delete-results. This parameter is optional.
PASSWD
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
.msg.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 Info*Engine messaging software 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 .msg.password property is used. If the .msg.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.
QUEUE
Identifies the LDAP relative distinguished name of the JMS queue to remove the message from. The value is an LDAP distinguished name relative to a configured base URI. If relative, the cn= (common name attribute) is implicit if not explicitly specified. This parameter is required.
WHERE
Specifies a properly formatted JMS message selector, as defined in the Sun Java Message Service specification, used to select a subset of messages from the message queue for deletion. The first message in the subset on the queue is deleted. The default behavior for this parameter is for the first message on the queue to be deleted. This parameter is optional.
EXAMPLE
The following example deletes a JMS message from the specified queue:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Delete-Object" type="MSG">
<ie:param name="DBUSER" data="$(@FORM[]dbuser[])"/>
<ie:param name="PASSWD" data="$(@FORM[]passwd[])"/>
<ie:param name="QUEUE" data="$(@FORM[]queue[])"/>
<ie:param name="WHERE" data="$(@FORM[]where[])"/>
<ie:param name="GROUP_OUT" data="results"/>
</ie:webject>
To actually run this example you would need to provide a form where the dbuser, passwd, queue, and where variables are identified.
Delete-Results
Retrieves and deletes a message from an Info*Engine task queue. It is assumed that the message contains a known Info*Engine object, normally a group to return to a user.
|
|
This webject can be used only after your environment has been set up for queuing tasks.
|
SYNTAX
<ie:webject name="Delete-Results" type="MSG">
<ie:param name="DBUSER" data="username"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="QUEUE" data="<managed_queue_name>"/>
<ie:param name="WHERE" data="<message_selector>"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
|
DBUSER
|
|
|
SERVICE
|
|
|
PASSWD
|
|
|
QUEUE
|
|
|
WHERE
|
DBUSER
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
.msg.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 Info*Engine messaging software 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 .msg.username property is used. If the .msg.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.
SERVICE
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.
PASSWD
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
.msg.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 Info*Engine messaging software 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 .msg.password property is used. If the .msg.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.
QUEUE
The LDAP distinguished name of a managed queue. The value is an LDAP distinguished name relative to a configured base URI. If relative, the cn= (common name attribute) is implicit if not explicitly specified. The default for this parameter is to use the value specified in the com.infoengine.msg.defaultResponseQueue property.
This parameter is optional.
WHERE
Specifies a properly formatted JMS message selector, as defined in the Sun Java Message Service specification, used to select a subset of messages from the message queue for deletion. The first message in the subset on the queue is deleted.
The value of the CORRELATION_ID parameter from the Queue-Task webject can be used as the WHERE value to select the corresponding result.
The default value of this parameter is derived from the user identifier found in the SERVER context group and results in a subset that contains this user’s messages. This parameter is optional.
EXAMPLE
The following example retrieves a message from the specified queue, then deletes the message:
<%@page language="java" session="false" %>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="delete-results" type="MSG">
<ie:param name="QUEUE" data="$(FORM[]QUEUE[0])"/>
<ie:param name="CORRELATION_ID"
data="$(FORM[]CORRID[0])"/>
<ie:param name="WHERE" data="$(@FORM[]where[0])"/>
<ie:param nam
<ie:webject name="Return-Groups" type="GRP">
<ie:param name="GROUP_IN" data="*"/>
</ie:webject>
To actually run this example you would need to provide a form where the QUEUE, CORRID, and where variables are identified.
Query-Object
Retrieves a message from a JMS message queue. If there is no message to return, an instance of com.infoengine.exception.nonfatal.IERequestTimeOutException is thrown.
|
|
This webject can be used only after your environment has been set up for messaging.
|
SYNTAX
<ie:webject name="Query-Object" type="MSG">
<ie:param name="BLOB_COUNT" data="number"/>
<ie:param name="DBUSER" data="username"/>
<ie:param name="DELETE" data="[TRUE | FALSE]"/>
<ie:param name="GET_BOOLEAN" data ="[TRUE | FALSE]"/>
<ie:param name="GET_BYTE" data ="byte"/>
<ie:param name="GET_BYTES" data ="bytes"/>
<ie:param name="GET_CHAR" data ="char"/>
<ie:param name="GET_DOUBLE" data ="double"/>
<ie:param name="GET_FLOAT" data ="float"/>
<ie:param name="GET_INT" data ="int"/>
<ie:param name="GET_LONG" data ="long"/>
<ie:param name="GET_SHORT" data ="short"/>
<ie:param name="GET_STRING" data ="string"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="QUEUE" data="managed_queue_name"/>
<ie:param name="WHERE" data="message_selector"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
QUEUE
|
|
BLOB_COUNT
|
|
|
DBUSER
|
|
|
SERVICE
|
|
|
DELETE
|
|
|
GET_BOOLEAN
|
|
|
GET_BYTE
|
|
|
GET_BYTES
|
|
|
GET_CHAR
|
|
|
GET_DOUBLE
|
|
|
GET_FLOAT
|
|
|
GET_INT
|
|
|
GET_LONG
|
|
|
GET_SHORT
|
|
|
GET_STRING
|
|
|
PASSWD
|
|
|
WHERE
|
BLOB_COUNT
The number of BLOBs to return on the caller’s output stream. Any BLOBs not returned can be used as input to other tasks or webjects. The default for this parameter is 0. This parameter is optional.
DBUSER
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
.msg.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 Info*Engine messaging software 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 .msg.username property is used. If the .msg.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.
SERVICE
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.
DELETE
Specifies whether or not to remove the message from the queue once it is retrieved from the queue. The default for this parameter is TRUE, which deletes the object once it is retrieved from the queue. Use FALSE to disable. This parameter is optional.
GET_BOOLEAN
Retrieves a Java Boolean value from the JMS message. The value can be specified as TRUE or FALSE. This parameter can only be used if the incoming message type is StreamMessage. This parameter is optional.
GET_BYTE
Retrieves a single byte from the JMS message. This parameter can only be used if the incoming message type is StreamMessage. This parameter is optional.
GET_BYTES
Retrieves multiple bytes from the JMS message. This parameter can only be used if the incoming message type is StreamMessage. This parameter is optional.
GET_CHAR
Retrieves a single Java character from the JMS message. This parameter can only be used if the incoming message type is StreamMessage. This parameter is optional.
GET_DOUBLE
Retrieves a Java double value from the JMS message. This parameter can only be used if the incoming message type is StreamMessage. This parameter is optional.
GET_FLOAT
Retrieves a floating point number from the JMS message. This parameter can only be used if the incoming message type is StreamMessage. This parameter is optional.
GET_INT
Retrieves an integer from the JMS message. This parameter can only be used if the incoming message type is StreamMessage. This parameter is optional.
GET_LONG
Retrieves a long integer from the JMS message. This parameter can only be used if the incoming message type is StreamMessage. This parameter is optional.
GET_SHORT
Retrieves a short integer from the JMS message. This parameter can only be used if the incoming message type is StreamMessage. This parameter is optional.
GET_STRING
Retrieves an instance of java.lang.String from the JMS message. This parameter can only be used if the incoming message type is StreamMessage. This parameter is optional.
PASSWD
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
.msg.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 Info*Engine messaging software 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 .msg.password property is used. If the .msg.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.
QUEUE
The LDAP distinguished name of the JMS Queue from which to retrieve the message. The value is an LDAP distinguished name relative to a configured base URI. If relative, the cn= (common name attribute) is implicit if not explicitly specified. This parameter is required.
WHERE
Specifies a properly formatted JMS message selector, as defined in the Sun Java Message Service specification, used to select a subset of messages from the message queue for retrieval. The first message in the subset on the queue is returned. The default for this parameter is to select all messages in the queue. This parameter is optional.
EXAMPLE
The following example retrieves a message from the specified queue:
<%@page language="java" session="false" %>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Query-Object" type="MSG">
<ie:param name="DBUSER" data="$(@FORM[]dbuser[])"/>
<ie:param name="PASSWD" data="$(@FORM[]passwd[])"/>
<ie:param name="DELETE" data="$(@FORM[]delete[])"/>
<ie:param name="QUEUE" data="$(@FORM[]queue[])"/>
<ie:param name="WHERE" data="$(@FORM[]where[])"/>
</ie:webject>
To actually run this example you would need to provide a form where the dbuser, passwd, delete, and where variables are identified.
Query-Results
Retrieves a message from an Info*Engine task queue, returns the results, and by default, deletes the message from the queue. It is assumed that the message contains a known Info*Engine object, normally a group to return to a user.
|
|
This webject can be used only after your environment has been set up for queuing tasks.
|
SYNTAX
<ie:webject name="Query-Results" type="MSG">
<ie:param name="CORRELATION_ID" data="message_selector"/>
<ie:param name="DBUSER" data="username"/>
<ie:param name="DELETE" data="[TRUE | FALSE]"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="QUEUE" data="managed_queue_name"/>
<ie:param name="WAIT_TIME" data="wait_time"/>
<ie:param name="WHERE" data="message_selector"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
|
CORRELATION_ID
|
|
|
DBUSER
|
|
|
SERVICE
|
|
|
DELETE
|
|
|
PASSWD
|
|
|
QUEUE
|
|
|
WAIT_TIME
|
|
|
WHERE
|
CORRELATION_ID
The JMS header correlation identifier. This value is used to select results from a response queue and corresponds to the CORRELATION_ID parameter used when queueing a task for execution with the Queue-Task webject. This parameter is optional.
DBUSER
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
.msg.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 Info*Engine messaging software 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 .msg.username property is used. If the .msg.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.
SERVICE
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.
DELETE
Indicates whether or not the message is to be deleted from the queue when successfully returned to the user. If the value specified is TRUE, then the message is deleted. If the value specified is FALSE, then the message is not deleted. The default for this parameter is TRUE. This parameter is optional.
PASSWD
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 .msg.password and .jms.password properties of the service that is used to connect to the MOM.
If this parameter is omitted, the mapped credentials for the Info*Engine messaging software 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 .msg.password property is used. If the .msg.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.
QUEUE
An LDAP distinguished name of a managed queue. The value is an LDAP distinguished name relative to a configured base URI. If relative, the cn= (common name attribute) is implicit if not explicitly specified. The default for this parameter is to use the value specified in the com.infoengine.msg.defaultResultsQueue property.
This parameter is optional.
WAIT_TIME
The time in seconds to wait for the result to arrive in the specified queue. The default for this parameter is 0. This parameter is optional.
WHERE
Specifies a properly formatted JMS message selector, as defined in the Sun Java Message Service specification, used to select a subset of messages from the message queue for retrieval. The first message in the subset on the queue is returned.
The value of the CORRELATION_ID parameter from the Queue-Task webject can be used as the WHERE value to select the corresponding result.
The default value of this parameter is derived from the user identifier found in the SERVER context group and results in a subset that contains this user’s messages. This parameter is optional.
EXAMPLE
The following example retrieves a message from the specified queue and returns the results:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Query-Results" type="MSG">
<ie:param name="QUEUE" data="$(@FORM[]queue[0])"/>
<ie:param name="CORRELATION_ID"
data="$(@FORM[]corrid[0])"/>
<ie:param name="WHERE" data="$(@FORM[]where[0])"/>
<ie:param name="DELETE" data="$(@FORM[]delete[])"/>
<ie:param name="WAIT_TIME" data="10"/>
</ie:webject>
<ie:webject name="Return-Groups" type="GRP">
<ie:param name="GROUP_IN" data="*"/>
</ie:webject>
To actually run this example you would need to provide a form where the queue, corrid, where, and delete variables are identified.
Queue-Task
Allows a subscriber of an Info*Engine task queue to add a task to the queue for execution. The task is built from a task execution name and if necessary one or more existing Info*Engine groups.
|
|
This webject can be used only after your environment has been set up for queuing tasks.
|
SYNTAX
<ie:webject name=Queue-Task type="MSG">
<ie:param name="CORRELATION_ID" data="message_selector"/>
<ie:param name="DBUSER" data="username"/>
<ie:param name="DESTINATION" data="queue_name"/>
<ie:param name="GROUP_IN" data="group_name"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="PRIORITY" data="numeric_value"/>
<ie:param name="QUEUE" data="queue_name"/>
<ie:param name="RESULT_TIME_TO_LIVE" data="minutes"/>
<ie:param name="TASK" data="task_uri"/>
<ie:param name="TASK_TIME_TO_LIVE" data="minutes"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
TASK
|
|
CORRELATION_ID
|
|
|
DBUSER
|
|
|
SERVICE
|
|
|
DESTINATION
|
|
|
GROUP_IN
|
|
|
PASSWD
|
|
|
PRIORITY
|
|
|
QUEUE
|
|
|
RESULT_TIME_TO_LIVE
|
|
|
TASK_TIME_TO_LIVE
|
CORRELATION_ID
Specifies a JMS message selector to set as the JMS header correlation identifier of the result. The value of this parameter can then be used as the value of the WHERE parameter of the Query-Results or Delete-Results webjects to select the corresponding result.
The default value of this parameter is derived from the auth-user HTTP header value found in the SERVER context group. If auth-user is not defined and no explicit correlation identifier is specified, no correlation identifier is associated with the task. In this case, the Info*Engine group returned from Query-Task returns the value of the correlation identifier that was associated with the task. This parameter is optional.
DESTINATION
The LDAP distinguished name of the queue where the response should be queued after the task is executed. The default for this parameter is to use the value specified in the com.infoengine.msg.defaultResponseQueue property. This parameter is optional.
DBUSER
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
.msg.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 Info*Engine messaging software 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 .msg.username property is used. If the .msg.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.
SERVICE
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.
GROUP_IN
The name of a local VDB Info*Engine group object to attach to the task to be queued. The default behavior is that no group is attached. Multiple groups can be specified on this parameter. This parameter is optional.
PASSWD
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 .msg.password and .jms.password properties of the service that is used to connect to the MOM.
If this parameter is omitted, the mapped credentials for the Info*Engine messaging software 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 .msg.password property is used. If the .msg.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.
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. The default for this parameter is not to set a priority which results in the message being queued with the MOM’s default priority. This parameter is optional.
QUEUE
The LDAP distinguished name of the queue where the task is to be placed. The default for this parameter is to use the value specified in the com.infoengine.msg.defaultExecutionQueue property. This parameter is optional.
RESULT_TIME_TO_LIVE
Indicates a numeric value specifying how long the results of a task execution should remain in the response queue before being discarded by the MOM. This parameter is specified as a numeric string in minutes. The default for this parameter is 0, in which case the MOM does not discard the response. This parameter is optional.
TASK
Specifies a URI that is the location of the XML task file for the listener on the EXECUTION_QUEUE to execute. The URI can be a relative or absolute URI:
◦ Relative URIs reference files that reside under the root file system directory that is defined for the local Info*Engine task processor.
◦ Absolute URIs reference files that reside in the local file system, reside on a remote HTTP server, or are referenced through an accessible LDAP directory.
This parameter is required.
|
|
The URIs shown in this guide use the forward slash as the separator (/) in file paths even though the back slash (\) is the directory separator used on NT systems. Info*Engine correctly identifies all system URIs when you specify the forward slash. If you prefer to use the back slash for NT URIs, you must escape the back slash in the URI. This means that you enter two \\ for each \ in the URI.
|
TASK_TIME_TO_LIVE
Indicates a numeric value specifying how long the message should remain in the execution queue before it can be discarded by the MOM. This parameter is specified as a numeric string in minutes. The default for this parameter is 0, in which case the MOM does not discard the message. This parameter is optional.
EXAMPLE
The following example adds the specified task to the specified queue:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<ie:webject name="queue-task" type="MSG">
<ie:param name="TASK" data="$(@FORM[]TASK[0])"
default="/com/company/CreateGroup.xml"/>
<ie:param name="QUEUE" data="$(@FORM[]QUEUE[0])"/>
<ie:param name="TASK_TIME_TO_LIVE"
data="$(@FORM[]TTTL[0])"/>
<ie:param name="RESULT_TIME_TO_LIVE"
data="$(@FORM[]RTTL[0])"/>
<ie:param name="DESTINATION" data="$(@FORM[]DEST[0])"/>
<ie:param name="CORRELATION_ID"
data="$(@FORM[]CORRID[0])"/>
<ie:param name="PRIORITY" data="$(@FORM[]PRIORITY[])"/>
<ie:param name="GROUP_OUT" data="myQueueResults"/>
</ie:webject>
To actually run this example you would need to provide a form where the TASK, QUEUE, TTTL, RTTL, DEST, CORRID, and PRIORITY variables are identified.
Send-Mail
Creates and sends an email message. Send-Mail supports designation of primary, copy, and blind copy recipients, as well as message subject and message bodies. It can create and send multi-part MIME messages containing a mixture of message body part types. It allows message body parts to be specified as simple text using webject parameters or as BLOBs using the task input stream.
SYNTAX
<ie:webject name="Send-Mail" type="MSG">
<ie:param name="BCC" data="e-mail_address"/>
<ie:param name="BLOB_COUNT" data="number"/>
<ie:param name="CC" data="e-mail_address"/>
<ie:param name="CONNECTION_TIMEOUT" data="milliseconds"/>
<ie:param name="CONTENT" data="message_body"/>
<ie:param name="CONTENT_TYPE" data="MIME_type"/>
<ie:param name="CONTENT_URL_LANGUAGE" data="
<ie:param name="DBUSER" data="username"/>
<ie:param name="FROM" data="e-mail_address"/>
<ie:param name="GROUP_OUT" data="results"/>
<ie:param name="HEADERS_CHARSET" data="
<ie:param name="MAIL_SERVER" data="host_name"/>
<ie:param name="MAX_DELIVERY_TIME" data="
<ie:param name="MULTIPART_TYPE" data="
<ie:param name="PASSWD" data="password"/>
<ie:param name="PASSWORD" data="password"/>
<ie:param name="REPLY_TO" data="e-mail_address"/>
<ie:param name="SUBJECT" data="message_subject"/>
<ie:param name="TIMEOUT" data="milliseconds"/>
<ie:param name="TO" data="e-mail_address"/>
<ie:param name="USERNAME" data="user_name"/>
</webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
TO
|
BLOB_COUNT
|
CC
|
|
|
CONNECTION_TIMEOUT
|
|
CONTENT
|
BCC
|
|
CONTENT_LINE_BREAK
|
DBUSER
|
|
CONTENT_TYPE
|
FROM
|
|
CONTENT_URL
|
GROUP_OUT
|
|
|
HEADER
|
|
|
HEADERS_CHARSET
|
|
|
MAIL_SERVER
|
|
|
MAX_DELIVERY_TIME
|
|
|
MULTIPART_TYPE
|
|
|
PASSWD
|
|
|
PASSWORD
|
|
|
REPLY_TO
|
|
|
SUBJECT
|
|
|
TIMEOUT
|
|
|
USERNAME
|
BCC
The email addresses of the blind copy recipients of the message. Each of these recipients receives a copy of the message, but none of these addresses are disclosed to any other recipients, including any other blind copy recipients. This parameter can be specified multiple times to specify multiple blind copy recipients. Each instance of the parameter specifies exactly one address. This parameter is optional.
BLOB_COUNT
The number of BLOBs to read from the input stream. If the CONTENT parameter is also specified, the BLOBs are appended to the message as attachments. If the CONTENT parameter is not specified, then the BLOBs become the message.
CC
The email addresses of non-primary recipients to which copies of the message are sent. This parameter can be specified multiple times to specify multiple copy recipients. Each instance of the parameter specifies exactly one address. This parameter is optional.
CONTENT
The text that appears in the message body. Each instance of the CONTENT parameter can correspond to an instance of the CONTENT_TYPE parameter, which specifies the MIME content type of the CONTENT parameter. If no CONTENT_TYPE is specified, the CONTENT parameter defaults to plain text unless the BLOB_COUNT parameter is specified. Multiple values can be specified for this parameter.
CONTENT_LINE_BREAK
This parameter is a multi-valued parameter that can specify a string (or strings) to be used as a line break. Wherever the value of this parameter exists in the content of the email it is replaced with a line break.
CONTENT_TYPE
The MIME content type of a corresponding CONTENT parameter. Each instance of the CONTENT_TYPE parameter corresponds to an instance of the CONTENT parameter and specifies the MIME content type of that parameter. If no CONTENT_TYPE parameters are specified, the MIME content types of the CONTENT parameters defaults to plain text. Similarly, if there are fewer CONTENT_TYPE parameters than CONTENT parameters, plain text values are implicitly added to the list of CONTENT_TYPE parameters.
CONTENT_URL
The CONTENT_URL parameter can be multi-valued. Each value specifies a URL that is opened and read. The content read from the URL becomes a body part (main body or attachment) for the message that is sent.
DBUSER
The username to use when connecting to the SMTP mail server. This parameter is optional.
FROM
The email address of the originator of the message. The default for this parameter is to use the value of the com.infoengine.mail.originator property. If the property does not exist, and the FROM parameter is not specified, an exception is thrown. This parameter is optional.
GROUP_OUT
The optional name of an output group. If this parameter is specified, then an output group is returned containing a single element with three attributes named sent, unsent, and invalid:
◦ The sent attribute specifies the addresses to which the message was sent.
◦ The unsent attribute specifies the addresses that are assumed to be valid but to which the message could not be sent (for example, because the mail server was unavailable).
◦ The invalid attribute specifies the addresses that were invalid.
HEADER
An optional header to add to the outgoing message. Multiple values can be specified for this parameter.
The format of the parameter is name=value (no quotation marks should be placed around value).
For example, the following value adds a CC header to the message even though the user is not actually included in the CC list, and does not receive the email:
cc=user@host.com
|
|
This parameter proves useful when sending an email to recipients in multiple languages. When recipient groups have different language locales set, Windchill sends a separate email for each locale. However, sending a separate email per language means that the recipient list only displays users who share the same locale. To prevent confusion as to whether disparate locale groups have been included in an email, you can set HEADER to cc=user@host.com.
|
HEADERS_CHARSET
The name of the character set that is used in email headers, such as the subject header.
MAIL_SERVER
The internet domain name of the SMTP mail server to which the message is sent for routing to the recipients. The default for this parameter is to obtain the mail server name from the com.infoengine.mail.smtp.server property. If the property does not exist, and MAIL_SERVER is not specified, the mail server defaults to localhost. This parameter is optional.
MAX_DELIVERY_TIME
The maximum length of time in seconds to take in attempting to deliver messages to valid addresses. This is for situations in which the mail transport indicates that the addresses are valid, but the mail server does not accept them (for example, because the mail server is temporarily unavailable or congested). The default value is 60 seconds.
MULTIPART_TYPE
The MIME subtype of the multipart message when multiple CONTENT and/or CONTENT_URL parameter values are specified. The default value for this parameter is mixed.
PASSWD
The password associated with the DBUSER parameter. This parameter is optional.
PASSWORD
The password to specify when authenticating to the SMTP mail server. While PASSWORD can be used in conjunction with USERNAME, it is not necessary for both parameters to be specified. The default for this parameter is to obtain the password from the .mail.smtp.password property. This parameter is optional.
REPLY_TO
The email address or addresses to which replies should be sent. Multiple values can be specified for this parameter. For each instance of the parameter, specify exactly one email address. The default for this parameter is for replies to be sent to the address specified by FROM. This parameter is optional.
SUBJECT
The subject header of the message. If it is not specified, the message does not contain a subject header. This parameter is optional.
TO
The email address or addresses of the primary recipients of the message. It can be specified multiple times to specify multiple primary recipients. Each instance of the parameter specifies exactly one address. This is a required parameter
USERNAME
The username to specify when authenticating to the SMTP mail server. While USERNAME can be used in conjunction with PASSWORD, it is not necessary for both parameters to be specified. The default for this parameter is for the username to be obtained from the .mail.smtp.username property. If the property does not exist, and USERNAME is not specified, an anonymous binding to the mail server is attempted. This parameter is optional.
EXAMPLE
The following example sends an email based on user input: .
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Send-Mail" type="MSG">
<ie:param name="USERNAME" data="$(@FORM[]user[])"/>
<ie:param name="PASSWORD" data="$(@FORM[]password[])"/>
<ie:param name="TO" data="$(@FORM[]to[])"/>
<ie:param name="FROM" data="$(@FORM[]from[])"/>
<ie:param name="SUBJECT" data="$(@FORM[]subject[])"/>
<ie:param name="CONTENT_TYPE"
data="$(@FORM[]contentType[])"/>
<ie:param name="CONTENT" data="$(@FORM[]content[])"/>
</ie:webject>
To actually run this example you would need to provide a form where the user, password, to, from, subject, contentType, and content variables are identified.
Subscribe-Queue
Registers an event handler that is called by the MOM implementation when a message arrives in the specified queue.
|
|
This webject can be used only after your environment has been set up for queuing tasks.
|
SYNTAX
<ie:webject name=Subscribe-Queue type="MSG">
<ie:param name="DBUSER" data="username"/>
<ie:param name="EXECUTE_TASK" data="task_name"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="QUEUE" data="managed_queue_name"/>
<ie:param name="WHERE" data="jms_message_selector"/>
<ie:param name="MAX_CONCURRENCY"="managed_receiver_generation"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
|
DBUSER
|
|
|
SERVICE
|
|
|
EXECUTE_TASK
|
|
|
PASSWD
|
|
|
QUEUE
|
|
|
WHERE
|
|
|
MAX_CONCURRENCY
|
DBUSER
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 .msg.username and .jms.username properties of the service that is used to connect to the MOM.
If this parameter is omitted, the mapped credentials for the Info*Engine messaging software 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 .msg.username property is used. If the .msg.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.
EXECUTE_TASK
The task to be executed when a message is received in the subscribed queue. If the incoming message does not contain a task to execute, then the task specified on this parameter is run.
If EXECUTE_TASK is not specified, then the subscription can only handle Info*Engine requests on its queue. Other incoming messages are rejected. This parameter is optional.
MAX_CONCURRENCY
The number of receivers that should be generated upon queue subscription. This specifies the maximum number of messages that the Info*Engine system processes simultaneously. The default value is 1, causing messages to be processed serially.
Specifying a MAX_CONCURRENCY value greater than one means that messages that are placed in a queue are not necessarily processed in the order in which they were queued. This parameter should not be used if the order of messages is important. This parameter is optional.
|
|
Specifying this parameter does not necessarily mean that all receivers are kept busy when given a queue load. This functionality is partially dependent upon the configuration of the to which MOM you are connecting.
To illustrate this, Tibco EMS supports a queue property named “prefetch.” The default value for this property is 5, meaning that any given receiver receives five messages at a time. Based on the amount of data in a queue, this can mean that if your MAX_CONCURRENCY is too high, then certain receivers might remain idle. For example, given the default queue configuration for Tibco EMS (five messages per receiver), if there were fifteen messages in a queue and upon subscription you specified a MAX_CONCURRENCY of 4, then only three out of the four available receivers would actually be used (resulting in a real concurrency of three). Because the fifteen messages would be divided by the default prefetch value of five and distributed evenly to the first three receivers, the fourth would then be left idle. Setting a value for prefetch of 1 for the queue in question would result in all receivers staying busy, but if message sizes are typically large then this might mean that there is a lag between messages.
|
PASSWD
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
.msg.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 Info*Engine messaging software 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 .msg.password property is used. If the .msg.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.
QUEUE
The LDAP distinguished name of an administered queue. The value can be an LDAP distinguished name relative to a configured base URI or a fully qualified LDAP distinguished name. If relative, the cn= (common name attribute) is implicit if not explicitly specified. The default for this parameter is to use the value specified in the com.infoengine.msg.defaultExecutionQueue property. If there is no such value, then the QUEUE parameter must be specified. This parameter is optional.
SERVICE
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.
WHERE
A properly formatted JMS message selector, as defined in the Sun Java Message Service specification, used to select a subset of messages to execute from the specified queue. The default for this parameter is to subscribe to all messages that arrive in the queue. This parameter is optional.
EXAMPLE
The following example registers a subscription to listen to the specified queue:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Subscribe-Queue" type="MSG">
<ie:param name="QUEUE" data="$(@FORM[]queue[0])"/>
<ie:param name="WHERE" data="$(@FORM[]where[0])"/>
</ie:webject>
To actually run this example you would need to provide a form where the queue and where variables are identified.
Unsubscribe-Queue
Unregisters an event handler that is called by the MOM implementation when a message arrives in a specified queue.
|
|
This webject can be used only after your environment has been set up for queuing tasks.
|
SYNTAX
<ie:webject name=Unsubscribe-Queue type="MSG">
<ie:param name="QUEUE" data="managed_queue_name"/>
<ie:param name="WHERE" data="jms_message_selector"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
|
GROUP_OUT
|
|
|
QUEUE
|
|
|
WHERE
|
|
|
SERVICE
|
GROUP_OUT
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.
QUEUE
The LDAP distinguished name of an administered queue. The value is an LDAP distinguished name relative to a configured base URI. If relative, the cn= (common name attribute) is implicit if not explicitly specified. The default for this parameter is to use the value specified in the com.infoengine.msg.defaultExecutionQueue property. If there is no such value, then the QUEUE parameter must be specified. This parameter is optional.
WHERE
A properly formatted JMS message selector, as defined in the Sun Java Message Service specification, used to select the queue listener to unsubscribe from the specified queue. The default for this parameter is to unsubscribe the queue listener associated with no message selector. This parameter is optional.
SERVICE
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 cancels a subscription listening to the specified queue:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Unsubscribe-Queue" type="MSG">
<ie:param name="QUEUE" data="$(@FORM[]queue[0])"/>
</ie:webject>
To actually run this example you would need to provide a form where the queue variable is identified.
