(2/2) Using the MetaData Services (MDS) in a SOA environment

It has been almost a year since my last post about the metadata services. I talked about how-to set up a File-based MDS and DB-based MDS. This post talks about the usage of the files, placed in the MDS, in the different components available in a SOA composite. If the MDS is a new thing for you then I advise to read my previous about this subject first.

You can spot the presence of a file that is a reference to the MDS if it uses the oramds: URI annotation. Files are no longer referenced to a hardcoded or relative file path.

To start using you’re MDS that you have set up we will create a new SOA application. Let call the application WorkflowSOAapp and create a SOA project and call it WebformService.

In the last step of configuration select the Empty Composite template. I always prefer to start with a clean composite.

Use MDS resources for exposed services

After creating the new SOA project it will open the composite editor automatically. Exposed services are always created in the left swim lane. Because this project deals with a WSDL resource to expose a webservice, a Web Service component is first dragged to the left swim lane.

A dialog “Create Web Service” will open. Give the service a good name, preferred the same as the name in the WSDL (e.g. WebFormService). The next thing to do is to choose the WSDL URL. Click on the document icon at the right side of the WSDL URL input to find an existing WSDL.

A second dialog “SOA Resource Browser” opens, click on the dropdown list at the top and select Resource Palette instead of File System. The interface of the dialog will change to represent the same view as in our main window of JDeveloper. Expand the tree multiple times and drill down to your local MDS connection.

Expand the tree futher and open up WebFormEOL -> WSDL and select webformService.wsdl.

The second WSDL is a implementation WSDL which is used when the webservice is called as a external service and contains binding and service information. Which we don’t need when we create our own service, because deployment will create a implementation WSDL.

Click OK to choose this WSDL file and you will be back at the “Create Web Service” dialog. Take a look at the start of your new WSDL URL input, it’s now starts with oramds: protocol. Click OK to create the service component.

Note: DON’T check the box in front of the copy wsdl option. We use the MDS so we don’t need a local version in our project.

Use MDS resources in a Mediator

Drag a Mediator component to the components area of the composite.xml and create a new mediator and select to define the service later. Give it a good name (e.g. WebformMediator). Then drag a wire from the web service component in the left lane to the mediator to connect them.

Double-click on the mediator component to open the CustomerMediator.mplan, the editor for modifying a mediator, and notice that the WSDL URL references to the one in the MDS we selected when creating the web service adapter.

Also all the operations are added under the Routing Rules, but that is not different then selecting it as a local reference.

Use MDS resources in a BPEL Process

Drag a BPEL Process component to the components area of the composite.xml and create a new BPEL process. In the “Create BPEL Process” dialog choose the BPEL 2.0 specification if it’s available (11gR1 PS3+). I’m using the 2.0 spec, because it uses the reference specification at default, without any oracle extensions and thus easily ported to JBPM or Apache ODE.

Give the BPEL process a good name, I usually give it the name of the operation in CamelCase. For this example I’m going to make a BPEL process that implements the RegisterForm operation, so I will give it the same name. For this example you can leave the namespace at the default value, but in real-life I usually incorporate the company name and project name in the namespace. Choose for the template option “Base on a WSDL”, set the value for service name and give it a similar name as the WSDL. Important is that we don’t expose it as a SOAP service. Just like with the Web Service adapter select the WSDL from the local MDS connection in the resource palette. It should look something like this:

Besides the creation of the .bpel and .componentType file, there is a new WSDL wrapper file. BPEL creates this, because BPEL uses partnerlinks and a wsdl file at default doesn’t have one. The best practices is not to add a partnerlink to the original WSDL file. Most of the time you will reference an external WSDL which will not contain a partnerlink and wrapper files are then automatically created. A wrapper file is not placed in the MDS, because it is a project resource and not reused very much. Another reason is that a BPEL component doesn’t handle wrapper WSDLs very well if they are referenced from a MDS.

Wire the mediator with the BPEL process. If a WSDL has multiple operations a dialog “Choose Operation” is shown.
For this example link the same operation name RegisterForm.

Incorporate Domain Value Map as a MDS resource

A Domain Value Map or DVM is like a simple database table used for lookup lists or single entities. A DVM can be used to store for example a list of companies, formtypes or error messages. There can be a relationship between the data in various DVMs, but they stand on their own and have no knowledge of each other.

A DVM can be used in various levels of a SOA composite. A DVM can be used/accessed in a BPEL component or in a XSLT transformation file. In BPEL there is a XPATH function which can be used directly in the assign activity or when using the DVM in a XSLT it can be used in the transformation activity. The XSLT transformation file can also be used in a Mediator.

I have made a little scenario for this. The XSD types that the BPEL process is using have a few message details which one of these is a casetype. The use of a casetype is not allowed for every user that calls the service. So the first thing the process checks is if the requesting user is allowed to send a message revolving the given casetype. The DVM has three domain columns; company, casetype and allowed which has a true/false value.

Using the DVM, referenced from the MDS, in BPEL

First we are going to look at the direct usage in the assign activity. Open up the BPEL process that was just created, via the project browser, and drag a assign activity from the right and place it between the receiveInput and replyOutput activities. Don’t forget to give the assign activity a name that suits the lookup check (e.g. lookUpCasetypeIsAllowed).

The value from the DVM needs to be saved in a variable, so before accessing the DVM we need to create a local variable. Click on the button of the main scope and create a variable for the result of the lookup. For this case it would be of type xsd:boolean.

Also two more variables of type xsd:string, which will contain the company name and actual casetype from the input, and give them appropriate names (e.g. company & casetype). The XPATH function we’re going to use works more reliable if the input element is a string.

Double-click on the assign activity to edit the assign and add copy rules. To access a DVM there are XPATH functions that can be used.
• The first rule maps $inputVariable.payload/ns3:intakeDetails/ns3:casetype to the local variable $casetype.
• The second rule maps $inputVariable.payload/ns3:messageDetails/ns3:sender/ns3:organisation to the local variable $company.
• For the third rule we’re dragging the expression icon onto the output variable which will contain the result of the DVM lookup (e.g. ).

After dragging the expression icon on the output variable a window “Expression Builder” is opened. Under functions select DVM Functions in the dropdown list and you will see to lookup functions listed. For this example I’m (only) using the lookupValue function. Click on the function name and click on the Insert Into Expression button.

You will notice that only the expression being build is any empty function of dvm:lookupValue() but what are the parameters when we are using a DVM which is referenced from the MDS? For this to answer we need to know how the lookup works and how a ORAMDS: URI looks like.

First we look at the usage format of the lookupValue() function:

dvm:lookupValue(dvmLocation as string, sourceColumnName as string, sourceValue as string, targetColumnName as string, defaultValue as string, (qualifierColumnName as String, qualifierValue as string)*))

The one field interested here is the dvmLocation which needs to be a reference to the MDS. MDS resources are accessed by the ORAMDS:/ protocol and after that the location of the file. The root of the MDS is the seed which is configured in adf-config.xml. In our case the used DVM (e.g. AllowedCompanyCasetypes) is located in the apps/WebFormEOL/DVM/ folder. But also we need to use an extra qualifier column, because we have two input fields to check.

The final expression will select the value of column allowed and uses the company and casetype column to find a match:

dvm:lookupValue("oramds:/apps/WebFormEOL/DVM/AllowedCompanyCasetypes.dvm", "company", $company, "allowed", "false", "casetype", $casetype)

Because we use a boolean we need to wrap the dvm:lookupValue function into a boolean expressions by comparing the output to the string “true”.

boolean(dvm:lookupValue("oramds:/apps/WebFormEOL/DVM/AllowedCompanyCasetypes.dvm", "company", $company, "allowed", "false", "casetype", $casetype) = "true")

At this point we have the copy rules setup:

After the DVM lookup we can create a validation step to check if the condition is true, else we can throw an error.

Using the DVM, referenced from the MDS, in a XSLT

Sometimes a domain variable can have a different meaning in the destination system then in the source system, because of a different business jargon. A DVM can then be used to transform the domain value from one to another type. The XSLT can then be used in the transformation activity within a BPEL process or use the XSLT in the Mediator.

Setting up a DVM lookup in a XSLT transformation file is much easier, because of the simplified UI. First drag the transformation activity into the BPEL process and double-click on the new activity. For a simple transformation, create one between the input and output variable. When creating a new transformation file the editor will automatically open.

Same as in BPEL you can use the DVM functions to access the data in a DVM. In the Component Palette, usually at the right, select the Advanced Functions from the dropdown list and expand the DVM Functions tab. Here you will find the same function, lookupValue, as used in BPEL.

Drag this function to the middle part of the transformation editor and double-click on the icon that appears. The Edit Function dialog opens where you can select the dvmLocation by looking it up via the resource palette showed earlier in this article.

In this dialog you also select all the fields that make up the lookupValue function like the sourceColumnName, sourceValue and targetColumnName. The first and latter one can be looked up via the search icon. And if you need qualifier columns just click on the ADD button.

This concludes this article. As you see there are a lot of places the MDS resources can be used like in a Mediator, BPEL or transformations. If you have changes to one the these type of files, you don’t want to change it in every component it uses, but just on one place and that is why we use the MDS.

p.s. one resource that I did not preview here is the EDN event configuration file, but this works also with the resource palette and is self-explanatory if you have read this article.

References

¹ Download the sources here, including deploy scripts.
 

---