Management Webjects

Advanced Customization > Info*Engine User’s Guide > Administrative Webjects > Management Webjects

Management Webjects

The following webjects provide some common functions, such as getting properties, mapping credentials, and throwing exceptions, that can be useful in managing your JSP pages or tasks:

• Dispatch-Tasks

• Generate-WSDL

• Get-Properties

• Get-Resource

• List-Repositories

• Lookup-Services

• Map-Credentials

• Query-Schema

• Query-TypeHierarchy

• Throw-Exception

• Write-Log

All management webjects use the MGTtype attribute value in the webject tag.

Dispatch-Tasks

DESCRIPTION

Selects a task that is capable of executing a specified action against objects of the specified type residing at the specified location. The webject facilitates the development of applications that operate upon information distributed across multiple hosts or comprised of multiple object types.

SYNTAX

<ie:webject name="Dispatch-Tasks" type="MGT">
<ie:param name="ACCESS" data="http|soap|internal"/>
  <ie:param name="ACTION" data="action_name"/>
  <ie:param name="CLIMBER" data="class_name"/>
  <ie:param name="DEFAULT_DOMAIN" data="domain_name"/>
  <ie:param name="DEFAULT_TYPE" data="type_name"/>
  <ie:param name="GROUP_IN" data="group_name"/>
  <ie:param name="GROUP_VDB" data="group_name"/>
  <ie:param name="ID_ATTRIBUTE" data="attr_name"/>
  <ie:param name="ID_META_ATTRIBUTE" data="meta_name"/>
  <ie:param name="MAX_CONCURRENT" data="integer"/>
  <ie:param name="PARAM" data="name=value"/>
  <ie:param name="TASKS" data="group_name_or_url"/>
  <ie:param name="TYPE_ATTRIBUTE" data="attr_name"/>
  <ie:param name="TYPE_META_ATTRIBUTE" data="meta_name"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
ACTION	ACCESS	CLIMBER
GROUP_IN	ID_ATTRIBUTE	GROUP_VDB
TASKS	ID_META_ATTRIBUTE	MAX_CONCURRENT
	TYPE_ATTRIBUTE	PARAM
	TYPE_META_ATTRIBUTE

ACCESS

Specifies the required access configuration of the task that is called as a result of this Dispatch-Tasks invocation. This parameter value is only consulted if the value of the ACTION parameter has been supplied from an external client. It behaves identically to the access attribute on a task page directive. The value can be a pipe-delimited list of access values. If no value is specified then the default task access of the system is used. For more information about the access attribute, see page Directive.

ACTION

Specifies the name of the logical action that is performed by the tasks that are selected and executed. ACTION is the primary selector used in choosing the tasks to be executed. This parameter is required.

CLIMBER

Identifies the name of a Java class which climbs data type hierarchies in search of task delegates. If specified, the parameter continues to be called by the webject until it either succeeds in finding the appropriate task delegate or reaches the top of the hierarchy. If the top of the hierarchy is reached without finding a task delegate, an exception is thrown. This parameter is optional.

DEFAULT_DOMAIN

Specifies a default domain to use instead of deriving the domain from the name of the local virtual machine in cases where objects don’t have attributes or metadata that identifies their domains.

DEFAULT_TYPE

Specifies a default type name to use instead of com.ptc.object in cases where objects don’t have attributes of metadata that identifies their types.

GROUP_IN

Specifies the name of the group containing the object upon which the logical action specified by ACTION is taken. Multiple values can be specified for this parameter, resulting in more than one group of objects upon which to apply the ACTION. This parameter is required.

GROUP_VDB

Provides the names of one or more groups that are provided to each of the called tasks in their VDBs. These names populate each of the called tasks’ VDBs with an initial set of groups other than the groups specified as GROUP_IN parameters.

ID_ATTRIBUTE

Specifies the name of the attribute that every element of the input group contains and that specifies each respective element’s unique object identifier. For example, if the value of this parameter is OBID, then it is assumed that every element of the input group contains an attribute named OBID, and that the value of each such attribute identifies the unique object identifier of the element containing it.

If specified, ID_ATTRIBUTE takes precedence over the ID_META_ATTRIBUTE. If neither ID_ATTRIBUTE nor ID_META_ATTRIBUTE is specified, an internal API is called to obtain the element’s unique object identifier. If an element is a Windchill type instance, then the API returns the Windchill type identifier of the object.

If either ID_ATTRIBUTE or ID_META_ATTRIBUTE is specified and fail to resolve an element’s unique object identifier an internal API is used to obtain the unique object identifier.

ID_META_ATTRIBUTE

Specifies the name of the metadata item that every element of the input group contains and that specifies each respective element’s unique object identifier. For example, if the value of this parameter is com.infoengine.obid, then it is assumed that every element of the input group contains a metadata item named com.infoengine.obid, and the value of each such attribute identifies the unique object identifier of the element associated with it.

If both ID_META_ATTRIBUTE and ID _ATTRIBUTE are specified, then ID_ATTRIBUTE takes precedence over the ID_META_ATTRIBUTE. If neither ID_ATTRIBUTE nor ID_META_ATTRIBUTE is specified, an internal API is called to obtain the element’s unique object identifier. If an element is a Windchill type instance, then the API returns the Windchill type identifier of the object.

If either ID_ATTRIBUTE or ID_META_ATTRIBUTE is specified and fails to resolve an element’s unique object identifier, an internal API is used to obtain the unique object identifier.

MAX_CONCURRENT

Specifies the maximum number of selected tasks that the webject is allowed to execute concurrently. If this parameter is not specified and multiple tasks are selected, they are executed sequentially. The default for this parameter is 1. This parameter is optional.

PARAM

Specifies additional parameters to be passed to the tasks that are selected and executed. Each value of this parameter is specified as a name=value pair, where name is the name of the additional parameter to be passed to each selected task, and value is the value of the parameter.

If PARAM is not specified, no additional parameters are passed to the selected task. Multiple values may be specified for this parameter. This parameter is optional.

TASKS

Specifies either an LDAP URL or the name of a group.

If an LDAP URL is specified, then the URL identifies a directory server and the node within the associated directory that establishes the root of a tree of task definitions. Tasks are selected from the tree on the basis of action name (from the ACTION parameter), object type (obtained per object based on TYPE_ATTRIBUTE or TYPE_META_ATTRIBUTE), and object location (obtained from the domain component of the object identifier of each object based on ID_ATTRIBUTE or ID_META_ATTRIBUTE).

If a group name is specified, then the group represents a table of task definitions. Each element of the group specifies one task definition, and each such definition is assumed to contain attributes named the following:

◦ ACTION – Specifies the logical name of the action supported by this definition. This attribute is compared to the ACTION parameter of the webject. If they do not match, then the definition does not apply to this invocation of the webject.

◦ TYPE – Specifies the object type to which this definition applies. This attribute is compared to the object type obtained from each element of the input group. If they do not match, then the definition does not apply to the element. If the value of this attribute is “*”, the definition applies to all object types.

◦ DOMAIN – Specifies the fully qualified domain name to which this definition applies. This attribute is compared to the domain component obtained from the unique object identifier of each element of the input group. If they do not match, then the definition does not apply to the element. If the value of this attribute is “*”, the definition applies to all domains.

◦ TASK – Specifies the URL of the Info*Engine task that implements the action associated with this definition.

◦ PROCESSOR – Specifies the name of the Info*Engine task processor that is capable of executing the task identified by the TASK attribute. If this attribute is not specified in a task definition, the task implementation identified by the TASK attribute can be accessed and executed anywhere.

This parameter is required.

TYPE_ATTRIBUTE

Specifies the name of the attribute that every element of the input group contains and that specifies each respective element’s object type. For example, if the value of this parameter is CLASS, then it is assumed that every element of the input group contains an attribute named CLASS, and the value of each such attribute identifies the object type of the element containing it.

If both TYPE_ATTRIBUTE and TYPE_META_ATTRIBUTE are specified, then TYPE_ATTRIBUTE takes precedence over the TYPE_META_ATTRIBUTE. If neither TYPE_ATTRIBUTE nor TYPE_META_ATTRIBUTE is specified, then an internal API is called to obtain the type identifier. If the element is a Windchill type instance, this API returns the Windchill type identifier of the object.

If either TYPE_ATTRIBUTE or TYPE_META_ATTRIBUTE is specified and fail to resolve an element’s type identifier an internal API is used to obtain the type identifier.

TYPE_META_ATTRIBUTE

Specifies the name of the metadata item that every element of the input group contains and that specifies each respective element’s object type. For example, if the value of this parameter is com.infoengine.objectType, then it is assumed that every element of the input group has an associated metadata item named com.infoengine.objectType, and the value of each such metadata object identifies the object type of the element associated with it.

If both TYPE_META_ATTRIBUTE and TYPE _ATTRIBUTE are specified, then TYPE _ATTRIBUTE takes precedence over TYPE_META_ATTRIBUTE. If neither TYPE_ATTRIBUTE nor TYPE_META_ATTRIBUTE is specified, then an internal API is called to obtain the type identifier. If the element is a Windchill type instance, this API returns the Windchill type identifier of the object.

If either TYPE_ATTRIBUTE or TYPE_META_ATTRIBUTE is specified and fail to resolve an element’s type identifier an internal API is used to obtain the type identifier.

EXAMPLE

<%@page language="java" session="true" errorPage="IEError.jsp" import="java.util.
Vector,java.util.Enumeration,com.infoengine.SAK.*" %>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie" %>
<html>
<head>
<title>Dispatch Tasks</title>
</head>
<body bgcolor="#FFFFFF">
<ie:getService varName="ie"/>
<ie:webject name="Create-Group" type="GRP">
  <ie:param name="group_out" data="tasks"/>
  <ie:param name="delimiter" data=":"/>
  <ie:param name="element"
                 data="action=query:type=part:domain=s1.ptc.com:task=infoengine/
                                                     com/company/CreateGroup.xml"/>
  <ie:param name="element"
                 data="action=query:type=part:domain=s2.ptc.com:task=infoengine/
                                                   com/company/CreateGroupA.xml"/>
  <ie:param name="element"
                 data="action=query:type=part:domain=s3.ptc.com:task=infoengine/
                                                    com/company/JdbcQueryEmp.xml"/>
</ie:webject>
<ie:webject name="Create-Group" type="GRP">
  <ie:param name="group_out" data="parts"/>
  <ie:param name="delimiter" data=":"/>
  <ie:param name="element" data="ufid=part1@s1.ptc.com:class=part:number=1"/>
  <ie:param name="element" data="ufid=part2@s2.ptc.com:class=part:number=2"/>
  <ie:param name="element" data="ufid=part3@s3.ptc.com:class=part:number=3"/>
  <ie:param name="element" data="ufid=part4@s1.ptc.com:class=part:number=4"/>
  <ie:param name="element" data="ufid=part5@s2.ptc.com:class=part:number=5"/>
  <ie:param name="element" data="ufid=part6@s3.ptc.com:class=part:number=6"/>
  <ie:param name="element" data="ufid=part7@s1.ptc.com:class=part:number=7"/>
  <ie:param name="element" data="ufid=part8@s2.ptc.com:class=part:number=8"/>
  <ie:param name="element" data="ufid=part9@s3.ptc.com:class=part:number=9"/>
</ie:webject>
<% long start = System.currentTimeMillis (); %>
<ie:webject name="Dispatch-Tasks" type="MGT">
  <ie:param name="tasks" data="tasks"/>
  <ie:param name="group_in" data="parts"/>
  <ie:param name="max_concurrent" data="$(@FORM[]threads[])" default="10"/>
  <ie:param name="action" data="$(@FORM[]action[])" default="query"/>
  <ie:param name="type_attribute" data="class"/>
  <ie:param name="id_attribute" data="ufid"/>
  <ie:param name="param" data="group_out=results"/>
  <ie:param name="param" data="jdbcAdapter=$(@FORM[]jdbcAdapter[])"
default="jdbcAdapter"/>
</ie:webject>
<% long duration = System.currentTimeMillis () - start; %>
<h2>Execution time: <%= duration %> msec</h2><br>
<ie:webject name="Display-Object" type="DSP">
  <ie:param name="group_in" data="results"/>
  <ie:param name="border" data="1"/>
  <ie:param name="display_attribute_name" data="true"/>
</ie:webject>
</body>
</html>

Generate-WSDL

DESCRIPTION

Generates Web Service Definition Language (WSDL) from specified Info*Engine tasks for use by SOAP clients. WSDL is an XML-based language used to define client/server interfaces.

For the Info*Engine SOAP service to perform in a predictable manner, you must bind to the service using the HTTP URL specified in the SOAP port exposed in the generated WSDL, since it contains additional query parameters to pass to the underlying SOAP service.

The generated WSDL contains SOAP information specific to the SOAP RPC servlet that allows it to properly route requests. The generated WSDL contains a single service named IESoapServlet bound to a port named IESoapPort, and describes all methods and method signatures supported for the class specified in the CLASS parameter. For more information on SOAP, see Simple Object Access Protocol (SOAP) Web Service.

The tasks from which WSDL is generated must be prefaced with special comment lines that define their parameters and results (similar to Javadoc comment syntax). The webject parses all of the tasks found at the specified location and uses the special comment lines within them to generate WSDL. Depending on which webject parameters are specified, the WSDL can be written back as a BLOB or added to the VDB as a group.

SYNTAX

<ie:webject name="Generate-WSDL" type="MGT">
  <ie:param name="CLASS" data="class_name"/>
  <ie:param name="GROUP_OUT" data="output_group_name"/>
  <ie:param name="REPOSITORY" data="repository"/>
  <ie:param name="REPOSITORY_TYPE" data="repository_type"/>
  <ie:param name="SOAP_URI" data="uri"/>
  <ie:param name="STYLE" data="rpc"/>
  <ie:param name="TASKS" data="task_location"/>
  <ie:param name="VERSION" data="1.0"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
CLASS	GROUP_OUT	REPOSITORY
	SOAP_URI	REPOSITORY_TYPE
		STYLE
		TASKS
		VERSION

CLASS

Specifies the Java class with which the WSDL methods are associated. The value specified must correspond to an existing type identifier definition found in the supporting LDAP directory. The REPOSITORY or REPOSITORY_TYPE parameters can be used to direct the webject to the correct location within LDAP to discover the type identifier. This parameter is required.

GROUP_OUT

Specifies the name of the output group to create. If GROUP_OUT is specified, then the output is added to the VDB as a group with the specified name. The group contains one element for each command delegate exposed by the type identifier corresponding to the CLASS parameter. Each group element contains one attribute per task parameter. The parameter name becomes the attribute name. The parameter type become the attribute value. Method name and task are stored as metadata on each element with the identifiers com.infoengine.soap.wsdl.methodName and com.infoengine.soap.wsdl.task respectively. If comments are specified on either the entire task or individual parameters the comments are stored as metadata with the identifier com.infoengine.soap.wsdl.comment. Task comments are stored as metadata on the corresponding element. Parameter comments are stored as metadata on the corresponding attribute. If GROUP_OUT is not specified, then SOAP_URI must be specified.

REPOSITORY

Specifies the name of the repository whose repository type contains the required type identifier and task delegate definitions. For example, host.myCompany.com, which represents an installed instance of Info*Engine with a repository type of com.ptc.windchill. If this parameter is not specified the repository type is generated based on the virtual machine name of the running JVM. For example, a virtual machine name of com.myCompany.host.server results in a repository of host.myCompany.com. This parameter is optional.

REPOSITORY_TYPE

Specifies the name of the repository type that contains the required type identifier and task delegate definitions. For example, com.ptc.windchill. If this parameter is not specified, then the behavior described with the REPOSITORY parameter is carried out to attempt to dynamically discover the appropriate repository type. This parameter is optional.

SOAP_URI

Identifies the URI of the SOAP service used to route requests. Only fully-qualified URIs should be specified for this parameter. For example:

http://localhost/Windchill/servlet/RPC

where RPC is an instance of com.infoengine.soap.SoapRPCRouter. If this parameter is specified, the WSDL is generated and returned to the client as a BLOB. If GROUP_OUT is not specified, SOAP_URI must be specified.

STYLE

Acceptable values are rpc or document. This parameter governs how the generated WSDL represents Info*Engine SOAP services, and how those services behave when it comes to processing requests and generating responses. If the value is rpc, the generated WSDL is Remote Procedure Call (rpc)-style SOAP. If the value is document, the generated WSDL is document-style SOAP. The default value is rpc. This parameter is only processed if the VERSION parameter is set to 1.1. This parameter is optional.

Since the defaults for VERSION and STYLE are 1.0 and rpc respectively, this means that by default Info*Engine SOAP services are rpc-encoded SOAP services. If you want Info*Engine SOAP to behave rpc-literal, you must specify rpc and 1.1 for STYLE and VERSION respectively. If you want Info*Engine SOAP to behave document-literal, specify document and 1.1 respectively.

TASKS

Specifies the location, relative to the configured task root, of the tasks to be externalized to the SOAP client using WSDL. This parameter is optional.

VERSION

Acceptable values are 1.0 or 1.1. This parameter governs whether the generated WSDL is SOAP encoded or literal. The default value is 1.0, which results in encoded SOAP. This parameter is select with the STYLE parameter. The STYLE parameter is only processed if VERSION is 1.1. This parameter is optional.

Since the defaults for VERSION and STYLE are 1.0 and rpc respectively, this means that by default Info*Engine SOAP services are rpc-encoded SOAP services. If you want Info*Engine SOAP to behave rpc-literal, specify rpc and 1.1 for STYLE and VERSION respectively. If you want Info*Engine SOAP to behave document-literal, specify document and 1.1 respectively.

EXAMPLE

The following Generate-WSDL example generates WSDL from Info*Engine tasks. The REPOSITORY parameter is generated based on the running virtual machine name (as described in the REPOSITORY parameter description). The WSDL methods are associated with the Java class named com.infoengine.soap. The request is routed through the SOAP service specified in SOAP_URI, and the generated WSDL is returned to the client as a BLOB.

<ie:webject name="Generate-WSDL" type="MGT">
<ie:param name="CLASS" data="com.infoengine.soap"/>
<ie:param name="SOAP_URI"
data="http://host/Windchill/servlet/RPC"/>
</ie:webject>

Get-Properties

DESCRIPTION

Creates a group from a Java property resource.

SYNTAX

<ie:webject name="Get-Properties" type="MGT">
  <ie:param name="ATTRIBUTE" data="name"/>
  <ie:param name="GROUP_OUT" data="group_name"/>
  <ie:param name="SOURCE" data="uri_or_file_pathname"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
		ATTRIBUTE
		GROUP_OUT
		SOURCE

ATTRIBUTE

Specifies the names of the properties to fetch and place in the output group. If ATTRIBUTE is not specified, all of the properties from the specified SOURCE are placed in the output group. This parameter is optional.

GROUP_OUT

Specifies the name of the group to create that contains the queue identifiers of the objects in the message queue.

The GROUP_OUT contains exactly one element. Each attribute of the element represents one property name/value pair obtained from the property source. The name of the attribute is the same as the name of the corresponding property, and the value of the attribute is the same as the value of the property.

This parameter is optional.

SOURCE

Specifies the location of the properties that are returned by the Get-Properties webject. It may be specified as a relative or absolute URI:

◦ Relative URIs reference files that reside under the root file system directory that is defined for the local Info*Engine task processor

◦ Absolute URIs reference files that reside in the local file system, reside on a remote HTTP server, or are referenced through an accessible LDAP directory.

It may also be specified as a system filepath referencing a properties file such as wt.properties. The default for this optional parameter is to return the properties defined by the java.lang.System class in the GROUP_OUT.

EXAMPLE

The following Get-Properties example JSP page gets properties from a predetermined source and returns those properties in a group that you have named:

<%@page language="java" session="false"
                                errorPage="../IEError.jsp"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
                                               prefix="ie"%>

<html>
<head><title>Get Properties</title></head>
<body>

<ie:webject name="Get-Properties" type="MGT">
  <ie:param name="SOURCE" data="$(@FORM[]source[0])"
                                                default=""/>
  <ie:param name="GROUP_OUT" data="$(@FORM[]group_out[0])"
                                                default=""/>
</ie:webject>

<ie:webject name="DISPLAY-TABLE" type="DSP"/>
</body>
</html>

To actually run this example, you would need to provide a form where the source and group_out variables are identified.

Get-Resource

DESCRIPTION

Creates an Info*Engine group from the localized strings in a Java resource bundle. The language of the strings in the created group is determined by the language setting of a client’s web browser.

The Get-Resource webject is used in conjunction with the Display-Resource webject to support insertion of localized text into web pages.

SYNTAX

<ie:webject name="Get-Resource" type="MGT">
<ie:param name="BUNDLE" data="resource_bundle"/>
<ie:param name="GROUP_OUT" data="group_name"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
BUNDLE		GROUP_OUT

BUNDLE

Identifies the Java class base resource bundle from which localized strings are to be retrieved. This parameter is required.

GROUP_OUT

Specifies the name of an Info*Engine group in which to store retrieved localized strings. The default for this parameter is bundle. This parameter is optional.

EXAMPLE

The following Get-Resource example JSP page creates a group using localized strings from the specified resource bundle:

<%@page language="java"
  session="false"
  errorPage="../IEError.jsp"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
                                              prefix="ie" %>

<html>
<head><title>Get Properties</title></head>
<body>

<ie:webject name="Get-Resource" type="MGT">
  <ie:param name="BUNDLE"
                     data="com.infoengine.util.IEResource"/>
</ie:webject>

<ie:webject name="Display-Table" type="DSP">
  <ie:param name="ATTRIBUTE" data="$(@FORM[]key[0])"
                                    default="20" delim=","/>
</ie:webject>

</body>
</html>

The key variable can be specified in a form, or the specified default value is used.

List-Repositories

DESCRIPTION

Lists Info*Engine repository entries. The output group contains one element per repository whose contents are the LDAP attributes for that repository. In addition, each element contains a dn attribute containing the distinguished name of the repository entry, and a domain attribute containing the domain name associated with the repository that can be used for task delegation.

SYNTAX

<ie:webject name="List-Repositories" type="MGT">
<ie:param name="FILTER" data="ptcRepositoryType=com.ptc.windchill" />
<ie:param name="FILTER_MODE" data="[MATCH | NOMATCH]" />
<ie:param name="GROUP_OUT" data="repositories" />
</ie:webject>

PARAMETERS

Required	Select	Optional
		FILTER
		FILTER_MODE
		GROUP_OUT

FILTER

Specifies the filter used to return a subset of the existing repositories. The format of the filter is <attribute>=<regular expression> where <attribute> is an LDAP attribute (such as ptcRepositoryType or ptcSupportingAdapter), and <regular expression> is a regular expression to match attribute values against. This parameter is optional. The default value for this parameter is ptcRepositoryType=.* which matches all repositories with a ptcRepository attribute set.

FILTER_MODE

Specifies whether the filter should match or not match. Specifying a value of MATCH means that if the repository entry matches the expression that had been specified by the filter, that expression are added to the output group. This parameter is optional. The default value for this parameter is MATCH.

GROUP_OUT

Specifies the name of the output group to create. This parameter is optional. The default value for this parameter is repositories.

Lookup-Services

DESCRIPTION

This webject performs directory searches to find Info*Engine services. The resulting group contains one element per service found. Each element may contain the following attributes:

• dn

• description

• ptcRuntimeServiceName

• ptcServiceName

• ptcServiceClassName

• ptcMetaType

• ptcServiceAddress

• ptcObjectSerializationType

• ptcCoresidentService

(The contents of the ptcApplicationServiceobjectClass plus distinguished name)

Since the ptcApplicationServiceobjectClass only requires ptcServiceName, dn and ptcServiceName are found in all elements, and the presence of the others is dependent on configuration of each specific service.

The defaults values are:

CLASS - none

FILTER - (objectclass=ptcApplicationService) (all available service entries)

GROUP_OUT -SERVICES

SYNTAX

<ie:webject name="Lookup-Services" type="MGT">
<ie:param name="GROUP_OUT" data="group name"/>
<ie:param name="FILTER" data="LDAP search filter"/>
<ie:param name="CLASS" data="class name"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
		CLASS
		FILTER
		GROUP_OUT

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, the XML representation of the output group contains the following tags:

The default for this parameter is “Unknown-Class-Name.” This parameter is optional.

FILTER

This parameter allows the user to specify an LDAP search filter such as (ptcServiceName=com.company.host.server). The default value is (objectclass=ptcApplicationService), which returns all services within the Naming Service’s search base (the search is always performed within the VMs Naming Service search base).

GROUP_OUT

This parameter allows the user to specify the name of the output group. The default value is SERVICES. The output group only contains services (LDAP directory entries who specify ptcApplicationService as an objectClass). The output group contains one element per service found. Each element contains at a minimum the dn and ptcServiceName attributes. Each element may also contain the following attributes if they have values set in the corresponding service: ptcRuntimeServiceName, ptcServiceClassName, ptcMetaType, ptcServiceAddress, description, ptcCoresidentService, ptcObjectSerializationType. The following attributes may be multivalued if specified: ptcServiceName, ptcServiceAddress, ptcCoresidentService.

Map-Credentials

DESCRIPTION

Reads a file or executes a task to establish a group as the credentials map for the task in which the webject executes (or does both). A credentials map is a Auth-Map context group that provides authentication information used by adapters in establishing connections to back-end information systems. Each element of a credentials map provides a username and associated credentials that are used in connecting to a specific back-end system.

The webject can be specified explicitly at any point in a task to create or change the credentials map that affects the remainder of the webjects in the task. If the .credentialsMapper configuration property is set, Map-Credentials is also called implicitly at the beginning of every task to create the initial credentials map for the task. If a default credentials mapping task has not been configured, Map-Credentials webject is not called implicitly.

For additional information about credentials mapping, see Credentials Mapping.

SYNTAX

<ie:webject name="Map-Credentials" type="MGT">
  <ie:param name="FILES" data="dir_path"/>
  <ie:param name="TASK" data="uri"/>
  <ie:param name="USERNAME" data="user_name"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
	FILES	USERNAME
	TASK

FILES

Specifies the system filepath directory in which each file is assumed to contain credentials mapping information for a specific user. The USERNAME parameter is concatenated to the FILES parameter to produce the path name of one such file. The resulting file name is formatted as follows:

FILES_parameter_value/USERNAME_parameter_value

The file is then read and parsed to produce a credentials map. Each line of the file is assumed to be of the form:

instance:dbuser:passwd

where:

◦ instance specifies the name of an Info*Engine adapter or the instance names used with the WES or MSG webjects.

◦ dbuser specifies the username.

◦ passwd specifies the credentials that are provided to the adapter for creating connections to the associated back-end information system.

If both FILES and TASK are specified, file-based mapping is performed first, then the credentials mapping task is executed. This allows some base or default mapping information to be specified using files, then augmented or overridden by the task.

If the FILES parameter is omitted, file-based mapping is not performed. In this case, the credentials map is derived only from the output of the task specified by the TASK parameter. The FILES parameter must be specified if the TASK parameter is omitted.

TASK

Specifies the URI of an Info*Engine task that produces an Auth-Map group that is used as a credentials map. For example, the credential mapping task could do one of the following:

◦ Allow a user to explicitly authenticate to Info*Engine once, and then Info*Engine automatically authenticates the user to other enterprise information systems.

◦ Enable role-based access to network resources by identifying the role played by a particular user, and then creating the output group containing the authentication information shared by users who play the same role.

The last group produced by a webject in this task becomes the credentials map. If the TASK parameter is not specified, a credentials mapping task is not executed. In this case the credentials map is derived only from the FILES parameter. The TASK parameter must be specified if the FILES parameter is omitted.

USERNAME

Identifies the name of the user for which a credentials map is being created. If no username is supplied, it is assumed that the credentials mapping task takes appropriate action to reject anonymous access (for example, by throwing an exception), or provides a default credentials map for anonymous access.

The default for this parameter is for the webject to obtain a username from the attribute named auth-user of the SERVER context group. This parameter is optional.

Query-Schema

DESCRIPTION

Retrieves schema information about object types either from the LDAP directory or another repository.

SYNTAX

<ie:webject name="Query-Schema" type="MGT">
<ie:param name="TYPE" data=" com.myCompany.Address"/>
<ie:param name="SCHEMA_GENERATOR" data="<generatorClass>"/>
<ie:param name="GROUP_OUT" data="Attributes"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
TYPE		GROUP_OUT
		SCHEMA_GENERATOR

TYPE

Defines the type for which schema should be generated.

GROUP_OUT

Defines the name of the output group to be generated. There is no default value. If not supplied no GROUP_OUT is generated and an instance of the generated SchemaObject bean is stored on the collection as the SOAP response.

SHEMA_GENERATOR

Defines the fully qualified name of a Java class that implements the com.infoengine.schema.SchemaGenerator interface. The implementing class is required to know how to navigate a type hierarchy to generate the requested SchemaObject. This parameter defaults to an implementation that knows how to generate SchemaObject instances based on information found in the LDAP directory.

Additional parameters may be specified/required based on the value of SCHEMA_GENERATOR. For example the LDAP SCHEMA_GENERATOR may require (or allow) parameters like REPOSITORY or REPOSITORY_TYPE to tell it where in the directory to look for schema information.

Query-TypeHierarchy

Description

Allows retrieval of information about existing type hierarchies. The Info*Engine group created contains information for each type found within a type hierarchy and a list of its ancestor or descendant types (depending on the direction of the traversal). The output group can be formatted as either a flat list of types, or as a nested group that reflects the structure of the type hierarchy.

SYNTAX

<ie:webject name="Query-TypeHierarchy" type="MGT">
  <ie:param name="RESOLVER" data="typeGraph"/>
  <ie:param name="TYPE" data="typeName"/>
  <ie:param name="DIRECTION"
            data="ANCESTORS | DESCENDANTS | BOTH"/>
  <ie:param name="MODE" data="NESTED | FLAT"/>
  <ie:param name="GROUP_OUT" data="groupName"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
TYPE		DIRECTION
		GROUP_OUT
		MODE
		RESOLVER

DIRECTION

Specifies the direction of traversal. Acceptable values are ANCESTORS, DESCENDANTS, and BOTH. The default value is BOTH. This parameter is optional.

GROUP_OUT

Specifies the name of the Info*Engine group in which to store the type hierarchy information.

The contents and format of the group depend on the values of TYPE, DIRECTION, and MODE.

◦ If MODE is specified with a value of FLAT, the output group contains one element per type; each element contains two attributes type and ancestors.

◦ If MODE is specified with a value of NESTED, the output group contains a single top-level element containing two attributes: type, and either ancestors or descendants.

Whether ancestors or descendants is used depends on the value specified for DIRECTION. If DIRECTION is specified with a value of ANCESTORS, the ancestors attribute is included, otherwise descendants is used. The value of the ancestors or descendants attribute is an Info*Engine element representing the next type in the hierarchy, and in turn its ancestors or descendants.

If a type hierarchy supports additional information per type in the hierarchy, additional attributes may be included in each element of the output group. For example, the Windchill implementation tells whether a particular type in the hierarchy is modeled or soft by including an attribute named definition whose value can be one of the following: interface, class, or soft.

The default value for this parameter is hierarchy. This parameter is optional.

MODE

Specifies how the output group is formatted. Acceptable values are: FLAT or NESTED. The default value is FLAT.

RESOLVER

Specifies the name of the type hierarchy implementation in which TYPE can be found. Currently there are two acceptable values for this parameter:

◦ com.infoengine.schema.type.LDAPTypeHierarchyGraph — Allows traversal of type hierarchies stored in LDAP.

◦ com.ptc.core.adapter.server.impl.WindchillTypeHierarchyGraph — Allows traversal of Windchill type hierarchies (requires Windchill be installed).

The default value is com.infoengine.schema.type.LDAPTypeHierarchyGraph. This parameter is optional.

TYPE

Specifies the name of the type at which to begin traversing the type hierarchy. This is a required parameter.

Throw-Exception

DESCRIPTION

Causes an exception to be thrown. If the webject is called from within the body of a unit within a task, control is transferred to a failure block, if the block exists. If the webject is called from outside of a unit, the task exits.

Info*Engine arranges for the names and messages of exceptions thrown during task execution to be registered automatically in the SERVER context group attributes named exception-class and exception-message. This makes it possible for failure blocks within units to process exceptions and then re-throw them by calling the Throw-Exception webject without passing on any parameters. The SERVER context attribute named exception-object unwraps nested exceptions and creates the registers the raw, unwrapped exception object. The Throw-Exception webject looks for this SERVER context attribute and, if present, throw the associated exception object directly.

SYNTAX

<ie:webject name="Throw-Exception" type="MGT">
  <ie:param name="BUNDLE" data="bundle_name"/>
  <ie:param name="CLASS" data="exception_class_name"/>
  <ie:param name="GROUP_IN" data="input_group"/>
  <ie:param name="KEY" data="resource_key"/>
  <ie:param name="MESSAGE" data="text_message"/>
  <ie:param name="PARAM" data="resource_param"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
	BUNDLE	CLASS
	GROUP_IN
	KEY
	MESSAGE
	PARAM

BUNDLE

Identifies the class name of a Java resource bundle containing localized message templates to be associated with the exception.

To use the KEY and PARAM parameters, you must also specify either BUNDLE or GROUP_IN.

CLASS

Specifies the Java class name of the exception to be thrown. If CLASS is omitted, the webject obtains the class name from the SERVER context group attribute named exception-class. If the attribute does not exist, the class name defaults to com.infoengine.util.IEException. This parameter is optional.

GROUP_IN

Identifies a group containing localized resource definitions, such as the group produced by the Get-Resource webject. If both BUNDLE and GROUP_IN are specified, BUNDLE takes precedence, and GROUP_IN is ignored.

To use the KEY and PARAM parameters, you must also specify either BUNDLE or GROUP_IN.

KEY

Selects a localized message template from the bundle or group. The KEY value may be specified as a number or a Java variable reference name.

This parameter is used only when you also specify either the BUNDLE or GROUP_IN parameter.

MESSAGE

The MESSAGE parameter specifies the textual message to be associated with the exception. Use this parameter only when it is not necessary to generate localizable messages in exceptions. If this parameter is omitted and the BUNDLE and GROUP_IN parameters are also omitted, the webject obtains message text from the SERVER context group attribute named exception-message. If BUNDLE or GROUP_IN are specified in addition to MESSAGE, the MESSAGE parameter takes precedence while BUNDLE and GROUP_IN are ignored.

PARAM

Supplies one or more values that are substituted into the localized message template to produce the final message text. If PARAM is not specified, it is assumed that the message template identified by the BUNDLE or GROUP_IN and the KEY parameters does not contain any substitution keywords, thus no substitution is performed.

This parameter is used only when you also specify either the BUNDLE or GROUP_IN parameter.

EXAMPLE

The following Throw-Exception example JSP page throws an exception using the localized message identified by KEY number 19 in the specified resource bundle:

<%@page language="java"
  session="false"
  errorPage="../IEError.jsp"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core"
                                              prefix="ie" %>

html>
<head><title>Throw Exception</title></head>
<body>

ie:webject name="Throw-Exception" type="MGT">
  <ie:param name="BUNDLE"
                     data="com.infoengine.util.IEResource"/>
  <ie:param name="KEY" data="19"/>
</ie:webject>

/body>
</html>

Write-Log

DESCRIPTION

Writes a message to the log associated with the context in which it is executed. For example, if the webject is called from a task executed within the Info*Engine task processor, the message is written to the task processor log. If the webject is called from a JSP page, it is written to the JSP processor log.

When writing Info*Engine tasks, it is preferable to make use of the Logging tag library to issue log statements to log4j.

SYNTAX

<ie:webject name="Write-Log" type="MGT">
  <ie:param name="GROUP_IN" data="input_group"/>
  <ie:param name="LOG" data="[DEBUG | INFO | ERROR | AUDIT |
                                         TRANSACTION | STAT]"/>
  <ie:param name="MESSAGE" data="message_text"/>
  <ie:param name="TAG" data="author_supplied_tag"/>
</ie:webject>

PARAMETERS

Required	Select	Optional
		GROUP_IN
		LOG
		MESSAGE
		TAG

GROUP_IN

Specifies the name of the input group to log. The input group is rendered as XML and written to the log file specified by the LOG parameter. Multiple values can be specified. Any input groups are logged after the values supplied on the MESSAGE parameter.

LOG

Specifies the log to which the message should be written. Valid values for this parameter are DEBUG, INFO, ERROR, AUDIT, TRANSACTION, and STAT. The default for this parameter is INFO. This parameter is optional.

MESSAGE

Provides the main text of the message to be written to the log.

The format of each log message written is:

date-time#:#host#:#service#:#tag#:#user#:#messagevalue

where:

date-time—The date and time at which the message is written.

host—The Internet domain name of the host from which the message is written.

service—The name of the Info*Engine service that wrote the message.

tag—The value specified by the TAG parameter.

user—The authenticated username of the user for which the service was working when the message is written.

messagevalue—The value specified by the MESSAGE parameter.

The default is for a log message to be written that has an empty message value. This parameter is optional.

TAG

Specifies a tag that is written as part of the log entry for the purpose of facilitating the searching and sorting of logs. The TAG parameter allows a task author to provide a simple identifier that can be used to distinguish one kind of log message from another. For example, you can use special tags for troubleshooting purposes, or to classify messages in site-defined ways.

The default for this parameter is to use the name of the task from which the webject is being called. This parameter is optional.

EXAMPLE

The following Write-Log example JSP page creates a group, writes messages to two different logs, and displays the output:

<%@page language="java"
  session="false"
  errorPage="../IEError.jsp"%>
<%@ taglib uri="http://www.ptc.com/infoengine/taglib/core" prefix="ie" %>

<html>
<head>
<title>Write-Log Webject</title>
</head>
<body>


<ie:task uri="com/company/CreateGroup.xml"/>



<ie:webject name="Write-Log" type="MGT">
  <ie:param name="TAG" data="-----Write-Log-----"/>
  <ie:param name="MESSAGE" data="----Info log message----"/>
</ie:webject>


<ie:webject name="Write-Log" type="MGT">
  <ie:param name="TAG" data="-----Write-Log-----"/>
  <ie:param name="MESSAGE"
                          data="----Debug log message----"/>
<ie:param name="LOG" data="DEBUG"/>
</ie:webject>


<ie:webject name="Display-Table" type="DSP"/>

</body>
</html>