Naming the Adapter in INSTANCE Parameters
The INSTANCE parameter specifies the name of the adapter that executes the webject. Adapter names are defined when the adapter is configured for use in your Windchill environment. This parameter is required.
In order to provide the ability to connect to other adapters if a specific adapter is not available, this parameter can be multi-valued. Info*Engine attempts to connect to the adapters in the order given. If the first adapter specified is not available, the next adapter listed is tried, and so on, until a connection is made. If a connection cannot be established with any listed adapter, an error is returned.
In conjunction with this parameter, you can include two other parameters that enable fail-over and load balancing: CONNECTION_ATTEMPTS and CONNECTION_ATTEMPT_INTERVAL.
CONNECTION_ATTEMPTS
Defines the maximum number of times to attempt establishing a connection to an adapter before returning an error. The default value is 1. This parameter is optional.
If multiple INSTANCE parameter values are specified, the value of CONNECTION_ATTEMPTS defines the maximum number of times to iterate through the list of adapter instances.
CONNECTION_ATTEMPT_INTERVAL
Defines the amount of time, in seconds, to delay between connection attempts. The default value is 60 seconds. This parameter is optional.
If multiple INSTANCE parameter values are specified, the value of CONNECTION_ATTEMPT_INTERVAL defines the number of seconds to wait between the attempts to iterate through the entire list of adapter instances.
Manually Configuring the Adapter Name
You define the adapter name to use in the INSTANCE parameter when you configure the adapter through the Info*Engine Property Administration utility.
An adapter name can be one of the following forms:
• A simple name.
This is defined in the Service Name field on the Info*Engine Property Administration LDAP form.
Simple names are stored in the ptcServiceName attribute of the adapter LDAP entry. To use a simple name, the adapter LDAP entry must reside within the Naming Service search path.
For example, assume that “com.myCompany.myHost.windchill” is the ptcServiceName attribute of the adapter LDAP entry in the Naming Service search path. Then, the following INSTANCE parameter can be used:
<ie:param name="INSTANCE" data="com.myCompany.myHost.windchill"/>
• A fully qualified distinguished name.
When configuring the adapter, you specify the distinguished name in the Info*Engine Property Administration form. This name consists of the ptcServiceName attribute and the other attributes that define the location of the LDAP entry.
For example, assume that the “com.myCompany.myHost.windchill” entry is located on “host1” at “dc=IeProps,dc=myHost,dc=myCompany, dc=com,ou=Applications,o=myCompany.” Then, the following INSTANCE parameter can be used:
<ie:param name="INSTANCE" data="ldap://host1/
ptcServiceName=com.myCompany.myHost.windchill,
dc=IeProps,dc=myHost,dc=myCompany,dc=com,
ou=Applications,o=myCompany"/>
ptcServiceName=com.myCompany.myHost.windchill,
dc=IeProps,dc=myHost,dc=myCompany,dc=com,
ou=Applications,o=myCompany"/>
• A domain-based reference name.
This is just another way of identifying the distinguished name. An Info*Engine domain-based reference name uses the following format:
ptcServiceName@dc_attributes
◦ ptcServiceName is the value of the ptcServiceName attribute.
◦ dc_attributes are the dc attributes that make up the domain location of the LDAP entry. Each attribute is separated from the next attribute using a period.
You can only use a domain-based reference name in the following situations:
◦ When constructing the LDAP directory in which the Info*Engine entries are located, you use dc=com as a root-level entry and other dc attributes for subtree entries
◦ The Naming Service .serviceDomainBase property is set to include those attributes beyond the domain that are used in the distinguished name of the entry.
For example, assume that the ptcServiceName attribute value is “com.myCompany.myHost.windchill” and that the entry is located in the “dc=myHost,dc=myCompany,dc=com,ou=Applications, o=myCompany” branch, then the following domain-based reference name could only be used in the INSTANCE parameter if the .serviceDomainBase property is set to “ou=Applications,o=myCompany”:
<ie:param name="INSTANCE" data="com.myCompany.myHost.
windchill@myHost.myCompany.com"/>
windchill@myHost.myCompany.com"/>
Use the Info*Engine Property Administration utility to set the .serviceDomainBase property.
Programmatically Discovering the Adapter Name
 |
The previous examples show how you could hard code an INSTANCE parameter name for your Windchill adapter. This is not a desirable option when authoring tasks since it means that they cannot be reused on other installations without being manually modified.
It is best to discover the name of your Windchill adapter using the system configuration.
|
If your task is being authored for use with a JCA client, then you should use the supporting-adapter input parameter to discover which adapters the system has been configured with.
Not doing so negates the system configuration. In this case your instance parameter should look like the following example:
<ie:param name="INSTANCE" data="$(@FORM[]supporting-adapter[*])"
valueSeparator=";" delim=";"/>
valueSeparator=";" delim=";"/>
When the task is invoked from a JCA client, the supporting-adapter input parameter is supplied by your system based on how it is configured. In general this is the most common way you should specify INSTANCE parameters for your Windchill adapter webjects.
If your task is not intended for use with a JCA client, then a common thing to do is to use the Get-Properties MGT webject to fetch the wt.federation.ie.VMName property and use that as input to your instance parameters.
<ie:webject name="Get-Properties" type="MGT">
<ie:param name="ATTRIBUTE" data="wt.federation.ie.VMName" />
<ie:param name="GROUP_OUT" data="properties" />
</ie:webject>
...
<ie:param name="INSTANCE"
data="$(properties[0]wt.federation.ie.VMName[0])" />
<ie:param name="ATTRIBUTE" data="wt.federation.ie.VMName" />
<ie:param name="GROUP_OUT" data="properties" />
</ie:webject>
...
<ie:param name="INSTANCE"
data="$(properties[0]wt.federation.ie.VMName[0])" />
You can also programmatically provide the value for your INSTANCE parameter by fetching it from Info*Engine either from the VMName or using the system properties object when running in the servlet.
For example:
<%
String vmName = com.infoengine.au.NamingService.getVMName();
// if running in the servlet engine vmName points to the servlet's
// name and not the adapter's name
// the servlet will be configured with its server name pointing to
// the adapter
vmName = System.getProperty ( vmName + ".ieServerName", vmName );
// now VMName should point to the current Windchill adapter
// regardless of whether the task is being runn in the server or
// servlet engine
%>
...
<ie:param name="INSTANCE" data="$(@FORM[]supporting-adapter[*])"
valueSeparator=";" delim=";" default="<%=vmName%>" />
String vmName = com.infoengine.au.NamingService.getVMName();
// if running in the servlet engine vmName points to the servlet's
// name and not the adapter's name
// the servlet will be configured with its server name pointing to
// the adapter
vmName = System.getProperty ( vmName + ".ieServerName", vmName );
// now VMName should point to the current Windchill adapter
// regardless of whether the task is being runn in the server or
// servlet engine
%>
...
<ie:param name="INSTANCE" data="$(@FORM[]supporting-adapter[*])"
valueSeparator=";" delim=";" default="<%=vmName%>" />