Reporting Info*Engine Task Data Source Customization

Advanced Customization > Business Logic Customization > Report Generation > Reporting Info*Engine Task Data Source Customization

Objective

You want to create a new Windchill programmatic data retrieval task to use in a report.

Background

The Windchill Business Reporting (WBR) solution uses Data Source objects to retrieve data from Windchill. One type of Data Source is an Info*Engine task. An Info*Engine task is a text-based document that uses programmatic constructs to retrieve and manipulate Windchill data. The task must return its data in a tabular format (i.e. each element must have the same number of attributes) and task must be commented with special tags and syntax to define it as a WBR Data Source.

Scope/Applicability/Assumptions

This documentation assumes that the Windchill Business Reporting (WBR) solution (i.e. Cognos) has been successfully installed and configured. The Windchill instance name is referred to as <WindchillInstanceName>. The Cognos root URL is referred to as <WBRHomeURL>. Typically, if the WBR solution is installed on <WBRHost>, then the <WBRHomeURL> would be http://<WBRHost>/cognos8/cgi-bin/cognos.cgi. It is assumed that you can login to <WBRHomeURL> and you have sufficient Cognos privileges to view Windchill Data Source objects and create reports.

Assume you have access to the Windchill server tasks directory, <WindchillHome>/tasks, to create an Info*Engine task <MyTask> in sub-directory <MyTaskPackage>.

For WBR integration, you must also have access rights to update the reporting meta model.

This document does not contain details on how to construct Info*Engine tasks. See the section Info*Engine User’s Guide for this information.

Intended Outcome

The end result of this solution is the creation of your Data Source that can be used to author Cognos reports.

Solution

Construct an Info*Engine Task Data Source.

Procedure – Creating an Info*Engine Task Data Source

1. Create an Info*Engine task XML file in <WindchillHome>/tasks/<MyTaskPackage>.

2. Write report task to return results in tabular format. This is an otherwise normal Info*Engine task that follows certain additional conventions. First, it returns a tabular Group where each column has objects of the same type. The following are the allowed column types:

◦ java.lang.Boolean

◦ java.lang.Long

◦ java.lang.String

◦ java.sql.Timestamp

◦ java.util.Date

◦ java.lang.Double

◦ com.ptc.core.meta.common.FloatingPoint

◦ com.ptc.core.meta.common.Hyperlink

◦ java.math.BigDecimal

3. Add WBR Data Source parameter information to the task comments. There can be zero or more parameter comments. Each specified parameter must exist on a single line. The syntax for the parameter comment is as follows:

@param <type> <name> <description>

where <type> is the parameter Java type, <name> is the parameter name, and <description> describes the parameter. The following are the allowed parameter types:

◦ java.lang.Boolean

◦ java.lang.Long

◦ java.lang.String

◦ java.sql.Timestamp

◦ java.util.Date

◦ java.lang.Double

◦ java.math.BigDecimal

4. Add WBR Data Source column information to the “return” task comment. The column information must be specified in the correct format for this task to be considered a Data Source. The syntax for the column comment is as follows:

@return <type> ${<variableName>} {columns: <columnList>}

where <type> is the Info*Engine task output type, <variableName> is a reference to the task variable that will be returned, and <columnList> describes the tabular format of the output. For more information on <type> and {<variableName>} consult section Info*Engine Task Invocation with SOAP in the Windchill Help Center. The column is a comma separate list of one or more type and name pairs for each column in the tabular output. The type and name are separated by whitespace. The following are the allowed column types:

◦ java.lang.Boolean

◦ java.lang.Long

◦ java.lang.String

◦ java.sql.Timestamp

◦ java.util.Date

◦ java.lang.Double

◦ com.ptc.core.meta.common.FloatingPoint

◦ com.ptc.core.meta.common.Hyperlink

◦ java.math.BigDecimal

5. Add task as a method to a ReportTask type. Create a file named “.delegateInfo” in the same directory as the task file. The file should contain the following two lines:

repositoryType=com.ptc.windchill

typeId=com.ptc.windchill.enterprise.report.ReportTask

6. Create and Install a package for <MyTask>. See Info*Engine Packages.

7. Update the Cognos model to recognize this new Data Source. Launch JConsole from installed Windchill shortcuts. Connect to the Embedded Servlet Engine (based on Tomcat) JVM instance. Select reporting management bean from the MBeans tab, “com.ptc > Monitors > ReportingSystem”. From the Operations tab, click “updateModel”.

8. Verify that the Data Source exists in Cognos. Login to Cognos using the <WBRHomeURL> and launch “Report Studio”. Find <MyTask> Data Source under “Windchill > Report Tasks > com.ptc.windchill.enterprise.report.ReportTask” in the “Insertable Objects” window under the “Source” tab.

The following is an example of task comments for a Data Source.

Customization Points

Procedure – Creating an Info*Engine Task Data Source under another Type

In the primary procedure above, the Info*Engine Task was created using the default reporting type, com.ptc.windchill.enterprise.report.ReportTask. The type correlates to the “Windchill > Report Tasks > com.ptc.windchill.enterprise.report.ReportTask” level of the Source tab. The Report task type can be used to group Data Sources logically. A variation of the primary procedure is to create the Info*Engine Task under another type, “myPackage.MyReportTask”.

1. This type will need to be added to the comma separated list of reporting types specified in the property com.ptc.windchill.enterprise.report.reportTaskClassNames

2. This property must be changed before executing step 7 of the Creating an Info*Engine Task Data Source procedure above.

3. In step 5 of the Creating an Info*Engine Task Data Source procedure above, the .delegateInfo entry for typeId should specify “myPackage.MyReportTask”.

4. In step 8 of the Creating an Info*Engine Task Data Source procedure above, the Data Source will now be available under “Windchill > Report Tasks > myPackage.MyReportTask”.

Procedure – Deleting an Info*Engine Task Data Source

An Info*Engine Task Data Source that is no longer needed can be removed from the system by deleting it from Windchill and updating the Cognos model. Alternatively, the task comments can be removed so that it is not recognized as a Data Source.

1. To remove a task, uninstall the package and remove the XML file from the tasks directory.

2. Then, update the Cognos model using step 3 of the Creating an Info*Engine Task Data Source procedure above.

Limitations

The typeId in the .delegateInfo file maps to the SOAP class and the task file name maps to the SOAP method within that class. Both of these names should only contain characters valid for Java identifiers. In addition, the methods must all be unique for a given class. For a given typeId, each task name must be unique.

Sample Code

Examples of Usage in Windchill Code

There are several out-of-the-box reports that use Info*Engine Task Data Sources. These Data Sources are listed in the “Windchill > Report Tasks > com.ptc.windchill.enterprise.report.ReportTask” level of the Source tab. These Data Sources can be used for creating Cognos reports. However, directly modifying the associated Info*Engine Tasks is not supported.

Packaged Samples

A demo Info*Engine task Data Source, ContextItems, is available in the “Windchill > Report Tasks > com.ptc.windchill.enterprise.report.ReportTask” level of the Source tab. The task source is located in <WindchillHome>/tasks/com/ptc/windchill/enterprise/reports/ContextItems.xml. It retrieves the union of all Parts and Documents in a specified context.

Additional Resources

Related Best Practices

• Reporting — ReportTemplate Data Source Customization

• Reporting — Cognos Presentation Customization

Related Package/Class Javadoc

• Reporting module

◦ com.ptc.windchill.enterprise.report