<<TableOfContents>>
Architecture
Properties Files
policyxpress.properties - Describes how Policy Xpress policies are stored, and the type of listeners available
policyxpress_errors.properties - Includes system and screen (UI) error messages, and environment error messages
policyxpress_plugins.properties - Describes details of elements and element types, actions and action types
Listener Types
policyxpress.listenertype.event=Event
policyxpress.listenertype.task=UI
policyxpress.listenertype.attribute=Attribute
policyxpress.listenertype.workflow=Workflow
policyxpress.listenertype.submittedTask=Submitted Task
policyxpress.listenertype.reverse=Reverse Sync
Listener Steps
policyxpress.listenerstep.before=Before
policyxpress.listenerstep.approved=Approved
policyxpress.listenerstep.rejected=Rejected
policyxpress.listenerstep.after=After
policyxpress.listenerstep.failed=Failed
policyxpress.listenerstep.start=Start
policyxpress.listenerstep.subject=Set subject
policyxpress.listenerstep.validate_onchange=Validate On Change
policyxpress.listenerstep.validation=Validate On Submit
policyxpress.listenerstep.submission=Submission
policyxpress.listenerstep.validate=Validate
policyxpress.listenerstep.workflowAsynch=Pending
policyxpress.listenerstep.taskStarted=Task started
policyxpress.listenerstep.taskCompleted=Task completed
policyxpress.listenerstep.reverse.detection=Reverse Sync Detection
policyxpress.listenerstep.taskFailed=Task Failed
policyxpress.listenerstep.approversResolved=Approvers resolved
Environment/Domain Errors
px.error.plugin.build.event=Error building action event
px.error.should.never.happen=Should never happen
px.error.role.missing=Failed finding role {0}
px.error.group.missing=Failed finding group {0}
px.error.role.members=Failed getting members for role {0}
px.error.group.members=Failed getting members for group {0}
px.error.role.membership=Failed getting role membership
px.error.group.membership=Failed getting group membership
px.error.group.set=Failed setting group membership
px.error.mo.getting.attribute=Failed getting attribute {0}
px.error.command.line=Failed running command line: {0}
px.error.search=Failed searching for object type {0}
px.error.screen.message=Failed placing screen message
px.error.blth.find=Failed searching for BLTH definitions
px.error.blth.create=Failed creating the BLTH listener
px.error.account.not.found=No account found
Etc...
Action Types
action.name.set.string.variable=Set String Variable
action.name.set.group=Set Group
action.name.set.access.role=Set Access Role
action.name.set.admin.role=Set Admin Role
action.name.set.provisioning.role=Set Provisioning Role
action.name.activate.command.line=Activate Command Line
action.name.execute.query=Execute Query
action.name.set.user.values=Set User Values
action.name.change.process.flow=Change Process Flow
action.name.log.message=Log Message
action.name.display.screen.message=Display Screen Message
action.name.throw.exception=Throw an Exception
action.name.send.mail=Send Mail
action.name.set.accounts.data=Set Account Data by Identifier
action.name.set.account.data=Set Account Data
action.name.java=Run Java Code
Etc...
Advanced Concepts
Recommended Development Methodology
Best Practices around Developing your Policy Xpress Policies
1. Document existing Policy Express policies with the following details to decide on Policy reuse and setting priority to control overall policy execution flow:
- PX Name
- PX Category
- PX Type
- PX Priority
- PX Description
2. Document business logic and use cases.
3. Develop pseudo code prior to developing policies, such as a flowchart or design document that describes functional or configuration details.
4. Develop Policy Xpress policies.
- Note: Be aware that some use cases may require many policies within the same STEP and EVENT to achieve the pseudo code goal. Also, policy priority numbers are critical in controlling the overall policy execution flow.
Deciding Policy Event Type
There are different Event types that can be configured in a policy to trigger an operation. It is important to decide the functional and business needs in order to select appropriate Event types to avoid any redundancy or policy looping.
- Event
(Asynchronous) This event type should be used when it is required to perform an operation if a specific event triggers, or if a Before or After specific Event triggers, such as ModifyUserEvent, AssignProvisioningRole, etc. This event type is similar to the Event listener. Note: Using this event type is expensive performance/process-wise.
- Pros:
Fewer rules required that are evaluated each time the specified event is raised.
- Cons:
Not all events have access to the USER object. Check under Management Console / Advance Settings.
Requires heavy planning and negative use case testing to prevent inadvertent execution. Otherwise looping WILL occur, especially for the Modify User event.
No access to secondary objects.
PX will trigger on event for any task that is capable of triggering a matching event.
- UI
This Event type should be used to perform operations at the User Interface level. UI Event type policies are generally used to prepopulate data, validate data, and to manipulate data once a task is submitted, while the task is in the synchronous state - meaning while a user still has the user interface for the task open. This event Type is similar to a BLTH. The following states are available for the UI Event type:
• 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
- Pros:
Can validate data with User intervention
Can stop task execution until valid data is entered
Interactive with User
- Cons:
Can slow down user experience
- Submitted Task
(Synchronous) This Event type should be used to perform operations when a task is transitioning from Synchronous state to Asynchronous state, but the task has not yet switched to Asynchronous state. The following states are available for the Submitted Task Event type:
• Task started
• Task completed
• Task failed
- Pros:
USER object is always available
EVENTS are linear, easier to debug, and unlikely to loop
- Cons:
Not user interactive
May require many policies, or a policy with a list of many task names that must be maintained
No access to secondary objects
Submitted Tasks vs. Event-Based - Synchronous vs. Asynchronous
Submitted Tasks (Synchronous Event Types):
- Task start – click on task link, search comes up
- Set subject – find object you want and click select
- (optionally enabled) Validate on change – type something in a field and hit tab
- Validate on submit – made changes and click submit button
- Submission – Done with the UI and its on the server
Event (Asynchronous Event Types - trigger events which have the following states):
- Before
- Approved - Note: No workflow always hits Approved.
- Rejected
- After
- Failed
Approach During Design Phase:
- Submitted Tasks
- Pro: USER object is always available
- Pro: EVENTS are linear and easier to debug and unlikely to loop
- Con: May require many policies or policy with a list of many task names that must be maintained
- Events
- Pro: Fewer rules required as a given policy will be evaluated each time the specified event is raised
- Con: Not all events have access to the USER object. Check under Management Console / Advance Settings
- Con: Requires heavy planning and negative use case testing to prevent inadvertent execution. Otherwise looping WILL occur, especially for the Modify User Event.
- Con: Expensive on process and performance
Note: Task name must be used to catch synchronous events. Sometimes you can't avoid Asynchronous triggers, for example, with copies of tasks - because the task name needs to be used to catch a Synchronous event. Otherwise, you must remember to edit the policy to use both task names (original and copy), or just trigger it for the Approved or After event.
When to use PX vs. BLTHs and LAHs, etc.
Generally, it is ALWAYS better to use Policy Xpress policies than a custom written BLTH, LAH, or Event Listener (where possible) for the following reasons:
- Policy Xpress policy evaluation and execution is metadata driven:
- No downtime - Policy Xpress allows you to create/edit policies and submit them. No need to compile, copy to app servers, restart, etc. With java code, you should always recompile with each SP - no need to do so with Policy Xpress policies.
- Cloud and managed service provider capability - There is no custom code support in the cloud.
- Policy Xpress executes business logic within pre-compiled and time-proven java code.
- Policy Xpress allows parameters of a policy to be changed on the fly.
- Quality - Policy Xpress code has been reviewed and tested through many releases of the product.
- Policy Xpress speed and performance, with regard to policy execution, is roughly equivalent to that of its custom written BLTH, LAH and Event Listener counterparts.
Data Element Order
- Define Static “Constants” Early in the Order. Use constants in the data element to avoid having to changing every Action Rule that may use the same static element.
- Define System Variables early in the Order. Use system variables to carry information over between additional Policy Xpress rules in the same Step.
- Define Data Elements used in Data Entry rules early in the Order
- Define Cascading Data Elements that rely on previous Data Elements in Sequential Order. Useful to avoid re-work of coding and performance
- Order of Remaining Elements is Non-critical
Iterators
- Have no stopping mechanism. If business logic requires only one rule to match, the engine continues to re-execute same Policy Xpress rule.
- Loops for remaining items => impact to performance
- Required to isolate correct endpoint accounts for multiple endpoint accounts for namespaces. For example, two (2) AD accounts on two (2) AD domains. There is no way to ensure that the first account name or endpoint returned is correct without checking. Returns more than one ID with ^ delineator.
- We recommend introducing a system variable to be updated in the add actions for any action rule that is met. For example, PX400.STOP_ITERATION = true. Prefix system variables with the Policy Xpress number so that they are not overwritten by a policy later in the stack.
Entry Rules
Entry Rules are your “data guards” to prevent unneeded execution.
- We recommended that you use entry rules for any Policy Xpress rule that triggers from an EVENT.
- Understand that the logic “within” an entry rule is always AND logic.
- Multiple entry rules use OR logic between them.
- Typically only one entry rule is required with one to three data elements.
- Unless using a task-friendly name to ensure that policies only fire under certain task names for a given event, the list of data elements may grow.
- Avoid using Task Unique Name. This is the Unique Identifier (numerical value) of the task within a given environment and will differ between environments.
- The Modify User Event requires entry rules. Otherwise you face looping for every single update made to a user account from AFTER CREATE USER EVENT to any SUBMITTED TASK.
Action Rules
Action Rules = case/switch logic.
- There can be only “ONE” that is valid.
- Ability to query/update SQL databases.
- Ability to update endpoint account attributes.
- Very flexible for most USER update operations.
- Add in system variables at end of the add action.
- Add in log warning message to allow for non-debug mode troubleshooting.
- Save ALL ADD actions to last Policy Xpress Rule in the SAME step. Performance gain to avoid triggering multiple events from the same Policy Xpress Step.
- List action rules with conditions that will most likely result in true first, unless switch logic prevents it.
- Prioritize action rules in 10 base to facilitate easier modifications in the future (10, 20, 30).
- Policy Xpress endpoint account attribute names do not always correspond to endpoint or Provisioning Server naming conventions.
- Policy Xpress endpoint DN representation does not correspond to endpoint convention when updating endpoint DN attributes.
- PX LDAP data source elements are unable to update an LDAP instance.
- Exposure to use Policy Xpress CLI action rule to use MS PowerShell is limited to certain version of Java (1.5 fails) / Java (1.6 works with workaround) due to PowerShell output in “objects” instead of strings.
Meta Policy Xpress Action Rule Concept
Where sequential Policy Xpress rules in the same Step are a sub-component of the “meta Policy Xpress rule”:
- Allows transformation logic to occur early, and commit write operation to the very last operation.
- Allows use of Policy Xpress system variables / SLAs (screen logical attributes) to store values instead of directly updating the LDAP store or endpoints.
- Allows for the product to process the business logic quickly, and reduces the impact of introducing multiple Modify User Events and looping.
- Define PX#.00 to manage data entry rules and initialization with system variables for all sequential Policy Xpress rules in the same Step, for performance.
- Policy Xpress GOTO Action Rule may be used to bypass additional Policy Xpress rules, but should be used in limited use cases.
Update Policy Xpress Modify Admin Task Screen
- Update the Search Screen to allow for searching on Policy Xpress naming conventions by changing the default search from equals to contains.
- Update the Profile Screen to allow for sorting of Policy Xpress rules by enabling sorting on all columns.
Debugging Policy Xpress
- Enabled logging.jsp
- If enabled without security, it is very easy to leverage for a development environment.
- Must be enabled per application server - other debugging info will be missed.
- Primary logger is ims.policyxpress. Set to DEBUG instead of default INFO.
- Allow other loggers to inherit
- DEBUG ims.policyxpress.PxStateListener
- DEBUG ims.policyxpress.PxSubmittedTaskListener
- DEBUG ims.policyxpress.PxBaseManagedObject
- DEBUG ims.policyxpress.FlowTask
- DEBUG ims.policyxpress.provider
- DEBUG ims.policyxpress.PxController
- Thread ID is the only current way to assist with following policy flow.
- log4j: Web AS log4j.properties file may be used to enable permanently.
- EAR folder location - use log4j.was_type.properties for the product
- Log4j.category.ims.policyxpress=DEBUG
- OS Environmental Variable may be used to set path to additional log4j.properties file. Example: WebLogic - LOG4J_CONFIG_FILE=E:\PROGRA~1\BEA\DOMAINS\IDM_DEV~1\log4j.properties
- Another File Appender may be used to keep Policy Xpress debug messages separate from WAS logging.
- log4j.rootCategory=WARN, Console, tofile
- log4j.appender.tofile=org.apache.log4j.DailyRollingFileAppender
- log4j.appender.tofile.layout=org.apache.log4j.PatternLayout
- log4j.appender.tofile.File=im_daily.log
- log4j.appender.tofile.DatePattern=yyyyMMdd'.'
- log4j.appender.tofile.layout.ConversionPattern=[%d] %-5p %c %x - %m%n