Packaging and importing your policies into IBM API Connect

Make your user-defined policy available to API developers by packaging it and importing it into an IBM® API Connect Catalog.

To package and import your user-defined policy, complete the following steps:

1. Create a .zip file that contains the following folder structure:

   <policy-name>.yaml
   implementation/
                 policy-name.zip
                 mypolicy_mgw.mgw

   where

   • <policy-name>.yaml is your policy definition file. The YAML file must use the name that is specified in its name property.
   • implementation/policy-name.zip is your policy implementation for a policy that is deployed to the DataPower Gateway. The policy implementation file contains the DataPower processing rules and actions that were exported from DataPower in step 2.
   • implementation/mypolicy_mgw.mgw is your policy implementation for a policy that is deployed to the Micro Gateway. The policy implementation file contains all of the source files (package.json, .js files, README.md, and so on). The package.json file and its peer files and folders are at the root path of the compressed file.

   The name of the .zip file or .mgw file must start with the name of the user-defined policy (as defined in the policy YAML file). If the implementation requires certificate and key files, these files must be added to the implementation directory.

   Note: Your package .zip file must contain a .zip or a .mgw policy implementation file, but can contain both.
2. Use the API Manager user interface to import your policy into a Catalog. When successfully imported, the policy appears on the policy palette of the API Designer assembly editor. For more information, see Importing a user-defined policy into a Catalog.
   Note: You must import your user-defined policy into every Catalog in API Manager that you require your policy to run in.
3. Deploy the imported policies to the Micro Gateway collective members.
   1. Create a directory on the Micro Gateway named package/userPolicies.
   2. Under package/userPolicies, create a directory for each policy to be deployed, such as package/userPolicies/micro-gw-policy-sample.
   3. Expand the contents of the compressed policy file into the policy directory. For example, the compressed file micro-gw-policy-sample.mgw is expanded into the package/userPolicies/micro-gw-policy-sample directory.
   4. Under the package/ directory, edit or create a file named .apiconnect.
   5. Edit or add the { userPolicies: [<userPolicies>] } array object, and enter the absolute path to the policy directory.

What to do next

Make your user-defined policy package accessible to the API Designer UI. To display user-defined policies in the API Designer UI, edit the .apiconnect/config file to point to the directory containing the policy.yaml file. You can edit the global config file (~/.apiconnect/config) or a project-specific config file (~/ProjectA/.apiconnect/config). Follow these steps:

1. Create one or more directories to hold your policy.yaml files that are accessible to Node.js, and copy the user-defined policy package into this directory. For example, create directories named /ProjectA/Policies and /ProjectB/Policies.
2. Extract the policy package so that the folder structure is visible, for example policy.yaml and implementation/policy-name.zip. The file containing the custom policies must be named policy.yaml.
3. Add the userPolicies: [ ] array object to the config file in ~/ProjectA/.apiconnect/ or ~/.apiconnect/, and edit the array object so it contains the absolute path to the director(ies) containing the policy.yaml file.

   Following is an example of an ~/.apiconnect/config file showing the userPolicies entry pointing to the directory containing the policy.yaml file:

   apim_server: us.apiconnect.ibmcloud.com
   us.apiconnect.ibmcloud.com.meta:
    formFactor: BLUEMIX_PUBLIC 
    serverCapabilities:
       authTypes:
         - basic   
         - token
    toolkit:
       version_recommended: 2.1.30
       version_minimum: 2.1.30
   catalog: >-
     apic-catalog://us.apiconnect.ibmcloud.com/orgs/sampleorg-myspace2/catalogs/sb
   app: >-
     apic-app://us.apiconnect.ibmcloud.com/orgs/sampleorg-myspace2/apps/acme-bank
   userPolicies:
     - /ProjectA/Policies

   Note:

   • The userPolicies: [] array object contains a list of absolute paths to the policy director(ies). The values can point to a parent location, for example userPolicies: ["~/mypolicies"]. Alternatively, each policy location can be specified in the array, for example userPolicies: ["~/mypolicies/policya", ~/mypolicies/policyb"]. However, do not use both of these approaches in the same directory. For example, do not create policies in a directory structure like this ~/foo, ~/foo/policya, and ~/foo/policyb.
4. Open the API Designer UI. The user-defined policy is available on the policy assembly palette, and you can add the policy to your API definition.