Configuration and Definition File Reference | MuleSoft Documentation
# Configuration and Definition File Reference
Find a complete technical reference for the configuration (XML) and definition (YAML) file for creating a custom policy.
## Policy Configuration XML File
The policy configuration is an XML file that implements the actual execution of the policy. The configuration achieves this by leveraging the elements in a flow when creating a Mule Runtime application. All of the elements usable in Mule Runtime can be used in a custom policy.
The policy configuration defines the actual processes that carry out the implementation of the policy. Structured like a Mule app, you wrap content in the following tags:
```
<policy>
</policy>
```

The opening `<policy>` tag includes references to all of the Mule XSD files used in the policy. Some of the Mule elements you can add require adding the corresponding XSD reference too.
You add properties `id` and `policyName` to the `<policy>` element parameters to gather data about the API for analytics.
By default, when you create a custom policy, you have access to the following default configuration properties that you can reference in the configuration XML file:
Property | Description  
---|---  
A unique ID for the current policy  
The full URI for the inbound endpoint of the API  
Unique ID number for the API  
`apiVersionId` |  Unique ID number for the API version  
Name of the API  
`isRamlEndpoint` |  Boolean that determines if the endpoint is linked to a RAML definition file  
`isWsdlEndpoint` |  Boolean that determines if the endpoint is linked to a WSDL definition file  
`isHttpEndpoint` |  Boolean that determines if the endpoint follows the HTTP protocol  
In addition to these default properties, you can specify new ones in the policy definition YAML file and reference them in the policy configuration XML file.
### Policy Tag Properties
The policy tag properties are important parts of a custom policy XML configuration:
  * `order` property in the `<policy>` tag
  * `order` property in the <before></before>and <after></after>


These properties determine the order of execution of policies.
The `requiresContracts` property is critical for client validation.
The Custom Policy Properties Reference contains more information about these properties.
In the configuration XML of a custom policy, you can access the default set of properties for a policy definition and properties defined in the Policy Template YAML file. To reference a property, type its name enclosed in two curly brackets as follows:
```
{{propertyName}}
```

This topic covers the `order` and `requiresContracts` properties.
## Order Property in Policy Tag
You can set the order of execution of a policy using the `order` property, however, setting the order of policy execution in a message processor takes precedence over setting the order of execution in the policy tag. Set the order to an integer greater than 2 because the order values 0 - 2 are reserved for CORS, Throttling, and Rate Limit policies, respectively. These policies must execute before others. The following example shows how to set the `order` property in the `<policy>` tag:
```
<?xml version="1.0" encoding="UTF-8"?>
<policy id="7777"
    policyName="A"
    order="3"
    xmlns="http://www.mulesoft.org/schema/mule/policy"
    xmlns:mule="http://www.mulesoft.org/schema/mule/core"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:api-platform-gw="http://www.mulesoft.org/schema/mule/api-platform-gw"
    xsi:schemaLocation="http://www.mulesoft.org/schema/mule/policy http://www.mulesoft.org/schema/mule/policy/current/mule-policy.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/api-platform-gw http://www.mulesoft.org/schema/mule/api-platform-gw/current/mule-api-platform-gw.xsd">
  <before>
     <mule:logger level="INFO" message="POLICY A" />
  </before>
  <pointcut>
    <api-platform-gw:api-pointcut apiName="Leagues API" apiVersion="1.0.0"/>
  </pointcut>
</policy>
```

## Order Property in Before or After Tags
Alternatively, you can set the order of execution of policies in the <before></before>and <after></after> tags. Setting the `order `property in the `before` and `after` tags takes precedence over any order setting in the policy tag. Set order to an integer greater than 2. For example:
```
<?xml version="1.0" encoding="UTF-8"?>
<policy id="2"
    ...
  <before order="4">
    <mule:set-payload value=" before cust2 "/>
    <mule:logger level="INFO" message="#[payload]" />
  </before>
  <before order="3">
    <mule:set-payload value=" before cust2.1 "/>
    <mule:logger level="INFO" message="#[payload]" />
  </before>
```

## requiresContracts in Policy Tag
The following versions support a `requiresContracts` property in the policy tag of the configuration XML:
  * The Mule Gateway Runtime 2.2.0 or later
  * Mule Runtime 3.8 or later


In earlier versions, you do not need this property because Mule Gateway Runtime caches client credentials by default.
**Important** : Enabling the `requiresContracts` property is vital for client validation. In the event Anypoint Platform goes down, a policy can continue to validate clients. Validation checks occur in-memory, which is naturally more performant than checks that involve an HTTP request over a network.
Custom policies that validate client IDs are often variations of MuleSoft-provided policies that authenticate clients, such as Client ID Enforcement or SLA-based policies.
In a custom policy that validates client IDs, include `requiresContracts` and set this boolean property to true as shown in the following example snippet.
```
<?xml version="1.0" encoding="UTF-8"?>
<policy id="{{policyId}}"
    policyName="Custom Client Id Enforcement"
    online="true"
    requiresContracts="true"
    xmlns="http://www.mulesoft.org/schema/mule/policy"/>
...
```

API client identity and authentication credentials are downloaded to Mule Gateway Runtime or Mule Runtime and stored. Validation occurs within the Runtime, eliminating the need for an outbound HTTP Request to do the validation.
Downloading and retrieving client information takes place in the background and occurs every 15 seconds by default. You can configure the polling frequency using the `anypoint.platform.poll_clients_freq` property. Configure this property on the CloubHub properties tab or the `wrapper.conf` file in your `<MULE_HOME>/conf` folder.
## Policy Definition YAML File
The policy definition file defines the high level properties of the policy, the configurable parameters, labels, and tips that are visible as a UI when implementing the policy.
The following example shows the IP Allowlist policy definition YAML file:
```
id: ip-whitelist
name: IP Allowlist
description: Limits all service calls to a defined set of IP addresses.
category: Security
standalone: true
requiresConnectivity: false
resourceLevelSupported: true
providedCharacteristics:
 - IP filtered
requiredCharacteristics: []
configuration:
 - propertyName: ipExpression
  name: IP expression
  description: |
   Mule Expression for extracting the IP address from this API request.
   for example, #[message.inboundProperties['http.headers']['X-Forwarded-For']]
  type: expression
  defaultValue:
  optional: true
  sensitive: false
  allowMultiple: false
 - propertyName: ips
  name: Allowlist
  description: Limited list of IP addresses allowed API access
  type: ipaddress
  optional: false
  sensitive: false
  allowMultiple: true
```
New properties you define have values based on what you want users to configure when they apply a policy. The IP Allowlist policy example requires values for the `ipExpression` and `ips` properties. The Policy Configuration XML file references these properties. Users are prompted to assign values to them.
The following policy definition values are related to the new policy:
Parameter | Description  
---|---  
string - Policy name  
description |  string - A description that displays in the policy details when applying it  
string - Category of the policy  
boolean - True if the policy can work on its own or false if the policy can be applied only as part of another policy.  
providedCharacteristics |  array - A list of optional characteristics that are fulfilled by applying this policy.  
requiresConnectivity |  boolean - A legacy internal parameter. The functionality is not implemented.  
resourceLevelSupported |  boolean - True means the user can apply the policy to specific API resources; False means the policy applies to all API resources. (Mule 3.8.1 and later)  
requiredCharacteristics |  array - A list of required characteristics that are fulfilled before this policy can be applied. Required characteristics can be fulfilled by applying other policies that provide these. This allows dependencies between policies. Any string input is valid as a characteristic name as long as at least one other policy provides this characteristic, these are case sensitive.  
configuration |  array - A set of configurable properties associated with your policy, details on the parameters for each property below.  
ramlSnippet |  string - A security scheme described in the RAML 0.08 specification.  
ramlV1Snippet |  string - A security scheme described in the RAML 1.0 specification.  
### providedCharacterics Parameter
Typically, you set `providedCharacteristics` to avoid clashes between policies that cannot be applied at the same time. For example, only one OAuth 2.0 policy can be applied at a time. Use the `OAuth 2.0 protected` to specify only one OAuth 2.0 policy.
The list of existing characteristics is:
  * `Client ID required`
  * `CORS enabled`
  * `Baseline Rate Limiting`
  * `SLA Rate Limiting`
  * `Requires authentication`
  * `IP filtered`
  * `JSON threat protected`
  * `Security manager`
  * `OAuth 2.0 protected`
  * `OAuth 2.0 provider`
  * `XML threat protected`


This list is unlimited: any string input is valid as a characteristic name. The list items are case sensitive.
### configuration Parameter
The `configuration` parameter lists a set of properties. Each can contain the following parameters:
Parameter | Description  
---|---  
`propertyName` |  string - Property name for internal reference.  
string - Property name to display in configuration window.  
string - Property description to display in configuration window.  
string - Data type: string, boolean, int, ipaddress, expression (in MEL), keyvalues, rateLimits. If type = int, define minimumValue and maximumValue.  
boolean - True if assigning a value for it is optional.  
boolean - True if the information contained by this field is sensitive (typically used for passwords and tokens). When policy information is requested from the server, these sensitive fields are filtered out.  
`allowMultiple` |  boolean - True if multiple values can be assigned.  
`minimumValue` |  int - Only for values of type int and required.  
`maximumValue` |  int - Only for values of type int and required.  
`defaultValue` |  Only for properties of type int, boolean, string and expression.  
#### propertyName Syntax
The following snippets show how to define propertyName parameters of the following types:
  * Integer
  * Boolean
  * String


#### Integer
If type = int, you must define minimumValue and maximumValue.
```
configuration:
 - propertyName: aint
  name: Test Int single between 5 and 10
  description: Some Description
  type: int
  minimumValue: 5
  maximumValue: 10
  optional: true
  sensitive: false
  allowMultiple: false
```

#### Boolean
```
configuration:
 - propertyName: aboolean
  name: Test Boolean single
  description: Some Description
  type: boolean
  optional: true
  sensitive: false
  allowMultiple: false
  defaultValue: false
```

#### String
```
configuration:
 - propertyName: astring
  name: Test String single
  description: Some Description
  type: string
  optional: true
  sensitive: false
  allowMultiple: false
```

```
configuration:
 - propertyName: amap
  name: Test Key/Value Map
  description: Some Description
  type: keyvalues
  optional: true
  sensitive: false
  allowMultiple: true
```

#### ramlSnippet and ramlV1Snippet Parameters
In the YAML of the custom policy, you can include the `ramlSnippet` and `ramlV1Snippet` parameters. When you add the custom policy to Anypoint Platform, links for the RAML .80 or RAML 1 snippets show up in the Applied Policies list.
The following snippet shows `ramlSnippet` and `ramlV1Snippet` parameters in a snippet of the YAML file of the MuleSoft-provided, Throttling-SLA based policy:
```
id: test
name: test
description: Rosario Central
...
configuration:
 - propertyName: omar
  name: arnaldo
...
 - propertyName: rosario
  name: central
...
ramlSnippet: |
 traits:
 - client-id-required:
   queryParameters:
    client_id:
     type: string
    client_secret:
     type: string
 ...
 /products:
 get:
  is: [client-id-required]
  description: Gets a list of all the inventory products.
ramlV1Snippet: |
 traits:
 client-id-required:
  queryParameters:
   client_id:
    type: string
   client_secret:
    type: string
 ...
 /products:
 get:
  is: [client-id-required]
  description: Gets a list of all the inventory products.
```

## See Also
  *   * Creating a Custom Policy