Classes
These are the classes that support the ESI response generation functionality:
ESIResponseGenerator
This class implements the interface java.lang.Runnable. Its run() method has all the necessary logic to create the required number of ESITransaction objects for the given release, link the various objects as appropriate, generate the ESI response messages and deliver them to an appropriate destination. The class is part of the com.ptc.windchill.esi.txn package.
When the user releases an object from Windchill PDMLink, the RTM workflow that gets launched performs pre-release validation and then invokes the release() method of StandardESIService. This method creates an instance of wt.session.SessionThread that wraps around an ESIResponseGenerator instance. One of the attributes on ESIResponseGenerator is a handle to the ESIRelease object – this is either a newly created object (when releasing the object for the first time), or one that is already associated to the primary business object in the release (when resubmitting an "ESI failure"). The release method then starts the newly created thread and returns the ESIRelease object to the workflow. The suspended workflow then waits for the "ESI Release Complete" event that gets dispatched from the postEvent() API of ESIReleaseUtility.
 |
By default, the RTM workflow listens for ESI release complete events associated to ESIRelease objects. See the ESIResultEvent and ESIRelease sections for more information.
|
The run() method that is executed in the newly started thread does all the useful work, like creating the ESITransaction objects, associating them to other objects as appropriate, generating the ESI response for every destination in the release and sending it to an appropriate destination. When it gets known that a certain transaction in the release has failed, or that all the transactions in the release have been completed successfully, the postEvent() API is invoked. This API emits the "ESI Release Complete" event, thereby causing the suspended RTM workflow to proceed ahead and terminate normally, and marking the end of the release.
The class is intended to be extended by customizers. An extension is particularly useful when a new type of object is to be published.
Points to keep in mind while creating a custom extension of ESIResponseGenerator that caters to a new type of object are as follows:
1. The release(obj : Persistable, userName : String, locale : Locale) API ofStandardESIService obtains the name of the ESI response generator class from the Windchill ESI preference ESI Response Generator (this appears under > in the Preference Management utility). Thus, if an extension of class ESIResponseGenerator is to be used for generating the ESI response, the preference should be set to the fully qualified name of the extension.
2. The extension should provide overridden versions of the following methods at a minimum – setType(), generateResponse(). A getXXX() method should be created as well, for rendering the new type of object.
3. The overridden version of setType() would ensure that the instance variable type is set to an appropriate value for the new type.
4. The overridden version of generateResponse() would invoke the getXXX() API thatwas created for rendering the new type.
5. The getXXX() API would simply invoke an identically named method on StandardESIService, which in turn would invoke the getXXX() API on the renderer instance that is appropriate for the new type.
|
|
The overridden versions of setType() and generateResponse() should retain the existing behavior for objects that are supported out-of-the-box. Also, the steps outlined above merely provide an overview of how an extension of class ESIResponseGenerator may be created. Besides following these, a customizer would need to worry about several other aspects like implementing a new renderer, associating distribution targets, adding the relevant response settings (and other attributes as may be appropriate) to the distribution target, customizing the business logic in the middleware for the new type of object etc.
|
ESIResponseSender
It implements the interface java.lang.Runnable, and is part of the com.ptc.windchill.esi.txn package. Upon generating the ESI response message for the distribution targets that represent a given destination, the run() method of ESIResponseGenerator creates an instance of this class, wraps it in a new wt.session.SessionThread instance and starts the thread. The run() method that executes in the newly started thread performs all the useful work, like fetching the value of the taskURI attribute on the distribution target being processed, creating a new com.infoengine.SAK.Task instance using the fetched URI, setting the task’s VDB to the response IeCollection, setting the task parameters as appropriate and finally invoking the task. The class is not meant to be extended by customizers. However, the taskURI attribute on a distribution target may be set to point to a customized version of the Info*Engine task that delivers the response message to the required destination. The attribute is set to the URI of the task in <Windchill>/tasks/com/ptc/windchill/esi/ExportTo<XXX>.xml by default, where <XXX>is either File, FTP or SMTP, according as the destination is a file, FTP or an Email type target respectively.
|
|
The run() method of ESIResponseGenerator proceeds to generate the response message for the distribution targets in the destination that occurs next in the list, soon after starting an ESIResponseSender thread (for the distribution targets in the currently processed destination) as described above.
|
The following classes support the CN auto-generation feature:
ESIECNFactory
This interface defines the methods that CN factory classes must implement. CN factories auto- generate a Windchill change order when change processing is not being used in the Windchill environment, but change processing is required by the target enterprise system.
createChangeOrder(item : Changeable2) : WTChangeOrder2
Wraps the given changeable in a change order.
ESIStandardECNFactory
This class is the default implementation of ESIECNFactory. It auto-generates a Windchill change order when change processing is not being used in the Windchill environment, but change processing is required by the target enterprise system. The class is intended to be extended by customizers. These are the available methods of the class:
createChangeOrder(item : Changeable2) : WTChangeOrder2
Creates a change request, a change order and a change activity, and associates theargument to the change activity. No change request is created if the preference Change Notice without Change Request is set to Yes.
1. Obtains an instance of WTChangeRequest2 from an instance of ESIChangeRequestFactory, provided the preference Change Notice without Change Request has a value No.
2. Obtains an instance of WTChangeOrder2 from an instance of ESIChangeOrderFactory. A null is passed in to the create() API of ESIChangeOrderFactory if no change request was created in (1); otherwise, the WTChangeRequest2 object that was created is passed in.
3. Obtains an instance of WTChangeActivity2 from an instance of ESIChangeActivityFactory.
4. Invokes associateChangeableToChangeActivity().
associateChangeableToChangeActivity(changeActivity : ChangeActivity2, item : Changeable2)
Persists the association between a given change activity and a given changeable.
getChangeRequestFactory() : ESIChangeRequestFactory
Returns an object capable of creating change requests.
getChangeOrderFactory() : ESIChangeOrderFactory
Returns an object capable of creating change orders.
getChangeActivityFactory() : ESIChangeActivityFactory
Returns an object capable of creating change activities.
ESIChangeRequestFactory
This class is responsible for creating and saving a change request. This class may be extended by customizers. These are the available methods of the class:
create() : WTChangeRequest2
Creates and saves a new change request.
getName() : String
Returns the name to be given to the new change request. The value is localized from EsiResource.ESI_CHANGE_REQUEST_NAME.
getDescription() : String
Returns the description to be given to the new change request. The value is localized from EsiResource.ESI_CHANGE_REQUEST_DESC.
getPriority() : RequestPriority
Returns the priority to be assigned to the new change request. Value is always RequestPriority.LOW.
getCategory() : Category
Returns the category to be assigned to the new change request. Value is always Category.OTHER.
getComplexity() : Complexity
Returns the complexity to be assigned to the new change request. Value is always Complexity.SIMPLE.
ESIChangeOrderFactory
This class is responsible for creating and saving a change order. This class is may be extended by customizers. These are the available methods of the class:
create(changeRequest : WTChangeRequest2) : WTChangeOrder2
Creates and save a new change order; if the input argument is not null, the change order is associated to the input change request as well.
getName() : String
Returns the name to be given to the new change order. The value is localized from EsiResource.ESI_CHANGE_ORDER_NAME.
getDescription() : String
Returns the description to be given to the new change order. The value is localized from EsiResource.ESI_CHANGE_ORDER_DESC.
ESIChangeActivityFactory
This class is responsible for creating and saving a change activity. This class is may be extended by customizers. These are the available methods of the class:
create(changeOrder : WTChangeOrder2) : WTChangeActivity2
Creates and save a new change activity associated with the argument.
getName() : String
Returns the name to be given to the new change activity. The value is localized from EsiResource.ESI_CHANGE_ACTIVITY_NAME.
getDescription() : String
Returns the description to be given to the new change activity. The value is localized from EsiResource.ESI_CHANGE_ACTIVITY_DESC.
These are the classes that support the Windchill ESI Windchill workflows:
ESIResultEvent
Windchill ESI workflows may suspend until external processes are complete. When they do, the ESIResultEvent (otherwise known as the ESI release complete event) is the trigger that tells the workflow to resume. Objects of this class convey to a workflow whether or not a Windchill ESI external request succeeded. The class may be extended by customizers; however, Windchill ESI workflows are not designed to look for a subclass of ESIResultEvent.
Customizers are required to modify the Windchill ESI workflow templates if they want to extend the class ESIResultEvent. The following attributes have public getters and setters:
successful : Boolean
Defines whether or not the external process succeeded.
errorMessage : String = ""
An optional message to provide to the workflow.
targetUfid : String
The UFID of the ESIRelease object that represents the given release.
| | Out-of-the-box, the ESIRelease object serves as the target object for the ESI result event. |
esiReleaseUfid : String
The UFID of the ESIRelease object representing the given release. This is same as targetUfid.
txUfid : String
The UFID of the ESITransaction associated with this result. This is currently not used.
consumed : boolean
Defines whether or not the "ESI release complete" event that is posted by the PostEvent RPC has been received and consumed by the RTM workflow.
These are the public methods of the class:
ESIResultEvent(eventTarget : Persistable)
Only constructor for this class. Ensures that the object is always in the correct state.
getTarget() : Persistable
Returns the event target associated with this event.
| | The postEvent() API of class ESIReleaseUtility uses the value in the Windchill ESI preference Associate ESI Release Complete Event To Primary Business Object to determine the target object to use for the ESI release complete event. Thus, by setting the preference to Yes, the postEvent() API can be configured to associate the event to the primary business object, rather than to the ESIRelease object. This setting would come in handy when dealing with ESI failures that were migrated over from an earlier release of ESI, where the RTM workflow template expects the target object associated with the event to be the primary business object. |
These are the classes that provide the publicly available capabilities of Windchill ESI services:
ESIService
This interface defines the Windchill ESI methods that are available to remote clients. This interface has a wt.method.RemoteInterface annotation, which provides for remote access to the methods of the interface, via the ServiceFactory utility. This interface is not intended to be extended. These are the methods of the interface:
assignTarget(object : Persistable, target : ESITarget)
Assigns an object to an ESITarget for distribution target system destination determination. Delegates all work to an instance of ESITargetUtility.
assignTarget(object : Persistable, targets : Group)
Assigns an object to an Info*Engine group of ESITarget objects for distribution target system destination determination. Delegates all work to an instance of ESITargetUtility.
deleteTarget(tgt : ESITarget)
Deletes an ESITarget from the database. Delegates all work to an instance of ESITargetUtility.
removeTargetAssignment(object : Persistable, target : ESITarget)
Removes the relationship between an ESITarget and a persistable object. Delegates the deletion to an instance of ESITargetUtility.
removeTargetAssignment(ufid : String)
Deletes from the database the ESITargetAssignmentLink that is identified by the argument. Delegates all work to an instance of ESITransactionUtility.
getTransaction(id : String, object : Persistable
Returns the ESITransaction whose idNumber attribute matches the method argument for a given Persistable. Throws an ESIException if no matching transaction exists. Delegates all work to an instance of ESITransactionUtility.
getTarget(system : String) : ESITarget
Returns the distribution target whose number attribute matches the argument. Throws an ESIException if no matching ESITarget exists. Delegates all work to an instance of ESITargetUtility.
createTransaction(object : WTObject)
Creates and saves in the database a new ESITransaction that is linked to a WTObject. Delegates all work to an instance of ESITransactionUtility.
findESITargets(anObject : Persistable) : Collection
Returns a collection of ESITarget objects for the given object. If the object is a WTChangeOrder2, return the distribution targets associated with the changeables on the change order.
isWfLaunched(anObject : LifeCycleManaged) : boolean
Checks whether there is a workflow process with the status of OPEN_RUNNING for the given object.
ESIHelper
Provides access to the ESIService implementation and provides several generally useful utility methods. The class is not intended to be extended.
These are the public methods of the class:
<<Static>> getTxStatusURL(txUfid : String) : String
This method simply returns the URL returned by getReleaseStatusURL(releaseUfid : String). The only time this method would be invoked is when using the RTMworkflow template from an earlier release of ESI (for e.g., when re-submitting an ESI failure that was migrated over from an earlier release). And the UFID of the ESIRelease object is what would get passed in.
| | This method is deprecated and should not be invoked under any circumstances other than the above mentioned scenario. |
<<Static>> getReleaseStatusURL(releaseUfid : String) : String
Returns a URL associated with the input ESIRelease UFID for the Windchill Enterprise Systems Transaction Administration UI.
<<Static>> hasESITargets(anObject : Persistable) : boolean
Returns true if the given object has distribution target assignments.
<<Static>> isOnWfProcess(anObject : LifeCycleManaged) : boolean
Returns true if Windchill ESI workflow is OPEN_RUNNING and, therefore, processing the given object.
<<Static>> isReleaseNeeded(persistable : Persistable) : boolean
Returns a true if the preference Enforce Changes has a value No. If the preference has a value Yes, and if the input object is a Change Notice, the method returns a true only if (i) the object is not released yet and (ii) with the preference Enforce Changes To Resulting Objects set to Yes, there is at least one resulting object in the Change Notice that is not released yet; if the input Persistable is any other object, the method returns a true if the object is not released yet, and a false otherwise.
<<Static>> isTxActive(obj : Persistable) : boolean
Returns true if the transaction status is pending or processing. The class has a public static attribute.
service: ESIService
This final static attribute is initialized to a new instance of the remote interface implementation (StandardESIService, by default), thereby providing access to all the remote methods of the interface.
| | The above initialization is achieved via a call to wt.services.ServiceFactory.getService(serviceClass : Class<T>). |
ESISvrHelper
Provides access to the ESISvrService implementation. The class is not intended to be extended. The class has a public static attribute.
service: ESISvrService
This final static attribute is initialized to a new instance of ESISvrService implementation.
ESISvrService
Defines the non-client methods that are available on the Windchill ESI service. This interface is not intended to be extended. These are the methods of the interface:
postResult(objectID : String, description : String, txnID : String, successful : boolean, subtransaction : boolean, targetSystem : String, message : String, timestamp : String, action : String, cls : String, user : String)
PostResult RPC processor. Delegates all work to an instance of ESITransactionUtility.
postEvent(objectID : String, transaction : String, successful : boolean, message : String)
PostEvent RPC processor. Delegates all work to an instance of ESITransactionUtility. This method is currently not used.
getPart(objectID : String, alternates : boolean, documents : boolean, auth : String, wcAdapter : String, transactionID : String) : IeCollection
GetPart RPC processor. Delegates all work to an instance of ESIWTPartRenderer. This method is currently not used.
getBOM(objectID : String, delta : boolean, parts : boolean, alternates : boolean, substitutes : boolean, referenceDesignators : boolean, lineNumbers : boolean, mulitLevel : String, documents : boolean, configSpec : String, auth : String, wcAdapter : String, transactionID : String) : IeCollection
This method is the GetBOM RPC processor. Delegates all work to an instance of ESIBOMRenderer. This method is currently not used.
getECN(objectID : String, delta : boolean, componentParts : boolean, alternates : boolean, substitutes : boolean, referenceDesignators : boolean, lineNumbers : boolean, mulitLevel : String, documents : boolean, configSpec : String, auth : String, wcAdapter : String, transactionID : String) : IeCollection
This method is currently not used.
adjustTargetAssignments(ufids : String, targetInfo : Group)
Given a concatenated set of UFIDs (for WTPart objects) and a Collection of ESITarget UFIDs, makes (or removes) any required assignments.
▪ The ufids argument contains a set of UFIDs which define the parts to operate on.
▪ The targetInfo argument is a Group. Each element in the group has Atts that define:
▪ the ufid of an ESITarget
▪ the operation to perform on the parts. If the operation is "add", then all parts that do not have the distribution target assigned are given the assignment. If the operation is "remove", then all existing assignments for that distribution target to any of the existing parts are removed.
Delegates all action to an instance of ESITargetUtility.
getTargetAssociations(ufids : String, groupName : String) : Group
Given a string of concatenated UFIDs, return the ESITarget objects that are associated with those objects. If the ESITarget is assigned to all of the objects identified by a UFID, indicate that it is a full assignment; otherwise, indicate that the value is partial. Delegates all work to an instance of ESITargetUtility.
getTargetsWithHistory(objects : Collection) : Group
Returns an Info*Engine Group of mapped ESITargetHistory objects. The ESITargetHistory objects contain the following:
▪ The target attribute is one of the available distribution targets.
▪ The persistableObject is one of the objects in the argument to this method.
▪ If the persistable object has been published to the distribution target, the releaseAttribute contains the appropriate ReleaseActivity.
The result is serialized by the Windchill ESI mapping logic to a group of Info*Engine Element objects. All of the work is done by the ESITransactionUtility which is called by this method.
getTargetsWithHistory(ufid : String) : Group
Returns an Info*Engine Group of mapped ESITargetHistory objects. The ESITargetHistory objects contain the following: • The target attribute is one of the available distribution targets. • The persistableObject is one of the objects in the argument to this method. • If the persistable object has been published to the distribution target, the releaseAttribute contains the appropriate ReleaseActivity. The result is serialized by the Windchill ESI mapping logic to a group of Info*Engine Element objects. All of the work is done by the ESITransactionUtility which is called by this method.
getTargetsWithHistory(object : Persistable) : Collection
Returns a collection of mapped ESITargetHistory objects. The ESITargetHistory objects contain the following:
▪ The target attribute is one of the available distribution targets.
▪ The persistableObject is one of the objects in the argument to this method.
▪ If the persistable object has been published to the distribution target, the releaseAttribute contains the appropriate ReleaseActivity.
The result is serialized by the Windchill ESI mapping logic to a group of Info*Engine Element objects. All of the work is done by the ESITransactionUtility which is called by this method.
getHistory(ufid : String, groupOut : String) : Group
Returns a Group of mapped ReleaseActivity objects associated with the object identied by the argument. This is the functional equivalent of getTargetsWithHistory() for objects that do not have ESITargetAssignmentLinks but do have ReleaseActivity associations. The method does the following:
▪ Obtains an instance of ESIObjectHistoryRenderer and an instance of ESIObjectHistoryBuilder from the ESIObjectHistoryRendererFactory
▪ Invokes the render() method on the renderer
▪ Returns the result of builder.getGroup()
getActivities(ufid : String) : ReleaseActivity[]
Given the UFID of an ESITransaction, returns an array of all of the ReleaseActivity objects associated with that ESITransaction. Delegates implementation to ESITransactionUtility.
hideTransaction(ufid : String)
Hides an ESITransaction from the user interface.
recordExport(objectID : String, targetSystem : String, releaseClass : String)
RecordExport RPC processor. This method identifies an object as published to an ESITarget. It does the following:
1. Obtains the persistable object from an instance of TaskHelper using the objectID argument.
2. Obtains the distribution target from an instance of ESITargetUtility using the targetSystem argument.
3. Passes the distribution target, the persistable object, and the releaseClassargument to an instance of ESITransactionUtility.
getReleaseActivities(ufid : String) : Group
Returns an Info*Engine Group of mapped ESIReleaseActivity objects given the UFID of an ESITransaction object.
getTransactions(elements : Group) : Group
Returns an Info*Engine Group of ESITransaction objects that are associated with the objects in the argument. The argument is an Info*Engine Group containing Elements that have been created by (or resemble the output of) a Query-Objects webject. Delegates all work to an instance of ESITransactionUtility.
getReleaseActivitiesMessage(ufid : String) : Group
Return an Info*Engine Group of mapped ReleaseActivityMessage objects given theUFID of a ReleaseActivity object.
getTransactionLogMessage(ufid : String) : Group
Returns an Info*Engine Group of mapped ESITransactionMessage objects given theUFID of an ESITransaction object.
getECN(objectID : String, delta : boolean, componentParts : boolean, alternates : boolean, substitutes : boolean, referenceDesignators : boolean, lineNumbers : boolean, mulitLevel : String, documents : boolean, processPlanPart : boolean, resource : boolean, sequence : boolean, standardProcedure : boolean, suboperationDepth : String, operatedOnPart : boolean, bomPart : boolean, workInstructions : boolean, configSpec : String, auth : String, wcAdapter : String, transactionID : String) : IeCollection
This method is the GetECN RPC processor. Obtains a VdbBuilder from the VdbBuilder factory.
▪ Obtains an ESIWTChangeOrder2Renderer from an ESIRendererFactory instance.
▪ Provides the necessary data to the renderer from the arguments to thismethod.
▪ Invokes the render() method on the renderer.
Returns the result of VdbBuilder asVDB(). This method is currently not used.
| | For the various getXXX() APIs that are in use at this release, see the Javadoc. |
StandardESIService
StandardESIService is a concrete implementation of ESIService and ESISvrService. The class may be extended. These are the additional modeled methods of the class:
registerEvents(ms : ManagerService)
This method has no implementation.
dispatchVetoableEvent(eventType : String, obj : Persistable)
This method has no implementation.
performStartupProcess()
Prepares the Windchill Service to begin operations. This is a protected method that is called by the base class, StandardManager, for start-up processing. The method registers event listeners that:
▪ Listen for Identity Change events on parts, documents, change notices and process plans and validate them as appropriate.
▪ Copy distribution target assignments when new iterations, versions, and view- versions of parts or process plans, or new iterations and versions of documents are created.
▪ Copy alternate item groups when new WTPartSubstituteLink objects are created.
▪ Optionally, depending on Windchill ESI preference settings, launch a Windchill ESI workflow when a lifecycle state change occurs.
▪ Validate the values entered by the user for certain Windchill ESI preferences via the Preference Management UI, before updating those preferences in the database.
▪ Initialize certain workflow attributes or locale related maps when an ESIpreference changes, as may be appropriate.
| | 1. For the various getXXX() APIs provided by the class that are in use at this release,see the Javadoc. 2. If the class is extended to provide for custom behavior, the relevant property should be set in esi.wt.properties.xconf and propagated to the file wt.properties as appropriate. |