Siva's Blog

In this post, you will learn to do Error Handling and will incorporate in the Pipeline Template created in post.  We consider our Pipeline to return generic Fault response with error message in all possible error scenarios.

As you know, service provider can send error to consumer in following ways:

• As a normal response, by populating fields like “ErrorNumber” and “ErrorMesssage” (assuming that these fields are defined in response message of operation in WSDL).
• As a SOAP fault

Typically when Service Bus is mediating, you might have to transform Error or Fault response to the Fault structure defined in WSDL. For this, you need to understand Message Context Variables that can be used.

As per WS-I BP, the service provider should send the HTTP response code as 200 when the error is sent as normal response and 500 should be sent when the error is sent as SOAP fault.

In message flow, Error Handler can be defined for Stage node, Pipeline Pair node (both Request Pipeline and Response Pipeline individually), Routing node and for entire Pipeline (called Service Error Handler). When HTTP response code 200 is received, Service Bus treats it as a normal response and proceeds further with message flow. When response code 500 is received, Service Bus runtime control goes to Service Error Handler if it exists or any other low level Error Handlers depending on where you received. That means Service Bus treats even Fault response as normal response when HTTP response code is 200.

Service Bus populates different message context variables with error/fault messages and is accessible in Error Handler depending on whether you used Routing or Service Callout. The following table summarizes this discussion:

So there is a possibility of 3 context variables $body, $fault and $faultVar having Error or Fault information (assuming faultVar is variable used in Raise Error activity of your message flow).

With this background, let us get back to Pipeline Template to add required Error Handler. Since your Pipeline uses both Service Callout and Routing in message flow, you can do fault handling in the following manner in Pipeline Template so that all of your concrete pipelines using this template would inherit this automatically.

• Add Service Error Handler.
• Add conditional branches in error handler to verify $body is populated with SOAP Fault, or faultVar or $fault is populated. Based on this, you have to extract Error Code and Error Message from $body, $faultVar and $fault variables.
• Populate $body variable with the Fault structure as defined in WSDL.

Changes in CustomerPipelineTemplate:

Drag If-Then activity into ErrorHandler stage from Flow Control and add 3 conditional branches (Else If branch) as shown below.

In Properties tab, set Condition for all branches in Expression Builder as shown below. Remember adding the namespace http://www.bea.com/wli/sb/stages/transform/config with con1 as alias in Namespaces.

Drag Replace activity from Message Processing into each of these branches and set properties as shown below.

Set expression in Expression Builder with following SOAP Fault structure for Replace activity in If branch. Here you are extracting Error Code and Error Message from received SOAP fault received in Routing. This way you are forwarding the actual error from Service Provider to Consumer.

<soap-env:Fault>

<faultcode>env:Server</faultcode>

<faultstring>{$body/soap-env:Fault/faultstring/text()}</faultstring>

<detail>

<cust:ErrorStatusMsg xmlns:cust="http://xmlns.xyzbank.com/schema/Customer"&gt;

<ErrorCode>{$body/soap-env:Fault/faultcode/text()}</ErrorCode>

<ErrorMsg>{$body/soap-env:Fault/faultstring/text()}</ErrorMsg>

</cust:ErrorStatusMsg>

</detail>

</soap-env:Fault>

Set expression in Expression Builder with following SOAP Fault structure for Replace activity in Else If branch. Here you are extracting Error Code and Error Message used in Raise Error activity. Observe the usage of $fault variable to get error code given in RaiseError activity. This way you are forwarding the error message used in Raise Error activity to Consumer.

<soap-env:Fault>

<faultcode>env:Server</faultcode>

<faultstring>{$faultVar/error_message/text()}</faultstring>

<detail>

<cust:ErrorStatusMsg xmlns:cust="http://xmlns.xyzbank.com/schema/Customer"&gt;

<ErrorCode>{$fault/ctx:errorCode/text()}</ErrorCode>

<ErrorMsg>{$faultVar/error_message/text()}</ErrorMsg>

</cust:ErrorStatusMsg>

</detail>

</soap-env:Fault>

Set expression in Expression Builder with following SOAP Fault structure for Replace activity in second Else If branch. Here you are extracting Error Code and Error Message from SOAP Fault received in Service Callout. This way you are forwarding actual error from Service Provider to Consumer.

<soap-env:Fault>

<faultcode>env:Server</faultcode>

<faultstring>{$fault/ctx:reason/text()}</faultstring>

<detail>

<cust:ErrorStatusMsg xmlns:cust="http://xmlns.xyzbank.com/schema/Customer"&gt;

<ErrorCode>{$fault/ctx:details/con1:ReceivedFaultDetail/con1:faultcode/text()}</ErrorCode>

<ErrorMsg>{$fault/ctx:details/con1:ReceivedFaultDetail/con1:faultstring/text()}</ErrorMsg>

</cust:ErrorStatusMsg>

</detail>

</soap-env:Fault>

Set expression in Expression Builder with following SOAP fault structure for Replace activity in Else branch. Here you are extracting Error Code and Error Message from $fault to take care of other possible error scenarios.

<soap-env:Fault>

<faultcode>env:Server</faultcode>

<faultstring>{$fault/ctx:reason/text()}</faultstring>

<detail>

<cust:ErrorStatusMsg xmlns:cust="http://xmlns.xyzbank.com/schema/Customer"&gt;

<ErrorCode>{$fault/ctx:errorCode/text()}</ErrorCode>

<ErrorMsg>{$fault/ctx:reason/text()}</ErrorMsg>

</cust:ErrorStatusMsg>

</detail>

</soap-env:Fault>

Now drag Reply activity into ErrorHandler stage from Flow Control after If-then. In Properties tab, select property as With Failure. This would send HTTP response code as 500 along with SOAP fault. Selecting With Success will send HTTP response code as 200.

Alternatively, you can come up with a XQuery map accepting these parameters and return appropriate SOAP fault structure. Now your ErrorHandler stage should look like below.

Observe that the Proxy Service you created using this Pipeline Template in this post had inherited ErrorHandler stage as shown below.

Some times, you may want to give your specific messages or override the messages from Service Provider. You can make all this kind of changes in your Error Handler and also typically one would want to convert System Errors into generic Application Error before sending to Proxy Service consumer. You can find more about details element in $fault variable here.

Testing:

Run your Pipeline and observe Flow Trace and Variables as shown below. Observe that the Error response from your Pipeline always contains a SOAP Fault conforming to WSDL.

Following are a few of the screenshots showing different Fault responses for both Routing and Service Callout in different error scenarios.

System Error in Routing:

Error Response received in Routing:

Fault Response received in Routing:

Validate activity failure Error:

System Error received in Service Callout:

Error Response received in Service Callout:

Fault Response received in Service Callout:

Security is one of the main aspects while developing any service and is no different from our regular web applications. Also services are reusable and can be invoked by either internal or external customers, so you should consider securing your Service Bus Proxy Services so that only valid users can invoke.

Service Bus is completely integrated with Oracle Webservices Manager (OWSM) that provides several out of the box security policies. You can use any of these OWSM policies to secure your Proxy Services based on requirements. Here in this post, you will use oracle/wss_username_token_service_policy policy to secure Proxy Service.

As a first step, you need to create users who can invoke the service. Typically an Organization will have users in LDAP directory and you have to configure one of the Authenticators in Weblogic server to access LDAP for authentication purpose. This configuration will not be discussed here in this post.

Creating User:

Login to Admin Console and click Security Realms in Domain Structure.

Click myrealm as shown below.

Navigate to Users by clicking on Users and Groups tab.

Click New and enter credentials as shown below.

Click OK. Observe that new user has been created which  can be used to invoke Proxy Service.

Attaching OWSM Policy:

Open your Proxy Service. Navigate to Policies tab and select option as shown below.

Click + icon in Security section and select policy oracle/wss_username_token_service_policy.

Click OK and observe that selected policy is shown up in Security section.

You can also attach OWSM policies to Proxy Service in sbconsole. Launch sbconsole and create a new session. Navigate to All Projects –> <<your project>> and open the Proxy service to bring up a new tab as shown below.

Click Security and choose the option as shown below.

Click Attach Policies icon (highlighted above) and select the policy as shown below and click Attach.

Click OK and observe that selected policy is shown up as shown below.

Save your changes in current tab and activate the session.

Testing

You can use SOAP UI for testing. Create a test suite in SOAP UI using your proxy service WSDL. Refer to http://soapui.org for any additional help.

Open request editor for any of your Proxy Service operations and paste the following in SOAP header. This represents the WS-Security header and is expected by OWSM policy i.e. attached to Proxy Service. You can observe username and password fields below.

<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"&gt;

<wsse:UsernameToken>

<wsse:Username>UNAME1</wsse:Username>

<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">Welcome1</wsse:Password&gt;

</wsse:UsernameToken>

</wsse:Security>

Test using wrong credentials and observe the output showing security error.

Test using credentials created in previous section and observe the output.

In this post, you will learn to create and use XSL maps in message flow using the same Service Bus project used in previous posts.

And here we are creating XSLT map for Customer transformation. The Source WSDL CustomerPS.wsdl and Target WSDL CustomerService.wsdl  are available here and here respectively. Make sure that you have these WSDLs copied in your project before proceeding with XSL map creation.

Creating XSL map:

Right click XSLTs folder in XYZCustomer project and select New -> XSL Map and give File Name as CustomerPSToUpdateCustomer.

Click Browse for Primary Source to bring up Select Schema screen.

Retain default selection and click Browse to select the source element.

Click OK twice to go back to Create XSL Map screen. Now click Browse for Target to bring up Select Schema screen again. And click Browse for Select Schema and select the target element as shown below.

Click OK twice and observe Source and Target elements.

Click OK to finish that brings up XSLT Transformation editor as shown below.

Here we are planning to do update of Customer Information, so you should not send null values in payload to business service; hence Target elements should be mapped only when corresponding Source element is available.

You can achieve this behavior automatically in XSL Map editor by setting a preference. Go to Tools -> Preferences and set property as shown below.

Now go back to XSL Map editor and do the initial mapping as shown below by connecting respective Source and Target elements. Observe that xsl:if condition gets added automatically when source element is defined as optional in schema.

Drag concat function into middle swim lane from Components-> General XPath -> String Functions to concatenate FirstName, Lastame and map to full_name. Also concatenate State, Country and ZipCode and map to addr_line4 as shown below.

Click concat functions and modify them to add  ‘,’ between elements as shown below.

Now go to Source and modify full_name and addr_line4 elements mapping to include xsl:if conditions so that Target will be mapped only when all of the  corresponding Source elements are present.

Testing XSL map:

It’s always advisable to test your XSL map to see whether mapping is working as expected. Click Test XSL Map icon in editor to bring up the following screen.

Click OK and observe that mapping is working as expected as shown below. You can also verify that both Source and Target xml files are generated. You can modify source xml and retest your XSL map again.

Using XSL map in Message Flow:

Drag Replace activity from Message Processing into message flow at place wherever you require transformation. In Properties tab, bring up expression editor for Value property and choose XSL map as shown below.

Click OK and give Input Document Expression as $body/*.

Set other properties as shown below. This action will replace the contents of $body context variable with transformed payload.

In this post, you will learn to create and use XQuery maps in message flow using the same Service Bus project used in previous posts.

And here we are creating XQuery map for Address transformation. The Source WSDL CustomerPS.wsdl and Target WSDL AddrValidationService.wsdl  are available here and here respectively. Make sure that you have these WSDLs copied in your project before proceeding with XQuery map creation.

Creating XQuery map:

Right click XQueries folder in XYZCustomer project and select New -> XQuery File ver1.0 to create new XQuery. Give both file and function name as AddrToAddrBSInput as shown below.

Click + icon to add Source parameter and give name as inputAddr.

Click pencil icon for Sequence Type to bring up Function Parameter Type window. Click browse icon and select Customer element in CustomerPS.wsdl as shown below. Here Customer element has address fields.

Click OK and retain default values for all the other properties in Function Parameter Type window as shown below.

Go back to Create XQuery Map window by clicking OK twice. Now click pencil icon for Target to bring up Function Result Type window. Click browse icon and select addrval_input element as shown below. Observe that the WSDL being used is AddrValidationService.wsdl.

Click OK thrice to bring up the Transformation editor and also do the initial mapping of attributes as shown below. You can map the fields by connecting Source and Target elements directly.

Drag concat function from Components -> XQuery Functions -> String Functions into Mappings swim lane. Connect Address2 and Address3 input elements to this function as shown below, as Target element expects concatenation of all address lines.

Address Validation service expects address lines with ‘,’ as delimiter, so go to XQuery Source tab and modify concat function as shown below.

Testing XQuery map:

It’s always advisable to test your XQuery to verify that mapping is working as expected. So right click XQuery file in XYZCustomer project and select Run XQuery.

Click List of variables button (highlighted above) to bring Edit Variable screen and select options as shown below.  This will generate the sample inputs automatically.

Click save icon and give file name as SampleCustomerInput.xml and click Add to Sequence.

Click OK and go back to Run XQuery screen. Give Target file name as AddrServiceInput by clicking Save icon.

Click Run and verify output of XQuery map to see mapping is working as you expected. You can observe that all address elements in Source concatenated and assigned to single element address_line in Target. You can also verify sample Source and Target files created in your XQueries folder.

Using XQuery map:

Drag Assign activity into Service Callout from Message Processing or place it at any other place in your Message Flow depending on where you want to use this transformation.

In Properties tab, select XQuery Resources for Value property.

In Expression Builder, click Browse icon and select the XQuery mapping.

Click OK. Use the following steps to set value for Binding property.

Click OK twice and set addrReqBody as the value for Variable property. This variable will contain the transformed value of address and can be used in your message flow later.

In this post, you will learn to use Domain Value Maps (DVM) in message flow.

We consider the business requirement of performing Address Validation in message flow based on a configurable property and we use DVM to store this Configurable Property.

Creating Domain Value Map (DVM)

Create a new folder named DVM in XYZCustomer project. Right click DVM folder and select New -> Domain Value Map.

Give Config as File Name and give DVM entries as shown below. The domain name PropertyName represents Configurable Properties and the domain PropertyValue represents configurable property values respectively.

Using this DVM, you can extend the same logic to any number of configurable properties in your Service Bus Application. For our requirement, give property name as ValidateAddress and set it’s initial value as Y.

Click OK to bring up DVM editor.

You can use JDeveloper to modify DVM or you can also modify it in sbconsole. Remember you need to create a session before modifying anything.

Using DVM in Message Flow

Drag Stage node into Stages placeholder of Request Pipeline and set name as AddrValidation in Properties tab.

Drag Assign activity into AddrValidation stage from Message Processing. Bring up expression builder for Value property and give expression as shown below. Alternatively you can select the function from Functions -> Custom XPath Functions -> Dvm functions. Make sure that you give complete qualified path of DVM containing Service Bus Project name too.

Set Variable property as ConfigVar. Now your Properties tab should look like below.

Address Validation business service should be invoked only when the value of this configuration property ‘Y’. So drag If Then activity into AddrValidation stage after Assign from Flow Control and set condition as $ConfigVar=’Y’.

Service Bus provides Service Callout, Routing and Publish activities to route incoming request to an appropriate business service. Routing and Service Callout are used for Synchronous where as Publish activity is used for one-way communication.

Routing node always depicts end of message flow so you can’t place any activities after Routing node. Hence use Service Callout for all intermediate service calls in pipeline. Drag Service Callout from Communication into If Then branch as shown below.

In Properties tab, browse and select AddrValidationServiceBS for Service property.

In this post, you will learn to create Pipeline and expose it as Proxy Service using Pipeline Template created in previous post.

You need a WSDL to be used in Proxy Service and you can get the one used in this post from here. You can copy WSDL into any of your Service Bus project directory in file system directly. And click Refresh in Project Explorer so that these resources will be shown. We will use the following Projects.

Right click Pipelines folder and select New -> Pipeline.

Give name as CustomerPSPipeline and select the option From Template as shown below.

Click Search icon to bring up Resource Chooser and select Pipeline Template.

Click OK to go back to Create Pipeline Service window and click Next.

Click Browse WSDLs icon (highlighted above) and select CustomerPS.wsdl from XYZCustomer project as shown below and click OK.

Verify that WSDL and binding is selected. Click Search icon for Proxy Location and select ProxyServices folder as shown below.

Click Select and modify Proxy Name to CustomerPS. Now your Create Pipeline Service window should look like below.

Click Finish. Verify both Pipeline and Proxy Service are created in Pipelines and ProxyServices folders respectively as shown in Project Explorer.

Observe that new tab is opened showing CustomerPSPipeline had inherited all placeholders, names and properties from your Pipeline Template. You can modify/add activities in placeholders and the properties of inherited activities. Since a few of the properties to be specified mandatorily in concrete pipelines and are not mentioned in template, you will see red marks (see below) both in Project Explorer and editor.

Open CustomerPS and navigate to Transport configuration as shown below. Modify Endpoint URI as /entity/CustomerService. So your service consumers can access your proxy service using following URL:

http://<host>:<port>/entity/CustomerService

Go to Message Handling tab and select SOAPAction Header as Selection Algorithm. This would enable proxy service to determine operation at runtime based on SOAP Action sent in HTTP header. These changes should resolve errors in Proxy Service and you can observe that red marks are not seen now.

To resolve errors in Pipeline you should set the properties of Validate activity. In Properties tab of Validate activity, for Schema property click Search icon and select Customer element from proxy service WSDL as shown below. This would enable Service Bus validate input payload against the selected schema at runtime.

For Location property, bring up expression editor by clicking icon. Drag or shuttle Customer element into Expression field as shown below and click OK. Now you can observe that all red marks are gone for Pipeline as well.

Now your properties tab for Validate activity should look like below.

Now your Service Bus Overview Editor should look like below.

In this post, you will learn how to create Pipeline Templates in Service Bus 12c.

A Pipeline Template defines general shape or pattern of your message flow. We use Service Bus project XYZCustomer shown below for the demonstration purpose and we intended to create proxy service performing CRUD operations on objects like Customer.

Note: You can create new folders by navigating to File -> New -> From Gallery -> General -> Folder.

Right click Pipelines folder and select New -> Pipeline Template.

Give a meaningful name. Here we are using name CustomerPipelineTemplate.

Click Next. In this screen, you can choose service type depending on your requirement. Here we want to create WSDL based proxy service, so choose Service Type as WSDL SOAP as shown below.

Click Finish and verify that new Pipeline Template is created and opened in a separate tab as shown below.

Pipeline templates are the right candidates to keep common logic or enforce pattern of message flow to be followed across Proxy services. Typically, you may want to perform following common activities for different operations that your Proxy Service supports.

• Validation of payload against schema
• Routing to a business service (e.g: CustomerServiceBS)
• Error Handling

Along with above functionality, your Pipeline Template needs to have nodes like Operational branch, Pipeline Pair, Stages etc…

When consumers call Proxy Service, it has to take different execution paths based on operation called. The Service Bus provides Operational Branch node serving this purpose. So drag Operational from Template Placeholders onto pipeline template where yellow circle is shown.

Note: All Nodes or activities used in message flow for Pipeline or Pipeline template are available in Components -> Message Flow under different sections. If you don’t see Components window, get it by selecting Window -> Components.

Click BranchNode1 and set name as CustomerOperation in Properties tab as shown below. As a best practice, always give meaningful labels for Nodes and other activities (wherever applicable).

Now drag Pipeline Pair from Nodes into Branch and give name as PipelinePair and rename Stage1 node in Request Pipeline to Validation in Properties tab.  Now your pipeline template should look like below.

Service Bus provides Validate activity to do payload validation against schema. So drag Validate activity into Validation stage from Message Processing.

In Properties tab, set Location property value as body and other properties as shown below. Here you will not select any schema or WSDL for validate activity as it’s just template and we will not have any payload available.

There may be additional validations to be performed while designing message flow in concrete Pipelines which requires a place holder. So drag Actions into Validation stage as shown below from Template Placeholders.

Delete Stage1 in Response Pipeline by selecting Delete option on right click. Also you may need to create several Stage nodes in your concrete Pipeline’s message flow. So create a place holder for the same in your template. Drag Stages into pipeline after Validation stage and in Response Pipeline from Template Placeholders. Now your pipeline pair node should look like below.

Routing node always depicts end of your message flow and you will not be able to place any other activities after this node. So drag and place Route after PipelinePair from Template Placeholders and set name as Route in Properties tab. Observe Actions placeholder which allows user to place any type of activity while designing message flow for your concrete pipelines.

Error handling is another aspect of message flow where you may want to follow similar approach for all Proxy Services. So drag Error Handler onto CustomerPipelineTemplate from Nodes. And in Properties tab, set name as ErrorHandler for Stage1 as shown below.

We will see Error Handling in detail in separate post. For the time being, you can drag Actions placeholder into ErrorHandler stage.

With this, you are done with Pipeline Template and can proceed with creation of Pipelines using this template.

During development, you may often deploy and test your Business and Proxy services to verify that you are able to send request and receive response as expected. And typically, if the service provider is external to your organization, you have to configure your business service to use HTTP proxy server.

Note: HTTP Proxy Server is a global resource to be created in Service Bus Application and can be attached to business service in Advanced Settings of Transport Details tab.

In Service Bus 12c, you can use either Integrated or Standalone WLS to test business/proxy services.

Integrated WLS:

Right click business/proxy service and select Run.

If Default Domain does not exist, JDeveloper will prompt for credentials to create Integrated WLS. Enter credentials click OK to start server.

Once the server starts, Test Console is opened as shown below. This Test Console shows all available operations (If it’s based on WSDL), Request Document section (to enter payload), Transport section (to enter transport headers) and Attachments section.

Click Execute and observe that you are able to send request and receive response as shown below. You can use Back to modify payload and repeat your test scenarios.

Standalone WLS:

You can also deploy your service bus project to standalone WLS from JDeveloper and test from sbconsole. Right click XYZCommon project and choose Deploy as shown below.

Finish deployment using steps shown below.

Once deployment is done, login to sbconsole using http://host:port/sbconsole. Clicking arrow icon (highlighted below) will bring up the same Test Console shown earlier.

Another option is exporting your projects as Configuration Jar and deploy to either Integrated or Standalone WLS. To do this, right click XYZCommon project and select Export as shown below.

Select Service Bus Resources option as shown below.

Select Configuration Jar as destination.

Click Next. Give Jar file name including file system path as shown below and click Finish.

Open sbconsle. Create new session by clicking Create to import configuration jar.

Click Import icon in Resources tab.

Select configuration jar using Choose File button as show below.

Click Next. Accept defaults and click Import.

Click Close on confirmation screen and verify new project is shown as below in Resources tab.

Click Activate and confirm the session so that your changes will be effective.

Similarly, you can export service bus project directly to server by choosing Server as shown below in Export Service Bus Resources window shown earlier.

Click Next and choose Destination Server as shown below.

Click Next. Accept defaults and click Finish. Once export is successful, you can launch sbconsole and test your business and proxy services as shown above.

Note: Developer can choose any of the above options for deploying and testing business/proxy services.

In Service Bus, Business Services provide abstraction layer and take care of communication with Service Providers. In this post, you will see different ways of creating Business Service in Service Bus project using JDeveloper based on a WSDL. And for the demonstration purpose, we will consider the Service Bus project and WSDLs shown below.

Method 1:

Right click Service Bus project and select New -> Business Service.

Give a meaningful name for Business Service as shown below.

Click Browse WSDLs icon (shown above) and choose CustomerService WSDL as shown below.

Click OK to go back to Create Business Service wizard.

Method 2:

Open the Service Bus overview file (file with same name as your project) and drag HTTP adapter into from Components –> Service Bus –> Technology –> HTTP into External Services swim lane to bring up Create Business Service wizard as shown below.

Give meaningful name for Business Service and click Next. Select the option WSDL and choose WSDL as shown in previous method by clicking Browse WSDLs icon.

Method 3:

Right click WSDL in Service Bus project and select Service Bus –> Generate Business Service as shown below.

Verify that Create Business Service wizard has come up showing WSDL and binding selected.

And the following steps are common irrespective of the above methods you choose to create Business Service.

Click Next and enter Endpoint URI of the service.

Click Finish to bring up a new tab showing CustomerServiceBS.bix.