Translate-Group
DESCRIPTION
Allows translation of data from a specified Info*Engine data group in one or more of the following ways:
• Rename attributes within elements in the group;
• Translate data types of attribute values in the output group;
• Remove attributes from elements in the output group;
• Apply an XSL stylesheet to the Info*Engine data group specified on the GROUP_IN parameter.
This webject can be used for generalized schema translation.
SYNTAX
<ie:webject name="Translate-Group" type="GRP">
<ie:param name="CLASS" data="class"/>
<ie:param name="COPY_UNTRANSLATED" data="[YES | NO]"/>
<ie:param name="DBUSER" data="username"/>
<ie:param name="DEFAULT_TABLE" data="group_name"/>
<ie:param name="GROUP_IN" data="group_in"/>
<ie:param name="GROUP_OUT" data="GROUP_OUT_name"/>
<ie:param name="NAME_TRANS_TABLE" data="group_name"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="TYPE_TRANS_TABLE" data="group_name"/>
<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
|
|
GROUP_IN
|
COPY_UNTRANSLATED
|
CLASS
|
|
GROUP_OUT
|
DEFAULT_TABLE
|
DBUSER
|
|
NAME_TRANS_TABLE
|
PASSWD
|
|
TYPE_TRANS_TABLE
|
XSL_PARAM
|
|
|
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.
COPY_UNTRANSLATED
Specifies the action to be taken against attributes found in GROUP_IN elements that are not matched by attributes of the same names defined in the NAME_TRANS_TABLE or TYPE_TRANS_TABLE parameters. If the value of the parameter is specified as YES, then the name of an attribute of a GROUP_IN element which does not match the name of an attribute in the NAME_TRANS_TABLE or TYPE_TRANS_TABLE is copied to the GROUP_OUT element unmodified. If COPY_UNTRANSLATED is not specified, its value defaults to NO, in which case any such attribute is not included in the GROUP_OUT element.
If you specify the COPY_UNTRANSLATED parameter, then you must also specify either the NAME_TRANS_TABLE or the TYPE_TRANS_TABLE parameter.
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.
DEFAULT_TABLE
Specifies the name of a group that provides default attribute names and values to the GROUP_OUT group. The group is assumed to contain exactly one element. If more than one element is contained within the group, then the additional elements are ignored. Each attribute of the element specifies a default name and value.
After the NAME_TRANS_TABLE and TYPE_TRANS_TABLE parameters have been applied to each element of the GROUP_IN group to produce an element of the GROUP_OUT group, the GROUP_OUT element is checked for attributes having names matching attributes defined in the DEFAULT_TABLE. For each attribute defined in the DEFAULT_TABLE that does not have a matching name in the GROUP_OUT element, the attribute of the DEFAULT_TABLE is added to the GROUP_OUT element. For example, if the DEFAULT_TABLE contains an attribute named “Factory” and a value named “Unknown”, and after translation a GROUP_OUT element does not contain an attribute named “Factory”, then an attribute with name “Factory” and value “Unknown” are added.
If you specify the DEFAULT_TABLE parameter, then you must also specify either the NAME_TRANS_TABLE or the TYPE_TRANS_TABLE parameter.
GROUP_IN
Specifies the group to convert to XML and to which an XSL stylesheet is applied. This parameter is required.
GROUP_OUT
Specifies the name of the results of translating the input group. This parameter is required.
NAME_TRANS_TABLE
Specifies the name of a group that defines an attribute name translation table. The group is assumed to contain exactly one element. If more than one element is contained within the group, then the additional elements are ignored. The name of each attribute of the element identifies an attribute name to be translated. The value of each attribute specifies the new name. For example, if an attribute in the NAME_TRANS_TABLE group has the name “PartNo” and the value “PartNumber”, then every attribute named “PartNo” in the GROUP_IN group is renamed to “PartNumber” in the GROUP_OUT group.
NAME_TRANS_TABLE and TYPE_TRANS_TABLE can be specified together to change both the names and data types of attributes and their values. When both parameters are specified, it is important to remember that the attribute names specified by TYPE_TRANS_TABLE identify attributes in the GROUP_OUT group, after NAME_TRANS_TABLE has been applied. If TYPE_TRANS_TABLE specifies names of attributes that occur in the GROUP_IN group, but one or more of these are not translated using NAME_TRANS_TABLE, then these attributes are copied to the GROUP_OUT group with their names unchanged, but their values translated using TYPE_TRANS_TABLE into different data types.
The NAME_TRANS_TABLE and TYPE_TRANS_TABLE parameters can be specified in addition to the XSL_URL parameter. In this case, the XSL-based translation is executed first; the NAME_TRANS_TABLE and/or TYPE_TRANS_TABLE based translations are then applied to the output group produced by the XSL-based translation. Thus, the attribute names specified in the NAME_TRANS_TABLE identify attributes of the group produced by the XSL-based translation, not attributes of the original GROUP_IN group. In all cases, the attribute names specified in TYPE_TRANS_TABLE identify attributes of the final GROUP_OUT group.
PASSWD
Specifies the password corresponding to DBUSER.
This parameter is optional.
TYPE_TRANS_TABLE
Specifies the name of a group that defines an attribute value data type translation table. The group is assumed to contain exactly one element. If more than one element is contained within the group, then the additional elements are ignored. The name of each attribute identifies the name of an attribute in the GROUP_OUT group whose values are to be translated. The value of each attribute specifies the desired data type. For example, if an attribute in the TYPE_TRANS_TABLE group has the name “Quantity” and the value “Integer”, then every value of every attribute named “Quantity” in the GROUP_OUT group is converted to the data type INTEGER. The data types currently supported are:
BYTE – 8-bit value.
DOUBLE – double precision floating point value.
FLOAT – single precision floating point value.
INTEGER – integer value with default range.
LONG – integer value with long range.
SHORT – integer value with short range.
STRING – character string value.
NAME_TRANS_TABLE and TYPE_TRANS_TABLE can be specified together to change both the names and data types of attributes and their values. When both parameters are specified, the attribute names specified by TYPE_TRANS_TABLE identify attributes in the GROUP_OUT group, after NAME_TRANS_TABLE has been applied. If TYPE_TRANS_TABLE specifies names of attributes that occur in the GROUP_IN group, but one or more of these are not translated using NAME_TRANS_TABLE, then these attributes are copied to the GROUP_OUT group with their names unchanged, but their values are translated using TYPE_TRANS_TABLE into different data types.
The NAME_TRANS_TABLE and TYPE_TRANS_TABLE parameters can be specified in addition to the XSL_URL parameter. In this case, the XSL-based translation is executed first. The NAME_TRANS_TABLE and/or TYPE_TRANS_TABLE based translations are then applied to the output group produced by the XSL-based translation. Thus, the attribute names specified in the NAME_TRANS_TABLE identify attributes of the group produced by the XSL-based translation, not attributes of the original GROUP_IN group. In all cases, the attribute names specified in TYPE_TRANS_TABLE identify attributes of the final GROUP_OUT group.
XSL_PARAM
Defines XSL parameters that are then passed to the XSL stylesheet named in the XSL_URL parameter. 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 group specified in the GROUP_IN parameter. A relative URL or a fully qualified URL can be specified. Relative URLs are relative to the Info*Engine Server task template root. The XSL stylesheet should be constructed to apply to the Info*Engine XML format (the format shown in all examples in this guide, and produced by the Display-XML webject). The stylesheet must also produce Info*Engine XML format.
The NAME_TRANS_TABLE and TYPE_TRANS_TABLE parameters can be specified in addition to the XSL_URL parameter. In this case, the XSL-based translation is executed first; the NAME_TRANS_TABLE and/or TYPE_TRANS_TABLE based translations are then applied to the output group produced by the XSL-based translation.
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/servlet/IE/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, the stylesheet is assumed to be a local file relative to the current task template root directory.
This parameter is optional.
EXAMPLE
The following example translates the data from the group named “createdgroup” by renaming the attributes. The resulting data is placed in the group named “RenamedGroup”:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<!-- Create a test Group -->
<ie:task uri="com/company/CreateGroup.xml"/>
<!-- Create attribute translation Group -->
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT"
data="NAME=FullName:EMAIL=EmailAddress"/>
<ie:param name="GROUP_OUT" data="NewNames"/>
</ie:webject>
<!-- Translate the attribute names -->
<ie:webject name="Translate-Group" type="GRP">
<ie:param name="GROUP_IN" data="createdgroup"/>
<ie:param name="NAME_TRANS_TABLE" data="NewNames"/>
<ie:param name="GROUP_OUT" data="RenamedGroup"/>
</ie:webject>
<!-- Translate some of the attribute names -->
<ie:webject name="Translate-Group" type="GRP">
<ie:param name="GROUP_IN" data="createdgroup"/>
<ie:param name="NAME_TRANS_TABLE" data="NewNames"/>
<ie:param name="COPY_UNTRANSLATED" data="YES"/>
<ie:param name="GROUP_OUT" data="RenamedGroup"/>
</ie:webject>