Home > Tutorial

Add UI Services for Import/Export

In this chapter we will tackle the connectivity problem, allowing any back-end system to interact with webMethods MDM, like an existing database for instance.

What is important to notice is that webMethods MDM provides all necessary features to connect through its API and exchange standard XML format files. However, in the data integration process, you will probably need to apply specific transformations to your Master Data.

Learn MoreImport and export tasks can be defined as Services under webMethods MDM. Each service is declared in the schema and can be used interactively by the user (Advanced tab webMethods Master Data Manager).

Let us walk through these core functionalities.

Master Data Import

The first step is to define the service in the schema:

< xs:complexType  name="Import">
    <xs:annotation>
        <xs:appinfo>
            <mdm:service resourcePath="/importXML/importXML.jsp"/>
        </xs:appinfo>
    </xs:annotation >
</xs:complexType >

The service is declared with an mdm:service element under the xs:annotation/xs:appinfo element of a complex type. It accepts resourcePath as an attribute to specify the directory in the module where the code lies.

Note that, for this example, the directory importXML/ is located at the same level than the WEB-INF/ directory.

Now the service is defined, webMethods Master Data Manager now handles the service:

The last thing to do is then to implement the code:

JavaDocAll the core import logic is in the com.softwareag.mdm.service.Procedure class.

To create an import service, we have to define a procedure instance and override its execute method as shown in the following code snippet (see the description of file "runImportXML.jsp" therafter):

import com.softwareag.mdm.service.*;

...

final ImportSpec is =  new ImportSpec();
is.setSourceFile(xmlSource);          // xmlSource is the File handler to import from
is.setTargetAdaptation(adaptation);      // adaptation is the current Adaptation instance


// Define the procedure
Procedure proc = new Procedure()
{
public void execute(ProcedureContext aContext) throws Exception
    {
        aContext.doImport(is);
    }
};

JavaDocPlease refer to the API JavaDoc for more information.

Here we give the full implementation of an import done in JSP:

<%-- importXML.jsp --%> 

<%@ page language="java" contentType="text/html; charset=UTF-8"  pageEncoding="UTF-8"%> 
<%@ page import="com.softwareag.mdm.service.ServiceContext" %> 
<% 
ServiceContext sContext = ServiceContext.getServiceContext(request);  
%> 
<p class="title">XML Import</p> 

<form id="serviceExtensionForm" action="<%=sContext.getURLForIncludingResource("
/importXML/doImportXML.jsp")%>" method="post"> 

    XML file:  
    <input type="file" id="file" name="xmlSource" size="100" devices="files" accept="text/xml"/> 
    <p><input type="button" value="Start Import" onclick="executeServiceExtension();" 
class="on_button" onMouseOver="this.className='on_button_over'" onMouseOut="this.className='on_button'"></p> 
    <input type="hidden" id="xml" name="anXMLSource"  /> 
     
</form> 

<script> 
function executeServiceExtension() 
{ 
        document.getElementById("xml").value=document.getElementById("file").value; 

        var text = "Do you want to start the import ?"; 
        var confirmation = confirm(text); 
        if (confirmation) 
        { 
            document.getElementById("serviceExtensionForm").submit(); 
        } 
} 
</script> 

<%-- doImportXML.jsp --%>

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<%@ page import="com.softwareag.mdm.service.ServiceContext" %>
<%
    ServiceContext sContext = ServiceContext.getServiceContext(request);
    String anXMLSource=request.getParameter("anXMLSource");
%>
<p class="title">XML import in progress ...</p>

<%
    // Check document
    if(anXMLSource==null||anXMLSource.equals(""))
    {
        %>
        <p class=text><font color=red>You must specify an XML document !</font></p>
        <%
    }
    else
    {
        anXMLSource=anXMLSource.replaceAll("\\\\","/");
    %>
        <p align="center">
        <img src="/mdm-manager/www/common/images/onCommon/on_anim_wait.gif" 
width="110" height="30" border="0">
        </p>        
        <p class=text align="center">Import in progress ....</p>
        <p class=text align="center">... please wait</p>
        <iframe id="exportFrame" width="1" height="1" border=0 style="display: none;"></iframe>

<script>
        window.setTimeout("document.getElementById('exportFrame').src='<%=
sContext.getURLForIncludingResource("/importXML/runImportXML.jsp")%>&anXMLSource=<%=anXMLSource%>';", 500);
</script>    
    <%
    }
%>

<%-- runImportXML.jsp --%>  

<%@ page language="java" contentType="text/html; charset=UTF-8"  
    pageEncoding="UTF-8"%>  
<%@ page import="com.softwareag.mdm.service.ServiceContext"%>  
<%@ page import="java.io.*"%>  
<%@ page import="com.softwareag.mdm.service.*"%>  
<%@ page import="com.softwareag.mdm.adaptation.*"%>  

<%ServiceContext sContext = ServiceContext.getServiceContext(request);  
            final String anXMLSource = request.getParameter("anXMLSource");  
            final File xmlSource = new File(anXMLSource);  

            if (!xmlSource.exists())  
            {  
                request.getSession().setAttribute("EndingMsg", "End of XML import");  
                request.getSession().setAttribute(  
                    "ErrorMsg",  
                    "Filename specified [" + anXMLSource  
                        + "] does not exist or is not accessible !");  
            }  
            else  
            {  
                final Adaptation ada = sContext.getCurrentAdaptation();  
                final StringBuffer msg = new StringBuffer();  

                final ImportSpec is = new ImportSpec();  
                is.setSourceFile(xmlSource);  
                is.setTargetAdaptation(ada);  
                // Defines the procedure  
                Procedure proc = new Procedure()  
                {  
                    public void execute(ProcedureContext aContext) throws Exception  
                    {  
                        try  
                        {  
                            aContext.doImport(is);  
                            msg.append("File [" + anXMLSource  
                                + "] has been imported into adaptation [" + ada.toPublicReference()  
                                + "].");  
                        }  
                        catch (Exception e)  
                        {  
                            throw e;  
                        }  
                    }  
                };  

                // Requests the execution in the container and handles the result  
                ProcedureResult result = sContext.execute(proc);  
                String summary;  
                if (result.hasFailed())  
                {  
                    summary = "Exception: " + result.getException();  
                    request.getSession().setAttribute("ErrorMsg", summary);  
                }  
                else  
                {  
                    summary = "Execution successful: " + msg;  
                    request.getSession().setAttribute("InfoMsg", summary);  
                }  

                request.getSession().setAttribute("EndingMsg", "End of XML import");  
            }  
%>  
<br />  
<br />  

<script>window.parent.location.href="<%=sContext.getURLForIncludingResource("/displayMessage.jsp")%>"</script>  

<%-- displayMessage.jsp --%>


<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<%@ page import="com.softwareag.mdm.service.ServiceContext" %>
<%@ page import="com.softwareag.mdm.base.text.*" %>

<%

    ServiceContext sContext = ServiceContext.getServiceContext(request);
    String ErrorMsg=(String)request.getSession().getAttribute("ErrorMsg");
    String InfoMsg=(String)request.getSession().getAttribute("InfoMsg");
    String EndingMsg=(String)request.getSession().getAttribute("EndingMsg");
    
%>
<p class="title"><%=EndingMsg%></p>

<%


    UserMessage msg=null;

    if(ErrorMsg!=null)
        msg=UserMessage.createError(ErrorMsg);
    else
        msg=UserMessage.createInfo(InfoMsg);

    request.getSession().removeAttribute("EndingMsg");
    request.getSession().removeAttribute("InfoMsg");
    request.getSession().removeAttribute("ErrorMsg");
    
    sContext.addMessage(msg);
%>

<br/>
<br/>
<br/>

Note that files import.jsp, doImport.jsp and runImport.jsp are all located in the directory importXML/, whereas displayMessage.jsp file is located in the importXML/ parent directory. This means that displayMessage.jsp file is at the same level than the WEB-INF/ directory.

Please find below, an XML sample file to import. This file concerns, here, only the authors table. Note that this kind of file can concern several tables to be updated in the current adaptation. This file then provides information concerning the target tables to update with its new occurrences (values of tables nodes).

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <Authors>
        <au_id>84-8-776</au_id>
        <lastname>Valade</lastname>
        <firstname>Janet</firstname>
        <address/>
        <city/>
        <country/>
    </Authors>
    <Authors>
        <au_id>10-8-910</au_id>
        <lastname>Sempf</lastname>
        <firstname>Bill</firstname>
        <address/>
        <city/>
        <country/>
    </Authors>
</root>

And the corresponding result in webMethods Master Data Manager:

After the user populates the filename to import, the data are imported as shown below:

We can see that the two new authors to import are now part of the adaptation.

Master Data Export

The definition of a export service is as simple as the import described just above.
The only difference is in the execute method of the procedure:

import com.softwareag.mdm.service.*;

...

final ExportSpec es = new ExportSpec();
es.setDestinationFile(xmlSource);         // xmlSource is the File handler to export to
es.setSourceAdaptation(adaptation);         // adaptation is the current Adaptation instance


// Define the procedure
Procedure proc = new Procedure()
{
public void execute(ProcedureContext aContext) throws Exception
    {
        aContext.doExport(es);
    }
};

JavaDocPlease refer to the API JavaDoc for more information.

We now give the complete implementation of the export service in JSP:

<%-- exportXML.jsp --%> 

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%> 
<%@ page import="com.softwareag.mdm.service.ServiceContext" %> 
<% 
ServiceContext sContext = ServiceContext.getServiceContext(request); 
%> 
<p class="title">XML Export</p> 

<form id="serviceExtensionForm" action="<%=
sContext.getURLForIncludingResource("/exportXML/doExportXML.jsp")%>" method="post"> 

    XML file:  
    <input type="text" id="file" name="anXMLDest" size="80"/> 
    <p><input type="button" value="Start Export" onclick="executeServiceExtension();" 
class="on_button" onMouseOver="this.className='on_button_over'" onMouseOut="this.className='on_button'"></p> 
    <input type="hidden" id="xml" name="anXMLSource"  /> 
     
</form> 

<script> 
function executeServiceExtension() 
{ 
    document.getElementById("xml").value=document.getElementById("file").value; 

        var text = "Do you want to start the export ?"; 
        var confirmation = confirm(text); 
        if (confirmation) 
        { 
            document.getElementById("serviceExtensionForm").submit(); 
        } 
} 
</script> 

<%-- doExportXML.jsp --%>

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<%@ page import="com.softwareag.mdm.service.ServiceContext" %>

<%
    ServiceContext sContext = ServiceContext.getServiceContext(request);
    String anXMLDest=request.getParameter("anXMLDest");
%>
<p class="title">XML Export in progress ...</p>

<%
    // Check the document
    if(anXMLDest==null||anXMLDest.equals(""))
    {
        %>
        <p class=text><font color=red>You must specify an XML document !</font></p>
        <%
    }
    else
    {
        anXMLDest=anXMLDest.replaceAll("\\\\","/");
        %>
        <p align="center">
        <img src="/mdm-manager/www/common/images/onCommon/on_anim_wait.gif" width="110" 
height="30" border="0">
        </p>        
        <p class=text align="center">Export en cours ....</p>
        <p class=text align="center">... veuillez patienter</p>
        
        <iframe id="exportFrame" width="1" height="1" border=0 style="display: none;"></iframe>
        
<script>
    window.setTimeout("document.getElementById('exportFrame').src='<%=
sContext.getURLForIncludingResource("/exportXML/runExportXML.jsp")%>&anXMLDest=<%=anXMLDest%>';", 500);
</script>    
<%
    }
%>

<%-- runExportXML.jsp --%>

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<%@ page import="com.softwareag.mdm.service.ServiceContext" %>
<%@ page import="java.io.*" %>
<%@ page import="com.softwareag.mdm.service.*"%>
<%@ page import="com.softwareag.mdm.adaptation.*"%>

<%
        ServiceContext sContext = ServiceContext.getServiceContext(request);
        final String anXMLDest=request.getParameter("anXMLDest");
        final File xmlDest= new File(anXMLDest);

        final Adaptation ada = sContext.getCurrentAdaptation();
        final StringBuffer msg = new StringBuffer();

        final ExportSpec es = new ExportSpec();
        es.setDestinationFile(xmlDest);
        es.setSourceAdaptation(ada);

        // Defines the procedure
        Procedure proc = new Procedure()
        {
            public void execute(ProcedureContext aContext) throws Exception
            {
                aContext.doExport(es);
                msg.append("Adaptation ["+ ada.toPublicReference() + "] has been exported into 
file [" + xmlDest + "].");
            }
        };
        
        // Requests the execution in the container and handles the result
        ProcedureResult result = sContext.execute(proc);
        String summary;
        if (result.hasFailed())
        {
            summary = "Exception: " + result.getException();
            request.getSession().setAttribute("ErrorMsg",summary);
        }
        else
        {
            summary = "Execution successful: " + msg;
            request.getSession().setAttribute("InfoMsg",summary);
        }
        
        request.getSession().setAttribute("EndingMsg","End of XML export");                
        
%>

<script>window.parent.location.href="<%=sContext.getURLForIncludingResource("/displayMessage.jsp")%>"</script>

Note that, for this example, the directory exportXML/ is also located at the same level than the WEB-INF/ directory. Hence, the files export.jsp, doExport.jsp and runExport.jsp are all located in the directory exportXML/, whereas displayMessage.jsp file is located in the exportXML/ parent directory. This means that displayMessage.jsp file is at the same level than the WEB-INF/ directory (it is the same file for both import and export tasks).

And the corresponding result in webMethods Master Data Manager:

And the resulting export file:

<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:mdmd="urn:mdm-schemas:deployment_1.0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" mdmd:uuid="E7C68990-FB73-11DA-8ABB-001010101010" 
mdmd:lastModified="2006-06-22T15:38:42.671" mdmd:card="0">
    <Titles mdmd:uuid="E78DF9E0-0104-11DB-8B9C-001010101010" 
mdmd:lastModified="2006-06-22T15:18:31.718" mdmd:card="9">
        <title_id>A0001</title_id>
        <title>Java for Dummies</title>
        <type>Business &amp; Technology</type>
        <pub_id>4562</pub_id>
        <au_id>30-1-683</au_id>
        <unit_price>24.99</unit_price>
        <total_sales/>
        <pub_date>1996-06-27</pub_date>
        <front_picture>Book Publishers:ext-images:frontpages/Java for Dummies 3rd Edition.jpg
</front_picture>
    </Titles>
    <Titles mdmd:uuid="99147610-01F2-11DB-BF09-001010101010" 
mdmd:lastModified="2006-06-22T15:34:31.562" mdmd:card="9">
        <title_id>A0208</title_id>
        <title>Ajax for Dummies</title>
        <type>Business &amp; Technology</type>
        <pub_id>4562</pub_id>
        <au_id>24-1-865</au_id>
        <unit_price>29.99</unit_price>
        <total_sales/>
        <pub_date>2006-03-01</pub_date>
        <front_picture>Book Publishers:ext-images:frontpages/Ajax for Dummies.jpg</front_picture>
    </Titles>
    <Titles mdmd:uuid="B6066F30-01F2-11DB-BF09-001010101010" 
mdmd:lastModified="2006-06-22T15:27:00.781" mdmd:card="9">
        <title_id>A3024</title_id>
        <title>Eclipse for Dummies</title>
        <type>Business &amp; Technology</type>
        <pub_id>4562</pub_id>
        <au_id>75-2-770</au_id>
        <unit_price>24.99</unit_price>
        <total_sales/>
        <pub_date>2004-12-01</pub_date>
        <front_picture>Book Publishers:ext-images:frontpages/Eclipse for Dummies.jpg</front_picture>
    </Titles>
    <Titles mdmd:uuid="98E2E950-01F3-11DB-BF09-001010101010" 
mdmd:lastModified="2006-06-22T15:34:31.562" mdmd:card="9">
        <title_id>B5626</title_id>
        <title>HTML Black Book</title>
        <type>Business &amp; Technology</type>
        <pub_id>6421</pub_id>
        <au_id>24-1-865</au_id>
        <unit_price>59.99</unit_price>
        <total_sales/>
        <pub_date>2000-05-01</pub_date>
        <front_picture>Book Publishers:ext-images:frontpages/HTML Black Book.gif</front_picture>
    </Titles>
    <Publishers mdmd:uuid="CA95B7F0-01F0-11DB-BF09-001010101010" 
mdmd:lastModified="2006-06-22T15:16:47.921" mdmd:card="3">
        <pub_id>4562</pub_id>
        <name>IDG Books</name>
        <city/>
    </Publishers>
    <Publishers mdmd:uuid="A8B58270-01F3-11DB-BF09-001010101010" 
mdmd:lastModified="2006-06-22T15:34:31.562" mdmd:card="3">
        <pub_id>6421</pub_id>
        <name>Paraglyph</name>
        <city/>
    </Publishers>
    <Authors mdmd:uuid="40151B00-01F2-11DB-BF09-001010101010" 
mdmd:lastModified="2006-06-22T15:27:00.781" mdmd:card="6">
        <au_id>24-1-865</au_id>
        <lastname>Holzner</lastname>
        <firstname>Steve</firstname>
        <address/>
        <city/>
        <country/>
    </Authors>
    <Authors mdmd:uuid="611CD560-01F0-11DB-BF09-001010101010" 
mdmd:lastModified="2006-06-22T15:16:47.921" mdmd:card="6">
        <au_id>30-1-683</au_id>
        <lastname>Aaron E.</lastname>
        <firstname>Walsh</firstname>
        <address/>
        <city/>
        <country/>
    </Authors>
    <Authors mdmd:uuid="691440D0-01F2-11DB-BF09-001010101010" 
mdmd:lastModified="2006-06-22T15:27:00.781" mdmd:card="6">
        <au_id>75-2-770</au_id>
        <lastname>Burd</lastname>
        <firstname>Barry</firstname>
        <address/>
        <city/>
        <country/>
    </Authors>
    <Royalties mdmd:uuid="0B02AAB0-0105-11DB-8B9C-001010101010" 
mdmd:lastModified="2006-06-22T15:16:47.921" mdmd:card="3">
        < title_id>A0001</title_id>
        <lo_range>1</lo_range>
        <hi_range>4</hi_range>
        <royalty>2.4000000000000003552713678800500929355621337890625</royalty>
    </Royalties>
</root>

 

The final XML Schema for our Publications sample database is available here.

 

Next: Add Programmatic Service for Import >

 

Home > Tutorial