Working with global policies

Use global policies to configure policy assemblies that are called just before, or just after, each of your API assemblies is called, or when an error is thrown. You can upload global policies into each of the gateway services in your Catalogs, and then designate, for each gateway service, which global policy should be called before an API assembly is called, after an API assembly is called, or if an error occurs when an API assembly is called. The designated global policies are applied to all the APIs that are deployed to the associated gateway service.

Prerequisites

IBM® DataPower® Gateway version that is compatible with your deployed version of API Connect.

To complete the global policy management tasks described in this topic, you must be the owner of the provider organization, or be assigned a role that has the Settings:Manage permission. The pre-supplied Administrator role has this permission by default; if you are assigned a custom role it must have this permission. For more information, see Creating custom roles.

Overview

For each of the gateway services in a Catalog, a global policy that you want to be called before any API assembly is called is designated as a pre-request global policy, and a global policy that you want to be called after any API assembly is called is designated as a post-response global policy. A policy that you want to be called when an error is thrown is called an error global policy. You can upload as many global policies into a gateway service as you want, but you can designate at most one global policy to be pre-request, one to be post-response, and one to be an error, at any one time.

Note: In the The Help icon.

Help page of the API Manager, and API Designer user interfaces, there's a Product information tile that you can click to find out information about your product versions, as well as Git information about the package versions being used. Note that the API Designer product information is based on its associated management server, but the Git information is based on where it was downloaded from.

Note:

If you are using the DataPower Gateway (v5 compatible), there can be only one proxy policy across the combined pre-request, API, and post-response assembly flows.
Catalog properties, as described in Creating and configuring Catalogs, and API properties, as described in Setting API properties, are not supported with global policies. Therefore, if you use such properties in a global policy, they are not replaced with the values specified in the API or Catalog property definitions.

A global policy is defined in a .yaml file. The global policy file specifies the policy assembly that you want to call. A global policy file has the following structure:

global-policy: 1.0.0

info:
    name: global_policy_name
    title: global_policy_title
    version: global_policy_version

gateways:
    - gateway_type

assembly:
    - policy_assembly_to_be_called

where gateway_type has the value datapower-gateway if you want to use the global policy in a DataPower Gateway (v5 compatible), and datapower-api-gateway if you want to use the global policy in a DataPower API Gateway. For more information on the different types of gateway, see API Connect gateway types.

Note: Error global policies are supported only by the DataPower API Gateway, not by the DataPower Gateway (v5 compatible).

The assembly section for a pre-request or post-response global policy can contain any valid API assembly flow. For more information, see the execute section.

The assembly section for an error global policy can only contain a catch extension in the assembly, an execute section is not valid. For details of the catch extension, see catch.

Sample global policy .yaml file for pre-request or post-reponse

global-policy: 1.0.0

info:
  name: sample-policy
  title: Sample Policy
  version: 2.0.0

gateways:
  - datapower-api-gateway

assembly:
  execute:
    - invoke:
        target-url: http://myhost.com/mytarget
        version: 2.0.0

  catch:
    - errors:
        - ConnectionError
      execute:
        - activity-log:
            title: activity-log
            content: activity
            error-content: payload
            version: 2.0.0

Sample error global policy .yaml file

Note: An error global policy .yaml file can contain only a catch extension in the assembly.

global-policy: 1.0.0

info:
  name: sample-error-policy
  title: Sample Error Policy
  version: 2.0.0

gateways:
  - datapower-api-gateway

assembly:
  catch:
    - errors:
        - ConnectionError
      execute:
        - activity-log:
            title: activity-log
            content: activity
            error-content: payload
            version: 2.0.0
    - errors:
        - SOAPError
      execute:
        - xslt:
            version: 2.0.0
            title: xslt
            input: true
            source: |-
              <!-- Placeholder -->
              <xsl:stylesheet xmlns:xsl=''/>

Logging in to the Management server

You work with global policies by using developer toolkit CLI commands. Before you can run the commands, you must log in to your management server from the CLI. Use the following command:

apic login --server mgmt_endpoint_url --username user_id --password password --realm provider/identity_provider

You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):

apic identity-providers:list --scope provider --server mgmt_endpoint_url --fields title,realm

For example,

apic identity-providers:list --scope provider --server myserver.com --fields title,realm 
total_results: 2
results:
  - title: API Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap

The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default API Manager Local User Registry for login as a member of a provider organization is default-idp-2.

For full details of the apic login command, see Logging in to a management server.

Uploading a global policy to a gateway service

You upload a global policy to a gateway service by using the apic global-policies:create command. The command has the following format:

apic global-policies:create --catalog catalog_name --configured-gateway-service gateway_service_name --org organization_name --server mgmt_endpoint_url --scope scope [--space space] filename

where:

catalog_name is the value of the name property of the Catalog that contains the gateway service to which you want to upload the global policy.
gateway_service_name is the value of the name property of the gateway service.
organization_name is the value of the name property of the provider organization that contains the Catalog.
mgmt_endpoint_url is the platform API endpoint URL.
scope has one of the following values:
- catalog if the Catalog does not have Spaces enabled.
- space if the Catalog has Spaces enabled. If you specify space for the --scope parameter you must also supply the --space parameter to specify the Space that contains the gateway service.
(optional) space is the name of the Space that contains the gateway service. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
filename is the name of the global policy .yaml file that you want to upload.

Note: If Spaces are enabled in a Catalog, a global policy that you apply to one Space is applied to all Spaces; you cannot apply a global policy to an individual Space in the Catalog. Any subsequent updates are also applied to all Spaces.

You can confirm the global policies that have been uploaded by using the apic global-policies:list-all command, which has the following format:

apic global-policies:list-all --catalog catalog_name --configured-gateway-service gateway_service_name --org organization_name --server mgmt_endpoint_url --scope scope [--space space]

For reference details of the apic global-policies commands, see the toolkit CLI reference documentation.

Designating the pre-request global policy

To designate the pre-request policy for a gateway service, complete the following steps:

Write the URL of the required global policy to a .yaml file by using the following command:
```
apic global-policies:get --catalog catalog_name --configured-gateway-service gateway_service_name --org organization_name --server mgmt_endpoint_url --scope scope [--space space] policy_name:policy_version --fields url
```
where policy_name:policy_version specifies the name and version number of the required global policy, as defined in the global policy .yaml file that was originally uploaded to the gateway service.
The value of the URL is written to a file called GlobalPolicy.yaml.

Edit the GlobalPolicy.yaml file and replace the string url with global_policy_url. The resulting file has the following format:

global_policy_url: >-
  https://server_host_name/api/catalogs/catalog_id/configured-gateway-services/gateway_service_id/global-policies/policy_id

Designate the global policy to be the pre-request policy by using the following command:

apic global-policy-prehooks:create --catalog catalog_name --configured-gateway-service gateway_service_name --org organization_name --server mgmt_endpoint_url --scope scope [--space space] GlobalPolicy.yaml

To replace the designated pre-request global policy with another policy, repeat steps 1 and 2, then use the

apic
global-policy-prehooks:update

command. To remove the pre-request global policy designation, use the apic global-policy-prehooks:delete command.

For reference details of the apic global-policy-prehooks commands, see the toolkit CLI reference documentation.

By default, whenever an API is called, a series of policies, called the preflow policies, are invoked prior to the policy assembly configured in the API definition. However, by using a pre-request global policy you can, if required, fully customize the behavior of these policies, controlling if and when they are invoked, and with what customization. For more information, see Customizing the preflow policies.

Designating the post-response global policy

To designate the post-response policy for a gateway service, complete the following steps:

Write the URL of the required global policy to a .yaml file by using the following command:
```
apic global-policies:get --catalog catalog_name --configured-gateway-service gateway_service_name --org organization_name --server mgmt_endpoint_url --scope scope [--space space] policy_name:policy_version --fields url
```
where policy_name:policy_version specifies the name and version number of the required global policy, as defined in the global policy .yaml file that was originally uploaded to the gateway service.
The value of the URL is written to a file called GlobalPolicy.yaml.

Edit the GlobalPolicy.yaml file and replace the string url with global_policy_url. The resulting file has the following format:

global_policy_url: >-
  https://server_host_name/api/catalogs/catalog_id/configured-gateway-services/gateway_service_id/global-policies/policy_id

Designate the global policy to be the post-response policy by using the following command:

apic global-policy-posthooks:create --catalog catalog_name --configured-gateway-service gateway_service_name --org organization_name --server mgmt_endpoint_url --scope scope [--space space] GlobalPolicy.yaml

To replace the designated post-response global policy with another policy, repeat steps 1 and 2, then use the

apic
global-policy-posthooks:update

command. To remove the post-response global policy designation, use the apic global-policy-posthooks:delete command.

For reference details of the apic global-policy-posthooks commands, see the toolkit CLI reference documentation.

Designating the error global policy

The error global policy is applied to an error caught in the API pre-request, assembly, and post-response stages unless any of those stages has its own error rule defined for the same error, in which case that error rule takes priority.

To designate the error global policy for a gateway service, complete the following steps:

Write the URL of the required global policy to a .yaml file by using the following command:
```
apic global-policies:get --catalog catalog_name --configured-gateway-service gateway_service_name --org organization_name --server mgmt_endpoint_url --scope scope [--space space] policy_name:policy_version --fields url
```
where policy_name:policy_version specifies the name and version number of the required global policy, as defined in the global policy .yaml file that was originally uploaded to the gateway service.
The value of the URL is written to a file called GlobalPolicy.yaml.

Edit the GlobalPolicy.yaml file and replace the string url with global_policy_url. The resulting file has the following format:

global_policy_url: >-
  https://server_host_name/api/catalogs/catalog_id/configured-gateway-services/gateway_service_id/global-policies/policy_id

Designate the global policy to be the error policy by using the following command:

apic global-policy-errors:create --catalog catalog_name --configured-gateway-service gateway_service_name --org organization_name --server mgmt_endpoint_url --scope scope [--space space] GlobalPolicy.yaml

To replace the designated error global policy with another policy, repeat steps 1 and 2, then use the apic global-policy-errors:update command. To remove the error global policy designation, use the apic global-policy-errors:delete command.

For reference details of the apic global-policy-errors commands, see the toolkit CLI reference documentation.