Creating and deploying a policy in a CICS bundle project

A policy is an XML definition that contains one or more policy rules. A policy rule describes the action to be applied to a CICS system or an individual user task when the specified condition is met. A policy is created in a CICS® Bundle project and you can define one or more policies in a CICS Bundle project. By packaging your policies in this way, you can deploy your policies as a single entity to CICS, making it easier to update and manage the policies in CICS.

Before you begin

To create and deploy a policy, you must have an existing CICS bundle project. For more information, see Creating a CICS bundle project.

About this task

CICS supports system and task rules. A system rule monitors and controls the overall health of a CICS system, and a task rule monitors and controls an individual user task. Each policy rule defines the conditions that must be met before an automated action is performed. Each policy can define one or more rules, and one or more policies can apply to a CICS system or an individual user task.
Note: Although system and task rules can be defined in the same policy, you must define the two types of rule in separate policies if you want to deploy any policy that defines task rules with a CICS application.
Levels of scope for task rules
Policies that define task rules can be deployed at the following levels of scope:
Region level
Rules apply to all user tasks running in the specified region.
Platform level
Rules apply to all user tasks for any CICS application that is deployed on the specified platform.
Application level
Rules apply only to the users tasks for the specified application and not to other user tasks that might run on the same platform.

For policies that define task rules that are deployed at the region or application level, you can further restrict their scope to specific user tasks, by defining policy scopes. For more information, see Defining policy scopes.

Levels of scope for system rules
Policies that define system rules can be deployed to the following levels of scope:
Region level
Rules apply to all tasks (system or user) in the specified region that make changes to system or resource state.
Platform level
Rules apply to all tasks (system or user) in all regions of the specified platform that make changes to system or resource state.

Policies that define system rules cannot be deployed at the application level.

Procedure

To create a policy in a CICS bundle project:

  1. Select the parent folder of a CICS bundle project from the Project Explorer view.
  2. Open the New Project wizard in either of the following ways:
    • On the main menu for the workbench, click File > New > Other. Then expand the CICS Resources folder, select Policy Definition, and click Next.
    • Right-click the CICS bundle project, and then click New > Policy Definition.
  3. Create a policy that contains the policy rule:
    Tip: To quickly create a policy rule from a CICS local file or transaction class resource, navigate to the corresponding resource view and right-click the resource for which you want to create a policy. Select Create Policy and then the rule type you want to create.
    1. In the File Name field, enter the policy file name, for example policy_rules.
    2. Click Finish. This opens the policy definition editor. For more information, see The policy definition editor.
  4. Optional: In the General Information section on the Overview tab, you can enter a description in the Description field, a user tag in the User Tag field, or both. A user tag is a user defined 1-8 character identifier that is included in any event emitted for rules defined in a policy. It can be a version number, a department code, or initials of policy author, that is, anything that helps associate an event with the policy that requests the event.
  5. Create a rule in the policy definition editor:
    1. On the Overview tab, click New.
    2. In the New Rule dialog, enter a rule name, select a rule type from the list, and optionally enter a description for the rule.
    3. Click OK. This opens the Rules tab.
  6. In the Conditions section on the Rules tab, define the conditions that trigger the automated action when they are met. System and task rules support different types of condition; for more information, see Policy conditions.
    Note: The earliest CICS release that supports a specific rule is displayed in the lower-right corner of the Conditions section. Ensure that this is equal to or less than the CICS release to which this policy will be deployed. For more information, see Policy schema versioning.
  7. Select one action to take when the defined conditions are met:
    • Issue a message. CICS issues a message to the CICS log when the specified condition is met. For task rules, either DFHMP3001 or DFHMP3007 is issued. For system rules, either DFHMP3009 or DFHMP3010 is issued.
    • Emit an event. Specify an event processing (EP) adapter or an EP adapter set for CICS to emit an event either to a single EP adapter or to all adapters in an EP adapter set. EP adapters format the event data into a suitable output format, and route the event to the defined event consumers. For more instructions, see Choosing an EP adapter resource and Choosing an EP adapter set resource.
      Action tab on the Rules tab of the policy definition editor
      Optionally, to distinguish events emitted by policy rules of the same type, specify the event name as follows. If no event name is specified, a default one will be used.
      • 1 - 32 characters in length.
      • Acceptable characters are: 0-9 A-Z a-z _
      • Must start with an alphabetic character and cannot start with characters XML in any case.
      Optionally, to pass unchangeable data to the event consumer, associate static data items with the event by clicking Add. Any rule can contain a maximum of 479 static data items. Define each static data item as a name-value pair as follows:
      For static data names:
      • 1 - 32 characters in length.
      • Acceptable characters are: 0-9 A-Z a-z _
      • Must start with an alphabetic character and cannot start with characters EPFE, MPFE, or XML in any case.
      • Must be unique within a rule.
      For static data values:
      • 1 - 255 characters in length.
      • Acceptable characters are as follows, including embedded spaces:

        0-9 A-Z a-z `¬¦!"£$%^&*()_+-={}:@~;'#<>?,./|

      Note: If you specify the event action for a policy rule, you can export the event specifications as a schema or copybook for use elsewhere. Definitions of static data capture items are included in the exported file; and if an event name is specified, it is used as the prefix of the exported file name. For instructions, see Exporting event specifications from a policy.
    • For task rules only: Abend task. If you want CICS to terminate a running task when the specified threshold is crossed, select the Abend task with abend code option. CICS also issues a message (DFHMP3002 or DFHMP3008) to the CICS log when a task is terminated. The default abend code is AMPB but you can overtype this to specify another code for the task abend.
  8. Optional: Add more rules by following Steps 5 through 7.
  9. To save the policy, click File > Save.

To deploy a policy in the CICS bundle project:

Policies that define system rules can be deployed either to a stand-alone CICS region or with a CICS platform, but they cannot be deployed with a CICS application. Policies that define task rules can be deployed to a stand-alone CICS region, with a CICS platform, or with a CICS application.

  1. Deploy the policy by using one of the following methods:
    • To deploy the policy to a stand-alone CICS region:
      1. Export the CICS bundle project that defines the policy to zFS. For more information about deploying CICS bundles to zFS, see Deploying a CICS bundle.
      2. Define, install, and enable a CICS BUNDLE resource for the CICS bundle. You can create and install a BUNDLE definition by opening the Bundle Definitions view. For more information about bundle resources, see BUNDLE resources in the CICS TS V5.4.0 product documentation.
    • To deploy the policy to a platform, add the CICS bundle that contains the policy to a platform:
      • If the platform is not yet deployed, add the CICS bundle that defines the policy to the platform definition as follows, so that it is deployed during the platform deployment:
        1. Locate the platform bundle project in your workspace, expand the META-INF folder for the bundle project, and double-click the bundles.xml file or the platform.xml file. The platform descriptor editor opens. For more instructions on using the platform descriptor editor, see The platform descriptor editor.
        2. Click Add in the CICS Bundles section on the Overview tab.
        3. From the list of CICS bundles that are available in your workspace, select the CICS bundle that defines the policy.
      • If the platform is active, follow these steps:
        1. Export the CICS bundle project to the platform home directory on zFS. For more information, see Deploying a CICS bundle.
        2. Add the CICS bundle that defines the policy to the active platform, by using the ADDBUNDLE operation dialog of the Cloud Explorer view. For more information, see Adding a CICS bundle to a platform.
    • To deploy the policy with a CICS application, add the CICS bundle that defines the policy to the application, as follows:
      1. Locate the application bundle project in your workspace, expand the META-INF folder for the bundle project, and double-click the application.xml file or the bundles.xml file. The application descriptor editor opens. For more instructions on using the application descriptor editor, see The application descriptor editor.
      2. Click Add in the CICS Bundles section on the Overview tab.
      3. From the list of CICS bundles that are available in your workspace, select the CICS bundle that defines the policy.

Results

A policy is created in the CICS bundle project and deployed.