Create-Group
DESCRIPTION
Creates a data group from embedded parameters or from an XML source file. If the XML source conforms to the Info*Engine schema, a group can be created from it directly. Otherwise, this webject allows an XSL stylesheet to be applied in order to translate the source form to the Info*Engine schema.
The Create-Group webject accepts an XML_URL parameter. The value of this parameter can be a fully specified HTTP URL. If so, Create-Group creates an HTTP connection to a remote web server, delivers the URL, and then reads the response from the remote server. The response is expected to be an XML stream. Ideally, the remote web server returns an XML stream that is formatted as a collection of Info*Engine groups (the same format as is produced by the Info*Engine task processor).
In cases where the format of the XML stream is not the same as produced by the Info*Engine task processor, Create-Group accepts an XSL_URL parameter specifying an XSL stylesheet that can be applied to translate the XML stream into Info*Engine format. For a list of the XML Info*Engine output requirements, see
Understanding XML Output for Info*Engine Groups.
You can use the Create-Group webject to create an empty group. When you specify only the GROUP_OUT parameter and no ELEMENT parameters, Info*Engine creates an empty group.
SYNTAX
<ie:webject name="Create-Group" type="GRP" >
<ie:param name="CLASS" data="class"/>
<ie:param name="DBUSER" data="username"/>
<ie:param name="DELIMITER" data="delimiter_character"/>
<ie:param name="ELEMENT" data="key_value_pairs"/>
<ie:param name="GROUP_OUT" data="group_out_name"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="XML_URL" data="url_of_xml_source"/>
<ie:param name="XSL_PARAM" data="name_value_pair"/>
<ie:param name="XSL_URL" data="url_of_xsl_source"/>
</ie:webject>
PARAMETERS
|
Required
|
Select
|
Optional
|
|
ELEMENT
|
CLASS
|
|
GROUP_OUT
|
DBUSER
|
|
XML_URL
|
DELIMITER
|
|
XSL_PARAM
|
PASSWD
|
|
XSL_URL
|
|
CLASS
Specifies the type of the objects contained in the output group named by the GROUP_OUT parameter. For example if a webject specifies CLASS=MyClassName and GROUP_OUT=data_1, then the XML representation of the output group contains the following tags:
<MyClassName NAME="data_1" TYPE="Object" STATUS="0">
</MyClassName>
The default for this parameter is “Unknown-Class-Name”. This parameter is optional.
DBUSER
Specifies the username to be used to authenticate to XSL_URL. If the XSL templates to be used by the webject reside on a remote HTTP server, then this parameter should be used in conjunction with the PASSWD attribute.
This parameter is optional.
DELIMITER
Specifies the character used to delimit key and value pairs created in the ELEMENT parameter.
If you are using a substitution string containing an asterisk (*) within the ELEMENT parameter, you should not specify the characters that are used in separating multiple elements or values as the delimiter in the Create-Group webject. If you do use the same character, the resulting elements or attribute values may be different from what you expect them to be. Substitution is described in
Dynamic Parameter Value Substitution.
The default for this parameter is the colon (:). This parameter is optional.
ELEMENT
Specifies a delimited set of key and value pairs to add to the group specified by the GROUP_OUT parameter. Each key and value pair is specified by key=value. Each ELEMENT parameter creates an instance in the group with the attribute specified by the key value and the value specified by the value portion of the key and value pair.
Multiple ELEMENT parameters can be specified to create multiple instances of objects in the group. At least one ELEMENT parameter is required for this webject if no XML_URL parameter is specified. If both XML_URL and ELEMENT parameters are specified, the resulting group is the sum total of the rows created by the XML source file and the ELEMENT parameters specified.
GROUP_OUT
Specifies the name of the resulting group. The GROUP_OUT parameter is required only when the XML_URL parameter is not specified. When the XML_URL parameter is specified, the XML stream being parsed contains one or more groups. The names of these groups can be specified in the XML stream, so it is not necessary to provide a GROUP_OUT parameter to supply a name for the group(s) in this case.
PASSWD
Specifies the password corresponding to DBUSER.
This parameter is optional.
XML_URL
Identifies the location of an XML source file from which to create the group. A relative URL or a fully qualified URL can be specified. Relative URLs are relative to the Info*Engine Server task template root. The XML source is expected to be in Info*Engine format; the same format as is produced by the Info*Engine task processor. If the contents of the source specified by the XML_URL parameter is not in Info*Engine format, the XSL_URL parameter can be used to specify an XSL stylesheet that can be applied to transform the source into Info*Engine format. In any case, the source (possibly transformed by XSL) can contain definitions for more than one Info*Engine group. Create-Group parses all of them and add them to its collection of output groups.
Fully qualified URLs are dereferenced using the 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
then 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 is found, BASIC authentication is used. If no username or password is 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.
If the data value is input: the webject reads an XML object from the task’s BLOB input stream. This allows XML objects to be submitted from web pages and converted into groups by Create-Group.
XSL_PARAM
Defines XSL parameters that are then passed to the XSL stylesheet named in the XSL_URL parameter. You enter the value for the XSL_PARAM parameter in the form XSL_name=XSL_value, where XSL_name is the name of a parameter in the XSL stylesheet and XSL_value is the value you want set for the parameter.
The default for XSL_PARAM is that no parameters are passed to the stylesheet. Multiple values can be specified for this parameter. This parameter is optional.
XSL_URL
Identifies the location of an XSL stylesheet to apply to the XML source specified by the XML_URL parameter. A relative URL or a fully qualified URL can be specified. Relative URLs are relative to the Info*Engine Server task root.
Fully qualified URLs are dereferenced using the 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.
EXAMPLE: INTERNAL GROUP CREATION
In the following example, the webject specifies the elements in the output group named “createdgroup” and adds the group to the local output group collection:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<!-- Create an internal Group -->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT" data="NAME=Sam
Johnson:ADDRESS=1234 Main
St.:EMAIL=sjohnson@somewhere.com"/>
<ie:param name="ELEMENT" data="NAME=Harvy
Anderson:ADDRESS=1234 Amber
St.:EMAIL=handerson@somewhere.com"/>
<ie:param name="ELEMENT" data="NAME=James
O'Connor:ADDRESS=775 Main St.:EMAIL="/>
<ie:param name="ELEMENT" data="NAME=Harvey
Hampton:ADDRESS=775 Main
St.:EMAIL=hhampton@somewhere.com"/>
<ie:param name="CLASS" data="EmployeeData"/>
<ie:param name="GROUP_OUT" data="createdgroup"/>
</ie:webject>
The XML output from executing the example is the following:
EXAMPLE: EXTERNAL GROUP CREATION
The following example of Create-Group executes a task in a remote Info*Engine Server and adds its output groups to the local output group collection:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie"%>
<!-- Create one or more local groups from the output of a remote
Info*Engine task -->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="XML_URL" data="http://remote-ie.acme.com/
infoengine/servlet/IE/tasks/report.xml"/>
</ie:webject>