Page
1
Pooja Kamath & Diane Kesler Building Integrations with MuleSoft Integrating Systems and Unifying Data in the Enterprise
Page
2
9 7 8 1 0 9 8 1 5 8 2 9 3 5 5 9 9 9 ISBN: 978-1-098-15829-3 US $59.99 CAN $74.99 PRODUC TIVIT Y TOOL S This concise yet comprehensive guide shows developers and architects how to tackle data integration challenges with MuleSoft. Authors Pooja Kamath and Diane Kesler take you through the process necessary to build robust and scalable integration solutions step-by-step. Supported by real-world use cases, Building Integrations with MuleSoft teaches you to identify and resolve performance bottlenecks, handle errors, and ensure the reliability and scalability of your integration solutions. You’ll explore MuleSoft’s robust set of connectors and their components, and use them to connect to systems and applications from legacy databases to cloud services. • Ask the right questions to determine your use case, define requirements, decide on reuse versus rebuild, and create sequence and context diagrams • Master tools like the Anypoint Platform, Anypoint Studio, Code Builder, GitHub, and Maven • Design APIs with RAML and OAS and craft effective requests and responses • Write MUnit tests, validate DataWeave expressions, and use Postman Collections • Deploy Mule applications to CloudHub, use API Manager to create API proxies, and secure APIs with Mule OAuth 2.0 • Learn message orchestration techniques for routers, transactions, error handling, For Each, Parallel For Each, and batch processing Pooja Kamath is a results-oriented project leader specializing in integration projects. She adeptly manages stakeholders, ensuring successful delivery of multimillion-dollar initiatives. A three-time MuleSoft community ambassador (2023–2025), Pooja is also a speaker and blogger. Diane Kesler is cofounder of Integration Quest, a Salesforce certified instructor, and hyperautomation MuleSoft practice lead at CloudBlazer. She was named top MuleSoft community ambassador three years in a row and is passionate about mentoring others and building future-ready integration teams. Building Integrations with MuleSoft “What sets this book apart is its balance of theory and practice: not only does it explain MuleSoft’s design principles, it also provides examples, best practices, and design insights that readers can apply to their own projects.” Simone Geib, director of product management, Salesforce “Pooja and Diane have done an amazing job creating a single resource containing all the essential information to enable you to design and deploy a MuleSoft API.” Brian Statkevicus, MuleSoft ambassador and MuleSoft practice director, Argano
Page
3
Praise for Building Integrations with MuleSoft In my 25+ years in technology, I’ve never seen integration explained so clearly. This practical guide transforms technical complexity into strategic business advantage—essential for modern enterprises. —Justine Reilly, director, enterprise architecture, Salesforce, and former director of automation specialists, MuleSoft Pooja and Diane offer an expertly crafted, practical blueprint drawn from their extensive MuleSoft training and real-world experience. —Isabella Nararro, MuleSoft community manager, MuleSoft With deep roots in the MuleSoft ecosystem, Pooja and Diane have created an invaluable guide for developers and architects alike. Drawing on years of hands-on experience, this book is packed with practical insights that will empower anyone building integrations with MuleSoft. —Sabrina Marechal, MuleSoft community director, MuleSoft Pooja and Diane exemplify what it means to be MuleSoft experts through their clear and detailed explanations guiding both beginners and advanced users to build integrations easily with MuleSoft. —Sabrina (Hocket) Barnes, MuleSoft community advocacy and marketing manager, MuleSoft
Page
4
This book is a masterful resource for developers and architects seeking to excel in enterprise integration. With its practical approach, this book transforms complex integration concepts into actionable insights, empowering readers to design scalable, reliable solutions. From prototyping APIs to mastering tools like Anypoint Studio and conquering DataWeave, the authors provide a comprehensive roadmap for tackling real-world challenges. Supported by detailed use cases, this guide dives deep into error handling, message orchestration, and deployment strategies, ensuring readers are equipped to handle the most demanding integration scenarios. Whether you’re connecting legacy systems or deploying CI/CD pipelines, this book is your essential companion for leveraging MuleSoft’s capabilities to unify data and streamline processes across the enterprise. —Jim Andrews, MuleSoft architect and author This book is a comprehensive, thoughtfully crafted guide for developers and architects who want to go beyond the basics and truly understand the power of MuleSoft. Pooja and Diane do an outstanding job of breaking down complex concepts—from API-led connectivity and integration patterns to the nuances of AsyncAPI, DataWeave and Unit Testing (MUnit)—without ever losing the reader in jargon. What sets this book apart is its balance of theory and practice: not only does it explain the why behind MuleSoft’s design principles, it also provides real-world examples, best practices, and design insights that readers can immediately apply to their own projects. Whether you’re just getting started or looking to deepen your expertise, this book is the perfect companion on your MuleSoft journey. —Simone Geib, director of product management, Salesforce An indispensable guide for anyone building modern enterprise integrations. This book brings API-led connectivity to life with clarity, precision, and practical examples—bridging foundational concepts with hands-on mastery in Anypoint Studio and Code Builder. —Ramsundernag Changalva, software engineering senior member technical staff, Salesforce Pooja and Diane have done an amazing job creating a single resource containing all the essential information to enable you to create and deploy a MuleSoft API. If you are a MuleSoft developer, you need to get this book. Agentic AI needs integration to truly meet business goals. If your choice of an integration platform is MuleSoft, this book will teach you everything you need to know to develop MuleSoft APIs used by your agentic AI solution. —Brian Statkevicus, MuleSoft ambassador and MuleSoft practice director, Argano
Page
5
Pooja Kamath and Diane Kesler Building Integrations with MuleSoft Integrating Systems and Unifying Data in the Enterprise
Page
6
978-1-098-15829-3 [LSI] Building Integrations with MuleSoft by Pooja Kamath and Diane Kesler Copyright © 2025 Pooja Kamath and Diane Kesler. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://oreilly.com). For more information, contact our corporate/institutional sales department: 800-998-9938 or corporate@oreilly.com. Acquisitions Editor: Andy Kwan Development Editor: Corbin Collins Production Editor: Elizabeth Faerm Copyeditor: nSight, Inc. Proofreader: Miah Sandvik Indexer: Ellen Troutman-Zaig Interior Designer: David Futato Cover Designer: Susan Thompson Illustrator: Kate Dullea May 2025: First Edition Revision History for the First Edition 2025-05-09: First Release See http://oreilly.com/catalog/errata.csp?isbn=9781098158293 for release details. The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Building Integrations with MuleSoft, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. The views expressed in this work are those of the authors and do not represent the publisher’s views. While the publisher and the authors have used good faith efforts to ensure that the information and instructions contained in this work are accurate, the publisher and the authors disclaim all responsibility for errors or omissions, including without limitation responsibility for damages resulting from the use of or reliance on this work. Use of the information and instructions contained in this work is at your own risk. If any code samples or other technology this work contains or describes is subject to open source licenses or the intellectual property rights of others, it is your responsibility to ensure that your use thereof complies with such licenses and/or rights.
Page
7
Table of Contents Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi 1. The World of Integrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Super Routes Logistics 2 Milestones 2 Transformation Goals 3 Business Challenges 3 From Spaghetti Links to Smart APIs: The Evolution of Integration 4 Point-to-Point Integration 5 Enterprise Service Bus 7 API-Led Connectivity 8 Application Network 10 Discovery 15 Writing Sequence Diagrams 16 Writing API Context Diagrams 18 Writing Stories 19 Integration Essentials: The Tools You Need to Succeed 20 MuleSoft’s Anypoint Platform 21 Anypoint Platform APIs 22 Getting Started with the Anypoint Platform 23 Anypoint Exchange 25 Anypoint Studio 26 Anypoint Code Builder 28 Maven 29 POM and Its Elements 29 Repositories 31 Maven’s Lifecycle 31 Summary 33 v
Page
8
2. Prototyping APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 API Fundamentals 36 SOAP Web Services 37 REST Web Services 38 RAML 44 Design Center: Text Editor 49 Design Center: Visual Editor 52 OpenAPI Specification 53 RAML Versus OAS 55 Anypoint Code Builder 56 Summary 60 3. Designing and Publishing APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 API Fragments 62 Resource Type Fragments 63 Traits 66 Security Schemes 68 Creating Fragments on Exchange 69 Mocking APIs 73 Publishing APIs 76 Summary 78 4. Build Essentials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Mule Events 79 Creating Projects from Scratch 82 Adding Connectors 85 Code Snippets: A Coding Shortcut 88 Variables 90 DataWeave 91 Debugging 92 Managing Properties 95 Referencing Properties 96 Encrypting Properties 96 Other Ways to Trigger Flows 97 File System Monitoring 98 Watermarking 98 Database Event Detection 99 Schedulers 100 Object Store 103 Application Structure 103 Flows 103 Configuration Files 105 vi | Table of Contents
Page
9
Global Elements 105 Summary 105 5. Mechanics of Message Orchestration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Error Handling 108 Error Types: System and Messaging Errors 108 Family of Errors: Hierarchy 109 Error Object Creation 110 Decoding HTTP Listener Default Settings 110 Modifying HTTP Listener Default Settings 111 Mule Default Error Handler 113 Error Handling Scopes 114 Raise Error Processor 116 On Error Propagate 117 On Error Continue 118 Overriding HTTP Status Codes 119 Flow-Level Error Handling 122 Application Level: Global Error Handler 123 Process Level: Try Scope 128 Customize Error Types with Error Mapping 131 Practical Error-Handling Use Cases 134 Routers: Control the Flow 134 Choice Router 134 Scatter-Gather Router 135 Round Robin Router 136 First Successful Router 137 Processing Records 138 For Each 139 Parallel For Each 139 Batch Processing 140 Anypoint Code Builder 141 Summary 149 6. AsyncAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Event-Driven Architecture 151 OpenAPI Versus AsyncAPI 153 AsyncAPI Object 155 EDA with AsyncAPI 159 Example of Event-Driven Orders API 159 AsyncAPI Design 160 Implementing AsyncAPI 164 Scaffolding a Basic Orders API in Mule 165 Table of Contents | vii
Page
10
Using APIkit for AsyncAPI 166 Importing AsyncAPI Specifications 167 Building from Exchange and Updating Your API 168 Example for Re-Scaffolding 168 Validating AsyncAPI Documents 169 Validating Against the Specification 169 Validating Against Best Practices or Company Rules (Linting) 170 Summary 171 7. Events and Storage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 Anypoint MQ 174 VM Queues 185 Third-Party Queues 189 Object Store 189 Cache Scope 191 Redis 192 Anypoint Code Builder 193 Summary 199 8. DataWeave: The Language of Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 DataWeave: The Essentials 203 Functional Programming Principles 203 The Evolution of DataWeave 203 DataWeave in Salesforce: A Revolutionary Tool 204 DataWeave Basics 204 Simple Transformations: Dates 212 Complex Transformations: filter, map, reduce 213 Joining Datasets: Concatenate, Join Functions 217 Improving Performance: SRL’s DataWeave Transformation Success Story 226 Reuse with DataWeave Libraries 238 Summary 242 9. Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 MUnit 244 MUnit Processors 248 Set Event 248 Mock When 249 Assert That 249 Verify Call 249 Spy 251 MUnit Structure 253 Behavior Scope (Arrange) 253 viii | Table of Contents
Page
11
Execution Scope (Act) 253 Validation Scope (Assert) 254 Best Practices 254 Agree on Standards 254 Create a Base MUnit Template 256 Include Common Components and Mocks 257 Define Setup and Teardown Logic 257 Troubleshoot 258 Reuse 258 Socialize the Template 259 Integration Testing 259 Identify Test Scenarios 259 Environment Setup 260 Mocking 261 Spies 262 Integrate with CI/CD for Automation 263 Example Integration Test for an API Flow 263 MUnit Test Recorder 265 Summary 266 10. Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 Deployment Options 268 CloudHub 268 Customer-Hosted Runtime Environment 270 Anypoint Runtime Fabric 271 Deploying Applications to CloudHub 271 Method 1: Using Anypoint Studio 272 Method 2: Using Runtime Manager in Anypoint Platform 274 Method 3: Using Anypoint Code Builder 276 Managing Deployed Applications 278 Static IPs 281 CloudHub 2.0 281 Proxy Deployment 283 Policy Creation 285 Access Provision 288 Anypoint Monitoring 291 Summary 292 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Table of Contents | ix
Page
12
(This page has no text content)
Page
13
Preface In today’s ever-changing digital landscape, disruption is widespread, and creating a composable enterprise enables organizations to adapt to changing landscapes. This is made possible by creating reusable assets to foster agility and adaptability. Enterprises like this help democratize automation and drive innovation. Just like integration connects applications and data to generate insights and improve observation of busi‐ ness impact, automation relies on this integration to create a network of capabilities. The ability to scale rapidly and develop truly connected experiences is important for organizations to remain competitive. As businesses strive to automate their sys‐ tems quickly and seek to create assets that can be combined to deliver a distinctive customer experience, companies are exploring technologies that complement rapid innovation. Welcome to the world of integration! MuleSoft is a robust integration platform consisting of products like CloudHub, Mule as an ESB, Anypoint Studio, Enterprise Management Console, DataWeave, and Anypoint Enterprise Security. Together, these products provide organizations with essential connectivity solutions, streamlined development, comprehensive management, and enhanced security for seamless inte‐ gration and interoperability across their enterprise. MuleSoft stands as the ultimate solution for seamlessly integrating applications and unifying data. Powered by the Mule runtime engine, MuleSoft ensures exceptional performance, outperforming other comparable approaches by up to five times. Additionally, with the aid of Anypoint templates, MuleSoft empowers organizations with unmatched productivity and accelerated time to market, enabling these organizations to stay ahead in today’s fast-paced business landscape. MuleSoft helps organizations create an API portal for their software ecosystem, personalize new digital experiences using templates that can be viewed via Anypoint Exchange, and provide interactive documentation for developers so they can solicit feedback from users while building assets. It also has a vibrant community where the users can engage with other developers and architects to post questions and access publicly shared knowledge. xi
Page
14
The world of integration is evolving faster than ever. We stand at the intersection of API-led connectivity, hyperautomation, and AI-driven innovation, transforming how businesses connect, scale, and automate. What once required months of custom development can now be achieved in days with the right tools, frameworks, and strategies. This book is designed to guide you through the entire process of design‐ ing, building, and deploying effective MuleSoft application programming interfaces (APIs). As you progress, you will learn practices and principles to create connected experiences for your enterprise. You will also gain skills in a wide range of MuleSoft developer tools, including tools for design, documentation, development, testing, and deployment. By the time you work through this book, you should have enough experience to develop an API from concept to launch. This book is more than a guide—it’s a blueprint for the future of integration, automation, and intelligent systems. Welcome to the journey. Let’s build the future together. Who Should Use This Book? This book is for developers and architects looking to get up to speed on developing integrations using MuleSoft. Most of the content used here is from the training mate‐ rial we have created and used over the years. This book also contains our learnings from past project experiences. This book can also serve as a comprehensive reference guide for fundamental topics such as API design methods, the API build process, testing, and other stages of API development using MuleSoft. This is why it is a valuable resource for senior software architects and API product managers who aim to provide consistent guidance to their teams. What’s Covered and What’s Not The goal of this book is to give you a linear coverage of what is required to get up and running and launch an API to production. We understand that software development is an iterative process, and in the real world you will have to bounce back and forth between processes for the successful delivery of applications. MuleSoft is a very big topic with a lot of products; we won’t be able to cover it all. With the help of a use case, we will learn how to create an API, develop, test, and deploy it. We won’t be covering topics related to the broader topic of API management. Things like API Gateways, portals, monitoring, and overall governance are out of scope for us in this book. xii | Preface
Page
15
Conventions Used in This Book The following typographical conventions are used in this book: Italic Indicates new terms, URLs, email addresses, filenames, and file extensions. Constant width Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords. Constant width bold Shows commands or other text that should be typed literally by the user. Constant width italic Shows text that should be replaced with user-supplied values or by values deter‐ mined by context. This element signifies a tip or suggestion. This element signifies a general note. This element indicates a warning or caution. Using Code Examples Supplemental material (code examples, exercises, etc.) is available for download at https://github.com/poojapkamath/Building-Integrations-with-MuleSoft. If you have a technical question or a problem using the code examples, please send email to support@oreilly.com. This book is here to help you get your job done. In general, if example code is offered with this book, you may use it in your programs and documentation. You Preface | xiii
Page
16
do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission. We appreciate, but generally do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Building Integrations with MuleSoft by Pooja Kamath and Diane Kesler (O’Reilly). Copyright 2025 Pooja Kamath and Diane Kesler, 978-1-098-15829-3.” If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at permissions@oreilly.com. O’Reilly Online Learning For more than 40 years, O’Reilly Media has provided technol‐ ogy and business training, knowledge, and insight to help companies succeed. Our unique network of experts and innovators share their knowledge and expertise through books, articles, and our online learning platform. O’Reilly’s online learning platform gives you on-demand access to live training courses, in-depth learning paths, interactive coding environments, and a vast collection of text and video from O’Reilly and 200+ other publishers. For more information, visit https://oreilly.com. How to Contact Us Please address comments and questions concerning this book to the publisher: O’Reilly Media, Inc. 1005 Gravenstein Highway North Sebastopol, CA 95472 800-889-8969 (in the United States or Canada) 707-827-7019 (international or local) 707-829-0104 (fax) support@oreilly.com https://oreilly.com/about/contact.html xiv | Preface
Page
17
We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at https://oreil.ly/bldg-integ-mulesoft. For news and information about our books and courses, visit https://oreilly.com. Find us on LinkedIn: https://linkedin.com/company/oreilly-media. Watch us on YouTube: https://youtube.com/oreillymedia. Acknowledgments We are grateful to all those who helped us while we were writing this book: the staff at O’Reilly, especially Corbin Collins and Elizabeth Faerm, whose efforts kept us on track. We are grateful to Simone Geib, who provided deep technical exper‐ tise and patient guidance on the content for this book. We thank our reviewers Ramsundernag Changalva, Shivani Marrero, Tahn Amuchastegui, Audrey Honeycutt, and Ethan Port for their expert reviews of our treatment of the subject matter. Preface | xv
Page
18
(This page has no text content)
Page
19
CHAPTER 1 The World of Integrations Welcome to the world of integrations, where the magic of connecting systems, data, and people transforms what we can accomplish. We are getting more connected and faster than ever, and integration is no longer just nice to have—it’s essential. This book is your guide to understanding what makes integration tick and how MuleSoft can help you build solutions to tackle real-world challenges. Whether you’re diving in for the first time or you’re already deep in the integration game, we’re excited to be on this journey with you. MuleSoft is indeed like that trusty, hardworking mule, doing the heavy lifting so you don’t have to (and with way fewer hay bales involved). It’s not just a platform; it’s a game changer that helps bring innovation, speed, and flexibility into your integra‐ tions. With AI-driven tools like Intelligent Document Processing and AI-assisted flow building, MuleSoft is keeping us all on the cutting edge by making automating data capture and building adaptable workflows easier than ever. By blending API-led connectivity with these new AI-powered tools, MuleSoft empowers you to create integrations that move at the speed of today’s digital pace and do it with style. Integration is a journey, one that will totally transform how you approach building and scaling. Each chapter in this book invites you to learn, experiment, and build something impactful. MuleSoft’s possibilities are vast, and with these new AI capabili‐ ties, there’s never been a better time to hitch up that digital mule and get to work. Let’s make your integration vision a reality. Imagine each integration as part of a bigger puzzle. Build reusable APIs for each layer: experience, process, and system. It’s like play‐ ing with Legos: once the pieces exist, you mix, match, and boom— everything just clicks! Who doesn’t love building something that actually works without extra duct tape? 1
Page
20
Super Routes Logistics In this book, we’ll be helping a fictional logistics company, Super Routes Logistics (SRL), integrate their proprietary cost-analysis software with MuleSoft to offer real- time quotes and delivery times to customers. They want to include variables such as traffic conditions, package load, and even driver availability in the analytics model. Their goal is to optimize operations and reduce costs. Now, these guys aren’t your run-of-the-mill delivery service. No, they’re in the regional freight and delivery game, and they’ve got big plans. They want to flip the logistics world on its head using some really smart tech, but they want to do this while helping small- to medium-sized businesses. SRL knows that these smaller companies often get the short end of the stick or can’t afford the big logistics players, which is SRL’s differentiator. They offer shipping solutions that are easy on the wallet, super efficient, and totally transparent. This way, businesses can focus on what they do best—running their businesses— while SRL handles all the shipping headaches. Milestones Founded in 2010, SRL has rapidly ascended as a leader in the logistics and supply chain industry. Below are some milestones the company is proud of: 2011 Launched operations in North America 2012 Introduced customer portal 2013 Purchased Salesforce license for customer management 2019 Introduced proprietary cost-analysis software 2020 Achieved a 97% customer satisfaction rate 2023 Purchased MuleSoft licenses and intends to use the product to implement its real-time analytics shipping solution 2 | Chapter 1: The World of Integrations