Design/change-time polices provide governance controls that you can use to effectively administer and manage Web services and other assets within your SOA environment. Design-time policies enable you to control the acceptance of assets into the registry and manage their eventual deployment into the runtime environment. You can use design/change-time policies to ensure that assets entering the SOA environment conform to organizational standards and conventions, meet the architectural requirements of your enterprise and adhere to industry best practices. You can also use policies to execute standard procedures, such as initiating review processes, issuing notifications and granting instance-level permissions at key junctures in an asset's lifecycle.
The following sections generally describe design/change-time policies and explain how you might apply them at your site. For additional information about design/change-time policies, including specific steps for the procedures described in these sections, see the section Working with Design/Change-Time Policies.
A design/change-time policy defines a sequence of user-specified tasks that CentraSite is to execute when designated events occur in the registry. For example, a policy could instruct CentraSite to perform any of the following tasks:
Verify that a schema name conforms to specified conventions when a new schema is added to the catalog.
Submit a Web service to a review panel for approval before the service enters the Design state.
Send an email notification to the IT organization when a service is deployed.
Change the permission settings on an asset when the asset switches to the Available state.
Assign a user in a given role to a particular group when a new user is added to CentraSite.
Alter an asset's lifecycle path depending on the way in which the asset is classified.
A design/change-time policy has two major elements: it has an action list, which specifies the tasks (policy actions) that are to be executed, and it has a defined scope, which specifies when the action list is to be executed.
A policy action is a programmed task, written in Java or Groovy (a scripting language). A policy action can perform any type of work you require (e.g., sending an email, validating an attribute setting, submitting an approval request, updating a database). It can have one or more input parameters. An action that sends an email message, for example, will include input parameters that specify the text of the message and to whom it is to be sent. A policy action returns a completion code that indicates whether it completed its task successfully.
The action list in a policy can contain one or more actions. CentraSite executes the actions in the order that they appear in the list. If an action does not complete successfully, CentraSite immediately exits the policy and bypasses any remaining actions in the list. Policy failures are recorded in CentraSite's policy log.
CentraSite is installed with a library of "built-in" policy actions that you can use to construct policies. You can also develop your own custom actions using Java or Groovy.
The policy's scope specifies the conditions under which CentraSite is to execute the policy. It consists of two main parameters: Event Type and Object Type.
The Event Type parameter specifies the events to which the policy applies. An event represents a specific point during a registry operation when policies can be executed. Such points include the PreCreate event (the point in time just before CentraSite saves a new instance of an object to the registry), the PostCreate event (the point immediately after CentraSite saves a new instance of an object to the registry) and the PreDelete event (the point in time immediately before CentraSite deletes an object). Other events include the points in time before and after an update operation and before and after a state change. For a complete list of the supported event types, see the topic Events during Which Design/Change-Time Policies Can Be Enforced in the section Working with Design/Change-Time Policies > Functional Scope .
The Object Type parameter specifies the types of objects to which the policy applies. Policies can be applied to any type of asset and to several other types of registry objects. For a complete list of supported objects, see the topic Objects on Which Design/Change-Time Policies Can Operate in the section Working with Design/Change-Time Policies > Functional Scope .
Together, the event type and the object type determine when the policy will execute. You can make the scope as narrow or as broad as you need. That is, you can target the policy for one particular type of event and object (e.g., a PreDelete event on an XML Schema) or apply the policy to multiple events and objects (e.g., a PreCreate, PreUpdate or PreDelete event on an XML Schema, a Service or a BPEL Process).
You can optionally refine the scope of a policy to narrow the set of objects to which the policy applies. To do this, you include additional selection criteria based on an object's Name, Description or Classification properties. For example, you might create a policy that applies only to Application Servers whose name includes the string "myDomain.com:" or to Application Servers that are classified as Software AG Runtime.
The ability to execute policies based on object classification is an especially effective way to selectively apply policies to objects. As described in Creating a Different Lifecycle Path for a New Version of an Asset, you can use this technique to route assets between alternate paths in a lifecycle model. However, this technique can generally be used any time you want to apply a policy to a particular subset of objects within the specified object types.
A policy action also has a declared scope. The action's scope specifies the object and event types with which the action can be used. Some actions have very specific object-type and event-type requirements. For example, you can use the "Validate Policy Deactivation" action only during a PreStateChange on a Policy object. Other actions support a broad range of object and event types.
A policy can contain only actions that support the full set of object types and event types specified by the policy's scope. For example, if you create a policy that executes on the PreCreate and PreUpdate events for XML Schemas, it can only contain actions whose scope includes the PreCreate and PreUpdate event types and the XML Schema object type.
When you create a policy, CentraSite's user interface will only allow you to select actions that satisfy the specified scope of the policy. If you subsequently change the policy's scope, CentraSite will not allow you to save the updated policy unless all of its actions support the policy's new scope.
A design/change-time policy is either system-wide or organization-specific. System-wide policies apply to all organizations within an instance of CentraSite. Organization-specific models apply only to a specified organization.
Whether a policy is system-wide or organization-specific affects the policy's scope. When a policy is organization-specific, its scope is limited to the set of objects that belong to a specified organization. For example, if you create a policy that executes on a PreDelete event for XML Schemas, and you make that policy specific to organization ABC, that policy will execute only when XML Schemas in organization ABC are deleted. If you make it system-wide, it will execute when an XML Schema in any organization is deleted.
Note:
Once you create a policy, its organizational scope is fixed and
cannot be changed. That is, if you create a policy whose scope is specific to
organization ABC, you cannot change its scope to make it system-wide or switch
it to another organization. You must create a new policy and set its
organizational scope in the new policy as needed.
A policy has a priority value, which CentraSite uses when an event triggers multiple policies. You can give a policy a priority value between 11 and 9999 (inclusive). Priority 11 is the default. Values less than 11 and greater than 9999 are reserved for system use.
A policy's priority value is used only when an event triggers multiple policies. When this occurs, CentraSite examines the priorities of the selected policies and executes the policies serially, in priority order, from the lowest value to the highest value (that is, it executes the policy with the lowest value first). Each policy in the series is executed to completion before the next one begins.
For example, if an event were to trigger the following policies, CentraSite would execute the policies in the following order: B, A, C (as determined by the priority assignments 11, 25 and 100, respectively).
| Policy | Priority |
| A | 25 |
| B | 11 |
| C | 100 |
If multiple policies have the same priority, they will be executed serially, but their order is indeterminate. (That is, you cannot predict the order. CentraSite will choose the order at enforcement time.)
Many of the event types to which you can apply policies represent pre-operation events or post-operation events.
Pre-operation events occur immediately before a requested operation is performed on a registry object. They include the following event types: PreCreate, PreUpdate, PreStateChange and PreDelete. When you apply a policy to a pre-operation event, CentraSite executes the requested operation only if the pre-operation policy executes successfully. You generally apply policies at these points to prevent the requested operation from being executed unless an object satisfies the verification checks performed by the policy.
Post-operation events occur immediately after a requested operation is performed on a registry object. They include the following event types: PostCreate, PostUpdate, PostStateChange, PostDelete. When you apply a policy to a post-operation event, CentraSite executes the policy only if the requested operation is performed successfully. Post-operation polices are often used to notify users (via email) that certain changes have occurred in the registry, to update specified attribute values and to assign permission settings on an object.
When an event occurs in the registry, CentraSite determines which policies are "within scope" and executes those policies in priority order (from lowest assigned value to the highest assigned value). If an action within a policy fails, CentraSite immediately exits the policy. It does not execute any of the remaining actions in the policy, nor does it execute any remaining policies that are within scope of the event.
If the policy was triggered by a pre-operation event (e.g., a PreCreate event or a PreStateChange event) the requested operation is also not executed. For example, if a user attempts to add an XML Schema to the catalog, and the schema does not satisfy a validation policy that is triggered by the PreCreate event for XML Schemas, CentraSite will reject the user's request to add the new schema to the catalog.
Policy failures are written to CentraSite's policy log. From the Inbox page in CentraSite Control, users can view the failed policies that were logged during the events that they initiated. Administrators with "View Policy Log" permission can view and query the entire log using CentraSite Control's Logging feature.
CentraSite provides a special event type called an OnTrigger event. Policies that you create for this event type can be run "on demand" from the CentraSite Control user interface. Anyone who has View permission on an OnTrigger policy can execute the policy on demand.
When you run a policy on demand, CentraSite applies the policy directly to each object instance in the registry that:
Is of a type specified in the policy's object scope.
Satisfies all conditional criteria specified by the policy (i.e., Name, Description and/or Classification criteria that the policy specifies).
Is an object on which the user running the policy has View permission. If the policy is organization-specific, the policy is applied to only the objects that satisfy the preceding criteria and belong to the organization specified by the policy. If the policy is system-wide, the policy is applied to all objects in the registry that satisfy the preceding criteria.
Administrators often use OnTrigger policies to assign permissions to a specified set of objects instead of manually setting permissions on individual objects using the user interface.
The following sections describe typical uses for design/change-time polices.
Enforcing a review and approval process is a common use of a design/change-time policy. To create this type of policy, you include one of CentraSite's approval actions in the policy. An approval action identifies the group of users (the approver group) whose approval is required in order to complete the policy successfully. When you configure an approval policy, you can specify whether approval is required from just one approver in the group or from all approvers in the group.
You apply approval polices to PreStateChange events. Thus, to use approval policies on assets, those assets must be under lifecycle management.
Note:
Approval policies can also be used with an OnConsumerRegistration
event. This use case is described later in this section.
When CentraSite executes an approval policy, it initiates an approval workflow. Users who are designated approvers review the request on the Pending Approvals tab of their Inbox page in CentraSite Control user interface. If the approvers approve the request, CentraSite executes the requested state change. If an approver rejects the request, the policy fails and the requested state change is not executed.
Pending approvals appear in the approvers inbox in CentraSite Control
Users who submit requests that require approval can view the status of their requests on the Approval Requests tab of their Inbox page in the CentraSite Control user interface.
Validation is another common task that you can perform using design/change-time policies. You use validation policies to ensure that assets conform to organizational norms and standards before they are accepted into the catalog or enter a critical lifecycle state. For example, you might create validation policies to perform the following types of tasks:
Ensure that a service satisfies certain naming conventions, that it exists within a specified namespace and/or supports specified protocols.
Ensure that an asset has been classified by a specified taxonomy and/or includes required attribute settings.
Ensure that a service complies with Web Service Interoperability (WS-I) standards (Basic Profile 1).
Prevent an asset from being deleted unless it is has reached a specified state within its lifecycle.
CentraSite provides built-in actions that you can use to perform many validation tasks. You can also create custom actions to perform validation tasks that are specific to your environment.
You can use design/change-time policies to make changes to assets when certain events occur. Setting instance-level permissions on an asset is an example of an update you might make using a policy. Other kinds of changes you might make include classifying an asset, setting a specified attribute when an asset completes a series of tests and changing an asset's lifecycle state.
CentraSite provides built-in actions that you can use to perform many kinds of updates to assets. You can also create custom actions to modify assets.
Notifying individuals when certain events occur in the registry is another common use case for design/change time policies. CentraSite includes a built-in email action that you can use for this purpose.
You might, for example, use this action to send an email to key users in your IT organization when a service switches to the Production state of its lifecycle. You might also create custom actions that would send messages to and/or trigger processes on external systems when certain events occur in the CentraSite registry.
If you want to use CentraSite's consumer-registration feature, you must first create a consumer-registration policy. CentraSite will not enable the consumer-registration feature until you create this policy.
The consumer-registration feature in CentraSite enables users to register users and/or applications as consumers of an asset. To complete the registration process, the owner of the asset must first review and accept the user's request. If the owner accepts the request, the consumer-registration policy, which you create, is executed. This policy includes the "Register Consumer" action, which performs the actual registration process. It can optionally include other actions, such as an approval action, as needed. For additional information about creating a policy that registers consumers, see The Consumer Registration Policy.
If you use virtual services, you must create policies that enable an administrator to deploy a virtual service to webMethods Mediator and to make a virtual service undeployable while it is being revised. For additional information about creating these kinds of policies, see Defining a Lifecycle Path that Enables Deployment of a Virtual Service.
The following are issues to keep in mind when creating design/change-time policies for your CentraSite registry.
When an event occurs in the registry, CentraSite executes all policies whose scope encompasses the event. Use priorities to control the order in which CentraSite executes the policies. Consider assigning something other than the default priority of 11 to routine policies. Doing this will enable you to more easily interject higher priority policies for the events associated with those policies, should you ever need to do so.
Many of the built-in actions provided with CentraSite (including the approval actions) are scoped for state-change events and can only be used with objects that are under lifecycle management. Before you create a policy, determine which policy actions you want to use and check the event types that they support. To create certain types of policies, you might need to first apply a lifecycle model to the objects that you intend to govern with those policies.
Exercise caution when using OnTrigger policies! If the policy updates objects, be certain that the scope of the policy is set precisely and targets only the set of objects that you intend to change. Used inappropriately, this type of policy can change objects in ways that cannot easily be undone.
By default, CentraSite is configured to record only policy failures in the policy log. You can optionally configure CentraSite to log both successful and failed policies in its log. However, if you do this, the log can grow quite rapidly. Consider logging successful policy executions only when it is necessary for tracing or troubleshooting purposes. Or, if you choose to enable this option as part of your normal operations, consider purging the log on a regular basis.
When CentraSite executes a policy, the policy's actions are executed on behalf of the user who triggered the policy (in other words, the actions are executed under that user's account). If the user does not have the permissions necessary to complete an operation initiated by a policy action, the action (and thus, the policy) will fail. For example, if a user triggers a policy that sets permissions on an object, the policy will fail unless the user has Full permission on the object. (Only users with Full permission on an object are allowed to change the object's permission settings.)
The following sections describe issues relating to the creation and maintenance of design/change-time policies.
Policies are managed by a predefined lifecycle installed with CentraSite. This lifecycle, called the "Policy Lifecycle", defines the following lifecycle states: New, Productive, Suspended and Retired.
To activate a policy, you must place the policy in the Productive state. When you switch the policy to this state, CentraSite begins enforcing it.
You cannot modify a policy while it is in the Productive state. To make changes to a policy, you can do any of the following:
Create a new version of the policy, make the necessary changes to the new version and switch the new version to the Productive state when you are ready to put it into effect. Switching the new version to the Productive state will immediately put the previous version in the Retired state. (The Retired state is an end state. After you place a policy in this state, you can no longer reactivate it.)
Create a completely new policy that includes the required changes. When you are ready to put the new policy into effect, switch the old policy to the Suspended state and switch the new policy to the Productive state. When you are certain that you will no longer need to revert to the original policy, switch it to the Retired state.
Switch the existing policy to the Suspended state, make the necessary changes to the policy and then switch it back to the Productive state. While the policy is in the Suspended state, it will not be enforced. (Because suspending the policy results in an enforcement gap, one usually does not use this approach in a production environment.)
A design/change-time policy can become quite complex, especially if it contains several policy actions. Instead of creating a new policy "from scratch", it is sometimes easier to copy an existing policy that is similar to the one you need and edit the copy.
CentraSite includes a copy feature that lets you do this. It produces a copy that is identical to the original policy. Unlike a new version of a policy, a copy of a policy is not associated with the original policy in any way. CentraSite treats the copy just as if it were a new policy that you created from scratch.
The predefined lifecycle model that CentraSite uses for policies is made up of four states: New, Productive, Suspended and Retired. This lifecycle is generally adequate for most environments. However, you can make certain minor types of customizations to it if necessary.
For information about the ways in which you can customize this lifecycle model, see the topic Customizing the Predefined Lifecycle Model for Policies in the section Working with Design/Change-Time Policies > Functional Scope .
