WID Best Practices Employ code versioning. WebSphere Integration Developer has a CVS/ClearCase view so you can setup source control quickly. This will save you countless hours in the end, even if you only setup a CVS/ClearCase repository on the same machine as WebSphere Integration Developer. For instance, should you find a bug in your assembly, with proper versioning you can check back to previous versions to see when the bug was introduced. On smaller projects, you can use project interchanges to backup your workspace periodically. The project interchanges are a good way to do a quick backup, but it doesn’t version well because it can’t be shared. It may not remember about synchronization with clearcase. The PIs aren’t a change management tools, they’re a tool for persisting a project’s state outside a workspace. In the ideal world of version control, if you don’t have anything checked out, you ought to be able to construct it by extracting the appropriate authored artifacts from Clearcase and building. Initialy the CVS/ClearCase is recommended and only incase of small projects this adhoc way of “version control” is suggested. A project interchange file is a ZIP file that can backup any number of projects in your workspace. You can create one by selecting File => Export.. => Project Interchange. It is recommended to create a project interchange or a new source control version after each SCA component you build. Make sure you use descriptive filenames for interchange ZIP files. For example, name them by date. In case of a change, either in your application or calling service, you need strong governance in place and you need to have contingency plans in place for third-party failures in exactly the same way that you would have contingency plans in place should the provider of other third-party services fail. This is the starting point. In general, external services can change and some mechanism needs to be defined to deal with this. For example, what happens if a service (this service being well external to the process) changes at a semantic level (e.g., something that can’t be hidden; it requires a change to the process and we don’t want to implement the change right away for whatever reason? Obviously, long-lived Long Running processes are a subset of this case. In this case, you need a way to maintain both the old and new version of the services.
- One of the solutions provided by WebSphere Process Server/WID is the selector. This is a component that can choose the target of an invocation dynamically at runtime, based on simple logic. Crucially, the choice of targets – and the definition of when they are active – can be modified at runtime. This means that you can respond to the problems outlined above without even having to reboot your application. It is an SCA component. It chooses which implementation of an interface to invoke based on simple logic. It can invoke implementations both inside a module and in other SCA modules. It can be reconfigured, at runtime, without having to redeploy the host module.
- WebSphere Process Server/WID provides business rules. These are runtime, and development, artifacts that let developers graphically describe business decisions and parameters. Solutions can call the appropriate business rule group to obtain the current value (or invoke the correct computation) as the process runs. Importantly, developers can parameterize these rules and expose them in a runtime GUI to appropriately authorized business users to change the settings as the application runs.
- There is a need for only new instances of a process to follow the new design and also the need for existing ones to dynamically be updated. Process versioning allows us to keep multiple definitions of a process in existence at once. Existing instances will continue to run according to their original designs, whereas new instances will pick up the new definition.
Add libraries with the dependency editor to avoid errors. Using WebSphere Integration Developer libraries is almost always a good idea so you can reuse business objects and WSDL interfaces. Otherwise, problems surrounding libraries that produce errors similar to the following will be common: CWSCA8025E: The WSDL PortType defined in the interface is invalid. CWSCA8011E: Operation checkCredit cannot be resolved. These errors indicate that a WSDL interface can't be found. A common cause for this is an undefined library dependency for a module. Libraries should be added by right-clicking the module and selecting Dependency Editor. After deployment, if shared resources change in the library, modules using the resources have to be updated. For example, two modules share some resources in a library. The applications are deployed. One of the modules has to be updated resulting in changes to some of the shared resources in the library. In this case, the second module also needs to be updated to reflect the changes in the shared resources. You should avoid modifying module dependencies outside of the dependency editor. When you add a dependency on a library, Java project, or J2EE project, changes are made to the module's properties. That is, the module's properties are changed, as follows: - The Java Build Path would have the library or project added to its build path.
- The Project References determines which J2EE projects or utility JARs are to be included in the resulting EAR file for the module. If in the dependency editor, the library or project is also selected to be Deployed with the Module, then the Project References will have the library or project selected so that it will be added to the EAR file for deployment.
Use the dependency editor to manage project dependencies for your modules and libraries instead of editing their properties. There are important Java assumptions set in the properties of modules and libraries, so you should not modify the Java properties, for example, to change their source and output folders. When you are designing a system or developing modules, you sometimes gain advantages by placing an intermediary module between a module and an external service that it is invoking. You can only use the approach described here if you are using SCA bindings. One advantage of using an intermediary module is that you can then change the external service or application that your application is invoking without interruption. For example, a module (A) with an import invokes a remote service through a direct connection. If you wanted module A to invoke a different remote service, you would need to update the logic. You would then need to stop the old version of the module and uninstall it from the server. The new version of the module could then be installed and started. During this process, there is an interruption of service for module A. If you use an intermediary module in your application and connect it to module A with an SCA binding, you have more flexibility. Module A can have an import that is wired to the export of an intermediary module or mediation module, module B. The modules must have matching interfaces. Module B invokes the service. Module B is a facade; module A contains the real business logic. When a new module is ready to be deployed, you can use the WebSphere Process Server administrative console to point the SCA import in module A from the old target module (module B) to the SCA export in the new one (say, module C), creating a seamless transition to the updated service. This method allows you to update an application without causing any interruption in service. The above pattern could also be used for external exports. Ensure that the server starts clean so that the runtime errors are not included into application errors. The application error stack trace may not include any of the code in the workspace (ex: it was a runtime exception by the business process container). WebSphere Process Server test server itself may be causing such errors. Ensure that it is patched and running normally. The runtime errors may include SIBus errors. When you run into a WebSphere Process Server or ESB runtime exception while testing your applications, restart the server and make sure that it comes up clean. It is important to distinguish a problem with your application from a server runtime problem. This can be a testing practice and should be treated as an exit criteria at some appropriate place in the application promotion process (e.g., can’t exit integration test if it doesn’t start clean). Check the administration console for installed applications from various projects/workspaces. WebSphere Integration Developer business integration applications make use of the WebSphere Application Server SIBus (system integration bus) heavily. The root cause of some of the problems can be due to many versions of the same application installed on the test server and the SIBus destinations (or JMS plumbing used by WebSphere Process Server and ESB assemblies) started to conflict. The user may not even know that more than one application is deployed on the server. The server view in Eclipse-based development environments only shows the projects deployed on the server that are in the current workspace. It is usually a good idea to use multiple workspaces; you may want to create a completely new workspaces for each project. When faced with a debugging problem, you can create a new workspace and try things in a different way. Each time, you may leave a module deployed on the server from the previous workspace. The best way to determine what is deployed in your test environment is to use the WebSphere Application Server administration console which can be accessed with a Web browser at the default address: http://localhost:9060/admin (use your port number!). Remove unneeded applications, and the server will start cleanly and without any SIBus conflicts. Remove emulators from the test component wizard! Sometimes the tests did not return errors, but they also did not seem to execute any behavior. The Configurations tab of the test component wizard shows the emulators. By default, WebSphere Integration Developer unit tests only the component you have right-clicked to test and emulates the others: it stubs out the interface associated with downstream components and returns default values. The assumption that the wizard unit tests all the components in an assembly is a common misconception. Remove all the emulators when you want all the components to be tested. This is local to someone who is unit testing in WID. Become familiar with the XML representation of components by paying attention to the underlying XML representations of WSDL interfaces, business process components, and business objects. All of these components use XML standards such as XML Schema Definitions (XSD) for business objects, Business Process Execution Language (BPEL) for business processes, and Web Services Definition Language (WSDL) for interfaces. Errors like below can be resolved by reviewing the XSD documents. cvc-attribute.3: The value 'myObject:Report' of attribute 'type' on element 'xsd:element' is not valid with respect to its type, 'QName'. First, find out what file in the workspace is causing the error. This is usually quite obvious in an Eclipse IDE, because little Xs mark the spot. The culprit is an interface called SimpleInterface. After double-clicking on the file we get the interface editor. The interface editor provides no way to debug the problem. To really get to the root cause, you need to look at the underlying XML representation of the interface which is a *.wsdl XML document. You can edit the XML by right-clicking the interface and selecting Open With => XML Source Page Editor. The error mentions "myObject:Report". Report is a complex XML Schema type which is defined in another file (probably called Resport.xsd). In order to reference external complex types, a namespace identifier is used. The namespace identifier is myObject. However, the namespace was declared as myObjects with an extra letter "s". Changing either of them so that they are consistent resolves the error. Even better, enforce a requirement that nothing enter an integration build with errors, especially flags on XSD files for schema validation. The XSD representations of business objects are fundamental – they describe the serialization rules and how they interface to just about everything; if they’re wrong, the BO probably can’t be represented correctly in WPS and certainly won’t ever get out.
Make sure that the installation path for WID is small or modify the installation path. There is a 259 character limit for Windows path lengths. If WebSphere Integration Developer is installed under Program Files, errors such as the following can occur: [7/23/06 16:59:14:500 EDT] 0000009f WorkSpaceMast E The URI length is greater than the Windows limit of 259 characters. Unable to create or update file: C:\Program Files\IBM\WebSphere\ID\6.0\pf\wps\wstemp\10c9d2da4bb\ workspace\cells\widCell\applications\inEnergyProcessApp.ear\deployments\ inEnergyProcessApp\inEnergyProcessEJB.jar\META-INF\wsdl\com\ibm\extremeblue\ inenergy\process\outageprocess\OutageProcess.wsdl The solution is to use a shorter install path such as C:\WID or D:\IBM\WID, rather than the full product name. As a temporary fix, you can also use shorter business integration module names. Through Eclipse, WebSphere Integration Developer provides a filtering function known as capabilities. With capabilities, you can choose to hide tools not used during business integration application development; at any time, you can choose to show those tools again. In the Preferences settings, the product's functions and tools are categorized into capabilities. You can choose to enable and disable categories of capabilities or the subset functions of any category. The Integration Developer capability is also implemented as a role, which can be enabled and disabled from the Welcome view's Enable Roles interface. Various perspectives can also be used to filter information. The Business Integration perspective provides simple, uncluttered views of essential resources so you can model and build business solutions. Unnecessary details and unused tools are hidden. By default, when you launch the product, the Business Integration perspective is opened. In addition to viewing resources, you may need to document the applications that you are building. WebSphere Integration Developer provides a tool to generate documentation for the resources in your modules, mediation modules, and libraries. You initiate the documentation generation by invoking a wizard. You can customize the contents of the documentation by selecting multiple resources from one or more modules and libraries so that all the information will be written to a single report, which is a PDF file. You can also specify the layout and fonts for the output. WebSphere Integration Developer provides cheat sheets to guide you through some of its application development processes. The Business Integration cheat sheets import resources to let you explore the business integration tools. As you progress from one step to the next, the cheat sheet will automatically launch the required tools for you. If there is a manual step in the process, the step will tell you to perform the task and click a button in the cheat sheet to move on to the next step. Also, relevant help information and sometimes, viewlets are available so that lengthy documentation searches will no longer be required. Access the cheat sheets from Help menu from the WID. JavaServer Pages (JSP) files invoke Service Component Architecture (SCA) components using stand-alone references in the module assembly. The JSP file has to be deployed in the same EAR file as the module assembly. Do not copy the sca.references file to another EAR file. The file will not work outside of the module that it belongs to. If a JSP invokes SCA directly in this manner, it’s now dependent on WPS. For simple applications or JSPs that are otherwise intrinsically tied to the module, that’s probably correct. But you need to decide if you want that close a coupling. Since web apps are really freestanding, they ought to use a more standard J2EE means of getting at SCA services. The online component of e-MPIRE is based on EAD4J, which like any MVC framework has its own action objects. These ought to use the framework to invoke components so that they can run in WAS – at present, we’re treating the online as a freestanding component. This makes sense if it has to deal with functionality outside WPS. This section is valid only if we are using a JSP to invoke an SCA component but does not recommend using that approach. If you need to develop Java applications or import JAR files that will be used in a business integration module, you should create a Java project for the code and add a dependency on the Java project to the module that will be using the Java code. The Java properties of the business integration library or module should not be altered because this may cause problems in deployment code generation. As a result, it is not recommend that you develop complex Java applications or import JAR files into a library or module in order to use them. Also, when generating Java implementations for components in an assembly diagram, the generated Java implementations should be used as a launch point to call other Java classes. Note that the Business Integration view only shows Java implementations and interfaces that are used in an assembly diagram. They are listed under the module that uses them. If you need to work with Java projects you can switch to work in the Java perspective. If you plan to use imports and exports in assembly diagrams, it is a good practice to put the business objects and interfaces that are used by the import and exports into a library so that they can be shared. Then, add a dependency on the library to all of the modules that use these common resources. Avoid copying the same business objects and interfaces into different modules to use them. When you build a component using the enterprise service discovery wizard, you are given the option of including the resource adapter in your module. Why might you consider this option and what is the tradeoff? Sometimes you may have several versions of the same resource adapter. Including the resource adapter with the module could be a way of handling the different versions. There is also a security consideration. You may not want a user accessing a resource adapter and so you could contain it in the module. Is the user accessing the resource adapter from the same application? Then you might include it. But if the user is accessing the resource adapter from another application, then it needs to be separate from the module. The tradeoff for including the resource adapter in the module is that with each deployed service you are carrying the cost of an additional resource adapter, which can occupy considerable space on your application server. Also, there is a higher maintenance cost. When you have to upgrade a resource adapter, if it is installed on a server then you only have to make a single update. One more point: some resource adapters may only support being deployed embedded in a module or on the server. Faults can occur when a process instance is created or when operations that are invoked as part of the navigation of a process instance fail. Mechanisms exist to handle these faults and they include: - Passing control to the corresponding fault handlers
- Stopping the process and let someone repair the situation (force-retry, force-complete)
- Compensating the process
- Passing the fault to the client application as an API exception, for example, an exception is thrown when the process model from which an instance is to be created does not exist
Faults can be either business faults or system faults.
Business faults Application errors Application errors are considered to be an “application” fault – they occur when data passed into a component has errors that keep the component from completing. To JCA and WPS, these errors appear to be a normal return from the service. Fatal errors A fatal application error is also reported by the application component and is signaled by data in a returned copybook. Unlike edit errors, these don’t provide a full response field passed back by the component. They do provide an indication of “fatal” and potential text error messages. This information and the original BO are useful for diagnosing the problem. System faults A particular fault case that is covered by transaction rollbacks is the case of a failure of either a WPS process or the LPAR that is hosting it. If the WPS process fails, the transaction is still retained in its transaction log. When the WPS container restarts, it completes or aborts any outstanding transactions. A transaction can be completed if WPS has already started the commit process. Otherwise, it’s rolled back and undone in CICS, DB2, and elsewhere, following the rollback scenario already outlined. The next time through, the transaction will probably complete. If the LPAR itself fails, the transaction log (which is on shared disk storage) is still accessible to WPS servers on the other LPAR, which will complete or abort any outstanding transactions. The aborted transactions will roll back the message to the input queue for the process.
Once the message has been rolled back, it is retried automatically by WebSphere Process Server. The number of times that WPS attempts to execute the transaction before it treats this as a hard failure is configurable in WPS.
The WPS administrative tools for SIBus (specifically, the activation specification for the SIBus invocation) define the behavior of queues and MDBs when the same message repeatedly results in an aborted transaction. A failed message will, after a configured number of transaction rollbacks, be diverted to an error queue. Poison messages can’t be handled automatically, as their ultimate disposition is application dependent. These would be diverted into a manual process where they could be corrected or otherwise processed.
API exceptions If a method in the BusinessFlowManagerService interface or the HumanTaskManagerService interface does not complete successfully, an exception is thrown that denotes the cause of the error. You can handle this exception specifically to provide guidance to the caller.
However, it is common practice to handle only a subset of the exceptions specifically and to provide general guidance for the other potential exceptions. All specific exceptions inherit from a generic ProcessException or TaskException. It is a best practice to catch generic exceptions with a final catch(ProcessException) or catch(TaskException) statement. This statement helps to ensure the upward compatibility of your application program because it takes account of all of the other exceptions that can occur.
Transient errors Transient errors include a variety of error conditions that will result in a system or middleware generated exception passed up through CTG to the WPS process. These errors are “transient” because in many cases the transaction will succeed during a subsequent re-try attempt. Some transient errors cause an immediate response whereas others are detected as the result of a transaction timeout somewhere in the chain from WPS to the CICS transaction. - Transaction timeouts due to database locking
- Transaction timeouts due to SOC7 and similar CICS events
- Non-timeout/software exceptions
- Infrastructure/network related faults
System outages A planned outage occurs when an important subsystem (the most important example is the mainframe CICS applications, which have scheduled downtime windows) is unavailable for a significant period of time. Planned and long-term outages are presumed to be visible to an external system monitoring agent.
A non-transient outage on z/OS will result in transaction rollbacks. The usual reason for such an outage is planned downtime.
On one hand, planned downtime is similar to the intermittent failure scenarios described above: when DB2 and CICS are back up, the same transaction invocation will succeed. Any transaction rollback that results as a consequence of outages should not be processed as a poison message. However, if no provision is made for long-term outages, there is no way for the messaging support in WPS to tell whether these are poison messages.
There are several alternative approaches to managing outages. The first is to simply allow the transactions to abort and roll back, and to build a poison message handler that is sophisticated enough to hold the messages for later. The second approach is to use external system management tools to detect the outage (or to be aware of it in advance) and to shut down the application module during the outage. A third approach is for the error handling framework to explicitly identify the “system down” outage case and to divert any messages to a designated hold queue that is explicitly intended to be replayed into the original process. 1.1.19 Best practices: Selectors In a typical selector, the routing algorithm uses the date and time settings to determine which component to route an operation for implementation. In a situation where you have a single interface with three individual operations, you could use a selector as a delegation tool to route the operations to the appropriate destinations. To do this, you would implement the interface with a selector, and then implement an interface for each destination that contains an operation that is defined in the original interface. If there is only one destination for the operation, it is recommended that you select it in the default destination, and leave the destination table empty. If there are two destinations which represent the current and future behavior for an operation, it is recommended that you create two destination rows in the table and leave the default destination empty. If there is some standard behavior for the operation, which is occasionally overridden for short durations, it is recommended that you use the default destination for the standard behavior and create a destination row for each short term behavior. Business rules are primarily useful for implementing versioning and basic changes to business processes. That’s why they’re called business rules. It’s not a full-featured rules inference engine. The value of Rules is that you can set up rules that can be parameterized at runtime. A state machine is an alternative realization of a long running process – instead of describing it in BPEL (which has a workflow approach to describing a business process), you describe it as states and transitions. It’s valuable when the business problem is naturally amenable to state transition – an example is a process that is basically driven by asynchronous events. Modeler can’t really support this yet. EIS imports and exports are different from web services imports and exports in that rather than talk a web services protocol and encoding standard, they talk some proprietary EIS standard. These are typically associated with JCA adapter support. The JCA adapter package provides some degree of tooling support to facilitate constructing these. |