<<TableOfContents>>
Profile Tab
The profile tab for a Policy Xpress policy contains fields that manage policies and refine policy capabilities.
Note: A policy only applies to the environment it is created in. For example, if you create a policy while logged into the neteauto environment, the policy runs only for the neteauto environment.
Provide the following profile information when creating a policy:
Policy Name
Defines a unique friendly name for the policy.
Policy Type
Defines the listeners that trigger the policy. Each policy type has a different configuration.
Note: You cannot change this field once the policy is saved.
Category
Defines a group of related policies. This field allows you to group policies for easy management.
Description
Specifies a description of the policy.
Priority
If there are multiple policies that run at a single event, this field specifies when the policy runs. Policies are executed based on their priority. The lower the number, the higher the priority (priority 1 runs first, 10 runs second, 50 runs third, and so on).
Setting priority is useful for policies which have a dependency on one another, or breaking a complex policy into two simple ones, that run one after the other.
For example, there are three policies which run if there is a specific value in the database. Instead of having each of the policies verify the value in the database, you can create a policy that runs before the other three policies and checks the value. If the new policy matches the required value, Policy Xpress can set a variable. The other three policies only run if that variable is set, which prevents redundant access to the database.
Enabled
Specifies if the policy is active in <idmgr>. You can clear this check box if you want to disable a policy without deleting it.
Run Once
Specifies if the policy runs only once. Some policies may need to run every time they meet criteria, and others may need to run only once. This value determines if action rules that have already executed in the past should execute again.
For example, adding an SAP role to a user based on department is an action that should only occur the first time the user matches that department. Alternately, a policy that sets the user's salary level based on title would not be set to run once, to make sure that no unauthorized changes take place.
Note: The Run Once option applies to an object, it does not apply globally.
Listeners
Policy Xpress policies are triggered by something that happens in the system. To implement this functionality, listeners that integrate with the system notify Policy Xpress when an event happens, and provide details about the event that occurred.
The following listeners are available:
Event
Listens for every event in the system and all the states associated with the event (before, approved, rejected, and so on). This listener also reports the name of the event to Policy Xpress. The following states are available for the Event listener:
- Before
- Rejected
- Approved
- After
- Failed
- UI
Listens for different tasks running in the system during the synchronized state, meaning while a user still has the user interface for the task open. The following states are available for the UI listener:
- Start—when the task starts
- Set subject—when the primary object is found
- Validate On Change—when an attribute set with the Validate on Change flag changes
- Validate On Submit—when clicking the submit button
- Submission—when the task is submitted
Workflow
Listens for workflow processes that have found approvers. This listener is useful for performing logic based on approvers, such as sending an email to the approver.
Submitted task
Listens for submitted tasks not running in the background. This listener is similar to the Event listener, however, it considers the task as a whole, instead of the task's events. The following states are available for the Submitted task listener:
- Task started
- Task completed
- Task failed
- Reverse Sync
Listens for notifications in the system that relate to <idmgr>'s Explore functionality.
On-Screen Attribute Validation
In addition to the defined triggers (policy types), Policy Xpress can also listen to validation on attributes. This allows you to create policies that can run when an on-screen attribute that has been flagged as “validate on change” is updated.
This functionality can be used for creating dependant drop-down lists. For example, if there are two drop-down lists on the screen, Policy Xpress runs when the first drop-down option is selected, then sets the values for the second drop-down list based on the option selected in the first. An unlimited number of drop-down lists and other screen refreshes can be done. This differs from Select Box Data by allowing the drop-down options to be populated using any logic, rather than importing an XML file of static options.
Another use is populating other attributes based on the value of one attribute. For example, when an administrator selects a department, Policy Xpress can automatically populate other attributes, such as department manager, department number, and HR Dept Code. This replaces the need to write logical attribute handler custom code.
To configure validation with a Policy Xpress policy
- In the User Console, modify a task's profile screen and select the field you want to listen for.
- Access the field's properties and select Yes in the drop-down list for Validate on Change.
- In Policy Xpress, create a policy of type 'UI' .
- Under the Run at Events tab, select the State 'Validate on Change' and the task you modified in Step 1.
Events Tab
Depending on the policy type selected on the profile tab, you can configure activation times to establish when the policy is evaluated. For example, a policy of type Event can be set for evaluation Before a CreateUserEvent. A policy of type Task can be set for evaluation at Set Subject for DisableUserEvent.
To configure an activation time, select the following fields:
State
Specifies the time frame or action related to the event that activates the policy. For example, a policy can be set to run "Before" an event occurs.
Event Name
Specifies the event that activates the policy, such as a CreateUserEvent.
A policy can have more than one activation time. Every time a specified activation time (a state and an event) occurs in the system, Policy Xpress searches for all policies with that activation time, and evaluates each policy based on its order.
Note: If a policy matches an activation time that occurs in the system, it does not mean that the policy is automatically run. Rules criteria evaluated later in the process determine if the policy is completed.
Data Elements Tab
Data elements are used for creating policy data. A policy can contain multiple data elements that represent the information used by the policy.
Policy Xpress uses flexible plug-ins for gathering the data element information. Each plug-in can perform a small, dedicated task. However, several plug-ins can be used together to build more complex policies. An example of a data element plug-in is a user attribute element. The goal of the element is to gather information about a certain attribute which is a part of the user's profile.
Data elements are calculated when they are called, meaning either a rule is using the data element, or another element needing calculation is using the data element as a parameter.
For example, an SQL query data element can retrieve a value from a table, but it needs the user's department to build the query. In this case, the department data element must run before the SQL query data element, and then the value can be used as a parameter.
The following fields define a data element:
Name
Defines a friendly name that describes the data element. Some data elements are complex (such as getting variables or retrieving information from the database). Be sure to select a meaningful name to simplify data element management.
Category
Provides a grouping of data elements. This field sorts the data elements and makes selection easier.
Type
Specifies the data element type, each with its own dedicated use. This field is based on the category selected.
Function
Defines possible variations of the same data. Most data elements only support the Get function.
For example, the user attribute data element has the following functions:
- Get—returns the values of the attribute
- is multi valued—returns true if the value is multi-valued
- is logical—returns true if the value is logical
- Function Description
Provides a prepopulated description of the function. Each function selected provides a different description to help in understanding its use and what the expected values are.
- Parameters
Defines the parameters passed to the data element. Data elements are dynamic and can do different things based on the parameters. A user attribute data element returns different results based on the attribute selected. The sub type option also defines the number of parameters, their names, and the optional values when available.
You can add additional parameters if necessary. The SQL query example accepts two required parameters, the data source and the query itself. The query can use the "?" to be replaced with values (much like a prepared statement). Adding additional parameters allows you to set those values.
- Note: When viewing data elements in Policy Xpress, there is a column titled 'In Use'. A checkmark in this column means that the data element is used by a rule, an action parameter, or as a parameter to other data elements.
Use Dynamic Values in Data or Action Elements
Dynamic values are the result of calculated data elements, and their values are only decided at run time. These values can then be used as parameters of other data elements (that are subsequently calculated, based on priority).
To use a dynamic value as a parameter for a data element
- In the Policy Data tab, locate the parameter you want to set a dynamic value in.
- In the empty text field, enter any regular text or select the dynamic value from the right drop-down list.
- Click OK.
Variables
Policy Xpress has variables that are set with actions and saved as data elements (Variables category). Variables are shared across all policies that run at the same time, so a variable that has been set can be used by other policies of lower priority.
For example, a variable can contain a value calculated once by a policy, and then shared across other policies that no longer need to recalculate the value. The initial policy sets a value to the variable, and policies that run later read that value by using a data element that has the variable name as a parameter.
A variable can also be a trigger for other policies. In this case, the policies only run if the policy before them has run.
Entry Rules Tab
Entry Rules define the conditions for when a policy should run. These conditions use the values gathered by the data elements in the policy.
There can be multiple entry rules in a policy, and an entry rule can have multiple conditions. At least one entry rule must be matched, meaning all conditions in that entry rule must be met for a policy to move on to the action rules.
The following fields define an entry rule:
Name
Provides a friendly name for the entry rule.
Description
Defines the meaning of the entry rule.
Conditions
Specifies the criteria to match.
Note: Conditions in an entry rule always have an AND operator between them.
Conditions
A condition is used in entry and action rules and is comprised of the following components:
- Policy Data
- Operator
- Value
For example, you want to create a condition that checks if a user's department was changed. First, define a Department Changed data element, then, in the condition, select the Department Changed data element, set the operator to Equals, and set the value to True.
Action Rules Tab
Action rules are similar to entry rules in structure, but differ in functionality. Action rules define when action should be taken. For example, if you want a policy to perform an action when a user's department has changed to Sales, create an action rule that defines when 'Department = Sales'.
Also, instead of having to match one entry rule, several action rules may be matched. The single action rule with the highest priority (0 being the highest) is the only one used.
Action rules also contain one or more actions, and the actions are divided into Add Actions and Remove Actions.
The following fields define an action rule:
Name
Provides a friendly name for the action rule. This name must be unique.
Description
Defines the meaning of the action rule.
Conditions
Specifies the criteria to match.
Priority
Defines which action rule executes, in the case of several action rules matching. This field is useful for defining default actions. For example, if you have multiple rules, each for a department name, it is possible to set a default by adding an additional rule with no conditions but a lower priority (such as 10 if all others are 5). If none of the department rules are matched, then the default is used.
Add Actions
Defines a list of actions taken when the rule is matched. For example, you can configure a rule that states if the user's department matches the one configured in the condition, add a specific Active Directory group. Action rules behave differently, based on the Run Once setting. If the policy is set to run once, the associated actions are performed the first time the rule matches. The actions are not performed again for each subsequent rule match. In the example above, the Active Directory group is added to the user only once. If Run Once is not set, then the actions run again as long as the rule is matched. This field is important for enforcing values.
Remove Actions
Defines a list of actions to perform when the rule no longer matches. For example, the previous example added an Active Directory group to the user, based on the department. If the department changes, then the remove action removes the Active Directory group.
Note: The PX policy ID is persisted on an object so that when a rule no longer matches, the policy triggers the remove action.
Actions
Actions perform the business logic after all the decision-making is done. An action works in a similar way to data elements except at the end. When it runs, it performs a task instead of returning a value.
Note: Actions are run in the order they appear in the User Console.
The following fields define an action:
Action Name
Defines the purpose of the action.
Category
Provides a grouping of actions. This field sorts the actions and makes selection easier.
Type and Function
Defines the type and function of the action taken.
Note: For more information about Type and Function, see Data.
Function Description
Provides a prepopulated description of the function. Each function selected provides a different description to help in understanding its use and what the expected values are.
Parameters
Defines the parameters passed to the action.
Flow Control
By default, policies are sorted by priority and then evaluated one by one. While this flow almost always applies, you can change the flow, if necessary.
This flow-changing functionality is represented by an action that can be attached to any action rule. Flow-changing functions are located under the System category of the action.
Important! Use caution when changing process flows. Using these actions may result in an infinite loop. For example, if you set 'Redo the current policy' on an action rule with no conditions, the rule will always be true, and the policy will always restart and never exit.
The following four flow-changing functions can be used:
Stop processing
Causes all policies after the current policy to be ignored, and causes Policy Xpress to exit.
Note: Only Policy Xpress exits. If you want to force <idmgr> to stop also, you can use the Exception type action plug-in.
Restart all policies
Stops processing the rest of the policies and goes back to the start of the list. This option is useful in cases where the action of one policy causes another policy, which ran before it and did not execute, to now meet the entry criteria. That policy is now reevaluated.
Redo the current policy
Causes a policy to run again. This option is useful for iteration. For example, creating a unique username requires a policy to run over and over again until it finds a unique name.
Go to a specific policy
This action requires selecting an existing policy. If that policy is running at the same time as the current policy (can be before or after) then Policy Xpress jumps to the selected policy. If the new policy is of lower priority, all policies between the current policy and the selected policy are ignored. If the new policy priority is higher, the process goes back.
Note: Because the action may cause Policy Xpress to skip certain policies, use this action type with caution.
Advanced
Policy Xpress allows for many configuration variations and also interacts with external components. Due to this flexibility, errors may occur that are not necessarily bugs, such as an incorrectly configured data source, a missing value returned from a dynamic data element, or an endpoint which is not responding.
Usually when an error occurs, the system will stop the calculation of policies for the current step. However, you can change the default error response, based on the error category. For example, if you have a policy that is non-critical, you can define that the processing should continue in the event of an error.
The Advanced tab allows you to change the default error responses if necessary.
Note: We recommend that these error responses be left to their defaults, but for advanced use cases, these settings can be changed per policy. For example, if you have a policy that is non-critical, you can define that processing should continue even if the policy failed.
The following error categories can be configured on the tab:
- Validation—caused by providing incorrect information to a plug-in. This type of error is reported before the action is attempted.
- Environment—caused by problems in the environment, such as a failing database server for the SQL plug-in.
- Allowed—a non-critical error. The default behavior for this error type is to continue processing the request, such as when sending an email fails.
For each of the previous errors, the following options can be set:
- Fail event—stops the current action. This is the default for most error types.
- Fail policy—stops the current policy and all actions associated with it. The rest of the policies continue.
- Ignore—logs any failure but does not stop the actions or policies.