---
schema_version: "1"
id: f21fb5118bcc135f7ae480393303d290d49cccf41c17cca047a89b10ad1c5f8d
title: Mule 4 Custom Policy Workflow
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-gateway/policies-custom-getting-started.md
canonical_url: https://docs.mulesoft.com/mule-gateway/policies-custom-getting-started
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 50d11275ea0f2b2c19e224a0a069453d288080c4c95259fc3472212c13fdf898
description: MuleSoft Documentation Site
latest: true
---
---
product: Mule Gateway
---

# Mule 4 Custom Policy Workflow

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Custom Policies are policies that anyone can develop and apply to their APIs, with the intention of
extending existing functionality or defining new ones.

The current workflow to get a working policy for Mule 4 that can be applied in Anypoint Platform
consists of:

1.  Develop the policy.

2.  Package the policy.

3.  Upload the resulting policy assets to Exchange.

4.  Apply the policy to any API through API Manager.

## Setting up a project with the archetype

The first step to develop a custom policy consists in setting up a project with the required
files.  
The easiest way to gather all your required files is by using the maven archetype. This archetype
creates all the necessary files for you. Then, use Maven to package your custom policy into a
deployable JAR.

The Maven archetype is not currently available in a Maven Central Repository, so you need to
configure your Maven settings to find the archetype in one of MuleSoft’s repositories.

One way to do so is by configuring Maven’s `settings.xml` with the following section:

```xml
 <profiles>
   <profile>
     <id>archetype-repository</id>
     <repositories>
       <repository>
         <id>archetype</id>
         <name>Mule Repository</name>
         <url>https://repository.mulesoft.org/nexus/content/repositories/public</url>
         <releases>
           <enabled>true</enabled>
           <checksumPolicy>fail</checksumPolicy>
         </releases>
         <snapshots>
           <enabled>true</enabled>
           <checksumPolicy>warn</checksumPolicy>
         </snapshots>
       </repository>
     </repositories>
   </profile>
 </profiles>
```

Once Maven is configured:

1.  Create a new directory where the custom policy project will live.

2.  Go to that directory in the command line.

3.  Execute the following command:

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

    Replace:

    - `${orgId}` with the Anypoint Platform Organization Id where the policy will be uploaded.

      - Get your organization ID from **Access Management > Organization**:

        - Click the name of your organization.

        - Copy the UUID from the browser address. For example, copy
          _2a4b93c3-7899-4ea7-9374-f787744d8784_ from the URL.

    - `${policyName}` with the desired name for the custom policy.

4.  Before finishing, Maven asks you to set up:

    - **policyDescription**: A brief description of your policy.

    - **policyName**: The identifier name of your policy.

      > [!TIP] You can create a policy that supports encryption by passing the
      > `-DencryptionSupported=true` property.  
      > See [Custom Policy Encryption for more information](https://docs.mulesoft.com/mule-gateway/mule-gateway-encryption-mule4#custom-policy-encryption).

After running the command, the project’s directory will have a structure similar to:

my-custom-policy/ ├── my-custom-policy.yaml ├── mule-artifact.json ├── pom.xml └── src └── main └──
mule └── template.xml

Those four files are the basic ones needed for having a working policy.

- **pom.xml**

  - `groupId` is defined as the organization ID used with the archetype. This value must remain as
    it is.

  - `mule-policy` packaging, so packager plugin can successfully build the JAR.

  - `distributionManagement` section is defined pointing to user’s Exchange.

  - `mule-maven-plugin` responsible of packaging the policy into a deployable jar

  - `maven-deploy-plugin` configured to deploy both the resulting jar and the YAML when uploading
    the policy to Exchange

- **mule-artifact.json** exists for the mule-maven-plugin. This is the same file you need for Mule
  applications.

- **my-custom-policy.yaml** renders the policy configuration UI. If this file is not provided, the
  policy won’t be able to be applied through API Platform’s UI.

- **template.xml** where the actual logic of the policy and Mule configuration that defines the
  policy behavior.

The archetype, by default, generates a basic policy that sets the returned HTTP Response payload to
a “Hello World!” message. That is implemented with the following configuration:

XML element

```xml
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:http="http://www.mulesoft.org/schema/mule/http"
     xmlns:http-policy="http://www.mulesoft.org/schema/mule/http-policy"
     xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
              http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
              http://www.mulesoft.org/schema/mule/http-policy http://www.mulesoft.org/schema/mule/http-policy/current/mule-http-policy.xsd">

   <http-policy:proxy name="{{{policyId}}}-custom-policy"> (1)
       <http-policy:source> (2)
           <http-policy:execute-next/> (3)
           <set-payload value="Hello World!" />
       </http-policy:source>
   </http-policy:proxy>
</mule>
```

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>Basic structure for defining a policy. <code>{{{policyId}}}</code> refers to a HandleBars variable. HandleBars is a templating framework that allows users to create more complex policies.</td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Source refers to inbound HTTP requests. The other option is to define logic for an outbound HTTP request.</td></tr><tr><td><i data-value="3"></i><b>3</b></td><td>Explicit element which indicates that the next policy or flow should be executed. Any element placed before it will be executed before jumping to the next, and any element placed after that will be executed after returning from the next.</td></tr></tbody></table>

Now that the project is set, you can update the logic as necessary with your requirements.  
The policy engine is powerful and enables you to do things like modifying HTTP requests and
responses, logging, caching, throttling, and almost any other integration that you can do with the
Mule runtime engine.

## See Also

- [Packaging a Custom Policy](https://docs.mulesoft.com/mule-gateway/policies-custom-package)

- [Uploading a Custom Policy to Exchange](https://docs.mulesoft.com/mule-gateway/policies-custom-upload-to-exchange)

- [Reviewing Custom Policy concepts](https://docs.mulesoft.com/mule-gateway/policies-custom-overview)

- [Custom Policy Example](https://docs.mulesoft.com/mule-gateway/policies-custom-response-example)