Using Quality of Service qualifiers in WebSphere Integration Developer V7, Part 1

Managing transactions and security in your business application

This article discusses how you can effectively use Quality of Service qualifiers provided by WebSphere® Integration Developer V7 to manage transactions, secure applications, and make reliable invocations in a business application.

Share:

Samanvitha Kumar (samanvitha.kumar@in.ibm.com), Staff Software Developer, IBM

Photo of the author, Samanvitha KumarSamanvitha Kumar works as a Staff Software Engineer at the IBM India Software Lab. She is an IBM Accredited IT Specialist (business applications) and is currently part of the WebSphere Commerce Development team. Samanvitha has 5 years of industry experience and has worked extensively in the Master Data Management and Business Integration space. She has published multiple articles in the business integration domain.


developerWorks Contributing author
        level

Pramodh Ramesh (pramodvr@in.ibm.com), Software Engineer, IBM

Photo of Pramodh RameshPramodh Ramesh works for Industry Solutions at the IBM India Software Lab. He has been working with various customers across different industry verticals like Banking, Telecom, and Retail. Currently, he is developing frameworks to provide end-to-end solutions for the Banking Industry. His core strengths include enterprise integration and business process management based on service-oriented architecture.



01 September 2010

Also available in Chinese Spanish

Introduction

The IT landscape of enterprises is highly complex because several systems are required for various operations. Achieving seamless integration between these systems with the help of business applications is important.

WebSphere Integration Developer (hereafter called Integration Developer) is an authoring tool that helps you compose complex business applications based on your requirements. It provides an easy way to achieve critical functional and non-functional requirements, without requiring programming or any change to service implementation code by means of qualifiers. Qualifiers are Quality of Service (QoS) specifications that define a set of communication characteristics required by an application for transmission priority, level of route reliability, transaction management, and security level.

Qualifiers define how much management must be provided for a component at runtime. They propagate transactions and control the quality and timing of message delivery. You can use qualifiers to extend the quality of service to components, helping to address error handling and load and performance requirements of the business service.

This two-part article series will discuss all the QoS qualifiers provided by Integration Developer. We have chosen Integration Developer V7.0 for the purpose of this article as this is the latest version and supports 13 different types of qualifiers. Part 1 of this article will focus on 6 of them, which deal with transaction, security, and data validation. It will provide the description, applicable values, and possible scenarios for each of the qualifiers to help you understand which one to use in your business application.


Understanding qualifiers

Quality of Service qualifiers are specified in the assembly editor in Integration Developer and can be set on:

  • Interfaces: These specify the qualifiers supported by a target service and represent a contract between a service and the client.
  • References: These specify the reliability for asynchronous invocations and whether a target component’s methods should be federated as part of any client transaction.
  • Implementations: These are used to identify the service's authority and express its requirements for a transactional environment.

The following is the list of all the qualifiers provided by Integration Developer V7.0. This article describes the first six:

  1. Transaction qualifier
  2. Join transaction qualifier
  3. Security identity qualifier
  4. Security permission qualifier
  5. Suspend transaction qualifier
  6. Data validation qualifier
  7. Activity session qualifier
  8. Asynchronous invocation qualifier
  9. Asynchronous reliability qualifier
  10. Event sequencing qualifier
  11. Join activity session qualifier
  12. Store and forward qualifier
  13. Suspend activity session qualifier

By default, Integration Developer generates some qualifiers to provide transaction handling and reliable asynchronous message delivery. You can edit these preset values in the assembly diagram based on your business need. To see and edit the qualifiers used in a module:

  1. Right-click an empty portion of the canvas and select Show In > Properties View.
  2. Click the All Qualifiers tab, where all of the qualifiers defined in the module are displayed as shown in Figure 1.
    Figure 1. Viewing qualifier settings
    Viewing qualifier settings

Transaction qualifier

A transaction is a unit of activity within which multiple operations on data can be made atomic (indivisible), such that exactly all or none of the actions are made permanent. The transaction qualifier is used to define a logical boundary or unit of work, such that either all or none of the changes made by the components falling within this boundary are committed or rolled back as a single unit. This is used when a set of operations are dependent on each other, mandating that either all are completed successfully, or all are rolled back even if one of them fails.

Applied on: Implementation

Applicable values: As shown in Figure 2, the transaction qualifier can have any of the settings below, depending on the design of the business application:

  • Global: A global transaction is a unit of work in a distributed transaction processing environment in which multiple resource managers may be enlisted. Things to note in a global transaction are:
    1. If the client propagates a transaction and a component is configured to join that transaction, then this component will run under the same transaction. In other words, resources updated by the component are committed when the client commits the transaction.
    2. If either of these conditions is missing, the component runs under a new global transaction that is committed when the operation completes.
  • Local (default): This setting is required when a component implementation is not capable of participating in a two-phase commit protocol. Things to note in a local transaction are:
    1. Even if the client propagates the transaction and the transaction qualifier is set to local, then the component runs in a local transaction because running the business logic in a local transaction performs better than in a global transaction in certain scenarios.
    2. Local transactions are not propagated to services invoked by the component.
    3. The local transaction joins an activity session if one is active. If an activity session is not currently active, one is started automatically.
  • Any: If a global transaction context has been propagated from the client, the runtime environment will dispatch methods from the component in a global transaction. Otherwise, the runtime environment will establish a local transaction environment.
  • Local application: Use this qualifier in scenarios where the application holds the responsibility for managing the transactions. Selecting this option is equivalent to setting the transaction descriptor to Not Supported and setting the LocalTranResolver to application for an enterprise Java™ bean.
Figure 2. Possible values of the Transaction qualifier
Possible values of the Transaction qualifier

Scenario

Consider a case where you have an SCA component that provides certain important operations and needs to be part of a global transaction due to the business need. In such a case, you will set the transaction qualifier on the implementation of this component to “global”. In some cases, you may also set it to “local” if the operations are better off if executed in a local environment, rather than using a global transaction that was propagated to it. The behavior of the components depends on the combination of the settings done for the transaction and join transaction qualifiers as explained below:

  • If the caller transaction qualifier is set to "global" and the called one interface joins the transaction, the called one executes under the same global transaction.
  • If the called one qualifier is set to "local", then the called one executes in a local transaction. In such scenarios, a join transaction cannot be set to "true" on the called one interface.
  • If the join transaction qualifier is set to "false" on the called one and the transaction qualifier is set to "global", a new global transaction is started.
  • If the transaction qualifier on the called one is set to "local", then the transaction is not propagated to the service invoked by it.

Join transaction qualifier

This qualifier determines whether the target service is capable of joining a client-propagated transaction. Since transactions can be propagated only during synchronous invocations, the join transaction qualifier is applicable only when a client invokes a service synchronously.

Applied on: You can apply the qualifier at three levels of a component or import:

  • All of its interfaces
  • An individual interface
  • An individual operation of an interface

Applicable values: You can set the join transaction qualifier to either “true” or “false”, depending on the business need. If set to:

  • True: The component joins a transaction propagated by its caller, if it happens to run in a global transaction.
  • False: The component does not join a transaction propagated by its caller.

Scenario

Consider an enterprise that is using an ERP system for maintaining the HR related information (HR Services) and another ERP for information related to payroll (Payroll Services). In this scenario, the business flow is to create an employee record that involves creating a record in the HR system as well as in a Payroll system. For a successful completion of the application, it is necessary for the records to be created in both systems, as shown in Figure 3.

Both the modules have Java implementations that have been coded to create records in the HR and Payroll systems, respectively. Ideally, you will use the respective adapters while connecting to such enterprise systems. The Java approach has been used for demonstration purposes only.

Figure 3. Assembly diagram for join transaction scenario
Assembly diagram for join transaction scenario

Given the above use case, it is evident that a record needs to be created in both the systems only if both operations are successful. This brings us to the concept of a transaction where, all or none of the changes made by participating operations need to be made permanent. In other words, we know that if any of the two operations fail, the entire transaction has to be rolled back. Hence, both these operations need to participate in a “transaction”.

To achieve this, use the “join transaction” qualifier on the HR and Payroll modules. By setting this value to “true”, you are ensuring that both the components participate in the global transaction propagated by the CreateEmployee module as shown in Figure 4. Consider the case where the HR module succeeds while the Payroll module fails (maybe due to insufficient data, incorrect data, network issues, and so on). The changes made by the HR transaction are also rolled back.

Figure 4. Setting join transaction qualifier on the interfaces
Setting join transaction qualifier on the interfaces

Note: The “join transaction” qualifier also needs the transaction qualifier to be set on the implementation to a value of “global” or “any” as a prerequisite. If the transaction is set to “local”, this generates an error (CWSCA8018E: The joinTransaction qualifier defined on the interface and the transaction qualifier on the implementation do not match) as these two settings are incompatible. In other words, it is not possible for a component to join a transaction that happens to be local in nature.


Suspend transaction qualifier

This qualifier determines whether a caller or client will propagate its transaction to the target component during synchronous invocation. This qualifier takes effect in a global transaction only and is ignored when it is a local transaction or if the invocation is done asynchronously. When the caller wants to control a transaction, you use the suspend transaction qualifier. If the caller wants to commit the change, even if the called component fails, set its value to “true”.

Applied on: Reference

Applicable values: You can set the suspend transaction qualifier to either “true” or “false”, depending on the business need. If set to:

  • True: Synchronous invocations occur outside any client or caller’s global transaction. The transactional environment of the target component is not affected by this qualifier.
  • False: Synchronous invocations run completely within any client’s or caller’s global transaction.

Scenario

Consider an enterprise application that has two modules for creating and retrieving the employee information from the HR and Payroll core systems as shown in Figure 5. Here, the CreateEmployee module requires both the HR and Payroll modules to participate in a transaction as explained previously. However, the RetrieveEmployee module is said to be complete even if either of them is successful.

Figure 5. Assembly diagram for suspend transaction scenario
Assembly diagram for suspend transaction scenario

To achieve the above stated scenario, we have used the following qualifier settings on the CreateEmployee module, as shown in Figure 6:

  • Set Suspend Transaction = false on the HRServices reference.
  • Set Suspend Transaction = false on the PayrollService reference.
Figure 6. Setting suspend transaction qualifier on references of CreateEmployee module
Setting suspend transaction qualifier on references of CreateEmployee module

The settings on the RetrieveEmployee module are as shown in Figure 7.

  • Set Suspend Transaction = true on the HRServices reference.
  • Set Suspend Transaction = true on the PayrollService reference.
Figure 7. Setting suspend transaction qualifier on references of RetrieveEmployee module
Setting suspend transaction qualifier on references of RetrieveEmployee module

Note: The join transaction qualifier is still set to true on both the HR and Payroll Service modules. The functionality required by the RetrieveEmployee module can be achieved by setting join transaction = false on the HR and Payroll services interfaces. However, this conflicts with the requirements of the CreateEmployee module. Hence, when the client needs to control a transaction, use the suspend transaction qualifier. When the service provider needs to control it, you will resort to the join transaction qualifier.

Transaction highlighting

The assembly editor provides highlighting to show where a transaction is propagated. Right-click any empty area on the assembly editor canvas and select Show Transaction Highlighting. This displays all the transaction related data as shown in Figure 8.

  • If an element is not highlighted at all, it does not join or propagate a transaction.
  • A thick solid green line around an element and along a wire shows that the element joins a transaction and the wire propagates a transaction.
  • A broken green line indicates that a transaction might be joined or propagated, but the system cannot confirm that will happen. A Java component reference might have a broken line leading to the target service because the system cannot determine if the Java component makes synchronous or asynchronous outbound calls.
  • A dotted line around a component indicates that the component participates in at least one transaction, but it might participate in more than one transaction.
    Figure 8. Transaction highlighting
    Transaction highlighting

Security permission qualifier

Use the security permission qualifier to restrict access to an operation in an interface to a specified set of users or groups.

If the security permission qualifier is specified, the identity of the caller must have the designated role in order to be permitted to call the interface or operation. If no security permission is specified, no permissions are checked and all callers are permitted to call the interface or operation.

Applied on: You can apply the qualifier to three levels of a component or import:

  • All of its interfaces
  • An individual interface
  • An individual operation of an interface

Scenario

Let us consider a scenario where the Payroll Service needs to be secured so that it is accessed only by authorized users. Hence, the service is accessible only to those callers who identify themselves and are authorized. To define security restrictions for operations or the interface as a whole, use the security permission qualifier.

As shown in Figure 9, we have defined the security permission qualifier on the entire payroll service by defining a “Payroll Auth” role. This means that only those callers, who are part of the Payroll Auth role, are allowed to access the service and others will be denied.

Figure 9. Setting security permission qualifier on PayrollService interface
Setting security permission qualifier on PayrollService interface

You can add users to this role by using the Security role to user/ group mapping in the application:

  1. Once the application is deployed, navigate to the particular application under Enterprise Applications in the Administrative Console.
  2. Click your application name and click Security role to user/ group mapping.
  3. Choose the role, namely Payroll Auth, and click Map users to add particular users or Map groups for adding groups.

In our scenario, we are adding a particular user named payrolladmin as shown in Figure 10. You can also add more users, depending on your requirement. This means that any caller who is part of Payroll Auth role can now invoke this service successfully.

Figure 10. Security role to user/ group mapping
Security role to user/ group mapping

Security identity qualifier

The security identity qualifier specifies the identity under which the implementation executes at runtime by providing a logical role name.

If this qualifier is not specified, then the implementation executes under the identity of its caller, or under the hosting container's identity if no caller identity is present. Roles are associated with the identity and the roles dictate if the implementation is authorized to invoke other components.

Applied on: Implementation

Scenario

Let us consider the previous use case where the Payroll service was secured and only users of the Payroll Auth role are allowed access. For the CreateEmployee component to access the Payroll service, it needs to access it as one of the users under “Payroll Auth” role defined by the Payroll service. For defining such run as users, we shall use the security identity qualifier.

As shown in Figure 11, we have defined “Security identity” on the CreateEmployee component by defining a role called “Payroll access”. This means that the CreateEmployee module will run under the identity for a particular user defined to the “Payroll access” role.

Figure 11. Setting security identity qualifier on CreateEmployee implementation
Setting security identity qualifier on CreateEmployee implementation

Similar to the previous case, we need to again set the security role to user/ group mapping in the Admin Console:

  1. Navigate to this application under Enterprise Applications in the Administrative Console. Click the application name and click Security role to user/ group mapping.
  2. Choose the role namely, Payroll access, and click Look up users. Assign a user to this role as shown in Figure 12.

To show a negative case, you can add a user by name of "noauth" to the Payroll access. Again, this role is mapped to more than one user or a group of users.

Figure 12. Adding wrong user to user or group mapping
Adding wrong user to user or group mapping

Additionally, this qualifier also mandates the setting up of the User RunAs roles in the Admin Console:

  1. To complete this activity, open the Administrative Console of the server and navigate to Enterprise Applications.
  2. Click your application name and click User RunAs roles.
  3. Provide the username and password of the user that you want to add to this role. Select the checkbox next to Payroll access and click OK. The new user is added to the required role as shown in Figure 13.
    Figure 13. Setting the User RunAs role
    Setting the User RunAs role

As per the above configuration, the Create Employee component will execute under the identity of “noauth”.

Executing the application

Because the “noauth” user is not part of the “Payroll Auth” role defined by the Payroll Service component, the service access fails with the error shown in Listing 1.

Listing 1. Security Identity qualifier error
Caused by: com.ibm.websphere.sca.ServiceRuntimeException: Fail to invoke 
 [CreateEmployeeImpl.public commonj.sdo.DataObject CreateEmployeeImpl.createEmployee
 (commonj.sdo.DataObject)] for component [{Article}CreateEmployee]: caused by: 
 com.ibm.websphere.sca.ServiceRuntimeException: Permission denied: User noauth 
 is not in role:Payroll Auth and does not have permission to invoke the method
	at com.ibm.ws.sca.internal.java.handler.JavaImplementationHandler.invokeSync
     (JavaImplementationHandler.java:473)
	at com.ibm.ws.sca.internal.java.handler.JavaImplementationHandler.processMessage
     (JavaImplementationHandler.java:195)
	at com.ibm.ws.sca.internal.message.impl.MessageDispatcherImpl.
     processMessageWithPCI(MessageDispatcherImpl.java:753)

Since there is a mismatch in the users specified, the execution of the application is not possible. The solution is to make sure that the user specified under the RunAs role matches the required security specification of the service.

In our scenario, add “payrolladmin” to the “Payroll access” role. Figure 14 shows the new mapping under the security role to a user or group mapping. Figure 15 shows the User RunAs role that now contains payrolladmin.

Figure 14. Mapping payrolladmin to Payroll access role
Mapping payrolladmin to Payroll access role
Figure 15. Adding payrolladmin to User RunAs role
Adding payrolladmin to User RunAs role

Also, in case you do not complete the step of setting up the RunAs data, you will get an error at runtime as shown in Listing 2.

Listing 2. Exception thrown due to an empty RunAs role setting
com.ibm.ws.sca.uow.UOWRolledBackException: caused by: com.ibm.websphere.sca.
 ServiceRuntimeException: The run-as authentication data is not configured 
 for role Payroll access
	at com.ibm.wsspi.sca.ejb.module.impl.ModuleSessionBean.processUOWMessage
     (ModuleSessionBean.java:348)
	at com.ibm.wsspi.sca.ejb.module.impl.ModuleSessionBean.
     transactionRequiredActivitySessionNotSupported(ModuleSessionBean.java:315)
	at com.ibm.wsspi.sca.ejb.module.EJSLocalStatelessModule_43132892.
     transactionRequiredActivitySessionNotSupported(EJSLocalStatelessModule_
     43132892.java:233)
	at com.ibm.ws.sca.internal.uow.handler.UOWStrategyImpl.
     transactionGlobalActivitySessionFalse(UOWStrategyImpl.java:311)
	at com.ibm.ws.sca.internal.uow.handler.JoinUOWHandler.processMessage
     (JoinUOWHandler.java:165)
	at com.ibm.ws.sca.internal.message.impl.MessageDispatcherImpl.processMessage
     WithPCI(MessageDispatcherImpl.java:726)
	at com.ibm.ws.sca.internal.message.impl.MessageDispatcherImpl.processMessage
     (MessageDispatcherImpl.java:1167)
	at com.ibm.ws.sca.internal.message.impl.ManagedMessageImpl.process
     ManagedMessageImpl.java:834)
	at com.ibm.wsspi.sca.ejb.module.impl.ModuleSessionBean.processMessage 
     (ModuleSessionBean.java:153)
	at com.ibm.wsspi.sca.ejb.module.EJSLocalStatelessModule_43132892.
     processMessage(EJSLocalStatelessModule_43132892.java:97)
	at com.ibm.wbit.comptest.controller.invocation.impl.AdhocInvoker.
     processMessage(AdhocInvoker.java:72)
	at com.ibm.wbit.comptest.controller.invocation.impl.Invoker.
     managedInvoke(Invoker.java:284)
	at com.ibm.wbit.comptest.controller.invocation.impl.Invoker.
     invoke(Invoker.java:175)

Thus, from the above two scenarios, we can understand that for the service provider to restrict the access, it can use the security permission qualifier and the client can use the security identity qualifier to run as a particular role.

Note: The service provider and the consumer can be across two different modules or systems as well.


Data validation qualifier

The data validation qualifier ensures that the data passed to an operation matches the XSD types of the operation's input. You can use it to validate instance data from a business object.

Applied on: You can apply this qualifier to three levels of a component or import:

  • All of its interfaces
  • An individual interface
  • An individual operation of an interface

Applicable values: You can set the data validation qualifier to either of the below values, depending on the design and requirements of your business application:

  • Log error and continue (default): If an error is encountered, the error is logged and the requested operation is performed. There is no guarantee that the service can handle data that is not valid, so a runtime error can occur.
  • Throw exception: If an error is encountered, an exception is thrown and the operation is not performed.

Scenario

Consider a component whose responsibility is to retrieve the details of an order, given the order ID as an input. It is possible that there are some constraints with respect to the format of the Order ID element. For example, some applications define constraints such as the maximum length of the element, pattern details, disallowance of alphabets, and so on. In such a case, passing on an Order ID, which does not conform to these standards, will obviously result in a runtime error. This is where you can do a preliminary check by using the data validation qualifier.

As shown in Figure 16, the “RetrieveOrderDetails” BPEL component accepts the Order business object as an input and does the job of fetching order details from an external system. It also performs some additional tasks, such as logging and storing the details for future use. The OrderBO is a business object that has OrderID, Description, and a list of Items.

Figure 16. RetrieveOrderDetails BPEL and OrderBO
RetrieveOrderDetails BPEL and OrderBO

For the above requirement, you can set the data validation qualifier on the interface as shown in Figure 17. You have set the value to “Throw exception” as this is a fatal error and further processing is meaningless without details of an order. The validation is basically done against the definition of the business object that is supplied as a parameter to this interface.

Figure 17. Data validation qualifier
Data validation qualifier

In this example, there is a limit set on the maximum length allowed for the “OrderId” element in the OrderBO, as shown in Figure 18. Other restrictions such as allowable values, minimum length, patterns, and so on can also be set.

Figure 18. Setting maximum length on the OrderID element
Setting maximum length on the OrderID element

An exception is displayed if the input to the Order interface violates the rules setup against the business object. The execution of the process stops as per the qualifier setting and details about the exception are also logged. Consider the case where the OrderID passed is greater than 10 characters in length. In this case, an exception appears as shown in Listing 3.

Listing 3. Exception thrown by the Data Validation qualifier
[3/2/10 14:44:16:765 IST] 00000054 Core          E   CWSCA2001E: 
 The SCA message-driven bean returned the following exception: 
 "com.ibm.websphere.sca.ServiceRuntimeException: com.ibm.ws.bo.handler.
 BOInstanceValidationException: wsdl:http://DataValidation_Interface/
 OrderInterface:processOrder_._type validation returned the following errors:
Property: OrderID has error: CWLBN1010E: The value '78458475874' with 
 length 11 may have at most length 5/n: caused by: com.ibm.ws.bo.handler.
 BOInstanceValidationException: wsdl:http://DataValidation_Interface/
 OrderInterface:processOrder_._type validation returned the following errors:
Property: OrderID has error: CWLBN1010E: The value '78458475874' with length 
 11 may have at most length 5/n".

Note: Usage of this qualifier leads to performance overhead. Hence, avoid overusing this qualifier. This qualifier is useful when a given business object is used in a number of components. In such a case, instead of including code snippets to do this check at each component, enforcing a global standard is easier.


Conclusion

This article showed how and when to use the QoS qualifiers to provide transaction handling, security handling, and data validation. It discussed some sample scenarios where these qualifiers contribute to the performance and the functionality of a business application. Once the advantages and functionality of these qualifiers are clearly understood, they can significantly help you design complex business applications.

Part 2 of this series will describe activity sessions, reliability, and event sequencing qualifiers, along with some sample scenarios.

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=514082
ArticleTitle=Using Quality of Service qualifiers in WebSphere Integration Developer V7, Part 1
publish-date=09012010