Oracle SOA Suite (and Oracle BPM Suite) includes a component called ‘Metadata Services’ or ‘MDS’ which is a good practice to use as the repository for all of your common components that are used across multiple processes and integration artifacts. One excellent example of such a component is the XML Schemas (XSDs) that define your canonical data model. This article shows the process to create and deploy XSDs to MDS.
Our XSD defines and holds information of a Customer. What is a Customer? What attributes and information can describe a Customer in a particular organization? These are types of questions organizations start exploring when defining their canonical layer. Usually this data is already known and stored somewhere, but not publically available, accepted and distributed. XSD could be built using existing structures, e.g. Database, Applications, etc. We build an XSD file from scratch in this example to demonstrate the concept.
This article was written using JDeveloper 22.214.171.124 running on Windows 2008 Server R2 and Oracle SOA Suite 126.96.36.199 running on Oracle Enterprise Linux 5. The same steps should work in earlier 11.x.x.x versions, however there may be some slight differences in the appearance of some windows.
To start, we create a new application in JDeveloper by selecting Application from the New menu. In the New Gallery, select Applications under General in the Categories section on the left, and select SOA Application on the right hand side. If you do not see this option, you may need to select the All Technologies tab at the top. Then press OK.
Enter a name for your application. I called mine CanonicalModel. Then click on Next.
Enter a name for the SOA project inside your new application. I gave mine the same name. Then click on Next.
On the Configure SOA settings page, keep the default, Empty Composite, and then click on Finish.
Your new application and project will open. Now, let’s create our canonical data model. For the purposes of this example, let’s just create a simple ‘customer’ object. Of course, in your environment, you will have a much more complete canonical data model!
Select New from the File menu. In the New Gallery select the All Technologies tab, and then select the XML category and XML Schema as shown below. Then click on OK.
Enter a name for your schema, I called mine customer.xsd. You should put it in the xsd directory of your project. Set the Target Namespace to something meaningful and provide a Prefix as shown. Then click on OK.
Now you need to create your XSD. JDeveloper provides a graphical edit for creating XSDs. For this example, I just created a simple XSD as shown below.
To use this same XSD, just copy the code below and paste it into the Source tab of the XSD editor. You can switch back and forward between the graphical and source views. Any updates you make in either view will be reflected in the other.
This example follows the ‘best practice’ approach of defining the data structures as types and then the main element, Customer, refers to that type.
<?xml version=”1.0″ encoding=”windows-1252″ ?>
<xsd:element name=”Customer” type=”cc:CustomerType”>
A sample element
<xsd:element name=”Version” type=”xsd:string”/>
<xsd:element name=”CustomerID” type=”xsd:string”/>
<xsd:element name=”Name” type=”xsd:string”/>
That completes our canonical model! Well, our simple example anyway.
Now we want to deploy that to our server so that everyone can see it and use it. To do this, we need to set up a deployment profile. Select Project Properties from the Application menu. Then select Deployment in the navigation tree on the left. You will see one already there. Click on the New… button to add another deployment profile.
In the Create Deployment Profile dialog, select Jar File as the Archive Type and then enter a name for your deployment profile. I called mine Metadata. Then click on OK.
In the dialog box, select Jar Options on the left. Deselect (uncheck) the Include Manifest File option.
Move to the Contributors section as shown below. Unselect all of the options and then click on the Add… button.
In the Add Contributor dialog, click on the Browse… button.
Navigate to your project directory. The directory that you choose here will determine the path name that appears in MDS. If you have a large set of canonical data, you may want to use additional folders to provide some structure. Click on OK and then OK again.
Now select Filters on the left hand side. On the right hand side, deselect everything except for your XSD file(s), as shown below. Then click on OK.
Now we need to make a ‘SOA Bundle’ containing this deployment profile we just created. The SOA Bundle is the thing we will actually deploy to the server. It will contain the jar file with our XSDs in it.
Select Application Properties from the Application menu. Navigate to the Deployment section on the left, and then click on the New… button. In the Create Deployment Profile dialog, select SOA Bundle as the Archive Type and enter a name. I called mine CanonicalModelBundle. Then click on OK.
In the SOA Bundle Deployment Profile Properties dialog, open the Dependencies section and select both of the Java EE Modules as shown below. Then click on OK.
Now we can deploy our canonical data model to MDS. Select your deployment profile from the Deploy submenu under Application as shown below.
The deployment wizard will appear. On the first page, select Deploy to Application Server and click on Next.
You can accept the defaults on the Deploy Configuration page. Click on Next.
Select your server, then click on Next. If you have not deployed to your server before, you will need to create a connection first. You can do that by clicking on the green plus icon in the top right corner of this page – you don’t have to leave the deployment wizard.
Select the correct managed server and SOA partition to deploy to. If you don’t know which one to use, you should probably take the default. Then click on Next.
Review the information on the Summary page and then click on Finish to start the deployment.
You can review the progress of the deployment by watching the Deployment tab at the bottom of the screen. If you cannot see it, you can open it from the View menu. You should see a deployment log something like this:
[02:51:22 PM] —- Deployment started. —-
[02:51:22 PM] Target platform is (Weblogic 10.3).
[02:51:22 PM] Running dependency analysis…
[02:51:22 PM] Building…
[02:51:29 PM] Deploying 3 profiles…
[02:51:29 PM] Wrote Archive Module to C:\JDeveloper\mywork\CanonicalModel\CanonicalModel\deploy\Metadata.jar
[02:51:29 PM] Updating revision id for the SOA Project ‘CanonicalModel.jpr’ to ‘1.0’..
[02:51:29 PM] Wrote Archive Module to C:\JDeveloper\mywork\CanonicalModel\CanonicalModel\deploy\sca_CanonicalModel_rev1.0.jar
[02:51:29 PM] Wrote Archive Module to C:\JDeveloper\mywork\CanonicalModel\deploy\CanonicalModelBundle.zip
[02:51:29 PM] Deploying CanonicalModelBundle.zip to partition “default” on server soa_server1 [http://ofm1.au.oracle.com:8001]
[02:51:29 PM] Processing sar=/C:/JDeveloper/mywork/CanonicalModel/deploy/CanonicalModelBundle.zip
[02:51:29 PM] Processing zip file – C:\JDeveloper\mywork\CanonicalModel\deploy\CanonicalModelBundle.zip
[02:51:29 PM] Adding shared data file – C:\Users\ADMINI~1\AppData\Local\Temp\deploy_client_1295495489829\Metadata.jar
[02:51:29 PM] Adding sar file – C:\Users\ADMINI~1\AppData\Local\Temp\deploy_client_1295495489829\sca_CanonicalModel_rev1.0.jar
[02:51:29 PM] Preparing to send HTTP request for deployment
[02:51:29 PM] Creating HTTP connection to host:ofm1.au.oracle.com, port:8001
[02:51:29 PM] Sending internal deployment descriptor
[02:51:29 PM] Sending archive – sca_CanonicalModel_rev1.0.jar
[02:51:29 PM] Sending archive – Metadata.jar
[02:51:30 PM] Received HTTP response from the server, response code=200
[02:51:30 PM] Successfully deployed archive CanonicalModelBundle.zip to partition “default” on server soa_server1 [http://ofm1.au.oracle.com:8001]
[02:51:30 PM] Elapsed time for deployment: 8 seconds
[02:51:30 PM] —- Deployment finished. —-
That completes our deployment. Our canonical data model is now available on the server and everyone will be able to use it.
Let’s take a look at how a developer can view the data model. To do this, you need to create a connection to the MDS from JDeveloper. Select New from the File menu. Select Connections on the left and SOA-MDS-Connection on the right, as shown below. Then press OK.
In the Create SOA-MDS Connection dialog, enter a name for your connection, I called mine ofm1MDS. Select DB Based MDS as the Connection Type. You will always use a database based MDS in your server environment. Then select which database connection to use. You probably wont have one set up yet, so click on the green plus icon to create one.
You need to enter the database connection details and give your connection a name, as shown below. Once you have entered all the details, press the Test Connection button to check you have everything correct. When you see the Success! message, click on OK to continue.
Select the connection you just created and then select the correct MDS partition to use. If you don’t know which one to use, choose soa-infra. Click on the Test Connection button to check you have everything correct. When you see the Success! message, click on OK to continue.
Now you will be able to browse the MDS and view the artifacts in there. You do this in the Resource Pallette. If you don’t see it, you can open it from the View menu. The diagram below shows our customer object in MDS.
Developers could now easily access and use the canonical data model from MDS. Doing so will ensure that everyone is using the same versions of you data definitions and dramatically reduce testing and maintenance effort. Enjoy!