esb_deploy - Progress Sonic ESB Deployment Guide 8.5 - Product ...

® 

® 

PROGRESS® 

SONIC® 

Sonic ESB 

Deployment Guide

Progress® Sonic® ESB Deployment Guide 8.5 

© 2011 Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved. 

These materials and all Progress® software products are copyrighted and all rights are reserved by Progress 

Software Corporation. The information in these materials is subject to change without notice, and Progress 

Software Corporation assumes no responsibility for any errors that may appear therein. The references in these 

materials to specific platforms supported are subject to change. 

Actional, Apama, Artix, Business Empowerment, Business Making Progress, DataDirect (and design), DataDirect 

Connect, DataDirect Connect64, DataDirect Technologies, DataDirect XML Converters, DataDirect XQuery, 

DataXtend, Dynamic Routing Architecture, EdgeXtend, Empowerment Center, Fathom, Fuse Mediation Router, 

Fuse Message Broker, Fuse Services Framework, IntelliStream, IONA, Making Software Work Together, 

Mindreef, ObjectStore, OpenEdge, Orbix, PeerDirect, POSSENET, Powered by Progress, PowerTier, Progress, 

Progress DataXtend, Progress Dynamics, Progress Business Empowerment, Progress Empowerment Center, 

Progress Empowerment Program, Progress OpenEdge, Progress Profiles, Progress Results, Progress Software 

Business Making Progress, Progress Software Developers Network, Progress Sonic, ProVision, PS Select, 

Savvion, SequeLink, Shadow, SOAPscope, SOAPStation, Sonic, Sonic ESB, SonicMQ, Sonic Orchestration 

Server, SpeedScript, Stylus Studio, Technical Empowerment, WebSpeed, Xcalia (and design), and Your Software, 

Our Technology-Experience the Connection are registered trademarks of Progress Software Corporation or one of 

its affiliates or subsidiaries in the U.S. and/or other countries. AccelEvent, Apama Dashboard Studio, Apama Event 

Manager, Apama Event Modeler, Apama Event Store, Apama Risk Firewall, AppsAlive, AppServer, ASPen, ASPin-a-Box, 

BusinessEdge, Cache-Forward, CloudEdge, DataDirect Spy, DataDirect SupportLink, Fuse, FuseSource, 

Future Proof, GVAC, High Performance Integration, ObjectStore Inspector, ObjectStore Performance Expert, 

OpenAccess, Orbacus, Pantero, POSSE, ProDataSet, Progress Arcade, Progress CloudEdge, Progress Control 

Tower, Progress ESP Event Manager, Progress ESP Event Modeler, Progress Event Engine, Progress RFID, 

Progress RPM, PSE Pro, SectorAlliance, SeeThinkAct, Shadow z/Services, Shadow z/Direct, Shadow z/Events, 

Shadow z/Presentation, Shadow Studio, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, 

SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, 

SmartWindow, Sonic Business Integration Suite, Sonic Process Manager, Sonic Collaboration Server, Sonic 

Continuous Availability Architecture, Sonic Database Service, Sonic Workbench, Sonic XML Server, The Brains 

Behind BAM, WebClient, and Who Makes Progress are trademarks or service marks of Progress Software 

Corporation and/or its subsidiaries or affiliates in the U.S. and other countries. Java is a registered trademark of 

Oracle and/or its affiliates. Any other marks contained herein may be trademarks of their respective owners. 

Third Party Acknowledgements: 

Progress Sonic v8.5 incorporates Model Objects Framework v2.0 from ModelObjects Group. Such technology is 

subject to the following terms and conditions: The ModelObjects Group Software License, Version 1.0 - Copyright 

(c) 2000-2001 ModelObjects Group. All rights reserved. Redistribution and use in source and binary forms, with 

or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source 

code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions 

in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the 

documentation and/or other materials provided with the distribution. 3. The end-user documentation included with

the redistribution, if any, must include the following acknowledgement: "This product includes software developed 

by the ModelObjects Group (http://www.modelobjects.com)." Alternatively, this acknowledgement may appear in 

the software itself, if and wherever such third-party acknowledgements normally appear. 4. The name 

"ModelObjects" must not be used to endorse or promote products derived from this software without prior written 

permission. For written permission, please contact djacobs@modelobjects.com. 5. Products derived from this 

software may not be called "ModelObjects", nor may ModelObjects" appear in thier name, without prior written 

permission of the ModelObjects Group. THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR 

IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 

MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 

SHALL THE MODEL OBJECTS GROUP OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 

INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 

BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 

DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 

LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 

OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 

THE POSSIBILITY OF SUCH DAMAGE. 

Progress Sonic v8.5 incorporates OpenSAML Java Distribution v1.0.1. Such technology is subject to the following 

terms and conditions: The OpenSAML License, Version 1. Copyright (c) 2002 - University Corporation for 

Advanced Internet Development, Inc. All rights reserved. Redistribution and use in source and binary forms, with 

or without modification, are permitted provided that the following conditions are met: Redistributions of source 

code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in 

binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the 

documentation and/or other materials provided with the distribution, if any, must include the following 

acknowledgment: "This product includes software developed by the University Corporation for Advanced Internet 

Development (http://www.ucaid.edu)Internet2 Project. Alternately, this acknowledegement may appear in the 

software itself, if and wherever such third-party acknowledgments normally appear. Neither the name of 

OpenSAML nor the names of its contributors, nor Internet2, nor the University Corporation for Advanced Internet 

Development, Inc., nor UCAID may be used to endorse or promote products derived from this software without 

specific prior written permission. For written permission, please contact opensaml@opensaml.org. Products 

derived from this software may not be called OpenSAML, Internet2, UCAID, or the University Corporation for 

Advanced Internet Development, nor may OpenSAML appear in their name, without prior written permission of 

the University Corporation for Advanced Internet Development. THIS SOFTWARE IS PROVIDED BY THE 

COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND WITH ALL FAULTS. ANY EXPRESS OR 


MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE 

DISCLAIMED AND THE ENTIRE RISK OF SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, 

AND EFFORT IS WITH LICENSEE. IN NO EVENT SHALL THE COPYRIGHT OWNER, CONTRIBUTORS 

OR THE UNIVERSITY CORPORATION FOR ADVANCED INTERNET DEVELOPMENT, INC. BE LIABLE 

FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 

DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 

SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 

AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 

SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

Progress Sonic v8.5 incorporates BasicLogin.java, SimpleCallbackHandler.java, SimplePasswordUser.java, 

SampleLoginModule.java, SamplePrincipal.java from Sun Microsystems, Inc. These technologies are subject to 

the following terms and conditions: Copyright 2000-2002 Sun Microsystems, Inc. All Rights Reserved. 

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the 

following conditions are met: -Redistributions of source code must retain the above copyright notice, this list of 

conditions and the following disclaimer. -Redistribution in binary form must reproduce the above copyright notice, 

this list of conditions and the following disclaimer in the documentation and/or other materials provided with the 

distribution. Neither the name of Sun Microsystems, Inc. or the names of contributors may be used to endorse or 

promote products derived from this software without specific prior written permission. This software is provided 

"AS IS," without a warranty of any kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS 

AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR 

A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND ITS 

LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES OR LIABILITIES SUFFERED BY LICENSEE 

AS A RESULT OF OR RELATING TO USE, MODIFICATION OR DISTRIBUTION OF THE SOFTWARE 

OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST 

REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, 

INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF 

LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS 

BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You acknowledge that Software is not 

designed, licensed or intended for use in the design, construction, operation or maintenance of any nuclear facility. 

Progress Sonic v8.5 incorporates Saxon XSLT and XQuery Processor v8.9.0.4 from Saxonica Limited 

(http://www.saxonica.com/) which is available from SourceForge (http://sourceforge.net/projects/saxon/). PSC 

will, at Licensee's request, provide copies of the source code for this third party technology, including 

modifications, if any, made by PSC. PSC may charge reasonable shipping and handling charges for such 

distribution. Licensee may also obtain the source code through http://communities.progress.com/pcom/docs/DOC- 

16051 by following the instructions set forth therein. - Mozilla Public License Version 1.0 (the "License"); you may 

not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.mozilla.org/MPL. Software distributed under the License is distributed on an "AS IS" basis, 

WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language 

governing rights and limitations under the License. The Original Code of Saxon comprises all those components 

which are not explicitly attributed to other parties. The Initial Developer of the Original Code is Michael Kay. Until 

February 2001 Michael Kay was an employee of International Computers Limited (now part of Fujitsu Limited), 

and original code developed during that time was released under this license by permission from International 

Computers Limited. From February 2001 until February 2004 Michael Kay was an employee of Software AG, and 

code developed during that time was released under this license by permission from Software AG, acting as a 

"Contributor". Subsequent code has been developed by Saxonica Limited, of which Michael Kay is a Director, 

again acting as a "Contributor". A small number of modules, or enhancements to modules, have been developed by 

other individuals (either written specially for Saxon, or incorporated into Saxon having initially been released as 

part of another open source product). Such contributions are acknowledged individually in comments attached to

the relevant code modules. All Rights Reserved. 

Progress Sonic v8.5 incorporates Mozilla Rhino v1.5R3. The contents of this file are subject to the Netscape Public 

License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may 

obtain a copy of the License at http://www.mozilla.org/NPL/. Software distributed under the License is distributed 

on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the 

specific language governing rights and limitations under the License. The Original Code is Mozilla Communicator 

client code, released March 31, 1998. The Initial Developer of the Original Code is Netscape Communications 

Corporation. Portions created by Netscape are Copyright (C) 1998-1999 Netscape Communications Corporation. 

All Rights Reserved. PSC will, at Licensee's request, provide copies of the source code for this third party 

technology, including modifications, if any, made by PSC. PSC may charge reasonable shipping and handling 

charges for such distribution. Licensee may also obtain the source code through 

http://communities.progress.com/pcom/docs/DOC-16051 by following the instructions set forth therein. 

Progress Sonic v8.5 incorporates Apache Ant-Contrib 1.0B3. Such technology is subject to the following terms 

and conditions: The Apache Software License, Version 1.1 - Copyright (c) 2001-2003 Ant-Contrib project. All 

rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted 

provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright 

notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the 

above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other 

materials provided with the distribution. 3. The end-user documentation included with the redistribution, if any, 

must include the following acknowlegement: "This product includes software developed by the Ant-Contrib 

project (http://sourceforge.net/projects/ant-contrib)." Alternately, this acknowlegement may appear in the software 

itself, if and wherever such third-party acknowlegements normally appear. 4. The name Ant-Contrib must not be 

used to endorse or promote products derived from this software without prior written permission. For written 

permission, please contact ant-contrib-developers@lists.sourceforge.net. 5. Products derived from this software 

may not be called "Ant-Contrib" nor may "Ant-Contrib" appear in their names without prior written permission of 

the Ant-Contrib project. THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR IMPLIED 

WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 


SHALL THE ANT-CONTRIB PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 

INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 

BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 

DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 

LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 

OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 

THE POSSIBILITY OF SUCH DAMAGE. 

Progress Sonic v8.5 incorporates Xalan Java XSLT Parser v2.4.1 from the Apache Foundation. Such technology 

is subject to the following terms and conditions: The Apache Software License, Version 1.1 - Copyright (c) 1999 

The Apache Software Foundation. All rights reserved. Redistribution and use in source and binary forms, with or 

without modification, are permitted provided that the following conditions are met: 1. Redistributions of source 

code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions 

in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the

documentation and/or other materials provided with the distribution. 3. The end-user documentation included with 

the redistribution, if any, must include the following acknowledgment: "This product includes software developed 

by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in 

the software itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Xalan" and 

"Apache Software Foundation" must not be used to endorse or promote products derived from this software without 

prior written permission. For written permission, please contact apache@apache.org. 5. Products derived from this 

software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of 

the Apache Software Foundation. THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR 



SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY 

DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 

(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 

OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 

THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 

NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 

IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

========================================== 

This software consists of voluntary contributions made by many individuals on behalf of the Apache Software 

Foundation and was originally based on software copyright (c) 1999, Lotus Development Corporation., 

http://www.lotus.com. For more information on the Apache Software Foundation, please see 

(http://www.apache.org/). 

Progress Sonic v8.5 incorporates Xerces v2.6.2 from the Apache Foundation. Such technology is subject to the 

following terms and conditions: The Apache Software License, Version 1.1 - Copyright (c) 1999-2004 The Apache 

Software Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without 

modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must 

retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary 

form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the 

documentation and/or other materials provided with the distribution. 3. The end-user documentation included with 

the redistribution, if any, must include the following acknowledgment: "This product includes software developed 

by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in 

the software itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Xerces" and 



software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of 

the Apache Software Foundation. THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR 





(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS





================================================================ 


Foundation and was originally based on software copyright (c) 1999, International Business Machines, Inc., 

http://www.ibm.com. For more information on the Apache Software Foundation, please see 


Progress Sonic v8.5 incorporates RSS4J v0.9.2. Such technology is subject to the following terms and conditions: 

Copyright (c) 1999-2002 ChurchillObjects.com All rights reserved. Redistribution and use in source and binary 

forms, with or without modification, are permitted provided that the following conditions are met: Redistributions 

of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following 

disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the 

copyright holder nor the names of its contributors may be used to endorse or promote products derived from this 

software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT 

HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 

INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 

FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR 

CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 

OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 

SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 

INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 

CONTRACT, STRICT LIABILITY, OR TORT, INC 

Progress Sonic v8.5 incorporates Crimson v1.1.3. Such technology is subject to the following terms and 

conditions: The Apache Software License, Version 1.1. Copyright (c) 1999-2003 The Apache Software 

Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without modification, 

are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the 

above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must 

reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation 

and/or other materials provided with the distribution. 3. The end-user documentation included with the 

redistribution, if any, must include the following acknowledgment: "This product includes software developed by 

the * Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in 

the software itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Xerces" and 



software may not be called "Apache", nor may "Apache" appear in their name, without prior written * permission 

of the Apache Software Foundation. THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR 


MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT




OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY 




==================================================================== 


Foundation and was * originally based on software copyright (c) 1999, International * Business Machines, Inc., 

http://www.ibm.com. For more * information on the Apache Software Foundation, please see * 


Progress Sonic v8.5 incorporates Jing 20030619 and Trang 20030619. Such technology is subject to the following 

terms and conditions: Copyright (c) 2002, 2003 Thai Open Source Software Center Ltd. All rights reserved. 

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the 

following conditions are met: Redistributions of source code must retain the above copyright notice, this list of 

conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, 

this list of conditions and the following disclaimer in the documentation and/or other materials provided with the 

distribution. Neither the name of the Thai Open Source Software Center Ltd nor the names of its contributors may 

be used to endorse or promote products derived from this software without specific prior written permission. THIS 

SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 

EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 

WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY 







Progress Sonic v8.5 incorporates RSSUTILS v1.1. Such technology is subject to the following terms and 

conditions: Copyright 2003 Sun Microsystems, Inc. ALL RIGHTS RESERVED Use of this software is authorized 

pursuant to the terms of the license found at http://developer.java.sun.com/berkeley_license.html Copyright 2003 

Sun Microsystems, Inc. All Rights Reserved. Redistribution and use in source and binary forms, with or without 

modification, are permitted provided that the following conditions are met: 

-Redistribution of source code must retain the above copyright notice, this list of conditions and the following 

disclaimer. 

-Redistribution in binary form must reproduce the above copyright notice, this list of conditions and the following 

disclaimer in the documentation and/or other materials provided with the distribution. 

Neither the name of Sun Microsystems, Inc. or the names of contributors may be used to endorse or promote

products derived from this software without specific prior written permission. This software is provided "AS IS," 

without a warranty of any kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND 

WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A 

PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MICROSYSTEMS, 

INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY 

LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS 

DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, 

PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR 

PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, 

ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN 

ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You acknowledge that this software is not designed, 

licensed or intended for use in the design, construction, operation or maintenance of any nuclear facility. 

Progress Sonic v8.5 incorporates DSTC Xs3P version 1.1 from DSTC Pty Ltd. PSC will, at Licensee's request, 

provide copies of the source code for this third party technology, including modifications, if any, made by PSC. 

PSC may charge reasonable shipping and handling charges for such distribution. Licensee may also obtain the 

source code through http://communities.progress.com/pcom/docs/DOC-16051 by following the instructions set 

forth therein. - DSTC Public License. The contents of this file are subject to the DSTC Public License Version 1.1 

(the 'License') (provided herein); you may not use this file except in compliance with the License. Software 

distributed under the License is distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, either 

express or implied. See the License for the specific language governing rights and limitations under the License. 

The Original Code is xs3p. The Initial Developer of the Original Code is DSTC. Portions created by DSTC are 

Copyright (c) 2001, 2002 DSTC Pty Ltd. All Rights Reserved. 

August 2011

Contents 

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 

Typographical Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

Progress Sonic Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

Sonic ESB Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

Worldwide Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 

Chapter 1: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 

Roles in Release Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

Stages of Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

Developing on Sonic Workbenches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 

Deploying to Developer Integration Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 

Deploying to Advanced Staging and Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 

Security in the Staging and Production Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

Different Passwords in Staging and Production Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

Using Authentication to Differentiate Management Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

Connection Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

Authorization on Endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

Chapter 2: Exporting ESB Artifacts for Deployment . . . . . . . . . . . . . . . . . 31 

About Sonic ESB Deployment Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 

About Sonic Archive Files and File Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

About Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

About Roots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 

Sonic Build and Deployment Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 

Creating Deployment Archives from a Workbench’s Domain. . . . . . . . . . . . . . . . . . . . . . . . . 39 

Creating Deployment File Sets from a Workbench’s Domain . . . . . . . . . . . . . . . . . . . . . . . . . 40 

Creating Deployment File Sets with Scripted Builds of Projects . . . . . . . . . . . . . . . . . . . . . . . 41 

Progress Sonic ESB Deployment Guide 8.5 11

Contents 

Using the Deployment Export Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 

Accessing Configurations in the Deployment Export Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 

Defining and Exporting a Sonic Deployment Archive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 

Viewing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49 

Exporting ESB Artifacts With the ESB Admin Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 

Starting the ESB Admin Tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 

Connecting to the Source Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 

Using the Export Archive Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 

Using the Export FS Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53 

Closing the Domain Connection and Stopping the ESB Admin Tool . . . . . . . . . . . . . . . . . . . .53 

Using Scripted Builds to Export ESB Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54 

Example of a Scripted Build of ESB Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 

Extending Ant Scripts For Mapping and Import Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . .57 

Chapter 3: Mapping ESB Artifacts to Target Domains . . . . . . . . . . . . . . . .59 

Overview of Mapping Sonic Deployment Archives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60 

Tailoring Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62 

Default Tailorings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63 

Adjusting Tailoring Rules to Apply When Creating Map Files. . . . . . . . . . . . . . . . . . . . . . . . .67 

Applying Tailoring Rules and Creating a Map File for an Archive. . . . . . . . . . . . . . . . . . . . . .73 

Adjusting and Applying a Map File to an Archive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78 

Defining Scripts to Automate Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81 

Incrementally Updating or Building Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83 

Incrementally Updating a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83 

Building ESB Elements into a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84 

Deciding on Export or Promotion Through Stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85 

Implementing Domain Builds and Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87 

Using the Build Strategy on a Static Target Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87 

Using the Update Strategy on Dynamic Target Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89 

Chapter 4: Analyzing ESB Artifacts in Archives, Stores, and File Systems. 

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95 

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96 

Reporting Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97 

Reporting SonicMQ Dependencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98 

Reporting on SonicMQ Reverse Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100 

Reporting on Impact Analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102 

12 Progress Sonic ESB Deployment Guide 8.5

Contents 

Chapter 5: Importing Deployment Artifacts into a Domain . . . . . . . . . 105 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 

Backing Up the Domain and Documenting Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 

Using The Deployment Archive Import Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 

Setting Import Properties for ESB Artifacts into a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . 107 

Saving a Deployment Import Property File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 

Importing an ESB Artifact Store Into a Domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 

Validating Imported Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 

Viewing Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 

Importing or Merging ESB Artifacts With the ESB Admin Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 

Starting the ESB Admin Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 

Connecting to the Target Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 

Using Import Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 

Using the Import Archive Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 

Using the Import FS Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 

Using the Merge Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 

Importing Configurations using the ESB Admin Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 

Closing the Domain Connection and Stopping the ESB Admin Tool . . . . . . . . . . . . . . . . . . 120 

Chapter 6: Adapting Imported Services to a Domain. . . . . . . . . . . . . . . . 121 

Scoping the Required Adaptation Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 

Deployment to a Unified Staging Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 

Deployment to a Distributed Staging or Production Deployment . . . . . . . . . . . . . . . . . . . . . 124 

Binding ESB Services to Messaging Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 

Setting Up Distributed Messaging Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 

Binding Connections to Host Ports in the New Domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 

Binding the Endpoints in the New Domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 

Routing Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 

Updating Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 

Reconciling Users and Groups to Authentication Domains . . . . . . . . . . . . . . . . . . . . . . . . . . 131 

Reconciling Endpoint Access and QoP to Authorization Policies . . . . . . . . . . . . . . . . . . . . . 131 

Enabling and Updating Sonic ESB Service Containers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 

Installing Distributed Systems with Deployment Software . . . . . . . . . . . . . . . . . . . . . . . . . . 132 

Checking for Elements That Might Not Have Been Exported . . . . . . . . . . . . . . . . . . . . . . . . 132 

Tuning the Imported Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 


Contents 

Chapter 7: Updating a Revised Deployment . . . . . . . . . . . . . . . . . . . . . . . . . .139 

Using Deployment Tools to Rebuild and Deploy a XAR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140 

Using the ESB Admin Tool to Rebuild a XAR or File Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 

Modifying ExportProperties.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141 

Rebuilding the Export Package with the ESB Admin Tool . . . . . . . . . . . . . . . . . . . . . . . . . . .142 

Modifying the Import Rules for the Target Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142 

Deploying a Rebuilt XAR or File Store with ESB Admin Tool . . . . . . . . . . . . . . . . . . . . . . .143 

Chapter 8: Distributed Deployment at Runtime. . . . . . . . . . . . . . . . . . . . . . .145 

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146 

Multiple Instances of a Service or Process in a Domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148 

Distributed Installation of a Product’s Runtime Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 

Multiple Services in a Container. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150 

Multiple ESB Containers in a Management Container. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152 

Multiple Management Containers on a Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153 

Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154 

Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154 

Runtime Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155 

Monitoring and Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156 

ESB Container Notifications and Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157 

Management Container Notifications and Metrics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158 

Container Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159 

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 


Preface 

This Preface contains the following sections: 

● “About This Guide” — Describes this manual and its intended audience 

● “Typographical Conventions” — Describes the text formatting, syntax notation, and 

flags used in this manual 

● “Progress Sonic Documentation” — Describes the books and API online references 

packaged with the Sonic ESB Product Family 

● “Worldwide Technical Support” — Provides information on how to contact Progress 

Sonic customer support and Progress Sonic evaluation support 


Preface 

About This Guide 

This guide is for administrators who want to export ESB artifacts from a source 

environment and deploy them into deployment environments, such as testing, and 

production. 

To make full use of this guide, you should be familiar with installing applications on your 

supported platform, and configuring SonicMQ. 

This guide includes the following chapters: 

● Chapter 1, “Introduction” — Introduces file structures, security, and composite 

applications to make them easier to deploy and maintain 

● Chapter 2, “Exporting ESB Artifacts for Deployment” — Describes archives, 

dependencies, and roots, then shows how use the deployment export tools and 

scripted builds to package deployment artifacts 

● Chapter 3, “Mapping ESB Artifacts to Target Domains” — Describes tailoring and 

mapping of export packages to a target domain. Shows alternative approaches build 

and manage deployment through source control and change management systems 

● Chapter 4, “Analyzing ESB Artifacts in Archives, Stores, and File Systems” — 

Details the syntax of each ESB Admin Tool command that reports on differences and 

dependencies between stores, and the impact of files or archives on a domain 

● Chapter 5, “Importing Deployment Artifacts into a Domain” — Describes how to use 

import and merge commands to move artifacts to a target domain 

● Chapter 6, “Adapting Imported Services to a Domain” — Presents the steps to 

implement an imported deployment archive 

● Chapter 7, “Updating a Revised Deployment” — Shows how to rebuild from a 

modified source 

● Chapter 8, “Distributed Deployment at Runtime” — Shows advanced techniques for 

additional service instances and combinations of services in a container or system 


Typographical Conventions 

Typographical Conventions 

This section describes the text formatting conventions used in this guide and a description 

of notes, warnings, and important messages. This guide uses the following typographical 

conventions: 

● Bold typeface in this font indicates keyboard key names (such as Tab or Enter) and 

the names of windows, menu commands, buttons, and other Sonic user interface 

elements. For example, “From the File menu, choose Open.” 

● Bold typeface in this font emphasizes new terms when they are introduced. 

● Monospace typeface indicates text that might appear on a computer screen other than 

the names of Sonic user-interface elements, including: 

■ Code examples and code that the user must enter 

■ System output such as responses and error messages 

■ Filenames, pathnames, and software component names, such as method names 

● Bold monospace typeface emphasizes text that would otherwise appear in monospace 

typeface to emphasize some computer input or output in context. 

● Monospace typeface in italics or Bold monospace typeface in italics (depending 

on context) indicates variables or placeholders for values you supply or that might 

vary from one case to another. 

This guide uses the following syntax notation conventions: 

● Brackets ([ ]) in syntax statements indicate parameters that are optional. 

● Braces ({ }) indicate that one (and only one) of the enclosed items is required. A 

vertical bar (|) separates the alternative selections. 

● Ellipses (...) indicate that you can choose one or more of the preceding items. 

This guide highlights special kinds of information by shading the information area, and 

indicating the type of alert in the left margin. 

Note Note indicates information that complements the main text flow. Such information is 

especially important for understanding the concept or procedure being discussed. 

Important Important indicates information that must be acted upon within the given context in order 

for the procedure or task (or other) to be successfully completed. 

Warning Warning indicates information that can cause loss of data or other damage if ignored. 


Preface 

Progress Sonic Documentation 

Sonic installations always have a welcome page that provides links to Sonic 

documentation, release notes, communities, and support. See the release’s Product 

Update Bulletin book to see what’s new and what’s changed since prior releases. 

The Sonic documentation set includes the following books and API references. 

Sonic ESB Documentation 

Sonic ESB provides the following documentation: 

● Progress Sonic Installation and Upgrade Guide — Provides information about 

installing, updating, and upgrading Sonic ESB components. 

● Progress Sonic Workbench User Guide (Progress Sonic Workbench Online Help) — 

Provides information about developing, testing, and debugging applications on the 

Progress Sonic Workbench. Describes the Sonic Workbench, its editors, and tools. 

Provides information about how to get started with each component of the Sonic ESB 

Product Family and describes sample applications. 

● Progress Sonic ESB Configuration and Management Guide — Provides information 

about configuring and managing components used by the Sonic ESB Product Family. 

Describes deployment configurations for Sonic ESB, Sonic Database Service, and 

Sonic BPEL Server 

● Progress Sonic ESB Deployment Guide — Provides information about moving 

development projects into test and production environments. Describes 

recommended build procedures, domain mappings, and reporting features. 

● Progress Sonic BPEL Server: Management API Guide — Describes how to use the 

management API to programatically access BPEL server functionality. 

● Sonic ESB API Reference — Online JavaDoc compilation of the Sonic ESB APIs. 


Worldwide Technical Support 

Worldwide Technical Support 

Progress Software’s Sonic support staff can provide assistance from the resources on their 

Web site at www.progress.com/sonic. There you can access technical support for licensed 

Progress Sonic editions to help you resolve technical problems that you encounter when 

installing or using Progress Sonic products. 

When contacting Technical Support, please provide the following information: 

● The release version number and serial number of SonicMQ that you are using. This 

information is listed on the license addendum. It is also at the top of the SonicMQ 

Broker console window and might appear as follows: 

SonicMQ Continuous Availability Edition [Serial Number nnnnnnn] 

Release nnn Build Number nnn Protocol nnn 

● The release version number and serial number of Sonic ESB that you are using. This 

information is listed on the license addendum. It is also near the top of the console 

window for a Sonic ESB Container. For example: 

Sonic ESB Continuous Availability Edition [Serial Number: nnnnnnn] 

Release nnn Build Number nnn 

● The platform on which you are running Progress Sonic products, and any other 

relevant environment information. 

● The Java Virtual Machine (JVM) your installation uses. 

● Your name and, if applicable, your company name. 

● E-mail address, telephone, and fax numbers for contacting you. 


Preface 


Chapter 1 Introduction 

This chapter summarizes the tasks for developers to perform on Sonic Workbenches and 

the tasks performed by a release management team to package deployable components 

and ESB artifacts for deployment testing, staging, and production environments. It also 

includes steps to establish secure, controlled access to deployment environments. 

Deployment is a managed, repeatable process of extracting a composite business 

application from one Sonic domain and tailoring it for use in other Sonic domains. 

This chapter contains the following sections: 

● “Roles in Release Management” 

● “Stages of Deployment” 

● “Security in the Staging and Production Domains” 


Chapter 1: Introduction 

Roles in Release Management 

Composite applications are created in the Sonic development environment, Sonic 

Workbench. The release management team is the bridge between development and 

deployment. A release team has several roles; these might be shared by one person, or 

distributed to multiple work groups. The roles are: 

● Deployment Architect — An enterprise’s release management infrastructure evolves 

as tools and requirements evolve. The architect defines and monitors the team’s 

requirements and tasks to ensure that the deployment plan is reliable and efficient. 

● Release Manager — The release manager controls the configuration repositories and 

their versioning/branching mechanisms. Often multiple branches evolve 

concurrently—the latest in testing, the previous test-approved promoted to user 

acceptance, and the previous user-approved—the release manager monitors the flow, 

and, as stages are accepted or rejected, redirects the flow. 

● Build Manager — The build manager controls the build process. When cued by 

development managers that the developer checkins are ready for a build, the build 

manager runs (and monitors) the scripts that output the appropriate ESB artifacts and 

compile the libraries that package the branch build. 

● Configuration Manager — The underlying messaging infrastructure requires 

administrative management of the security systems and messaging brokers. While 

deployments can be reliably and consistently tailored for adaptation to a target 

domain, the configuration manager tunes the scripts to connect the deployed 

components to the currently assigned connections, protocols, endpoints, and security. 


Stages of Deployment 


Deployment is based on composite applications stored in configuration repositories. 

Developers move files in and out of source control, creating and testing business 

functions, and then checking new or changed files into the source control repository. 

Sonic Workbenches 

Developer Licenses 

Developers 

Source Control 

Release Team 

- Deployment Manager 

- Release Manager 

- Build Manager 

- Configuration Manager 

Sonic Runtime Deployment Domains 

Deployment Licenses 

Staging and Test Environments 

Developer Integration 

User Acceptance 

Production 

Environment 

As illustrated, the typical stages from development to production are: 

● Development on Workbenches — Composite applications (applications that consist 

of functionality from several different sources within a domain) are developed on 

Sonic Workbenches. The developers check their files into a source control repository. 

See “Developing on Sonic Workbenches” on page 24 for more about this stage. 

● Developer integration — The first stage of deployment compiles classes from the 

source files in the branch, and packages ESB configurations in the branch for 

mapping to other domains. The procedure imports the configurations and JARs into 

the testbed where scripts execute tests. The release either reverts to further 

development or advances to the next stage. When advancing, tailoring of the bindings 

for the ESB artifacts prepare the files for the next domain in the progress toward 

production and—together with JARs that were built for the integration testing— 

imported into the next target domain. See “Deploying to Developer Integration 

Testing” on page 25 for more about this stage. 

● User Acceptance — An advanced deployment stage is user acceptance testing 

(UAT). The new deployment elements and the existing elements are positioned in a 

more complex underlying topology to more accurately simulate the production 

environment. In this stage, the stakeholders of the business applications evaluate the 

functionality of the new elements to confirm that the features perform as expected. 

UAT can be made more rigorous by exposing the domain to users for beta testing. See 

“Deploying to Advanced Staging and Production” on page 26 for more information. 

● Production Environment — The end-user-facing deployment domain. Testing 

performed in staging should make this stage of deployment occur without issues. 



Developing on Sonic Workbenches 

The Sonic Workbench development environment decouples developers from the 

deployment architecture so that they can focus on the business application’s functionality. 

A Sonic Workbench is a domain where developers upload development artifacts without 

having to maintain configuration objects. Generic components relieve the developer from 

managing the configuration objects that host and run the services and processes created. 


Repository 

1. Update View 

2. Checkouts 

4. Checkins 

As illustrated, the development flow is: 

Sonic Workbench 

Development Licenses 

Eclipse 

Workspace 

- Projects 

- Source files 

1. A developer on a Sonic Workbench connected to a source control repository loads or 

updates the latest version or view of projects in their current work branch as specified 

by the release manager. 

2. The developer checks out files that will be changed. 

3. Build, Upload, 

Run & Debug 

Workbench 

Directory Service 

- dev endpoints 

- dev containers 

- custom classes 

3. After making changes and building projects in the workspace, and uploading them to 

the Workbench’s domain creates instances that simulate deployment and binds the 

ESB artifacts to default endpoints, connections, and containers. Sonic Workbench 

provides run, test, and debug facilities to unit test the changed application. 

4. When complete, the developer checks in the checked out files of the projects to the 

source control repository to resolve conflicts with other developers’ changes, to back 

up source files, and to transfer and update the project on a different Workbench. While 

deployment can occur on a developer’s Workbench, typically one person is the release 

manager. 

Note Each Workbench container caches a new copy of a file for each invocation of the service 

if a required file is located in the sonicfs:///workspace directory. This is by design, 

because the workspace directory is only intended for development. To stop the container 

from caching a new copy of a file for each invocation of the service, move the file outside 

of the workspace directory within the Directory Service storage, for example: 

sonicfs:///MyFolder/ 


Deploying to Developer Integration Testing 


When all the developers’ check in their changes in and resolve any checkin conflicts, the 

release manager can initiate the deployment process, as shown in the following 

illustration. 


Repository 

Developer Integration Testing Deployment Licenses 

Clean DS 

image 

Selected technique for building and mapping ESB Artifacts 

Scripted build of source files into JARs 

Deployment Domain Manager 

Import ESB 

Artifacts 

Clean Target 

by Refreshing 

from Clean DS 


The release manager might use one of the Sonic Workbench techniques for deployment 

(described in Chapter 2, “Exporting ESB Artifacts for Deployment,”) to access and build 

the projects in the branch that are moving to deployment. 

Two build functions occur, one to package and prepare the ESB artifacts to be tested, and 

the other to compile and package the classes used by the services and processes. When 

both succeed, the output is staged for import into the test environment. 

You should perform integration testing on a simple, uncomplicated domain, referred to in 

this document as a ‘clean Directory Service’ or clean DS. (How to set up and refresh a 

clean DS is discussed in “Using the Build Strategy on a Static Target Domain” on 

page 87.) After refreshing the integration test environment with a clean DS, you should 

delete any JARs imported in prior test runs. 

While the integration test environment is similar to Sonic Workbench’s underlying 

domain, you must modify the naming patterns and paths in the Workbench environment 

for deployment domains. The Sonic mapping tools (discussed in Chapter 3, “Mapping 

Progress Sonic ESB Deployment Guide 8.5 25 

Import 

JARs 

Clean Target 

by Deleting 

Compiled 

JARs


ESB Artifacts to Target Domains,”) let you define and standardize the mapping of names 

into the integration test environment. 

Importing ESB artifacts into the clean DS (see Chapter 5, “Importing Deployment 

Artifacts into a Domain.”) is a pure write—there are no artifacts to overwrite and there are 

no residual artifacts or JARs. 

The configuration manager creates queues and connections that bind to the endpoints 

defined in configurations. The configuration manager also creates the containers that host 

the services. (See Chapter 6, “Adapting Imported Services to a Domain.”) 

When developer integration testing is successful, prepare the same build artifacts and 

JARs for the next staging domain. 

Deploying to Advanced Staging and Production 

In advanced staging domains, the configuration manager’s tasks are more involved, as the 

underlying messaging infrastructure is richer. The connections are dispersed across the 

broker architecture. Their messaging infrastructures reflect the deployment architect’s 

implementations that prototype configuration structures to improve performance, 

enhance security and fault tolerance, and emulate anticipated traffic volumes. These 

domains are stages toward the production environment. 


Repository 

Selected technique for building and mapping ESB Artifacts 

Scripted build of source files into JARs 

Advanced Staging and Production Deployment Licenses 

Deployment Domain Manager 

Import ESB 

Artifacts 

Import Rules 

Analysis 

Reports 


Import JARs 


Security in the Staging and Production Domains 

Advanced staging and production domains are not easily refreshed, so the ESB artifacts 

to be imported often attempt to overwrite matching files in the target domain. To 

document differences and impact, Sonic provides analysis reports that describe 

impending changes and contrasts between domains and artifacts staged for deployment. 

(See Chapter 4, “Analyzing ESB Artifacts in Archives, Stores, and File Systems.”) 

When it is preferred that some artifacts not be overwritten, you can define import rules 

that deselect specified files or branches during the import. (See Chapter 5, “Importing 

Deployment Artifacts into a Domain.”) 

The exporting-reporting-mapping-importing functions can be completely scripted so the 

impending actions, the actual import, and an audit reporting of the completed tasks are 

consistent and predictable from end to end. After importing is complete, the configuration 

manager might have to adjust some bindings. (See Chapter 6, “Adapting Imported 

Services to a Domain” for more information.) 


Planning for security makes it easier to administrate and control an evolving distributed 

services architecture. While the concepts and techniques for channel encryption, message 

Quality of Protection (QoP), and password-based file encryption are presented in the 

SonicMQ Deployment Guide and SonicMQ Configuration and Management Guide, this 

section discusses special considerations when deploying ESB services. 

Security considerations discussed in this section are: 

● Differentiating access to staging and production systems. 

● Setting up different access mechanisms for administrators and components that use 

management connections. 

● Defining different users for routing connections from different domains. 

● Using access control patterns for authorization. This task is simplified when you use 

hierarchical namespaces for destinations. 

This guide focuses authentication and authorization patterns to control domain use and 

management roles. 

See the SonicMQ Deployment Guide Part I, “Designing a SonicMQ Deployment” for 

details about topologies and other architectures, and Part III, “Implementing Security” for 

details about authentication and authorization for the Sonic Enterprise Service Bus. 

See also “Updating Security” on page 131 for security-related tasks after importing 

artifacts to a target domain. 



Different Passwords in Staging and Production Domains 

You can use unique passwords for access to each domain to control changes made to the 

staging and production environments. For example, the domain used for developer 

integration testing might have a password known to all developers, whereas the 

administrators of the staging and production environments might have secret passwords. 

As a result, the developer roles and administrator roles are distinguished by their access. 

The Sonic Workbench development environment should not connect to or update a 

deployment domain. Any required changes migrate from the development environment to 

deployment, thereby honoring the life cycle stages. 

Using Authentication to Differentiate Management Roles 

Another approach to authentication control uses a variety of administrative user names so 

that the authority to use administrative tools, ESB tools, management connections for 

service containers, and management connections for messaging nodes can be assigned to 

different authenticated users. 

This technique can be particularly useful if you want to lock out most users of 

management connections for administrative tools while importing and validating 

deployments. When you are about to enter a deployment import session, you can check 

that there are no user connections that are not intended to be involved in import sessions 

and then temporarily change their user password until the deployment session has been 

validated (or reverted). With this technique, management connections for services and 

messaging nodes would not be impacted. 

Important When domains use management permissions, specified actions might not be allowed and 

some configuration objects might not be visible. See the chapter “Permissions to 

Maintain Configurations and Perform Runtime Actions” in the Progress SonicMQ 

Deployment Guide. 

Connection Authentication 

When you use ESB connections to messaging nodes with routing to other messaging 

nodes, and security is enabled, these connections require user authentication as routing 

users. The subset of users that you define for these connections can increase the 

granularity of your control over access and minimize the recovery time from unauthorized 

use of a user name and password. 


Authorization on Endpoints 


The authorization policies in a domain enable control over read and write actions on 

endpoints—topics, queues, and routing nodes. When users are not granted privileges, the 

ESB services throw an exception. That means that a service can establish connections to 

perform its assigned tasks, yet might be prevented from performing certain tasks because 

a tightening of policies constrains the scope of the authenticated user’s access. See the 

SonicMQ Deployment Guide for information about authorization policies. 

Naming Queues and Topics Using Hierarchical Namespaces 

You can use a naming pattern for endpoint queues and topics. While there are some 

restricted characters and some characters that have special meaning, you can establish any 

pattern you want. 

See Appendix A of the SonicMQ Installation and Upgrade Guide for a complete listing 

of naming rules and allowed characters in SonicMQ configuration elements. 

Application developers should use dot-delimited naming patterns to define endpoint 

names, for example: 

● com.myCorp.Inventory.Valuation.EntryQ1 

● com.myCorp.Inventory.Valuation.EntryQ2 

● com.myCorp.Inventory.Valuation.Exit 

You can constrain use of these queues to developers and deployment management of the 

myCorp Inventory Valuation project. The template character capability in access control 

lists means that the developer of this application can confidently set the permissions on 

com.myCorp.Inventory.Valuation.# without concern about conflict with other 

applications. 




Chapter 2 

Exporting ESB Artifacts for Deployment 

Deployment starts with exporting selected Sonic projects stored in source control 

repositories, and building the selected projects into runtime ESB artifacts and classes that 

define the distributed composite business applications in deployment. 

Other chapters in this guide discuss the mapping, analysis, and importing of these ESB 

artifacts into target domains. 

Chapter 2 contains the following sections: 

● “About Sonic ESB Deployment Artifacts” 

● “Sonic Build and Deployment Tools” 

● “Using the Deployment Export Tool” 

● “Exporting ESB Artifacts With the ESB Admin Tool” 

● “Using Scripted Builds to Export ESB Artifacts” 


Chapter 2: Exporting ESB Artifacts for Deployment 

About Sonic ESB Deployment Artifacts 

A Sonic deployment is a unit of deployment, a set selected configuration files exported 

from a domain, either as a set of files or a Sonic archive file, a .xar file. Typically, the 

projects in a source control branch are uploaded and packaged as one deployment archive. 

Each export includes an export properties file that contains information about the source 

domain and the root elements selected for the export. The export properties file provides 

the template that the export tool uses to rebuild the set of exported configurations. 

The files exported from a domain can include containers, ESB processes, services, service 

types, endpoints, and resources in the Sonic File System, SonicFS. As you construct an 

export archive, selected items are evaluated so that configurations that are dependencies 

are included while standard references that are installed in target domains are explicitly 

excluded from the archive. 

Most archives can be assembled in two steps: 

1. Choosing a process or service and letting it discover its dependencies 

2. Choosing the branch that defines your storage area for the project in the Sonic File 

System. 

Important Additional elements — Some configuration elements are not readily discovered or 

exported. Some elements that you must recreate in the target domain are: 

● Properties files for management and administrative tools. 

● Management containers. They are created in the target domain’s Sonic Management 

Console to bind hosted ESB components and services to physical distributed 

systems. 

● Classes (.jar files) that not imported into SonicFS or not referenced by the ESB 

Container through a classpath parameter. 

● Files not stored in the SonicFS structure, perhaps used by services or GUI 

components of an application. See “Packaging Graphical Components” on page 37 

for more information. 

Note Ignored Elements — Within the set of referenced elements, some basic elements are not 

included because they are expected to exist in a target domain. These standard types are 

established in target domains as you define the domain and install its components. 


About Sonic Archive Files and File Sets 


A Sonic archive file, a XAR file, is an archive of selected configuration files exported from 

a domain. Each archive file includes an export properties file that contains information 

about the source domain and the root elements selected for the archive. The export 

properties file provides the template that the export tool uses to rebuild the archive. 

The files exported from a domain can include containers, ESB processes, services, service 

types, endpoints, and resources in the Sonic File System, SonicFS. As you construct an 

export archive, selected items are evaluated so that configurations that are dependencies 

are included while standard references that are installed in target domains are explicitly 

excluded from the archive. 

About Dependencies 

Dependencies are explicit references to other elements. When you choose an ESB 

element to be evaluated, the dependency logic traverses the selected element’s references 

to determine the element’s explicit dependencies. The following illustration shows the 

hierarchy of the ESB element groups that have dependencies on elements in that group or 

subordinate groups: 

ESB Connection Types 

ESB Endpoint Types 

ESB Container ESB Services 

ESB Endpoints 

ESB Processes 

ESB Connections 

ESB Service Types 



SonicFS 

classpaths 

The following illustration provides a more detailed look at ESB elements and reveals 

recursive and secondary references that the dependency logic discovers in a full set of 

dependencies: 

Routing HTTP connections 

Bus connections 

Dependencies in BPEL Server Projects 

ESB Connection Types 

ESB Connections 

ESB Service Types 

ESB Endpoint Types 

ESB Container ESB Services 

ESB Endpoints 

if BPE 

if BPAR 

ESB Processes 

itinerary 

BPAR 

(BPEL Archive) 

tracking details 

WSDL 

To choose a Sonic BPEL Server project, build and upload its project, and then choose its 

service name (such as Sample.BPEL) or its BPAR file. The traversal of the .bpar file 

evaluates the .wsdl, .bpel, .xlst, and .xsd content of the BPAR file recursively to 

determine dependent endpoints, connections, processes, .wsdl files and Resources. 

34 Progress Sonic ESB Deployment Guide 8.5 

WSDL URL

About Roots 


The procedure of creating a deployment export package specifies through a series of 

selections, each of which defines a root in the archive structure. Each root is a line item 

in the archive definition that defines: 

● An ESB artifact from which dependencies are to be evaluated. The process of 

discovery attaches the artifact’s dependencies to that root element. 

● A file in the Sonic File System whose dependencies are discovered and defined as 

attachments to that root element. A file name with the extension xsl, xslt, xml, xsd, 

wsdl, esbws, esbdb, xaction, or cbr is examined for further references to SonicFS. 

● A folder in the Sonic File System, SonicFS. Specifying a sonicfs:// folder includes 

all subordinate folders and files as attachments to that root element. Choosing a folder 

in SonicFS that contains files that, selected individually, would be evaluated does not 

cause any such files to be evaluated—instead the entire folder hierarchy below the 

selected folder is attached to that archive root. 

The following screen shows the roots specified in the example in “Using the Deployment 

Export Tool” on page 42. 

There are two roots in this archive specification: one ESB process, and one text file. 

Editing ExportProperties.xml 

The roots are stored in the ExportProperties.xml file that is created by a new export, and 

then stored in the file store or archive. When an archive is rebuilt, its contents are 

discarded except for its defined roots. The roots are re-evaluated so that current 

dependencies and folder hierarchies are included. This file is edited by changes you make 

in the Deployment Export Tool. If you want to change an existing ExportProperties.xml 

file when rebuilding an ESB artifact package using ESB Admin Tool export command, 

this file must be edited in the file store or within the archive before you issue the 

command. 



An ExportProperties.xml file looks like this: 

 

 

source section — Defines the domain connection when rebuilding the archive. 

 

Domain1 

tcp://localhost:2506 

Administrator 

 

ignore section — Artifacts that are preconfigured in every ESB-enabled domain are 

ignored for archive packaging. Sonic’s tailoring tools will tailor references that are 

dev.* artifacts to global.*, artifacts that you set up in the target domain. Typically, the 

ignore list is accepted as is. If you add or remove from this section, a rebuild of the 

archive will ignore the artifacts listed in this section. (The listed items below are an 

excerpt of the complete default list of files that will be ignored.) 

 

 

 

 

 

 

. . . 

 

 

 

 

roots section — Shows the selected roots. In this example, one service type and one 

service were selected. If you selected all, the root would be: 

 

 

 

 

 

notes section — Annotates the export package with any text information entered. 

Archive created 23 Jan 2008 to package the Remote Information Accesss 

project. Spec: vobs_specs/RIA.doc Test plan: vobs_qa/RIA.xls 

Usage notes: see atached readme.txt Contact: myCorp_Dev@myCorp.com 

 

 


Adding Additional Classes 


The classes compiled on a Sonic Workbench into a project’s /lib/custom-servicesclasses.jar 

are for use only on the Sonic Workbench. Use a general build tool (such as 

Ant) to compile classes and create Java archive files (JARs) that contain the classes that 

you import into deployment domains. 

If you have additional JARs, such as third-party security JARs, that you need in 

deployment domains, you can import them into the Sonic File System and then select 

them as SonicFS elements so that they are transported with their related configurations in 

the deployment archive. 

Packaging Graphical Components 

Applications that use graphical components, such as properties files and images, cannot 

reference files when they are in the Sonic File System. However, you can package 

supporting files for applications in an ESB deployment archive and unpack them on the 

target system. As the files transferred this way must be relocated locally to be used, you 

should create a readme file that describes the tasks required for runtime. 

To transfer graphical application components in a deployment, package the required files 

in their runtime project folder locations together with your read me file into a .zip archive. 

In the Configure tab of the Sonic Management Console, import the .zip file into SonicFS. 

You could create a subfolder in the runtime directory of files to place files to be adapted 

to the target domain. After packaging the .zip file into a deployment, it can be imported 

into a new domain where you can then export it out of SonicFS, relocate it and deploy its 

contents. After the deployment completes, review the files to see if you need to revise 

references in the properties files to URLs, endpoints, services, and ESB processes in the 

new domain. 

Rebuilding from Roots 

If you save export results and then prune or add a branch during ongoing development, 

choose to rebuild—select the Rebuild option in the Deployment Export Tool, or reference 

the export properties file in the ESB Admin Tool command parameters—to clear the 

archive or file store and repopulate it with the current dependencies and their artifacts. The 

rebuild process is not a refresh action. Instead, the ExportProperties.xml file’s source 

section supplies the correct domain connection, and its roots section is re-evaluated. The 

current list of files is packaged into the export results. 



Sonic Build and Deployment Tools 

The Sonic toolset provides alternative tool functions to export ESB artifacts: 

Tool and Function Selection Method 

Deployment Export Tool 

Save as deployment archive 

Deployment Export Tool 

Save to file system 

ESB Admin Tool 

export archive command 


export fs command 

User recursively selects 

artifact types, and a root 

that delimits the 

selection’s scope. 

Typically used to either 

rebuild an existing 

export archive/file set or 

choose all artifacts in the 

domain. 

Scripted Build Exports all ESB artifacts 

in specified folders 

except BPEL archives. 

* Can select miscellaneous files when updating from a properties file created by 

Deployment Export Tool. 

The following sections provide an overview of: 

Creates and 

Can Use an 

Export 

Properties File 

Requires 

Domain 

Connection 

and Upload 

Yes Yes Yes 

No Yes Yes 

Yes Yes No* 

Yes Yes No* 

No No No 

● “Creating Deployment Archives from a Workbench’s Domain” 

● “Creating Deployment File Sets from a Workbench’s Domain” 

● “Creating Deployment File Sets with Scripted Builds of Projects” 

Allows 

Selection 

of Misc. 

Files 



Creating Deployment Archives from a Workbench’s Domain 


Repository 

Deployment archives provide coarse-grained packaging of ESB artifacts. The following 

tools enable you to connect to a running domain manager to create ESB artifact archives: 

● The Deployment Export Tool, by choosing the Save XAR command 

● The ESB Admin Tool, by using the export archive command 

1. Read Projects 



Eclipse 

Workspace 

- Projects 


2. Build, Upload 

As illustrated, a Sonic Workbench: 

Workbench 





4. Build Java sources for Projects into JARs 

1. Starts and reads projects into its workspace. 

3. Export ESB Artifacts in an Archive 

2. The projects in the workspace are built and uploaded into the Workbench’s domain, 

establishing the ESB artifacts in the domain. 

3. An export archive is created by either the Deployment Export Tool or the ESB Admin 

Tool. 

4. A separate procedure builds the Java source files into deployment JARs. 

Export to 

.XAR file 



Creating Deployment File Sets from a Workbench’s Domain 


Repository 

Deployment file sets provide fine-grained packaging of ESB artifacts. The following tools 

enable you to connect to a running domain manager to create export ESB artifact file sets: 

● The Deployment Export Tool, by choosing the Save to File System As command 

● The ESB Admin Tool, by using the export fs command 

1. Read Projects 



Eclipse 

Workspace 

- Projects 


2. Build, Upload 

As illustrated, a Sonic Workbench: 

Workbench 






1. Starts and reads projects into its workspace. 

3. Export ESB Artifacts into File System 

2. The projects in the workspace are built and uploaded into the Workbench’s domain, 

establishing the ESB artifacts in the domain. 

3. An export of ESB artifacts as a set of files is created in the file system by either the 

Deployment Export Tool or the ESB Admin Tool. 


Export to 

File System 



Creating Deployment File Sets with Scripted Builds of Projects 


Repository 

Scripted builds evaluate the ESB artifacts in all projects in a storage location to provide 

fine-grained packaging. In a build script, you specify the source locations in a properties 

file, and the location of output ESB artifact file sets. Running a specialized Ant build’s 

instructions against the script exports the artifacts. 

1. Script defines projects to build 

As illustrated: 

2. Build emulates an upload 


3. Build exports ESB Artifacts into File System 

1. A properties script specifies the root locations of the source files, and the target 

location of the output files. 

2. The Ant build of the ESB artifacts evaluates the specified projects to determine the 

ESB artifacts and their dependencies 

3. The Ant build exports the ESB artifacts as a set of files in the file system. 


Both builds could run as one to automate the complete build process. 

Export to 

File System 

Note Scripted builds do not export Sonic BPEL Server projects complete for deployment. 



Using the Deployment Export Tool 

The Sonic deployment export tools include a graphical application and a command syntax 

in the ESB Admin Tool. This section describes the functionality of the graphical application, 

the Deployment Export Tool. The next section describes “Exporting ESB Artifacts With the 

ESB Admin Tool.” 

Note The corresponding Sonic Deployment Import Tool and the ESB Admin Tool commands 

import and merge are discussed in “Importing Deployment Artifacts into a Domain” on 

page 105. 

◆ To start the Deployment Export Tool: 

Note A system must have Sonic ESB Administration Tools installed (a Sonic ESB 

Administration Tools installation or a Sonic Workbench installation) to run this tool. 

1. Check that the source domain manager is running. 

2. On the system where you will execute the export process, start the Sonic Deployment 

Export Tool: 

■ Under Windows, choose: 

Start > Programs > Progress > Sonic 8.5 > Tools > ESB Deployment Export Tool 

■ Under UNIX or Linux, on a system installed with the Sonic ESB Administration 

Tools, open a console window to the Sonic ESB installation directory, and then 

enter: ./bin/deployExport.sh 

The Deployment Archive Export window opens: 



◆ To connect to the domain where you want to export ESB Artifacts: 

1. Be sure that the Domain Manager of the domain from which you want to export is 

running. 

2. Choose Domain > Connect. In the Domain Connection dialog box, enter the 

connection information for the domain, as shown: 

The default values (with the password Administrator) are appropriate when 

connecting on a Sonic Workbench system. When connecting to a Workbench domain 

from a different system, provide the source system’s host name instead of localhost. 

Accessing Configurations in the Deployment Export Tool 

The export options provide alternative techniques to select elements and files. 

The Actions menu offers the options, as shown: 

The scope of the export root selection options are: 

■ Add all elements in the domain — Selects everything. This is a useful technique 

in Workbench backup, and in advanced stages and production. This option does 

not require any further selection of additional root elements as it effectively adds 

all ESB elements, and all SonicFS elements. 



■ Add all ESB elements in the domain — Selects all the ESB element types, but 

does not include SonicFS data unless referenced as dependencies. 

■ Choose ESB Containers — Lets you select one or more ESB Containers. The 

links evaluated are services, endpoints, processes, and connections, each of which 

is, in turn, evaluated for dependencies. 

■ Choose ESB Processes — Lets you select one or more ESB processes. The links 

evaluated are endpoints, services, processes, and WSDL URLs (when referencing 

SonicFS). Also: 

❑ For each step in an ESB process, the endpoint name at each endpoint step (the 

endpoint name, the process name of each ESB process step, and the service 

name of each service step.) 

❑ For each runtime parameter, if the parameter is a URL reference to a SonicFS 

file, the referenced file is included. 

❑ For each invocation step, the .esbws file, when that file is in SonicFS. 

■ Choose ESB Services — Lets you select one or more ESB services. The links 

evaluated are endpoints, services, processes, WSDL URLs (when these reference 

SonicFS), and init parameters that are URL references to SonicFS files. Sonic 

BPEL Server services evaluate the related BPAR as a dependency. 

■ Choose ESB Service Types — Lets you select one or more ESB service types. 

Choosing a service type includes its properties file as a dependency. 

■ Choose ESB Endpoints — Lets you select one or more ESB Endpoints. The links 

that are evaluated are EndpointTypes and WSDL URLs in SonicFS. 

■ Add all SonicFS — Since many elements in SonicFS might be dependencies of 

ESB elements, this option selects all of the files in the Sonic File System. 

■ Choose SonicFS — Lets you select one or more folders and files from SonicFS: 

❑ When you choose a folder, you get all of a specified folder structure including 

any files you imported into the SonicFS in the selected folder. 

❑ When you choose a file in SonicFS as the root element, that file is evaluated 

to include its dependencies. These include xsl, xslt, xml, xsd, wsdl, esbws, 

esbdb, xaction, or cbr. For example, an esbws file references a wsdl file. 

You can choose a mixture of folders and files, a technique that lets choose a 

folder’s contents and also evaluate the dependencies of a file in the folder that you 

know will have dependencies; for example, an esbws file in a project folder. 

■ Rebuild — Starts the archive rebuild process, described on page 37. 


Defining and Exporting a Sonic Deployment Archive 


As an example, the following procedure shows how some ESB artifacts, folders, and files 

can be exported. 

The basis of this export example is the Sonic Workbench’s ESB sample for Remote 

Information Access, Sample.RIA. The sample was imported onto a Sonic Workbench and 

then uploaded into its domain. That domain is where the deployment tools will connect 

to perform the export functions. 

Note Prototypes — The Sample.RIA project demonstrates the use of the Prototype Service. As 

such, this export includes those prototypes. In a real application, prototypes should be 

replaced by actual services before moving the project into deployment. 

◆ To export ESB Artifacts through the Deployment Export Tool: 

1. Select the Actions menu. The menu lists the options you can choose as your first root 

element. For this example, select Choose ESB Processes, as shown:. 

2. In the Choose ESB Processes dialog box, choose the Sample.RIA.processRequest: 

When you click OK, references from the Sample.RIA.processRequest to other 

elements are traversed. When the traversal is complete, you are presented with the 

results for review. 



The list shows the dependencies on the selected root that will be exported, as shown: 

The Sample.RIA.processRequest references other processes, as well as—in 

SonicFS—a some resource files and sample data in the workspace. 

Notice the Errors tab. This indicates that something did not turn out as expected. 

While errors are not usually observed when projects have been successfully built and 

tested on the Workbench, a simple renaming and uploading of a dependent file causes 

dependency traversal to record an error when defining a root, and in the message 

viewer (see page 49) when creating or rebuilding an archive. 

To handle an error: 

a. Click the Errors tab to view the error. 



b. Choose Cancel, correct the problem by correcting the name of the referenced file, 

choose the ESB process Sample.RIA.processRequest again, and then click OK. 

Note You can ignore the reported error by clicking OK. If you do so, the resource 

requirement will still be perpetuated into target domains so it will have to be 

adjusted there or you will have to import the missing file there. For this example, 

the file is reinstated and the set of dependent artifacts are added showing no errors 

3. If you have other roots that should be packaged in this archive, choose the Action 

menu. 

For this example, the project’s readme file is a file we want in the package. 

a. Choose Actions > Choose SonicFS. In the Choose SonicFS dialog box, navigate 

to the workspace/Sample.RIA folder, and then click on Readme.txt, as shown: 

b. Click OK. The selected file is shown in the file list for this root in the Confirm 

Added Elements dialog box: 



4. After the roots are defined for this example, the set of selected roots looks like this: 

5. When the archive is complete, you can add notes to the archive by selecting 

File > Properties, entering text in the Notes field for the package, and then clicking 

OK. This note is any text you want to add such as who created the archive and what 

the archive contains. For example: 

You might also outline additional tasks required to adapt the archive into a new 

domain, or provide links to requirements and test documents for the verification of 

the elements in the new domain. The notes are retained in the ExportProperties.xml 

file that is created in the archive when you save the results. 

6. Choose Save As and name the archive. In this example, RIA.xar. 

The Sonic deployment archive is packaged and saved, ready for tailoring and import into 

another domain. 



In addition, you might want to output the files to the local file system. You can output 

directly to the file system by choosing Save to File System As. That creates a file structure 

identical to unpacking the XAR file. The only exception is that the export properties file 

is not created. As such, you cannot use files saved this way as the source for a command 

line rebuilding of the export files. To help you use this feature, you can set the select 

Options > Clean File System Before Write to clean out any files in that location in prior 

export actions. 

Chapter 4, “Analyzing ESB Artifacts in Archives, Stores, and File Systems,” shows how 

you can do analysis on either type of packaging. 

Viewing Messages 

You can choose View > Messages to review the sequence of steps taken by the export tool. 

The entries are date stamped and have colored alert flags for significant events worthy of 

special note or attention, as shown: 

Indicator flags call out the alert levels of each line item, as follows: 

● Red flags indicate errors, and when appropriate, provide a trace tab in the Message 

Details dialog box that opens when you double click on a message line. 

● Yellow flags indicate warnings. 

● Green markers set off the start and end points of actions. 

Messages that do not have indicator flags are informational only. 



Exporting ESB Artifacts With the ESB Admin Tool 

The Sonic ESB command line tool, ESB Admin Tool, performs export actions by adding 

all ESB elements, or those defined in the properties of an existing archive or an extracted 

archive properties file (ExportProperties.xml.) Using scripts, you can automate the 

process of connecting, starting the tool, opening an archive, and rebuilding the archive. 

The techniques under the command line tool are straightforward. Its use is appropriate for 

scripting the extraction of similar data from multiple systems. The archive files can be 

saved in change management or source control systems as binary objects. 

Note See “Sonic ESB Tools and Samples” chapter of the Progress Sonic ESB Configuration 

and Management Guide for more information about this tool. 

This technique for export either exports all the ESB elements in the domain or only the 

roots defined in an ExportProperties.xml file and then evaluated for their dependencies. 

That file is automatically created in an archive and is not intended for user editing. 

Starting the ESB Admin Tool 

The Sonic ESB Admin Tool provides a command-line interface for deployment. It 

provides commands for exporting to archives and the file system. These export commands 

can become part of a scripted set of commands. 

◆ To start the ESB Admin Tool for export 

Note A system must have a Sonic ESB Administration Tools installation or a Sonic Workbench 

installation to run this tool. 

1. Check that the source domain manager is running. 

2. On the system where you run the export process, start the ESB Admin Tool: 

■ Under Windows, choose: 

Start > Programs > Progress > Sonic 8.5 > Tools > ESB Admin Tool 


Tools, open a console window to the Sonic ESB installation directory, and enter: 

./bin/esbadmin.sh 

The ESB Admin Tool window opens. 


For a list of commands, enter: 

ESBAdmin> help (or ?) 

After you complete the export tasks with this tool, enter: 

ESBAdmin> disconnect 

ESBAdmin> exit (or bye) 

Using Scripts in the ESB Admin Tool 


You can create a text file of commands to run as a script. For example: 

1. Create a text file with the content: 

connect Domain1 localhost:2506 Administrator Administrator 

export archive c:\deploy\Samples.xar all 

disconnect 

2. Save the file as c:\deploy\exportAll.txt. 

3. Open a console window in the ESB8.5 directory, and then enter: 

c:\Sonic\ESB8.5> bin\esbadmin < c:\deploy\exportAll.txt 

Once you have developed tailoring maps, you can add scripted steps to apply maps, 

produce analysis reports, and import into the target domain. 

Connecting to the Source Domain 

To export from a domain, you must first connect to it. Enter the connection data for the 

domain using the following syntax: 

connect domain url [username password] [managementNode] 

For example, where security is required, but management nodes are not used: 

ESBAdmin> connect Domain1 localhost:2506 Administrator Administrator 

Connecting ... 

Connected to Directory Service at localhost:2506 



Using the Export Archive Command 

The export archive command syntax creates an archive file based on the properties or 

action specified in the command line: 

ESBAdmin> export archive target.xar [source.xar | export-prop.xml | all] 

where: 

■ target.xar is the path and name of the file (using the .xar extension) that is the 

deployment export package. If the archive file exists, it is overwritten. 

■ Use one of the following arguments: 

❑ source.xar — When an existing archive filename is specified, the export 

performs according to the export properties file located in that archive file, 

putting the results in the target archive file. If source and target are the same 

file, the archive is rebuilt. 

❑ export-prop.xml — If the argument is an .xml file with well-formed and 

valid export properties, the export performs according to that export 

properties file, putting the results in the target archive file. This is an 

advanced concept; typically, source.xar or all are used. 

❑ all — All elements in the Directory Service are packaged in the archive file. 

For example, you might periodically script a backup archive to check in to source control: 

ESBAdmin> export archive backup_myProject.xar all 


Using the Export FS Command 


The export fs command syntax creates a file system hierarchy for the exported files at 

the designated root on the local system: 

ESBAdmin> export fs targetFileStore [sourceFileStore | export_prop.xml | all] 

where: 

■ targetFileStore is the path and name of the Directory Service store on the local 

system; for example, c:\mySourceControlStaging\ 

■ Use one of the following arguments: 

❑ sourceFileStore — When an existing file system store is specified, the 

export performs according to the export properties file located in that file 

store, putting the results in the target file system store. If source and target are 

the same file system store, the store is rebuilt. 

❑ export-prop.xml — If the argument is an .xml file with well-formed and 

valid export properties, the export performs according to that export 

properties file, putting the results in the target archive file. This is an 

advanced concept; typically, source.xar or all are used. 

❑ all — All elements in the Directory Service are packaged in the archive file 

(the default value). 

Closing the Domain Connection and Stopping the ESB Admin Tool 

After you complete your export tasks with the ESB Admin Tool, close the administrative 

connection to the source domain, by entering: 


To stop the ESB Admin Tool, enter: 




Using Scripted Builds to Export ESB Artifacts 

Using scripted builds is a streamlined, reliable way to extract ESB artifacts for 

deployment. You specify the source locations you want to evaluate for ESB artifacts, and 

the target location for the output of the export process. Scripted builds have advantages 

and limitations. 

The advantages of scripted builds are: 

● They are applied against source control repository branches so that all checked in 

developer files are accessed concurrently and branches can be locked. 

● Ant build syntax and operations are familiar to build managers. 

● They do not require a running Sonic domain. 

● The build files and supporting properties files can be abstracted from the Sonic 

Workbench install location to run entirely in Ant and a Java SDK. 

The limitations of scripted builds are: 

● They do not support variable selection of files and correspondingly do not support 

rebuild from an export properties file. 

● They are constrained to only ESB artifacts and, at that, exclude ESB Containers. 

Supporting files packaged into exports must be handled by other export techniques. 

Important You must have a Java SDK installation accessible on a local or networked drive. 

You cannot use a Java Runtime Environment such as the JRE installed with SonicMQ. 

◆ To perform a scripted build of ESB artifacts: 

1. On a Sonic Workbench system, navigate to sonic_install_root\Workbench8.5 

tools\eclipse\plugins\com.sonicsw.tools.sonicbuild_85n. 

2. In your text editor, edit the com.sonic.build.user.properties file located in the 

resources folder as follows: 

a. Edit the line com.sonic.projects.src_list=Dir1,Dir2 to provide a commadelimited 

list of the projects from which to expand and extract ESB artifacts. 

Use forward slashes (/) regardless of platform. 

b. Edit the line com.sonic.out.target=targetDir to provide a target for the output. 

Use forward slashes (/) regardless of platform. 

3. Open a console to sonic_install_root\Workbench8.5. 

a. Set JAVA_HOME. For example, set JAVA_HOME=c:\jdk1.5.0_11 

b. Enter ant_executable -f build_file 


Example of a Scripted Build of ESB Artifacts 


The following steps describe setting up and running a scripted build of the Samples.ESB 

project in a Sonic Workbench installation on a Windows system. While resources in the 

workbench installation are used, no Sonic components or tools are running. The project 

used has not been imported, built, or uploaded. 

◆ To run a scripted build of the Sample.ESB project: 

1. Download and install C:\jdk1.5.0_11. 

2. Update the user properties file with the source and target locations, as shown: 

3. Open a console window to the sonic_install_dir\Workbench8.5 root, and then set the 

Java home variable, and then enter the Ant Build command as shown: 

The output location contains the evaluated and exported file set of ESB artifacts for 

deployment. 



4. When packaged in a Zip file with the extension .xar, the exported files are a tailorable 

export archive with the following content: 

The scripted build abstracted from the Sonic installation was successful. 

You could do a Java build on the project. The resulting classes could be packaged in a JAR 

that you add into the deployment archive. 



Extending Ant Scripts For Mapping and Import Functions 

When you use scripted builds to export ESB artifacts for deployment, you probably want 

to integrate the export script with the Java build process and the import process. 

You should also handle domain mapping functions (an archive-only process) and 

accessing ESB Admin commands from within the Ant script. 

As described in “Mapping ESB Artifacts to Target Domains” on page 59, mapping is an 

archive-only operation. You can manage that in your script by moving your ESB artifacts 

into a Sonic deployment archive form, doing the mapping from defined map definition 

files for the target domain, and then importing the mapped archive into the target domain. 

The following excerpted procedures outline these operations. The example uses these 

variables you might want to consider in your scripts: 

 

 

 

 

 

 

● Packaging a set of files into a XAR file: 

 

 

 

 

 

● Launching the ESB Admin Tool and then directing mapping scripts to run: 

The XQCommandline launches the ESB Admin Tool. The xarmapfile property specifies 

a script that is redirected into the ESB Admin Tool. 

 

 

 

 

 

 



In this example, XQCommandline launches the ESB Admin Tool. The xarmapfile 

property specifies the script that is redirected into the ESB Admin Tool. 

The script mapUAT.script does applyMap for your defined User Acceptance Test map 

and analysis report commands might look like this: 

applyMap C:\TheProject.xar C:\UAT_map.xml C:\TheProject_UAT.xar C:\UAT.log 

diff -xar C:\TheProject.xar -xar C:\TheProject_UAT.xar -out C:\diff_UAT.xml 

● Extending the mapping script to import the mapped archive into the target domain 

The archive for the target domain is well packaged so you can extend the ESB Admin 

script to connect to the target domain and perform the import: 

connect DomainUAT tcp://UAT_host:2506 UAT_Administrator UAT_Administrator 

import archive C:\UAT_staging\TheProject_UAT.xar override 

bye 


Chapter 3 Mapping ESB Artifacts to Target Domains 


● “Overview of Mapping Sonic Deployment Archives” 

● “Defining Scripts to Automate Deployment” 

● “Incrementally Updating or Building Domains” 

● “Implementing Domain Builds and Updates” 


Chapter 3: Mapping ESB Artifacts to Target Domains 

Overview of Mapping Sonic Deployment Archives 

The configurations packaged in Sonic deployment archives are deployment 

configurations that will be bound to destinations, connections, and the file system in a 

target domain. Mapping requires that you step through the process of creating the export 

definitions, the tailoring rules, the maps, and the import rules that will result in a 

successful import into a target domain. 

Once you establish files used in the end-to-end procedure of export, map, and import, you 

can create scripts that automate the process. 

While it is typical to script the export process to the point where the mapped archive is 

contrasted with the target domain to review its impact in reports, you can script the 

complete end-to-end process. 

This chapter shows how to perform the individual processes, how to script those 

processes, and how to apply the processes in both static test domains, in dynamic preproduction 

stages, and in the live production environment. 

Progress Sonic ESB provides tools for mapping Sonic ESB configuration elements from 

development to deployment domains, as outlined in Chapter 1, “Introduction.” 


Workbench 

Domain 

- ESB Artifacts 

- SonicFS files 

Directory 

Service 

Export 

Archive 

a 

Exported Deployment Archive 

Overview of Mapping Sonic Deployment Archives 

The following illustration shows the steps in creating a Sonic deployment archive, and 

then tailoring and mapping the archive to a target domain. 

f 

c 

CreateMap 

for Archive 

Analysis of Directory Services, 

archives, and file stores 

Differences 

Impact analysis 

SonicMQ dependencies 

SonicMQ reverse dependencies 

Edit Map 

Parameters for 

Target Domain 

b 

Map File Edited Map File 

Tailoring Rules 

Tailoring and Map export archive 

Deployment 

Domain 

d e 


Import Tailored 

Archive 

Mapped Archive 

Import Log File 

Map Log File 

The steps (as shown in the illustration) to map elements from one domain to another 

include: 

a. Export Archive — Specify the configuration elements to copy from a source 

domain manager into an archive file. Export the selected files and configuration 

elements from the source Directory Service to a deployment archive file (.xar). 

See Chapter 2, “Exporting ESB Artifacts for Deployment,” for more information. 

b. Tailoring Rules — Review the default tailoring rules file to see if you want to 

create custom tailoring rules. See “Adjusting Tailoring Rules to Apply When 

Creating Map Files” on page 67 for more information. 

c. Create Map for Archive — Create a map from the deployment archive. 

See “Applying Tailoring Rules and Creating a Map File for an Archive” on 

page 73. 


h 

Apply Map 

i 

g


d. Edit Map Parameters for Target Domain — Edit the map file to adjust 

development references and paths to preferred names in the deployment domain. 

Adjust any parameter values that should be changed in the deployment domain. 

“Editing the Map File for a Target Domain” on page 78 for more information 

e. Apply Map — Apply the edited map file to the exported archive to create a 

mapped archive. See “Adjusting and Applying a Map File to an Archive” on 

page 78 for more information. 

f. Analysis of Directory Services, Archives and File Stores — Produce analysis 

reports to review the dependencies and impact of the changes in the target 

domain. See “Analyzing ESB Artifacts in Archives, Stores, and File Systems” on 

page 95 for more information. 

g. Map Log File — Review the map log file to confirm that the mappings and 

parameter changes are correct. See “Reviewing the Mapping Log” on page 80 for 

more information. 

h. Import Tailored Archive — Define import properties to filter the deployment 

archive with overwrite capabilities on selected files, and ignore specified files, 

and then import the archive into the target domain manager. See Chapter 5, 

“Importing Deployment Artifacts into a Domain” for more information. 

i. Import Log File — Review the import log to certify that the changes took place 

as expected. 

You can produce analysis reports after the import completes to verify the changes. 


Tailoring rules define standards for transforming names and paths in the source domain 

(typically development), and for specifying the types of services, endpoints, and 

connections that will be exposed for mapping. For each of those types, the parameters that 

can be tuned at the mapping level are listed. Start by getting familiar with the structure 

and content of the default tailoring rules file at sonic_install_dir/ESB8.5/deploy. 

You will learn how you an use tailoring rules to create map files that you edit and then 

apply to an archive. You will also learn how to customize the tailoring rules so that map 

files always define your preferred rules, and extract parameters you want to tailor. 


Default Tailorings 


The following section reviews each section and subsection of DefaulTailorRules.xml. 

● DevEnvRules — The reference names used in the Workbench are typically updated for 

deployment environments. 

■ stringReplaceMaps — These maps adjust path names of artifacts as well as 

references to these same strings that are embedded in other artifacts. The default 

pattern is to remove the workspace folder level. 

 

 

 

 

■ DevServiceMaps — These DevEnvRules provide mapping of references in service 

configurations in the development environment to service configurations for 

service types that will be defined in deployment environments. Generic service 

configurations are defined in the development domain with the prefix dev. This 

mapping assumes that you will set up similar service configurations names that 

use the prefix global. The default DevServiceMap tailorings are as shown: 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

■ DevEndpointMaps — These DevEnvRules provide mapping of references of 

endpoint configurations in the development environment to endpoint 

configurations for service types that will be defined in deployment environments. 

Generic endpoint configurations are defined in the development domain with the 

prefix dev. This mapping assumes that you will set up similar endpoint 



configurations names that use the prefix global. The default DevEndpointMap 

tailorings are as shown: 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

That completes the DevEnvRules section. 



● ServiceRules — The next part of the default tailor rules file contains the 

ServiceRules. The listed services will be exposed in map files you create so that you 

can tune the parameters you expose in the map and then apply those changes to the 

archive before import into a target domain. The default service rules are as follows: 

 

 

 

 

 

 

 

Continued 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 



Continued 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

● EndpointRules and ConnectionRules — These rules enable tailoring of instances of 

the JMSType to expose the parameters that are typically redefined in each target 

domain. 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 



Adjusting Tailoring Rules to Apply When Creating Map Files 

You might accept the generic tailoring of this file, choosing instead to adjust the output 

maps you create. 

But when you find that you are copying and pasting the same variations into every map 

you create, you might want to customize the default rules file into variations that you use 

under different circumstances. Then, maps that you create are predictable and consistent. 

Edit a Copy of the Default Tailoring Rules File 

When you add a new service type, you must extend the tailoring rules file to include the 

new type and its tailorable parameters. For configuration elements that are listed in the 

rules file, you can add parameters for tailoring. Each configuration element’s 

configuration file lists its valid parameters. Similarly, if there are parameters in the default 

rules file that you never change from one domain to another, you can remove them from 

the rules file. The following example describes tuning a map for development references, 

adding a service type, and adding a parameter to an existing service type: 

1. Copy the ESB installation directory’s file, deploy/DefaultTailorRules.xml. 

2. Save the copied file as sonic_install_dir/ESB8.5/deploy/myTailorRules.xml. 

3. Edit myTailorRules.xml as follows: 

■ “Revising and Extending String Replace Maps” on page 68 

■ “Adjusting Dev Service and Dev Endpoint Maps” on page 69 

■ “Adding New Service Types” on page 69 

■ “Adding Parameters to Existing ServiceTypes” on page 70 

■ “Adjusting EndpointRules” on page 70 

■ “Adjusting ConnectionRules” on page 70 

■ “Adding Property Mapping Rules” on page 71 

4. Save myTailorRules.xml. 

When you run a CreateMap command (see page 73), use the rules file parameter with the 

explicit path sonic_install_dir/ESB8.5/deploy/myTailorRules.xml. 

The map file that it outputs will reflect your tailoring rules. 



Revising and Extending String Replace Maps 

The stringReplaceMaps section, by default, removes workspace from the sonicfs paths. 

You can tune this line if, for example, you routinely want the deployed files from a 

development workspace to map to a directory structure named com.myCorp, as follows: 

 

Important Always replace the name workspace — While you can revise the string replacement of 

sonicfs: path references from workspace to no name or any specified name, you should 

never leave the name workspace in a deployment configuration as it might trigger 

behaviors not intended for deployment environments. 

You can extend the stringReplaceMaps section to include multiple steps. The added steps 

must each have an order parameter set to an incrementing integer value. As shown in the 

following code segment, the stringReplaceMap line where order=”1” is evaluated first, 

then the result is recursed with the line where order=”2”. After the sequence has been 

completed, the default stringReplaceMap applies, as shown: 

 

 

 

 

If you use order steps you must have one instance of each sequential step, but the listing 

of the steps need not be in order. 

References within files — String mappings also apply to strings within files, even if they 

are packaged within the XAR (such as a CSAR package). You need to be careful in raw 

string replacements to qualify your search string, and to avoid mapping key words, fixed 

namespaces, and related artifacts by string replacement. This feature is most useful for 

replacing URLs and references. For example, the following line might be for mapping 

references to targets used in the test environment: 

 


Whereas the same line in the production map might be: 


 

Constraining references to a specified file — You can limit a string replacement to a 

specific file by adding the artifactName attribute, as shown for Readme.txt: 

 

Phases of tailoring — String replacement can be applied in the tailoring rules which 

propagate to map file. The map files can be extended or further edited. For example, you 

could either: 

● Do general changes in a general tailoring file—such as replacing 

sonicfs:///workspace/ with sonicfs:///com.myCorp/—and refine the projectspecific 

mappings in the map file for each target domain. 

● Do detailed changes in project-specific tailoring files so that map files can focus on 

finer tuning—such as the routings and quality of service—for each target domain. 

Adjusting Dev Service and Dev Endpoint Maps 

The transition from development to deployment means leaving behind the notion of a 

workspace, and mapping away from preset services and endpoints that are maintained and 

automated within the development environment. 

The sections DevServiceMaps and DevEndpointMaps map references that start with dev. to 

references that start with global. instead. 

You might want to change the prefix from global. to a general name that is focused on 

your work, such as com.myCorp or your customer’s project, such as EuroATM. 

Adding New Service Types 

When new service types are added, you can add the service type to the tailoring rules so 

that you can expose the parameters in its properties file for tuning in the map files. 

For example, if you were packaging the Sonic.ESB Sample.AuditServiceType, you might 

add the following lines to the tailoring rules file at the end of the ServiceRules section: 

 

 

 

 

 



Adding Parameters to Existing ServiceTypes 

The parameters of an ESB configuration element define its functionality and its bindings 

to a target domain’s requirements, service levels, and physical topology. While the 

functionality is intended to stay constant, the bindings must be adjusted when the ESB 

element is brought into another domain. 

While predefined service types expose the most common parameters for tailoring, you 

might want to add (or remove) some parameters that can be mapped. 

For example, the configuration file for the service SplitJoinForEach.xml has several init 

parameters, only two of which are stated as required in the default tailoring rules file. If 

you want to tailor the Boolean parameter Keep Original Part to toggle from its default 

value false to true in deployment, add its parameter in your tailoring rules file as follows: 

 

 

 

 

 

Adjusting EndpointRules 

For an endpoint, you need to be aware of required destination names, particularly for the 

type QUEUE as queues must be statically defined before they are referenced. These queues 

will need to exist in the target domain. Other endpoint parameters are generally accepted 

as they have been defined. 

You might also provide a preferred name or pattern for destinations. For example, you 

could redefine a destination name RIA.entry to be controlled by ACLs you define for 

com.myCorp.# by changing the destination name to com.myCorp.RIA.entry. 

Adjusting ConnectionRules 

For a connection, the parameters exposed provide the parameters for management 

connection in the target domain, as well as SSL parameters that specify locations on local 

systems. Or, if you do not use SSL for management connections, you could leave those 

parameters off the tailoring rules so that they are not exposed. 



Adding Property Mapping Rules 

You can append a PropertyRules section at the end of the tailoring rules file to enable 

mapping the value of a specific property name to your preferred value. For example: 

... 

 

 

 

 

 


Using StringReplace and PropertyReplace Content Change Rules 

The content change rules, StringReplaceMaps and PropertyReplaceMaps, are closely 

related. The following sections contain information about using both types. 

Rule Processing 

When you apply a map, its content change rules are processed as follows: 

1. PropertyReplaceMaps are processed before StringReplaceMaps and are checked for 

named rules and generic rules. 

■ If both a named rule and a generic rule exist, and both affect the same property, 

the named rule takes precedence over the generic rule. Best practice is to make 

sure that a named property file contains only one instance of a named property, 

because multiple instances may cause unpredictable results. 

■ If multiple generic rules exist, they are processed in a top-down manner. If 

multiple generic rules affect the same property, the last rule found in the map (that 

is, the rule nearest to the bottom) takes precedence. Best practice is to have only 

one generic rule. 

■ Generic rules extend to all properties files in the XAR and any component 

packages. Best practice is to use only named properties files, unless you are 

comfortable with changing properties globally. 

2. After all PropertyReplaceMaps are completed, StringReplaceMaps are processed. 

■ StringReplaceMaps are checked to determine the order of rules (specified with the 

order attribute) and then processed in the specified order. Unordered rules are 

processed after ordered rules. 

■ You can add an artifactName property to a StringReplaceMap to constrain its 

scope to the named file. But the rule is still processed in the stated order. 

■ If there are multiple unordered StringReplaceMaps, they are processed in a topdown 

manner. Best practice is to use only ordered rules, because multiple rules 

with no specific order may cause indeterminate results. 

Creating Properties Files 

It is good practice to make additional copies of properties files in preparation for tailoring. 

For example, copying ESBToREST.properties to ESBToREST_test.properties and 

ESBToREST_production.properties in SonicFS makes tailoring a bit easier. The alternative 

would be to extract the properties file from the XAR, make a named copy, and then add 

them back in to the XAR. 



Applying Tailoring Rules and Creating a Map File for an Archive 

Once the tailoring rules are complete, you can generate a map file from an archive. The 

tailoring rules will specify what is included in the map. Then you edit the map for the 

settings you want to adjust in the target domain. Then the edited map will ruin against the 

original archive to create a mapped archive. 

Creation of a map for an export archive is achieved by running an ESBAdmin command with 

the source archive and the output map file as parameters. The default tailoring rules are 

applied unless you specify a custom rules file. Note that file path names are fully 

enunciated. 

For this example, the export file RIA.xar created in the “Exporting ESB Artifacts for 

Deployment” chapter is used in the ongoing example. 

◆ To create a map file from a source archive and use default tailoring rules: 

1. Start the ESB Admin Tool. 

2. Enter: ESBAdmin> createMap source_archive map_file 

For this example: ESBAdmin> createMap c:\RIA.xar c:\RIA_map.xml 

You can now edit the map you created to specify its parameters for the target domain. 

◆ To create a map file from a source archive and apply modified tailoring rules: 

If you created custom tailoring rules, as described in “Adjusting Tailoring Rules to Apply 

When Creating Map Files” on page 67, reference the file you saved, as follows: 


2. Enter: ESBAdmin> createMap source_archive map_file [rules_file] 

For this example: ESBAdmin> createMap c:\RIA.xar c:\RIA_map.xml 

c:\myTailorRules.xml 

You can now edit the map you created to specify its parameters for the target domain. 



The content of RIA_map.xml when using the default tailoring rules is as follows: 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Operation Router 

 

 

 

getPhoneAccountActivity 

 

 

 

getTVAccountActivity 

 

 

 

getWirelessCellAccountActivity 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

CombineAllAccounts 

 

 

 

Format Result 

 

 

 

 


continued 


continued 

 

 

 

 

 

 

 

 

 

 

 

 


 

 

 

getAccounts 

 

 

 

getAccountActivity 

 

 

 

 

 

 

 

 

 

 

 

 



If you did the changes in “Revising and Extending String Replace Maps” on page 68 and 

“Adjusting Dev Service and Dev Endpoint Maps” on page 69, the map file would be: 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 


 

 

 

getPhoneAccountActivity 

 

 

 

getTVAccountActivity 

 

 

 

getWirelessCellAccountActivity 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

CombineAllAccounts 

 

 

 

Format Result 

 

 

 

 


continued 


continued 

 

 

 

 

 

 

 

 

 

 

 

 


 

 

 

getAccounts 

 

 

 

getAccountActivity 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 



Adjusting and Applying a Map File to an Archive 

Once you defined your tailoring rules (see “Adjusting Tailoring Rules to Apply When 

Creating Map Files” on page 67), and used those rules to create a map file for an ESB 

export archive (see “Applying Tailoring Rules and Creating a Map File for an Archive” 

on page 73), you can edit the map file for a target domain and then generate a mapped 

archive, ready for import into a target domain. 

Editing the Map File for a Target Domain 

In your preferred text editor, open the map file you created—RIA_map.xml. If you intend 

to import the same archive into multiple domains, you can save a step by copying the map 

file you created and then editing a copy to tune it to each target domain. 

For this example, the timeToLive is modified in the map file from 0 (forever) to 10000 

(msecs) for the getAccountyActivity process for use in Developer Integration Testing: 

 

 

 

... 

Additional String Replacements in the Map File 

You might do string mapping in the map file. See “Revising and Extending String Replace 

Maps” on page 68 for more information. Keep in mind that once string replacements have 

been applied in tailoring, any string replacement in the map file applies to the text patterns 

in the tailored XAR. 

When a tailoring is prepared for an archive, you can apply the map file to the original 

source archive to generate a new archive that has the map instructions applied to the 

archive. The log option provides a detailing of the actions that occur. 

As this is the map file for RIA deployment into the Developer Integration Testing (DIT) 

domain, save the file as RIA_map_DIT.xml. 

Note If you are rerunning an applyMap command, it is good practice to relocate or delete an 

existing mapped archive file that has the same name and target location. 


◆ To apply an edited map to a source archive and create a mapped archive: 

❖ In the ESB Admin Tool, enter: 


applyMap source_archive.xar map_file.xml mapped_archive.xar [log_file.xml] 

For example, to execute this command against the sample RIA.xar and the 

RIA_map_DIT.xml file you created, you might name the output file RIA_DIT.xar, and the log 

file RIA_DIT_log.xml. Therefore, the command would be: 

applyMap C:\RIA.xar C:\RIA_map_DIT.xml C:\RIA_DIT.xar C:\RIA_DIT_log.xml 

The process creates the target tailored XAR, RIA_DIT.xar and the mapping log, 

RIA_DIT_log.xml. The string replacements are apparent in the XAR files. 

● Original XAR: 

● Mapped XAR: 



... 

... 

Reviewing the Mapping Log 

The application of the map to the archive creates a log. In this example, the output file is 

RIA_DIT_log.xml. The following shows excerpts from the mapping log for the example 

along with the old values and new values for each change: 

 

 

Sample.RIA.getAccountActivity 

Process 

 

Reject Endpoint Reference 

dev.RME 

com.myCorp.RME 

 

 

Tracking Level Endpoint Reference 

dev.Tracking 

com.myCorp.Tracking 

 

 

Itinerary Endpoint Reference, Step: Operation Router 

dev.CBR 

com.myCorp.CBR 

 

 

TTL 

0 

10000 

 

 

 

Sample.RIA.getAccountActivity 

ESB 

 

String replacement 

sonicfs:///workspace/Sample.RIA/Sample Data/ 

sonicfs:///com.myCorp/Testing/RIA/Data 

 

Importing the Mapped Archive into the Target Domain 

Chapter 5, “Importing Deployment Artifacts into a Domain,” describes the creation of 

import rules and the import process. 


Defining Scripts to Automate Deployment 

Defining Scripts to Automate Deployment 

The preceding tasks created work files to enable scripting of the same process. The steps 

in Table 1 show how the steps can be used in scripts once their files are defined. 

Table 1. The Deployment Process Steps from Initial Deployment to Scripted Deployment 

Step Initial Use Subsequent use 

a Export archive X from 

source domain 

Define export roots from 

domain into a Sonic Archive 

(XAR) file. 

b Adjust tailoring rules No action required, but adjust 

as needed. 

c Create map for 

archive X 

d Edit archive X map for 

target domain Y 

e Apply map to archive 

X and create archive Y 

f Create X-Y analysis 

reports 

createMap command, 

referencing tailoring rules when 

not using the default file 

Adjust values of exposed 

parameters and string 

references. 

applyMap command to exported 

archive referencing the map file 

and naming the mapped archive 

Use interactively to discover 

which types suit your 

requirements. 

g Review Y map log See if changes were applied as 

expected. 

h Define / review 

Y import rules then 

Import into Y domain 

Select overwrites and deselect 

features not to apply. 

Import through GUI tool to 

create import rules. 

Connect to domain and then 

rebuild using the predefined 

roots. 

No action required. - 

You reuse maps after they are 

edited so they are recreated 

only when basic changes 

occur. 

Minor edits usually tune the 

archive for changes in the 

target. 

applyMap command to 

exported archive referencing 

the map file and naming the 

mapped archive 

Define a set of analyses that 

are tied closely to an export 

script. 

Could be generated to standard 

output to document the 

scripted process. 

Stored import rules can be 

accessed by scripts. 

import command with import 

rules or merge. 

Used in 

Scripts? 


Yes 

- 

- 

Yes 

Yes 

Yes 

Yes


For example, the following code sample is an end-to-end script that exports from a 

domain under defined roots, applies its defined map, produces several analysis reports, 

and then imports into a defined target domain using defined import rules: 

connect Domain1 releaseManager:2506 Administrator Administrator 

export archive c:\dev.xar c:\exportProperties.xml 

disconnect 

applyMap c:\dev.xar c:\2\map1.xml c:\2\mapped1.xar c:\2\mapped2_log.xml 

diff -xar c:\dev.xar -xar c:\1\mapped2.xar -out c:\2\vDiff_xar_xar2.xml -v 

diff -xar c:\dev.xar -xar c:\1\mapped2.xar -out c:\2\tDiff_xar_xar2.xml 

mqdepends -xar c:\2\mapped2.xar -out c:\2\mqDepends.xml 

mqrevdepends -xar c:\2\mapped2.xar -out c:\2\mqRevDepends.xml 

connect Domain2 StageTwo:2526 Administrator StageTwoPassword 

impact -xar c:\2\mapped2.xar -out c:\2\tImpact_XAR2_DS2.xml 

-ds Domain2 StageTwo:2526 Administrator StageTwoPassword 

impact -xar c:\2\mapped2.xar -out c:\2\vImpact_XAR2_DS2.xml 

-ds Domain2 StageTwo:2526 Administrator StageTwoPassword -v 

import archive c:\2\mapped2.xar c:\2\2_import.xml 

disconnect 

bye 

That series of commands in Sonic ESB Admin Tool syntax, when saved as a text file such 

as End2End.txt, lets you create a script file that pipes in the command sequence, such as: 

C:\Sonic\ESB8.5\bin\esbadmin < c:\2\End2End.txt 

Once defined, the sequence of steps in the illustration on page 61 can be scripted. The 

script overlaying the image in the following illustration shows an end-to-end development 

to deployment process that is reliable, consistent, and fully documented: 

Workbench 

Domain 

- ESB Artifacts 

- SonicFS files 

Directory 

Service 

Exported Deployment Archive 

Analysis of Directory Services, 

archives, and file stores 

Differences 

Impact analysis 

SonicMQ dependencies 

SonicMQ reverse dependencies 

Scripted Export Procedure, Mapping, and Import 

Deployment 

Domain 


Import tailored 

archive 

- Connect to the Workbench Domain. 

- Export archive using the previously defined export properties 

Mapped Archive 

- Disconnect. Export 

D 

archive 

C 

E 

- Apply the map that was previously defined to map the exported archive for this deployment domain. 

Edit Map 

- Output the map log fileCreateMap 

A 

Parameters for 

Apply Map 

- Generate a report that for shows Archive the differences between thie exported archive and the mapped archive. 

Target Domain 

- Generate a report that shows the SonicMQ dependencies in the mapped archive. 

- Connect to the deployment domain Map File Edited Map File 

- Generate a report that shows Bthe 

impact of the mapped archive on this deployment domain. 

- Import into the deployment domain Tailoring using Rules the preeviously definred import rules. 

- Output the import log file. 

- Disconnect. 

- End the script. 

Tailoring and Map export archive 

Import Log File 

Map Log File 


G 

H 

F

Incrementally Updating or Building Domains 


You can update the ESB elements in a domain or, for testing environments, initialize the 

domain so that only the packaged ESB elements populate the domain after import. 

Incrementally Updating a Domain 

When importing files into a target domain, the existing Directory Service is usually 

populated with existing ESB elements, as shown in the following illustration: 

UPDATE scripts 

Target Domain 

Directory 

Service 

POPULATED 

Import Rules 

- Overwrite 

- Ignore 

The changes you apply must reconcile the incoming files with existing files so that any 

potential file overwrites clearly determine whether the incoming files take precedence 

over (overwrite) the existing files or not (ignore). 

Update scripts must submit archives to the target domain in a specified sequence so that 

the decision to ignore or overwrite changes in multiple archives achieves the expected 

final result. 

The archive packaged after successful integration testing is imported into an advanced 

staging domain or production as an incremental update. In live stages, the more elaborate 

distributed resources and existing ESB elements are not easily decoupled, so their 

Directory Services are incremented by files selected in import properties files and 

matching files are resolved to determine which of the matched files is retained. 



Building ESB Elements into a Domain 

A build strategy is viable in a static domain where the physical installations are retained, 

but the Directory Service is discarded and a ‘clean’ base-level Directory Service is 

restored, as shown in the following illustration: 

BUILD scripts 

Target Domain 

Directory 

Service 

Flush and 

Restore with 

'Clean' DS 

The base level Directory Service structure is the foundation for the next build. The build 

strategy is useful only when the underlying domain manager is static, a situation that 

exists only on Sonic Workbenches and its deployment analog, the Developer Integration 

Test (DIT) environment. Because the DIT domain manager is narrowly defined and rarely 

reconfigured, a basic setup of the domain manager can be created, ESB-enabled, and then 

backed up and stored offline. 

The build scripts start by deleting the existing DIT Directory Service and then restoring 

the Directory Service from its backup. As a result, the imported ESB elements will 

encounter no file matches and there are no orphaned files to delete. 

This build technique propagates the selected branch of the source control repository into 

the target domain. 

You can use these methodologies in different ways at different deployment levels. For 

example, the techniques for deployment from development to integration testing might be 

a build process, while advanced staging uses incremental changes. 



Deciding on Export or Promotion Through Stages 

The flow or deployment sets from development to production can: 

● Enter a stage, and then be redeployed to move to the next stage. 

● Enter a stage, and then determine whether the original deployment set should enter 

the next stage. 

Many deployments build the initial stages and use incremental change in the later stages. 

Exporting Through Stages 

Using this technique, satisfactory completion of a stage is characterized by exporting the 

changes that will be applied in the next stage, as illustrated: 



Eclipse Project Workspace 

Checkout / Checkin 

Update View 

Source 

Control 

Repository 

Read source files and artifacts in branch 

This illustration shows: 

Runtime Deployments 



Developer 

Integration 

Directory 

Service 

User 

Acceptance 

DIT UAT LIVE 

Flush and 

Restore with 

'Clean' DS 

DIT Mapped Archive 

DIT Mapping Rules 

BUILD 

scripts 

Production Environment 

● The build strategy used in the Developer Integration Testing (DIT) environment— 

refresh the base level Directory Service, tailor the incoming archives, then apply 

import (at this stage, you might ignore nothing and overwrite everything unless you 

have a series of archives). 


Export 

Directory 

Service 

Import Rules 

- Overwrite 

- Ignore 

UAT Mapped Archive 

UAT Mapping Rules 

UPDATE 

scripts 

Export 

Directory 

Service 

Import Import Import 

Promoted 

to UAT 

Released to 

Production 

Import Rules 

- Overwrite 

- Ignore 

LIVE Mapped Archive 

LIVE Mapping Rules 

UPDATE 

scripts


● A single deployment archive is exported from DIT for incremental update in User 

Acceptance Testing (UAT) where it is tailored and passed through import rules. There 

might be conflicts. When conflicts are resolved, an archive is exported. 

● The UAT export archive carries the changes into production where, after tailoring, the 

issue resolutions discovered in UAT are similarly applied. 

Promotion Through Stages 

Using this technique, satisfactory completion of a stage is characterized by notifying the 

managers of the next stage that the version that it tested is ready for access, mapping, and 

import from the same source, as illustrated: 



Eclipse Project Workspace 

Checkout / Checkin 

Update View 

Source 

Control 

Repository 

This illustration shows: 

Runtime Deployments 



Developer 

Integration 

Read source files and artifacts in branch 

Directory 

Service 

User 

Acceptance 

DIT UAT LIVE 

Flush and 

Restore with 

'Clean' DS 

DIT Mapped Archive 

DIT Mapping Rules 

BUILD 

scripts 

Production Environment 

● The build strategy used in the Developer Integration Testing (DIT) environment is the 

same used in the promotion-through-stages strategy. 

● Advanced staging and the production environment build from the same source files 

and import the same ESB artifacts as the DIT stage. This strategy keeps the path from 

the release management branch to the target stages consistent and easier to reconcile 

when errors are observed. 


Directory 

Service 

Import Rules 

- Overwrite 

- Ignore 

UAT Mapped Archive 

UAT Mapping Rules 

UPDATE 

scripts 

Directory 

Service 

Import Import Import 

Import Rules 

- Overwrite 

- Ignore 

LIVE Mapped Archive 

LIVE Mapping Rules 

UPDATE 

scripts

Implementing Domain Builds and Updates 


The next sections describe in detail the procedures for using the build and update 

strategies. 

Using the Build Strategy on a Static Target Domain 

The following steps describe how to use the build technique for a basic, static domain such 

as Developer Integration Testing. 

◆ To implement build techniques for a Domain, complete the following tasks: 

1. “Create a Base Level Directory Service Structure” on page 87 

2. “Specify the Build Content” on page 88 

3. “Run the Build for the Test Domains” on page 88 

4. “Bind the ESB Elements to the Domain” on page 88 

5. “Dump Endpoint Lists and Iterate Queue Creation” on page 88 

6. “Test the Build” on page 89 

The following sections detail each of these tasks. 

Create a Base Level Directory Service Structure 

A base level Directory Service is the foundation for many different deployment tests. 

Once you create it, you refresh the working Directory Service with the base level 

Directory Service to reset the domain, as detailed here: 

1. On the system where you want to set up an integrated testing environment, use the 

Sonic Installer to install a Domain Manager with an MQ and an ESB license key. If 

you intend to deploy Sonic BPEL Server, enter its key as well. Start the Domain 

Manager’s container. 

2. Connect to the domain through the Sonic Management Console to enhance the base: 

■ Add some global services and endpoints to simplify initial bindings for mapped 

artifacts. See “Adjusting Dev Service and Dev Endpoint Maps” on page 69 for 

more about these mapping targets. 

■ Set up management and ESB Containers that correspond to the development 

containers. For example, dit_Test and dit_Core. 

3. Stop the Domain Manager. Archive this clean Directory Service store. 

4. Save the backup archive file. You will use it routinely to refresh the build domain. 



Specify the Build Content 

The content of a build is typically determined by the release management team through 

their branch mechanisms in source control and their build scripts that build JARs and 

package ESB artifacts on the specified branch. 

Run the Build for the Test Domains 

When you want to do a build in developer integration testing, refresh the Directory 

Service, then import the archives. 

◆ To run the build in integration testing: 

1. Flush the existing structure by stopping the domain manager's container, and then 

deleting the Directory Service folder. 

2. Recreate the Directory Service store from the base level Directory Service backup 

you created. 

3. Use the Deployment Archive Import Tool to import the archives targeted for the build 

into the restored clean Directory Service store. 

Bind the ESB Elements to the Domain 

The components of the built domain must be bound to the domain infrastructure. 

◆ To bind ESB elements to a domain: 

1. Bind the connections and endpoints to the management node. If you did tailoring, 

these are key parameters of the mapping process, so you do not have to do them now. 

2. Create management containers that connect to the management node. 

3. Create ESB Containers for the imported services, then add the ESB Containers to 

appropriate management containers. 

Dump Endpoint Lists and Iterate Queue Creation 

Because queues are static objects, they must be explicitly created before they can be used. 

When a deployment contains many endpoints, you might want to programmatically set 

the queue endpoints on the appropriate messaging node. 


◆ To dump endpoint lists and iterate queue creation: 


1. In a dumped archive or file structure, create an iterator over the elements in 

ESB\Endpoints\. On each item, examine the file to see if type is QUEUE. For each queue 

item, output its destination value to a list. 

2. Create an application based on the SonicMQ ConfigBean/CreateQueue sample that 

connects to the domain and then adds each listed item as a queue. 

Test the Build 

Run the services in the test domain. You might want to import the test plans into SonicFS. 

When the test run is complete, the Directory Service on the Developer Integration Testing 

system can be refreshed to the base level DS structure in preparation for the next build. 

After the developer tests are complete, archive export and import techniques are generally 

appropriate for advanced staging and production environments. 

Using the Update Strategy on Dynamic Target Domains 

The following procedure describes how to use the update strategy for complex, evolving 

domains such as User Acceptance Testing and the production environment. The dynamic 

nature of the configured SonicMQ objects in advanced staging or production makes it 

difficult to isolate a Directory Service that produces a base level, yet is cleared of all ESB 

elements. 

When you import into an existing logical structure, you risk file name conflicts that can 

cause new services or existing services to perform in unexpected ways. Further, 

incremental changes that are updates of existing deployments might no longer use some 

files that should be removed. 

The advantage of incremental deployments is that existing services are bound to 

management containers so only new elements must adapt to the new domain. 

◆ To implement update techniques for a Domain, complete the following tasks: 

1. “Build or Export the Set of Changes Moving into Deployment” on page 90 

2. “Map Archives for the Target Domain” on page 90 

3. “Review Developer Documentation on Setup and Cleanup” on page 90. 

4. “Backup the Directory Service” on page 91 



5. “Run a Scripted Update Sequence” on page 91 

6. “Evaluate Target Overwrites” on page 91 

7. “Dump Endpoint Lists and Then Iterating Queue Creation” on page 93 

8. “Manage Imports, Containers, and Installed Sonic Products” on page 93 

9. “Evaluate Change Requirements in JavaScript, and ebXML Files” on page 93 

10. “Test and Accept or Rollback” on page 93 

The following sections detail each of these tasks. 

Note See “Importing Deployment Artifacts into a Domain” on page 105 for update techniques. 

Build or Export the Set of Changes Moving into Deployment 

Use the archive or file set methods described in Chapter 2, “Exporting ESB Artifacts for 

Deployment.” 

Map Archives for the Target Domain 

If you used the archive method, create and apply the map for the target domain. See 

“Applying Tailoring Rules and Creating a Map File for an Archive” on page 73 for more 

information. 

Review Developer Documentation on Setup and Cleanup 

Ideally, the development and QA teams add their test procedures and notes to the archive. 

For example, queues that are expected to see high traffic can be properly placed in highspeed 

clusters. Or, for updated deployments, any elements that are no longer in use can be 

deleted in the updated domain (a manual task). 


Backup the Directory Service 


Before starting incremental changes, you should stop the management container, and then 

back up the Directory Service store before you perform archive imports. If imports and 

regression testing do not succeed, you can revert gracefully to the prior configuration. 

Important An import procedure that considers restoration of the Directory Service as a recovery 

technique should lock out administrative changes to the Directory Service until the 

import is complete and verified. When you start the domain manager after backup, you 

could revise the password for administrative users until the import procedure is complete 

and then change it back. 

Another tactic is to install the administrator tools on the target domain manager system. 

Then, when the import file is copied to that system, the domain manager can drop its 

network connections until the local user completes the import procedure (or restores the 

previous directory service.) That tactic can be quite effective when using fault tolerant 

management components at a remote site. In that case, when you back up the primary 

Directory Service and copy it to the backup location, set it to not accept updates. Then, 

when you take the primary Directory Service offline the failover is to the current data set 

as read-only. After the import session is complete, failback to the primary Directory 

Service resumes as write-enabled. 

Run a Scripted Update Sequence 

If you use archives in the advanced stages, the flow of updates might result in more than 

one archive loading to achieve the update. In that circumstance, you might want to script 

the process so that any overwrites in the import properties are consistently applied in later 

stages. 

See “Defining Scripts to Automate Deployment” on page 81 for information on creating 

and applying scripts. 

Evaluate Target Overwrites 

When deployment elements reach advanced staging and production, you must decide 

whether or not to overwrite on a file match. In the absence of a timestamp, you cannot 

choose to have “newer” overwrite “older.” Developer documentation and file 

management techniques can make these decisions easier. For example: 

● Use comments in XML files to record change history — When you add notes to 

XML files (actually, any files), you continue the established programmer tradition of 

maintaining change history. 



● Import without overwrites — When you attempt an import with no overwrites, the log 

indicates file matches that were not overwritten. Perform an import with no 

overwrites, and then examine the import message log for matched files. 

● Export and difference matched files — Examine the content of each of the files in a 

text tool. If developers recorded change history, the decision is easy. Otherwise, some 

criteria must be applied to decide which files overwrite on import. 

As the techniques of importing are in the scope of the import tool, see “Importing 

Deployment Artifacts into a Domain” on page 105 for more information. 



Dump Endpoint Lists and Then Iterating Queue Creation 

When a deployment contains many endpoints and multiple messaging nodes, you might 

want to programmatically set the queue endpoints on the appropriate messaging node. 

◆ To dump endpoint lists and iterate queue creation: 

1. Extract the content of an archive to a temp directory. 

2. Create an iterator over the elements in ESB\Endpoints\. On each item, examine the file 

to see if the type is QUEUE. For each queue item, output its destination value to a list. 

3. Create an application based on the SonicMQ ConfigBean/CreateQueue sample that 

connects to the domain and then adds (but does not overwrite!) each listed queue. 

4. You can tune the queues after they are created (global, clusterwide, size, etc.). 

You might have to handle different connection_ref values in separate runs, or a more 

robust application. 

Manage Imports, Containers, and Installed Sonic Products 

If you used host names as the management container names, you can add the name of the 

product hosted so adding deployed services to appropriate containers is easier to map. For 

example, if you install Sonic BPELServer (bpel) on a system named eagle, you could 

name the container eagle_bpel. 

Evaluate Change Requirements in JavaScript, and ebXML Files 

Use a regular expression tool to review sonicfs:// and URL references in documents. 

Correct references might be in development or early staging levels. Confirm that 

references are correct in the target domain. 

Test and Accept or Rollback 

You should run a test suite in a target domain that is for advanced staging or production 

to ensure that the behaviors expected of the new or updated elements in the change set are 

as expected and that nothing else changed. Be prepared to fail a domain update and roll it 

back to its previous configuration store. 




Chapter 4 Analyzing ESB Artifacts in Archives, 

Stores, and File Systems 

This chapter describes the tools for analyzing Sonic ESB artifacts and SonicMQ 

dependencies in file systems, archives, and Directory Service stores. 

This chapter has the following sections: 

● “Overview” 

● “Reporting Differences” 

● “Reporting SonicMQ Dependencies” 

● “Reporting on SonicMQ Reverse Dependencies” 

● “Reporting on Impact Analysis” 


Chapter 4: Analyzing ESB Artifacts in Archives, Stores, and File Systems 

Overview 

The decoupling of Sonic ESB artifacts from the underlying messaging infrastructure 

means that you must tune the artifacts and their parameters when you import them into a 

new domain. To help evaluate the potential changes, Sonic provides a set of analysis 

reports that extract differences and dependencies into XML files. The analysis reports 

discover and document variations in ESB artifact files and their content, and reveals 

SonicMQ configuration parameters required by ESB artifacts. 

The analysis commands assess the files in a file store, archive, or directory service in three 

categories: XML, text, or binary. In an analysis that offers the -v verbose switch, not 

enabling the option provides a Boolean response to differences. A file’s extension 

classifies it for analysis and appropriate verbose information, as shown in this table: 

File Type Extensions Differencing Verbose [-v] 

XML .amap 

.bp 

.cbr 

.esbws 

.esbdb 

.prj 

.wsdl 

.xaction 

.xcbr 

.xml 

.xsd 

.xsl 

.xslt 

Text .bat 

.css 

.html 

.js 

.properties 

.sh 

.txt 

.xquery 

Binary .bpv 

.gif 

.jar 

.jpg 

.xar 

any other 

extension 

Requires XML 

equivalence. The order 

of elements is not 

significant—a series of 

tags listed in a different 

sequence is treated as 

equivalent. 

Reports on differences in the 

content of XML elements. 

The content (payload) of an 

element is case sensitive. 

XML tag names are not case 

sensitive. 

Exact textual match. Reported as in a standard text 

difference. 

Case sensitive. 

Exact binary match. Offset into the document of the 

first byte difference 


Reporting Differences 

Reporting Differences 

The diff command assesses the difference between two artifact stores. Unlike a generic 

differencing engine, the ESBAdmin diff command only assesses specific filetypes in certain 

store types. The stores can be Sonic archive files—XAR files—(-xar store type), file 

systems (-fs store type), or Directory Service stores (-ds store type). 

Differences include: 

● Artifacts that are in both stores, yet do not have identical content. You can choose to 

identify only that the files are dissimilar or to expose the differences in detail. 

● Artifacts that are in the source store, but not in the target store. 

● Artifacts that are in the target store, but not in the source store. 

The syntax of the diff command in the Sonic ESB Admin Tool is: 

diff -storeType storeParameters -storeType storeParameters 

[-out outputFile.xml] [-v] 

where: 

■ The first -storeType storeParameters identifies the source artifact store, and 

the next -storeType storeParameters identifies the target artifact store. 

■ storeType is { xar | fs | ds }. 

■ storeParameters are: 

❑ When storeType is xar, the archive location on a file system 

❑ When storeType is fs, the root of the hierarchy on a file system 

❑ When storeType is ds, the management connection to a domain in the form: 

domain url [username password] [managementNode] 

■ outputfile is the preferred target XML file name and location for the analysis 

report on the file system. When you do not specify this parameter, the output file 

is created as Sonic_Diff.xml in the tool’s directory. 

■ -v requests verbose reporting. 

Examples of diff Commands 

● Comparing two XAR files: 

ESBAdmin> diff -xar sourceStore.xar -xar targetStore.xar 

● Comparing a XAR file with a Directory Service store: 

ESBAdmin> diff -xar sourceStore.xar -ds Domain1 myHost:2506 aUser aPassword 

● Comparing a file system with a XAR file in verbose output: 

ESBAdmin> diff -fs C:/myinstalldir/ESB -xar targetStore.xar -v 



Reporting SonicMQ Dependencies 

The mqdepends command assesses a source artifact store to evaluate and report on the 

dependencies of ESB artifacts on SonicMQ configuration objects. This information can 

then be used to create or verify the existence of the specified dependencies in a target 

Directory Service store. The stores can be a Sonic archive file, file system, or a Directory 

Service store. 

Sonic ESB dependencies on SonicMQ artifacts include: 

■ Endpoints for their destination dependencies (topics, queues, or routing). 

■ ESB connections for SonicMQ connection parameters (and, therefore, the broker 

location and port where static destinations must be created.) 

The report indicates an ESB artifact, and whether the SonicMQ configuration elements 

that are its dependencies exist in the target domain. 

The command provides parameters so you can constrain the analysis to specified files or 

a text document that provides a list of files. 

The syntax of the mqdepends command in the Sonic ESB Admin Tool is: 

mqdepends -storeType storeParameters [-out outputFile.xml] 

[-include artifact1 [artifact2 ...] | -includeFile artifactListFile] 

where: 



❑ When storeType is xar, the archive location of a .xar file on a file system 






is created as Sonic_Dependency.xml in the tool’s directory. 

■ artifact1 artifact2 ... is a series of specific files in the store to analyze. 

■ artifactListFile is a text file that provides a list of files in the store to analyze. 


Examples of mqdepends Commands 

● Producing a dependency report on a XAR file: 

ESBAdmin> mqdepends -xar sourceStore.xar 

● Producing a dependency report on a file system: 

ESBAdmin> mqdepends -fs C:/myinstalldir/ESB 

● Producing a dependency report on a Directory Service store: 

ESBAdmin> mqdepends -ds Domain1 myHost:2506 aUser aPassword 

● Producing a dependency report on a file system: 

ESBAdmin> mqdepends -fs C:/myinstalldir/ESB 

● Producing a dependency report on specified files: 

Reporting SonicMQ Dependencies 

ESBAdmin> mqdepends -fs C:/myinstalldir/ESB -include processA svcA svcB 

● Producing a dependency report on a list of specific files: 

ESBAdmin> mqdepends -fs C:/myinstalldir/ESB -includeFile artifactList.txt 



Reporting on SonicMQ Reverse Dependencies 

The mqrevdepends command assesses a source artifact store to evaluate and report on the 

dependencies of ESB artifacts on SonicMQ configuration objects. This information can 

then be used to create or verify the existence of the specified dependencies in a target 

Directory Service store. 

Reverse dependency produces the same set of information as a dependency. But the 

information indicates, for each ESB artifact, the SonicMQ configuration element on 

which it depends. 

The store can be a Sonic archive file, file system, or a Directory Service store. 

The command provides parameters so you can constrain the analysis to specified files or 

a text document that provides a list of files. 

The syntax of the mqrevdepends command in the Sonic ESB Admin Tool is: 

mqrevdepends -storeType storeParameters [-out outputFile.xml] 

[-include artifact1 [artifact2 ...] | -includeFile artifactListFile] 

where: 



❑ When storeType is xar, the archive location of a .xar file on a file system 






is created as Sonic_ReverseDependency.xml in the tool’s directory. 

■ artifact1 artifact2 ... is a series of specific files in the store to analyze. 

■ artifactListFile is text file that provides a list of files in the store to analyze. 


Examples of mqrevdepends Commands 

● Producing a reverse dependency report on a XAR file: 

Reporting on SonicMQ Reverse Dependencies 

ESBAdmin> mqrevdepends -xar source.xar 

● Producing a reverse dependency report on a Directory Service: 

ESBAdmin> mqrevdepends -ds Domain1 myHost:2506 aUser aPassword 

● Producing a reverse dependency report on a file system: 

ESBAdmin> mqrevdepends -fs C:/myinstalldir/ESB 

● Producing a dependency report on specified files: 

ESBAdmin> mqrevdepends -fs C:/myinstalldir/ESB -artifacts processA serviceA 

● Producing a dependency report on a list of specific files: 

ESBAdmin> mqrevdepends -fs C:/myinstalldir/ESB -artifactsFile aList.txt 



Reporting on Impact Analysis 

An impact analysis report combines aspects of “Reporting Differences” and “Reporting 

on SonicMQ Reverse Dependencies.” Together, these features define the impact on the 

target store that would result from merging the source store into the target store. 

Because this report provides impact, the following information is also included: 

● If a binary file type is different, the impact analysis report indicates that the file in the 

source store will overwrite the one in the target store. 

● If a file exists in the source store but not in the target store, the impact analysis report 

indicates that a new file will be added to the target store. 

However, if a file exists in the target store but not in the source store, it is not reported, 

as it is not impacted and will not be affected by any import actions. 

● If a dependency indicates that SonicMQ configuration objects must be created, the 

impact analysis report describes the requirement. 

Conversely, if existing SonicMQ configuration objects are no longer required by 

ESB, the impact analysis report notes that fact. (There might be non-ESB related 

references to a SonicMQ configuration.) 

The syntax of the impact command in the Sonic ESB Admin Tool is: 

impact -storeType storeParameters -storeType storeParameters 

[-out outputFile.xml] [-v] 

where: 








domainName hostname:port [user password] 



is created as Sonic_ImpactAnalysis.xml in the tool’s directory. 

■ -v requests verbose reporting (otherwise, you get terse reporting). 

Assessing impact on a Directory Service store requires a connect command to establish a 

connection to the domain prior to running impact. 


Examples of the impact Commands 

● Reporting the impact of a XAR on a Directory Service store: 

Reporting on Impact Analysis 

ESBAdmin> impact -xar sourceStore.xar -ds Domain1 myHost:2506 aUser aPassword 

● Reporting the Impact of a file system on a XAR: 

ESBAdmin> impact -fs C:/myinstalldir/ESB -xar source.xar 




Chapter 5 

Importing Deployment Artifacts into a Domain 



● “Backing Up the Domain and Documenting Tests” 

● “Using The Deployment Archive Import Tool” 

● “Importing or Merging ESB Artifacts With the ESB Admin Tool” 


Chapter 5: Importing Deployment Artifacts into a Domain 

Overview 

The deployment import process is based on the existence of target domains and 

deployment files extracted from source Workbench or deployment domains. 

The “Mapping ESB Artifacts to Target Domains” chapters described different ways to set 

up staging, source control, mapping of archives to target domains, and Directory Service 

population. 

This chapter discusses the procedures that take a mapped archive (or unmapped export 

files in a file store) and import it into the target domain. In this chapter, you see how the 

Sonic Deployment Archive Import Tool helps you create import rules to determine which 

files to overwrite and which to ignore. 

After developing import rules, the import process can be scripted, as described in 

“Defining Scripts to Automate Deployment” on page 81. 

The “Adapting Imported Services to a Domain” and “Updating a Revised Deployment” 

chapters discuss the final tuning of the imported ESB elements into the target domain, and 

the recurrence of the lifecycle when changes in developed applications are ready to update 

their previous deployment artifacts through established processes. 

Backing Up the Domain and Documenting Tests 

While importing deployment elements into an existing domain is not difficult, be sure you 

can recover the directory service if the updated domain is not accepted. 

Preparing a domain for import requires you to either stop and backup (incremental 

technique), or restore (build technique) the existing Directory Service. See “Incrementally 

Updating or Building Domains” on page 83 for more on these strategies. 

When you complete the backup or restoration of the Directory Service, start the container 

that hosts the Directory Service and the management broker. 

Developers should describe the tests (written as ESB services or processes) that verify 

their deployment elements when their work moves from Sonic Workbench into a target 

environment. Those tests can be added to the project elements packaged with the runtime 

deployment files. 

If regression or error conditions cannot be resolved, stop the domain manager and restore 

the directory service backup. 


Using The Deployment Archive Import Tool 


The Sonic Deployment Import Tool, when connected to a target domain manager, inserts 

selected configuration elements that are in a deployment archive or file store created by 

the Sonic Deployment Export Tool. 

Import properties files define rules to filter incoming elements. You can ignore some files 

and, for other files, specify that the imported file overwrite an existing file of the same 

identity. 

Importing elements from archive files involves: 

● Defining import rules for the archive contents 

● Updating the selected domain and reviewing logs of actions taken 

◆ To start the Deployment Import Tool 

A system must have SonicMQ and Sonic ESB Administration Tools installed (these are 

included in the Sonic Workbench) to run this tool. 

1. Check that the target domain manager is running. 

2. On the system where you will administrate the import process, start the Sonic 

Deployment Import Tool: 

■ Under Windows, choose Start > Programs > Progress > Sonic 8.5 > 

Tools > ESB Deployment Import Tool 


Tools, open a console window to the Sonic ESB installation directory, and then 

enter: ./bin/deployImport.sh 

Setting Import Properties for ESB Artifacts into a Domain 

The Deployment Export Tool lets you select structures of files for inclusion in an export 

package. You could not, however, at the time of the export, select which dependent files 

would be allowed into the target domain and, for those files that are allowed in, which 

should overwrite existing files of the same name and location. That functionality is 

defined in import properties—notation of files and branches that should overwrite 

existing files and files that should be ignored. 

If you choose not to define import properties, the default behavior is assumed—all files 

in the ESB artifact store are imported but no imported file will overwrite an existing file. 

Note The Remote Information access export file that was mapped for the Developer Integration 

Testing (DIT) named RIA_DIT.xar after it was mapped is described in these procedures. 



◆ To define deployment import properties: 

1. Start the Deployment Import Tool. 

2. Select an exported Sonic archive file (*.xar) and click Open. The file displays on the 

Archive Elements tab, as in this example using the mapped RIA sample XAR: 

(You could select the root of a file store if you chose to export as files in the Export 

Tool or used the ESB Admin Tool command export fs.) 

The elements in the store display with a green square in the lower corner of their icon. 

That means that the default behavior will be applied: import the file unless it would 

result in overwriting an existing file. 



3. To construct rules that override the default behavior for folder structures or individual 

elements, do the following: 

a. To specify the import should overwrite when it encounters a match, select the 

item, then choose Overwrite Existing on the menu. After the option is selected, 

the selected item has a filled red circle, as illustrated: 

b. To specify that the import should overwrite all the files in a branch when they 

encounter a file match, select the branch, then choose Overwrite Existing on the 

menu. After the option is selected, the selected item’s the branch and any items 

in the branch have a filled red circle, as illustrated: 

c. To ignore a file specified to overwrite at the branch level, click on the file, and 

then choose Ignore, as illustrated: 



d. You can click on the folder level and then choose Reset to clear the effect of the 

selection on that folder. In this series of examples, the files set to overwrite are 

cleared. The file-specific override to ignore stays in effect, as illustrated: 

After you tune your import properties, the Properties tab presents the text representation 

of the import properties settings you apply in this example: 



These defined import properties can be applied immediately. The following illustration 

shows the graphic representation of the overwrite and ignore options that can be applied 

to the example, RIA_DIT.xar: 

Saving a Deployment Import Property File 

You can store a defined set of import properties for reuse in later sessions or distribution 

of the packaged ESB artifacts. Choose Properties > Save to start the save process. The 

resulting import file for the example used here is named RIA_DIT_Import.xml so that it can 

be reapplied through a script in a subsequent import with the ESB Admin Tool. 



Importing an ESB Artifact Store Into a Domain 

After you establish (or open a saved) import properties file, the import process into a 

domain is a straightforward task that logs actions and anomalies. 

Note An ESB artifact store can be imported to more than one target domain. You can define an 

import properties file unique to each target domain. 

◆ To import a deployment ESB artifact store into a domain: 

1. Start the Deployment Import Tool, as described on page 107. 

2. Open the ESB artifact store you want to import, as follows: 

■ Open an archive file by choosing File > Open XAR. Select an exported Sonic 

archive file (*.xar) and click Open. 

■ Open a file store by choosing File > Open File System. Select the root of an 

exported Sonic ESB artifact file store and click Open. 

3. To overwrite or ignore any of the content, define import properties or open an existing 

import file, as described on page 108. 

4. Choose Domain > Connect. In the Domain Connection dialog box, enter the 

connection information for the domain to which you want to import configurations. 

5. Select Actions > Import. 

The files selected are imported into the domain. 


Validating Imported Elements 


You should confirm the imported elements, especially if you ignored some elements on 

the import. 

Another case for validation is when you are not sure if the export process ignored reported 

errors. See the example of error handling during export in Step a on page 46. 

A good technique to resolve missing elements is to initiate an export from the target 

domain of the elements that have dependencies to see if they indicate that any of their 

dependent elements are missing. 

Validation, however, is not a substitute for a test plan that exercises the features of the new 

and revised (or impacted) services together with a delineation of the expected results of 

each set of test parameters and actions. You can build your plan and any associated 

services or test applications and store them in SonicFS so they can travel in a deployment 

archive. You can create an additional project folder for test plans as they are relevant in 

both development and deployment domains. 



Viewing Messages 

You can choose View > Messages to review the sequence of steps taken by the import tool. 

The entries are date stamped and have colored alert flags, as shown: 

Indicator flags call out the alert levels of the line item, as described: 

● Yellow flags indicate warnings. 

● Red flags indicate errors, and when appropriate, provide a trace tab in the Message 

Details dialog box that opens when you double click on a message line. 

● Green markers set off the start and end points of actions. 

Messages that do not have indicator flags are informational only. 

Saving Import Messages to File as an Import Log 

When you view import messages, you can save the messages as a log of the import 

procedures that have been recorded in the current session of the Deployment Import Tool. 


◆ To save the import messages: 


1. In the Messages window, click the Save Messages to File button: 

2. Enter a location and name for the text file in the Save Messages dialog box. 

3. Click Save. 

Remove Import Messages 

You can delete a message or range of import messages in the Messages window. 

◆ To remove import messages: 

1. In the Messages window, click the message or range of import messages you want to 

remove. 

2. Click the Remove Message button: 

The selected import message is removed. 

Displaying an Import Message’s Details In a Dialog Box 

You can view an import message in a dialog box. 

◆ To display an import message’s details: 

1. In the Messages window, click a message that you want to see in a dialog box. 

2. Click the Message Details button: 

3. After you review the message details, click Close to close the dialog box. 



Importing or Merging ESB Artifacts With the ESB Admin Tool 

The Sonic ESB command line tool, ESB Admin Too, adds ESB artifacts in a Sonic 

Archive or a file store to a target domain. 

Note See the “Sonic ESB Tools and Samples” chapter of the Progress Sonic ESB 

Configuration and Management Guide for more information on this tool. 

Starting the ESB Admin Tool 

On the system where you will run the import process, start the ESB Admin Tool: 

● Under Windows, choose: 

Start > Programs > Progress > Sonic 8.5 > Tools > ESB Admin Tool 

● Under UNIX or Linux, on a system installed with the Sonic ESB Administration 

Tools, open a console window to the Sonic ESB installation directory, and enter: 

./bin/esbadmin.sh 

The ESB Admin Tool opens. For a list of commands, enter: ESBAdmin> help (or ?). 

Connecting to the Target Domain 

All import actions require that you open the archive and then establish connection to the 

target domain. Enter the connection data for the domain using the syntax: 

connect domain url [username] [password] [managementNode] 

For example: 

ESBAdmin> connect Domain1 localhost:2506 Administrator Administrator 

Using Import Properties 

When you use the Deployment Import Tool, the rules you define to overwrite or ignore 

specified files or folders can be saved. (See “Saving a Deployment Import Property File” 

on page 111). That file can be used on subsequent imports with either the Deployment 

Import Tool or the ESB Admin Tool import commands. 

You can edit an import properties file. Start with an existing rules file that has some ignore 

and some overwrite settings to observe the syntax of the import properties. 


Using the Import Archive Command 


The import archive command syntax reads an archive file, and, optionally, a related 

import properties file in its command line: 

ESBAdmin> import archive source.xar [import_prop.xml | override ] 

where: 

■ souce.xar is the path and name of the file (using the .xar extension) of the 

deployment archive package to be imported. 

■ One of the following arguments is used: 

❑ import-prop.xml — When an appropriate import properties file exists, you 

can use its location as a parameter of the command to apply the defined 

overwrite and ignore settings. 

❑ override — Import everything in the archive file with overwrite set to true. 

As an example, you might import the RIA export archive and use the defined import 

properties file (when the archive and the import properties file are at the ESB installation 

root) as: 

ESBAdmin> import archive C:\RIA_DIT.xar C:\RIA_DIT_Import.xml 

Using the Import FS Command 

When the source store is a file store, use the import fs command.Its syntax reads a file 

system structure, and, optionally, a related import properties file in its command line: 

ESBAdmin> import fs sourceFileStore [import_prop.xml | override ] 

where: 

■ sourceFileStore is the root of the file system hierarchy that contains the files to 

be imported into the connected Directory Service’s store. 

■ One of the following arguments is used: 

❑ import-prop.xml — When an import properties file exists, it can be applied 

as a parameter of the command to apply the defined overwrite and ignore 

settings. 

❑ override — Import everything in the file system file with overwrite set to 

true. 



Using the Merge Command 

An alternative to the import command is the merge command. It performs the action of 

applying the source store to the target store, and while it replaces ESB artifacts that are 

different in the target store and adds ESB artifacts that are new to the target store, it does 

not overwrite existing, unchanged files. 

The syntax of the merge command of one store into another in the ESB Admin Tool is: 

merge -storeType storeParameters -storeType storeParameters 

-out outputFile.xml 

[-v] 

where: 









■ outputfile is the target XML file name for the post-merge impact report on the 

file system. 


Examples of merge Commands 

● Merging a XAR into a Directory Service store: 

ESBAdmin> merge -xar sourceStore.xar -ds Domain1 myHost:2506 aUser aPassword 

● Merging a file system into a XAR: 

ESBAdmin> merge -fs C:/ESB_install_dir/ESB -xar targetStore.xar 


Using Merge for Multiple Stores 


The merge command enables a merge of two source stores into a target store. As a result, 

the target store is acted on but the two source stores are not modified. The source and 

target stores can be XAR files, file systems, or Directory Service stores. 

The syntax of the merge command of one store into another in the ESB Admin Tool is: 

merge -sourceStore1Type sourceStore1Parameters 

-sourceStore2Type sourceStore2Parameters 

-targetStoreType targetStoreParameters 

-out outputFile.xml 

[-v] 

where: 

■ sourceStore1 and sourceStore2 are the sources of the ESB artifacts to be merged 

into the target. 

■ targetStore is the target store where sourceStore1 is merged and then 

sourceStore2 is merged. 







■ outputfile is the target XML file for the post-merge report on the file system. 


Examples of merge Commands on Multiple Stores 

● Performing a merge of a XAR and a DS into a target XAR: 

ESBAdmin> merge -xar sourceStore.xar 

-ds domain url [username password] [managementNode] 

-xar targetStore.xar 

● Merging a XAR and a file system into a target file system: 

ESBAdmin> merge -xar source.xar -fs C:/source_dir/ESB -fs C:/target_dir/ESB 



Importing Configurations using the ESB Admin Tool 

You can use the ESB Admin Tool to import connections and endpoints into a domain’s 

Directory Service store. 

◆ To import connection types into a domain: 


2. Connect to the target domain’s management broker. 

3. Enter: 

import connectionType path_to_the_file [override] 

where: 

■ path_to_the_file is the pathname to the connection type XML configuration file 

■ the optional override parameter enables overwrite of a matching configuration. 

4. Confirm the new connection type configurations in the Directory Service by listing 

the stored connection types. Enter: 

list connectionType 

◆ To import endpoint types into a domain: 


2. Connect to the target domain’s management broker. 

3. Enter: 

import endpointType path_to_the_file [override] 

where: 

■ path_to_the_file is the pathname to the endpoint type XML configuration file 

■ the optional override parameter enables overwrite of a matching configuration. 

4. Confirm the new endpoint type configurations in the Directory Service by listing the 

stored endpoint types. Enter: 

list endpointType 

Closing the Domain Connection and Stopping the ESB Admin Tool 

After you complete your import tasks with the ESB Admin Tool, close the administrative 

connection to the target domain. Enter: 


To stop the ESB Admin Tool, enter: 



Chapter 6 

Adapting Imported Services to a Domain 


● “Scoping the Required Adaptation Tasks” 

● “Binding ESB Services to Messaging Nodes” 

● “Updating Security” 

● “Enabling and Updating Sonic ESB Service Containers” 


Chapter 6: Adapting Imported Services to a Domain 

Scoping the Required Adaptation Tasks 

When you move deployment elements into a new domain, you might need to map some 

parameters to the new domain while other parameters might not require modification 

when moving one domain to another. 

The following checklists provide a way to scope the requirements for tailoring and 

adapting imported archives, depending on the target environment and its maturity: 

● “Deployment to a Unified Staging Deployment” 

● “Deployment to a Distributed Staging or Production Deployment” 


Deployment to a Unified Staging Deployment 

Scoping the Required Adaptation Tasks 

When you move archives move into unified testing, consider the following requirements: 

[ ] Are the required deployment products installed? 

If not, see Progress Sonic Installation and Upgrade Guide. 

[ ] Is this a build domain? If so, has the base level DS been restored? 

If so, see “Using the Build Strategy on a Static Target Domain” on page 87. 

[ ] Is there a tailoring rules file for creating a map for this archive for this domain? 

If so, see “Adjusting Tailoring Rules to Apply When Creating Map Files” on page 67. 

[ ] Is there a map file for mapping this archive for this domain? 

If so, see “Applying Tailoring Rules and Creating a Map File for an Archive” on 

page 73. 

[ ] Does the test team plan to use localhost:2506? 

If not, see “Binding Connections to Host Ports in the New Domain” on page 125. 

[ ] Were any custom acceptors created? 

If so, see “Binding Connections to Host Ports in the New Domain” on page 125. 

[ ] Were the management user and password modified? 

If not, see “Reconciling Users and Groups to Authentication Domains” on page 131. 

[ ] Was the pattern of ACLs changed? 

If so, “Reconciling Endpoint Access and QoP to Authorization Policies” on page 131. 

[ ] Are there any new queues? 

If so, see “Binding the Endpoints in the New Domain” on page 128. 

[ ] Do you want to force overwriting on file matches? 

If so, “Setting Import Properties for ESB Artifacts into a Domain” on page 107. 



Deployment to a Distributed Staging or Production Deployment 

When deploying to a distributed deployment environment, consider the following: 

[ ] Is the domain manager configured? 

If so, see Progress Sonic Installation and Upgrade Guide. 

[ ] Are messaging nodes configured? 


[ ] Are the tools installed on an administrative system? 


[ ] Are the required deployment products installed for services? 


[ ] Is there a tailoring rules file for creating a map for this archive for this domain? 

If so, see “Adjusting Tailoring Rules to Apply When Creating Map Files” on page 67. 

[ ] Is there a map file for mapping this archive for this domain? 

If so, see “Applying Tailoring Rules and Creating a Map File for an Archive” on 

page 73. 

[ ] What host port or connection list will be used for administrative connections? 

See “Binding Connections to Host Ports in the New Domain” on page 125. 

[ ] What HTTP URLs are used by ESB Services deployed as Web Services? 


[ ] What are the acceptors in the new domain? 


[ ] What is the management user and password in the new domain? 

See “Reconciling Users and Groups to Authentication Domains” on page 131. 

[ ] Was the pattern of ACLs changed? 

If so, “Reconciling Endpoint Access and QoP to Authorization Policies” on page 131. 

[ ] Are there any new queues? 

If so, see “Binding the Endpoints in the New Domain” on page 128. 

[ ] Do you want to force overwriting on file matches? 

If so, “Setting Import Properties for ESB Artifacts into a Domain” on page 107. 


Binding ESB Services to Messaging Nodes 


You can import configurations into a domain that consists of only an ESB-aware domain 

manager. However, a distributed deployment environment typically constrains the domain 

manager’s messaging traffic to management traffic. Distributed broker installations are 

assigned to handle message traffic. 

Setting Up Distributed Messaging Nodes 

One of the first steps required after importing a deployment archive is binding 

connections and endpoints defined in ESB services to the new domain’s messaging 

environment. Often new messaging brokers are defined and deployed to host the 

connections and endpoints, especially in the initial stages of a distributed rollout. After 

the brokers are set up and configured, you can bind the connections and endpoints to the 

domain. 

See “Installing SonicMQ Messaging Nodes in the Domain” in the Progress Sonic 

Installation and Upgrade Guide for basic instructions on installing a messaging node. 

The administrator of the domain can set up broker clusters, fault tolerant brokers, and 

establish location-specific encryption and activation mechanisms for the deployed 

messaging nodes. See SonicMQ Deployment Guide for details on broker architectures and 

topologies. 

Binding Connections to Host Ports in the New Domain 

After the messaging nodes are installed, you can bind the ESB connections defined in 

SonicMQ Endpoints to acceptors on messaging nodes in the new domain. 

Important When you initially deploy into a new domain, be sure that you bind to connections on 

brokers in the new domain instead of perpetuating connections to messaging nodes in the 

source domain. 

The ESB connections such as http_defaultConnection and jms_defaultConnection are 

defined once in a domain. If you are hosting ESB services in a domain for the first time, 

you need to revise the connection URLs of the default ESB connections to the protocol, 

host, and port for corresponding acceptors set up on the stated host. 



In the following illustration, the protocol, host, and port defined for the acceptor 

TCP_ACCEPTOR on the messaging node installed as Broker100 are entered as the Connection 

URL for the http_defaultConnection ESB connection: 

The connections defined for ESB endpoints must bind to brokers on ports where the 

specified connection protocol is supported. 

You can run analysis reports for SonicMQ dependencies and the impact of the deployment 

on a domain to reveal the acceptors required by connections. Refer to the following 

sections: 

● “Reporting SonicMQ Dependencies” on page 98 

● “Reporting on SonicMQ Reverse Dependencies” on page 100 

● “Reporting on Impact Analysis” on page 102 


◆ To bind connections to host ports in the new domain: 


1. Connect the Sonic Management Console to the domain that is the import target. 

2. On the Configuration tab, expand the broker that you want to use as a messaging 

node. 

3. Click on Acceptors to view the acceptors and their properties. 

4. Decide which acceptor you want to use for the ESB endpoint connection. 

5. In the ESB Configured Objects section, expand the Endpoints folder and click on 

SonicMQ Endpoint. 

6. Select the Connections tab. 

7. Click on each Connection Name to view its parameters. 

8. Change the Connection URL to the acceptor you identified in Step 3. You can provide 

a comma-delimited list of connections. See the SonicMQ Configuration and 

Management Guide for more about connection lists. 

9. Click Apply. 

10. Repeat for each connection name as required. 

The security parameters on the connection for authentication and SSL parameters are 

discussed in the SonicMQ Configuration and Management Guide. 

Custom Connections 

If any connections were defined other than (or instead of) the default ones, you should 

review them before you start an import to determine whether to allow the import to 

overwrite existing connection definitions of the same name. 

Generally, it is a good practice to let individual applications define their own connection 

names even if they will resolve to the same acceptor used by other connections. 

The following screen excerpt shows two custom connection definitions: 



Binding the Endpoints in the New Domain 

After you bind the SonicMQ endpoints to a messaging broker host port, you must set up 

any queues required as endpoints on that broker. Because queues are static objects, they 

must exist in order to be used. Topics are dynamic and as such are created as needed on 

the messaging node. 

Important Security authorization policies let you define read and write permissions for 

authenticated users on both queues and topics. These policies also let you specify the 

requirements for messages to and from a specified endpoint to use encryption techniques. 

See “Reconciling Endpoint Access and QoP to Authorization Policies” on page 131. 

In this illustration, the endpoint myQ001 defines its Queue Destination Name as Q001 on the 

connection myCorp_NodeB. In this target domain, the node named NodeB is Broker100, so 

a queue named Q001 was created on Broker100. When routing definitions on other brokers 

specify NodeB, messages sent to NodeB::Q001 are routed to Broker100’s Q001. 



You can run analysis reports for SonicMQ dependencies and the impact of the deployment 

on a domain to reveal the destinations required by endpoints. Refer to the following 

sections: 

● “Reporting SonicMQ Dependencies” on page 98 

● “Reporting on SonicMQ Reverse Dependencies” on page 100 

● “Reporting on Impact Analysis” on page 102 

Setting Queue Parameters 

Queues have parameters that give them flexibility in the deployment topology: 

● Size and threshold — Controls the in-memory queue size and its save threshold 

● Global — Lets other messaging nodes send to the queue 

● Exclusive — Allows only one active receiver 

● Clusterwide — Defines a queue on all members of a cluster 

For more information about queue parameters, see the SonicMQ Deployment Guide and 

the SonicMQ Configuration and Management Guide. 

You can examine a deployment archive in the Deployment Import Tool to determine 

whether endpoints are defined that specify queues that do not exist on the broker specified 

for the endpoint’s connection. 

◆ To establish queues on messaging nodes that bind to endpoints in the new domain: 

1. Connect the Sonic Management Console to the domain that is the import target. 

2. On the Configuration tab, expand the broker that you want to use as a messaging 

node. 

3. Click on Queues to view the queues and their properties. 

4. In the ESB Configured Objects section, expand the Endpoints folder and select 

SonicMQ Endpoint. 

5. On the Endpoints tab, select each new Endpoint Name to view its parameters. 



6. If the JMS Destination Type is Queue, determine whether that queue exists on the 

target broker. If it does not exist, click Create Queue. 

7. Choose the broker from the list of brokers defined for connections. The queue is 

configured on the broker you select. Click OK. 

8. Repeat for each endpoint name as required. 

The security parameters on the destination for authorization and QoP are discussed in 

“Reconciling Endpoint Access and QoP to Authorization Policies” on page 131. 

Routing Nodes 

When WSDL definitions have routing definitions that use the node syntax (such as 

sonic://NodeB/Q1), you might have to establish the routing definition in the new domain. 

You could either revise the WSDL to use a different syntax or to create the node definition 

in the new domain. While the node does not have to be in the new domain, be sure that it 

is in the correct context for the new domain; that is to say, if the node was defined as 

another Workbench in development and you are moving into advanced staging, the node 

should be redefined as a node in the advanced staging or production infrastructure. 


Updating Security 

Updating Security 

Security in a domain has a set of interdependencies that make it an important aspect of the 

initial creation of a domain and messaging nodes. You should plan what security you will 

use and implement the plan as you define the domain and messaging nodes. 

There are many aspects of security to consider: 

● When you use authentication, you must: 

■ Consider whether to use external authentication and the login SPI. 

■ Create the users and passwords in the default authentication domain, or use a 

different authentication domain. 

■ For SSL, configure the provider, acceptors, and—if you use certificates—the 

certificate management and certificate revocation lists. 

● When you use Quality of Protection, the cipher suite for encryption 

● When you use authorization, defining authorization policies 

See the SonicMQ Deployment Guide section on implementing security in a domain. 

Note Channel Encryption and External Authentication — See the SonicMQ Deployment 

Guide and the SonicMQ Configuration and Management Guide for details about SSL 

parameters, HTTPS, QoP, and the Login SPI. 

Reconciling Users and Groups to Authentication Domains 

SonicMQ endpoint connections specify a user and password. You must either create the 

user and password information in the target domain or change the ESB connection user 

and password to one that exists in the target domain. 

Reconciling Endpoint Access and QoP to Authorization Policies 

Access control and Quality of Protection (QoP) is enforced by authorization policies in 

the target domain. Unless you set up patterns that will apply appropriate policies to new 

queues, topics, and routings, you must modify the ACLs in the target domain to provide 

your preferred pattern of permissions. 



Enabling and Updating Sonic ESB Service Containers 

Once the messaging nodes are established for the connections and endpoints in the target 

domain, the distributed systems and containers can be implemented. 

Installing Distributed Systems with Deployment Software 

On the computer systems that will run the services being deployed, install the appropriate 

software for the services. For example, the software for ESB requires installing the 

SonicMQ Container feature and then installing the Sonic ESB Container feature. See 

Progress Sonic Installation and Upgrade Guide for instructions on all deployment 

installations. The Sonic Installer requires that you use deployment licenses to install 

distributed components. 

Determine what ESB Containers need to be installed from the archive. When you create 

ESB Containers on distributed systems, the installation creates the named ESB Container 

and a similarly named management container. The remote installation registers the 

installation in the Directory Service and creates its boot file. It can run but has no assigned 

services. 

Then, when you import the archive, the ESB Container and any associated services and 

classpaths can overwrite the deployed ESB Container to complete the service 

configuration. 

Checking for Elements That Might Not Have Been Exported 

Chapter 1, “Introduction,” described how deployment archives can package all the files 

needed to transfer between development domains or move into deployment. 

Elements that need adjustment in the target domain are: 

● Classes External to SonicFS — If you did not import additional classes or JAR files 

and include them in the deployment package, they must be moved to the deployment 

domain and relocated in the same relative position to the Sonic installation as they 

were in the source domain. 

● ESBDB Scripts and ESBWS WSDL Files External to SonicFS — ESBDB scripts and 

ESBWS WSDL files can be stored on a file system outside the Directory Service. 

When that is the case, these files are not exported by the deployment tool. You can 

choose to add them into SonicFS as runtime elements. You might need to relocate 

them in the target domain to the same relative location outside SonicFS in the target 

domain after importing them. 



● GUI Properties Files and Images External to SonicFS — Applications that use 

graphical components, such as properties files and images, cannot access their files 

when they are in SonicFS. These files are not exported unless you make a point of 

doing so. If you do not package them, they must be moved to the deployment domain 

and relocated in the same relative position to the Sonic installation as they were in the 

source domain. 

Tuning the Imported Services 

Some elements are not bound to configuration objects in a Sonic domain. You could be 

referencing sample Web locations that will be consistently used in development, staging, 

and perhaps even in production. 

References to Files by URL in XSLT Files 

XSLT files that reference other files in SonicFS must be edited to correct the URL 

references to appropriate references in the new domain. 

Endpoints and Services Referenced in Code or in JavaScript Files 

Endpoints and services that are referenced in application code or in JavaScript files might 

need to be adapted in the new domain by creating queues. For example, an async dispatch 

to an endpoint effectively references the endpoint. That means that the destination and 

connection of that endpoint must exist in the deployment domain. 



Tuning BPEL Server Deployments 

A Progress Sonic BPEL Server installation for deployment and its configurations in the 

deployment domain adapt the BPEL services to their runtime environment. 

Specifying Persistence 

A Sonic BPEL Server installation can be set to persist its data in one of three ways: 

● When you choose memory, be sure that adequate memory is available on the target 

systems after allowing for the operating system, enterprise resources, and JVM 

memory usage. 

● When you choose embedded storage, specifying a storage directory will establish 

the store locally on each system where the BPEL server runs. Be sure that there is 

adequate disk space to accommodate the store. It is recommended that the data 

storage directory is a different directory from the BPEL service staging directory so 

that the staging directory can be easily deleted and recreated as needed. 

● When you choose your other database, you can specify oracle or mysql: 

■ For oracle, set the Oracle SID, the machine name, port, user name, and password. 

■ For mysql, set the database name, host name, port, user name, and password. 

Using a Callback URL 

MyRole is the local endpoint for a partner link defined by the process. It is used by the 

BPEL Server in the following two cases: 

● ReplyTo / Fault To for outbound invocations when asynchronous transport is used. 

● Explicit assignment from a myRole of a partner link. The value is determined using the 

service configured CallBack URL. 

You must also create a corresponding HTTP Direct acceptor (on the broker’s 

configuration) and a WebServices Protocol configuration so that messages sent to the 

callbackURL are routed to the BPEL Service entry endpoint. 

Monitoring Destinations for Processing Replies 

To monitor processing replies: 

● Two temporary queues are used, one for synchronous replies and one for 

asynchronous replies. Operations that are bound to ESB use synchronous replies. 

● The format of temporary queue names uses the pattern: 

container_name.service_name.queue_name 



where queue_name is either replies.async or replies.sync. 



Setting the Number of Listener Threads 

The number of listeners for a BPEL Service needs to account for the expected number of 

concurrently active receives with corresponding replies. A receive with a corresponding 

reply blocks the listener thread until the reply is produced. A single process could have 

multiple receive/reply pairs; and could therefore block multiple listener threads. If there 

aren't enough listeners available a process could deadlock. Asynchronous interactions 

(one way with an invoke callback rather than a reply) do not tie up a listener thread. 

The optimal number of threads is one more than the number of threads required by each 

receive in a BPEL server instance times the number of allowed concurrent receives to the 

instance. For example, if the developer notes that a BPEL Service requires two threads 

and you expect no more than five receives to be running concurrently, set the number of 

listener threads to eleven. 

For more information, see the Progress Sonic Workbench User Guide in the Eclipse help. 

Invoking a BPEL Service from an Itinerary using ESBPEL or ESBWS 

A BPEL Service can be invoked from an itinerary using either an ESBPEL file or an 

ESBWS file: 

● Using an ESBPEL — Can invoke any process or partner link in a deployed BPAR. No 

need for a public WSDL or any binding information. Script executes in the BPEL 

Service on its listener thread. 

● Using an ESBWS — Requires concrete port and binding information in the BPEL 

Service's public WSDL. This WSDL must be authored (it is not generated). Script 

executes on the caller's thread. 

Tuning Classloader Memory 

Each BPEL Service deployed to a container has a classloader that loads its classes first. 

When you deploy multiple BPEL Services in one container, multiple copies of the same 

classes are loaded in memory. You can set the -XX:MaxPermSize JVM option to specify a 

larger memory allocation for class files. 






Chapter 7 

Updating a Revised Deployment 

Once a deployment has been imported and adapted into a domain, it can be modified to, 

for example, change a service configuration, or update an XSLT file. These changes 

should be applied on the source workbench and propagated through the staging 

environments and into production. This chapter contains the following sections: 

● “Using Deployment Tools to Rebuild and Deploy a XAR” 

● “Using the ESB Admin Tool to Rebuild a XAR or File Store” 


Chapter 7: Updating a Revised Deployment 

Using Deployment Tools to Rebuild and Deploy a XAR 

The Deployment Export Tool contains an ExportProperties.xml file that you can edit 

interactively in the graphical tool. Then, use the Deployment Import Tool to bring the 

rebuilt archive’s contents in to the target domain. 

◆ To rebuild an archive with the Deployment Export Tool: 

1. Start the ESB Deployment Export Tool. 

2. Connect to the source domain and open the archive you want to change. 

3. Add or remove configurations, files, and roots. 

4. Choose Rebuild. 

5. Save the rebuilt archive. You can choose to save the archive under a different name. 

The export tool recreates the archive with any changes and a redefined 

ExportProperties.xml file. 

You might want to tune the import properties before importing the rebuilt archive into the 

target domain. See “Modifying the Import Rules for the Target Domain” on page 142 for 

more information. 

◆ To import a rebuilt archive with the Deployment Import Tool: 

1. Start the ESB Deployment Import Tool. 

2. Open the rebuilt archive. 

3. If you are only adding to the previous archive, change the import option to clear 

Override Existing Files (= ‘FALSE’) to prevent changing any of the 

endpoints/configurations previously modified. 

In the previous example with exampleProcess, you would specify to overwrite 

everything except: 

■ Endpoints 

■ Connections 

4. Connect to the target domain. 

5. Complete the import. 

In the example exampleProcess, the procedure imports the three additional files. 


Using the ESB Admin Tool to Rebuild a XAR or File Store 


When using the ESB Admin Tool commands, if you want to modify the export properties, 

you must edit the file before running an export command. 

Modifying ExportProperties.xml 

You can rebuild an ESB artifact package to regenerate the package with different or 

changed roots if the package contains ExportProperties.xml. That file is produced in most 

cases and is stored at the root level of export packages, specifically: 

● In a XAR produced by either the Deployment Export Tool or the ESB Admin Tool 

command export xar 

● In a file store produced by the ESB Admin Tool command export fs 

See “Editing ExportProperties.xml” on page 35 for more information. 

Adding Additional Configurations or Files 

You can add files that were not included in an export package. In the exampleProcess, the 

following files were referenced indirectly by files that were included in the archive: 

● File: sonicfs://Resources/myHelperFiles.js 

● File: sonicfs://Resources/soap-imports.xsl 

To obtain these files, go to the source domain, open the archive, and explicitly add these 

files. The packaging rules will then explicitly include three items—the ExampleProcess, 

plus the two files. 

Then see “Rebuilding the Export Package with the ESB Admin Tool” on page 142 and 

“Deploying a Rebuilt XAR or File Store with ESB Admin Tool” on page 143. 



Changing a Root Element 

You can also make changes to the configuration used as a root element before rebuilding. 

In the example process, the ErrorEndpoint is removed as a step. It is replaced by an 

invocation step to an ErrorService. This is an ESB service called using 

sonicfs://Resources/ErrorService.esbws. 

When the archive is rebuilt it will have the following changes: 

● Addition of sonicfs://Resources/ErrorService.esbws. 

● The endpoint, ErrorEndpoint, is no longer included in the archive. 

Note Reimporting the rebuilt archive overwrites the ExampleProcess. However, it does not 

remove the ErrorEndpoint from the target domain. You must do this manually, 

Rebuilding the Export Package with the ESB Admin Tool 

When you have identified the XAR and, if necessary, edited the ExportProperties.xml 

file, you can recreate the package by either: 

● “Using the Export Archive Command” on page 52 

● “Using the Export FS Command” on page 53 

Modifying the Import Rules for the Target Domain 

In the target domain, you want to control importing a revised deployment so that it 

concentrates on the areas of change. The developer preparing the archive should generate 

a corresponding import properties template for the changes that includes: 

● Overwritten Elements — When you are importing changes that you want to definitely 

replace a matching file at the same location, choose to overwrite in the import 

properties to ensure that the changes are accepted. 

● Ignored Elements — Setting the ignore flag on branches and files that are 

dependencies and supporting files but are known to have not changed, minimizes the 

rebinding in the target domains. 

● Leftover Elements — Elements that are no longer meaningful should be removed 

from the target domain. For example, if the original archive had services A, B, C, and 

D and the revised package uses only A and D, the developer should include an update 

note in the project folder that recommends deletion of services B and C in the updated 

domain. 



● Overrides — If you are only adding to the previous archive, change the import option 

to clear Override Existing Files (= ‘FALSE’) to prevent changing any of the 

endpoints/configurations previously modified. 

● Roots — You could change the nature of an archive by deleting roots and adding new 

ones. When everything is being packaged for the first time, it is in effect a new 

archive. But if there are some parts of the archive that were packaged and imported in 

other domains, rebuilding the archive rebuilds it from scratch, not incrementally. 

Deploying a Rebuilt XAR or File Store with ESB Admin Tool 

The following procedure describes how to use the ESB Admin Tool to import a rebuilt 

archive or rebuilt file store into a target domain. 

When you have rebuilt the export package and tuned the import rules, you can recreate 

the package according to its type: 

● For an archive, see “Using Import Properties” on page 116 

● For an file store, see “Using the Import FS Command” on page 117 




Chapter 8 

Distributed Deployment at Runtime 

This chapter contains the following sections: 


● “Multiple Instances of a Service or Process in a Domain” 

● “Distributed Installation of a Product’s Runtime Features” 

● “Multiple Services in a Container” 

● “Multiple ESB Containers in a Management Container” 

● “Multiple Management Containers on a Host” 

● “Operations” 

● “Monitoring and Metrics” 

● “Container Collections” 


Chapter 8: Distributed Deployment at Runtime 

Overview 

The procedures previously described in this guide described single services to import into 

a domain and single service installations. The following illustrations also depict this. This 

illustration pattern is expanded later in this chapter. 

Consider a set of configuration elements exported from the development environment 

(Sonic Workbench) for deployment. In these illustrations, the functionality of the services 

and processes are represented by diamond shapes. 

For a distributed services infrastructure, a deployment domain manager is installed to 

provide the runtime Directory Service. 

The deployment package is imported into the new domain’s Directory Service, as shown: 

my.xar 

Import ESB Artifacts 

Directory 

Service 

Management 

Node 

Enterprise Service Bus 

On a host system named aHost, install a Container Launcher with a management 

container named aHost-1 connected to the deployment Directory Service that will manage 

it. The container can be created to have a Windows Service, and can be started at the time 

it is created 

Create an ESB Container, and then create an instance of the service to deploy with 

appropriate parameters for the instance. Add the instance to ESB container. 


ctHostA1

Overview 

When you add the ESB container to the aHost-1 container, the cache of the management 

container at the remote location is provisioned with the appropriate versioned libraries to 

support the ESB service and any additional service functionality on the Enterprise Service 

Bus, as shown: 

Directory 

Service 

Management 

Node 

ctHostA1 


esbHostA1 

Advanced ESB Service 

BPEL Server + BPEL DataStore 

ESB Container 


Management Container 

SonicMQ 

The alternative deployment scenarios let you to enable multiple instances in the domain, 

in an ESB Container, and in management containers on a host system. This chapter shows 

the techniques and best practices for: 

● “Multiple Instances of a Service or Process in a Domain” on page 148 

● “Distributed Installation of a Product’s Runtime Features” on page 149 

● “Multiple Services in a Container” on page 150 

● “Multiple ESB Containers in a Management Container” on page 152 

Note You can install deployment archives into multiple domains. 


ctHostA1 

HostA


Multiple Instances of a Service or Process in a Domain 

After you establish a service or process in the production environment, you can deploy 

multiple instances of the service. This scales your service oriented architecture, as shown: 

Directory 

Service 

Management 

Node 

ctHostA1 

ctHostB1 






esbHostB1 

ctHostA1 

HostA 










In this illustration, the service that was imported into the domain is duplicated by 

installing similar deployment software on a different host, and—when the components 

register in the Directory Service—adding an instance of the service to the new container. 

Both instances of the service provide identical operation. As you deploy more instances 

of the service, and the service is modified, one update to the domain perpetuates the 

change to every service instance automatically. 


ctHostB1 

HostB

Distributed Installation of a Product’s Runtime Features 

Distributed Installation of a Product’s Runtime Features 

my.xar 

Import 

ESB Artifacts 

You can locate the runtime features of some products on different systems. That means 

that you could deploy several instances of one runtime feature and a few of another. It also 

means that features that intensively use the resources of a host system can be isolated from 

other runtime features of its product deployment, as shown: 

Directory 

Service 

Management 

Node 

ctHostA1 

ctHostB1 


Service One 




esbHostB1 

ctHostA1 

HostA 




ctHostB1 

HostB 


Service Two 





In this illustration, a deployment archive imported into the Directory Service defines two 

fully-encapsulated services. The services could be distributed as follows: 

● Service One— On system HostA, the SonicMQ management container, and ESB 

Container installations are registered in the Directory Service. Then, Service One is 

deployed into the ESB Container. 

● Service 2— On system HostB, the SonicMQ management container, and ESB 

Container are registered in the Directory Service. Then, Service Two is deployed into 

that ESB Container. 



Multiple Services in a Container 

Sometimes the resources to maintain a service do not tax a system’s resources. You can 

choose to place several different services into a container and let them work 

independently to provide finer granularity for your composite application. Some services 

complement each other to the point where they comprise a coarser grained application, as 

shown: 

Directory 

Service 

Management 

Node 

ctHostA1 







In this illustration, several services are deployed in a container. The services work 

independently, sharing the caching and runtime management of the single container. 

When Intra-Container Messaging is enabled on a container, messages can be transferred 

within the container. Do this when a message heading for one hosted service’s exit 

endpoint matches the entry endpoint of another service hosted in the container. 

For more information on intra-container messaging and also its Quality of Service 

ramifications, see the Sonic ESB Product Family: Development Guide in the Eclipse help. 

See Part IV of the Progress Sonic ESB Configuration and Management Guide for 


ctHostA1 

HostA

Multiple Services in a Container 

information on using intra-container messaging in adding multiple Database Service steps 

to an ESB process, and using polling queries to run the Database Service in an ESB 

process. 

Services that share an ESB Container are not required to be heterogeneous. You can have 

an BPEL Server running in a container where an ESB service transforms or routes the 

incoming or outgoing data, as shown: 

Directory 

Service 

Management 

Node 

ctHostA1 









ctHostA1 

HostA 

Enterprise Service Bus


Multiple ESB Containers in a Management Container 

A management container can support multiple ESB Containers. You might want to do this 

to have one classloader for the two ESB containers. This tactic is not typically 

recommended because the memory requirements for another management container’s 

JVM are minimal when compared to the ESB processes. An appropriate use-case for this 

construct is when you have a large ESB process that is running intra-container, as shown: 

Directory 

Service 

Management 

Node 


ctHostA 


esbHostA1 esbHostA2 


aHost-1 

ctHostA 


In this illustration, HostA has one management container, hosting two ESB Containers. 

When intra-container steps are in separate ESB Containers, the process writes the 

message to the broker at strategic places in the process. Thus, a restart of the process can 

resume the process, and avoid having to start it from its beginning. 


HostA 





Sonic ESB

Multiple Management Containers on a Host 

Multiple Management Containers on a Host 

Using multiple management containers provides independence of services. Unless the 

services complement each other or can use intra-container messaging, it is usually better 

to use separate container instances, as shown: 

Directory 

Service 

Management 

Node 

ctHostA1 

ctHostA2 

Management Container Management Container 


aHost-1 

ctHostA1 


ctHostA2 

In this illustration, HostA has two management containers, each hosting an ESB 

Container. 

When you keep multiple management containers in the same version, you can use 

Activation Daemons to provide remote and scheduled startup of management containers. 


HostA 




esbHostA1 esbHostA2 


Sonic ESB


Operations 

The Sonic Management Console provides runtime monitoring and management on 

management containers and ESB Containers. 

Note The operations and activities mentioned in this chapter are described in the “Managing 

the Sonic Management Environment” chapter in the Progress SonicMQ Configuration 

and Management Guide” 

Actions 

You can perform operations on ESB Containers when their management container is 

running, as shown: 

You can also perform operations on a management container. However, you can only start 

a remote container if you have associated it with an Activation Daemon that is running on 

the remote system. See the “Extending and Activating Components” chapter in the 

Progress SonicMQ Configuration and Management Guide for information on setting up 

Activation Daemons on remote systems. 


Runtime Properties 

Operations 

Management containers and ESB Containers have Properties dialog boxes that show their 

identity, status, loading, and tracing facilities. ESB Container Properties can be viewed 

whether an ESB Container is running or not. However, if the management container is not 

running, the ESB Container’s Properties are not available. 

Management container information is described in the Progress SonicMQ Configuration 

and Management Guide. ESB Container information is described in the Progress Sonic 

ESB Configuration and Management Guide. 

The following set of Properties dialog box tabs are for an ESB Container: 

● The General tab shows domain identification information and the ESB Container’s 

status: 

● The Loading tab shows the classpaths in use by this ESB Container: 



● The Tracing tab lets you select tracing options, which are immediately implemented 

in the ESB Container’s logs. The management container also has tracing options: 

Tracing options should be used with discretion to debug or monitor specific 

situations. The volume of data that could flow into the logs when extensive, verbose 

tracing is active can increase the container logs dramatically. You can set the tracing 

options on a management container and on an ESB Container to persist through 

restarts. 

For more information about management container and ESB Container tracing, see 

the “Logging and Tracing” section of the “ESB Containers” chapter in the Progress 

Sonic ESB Configuration and Management Guide. 

Monitoring and Metrics 

Use monitoring and metrics to send notifications and alerts to the domain manager (rather 

than to the log) to observe the management container and the ESB Container. 


ESB Container Notifications and Metrics 

Monitoring and Metrics 

ESB Container notifications let you watch for notifications of state changes, as shown: 

ESB Container metrics let you measure performance in the ESB Container, as shown: 

For more information about ESB Container notifications and metrics, see the “Monitoring 

Service Metrics and Notifications” section of the “ESB Containers” chapter in the 

Progress Sonic ESB Configuration and Management Guide 



Management Container Notifications and Metrics 

The management container provides metrics and a range of notifications. The 

Notifications options for a management container include: 

The Metrics options for a management container are as shown: 

See the Progress SonicMQ Configuration and Management Guide for more information 

about metrics and notifications on management containers. 


Container Collections 

Container Collections 

Container collections are components that monitor the runtime status of selected 

management containers defined in its collection. The same container can be monitored in 

several container collections. 

The examples shown here are simple. In a deeply nested structure or a large scale 

deployment, container collections are useful for providing operator alerts. In this 

example, two management containers are included in the configured object created at the 

root level of the domain hierarchy. As shown, both of its monitored containers are running 

(green highlight) so the container collection object also displays a green highlight: 

When one of the monitored components stops (red highlight) and the other continues to 

run, the container collection object displays a yellow highlight, as shown: 

For more information about collections, see “Configuring Container Components” 

section of the “Containers and Collections” chapter in the SonicMQ Configuration and 

Management Guide. 




A Access Control Lists 131 

activation daemon 154 

applyMap 

syntax 79 

authorization 

endpoints 29 

B 

Index 

backup 

Directory Service before import 91 

build 

scripted 38, 41, 54 

build strategy 84, 87 

C 

classes 

as dependencies 37 

external to SonicFS 132 

classpath 

loaded at runtime 155 

clusterwide queue 129 

connection 

source domain for export 43 

connections 

adapting in a new domain 125 

custom 127 

container 

messaging when multiple services 150 

operations 154 

runtime state 155 

container collections 159 

CPA files 

adjusting after import 134 

createMap 

syntax 73 


D 

dependencies 33 

classes 37 


base level for builds 87 

distributing runtime features 149 

E 

ebXML files 

adjusting after import 134 

endpoint lists 88, 93 

endpoints 

adapting in a new domain 128 


export archive 50 

import archive 116 

ESBDB scripts 

external to SonicFS 132

Index 

ESBWS WSDL files 


exclusive queue 129 

F 

FTP server 

adjusting configuration 134 

G 

global queue 129 

graphical components 37 

group 

reconciling in a new domain 131 

GUI properties 37 

H 

hierarchical namespaces 

authorization 29 

I 

ignore 

during export 36 

during import 109 

import properties 107 

imported elements 

validation 113 

incremental change 83 

intra-container messaging 150 

J 

JavaScript 

adjusting embedded endpoint references 133 

adjusting embedded service references 133 

M 

Mail server 

adjusting configuration 134 

messaging nodes 125 

metrics 156 

monitoring 156 


N 

node syntax 130 

notes 

attached to archive properties 48 

notifications 156 

O 

overwrite 

during import 109 

P 

password 

between deployment domains 28 

management roles 28 

properties 


properties files 37 

Q 

QoP 131 

queue creation 88, 93 

queue parameters 129 

queue size 129 

R 

rebuilding an archive 37 

reload an ESB Container 154 

reload container 154 

Reset 110 

reset 

defining import properties 110 

restoring 

Directory Service 91

outing nodes 130 

S 

scripted build 38, 41, 54 

service 

deploying multiple instances 148 

source control 50 

stages 85, 86 

stages, deployment 23 

start an ESB Container 154 

start container 154 

state 

container at runtime 155 

stop an ESB Container 154 

stop container 154 

support, technical 19 

T 

technical support 19 

test plans 

regression after import 106 

testing 89, 93 

tracing 

ESB container 156 

U 

update strategy 89 

users 

reconciling in a new domain 131 

V 

validation 

imported elements 113 

W 

WSDL 


Index 


X 

xslt 

adjusting embedded URL references 133

Index

esb_deploy - Progress Sonic ESB Deployment Guide 8.5 - Product ...

Create successful ePaper yourself

Delete template?

Save as template?