Authoring Info*Engine Tasks
 |
When authoring an Info*Engine task it is very important to consider how you intend that task to be invoked. Info*Engine tasks might be executed in several different ways, including from other Java code using the SAK (for example, from a Windchill user interface or workflow), from a SOAP client, or from a raw HTTP client through the IE servlet. For example, if you are authoring a task that is intended to be called from a Windchill workflow you probably do not also intend for someone to be able to run that task through the IE servlet. To control how a task is executed, you can use the access attribute. For more information, <<<<<<< HEAD see page Directive section in Directives.
|
All webjects that do not directly deal with the display of information can be placed in Info*Engine tasks. That is, any webject with that has the DSP type exists only in a JSP page or custom application. The following standard webject types can be included in Info*Engine tasks and are known as “task webjects”:
• The GRP type, or group webjects.
• The OBJ type, or query webjects.
• The ACT type, or action webjects.
• The MGT type, or management webjects.
• The MSG type, or message webjects.
• The WES type, or Web Event Service webjects.
• The ADM type, or administrative webjects.
In addition, you can create external custom webjects (EXT) that provide custom solutions in either a JSP page or a standalone task. For more information, see Creating an External Custom Webject.
Think of a task as a script of commands executed by Info*Engine. Each command in a task is a webject. The webjects are executed in the sequence defined within the task. By default, the sequence is from the top to the bottom. The webjects within a task perform operations such as querying databases, combining and integrating data in interesting ways, performing schema translations, and creating and updating database information. For a task to be successful, it must contain at least one properly constructed webject.
The following CreateGroup.xml task creates a group consisting of names, street addresses, and email addresses:
<%@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>
<%@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 resulting “createdgroup” group generated by this task is shown as the following table:
|
NAME
|
ADDRESS
|
EMAIL
|
|---|---|---|
|
Sam Johnson
|
1234 Main St.
|
sjohnson@somewhere.com
|
|
Harvy Anderson
|
1234 Amber St.
|
handerson@somewhere.com
|
|
James O’Connor
|
775 Main St.
|
|
|
Harvey Hampton
|
775 Main St.
|
hhampton@somewhere.com
|
Notice that there was no EMAIL value specified for James O’Connor, so the corresponding table cell is empty.
Parts of a Task
Each Info*Engine standalone task should contain the following items:
• The standard JSP page directive.
Although the Info*Engine task compiler only uses the import attribute from the page directive, it is good practice to include it as the first line in your task file even when no additional classes are required. You should use fully qualified class names in scriptlets or specify the classes used in scriptlets on the import statement.
• The standard JSP taglib directive, which declares that the Info*Engine standalone task uses custom tags defined in a tag library.
You must put this directive before any lines that use the custom tags in the library.
• Info*Engine custom tags, which provide access to a set of custom actions that encapsulate recurring functionality.
The custom tags provide the syntax for executing webjects and provide the structure around which you can build a task.
The previous CreateGroup.xml example task includes the following standard JSP directives:
<%@page language="java" session="false"%>
This is the standard page directive. No additional classes are required for this task.
To identify the “core” Info*Engine tag library you must include the following:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
prefix="ie" %>
This provides the general tags that can be used in the task and specifies ie as the required prefix that identifies the tag as belonging to the core tag library.
The previous CreateGroup.xml example task also includes the webject and param tags:
• The webject tag identifies the Create-Group webject.
• The param tags supply webject parameters and parameter values.
For the Create-Group webject, the parameters define both name of the output group and the attributes and values of elements in the group.
There are many more custom tags that you can use in a task. For the description and syntax of all of the custom tags, see Info*Engine Tags.
In addition to directives and custom tags, you can include JSP scriptlets, expressions, and declarations in your Info*Engine tasks. For the details on how the Info*Engine task compiler processes scriptlets, expressions, and declarations, see their corresponding descriptions in Scriptlets, Expressions, and Declarations.
Task Creation
You can create task files using any standard editing tool. Using a tool that provides you with a Graphical User Interface (GUI) for inserting custom tags and JSP elements is helpful, but not required.
For additional information on creating tasks, see Using the Info*Engine Task Editor.
Task File Extension
You should save your task files using the .xml extension. Info*Engine recognizes files with this extension as tasks.
Task File Location
Info*Engine provides a directory structure under which you should save your task files. Using this directory structure allows you to execute tasks from a web browser URL and to specify a relative path to the task when executing it from within another task or from a JSP page.
Windchill is configured to look for Info*Engine tasks within the <Windchill>/tasks directory. You must save your tasks somewhere within the tasks directory. Ideally, you should create a directory hierarchy to organize your tasks, such as <Windchill>/tasks/com/company/CreateGroup.xml.
Task Execution
You can execute a standalone task in the following ways:
• Specify the task in the Info*Engine custom task tag.
You can include the task tag in JSP pages and in other tasks.
• Enter the task URL in a web browser.
• Submit the task so that it is queued for execution.
• Emit an event that results in a task being executed.
 |
The URLs and URIs shown in this guide use the forward slash as the separator (/) in paths. Info*Engine correctly identifies all system URLs and URIs when you specify the forward slash. If you prefer to use the back slash for NT URLs and URIs, you must escape the back slash. This means that you enter two back slashes (\\) for each slash (\).
|
Specifying a Task in a task Tag
The uri attribute on the Info*Engine task tag names the task to execute. For example, to execute the CreateGroup.xml task described previously, you could include the following elements in a JSP page:
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<ie:task uri="/com/company/CreateGroup.xml"/>
prefix="ie" %>
<ie:task uri="/com/company/CreateGroup.xml"/>
In this example, the taglib directive identifies the Info*Engine core tag library and defines ie as the prefix that the tags use. The task tag specifies the relative path to the CreateGroup.xml task.
The group created by the example task is automatically available to the rest of the elements on the JSP page. These elements could further manipulate the data in the group or could display the group back to the user who initiated the execution of the JSP page. For example, assume that a user executed the following JSP page:
<%@page language="java" session="false"
errorPage="IEError.jsp%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<ie:task uri="/com/company/CreateGroup.xml"/>
<ie:webject name="Display-Table" type="DSP">
<ie:param name="GROUP_IN"data="createdgroup"/>
</ie:webject>
errorPage="IEError.jsp%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie" %>
<ie:task uri="/com/company/CreateGroup.xml"/>
<ie:webject name="Display-Table" type="DSP">
<ie:param name="GROUP_IN"data="createdgroup"/>
</ie:webject>
The CreateGroup.xml task executed through the task tag is the same task described earlier. The output from this task is the “createdgroup” group, which is then used as input to the Display-Table webject. Executing this page results in the following display:
Entering a Web Browser URL
Entering a task URL in the web browser is an easy way to execute the task without providing the additional coding required to execute the task through an application or JSP page.
The installer also specifies an application URL that is used as the URL prefix for requesting Info*Engine tasks. Produce the URL that contains the request to execute Info*Engine JSP pages by doing the following:
• Including the host name and application URL prefix specified when Windchill was installed. The default application URL is Windchill.
• Including the /servlet/IE/tasks prefix, which directs the servlet to the task processor.
• Specifying the path for the task that is relative to the tasks directory.
• Specifying any optional parameters to pass to the task.
| | If your site is using form-based authentication, programmatic clients attempting to access the IE servlet must use the /protocolAuth URL prefix. For example: http://<host>/Windchill/protocolAuth/servlet/IE For more information about form-based authentication, see Authentication. |
Therefore, to execute the com/company/CreateGroup.xml task using the myServer host name and the Windchill application URL, specify the following URL:
http://myServer/Windchill/servlet/IE/tasks/com/company/CreateGroup.xml
The XML output displayed in the browser is similar to the following:
<?xml version="1.0" encoding="UTF-8"?>
<wc:COLLECTION xmlns:wc="http://www.ptc.com/infoengine/1.0">
<EmployeeData NAME="createdgroup" TYPE="Object" STATUS="0">
<wc:INSTANCE>
<NAME>Sam Johnson</NAME>
<ADDRESS>1234 Main St.</ADDRESS>
<EMAIL>sjohnson@somewhere.com</EMAIL>
</wc:INSTANCE>
<wc:INSTANCE>
<NAME>Harvy Anderson</NAME>
<ADDRESS>1234 Amber St.</ADDRESS>
<EMAIL>handerson@somewhere.com</EMAIL>
</wc:INSTANCE>
<wc:INSTANCE>
<NAME>James O'Connor</NAME>
<ADDRESS>775 Main St.</ADDRESS>
<EMAIL></EMAIL>
</wc:INSTANCE>
<wc:INSTANCE>
<NAME>Harvey Hampton</NAME>
<ADDRESS>775 Main St.</ADDRESS>
<EMAIL>hhampton@somewhere.com</EMAIL>
</wc:INSTANCE>
</EmployeeData>
</wc:COLLECTION>
<wc:COLLECTION xmlns:wc="http://www.ptc.com/infoengine/1.0">
<EmployeeData NAME="createdgroup" TYPE="Object" STATUS="0">
<wc:INSTANCE>
<NAME>Sam Johnson</NAME>
<ADDRESS>1234 Main St.</ADDRESS>
<EMAIL>sjohnson@somewhere.com</EMAIL>
</wc:INSTANCE>
<wc:INSTANCE>
<NAME>Harvy Anderson</NAME>
<ADDRESS>1234 Amber St.</ADDRESS>
<EMAIL>handerson@somewhere.com</EMAIL>
</wc:INSTANCE>
<wc:INSTANCE>
<NAME>James O'Connor</NAME>
<ADDRESS>775 Main St.</ADDRESS>
<EMAIL></EMAIL>
</wc:INSTANCE>
<wc:INSTANCE>
<NAME>Harvey Hampton</NAME>
<ADDRESS>775 Main St.</ADDRESS>
<EMAIL>hhampton@somewhere.com</EMAIL>
</wc:INSTANCE>
</EmployeeData>
</wc:COLLECTION>
Submitting Tasks and Emitting Events
If your Info*Engine environment includes the implementation of Info*Engine task queuing or the Web Event Service with a Message-Oriented Middleware (MOM) software product such as IBM MQSeries, you can execute tasks through specialized webjects that are provided for these environments. Using these webjects requires the installation and configuration of additional third-party products and also requires additional Info*Engine configuration.
Your site administrator should know if your environment includes any of these optional features. For implementation information, see About the Configuration Process . For more webject information, see Message Webjects and Subscribe—Event in Web Event Service Webjects