Dynamic Parameter Value Substitution
Although most simple Windchill installations do not require them, webject parameter values must often be taken directly from user input in a web-based form or as a group of unknown size or kind from a data repository. Info*Engine provides a mechanism called “dynamic parameter value substitution” that can be used in the following situations:
• When information comes from a web-based form or as URL parameters.
• When information comes from the data objects in a VDB group.
The substitution required in a webject is applied once, immediately before a webject is executed. Therefore, to substitute values from a group that is created through the execution of a task, you must execute the task before you execute the webject that contains the substitution expressions. You cannot execute the task from within the webject.
You can use Info*Engine substitution expressions in data attribute values on the param tag used in any webjects.
General Value Substitution Syntax
Info*Engine substitution expressions are always delimited by the characters $( and ). Within these delimiters, specify the group and attributes for which the substitution is made as follows:
$(group_name[element_selector]attribute_name[value_selector])
where:
group_name
Names a group that exists in the VDB. This group can be a context group such as @FORM or a data group that results from the execution of a task.
element_selector
Identifies the elements (rows) within the group that are selected. The selector can be one of the following:
◦ An integer, which identifies an element by its index. The first element has an index of 0. Therefore, if a group contains 10 elements, their indices range from 0 to 9.
◦ The letter N, which selects the last element of the group.
◦ Empty, which selects all elements and concatenates them together into a string using no separators. The empty selector is usually used when there is only one element.
◦ The word META, which selects the metadata from the group instead of selecting elements.
◦ The asterisk (*) symbol, which selects all elements and concatenates them together into a string. Semicolons separate the elements in the string.
◦ An attribute and value pair specified as attribute=value. Info*Engine selects the first element it finds that contains the specified value for the named attribute. For example, assume that the “grp1” group contains “name” and “phone” attributes. To locate the phone number of an employee named “Doyle,” use the following substitution expression:
$(grp1[name=Doyle]phone[])
attribute_name
Names an attribute (column) that exists within the selected elements.
If META is specified for element_selector, then one of the following attributes can be specified for attribute_name:
◦ COUNT is the number of elements in the group.
◦ STATUS is the numeric status value currently associated with the group. A status of 0 indicates success. A status of anything but 0 indicates failure.
◦ NAME is the name of the group.
◦ TYPE is the type of group. The group creator may set the meta value of TYPE but is not required to. Valid group types include:
▪ Object -- The group contains data.
▪ Status -- The group contains the success or failure of a request
▪ Exception -- The group contains the error information produced when an exception has occurred.
▪ Unknown -- The group creator did not set the TYPE information for the group.
◦ MESSAGE is the current message associated with the group. If there is no message associated with the group, the substitution is an empty string. You can retrieve multiple messages from the MESSAGE metadata. For example, to get all messages associated with “Grp123” you can use the following substitution expression:
$(Grp123[META]MESSAGE[*])
In addition, you can specify any metadata attribute defined in the group for attribute_name.
value_selector
Identifies the attribute values that are selected. The selector can be one of the following:
◦ An integer, which identifies a value by its index. The first value has an index of 0. Therefore, if an attribute contains 5 values, their indices range from 0 to 4.
◦ The letter N, which selects the last value of the attribute.
◦ Empty, which selects all values and concatenates them together into a string using no separators. The empty selector is usually used when there is only one value.
◦ The asterisk (“*”) symbol, which selects all values and concatenates them together into a string. Commas separate the values in the string.
The following substitution expression selects all XYZ values from the element in the @FORM group and concatenates them together into a string using a comma to separate the values:
$(@FORM[]XYZ[*])
The following substitution expression selects the first NAME attribute value from the element in the USERS group:
$(USERS[]NAME[0])
The following substitution expression selects the COUNT value from the metadata in the OUTGRP group:
$(OUTGRP[META]COUNT[])
Default Values for Substitutions
To cover the possibility that the evaluation of a substitution expression could return no values, you should include a default for the expression. Specify a default by including the following default attribute on the param tag:
default="value"
For example, the following param tag sets the default for the ATTRIBUTE parameter to the string "*":
<ie:param name="ATTRIBUTE" … default="*"/>
Substitution Expressions for User-Specified Values
When information must be specified by a user rather than by the designer of a task, the substitution expressions that access the @FORM context group makes this information available within a webject even though the exact value is not known at the time the template or task is being designed.
You can use substitution expressions in any data attribute value on a param tag.
To specify one parameter value as input by a user in a web-based form or on a URL, the parameter value can be similar to the following:
data="$(@FORM[]variable[])"
You use @FORM[] in these formats because there is only one element in the @FORM context group. The empty value selector, [], for the form variable is used because there is only one value equated to the variable.
To specify multiple parameter values as input, you include the asterisk (*) as the value selector. To format multiple parameter values correctly, you must also include the delim attribute to identify the comma as the separator in the string that is substituted. For multiple values, the parameter value can be similar to the following:
data="$(@FORM[]variable[*])" delim=","
The asterisk in the value selector, [*], selects all values and concatenates them together into a string using the comma as a separator. The delim attribute tells the webject that multiple values in the data attribute are separated by a comma.
 |
If the form you use includes an INPUT element that has a control type of file select for selecting files to upload, all of the form variables you want to use in parameter substitution must be set on the form before the INPUT element. For more information, see Uploading and Downloading BLOBs.
|
Example: Display-Object Substitution Using @FORM
The following variables set up the table format and attributes that are visible to the user. The values for the variables are available in the @FORM context group and can be retrieved from this group.
border=2
att=ename
att=phone
headers=Name
headers=Telephone
Also assume that the following Display-Object webject resides in an Info*Engine JSP page and displays an employee list using the variables from the form:
<ie:task uri="listemployees"/>
<ie:webject name="Display-Object" type="DSP">
<ie:param name="BORDER" data=$(@FORM[]border[])/>
<ie:param name="ATTRIBUTE" data=$(@FORM[]att[*]) delim=","
default="*"/>
<ie:param name="HEADER" data=$(@FORM[]headers[*]) delim=","/>
</ie:webject>
<ie:webject name="Display-Object" type="DSP">
<ie:param name="BORDER" data=$(@FORM[]border[])/>
<ie:param name="ATTRIBUTE" data=$(@FORM[]att[*]) delim=","
default="*"/>
<ie:param name="HEADER" data=$(@FORM[]headers[*]) delim=","/>
</ie:webject>
After substitution processing by Info*Engine, the parameters in the webject are as follows:
<ie:webject name="Display-Object" type="DSP">
<ie:param name="BORDER" data="2"/>
<ie:param name="ATTRIBUTE" data="ename,phone" delim=","
default="*"/>
<ie:param name="HEADER" data="Name,Telephone" delim=","/>
</ie:webject>
<ie:param name="BORDER" data="2"/>
<ie:param name="ATTRIBUTE" data="ename,phone" delim=","
default="*"/>
<ie:param name="HEADER" data="Name,Telephone" delim=","/>
</ie:webject>
Example: Query-Objects Substitution Using @FORM
Assume that the following URL has been submitted to “webServer1”:
http://webServer1/Windchill/servlet/IE/tasks/QueryObject.xml?CLS=EMPLOYEES&ATTS=
NAME&ATTS =EMPNO&ATTS=SALARY&WHR=NAME='&SMITH'
NAME&ATTS =EMPNO&ATTS=SALARY&WHR=NAME='&SMITH'
Then, the @FORM context group contains the following variables:
CLS=EMPLOYEES
ATTS=NAME
ATTS=EMPNO
ATTS=SALARY
WHR=NAME='&SMITH'
Also assume that the following Query-Objects webject resides in the QueryObject.xml task and queries the information system connected to the “jdbc” adapter using the variables from the URL:
<ie:webject name="Query-Objects" type="ACT">
<ie:param name="INSTANCE" data="jdbc"/>
<ie:param name="ATTRIBUTE" data="$(@FORM[]ATTS[*])" delim=","
default="*"/>
<ie:param name="CLASS" data="$(@FORM[]CLS[0])" default="EMP"/>
<ie:param name="WHERE" data="$(@FORM[]WHR[0])" default="()"/>
<ie:param name="GROUP_OUT" data="queryStatus"/>
</ie:webject>
<ie:param name="INSTANCE" data="jdbc"/>
<ie:param name="ATTRIBUTE" data="$(@FORM[]ATTS[*])" delim=","
default="*"/>
<ie:param name="CLASS" data="$(@FORM[]CLS[0])" default="EMP"/>
<ie:param name="WHERE" data="$(@FORM[]WHR[0])" default="()"/>
<ie:param name="GROUP_OUT" data="queryStatus"/>
</ie:webject>
After substitution processing by Info*Engine, the parameters in the webject are as follows:
<ie:webject name="Query-Objects" type="ACT">
<ie:param name="INSTANCE" data="jdbc"/>
<ie:param name="ATTRIBUTE" data="NAME,EMPNO,SALARY" delim=","
default="*"/>
<ie:param name="CLASS" data="EMPLOYEES" default="EMP"/>
<ie:param name="WHERE" data="NAME='&SMITH'" default="()"/>
<ie:param name="GROUP_OUT" data="queryStatus"/>
</ie:webject>
<ie:param name="INSTANCE" data="jdbc"/>
<ie:param name="ATTRIBUTE" data="NAME,EMPNO,SALARY" delim=","
default="*"/>
<ie:param name="CLASS" data="EMPLOYEES" default="EMP"/>
<ie:param name="WHERE" data="NAME='&SMITH'" default="()"/>
<ie:param name="GROUP_OUT" data="queryStatus"/>
</ie:webject>
After all processing is completed by Info*Engine, the parameters in the webject are as follows:
<ie:webject name="Query-Objects" type="ACT">
<ie:param name="INSTANCE" data="jdbc"/>
<ie:param name="ATTRIBUTE" data="NAME"/>
<ie:param name="ATTRIBUTE" data="EMPNO"/>
<ie:param name="ATTRIBUTE" data="SALARY"/>
<ie:param name="CLASS" data="EMPLOYEES"/>
<ie:param name="WHERE" data="NAME='&SMITH'"/>
<ie:param name="GROUP_OUT" data="queryStatus"/>
</ie:webject>
<ie:param name="INSTANCE" data="jdbc"/>
<ie:param name="ATTRIBUTE" data="NAME"/>
<ie:param name="ATTRIBUTE" data="EMPNO"/>
<ie:param name="ATTRIBUTE" data="SALARY"/>
<ie:param name="CLASS" data="EMPLOYEES"/>
<ie:param name="WHERE" data="NAME='&SMITH'"/>
<ie:param name="GROUP_OUT" data="queryStatus"/>
</ie:webject>
Substitution Expressions for VDB Data Group-Specified Values
When information must come from a VDB group that has been generated, the substitution expressions that access a VDB data group makes this information available within a webject even though the exact value is not known at the time the task is being designed.
|
|
The VDB group must be available to the webject before the webject executes. You cannot execute the task that creates the group from within the webject.
|
You can use substitution expressions in any data attribute value on a param tag.
To specify one parameter value that is substituted from a VDB data group, the parameter value can be similar to the following:
data=$(grp_name[]att_name[])
Use grp_name[] in these formats when there is only one element (row) in the group named “grp_name.” Use att_name[] in these formats when there is only one value in the att_name attribute. If the data group has more than one element, you can use grp_name[0] to access the first element in the group and use grp_name[N] to access the last element in the group. To access other elements, you can specify the index of the element inside the brackets. Similarly, you can use 0, N, or other indices inside the brackets to access a specific value in the attribute named by att_name[].
To specify multiple parameter values as input, you include the asterisk (*) as the value selector. To format multiple parameter values correctly, you must also include the delim attribute to identify the comma as the separator in the string that is substituted. For multiple values, the parameter value can be similar to the following:
data=$(grp_name[]att_name[*]) delim=","
The asterisk in the value selector, [*], selects all values and concatenates them together into a string using the comma as a separator. The delim attribute tells the webject that multiple values in the data attribute are separated by a comma.
The last set of formats assumes that there is only one element in the named group. If the data group has more than one element, you can use grp_name[0] to access the first element in the group and use grp_name[N] to access the last element in the group. To access other elements, you can specify the index of the element inside the brackets.
For more information, see General Value Substitution Syntax in this topic.
Example: Create-Group Substitution Using A VDB Data Group
Assume that the following table represents the elements (rows), attributes (column headings) and attribute values (cells in columns) in the “EMP” VDB group:
|
ename
|
phone
|
|---|---|
|
Burton, Jack
|
873-2302
|
|
Law, Gracie
|
873-2200
|
|
LoPan, David
|
873-3313
|
You can create a new group called “salesEmp” by adding the DEPT attribute column to the “EMP” group using substitution in the following Create-Group webject:
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT" data="NAME=$(EMP[0]ename[]):
TELEPHONE=$(EMP[0]phone[]):DEPT=Sales"/>
<ie:param name="ELEMENT" data="NAME=$(EMP[1]ename[]):
TELEPHONE=$(EMP[1]phone[]):DEPT=Sales"/>
<ie:param name="ELEMENT" data="NAME=$(EMP[2]ename[]):
TELEPHONE=$(EMP[2]phone[]):DEPT=Sales"/>
<ie:param name="CLASS" data="SalesEmployees"/>
<ie:param name="GROUP_OUT" data="salesEmp"/>
</ie:webject>
<ie:param name="ELEMENT" data="NAME=$(EMP[0]ename[]):
TELEPHONE=$(EMP[0]phone[]):DEPT=Sales"/>
<ie:param name="ELEMENT" data="NAME=$(EMP[1]ename[]):
TELEPHONE=$(EMP[1]phone[]):DEPT=Sales"/>
<ie:param name="ELEMENT" data="NAME=$(EMP[2]ename[]):
TELEPHONE=$(EMP[2]phone[]):DEPT=Sales"/>
<ie:param name="CLASS" data="SalesEmployees"/>
<ie:param name="GROUP_OUT" data="salesEmp"/>
</ie:webject>
After substitution processing by Info*Engine, the parameters in the webject are as follows:
<ie:webject name="Create-Group" type="GRP">
<ie:param name="ELEMENT" data="NAME=Burton, Jack:
TELEPHONE=873-2302:DEPT=Sales"/>
<ie:param name="ELEMENT" data="NAME=Law, Gracie:
TELEPHONE=873-2200:DEPT=Sales"/>
<ie:param name="ELEMENT" data="NAME=LoPan, David:
TELEPHONE=873-3313:DEPT=Sales"/>
<ie:param name="CLASS" data="SalesEmployees"/>
<ie:param name="GROUP_OUT" data="salesEmp"/>
</ie:webject>
<ie:param name="ELEMENT" data="NAME=Burton, Jack:
TELEPHONE=873-2302:DEPT=Sales"/>
<ie:param name="ELEMENT" data="NAME=Law, Gracie:
TELEPHONE=873-2200:DEPT=Sales"/>
<ie:param name="ELEMENT" data="NAME=LoPan, David:
TELEPHONE=873-3313:DEPT=Sales"/>
<ie:param name="CLASS" data="SalesEmployees"/>
<ie:param name="GROUP_OUT" data="salesEmp"/>
</ie:webject>
Executing the Create-Group webject creates the “salesEmp” group that is represented by the following table:
|
NAME
|
TELEPHONE
|
DEPT
|
|---|---|---|
|
Burton, Jack
|
873-2302
|
Sales
|
|
Law, Gracie
|
873-2200
|
Sales
|
|
LoPan, David
|
873-3313
|
Sales
|
Returning Multiple Values in Substitution Expressions
Using the asterisk (*) for the element selector or for the value selector in a substitution expression can return a string containing multiple values. The string can contain:
• Multiple attribute values from a single element and attribute pair.
• The attribute values from multiple elements that correspond to a single attribute.
To understand how these combinations are represented in the string, consider the following graphical representation of a group named “tbl”:
Multiple Attribute Values from One Element
To return a string containing all Y attribute values from element 1 (A and A1), include the following data attribute:
data="$(tbl[0]Y[*])"
The string returned is:
"A,A1"
Notice that the comma separates the values.
To specify a different separator, you must include the valueSeparator attribute. For example, to return a colon-separated list, use the following:
data="$(tbl[0]Y[*])" valueSeparator=":"
Then, the string returned is:
"A:A1"
First Attribute Value From Each Element
To return a string containing the first Z attribute value from each element (56 and 77), include the following data attribute:
data="$(tbl[*]Z[0])"
By default, the string returned is:
"56;77;"
Notice that the semicolon separates values from different cells and that there is no value for the third element.
To specify a different separator, you must include the elementSeparator attribute. For example, to return a percent-separated list, use the following:
data="$(tbl[*]Y[0])" elementSeparator="%"
Then, the string returned is:
"56%77%"
Multiple Attribute Values From All Elements
To return a string containing all Y attribute values from all elements (A, A1, B, B1, and C), include the following data attribute:
data="$(tbl[*]Y[*])"
By default, the string returned is:
"A,A1;B,B1;C"
Notice that the comma separates the values in one cell and the semicolon separates values from different cells.
To specify different separators, you must include the valueSeparator and elementSeparator attributes. For example, to return a string that uses the colon and percent symbols as separators, use the following:
data="$(tbl[*]Y[*])" valueSeparator=":" elementSeparator="%"
Then, the string returned is:
"A:A1%B:B1%C"
Selecting an Element by an Attribute-Value Pair in Substitution Expressions
Using an attribute–value pair for the element selector in a substitution expression provides a way to select an element without knowing the index number of the element.
To understand how the selections works, consider the following graphical representation of a group named “tbl”:
Element Selection
To return a string containing all Y attribute values from the element where X=221, include the following data attribute:
data="$(tbl[X=221]Y[*])"
The X attribute value of 221 is located in element number 2, therefore the Y attribute values returned in the string are:
"B,B1"
By default, the comma separates the values.