# MuleSoft

{% columns %}
{% column %}
Deploy Alma on MuleSoft to **capture API gateway HTTP traffic** without app code changes.

The Alma Capture Policy is a MuleSoft API Gateway custom policy.

It captures HTTP request/response metadata + payloads and exports them asynchronously to an OpenTelemetry Collector over OTLP/HTTP(S).

If you’re new to Alma, start with [Alma Overview](/about-alma/quickstart.md).
{% endcolumn %}

{% column %}
![](/files/9jRyJx2rOg2p25Z7J1Ia)
{% endcolumn %}
{% endcolumns %}

### How it works

When applied to an API (or as an automated policy), the policy:

1. Intercepts inbound traffic at the Mule gateway.
2. Captures HTTP request metadata and payload data.
3. Invokes the downstream API (`http-policy:execute-next`).
4. Captures HTTP response metadata and payload data.
5. Exports captured telemetry asynchronously to an OpenTelemetry Collector.

The policy runs inline using the Mule 4 custom policy model (`http-policy:proxy`).

### Telemetry export

* Protocol: **OTLP**
* Transport: **HTTP(S)**
* Default port: **4318**
* Encoding: **Protobuf** (`application/x-protobuf`)
* TLS: **HTTPS**

Typical gateway endpoint:

* `https://gw-<host>.alma-security.com/`

{% hint style="info" %}
Export is **asynchronous** and should not block API request processing.
{% endhint %}

### Prerequisites

* MuleSoft Anypoint Platform permissions to:
  * upload a custom policy to **Anypoint Exchange**
  * apply policies in **API Manager**
* Maven (`mvn`) installed (for Maven-based publishing).
* The Alma gateway endpoint reachable from Mule runtime over **HTTPS** on **port 4318**.
* TLS trust configured so Mule trusts the collector’s certificate.

### Install and apply the policy

Use the Maven flow below.

For MuleSoft’s baseline flow, see: [Upload a Custom Policy to Exchange](https://docs.mulesoft.com/mule-gateway/policies-custom-upload-to-exchange).

{% stepper %}
{% step %}

### 1) Download and unzip the policy bundle

1. Download `alma-mule-policy.zip` from your Alma distribution channel.
2. Unzip it.
3. Open the extracted policy folder.

You should see the Mule 4 custom policy files, including `pom.xml` and `template.xml`.
{% endstep %}

{% step %}

### 2) Configure Maven credentials for Exchange

Update `~/.m2/settings.xml` with your Anypoint credentials:

{% code title="\~/.m2/settings.xml" %}

```xml
<?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>anypoint-exchange-v3</id>
           <username>xxxxx</username>
           <password>xxxxx</password>
       </server>
   </servers>
</settings>
```

{% endcode %}

{% hint style="warning" %}
Keep the server ID as `anypoint-exchange-v3`. MuleSoft uses that value during `mvn clean deploy`.
{% endhint %}
{% endstep %}

{% step %}

### 3) Set the Organization ID and publish

1. Open `pom.xml`.
2. Set the `groupId` to your Anypoint **Organization ID**.
3. You can copy the Organization ID from the Anypoint URL:

```
https://anypoint.mulesoft.com/home/organizations/<organization-id>/
```

4. From the policy folder, run:

```bash
mvn clean deploy
```

{% hint style="info" %}
Run the deploy command from the folder that contains the policy `pom.xml`.
{% endhint %}
{% endstep %}

{% step %}

### 4) Apply the policy in API Manager

After the Maven publish succeeds:

1. Open **API Manager** in Anypoint Platform.
2. Select the target API.
3. On the API page, open **Policies**.
4. In the policies list, find the uploaded **Alma Capture Policy**.
5. Add it.
6. Save and apply the configuration.

Use the screenshots below for the UI flow.

<figure><img src="/files/EakZBlMvroe1i4U4dYk5" alt="Policies view in API Manager showing the uploaded Alma Capture Policy."><figcaption><p>From the API page, open <strong>Policies</strong> to see the uploaded <code>Alma Capture Policy</code>.</p></figcaption></figure>

<figure><img src="/files/5p38qSN1uaMYz5T1eCEN" alt="API Manager flow for adding the Alma Capture Policy."><figcaption><p>Open the target API and start the policy flow.</p></figcaption></figure>

<figure><img src="/files/CZLobd0jLdrRGovvLHAE" alt="Policy selection screen in Anypoint API Manager."><figcaption><p>Select <code>Alma Capture Policy</code> from the available policies.</p></figcaption></figure>

<figure><img src="/files/uFTLAGVAXCjkVy4ZiPTL" alt="Policy configuration screen in Anypoint API Manager."><figcaption><p>Review the policy configuration before applying it.</p></figcaption></figure>

#### Optional: capture only specific APIs

If you only want to capture specific APIs, open the policy’s **Advanced** section.

Select the HTTP **method**, then add an **API regex** for the endpoints you want to capture.

Use this to limit capture to specific routes instead of all traffic on the API.

<figure><img src="/files/ua1AaOHbhVeuKMCP8Ie4" alt="Advanced policy settings in MuleSoft API Manager for filtering by HTTP method and API regex."><figcaption><p>Use the <strong>Advanced</strong> section to filter capture by HTTP method and API regex.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Verify

1. Send traffic through the API.
2. Confirm the gateway endpoint is receiving data on **port 4318**.
3. Confirm traces and logs appear in your backend.

### Upgrade and uninstall

#### Upgrade

1. Publish a newer policy version to Exchange.
2. In API Manager, select the existing policy and change the policy version.
3. Apply the updated policy version.

#### Uninstall

API Manager → **Policies** → remove **Alma Capture Policy**.\\


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alma-security.com/integrations/api-gateways/mulesoft.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.