Step-by-Step Guide on Publishing Custom Policies to PCE Exchange

Solution and Workaround Steps

To resolve this issue, follow these key steps:

1. Update the mule-maven-plugin version: Ensuring a modern and compatible version of the plugin.

2. Specific Connected App Permissions: Configuring a Connected App with precisely the necessary Exchange permissions, avoiding overly broad access.

3. Using a Specific Maven Version: Standardizing local Maven environment to a version that proved compatible with the deployment.

Step-by-Step Process for Publishing

Here are the detailed steps should be followed to get the custom policies published to PCE Exchange.

Prerequisites:

Before starting, make sure you had the following in place:

• Anypoint Platform Account: With access to your PCE instance.

• Maven: Specifically, use version 3.9.6 installed on your local machine.

• Java Development Kit (JDK): Java Version 8 or higher.

• MuleSoft Anypoint Studio (Optional): While not strictly required for the deployment itself, it's useful for policy development and local testing.

Step 1: Creating a Dedicated Connected App in Anypoint Platform

To authenticate via Maven deployment with Anypoint Platform Exchange, we need to craete a Connected App.

1. Log in to Anypoint Platform: Please access to your PCE instance.

2. Navigated to Access Management: Access Management > Connected Apps.

3. Created a New App:  Click on Create App.

4. Configured the App Details:

   • App Name: give a clear name like PCE-Exchange-Policy-Publisher.

   • App Type:  select Client Credentials.

   • Grant Type: choose Client Credentials.

   • Scopes (This was crucial!):

     • Under Exchange, grant Exchange Contributor permissions.

     • Under Exchange, grant Exchange Viewer permissions.

     • Important: deliberately avoided selecting General Admin scopes or other excessively broad permissions. In our testing showed that focused Exchange-specific permissions were sufficient and worked without issues.

5. Saved the App: After adding the scopes, click Save.

6. Recorded Credentials: Immediately after saving, copy the Client ID and Client Secret. Please copy the credentials  as we needed them for Maven settings.xml file.
   
   

Step 2: Configuring Maven settings.xml

We need to add a server entry to the Maven settings.xml file, using the credentials from the Connected App.

1. Located settings.xml: You will find the file at ~/.m2/settings.xml (on macOS/Linux; for Windows, it's %USERPROFILE%\.m2\settings.xml). If it didn't exist, please create it.

2. Added the Server Entry: Insert the following server block within the <servers> section of the settings.xml. Please make sure to replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with the actual credentials that copied from Connected App.
   
   

With Username and Password combination 

<settings>
    <servers>
      <server>
        <id>exchange-server</id>
        <username>YOUR_CLIENT_ID</username>
        <password>YOUR_CLIENT_SECRET</password>
      </server>
    </servers>
</settings>

With Client Connected app combination 

<settings>
    <servers>
      <server>
        <id>exchange-server</id>
        <username>~~~Client~~~</username>
        <password>YOUR_CLIENT_SECRET</password>
      </server>
    </servers>
</settings>

• The <id>exchange-server</id> is important; it must match the repository ID that's typically defined in the policy's pom.xml for Exchange deployments.

• The username and password here correspond to the Connected App's Client ID and Client Secret, enabling authentication.

Step 3: Add certs before running the maven commands 

Note: Based on your java version, update the cacerts path

Use the following command to generate a custom policy project:

  
keytool -printcert -sslserver ${ANYPOINT_DNS}:443 -rfc > /tmp/anypoint.crt
keytool -importcert -alias my-company.com -keystore 
/etc/ssl/certs/java/cacerts -storepass changeit -file /tmp/anypoint.crt  

Step 4: Preparing the Custom Policy Project

Whether starting a new project or working with an existing one, please ensure its pom.xml was correctly configured.

1. Project Creation (if new): If you were starting fresh, please use the Mule custom policy archetype:
   Bash:

mvn -Parchetype-repository archetype:generate \
  -DarchetypeGroupId=org.mule.tools \
  -DarchetypeArtifactId=api-gateway-custom-policy-archetype \
  -DarchetypeVersion=1.0.0 \
  -DgroupId=${orgId} \
  -DartifactId=${policyName} \
  -Dversion=1.0.0-SNAPSHOT \
  -Dpackage=mule-policy

2. Then follow the prompts to set your groupId, artifactId, version, etc.

3. Update the pom.xml: Open the pom.xml file of custom policy project.

   • Critical Update: Please make sure to update the mule-maven-plugin version. The version 4.5.1  will work reliably. Locate the plugin entry within the <build><plugins> section and update its version:
     XML:

<plugin>
    <groupId>org.mule.tools.maven</groupId>
    <artifactId>mule-maven-plugin</artifactId>
    <version>4.5.1</version>
    <extensions>true</extensions>
    <configuration>
      <skipDeploy>false</skipDeploy>
    </configuration>
</plugin>

• Repository Configuration Check: Verify that the distributionManagement section in pom.xml correctly pointed to the Exchange repository with the exchange-server ID. The archetype usually sets this up correctly:

<distributionManagement>
    <repository>
      <id>exchange-server</id>
      <name>Exchange Repository</name>
      <url>
        https://pce41-8node-26e658a2edf83013.elb.us-east-2.amazonaws.com/exchange/api/v2/organizations/${project.organizationId}/maven
      </url>
    </repository>
</distributionManagement>
  

• The ${project.organizationId} placeholder is resolved from policy's properties or passed via Maven.

Step 5: Setting Local Maven Version

This step was a key part of the workaround. Maven version 3.9.6 was crucial for successful deployment.

mvn -v

2. Installed Maven 3.9.6+ (if necessary): If your version was different, download Maven 3.9.6 from the Apache Maven Archive and updated PATH environment variable to point to its bin directory.

Step 6: Deploying the Custom Policy to PCE Exchange

With all the configurations in place, proceed with the deployment.

1. Navigated to Project Directory: In terminal, navigate to the root directory of custom policy project (where pom.xml is located).

2. Run the Maven Deploy Command:
   Bash:

mvn clean deploy -Dmule.deploy.organizationId=

• Replace <OUR_ORGANIZATION_ID> with your actual Anypoint Platform Organization ID (found under Access Management > Organization in Anypoint Platform).

• The clean deploy command handles compilation, packaging, and deployment to the configured PCE Exchange repository. The -Dmule.deploy.organizationId property is vital for the mule-maven-plugin to target the correct organization within Exchange.
  
  

3. Verified Deployment:

   • Upon successful completion, you will see BUILD SUCCESS in terminal.

   • Finally, navigat to Anypoint Platform > Exchange within PCE instance. The published custom policy will be listed there, confirming its successful publication and readiness for use.

   • Login to PCE Environment and navigate to Exchange and validate the deployment