<<TableOfContents>>

What is Policy Xpress?

Policy Xpress allows the product to move from a pure role engine to a rule engine.

Policy Xpress allows you to create complex business logic (policies) without the need to develop custom code. However, the concepts involved in creating Policy Xpress policies are complex and require careful thought and planning. An administrator using the product UI screens can configure a policy within Policy Xpress to implement even the most sophisticated business logic required. As business policies change, an administrator can modify the policies using configuration screens within the product without requiring a developer to make underlying code changes, or more importantly—with proper change management procedures—without restarting the services.

IMPORTANT! Although Policy Xpress does not require direct coding, it should still be used with software development best practices.

The following types of data can be accessed in a policy:

• Accounts
• Groups
• Attributes
• System roles
• Data sources
• System info
• System events
• Defined variables

All actions done by Policy Xpress are run as events, when possible. For example, a policy that changes a user's attribute, generates a ModifyUserEvent. This allows for auditing in the system, and for viewing detailed information about tasks generated by Policy Xpress. As with all system events, events generated by Policy Xpress can be viewed in the View Submitted Tasks tab. If your Policy Xpress policies are not running as expected, you can use the information available in View Submitted Tasks to help with troubleshooting.

Note the following:

• Not all Policy Xpress actions generate events, for example, writing to a log file does not generate an event in the system.
• When viewing events in the View Submitted Tasks tab, an event can show as failed because of a Policy Xpress policy, and not because of the event itself.
• Policy Xpress gives you the ability to execute a policy at the following times relative to events within the system:
  • Before
  • After
  • Approved
  • Failed
  • Rejected

Policy Xpress Flow

When a trigger (tasks, events, business logic task handlers, and workflow) happens, Policy Xpress is activated and the following steps occur:

1. Policy Xpress checks activation times (events) to see if there is a policy that should run at that particular time.
2. A list of policies is generated. 　
3. Policies are ordered based on priority, and Policy Xpress evaluates policies as follows:
   1. All required values (data) are calculated.
   2. Entry rules are checked to see whether the policy should run.
   3. If the entry rules allow the policy to run, all action rules are checked for matches.
   4. For the matching action rule with the highest priority, the add actions for that rule are executed.
   5. For any action rule that previously matched but no longer matches, remove actions are executed.
4. Once the policy completes, information about the policy that ran is saved on the user object (even if the policy made no changes).
5. Appropriate events related to the action rules are generated. For example, if the policy modifies a user, the ModifyUserEvent is generated.
6. The next policy is loaded. Note: The previous flow can be changed using action rules. For more information about changing the flow of Policy Xpress, see Flow Control.

How to Create a Policy

To create a policy with Policy Xpress, define the following basic elements of a policy.

Profile defines the policy type and priority, and allows for grouping similar policies for easy management.

Events define when a policy runs.
Note: Be sure to set the Events parameter carefully. Business logic must run at specific times to prevent data corruption and to increase performance. For example, setting a user as enabled should occur when the user is created. Running this logic at all times may cause user accounts that should be disabled to become enabled again. Another example is giving the user a provisioning role that grants access to a certain system. This role should only be assigned to the user after a different role has been assigned and approved. Policy Xpress allows for the activation of its business logic during event and Business Logic Task Handler processing, much like custom adapters. Therefore, unlike identity policies, the logic can be triggered at any time, and not only at the beginning of a task.　

Data (Data Elements) specify the data used by the policy. Every type of business logic requires some data to work with. That data can be used to make decisions or it can be used to construct more complex data. Policy Xpress provides many individual components to gather data. These components are referred to as Data Elements. An example of a data element is a user's attribute value. For example, Policy Xpress can gather the user's first name and store it as a data element for later use. 　

Entry Rules define the requirements that must be met before execution. Defining entry rules allows you to specify when Policy Xpress evaluates policies, which can simplify policies and improve performance. An example of an entry rule is to run a 'Set Full Name' policy only if the first name or the last name has changed.

Action Rules define the action taken based on the information gathered. For example, based on a user's department name, Policy Xpress can assign a user to different roles or specify different account values.
Actions specify the action to perform. At the end of the process, Policy Xpress performs the actions needed by the business logic. Policy Xpress works by having an action rule attached to multiple actions, so          ----when the rule is met, the actions are performed. Actions can include assigning attribute values to a user or an account, executing a command line, running a SQL command, or generating a new event.

Basic Use Cases

Set a user's full name
Run At Events—when the user is created or modified Data Elements—get the values of the first name and last name Entry Rules—if the first name or last name has changed based on the data gathered. It prevents the policy from running otherwise. Action Rules—set the full name to be the value of the first name, space, and the value of the last name.

Assign different provisioning roles for employees versus contractors
Run At Events—at create user and modify user Data Elements—get the value of the user's type Entry Rules—none (action rules are always evaluated) Action Rules—1) checks if the user type is an employee 2) checks if the user type is not an employee. Only one of the action rules can be met, and assigns the appropriate provisioning role.

Set the user's groups and OU in Active Directory, based on department
Run At Events— at the end of the assign provisioning role event. This ensures that an account is already created when setting the values. Data Elements—get the user's department, and also the endpoint type and Active Directory domain to make things easier to manage later on　 Entry Rules—if the department is not empty Action Rules—multiple rules for each possible department. Each rule checks if department equals Sales or any other value. There is a default rule in case the department does not meet any requirements. Different actions are configured for each rule, assigning different values. This ensures that a user in a specific department gets the Active Directory groups and OU they need, while a user in a different department gets others, as appropriate.

Write all new users to a table. The table contains some of the user's HR data.
Run At Events—on create user, but only after the user has been created (after the create user event has completed) Data Elements—gets the required HR information, such as user name, country, department, and any other values Entry Rules—none (action rules are always evaluated) Action Rules—execute an SQL query which accepts the values gathered as parameters. The result of activating the query is having a new record in the database for the new user.

Samples

Samples Directory

Policy Xpress policy samples for common use cases are available at the following location:
admin_tools\samples\PolicyXpress

Checking Offensive Names (On-screen Attribute Validation)

When a new user is created, you may want to check if the username is offensive. The following process outlines how to check for offensive names using a Policy Xpress policy.

1. Be sure that the appropriate fields in the Create User task's profile screen are set to Validate on Change = Yes.
2. In Policy Xpress, create a policy of type 'UI' .
3. Under the Run at Events tab, select the State 'Validate on Change' and the Create User task.
4. Create the following data elements to check the first name:
   • Get the first name attribute (Attributes, User attribute, Get)
   • Parse the first name to all lower case letters (General, String parser, To lower)
   • Check the first name against offensive words in a database table (Data sources, SQL query data).
5. Create similar data elements as in Step 4 to check the last name.
6. Create an action rule as follows. This rule will force the user to change the name before submitting the Create User task again:
   1. Condition—first name is not equal to "" (this occurs if the query returns a message that the name is offensive)
   2. Action—message that displays (Messages, On screen message) indicating the offensive name.
7. Create a similar action rule as in Step 6 for the last name.

Set Objects Associated with Accounts

When creating an Add Action to set an object that is associated with an account, such as Member Of, a specific relationship format is used to represent the object. The following two types of formats can represent the object in <idmgr>:

• To represent simple relationships between the object and the account, for example, Active Directory Groups: ADSGroup=Administrators,ADSContainer=Builtin,EndPoint=LocalAD,Namespace=ActiveDirectory,Domain=im,Server=Server
• To represent binding relationships between the object and the account, for example, SAP Roles: {"validFromDate":"2009\/12\/01","roleName":"SAPRole=SAP_AUDITOR_ADMIN,EndPoint=sap endpoint,Namespace=SAP R3,Domain=im,Server=Server","validToDate":"2009\/12\/31"} A binding relationship differs from a simple relationship in that the association between the object and the account has additional data on it.  In the previous example, the parameters validFromDate and validToDate only contain data related to the association between the account and the SAP role.  The validFromDate and validToDate data does not exist on the account, or the role object.

To discern the format for the relationship, create a data element that Gets the value of the object. The value returned is the format you use in the Add Action to set that object.

Example: Active Directory Groups
1.  Create a Policy Xpress policy with the following settings:

• Policy Type: Event
• Events: After – Modify User 2.  In the Action Rule, configure the following Add Action:
• Category: Attributes
• Type: Set Account Data
• Function: Set
• Endpoint Type: Active Directory
• Endpoint: endpoint_name
• Account Name: account
• Attribute: Member Of (groupMembership)
• Value: ADSGroup=Administrators,ADSContainer=Builtin,Endpoint=endpoint_name,Namespace=ActiveDirectory,Domain=im,Server=Server Note: Depending on the type of ADS container, the container naming part could be "ADSContainer" or "ADSOrgUnit". E.g. the following value is using the "ADSOrgUnit": ADSGroup=IT,ADSOrgUnit=Groups,ADSOrgUnit=NorthAmerica,EndPoint=ForwardincAD,Namespace=ActiveDirectory,Domain=im,Server=Server

How to Invoke Web Services Actions

This scenario answers the following question:

As a system administrator, I want Policy XPress to support Web Services (SOAP and REST) so that I can integrate with external applications that provide a web service interface.

The process is very similar to how you would define the basic elements of a policy. New functions on the Data tab let you invoke Web Services.

The following steps show you how to:

1. Create a Policy XPress policy to capture the ModifyUserEvent.

2. Call a Web Services operation that retrieves the country name based on the user’s IP address. The IP address is taken from the user’s mobile attribute name.

3. Store the output of the Web Services operation in the user’s Country attribute.

This section also explains the necessary data functions, as well how to test your functions before submitting them.

To invoke Web Services with Policy Xpress, complete the following steps:

1. Under Policies, Policy Xpress, select Create Policy Xpress Policy, Create a new object of type Policy Xpress, and then OK.

2. In the Profile tab, specify the required attributes.
   NOTE: In the Policy Type drop down, select Event.
3. In the Profile tab, Click Add Event.

4. For the Event State, select Before.

5. For the Event Name, select ModifyUserEvent.

How to Create the Data Elements for a SOAP-Based Query

Use the Data tab to determine the information that you want to retrieve. In this example, you create two data elements to retrieve the country name based on the user’s IP address using the SOAP-based Web Service plugin. 

Create the first data element retrieving the user’s mobile:

1. In the Data tab, click Add Data Element.

2. Complete the fields:

• Name: GetMobile
• Category: Attributes
• Type: User Attribute
• Function: Get
• Attribute Name: Cell Phone (mobile)

3.  Click OK to create the element and return to the Data tab.

Create a data element to retrieve the country name based on the IP address, using the SOAP base Web Service plugin.

1. In the Data tab, click Add Data Element.
2. Complete the fields:
   • Name: wsResponse
   • Category: Data Sources
   • Type: SOAP Base Query
   • Function: Anonymous Auth Get
   NOTE: If you select Basic Auth Get for the Function, then the parameter fields will include a user name and password.
3. Specify the following in the SOAP Base Query plugin:
   • WSDL URL: http://www.webservicex.net/geoipservice.asmx?WSDL
   • SOAP Action: http://www.webservicex.net/GetGeoIP• SOAP Version: 1.1
   NOTE: If you select Basic Auth Get for the Function, then the parameter fields will include a user name and password.
   • SOAP Request Message: Manually entering the SOAP Request Message is error prone; CA technologies recommends using the soap UI http://www.soapui.org/ as a tool to help create the SOAP request.
   Note: In the SOAP message, the input for the IP address is the ‘GetMobile’ data element.
   • Returned Attribute: Because you want to return the name of the country, enter CountryName.
   Note: You can click the “Test” button to verify the provided parameters. But make sure substitute any data element with the real data as the data elements won’t be evaluated during testing.
4. Create the Action Rule ‘setCountry’ to store the Web Service response into the user’s City attribute.
5. In the Action Rules tab, click Add Action Rule.
6. Complete the Name & Priority fields.
7. Click Add Condition When Matched, and then complete the following fields:
   a. Name: SetCountry
   b. Category; Attributes
   c. Type: Set User Values
   d. Function: Set
   e. Attribute Name: Country (physicalDeliveryofficeName)
   f. Value: {'wsResponse'}
   This is the  Data Element used to invoke the SOAP request.
8. Click OK.

Use the following procedure to test this procedure:
Follow these steps:
1. Modify a user and specify a IP address in the ‘Cell Phone’ attribute. In this test case, the IP address is the ‘bbc.co.uk’ (212.58.253.67).
2. View the VST and see the PX policy has been invoked correctly.
3. Verify the Country attribute of the user has been set correctly.

Using the JSON Plug in to Filter Results

The response to the web service operation contains more than one result, and each result has the same set of attributes.

You can specify which particular result you want to retrieve for that attribute using the JSON Path Plugin.

Complete the following steps to test the JSON Path plugin.

1. Using the previous Web Service example, we need to clear the ‘Returned Attribute’ field so that the whole web service response with JSON format will be returned:
   {"GetGeoIPResponse":{"GetGeoIPResult":{"CountryName":"United Kingdom","ReturnCodeDetails":"Success","ReturnCode":"1","IP":"212.58.253.67","CountryCode":"GBR"},"xmlns":"http:\/\/www.webservicex.net\/"}}
2. Create a data element using JSON Path plugin to extract the CountryCode attribute from the response.
   • Name: jsonResult
   • Category: General
   • Type: JSON Path
   • JSON String: {wsResponse}
   • JSON Path: $.GetGeoIPResponse.GetGeoIPResult.
3. In the Action Rules tab, edit the action for the Country attribute of the user to the data element jsonResult. Do this by entering {‘jsonResult’} in the Value parameter.
4. Modify a user and you should see the Country attribute being set to the country code where the IP address belongs.

How to Use the SOAPUI to Construct a SOAP Request

The following steps show how to use the SOAPUI as a tool to construct a SOAP request:

1. Download the tool from here http://www.soapui.org/

2. Open the tool and create a new SOAP project by specifying a name and the WSDL URL.

3. Right click the ‘Request 1’ under the ‘GetGeoIP’ web service operation and click ‘Show Request Editor’. The editor screen displays the template of the whole SOAP request.

4. Specify the required parameters.

5. Test the request by clicking Run.

6. If you are satisfied with the request, then you can cut and paste the whole request to the web service plugin.

Note: The sample SOAP action of the web service operation appears similar to the following graphic: