Publishing Assets Using Maven | MuleSoft Documentation
# Publishing Assets Using Maven
Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.  
---  
With the Anypoint Exchange Maven Facade API, Apache Maven clients can publish and consume Exchange assets, including these asset types:
  * Connectors
  * Mule applications
  * Examples
  * Templates
  * Policies
  * Custom assets


The Exchange Maven Facade API does not support deleting assets. To delete an asset, use the Exchange user interface or the Exchange API.
The Exchange Maven Facade API does not support dynamic parameters for fields other than `<artifactId>` and `<version>`. If the uploaded asset has a defined parent, the parent must be a valid and already uploaded Exchange asset for the dynamic parameters to be properly interpreted.
New assets count toward your organization’s asset limit.
## Prerequisites
To benefit from this documentation, you must be familiar with Maven, programming concepts, and command line operations on your computer or server.
Include the required plugin `org.mule.tools.maven.mule-maven-plugin` in your POM file. Do not include the plugin `org.apache.maven.plugins.maven-deploy-plugin` in your POM file or settings file, because it is not compatible with the required plugin.
If you use the Anypoint Exchange Maven Facade API version 3 to publish assets to Exchange, you must have the Mule Maven plugin version 3.5.0 or later.
You must have a unique artifact name and organization ID to publish your asset.
The US cloud and EU cloud use slightly different URLs, as shown in the examples.
## View Your Organization ID
To construct the elements of a Maven POM file, you need to determine your organization ID:
  1. Log in to Anypoint Platform and click **Access Management**.
  2. Click the name of the top-level organization or a business group, and view your organization ID in the organization information screen.
  3. Copy the organization ID so you can add it to your project’s POM file for the following examples.


## Publish an Asset to Exchange Using Maven
Refer to examples of publishing each asset type with Maven in the repository located at `https://github.com/mulesoft-labs/exchange-documentation-samples`.
The steps to publish an asset with Maven are slightly different for each asset type, and different assets use different Maven plugins, so check the examples in the repository for an example that matches your asset type. For example, use `exchange-mule-maven-plugin` to publish a custom asset, and use `mule-maven-plugin` to publish an extension.
The following example shows how to publish a Mule 4 asset such as an application, example, or template.
  1. In your project’s POM file, set `groupId` to your organization ID:
```
 ...
 <groupId>ORGANIZATION_ID</groupId>
 ...
```

If you are publishing your asset to the root organization, the group ID is the same as the organization ID. The URL format is:
`https://maven.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven`
In the EU, use:
`https://maven.eu1.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven`
In the Canada cloud, use:
`https://maven.ca1.platform.mulesoft.com/api/v3/maven`
In the Japan cloud, use:
`https://maven.jp1.platform.mulesoft.com/api/v3/maven`
When using MuleSoft Government Cloud, use:
`https://maven.gov.anypoint.mulesoft.com/api/v2/organizations/ORGANIZATION_ID/maven`
If you are publishing your asset to a business group, the group ID is the same as the business group ID. The URL format is:
`https://maven.anypoint.mulesoft.com/api/v3/organizations/BUSINESS_GROUP_ID/maven`
In the EU, use:
`https://maven.eu1.anypoint.mulesoft.com/api/v3/organizations/BUSINESS_GROUP_ID/maven`
When using MuleSoft Government Cloud, use:
`https://maven.gov.anypoint.mulesoft.com/api/v2/organizations/BUSINESS_GROUP_ID/maven`
  2. In your project’s POM file, include `mule-maven-plugin` and set the correct classifier (in this example `mule-application-example`).
In this example, it is not necessary to set the asset type because it is inferred from the classifier:
```
...
<name>Hello World Application Example</name>
<description>A mule application example uploaded using Exchange Maven Facade v3</description>
<build>
  <plugins>
    <plugin>
      <groupId>org.mule.tools.maven</groupId>
      <artifactId>mule-maven-plugin</artifactId>
      <version>3.5.0</version>
      <extensions>true</extensions>
      <configuration>
        <classifier>mule-application</classifier>
      </configuration>
    </plugin>
  </plugins>
</build>
...
```

You must set the `<classifier>` element to make the asset visible in Exchange.
The `name` property is required and represents the visible name of the asset. If you are publishing the first version of a GA (GroupId and AssetId combination), the asset name is taken from the POM file. If there is already at least one version of the GA, the `name` property is ignored. You can change the name in the asset portal as described in Describe an Asset.
The `description` property is optional and represents the description of the asset. If you are publishing the first version of a GA (GroupId and AssetId combination), the asset description is taken from the POM file. If there is already at least one version of the GA, the `description` property is ignored. You can change the description in the asset portal as described in Describe an Asset.
Deploy Mule 3 applications by setting the property `<type>` to `app` and setting `<classifier>` as `mule-application` in the `mule-maven-plugin` configuration if the `mule-maven-plugin` is used.
Deploy Mule 3 `templates` and `examples` by using Anypoint Studio 6.3 or later.
For Mule 4 applications, do not specify the `<type>` element. In the `mule-maven-plugin` configuration, set `<classifier>` as `mule-application` (default), `mule-application-template`, `mule-application-example`, or `mule-policy`.
Mule 3 and Mule 4 applications are not displayed in the Exchange asset list.
  3. Add the Maven facade as a repository in the distribution management section of your project’s POM file:
```
 ...
 <distributionManagement>
  <repository>
   <id>Repository</id>
   <name>Corporate Repository</name>
   <url>https://maven.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven</url>
   <layout>default</layout>
  </repository>
 </distributionManagement>
 ...
```

In the EU, use:
```
 ...
 <distributionManagement>
  <repository>
   <id>Repository</id>
   <name>Corporate Repository</name>
   <url>https://maven.eu1.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven</url>
   <layout>default</layout>
  </repository>
 </distributionManagement>
 ...
```

When using MuleSoft Government Cloud, use:
```
 ...
 <distributionManagement>
  <repository>
   <id>Repository</id>
   <name>Corporate Repository</name>
   <url>https://maven.gov.anypoint.mulesoft.com/api/v2/organizations/ORGANIZATION_ID/maven</url>
   <layout>default</layout>
  </repository>
 </distributionManagement>
 ...
```

The `<id>` and `<name>` elements are arbitrary names that you create to identify the repository and any other organizational identifiers. The `<id>` value must be the same in the `pom.xml` file as in the `~/.m2/settings.xml` file. The `<id>` value connects the `pom.xml` file with information to log in to the organization’s URL.
  4. Update the `settings.xml` file in your Maven `.m2` directory.
After you install Maven, the `mvn clean` command creates the `.m2` directory. The directory is `~/.m2` on macOS or Linux and `<default-drive>\Users\YOUR_USER_NAME\.m2` on Windows. It contains your Anypoint Platform credentials. The Maven client reads the settings file when Maven runs.
Example `settings.xml` file:
```
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
 <servers>
  <server>
   <id>Repository</id>
   <username>myusername</username>
   <password>mypassword</password>
  </server>
 </servers>
</settings>
```

  5. Publish your asset to Exchange using this Maven command:
  6. Search Exchange for the asset ID to find the asset.
5. Publish your asset to Exchange using this Maven command:
  6. Search Exchange for the asset ID to find the asset.


## Publish an Asset with Mutable Data
The Maven Facade API enables you to both create your asset and set the mutable data describing it in the same request. The mutable data of an asset includes tags, custom fields, categories, and documentation pages.
The GitHub repository of Exchange documentation examples includes a complete example of creating a Mule application template with documentation and tags.
Declare tags, custom fields, and categories in the `pom.xml` file in the properties section, with the XML property `key` set to the key of the custom field or category:
```
  ...
  <properties>
    <categories key="categoryKey">someValue</categories>
    <fields key="fieldKey">someValue</fields>
    <tags>tag1,tag2,tag3</tags>
  </properties>
  ...
```

To set documentation pages, create a documentation directory in `src/main/resources`. In the documentation directory, include each page as a Markdown file with a name such as `Getting Started.md`. Replace `Getting Started` with the title of the page. To include a terms and conditions page, put the content in a file named `terms.md`. Include resources such as images in the optional subdirectory `resources`. Specify the page order with the property `pageOrder` on the root of the main object in the optional file `config.json`:
```
{
 "pageOrder": ["home", "Getting Started", "Examples"]
}
```

Add the Maven Assembly Plugin in the `pom.xml` plugin section to package the documentation folder, and create a Maven Assembly Plugin configuration file such as this:
```
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-assembly-plugin</artifactId>
  <version>2.6</version>
  <configuration>
    <appendAssemblyId>true</appendAssemblyId>
  </configuration>
  <executions>
    <execution>
      <id>create-distribution</id>
      <phase>package</phase>
      <goals>
        <goal>single</goal>
      </goals>
      <configuration>
        <descriptors>
          <descriptor>/src/main/resources/docs-assembly/assembly.xml</descriptor>
        </descriptors>
      </configuration>
    </execution>
  </executions>
</plugin>
```

Create an `assembly.xml` file in `src/main/resources/docs-assembly`:
```
<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
  <id>docs</id>
  <formats>
    <format>zip</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <fileSets>
    <fileSet>
      <directory>${project.basedir}/src/main/resources/docs</directory>
      <outputDirectory>/</outputDirectory>
      <useDefaultExcludes>true</useDefaultExcludes>
    </fileSet>
  </fileSets>
</assembly>
```

## Asset Lifecycle State
A new asset version is in the `development` state or the default `stable` state.
To create an asset version in the `stable` state, use Maven normally.
To create an asset version in the `development` state, use the Anypoint Exchange Maven Facade API version 3 and set the version of the asset to `SNAPSHOT`. This behavior allows for backward compatibility with legacy APIs.
A `SNAPSHOT` asset is permanently in the `development` state and cannot be promoted to any other state.
An asset with the version `SNAPSHOT` published with the Anypoint Exchange Maven Facade API version 1 or version 2 has the state `stable`.
Uploading a `SNAPSHOT` template asset in the `development` state example:
In a terminal:
  1. Execute: `git clone https://github.com/mulesoft-labs/exchange-documentation-samples.git`
  2. Execute: `cd exchange-documentation-samples/template-snapshot`
  3. Edit the file `pom.xml` and replace the values `YOUR_ORG_ID`, `YOUR_GROUP_ID`, and `YOUR_ASSET_ID` with your asset’s organizationId, groupId, and assetId.
  4. Execute: `mvn clean deploy`
  5. Open your Exchange home page and view the template in the `development` state.


If you execute `mvn clean deploy` multiple times, the asset is overwritten without any errors.
An asset that is in development state and is not an SNAPSHOT version cannot be consumed through Maven.   
---  
## Publish a Custom Asset
Publish custom assets with the `exchange-mule-maven-plugin` plugin. The latest version of this plugin is 0.0.23.
This example shows the `build` section of `pom.xml`:
```
<build>
  <plugins>
    <plugin>
      <groupId>org.mule.tools.maven</groupId>
      <artifactId>exchange-mule-maven-plugin</artifactId>
      <version>0.0.23</version>
      <executions>
        <execution>
          <id>validate</id>
          <phase>validate</phase>
          <goals>
            <goal>exchange-pre-deploy</goal>
          </goals>
        </execution>
        <execution>
          <id>deploy</id>
          <phase>deploy</phase>
          <goals>
            <goal>exchange-deploy</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
```

## Publish a Parent POM Project and a Parent POM Dependant Project to Exchange
Parent POMs are published to Exchange as custom assets. See the previous section to publish a custom asset. If you want to publish a maven project, like a mule application, using the Mule Maven Plugin, and your maven project depends on a Parent Pom that has already included the exchange-mule-maven-plugin, you need to prevent the inheritance:
```
<build>
  <plugins>
    <plugin>
      <groupId>org.mule.tools.maven</groupId>
      <artifactId>exchange-mule-maven-plugin</artifactId>
      <version>0.0.23</version>
      <inherited>false</inherited>
      <executions>
        <execution>
          <id>validate</id>
          <phase>validate</phase>
          <goals>
            <goal>exchange-pre-deploy</goal>
          </goals>
        </execution>
        <execution>
          <id>deploy</id>
          <phase>deploy</phase>
          <goals>
            <goal>exchange-deploy</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
```
## Publish a Parent POM Project and a Parent POM Dependant Project to Exchange
Parent POMs are published to Exchange as custom assets. See the previous section to publish a custom asset. If you want to publish a maven project, like a mule application, using the Mule Maven Plugin, and your maven project depends on a Parent Pom that has already included the exchange-mule-maven-plugin, you need to prevent the inheritance:
```
<build>
  <plugins>
    <plugin>
      <groupId>org.mule.tools.maven</groupId>
      <artifactId>exchange-mule-maven-plugin</artifactId>
      <version>0.0.23</version>
      <inherited>false</inherited>
      <executions>
        <execution>
          <id>validate</id>
          <phase>validate</phase>
          <goals>
            <goal>exchange-pre-deploy</goal>
          </goals>
        </execution>
        <execution>
          <id>deploy</id>
          <phase>deploy</phase>
          <goals>
            <goal>exchange-deploy</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
```

### Troubleshooting
If the build fails during the deploy stage with a status code of 412 (Precondition Failed), then `<goal>exchange-pre-deploy</goal>` was not executed. To fix this error, ensure that goal is set inside the executions section of the plugin.
The error looks similar to this:
```
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.871 s
[INFO] Finished at: 2020-11-09T12:11:54-03:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-deploy-plugin:2.7:deploy (default-deploy) on project hello-world-pom: Failed to deploy artifacts: Could not transfer artifact 1da12ec1-7614-43a3-bf24-ff754cab8ddf:hello-world-pom:pom:1.0.3 from/to repository-id ([https://maven.anypoint.mulesoft.com/api/v3/organizations/orgId/maven/](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/)): Transfer failed for [https://maven.anypoint.mulesoft.com](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/)[/api/v3/organizations/](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/1da12ec1-7614-43a3-bf24-ff754cab8ddf/hello-world-pom/1.0.3/hello-world-pom-1.0.3.pom)[orgId](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/)[/maven/groupId/assetId/version/filename](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/1da12ec1-7614-43a3-bf24-ff754cab8ddf/hello-world-pom/1.0.3/hello-world-pom-1.0.3.pom) 412 -> [Help 1]
```

## Publish and Consume Federated Assets
Publishing and consuming federated assets requires token authentication or connected application authentication.
To use token authentication:
  1. Get an API bearer token by using a SAML assertion.
This is your access token.
  2. Open the `settings.xml` file at `C:\Users\YOUR_USER_NAME\.m2\settings.xml` on Windows, or at `~/.m2/settings.xml` on macOS or Linux.
  3. Do not change the value in `<username>`.
This value tells the platform that you’re using a token.
  4. Set the value in `<password>` to your access token:
```
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
     http://maven.apache.org/xsd/settings-1.0.0.xsd">
 <servers>
  <server>
   <id>Repository</id>
   <username>~~~Token~~~</username>
   <password>01234567-89ab-cdef-0123-456789abcdef</password>
  </server>
 </servers>
</settings>
```

  5. Save the `settings.xml` file.


To use connected application authentication:
  1. Create a connected application.
  2. Provide basic authentication and define the username as `~~~Client~~~` and the password as `clientID~?~clientSecret`.
    1. Replace `clientID` with the client ID.
    2. Replace `clientSecret` with the client secret.


Include the connected application in the file `settings.xml` in your repository:
```
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
 <servers>
  ...
  <server>
   <id>Repository</id>
   <username>~~~Client~~~</username>
   <password>clientID~?~clientSecret</password>
  </server>
 </servers>
</settings>
```

## Dependencies external to Exchange
Publish Java libraries and POM files as Exchange custom assets.
Mule 4 Extensions that declare dependencies that don’t exist in Maven Central or the MuleSoft Maven repositories are not currently supported.
## Document Your Exchange Assets
When you use Maven Facade to publish an asset to Exchange, a documentation portal is automatically created for it in Exchange and you can document it normally.
## Consume an Exchange Asset with Maven
With Maven Facade you can consume assets published in Exchange, including connectors, Mule applications, and REST APIs. To consume an Exchange asset, add the asset’s group ID, artifact ID, and version to the `dependencies` section of your project’s `pom.xml` file, and add the Maven facade as a repository in the `repositories` section.
```
<project xmlns="http://maven.apache.org/POM/4.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
           http://maven.apache.org/xsd/maven-4.0.0.xsd">
 ...
 <dependencies>
  <dependency>
   <groupId>org.mule.modules</groupId>
   <artifactId>mule-module-metoo</artifactId>
   <version>1.0.0</version>
  </dependency>
 </dependencies>
 ...
 <repositories>
  <repository>
   <id>Repository</id>
   <name>Corporate Repository</name>
   <url>https://maven.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven</url>
   <layout>default</layout>
  </repository>
 </repositories>
 ...
</project>
```

Replace `ORGANIZATION_ID` with your organization ID.
You can use `https://maven.anypoint.mulesoft.com/api/v3/maven` as a valid URL for the `<url>` value, because this is the default to publish to the root organization. In the EU, use `https://maven.eu1.anypoint.mulesoft.com/api/v3/maven` as the URL. When using MuleSoft Government Cloud, use `https://maven.gov.anypoint.mulesoft.com/api/v2/maven` as the URL.
In the EU, the `<repositories>` section is:
```
 <repositories>
  <repository>
   <id>Repository</id>
   <name>Corporate Repository</name>
   <url>https://maven.eu1.anypoint.mulesoft.com/api/v3/organizations/ORGANIZATION_ID/maven</url>
   <layout>default</layout>
  </repository>
 </repositories>
```

When using MuleSoft Government Cloud, the `<repositories>` section is:
```
 <repositories>
  <repository>
   <id>Repository</id>
   <name>Corporate Repository</name>
   <url>https://maven.gov.anypoint.mulesoft.com/api/v2/organizations/ORGANIZATION_ID/maven</url>
   <layout>default</layout>
  </repository>
 </repositories>
```

## See Also
  *   *   *