Describing your policy
Describe your user-defined policy by creating a definition file in YAML format to document metadata about the policy.
About this task
A policy YAML file contains the following sections:
- A specification version.
- An information section.
- An attach section.
- A properties section.
- A gateways section.
You can create a policy YAML file by using any editor of your choice. Both .yaml and .yml file extensions are supported, but the use of the .yaml file extension is recommended by yaml.org.
Note: All keys and enumeration values that are specified in this topic are case-sensitive.
The following steps describe how to construct a policy YAML file.
Set the specification version by adding the following line to the beginning of the file:
Complete the information section with details about the policy by using the following
info: title: Title of policy name: shortnameofpolicy version: 1.0.0 description: An example policy contact: name: name1 url: url1 email: email1
titleis the title of the policy. Any string can be used, but the title should be kept short so that it can be displayed in the API Manager user interface.
nameis the short name for the policy and must contain only alphanumeric characters, the - (dash) character, and the _ (underscore) character (blank spaces are not supported). The name is case-sensitive, and should be 20 characters or less so that it can be displayed in the API Manager user interface. In the example, the name is shown as
<policy-name>.Important: The policy short name must be different from the OpenAPI names of the built-in policies, otherwise it will cause a policy conflict in the API assembly definition. For a list of the OpenAPI built-in policy names, see execute. Also, consider including an appropriate unique prefix or suffix string in the short names of your user-defined policies to prevent possible name conflicts with future built-in policies.Note: The
name:property must be identical to the Node.js module name.
versionis the version number of the policy. This is a reserved property.Tip: The version.release.modification version numbering scheme is recommended, for example 1.0.0.Note: The
info.versionin policy.yaml must match the
versionindicated in package.json.
description(optional) is a short description of the policy.
contact(optional) is the contact information for the policy, where:
name(string) is the identifying name of the contact person or organization.
url(string) is the URL that points to the contact information.
Complete the attach section by specifying which type of API flow the policy can be attached
attach: - rest - soap
restindicates that this policy can be attached to a REST API flow.
soapindicates that this policy can be attached to a SOAP API flow.
The attach section must contain at least one API flow type. If a policy can be attached to both API flow types, they must both be indicated in the attach section.
Complete the properties section by defining a JSON schema (based on JSON Schema Specification
Draft 4, but rendered in YAML format) that contains the list of properties the policy will declare
as required input. These properties are presented to the API author at development time, when the
properties can be configured or mapped to values as required.
The JSON schema defines a root object that contains the following JSON properties:
The root type of the schema must be an
properties: $schema: "http://json-schema.org/draft-04/schema#" type: object properties: a_property: label: a label description: a description type: a type required: - a_property
object, as shown in the example schema. You can define zero or more properties in the schema. Required properties are declared by using the
requiredparameter, as shown in the example schema. The policy will not be accessible in the API Manager assembly editor, unless all the required properties have values. Each property is an object with the following items:
labelis a short name for the property and is displayed in the Name column of the API Manager assembly editor.
descriptionis a short description for the property and is displayed in the Description column of the API Manager assembly editor.
typemust be one of the following primitives that are supported:
- boolean (this primitive is shown as a check box in the assembly editor)
default(optional) specifies a default value for the property.
enum(for properties with a
typeof string) is an array of valid values.
In your gateways section, specify that the policy is for the DataPower® Gateway.
Enter the following code:
gateways: - datapower-gateway
- Save the new policy as a YAML file using the value of the
nameproperty (in the
infosection) as the file's name.Required: To ensure a successful import, the YAML file must use the name specified in the policy's
You have created a user-defined policy definition YAML file that documents metadata about your policy.
The following code block shows an example of a policy definition file that contains all the supported primitives. This policy must be saved as sampleimpl.yaml to ensure that it can be imported into API Connect.
policy: 1.0.0 info: title: Sample Policy name: sampleimpl version: 1.0.1 description: This is a sample policy. contact: name: Steve Product Manager url: http://developer.acme.com/contacturl email: email@example.com attach: - rest - soap properties: $schema: "http://json-schema.org/draft-04/schema#" type: object properties: samplestring: label: String Property description: Sample string property type: string sampleboolean: label: Boolean Property description: Sample boolean property type: boolean sampleinteger: label: Integer Property description: Sample integer property type: integer samplenumber: label: Number Property description: Sample number property type: number samplestringwithenum: label: Enum Property description: Sample string enum property enum: - one - two - three default: one type: string samplearray: label: Array of properties description: Sample array of properties type: array items: type: object properties: string: label: String Property description: Sample string property in array type: string boolean: label: Boolean Property description: Sample boolean property in array type: boolean required: - string required: - samplestring - sampleboolean - sampleinteger - samplenumber - samplearray gateways: - datapower-gateway
In the following code block, an example of a policy definition file for modifying message payload is shown.
policy: 1.0.0 info: title: Run GatewayScript name: gatewayscript-policy version: 1.0.0 description: Execute GatewayScript contact: name: IBM DataPower Samples url: https://github.com/ibm-datapower/ email: firstname.lastname@example.org attach: - rest - soap gateways: - datapower-gateway properties: $schema: "http://json-schema.org/draft-04/schema#" type: object properties: source: label: "GatewayScript Source" description: "The location of the GatewayScript file to execute" type: string default: store:///identity.js value: label: "New Value" description: "The value to be added to the payload" type: string default: "Hello Policy" required: - source - value
Create an implementation for your user-defined policy by using DataPower processing rules and actions. For more information, see Implementing your policy.