Reading Time: 12 minutes

Mary Joy Sabal, Integration Technical Lead at Datacom is a multi-MuleSoft Certified Developer and Architect. She frequently speaks at Meetups and is the Wellington Meetup group leader. Joy shared how to use Maven Archetypes to create MuleSoft API project templates at MuleSoft CONNECT:Now JAPAC. 

MuleSoft API Project Templates are great tools for integration projects. Throughout this blog, I will provide tips for using Maven Archetypes to simplify the creation of these templates as well as discuss the various benefits of doing so. We’ll look at technical challenges you might face, an example use case, and how to leverage Anypoint Exchange in conjunction with Maven. My demonstration is also shared at the end of this blog if you are interested in trying it for yourself! 

latest report
Learn why we are the Leaders in API management and iPaaS
Read reports

To begin, let’s take a look at real-life scenarios in which using an API Project Template would be beneficial for your organization:

  • A new MuleSoft client needs help to upskill developers. This requires significant time for each team or line of business to review the MuleSoft project structure — and more importantly, to enforce best practices and technical governance. These are mainly technical challenges experienced during onboarding and the process would be overwhelming for a new developer.
  • As your application network grows, you will be building many APIs within a short timeframe. Each developer or team might have their own way of building APIs causing each API to have its own standard base structure of the project. Thus, the team will probably copy and paste the base structure of their API project, as well as configure its core dependencies all over again to ensure consistency.
  • A new Mule developer comes along and lands on the repository page. If your project structure is a massive dump of files or a nested mess of directories, the developer might look elsewhere before even reading your structured documentation. Thus, it will be confusing which project structure to follow meaning they are less likely to follow your structure since there isn’t a standard one in place.

To summarize, the technical challenges teams may face without having a standard API Template include:

  • Consuming significant development time 
  • Inconsistent project structures
  • Unable to meet development standards nor follow technical governance when building APIs

All of these challenges are avoidable using Maven and Anypoint Exchange. Let’s dive into what these features are and how to use them to build a MuleSoft API Project template.

What is Maven in MuleSoft?

Maven is a dependency management utility that Mule implements to enhance project development. All new projects created in Anypoint Studio 7.X are configured Maven by default and one of its plug-ins is Maven Archetypes.

Maven Archetypes create a project structure as per its template from which all other projects are created. Maven provides a large list of different types of project templates. For this blog, we will focus on archetype:create-from-project and archetype:generate.

Before we deep dive, I’ll run you through a few common terms when dealing with Maven.

POM (Project Object Model)

File: pom.xml

This is a fundamental unit of work in Maven. It is an XML file that contains information about the project and configuration details used by Maven to build the project. It contains default values for most projects. This is where you declare the project dependencies as well. More information here.

Archetype Descriptor

File: archetype-metadata.xml

The Archetype Descriptor is the heart or metadata of the archetype project. More information here:

Archetype Properties

File: archetype.properties

There are default properties or placeholders in the Maven archetype,however you can also define your own placeholders.

Create a Custom Mule Project

Now that you are familiar with the basics of Maven, let’s get into implementation. To start, we will create a custom project tailored according to your organization’s needs. This will be your baseline of all the future MuleSoft API Projects. At this stage, we will enforce the best practices and technical governance in project development as seen in the steps below.

  1. The Mule Configuration File Structure should ideally have five XML files. Note that domain will act as a placeholder. This will change dynamically based on your new API name. 
  • domain-interface.xml
    • The entry point of your project.
  • domain-impl.xml
    • The implementation layer, this is called by the interface. This could contain the business logic and transformations specific to a method.
  • commons-services.xml
    • These are common flows that can be called by either the interface or implementation layer.
  • global-configs.xml
    • Global configs are common configurations such as HTTP listener and request, autodiscovery ID, object store, etc. For our custom base project, we will set up the basic configurations below:

  • global-error-handler.xml
    • Here you can consolidate all error handling in this file and later in reference within your flow.
  1. Modify the pom.xml to add the common dependencies that you think you’ll use often across all your APIs including MUnit, MUnit Tools, Secure Configuration Properties, JSON Logger, JSON Module (Validation), etc.
  1. Resources Structure should contain the packages shown below. All DataWeave files should be stored under dwls.
  1. Create archetype.properties to add custom placeholders that we will need during project generation. This should be located outside the Mule custom project.

  1. Safely hide sensitive properties in mule-artifact.json such as mule.key, anypoint.platform.client_secret, splunk.token, etc. You can verify this once you deploy the API to Runtime Manager. Check the Properties tab.

  1. Configure log4j to push the logs to Cloudhub and rename the file based on the Mule application. You can add a Splunk appender as well if need be.
<!-- Log4J2CloudhubLogAppender = Send log data to Cloudhub -->
       <Log4J2CloudhubLogAppender name="cloudhub"
               addressProvider="com.mulesoft.ch.logging.DefaultAggregatorAddressProvider"
               applicationContext="com.mulesoft.ch.logging.DefaultApplicationContext"
               appendRetryIntervalMs="${sys:logging.appendRetryInterval}"
               appendMaxAttempts="${sys:logging.appendMaxAttempts}"
               batchSendIntervalMs="${sys:logging.batchSendInterval}"
               batchMaxRecords="${sys:logging.batchMaxRecords}"
               memBufferMaxSize="${sys:logging.memBufferMaxSize}"
               journalMaxWriteBatchSize="${sys:logging.journalMaxBatchSize}"
               journalMaxFileSize="${sys:logging.journalMaxFileSize}"
               clientMaxPacketSize="${sys:logging.clientMaxPacketSize}"
               clientConnectTimeoutMs="${sys:logging.clientConnectTimeout}"
               clientSocketTimeoutMs="${sys:logging.clientSocketTimeout}"
               serverAddressPollIntervalMs="${sys:logging.serverAddressPollInterval}"
               serverHeartbeatSendIntervalMs="${sys:logging.serverHeartbeatSendIntervalMs}"
               statisticsPrintIntervalMs="${sys:logging.statisticsPrintIntervalMs}">
           <PatternLayout pattern="[%d{MM-dd HH:mm:ss}] %-5p %c{1} [%t]: %m%n"/>
       </Log4J2CloudhubLogAppender>
   </Appenders>
   <Loggers>

Now that we have our custom project ready, we will publish it as a template to Anypoint Exchange to be shared across the developer team.

Anypoint Exchange

Anypoint Exchange is a one-stop-shop for connectors and templates, which you could share across your organization. From your Anypoint Studio, you could publish the custom project to Anypoint Exchange. The project type would be a template.

Back to one of our use cases, now that we created a MuleSoft API Project Template as new Muleys onboard they just need to download the api-template (custom project) asset from Anypoint Exchange and start their journey of Mule development using Anypoint Studio.

After downloading the asset, we will now proceed to our Maven Archetypes.

Maven archetype:create-from-project 

This operation creates a Maven Archetype from a custom or existing project. In short, “a template on top of a template.” 

  1. Download the api-template from Anypoint Exchange.
  2. From your api-template directory run the command: mvn archetype:create-from-project -Darchetype.properties=../archetype.properties
  3. From your Anypoint Studio, locate archetype-metadata.xml under target/generated-sources/archetype/src/main/resources/META-INF/maven.Modify the archetype-metadata.xml to include or exclude files or folders. By default, Maven excludes empty packages during the project generation. So in this case, we have to update the archetype-metadata.xml to include the empty packages when we generate a new project.
  1. Go to the archetype folder and do a Maven install. This will upload the artifact to your local .m2 repository: cd target/generated-sources/archetype mvn install

Maven archetype:generate 

From the generated Maven Archetype that contains our custom project, we will generate a new Maven project for your new API.

  1. From outside of your api-template project directory, run the command.
mvn archetype:generate 
-DarchetypeGroupId= 
-DarchetypeArtifactId=api-template-archetype
-DarchetypeVersion=1.0.0 
-Ddomain=
-DapiDescription=
  1. Then it will enter interactive mode.
[INFO] Generating project in Interactive mode
[INFO] Archetype repository not defined. Using the one from [d761a7b1-1d1a-44fb-ad71-685ec9133636:api-template-archetype:1.0.0] found in catalog local
Define value for property 'groupId': com.joycompany
Define value for property 'artifactId': joy-sys-api
Define value for property 'version' 1.0-SNAPSHOT: :
Define value for property 'package' com.joycompany: :
  1. Import the newly created project into your Anypoint Studio.

You’ve got a newly generated Mule API Project Structure in less than 10 minutes. What a relief!

Benefits of creating a MuleSoft API Project Template 

There are numerous benefits of creating a MuleSoft API Project Template including:

  • Standardize project development
  • Preconfigured dependencies
  • Unified log4j format
  • Safely hidden properties for sensitive properties
  • Focus on implementing business specific requirements
  • Speed up your development time
  • Enable developers to easily follow best practices

Just as code style, API design, and automation — project structure is essential for a healthy development cycle. It is a crucial part of software integration.

If you have any questions, please feel free to reach out to me on LinkedIn. You can find my recorded presentation here.