There are numerous best practices that can be listed for proper driver development. This guide lists the ones that make sense to improve driver configuration quality, stability, scalability, and readability.
GCVs are global configuration values or constants, not global variables. There is no way to change a GCV value at runtime. The GCVs are globally accessible to the driver and driver set, but not to the tree or network.
Given these facts, GCVs are constants and cannot be changed at runtime, but they can be consumed by all drivers in a driver set or by all policies in a driver. This makes GCVs a very powerful configuration tool. Use the following guidelines when developing with GCVs.
GCVs help driver configuration files adapt to changing environments by externalizing environment-specific, such as placement contexts, domain names, IP addresses, usernames, dates, and times.
It is a bad practice to configure the driver to prompt for information during import and then add the answer directly into policy code. The better approach is to store the answer in a GCV and make the policies reference the GCV. If the answer to the prompt is wrong or the environment changes, the answer also needs to change. It is much simpler to change a single GCV value than to go through all policies that have the value and change the value in each policy.
By adding the configuration data as a GCV, the GCVs become the controls of the driver.
If there are certain configuration values that must never change, they should not be surfaced in a GCV.
All information in a GCV can be easily changed or tuned. To keep certain configuration values and implementation details from being changed, add this information directly into the code. Everything that an administrator should see and be able to change should go into a GCV. Everything that only a developer sees or changes should go directly into the driver policy code.
The only reason to add a static value to a GCV is if it is used in many different places and it does not make sense to add it directly to the code.
GCVs can be defined on a driver or driver set. The GCV location determines its scope and visibility. GCVs defined on the driver set are visible to all drivers and their policies in that driver set. GCVs defined on a driver can only be consumed by policies of the driver.
If a GCV defined on a driver has the same name as a GCV defined on the driver set, the driver GCV takes precedence in all policies that belong to that driver. This allows for easy exception handling:
Driver Set: idv-new-users = users.staging.data
All drivers except one: none
Exceptional driver: idv-new-users = users.inactive.data
All drivers that do not explicitly define the GCV g-driver-new-users would inherit this GCV from the driver set, and policies in those drivers can read the value user.data. The policies in the exceptional driver, which defines a GCV with the same name, read the value users.inactive.data.
There are certain operations that all administrators should be able to rely on having in every driver configuration file. There are other operations that are optional. This is to avoid problems that might occur if an unexpected operation is invoked, and also to establish a similar driver behavior across all drivers.
The following options should be implemented on each driver. For a more detailed explanation of how the Metadirectory engine handles these requests, see Synchronizing Objects
in the Identity Manager 3.6.1 Common Driver Administration Guide.
Over time, event-based synchronization tends to result in a growing gap between what is expected and what actually happens. This is because policy writers do not consider all possible events and don’t implement policies to take all necessary actions.
Administrators want and need the ability to tell a driver to re-evaluate the current data in the Identity Vault against its policies and perform all the necessary tasks so that after the evaluation occurs, the gap between the two systems is closed.
Over time, event-based synchronization tends to result in a growing gap between what is expected and what actually happens. This is because policy writers do not consider all possible events and don’t implement policies to take all necessary actions.
Administrators want and need the ability to tell a driver to re-evaluate the current data in the application against its policies and perform all the necessary tasks so that, after the evaluation occurs, the gap between the two systems is closed.
Administrators might click the resynchronize button for the same reasons as they would to a migrate data to or from Identity Vault. However, the Metadirectory engine treats a resynchronization request very differently from migration requests. If Migrate From Identity Vault and Migrate Into the Identity Vault are implemented fully, there would be no need for the resynchronization option.
The guidelines in this section are not the only options for policy development, but they are backed by years of field experience and also represent engineering experience and advice.
New policy writers have trouble deciding whether to use a single rule or to use multiple rules, and whether to use a single policy or to use multiple policies. Use these considerations to help you decide:
Group actions by task, feature, and requirement. This means that if you define a feature called Password Synchronization, you group all the conditions and actions that make up this feature and put them into a single separate policy or multiple separate policies. Do not have different features use the same policy because that makes it difficult to remove or add individual features.
Every action of a task, feature, or a requirement that must be completed based on the same conditions and that can be completed in the same policy set should be placed into the same rule.
NOTE:An exception is that if one action changes the variables of the conditions, this action must have its own rule, but it must reside in its own policy.
All rules that can be executed in the same policy set should be grouped into the same policy.
A short-circuit evaluation rule should be the first rule in a policy, if a policy deals with numerous rules that all test on very similar but slightly different conditions, and there is a strong possibility that none of the rules will be activated.
The evaluation rule should opt out of the current policy when it is obvious that none of the conditions in the rules evaluate to True. An example is a Placement policy based on the location code. The Placement policy might be rather long, consisting of a dozen or even hundreds of rules, each testing for their specific location code. If the location code is a well-know format, such as two characters and no numbers, it makes sense to have the first rule of the policy check these requirements and put a break in the policy if the value of the location does not conform to the format, and none of the following rules would even run.
If dynamic information, like an attribute value from a query result, is passed on from policy to policy, local variables cannot be used prior to Identity Manager 3.5. The earlier versions limited the scope of a variable to a single policy. GCVs cannot be used either because they are a constant and the content cannot be changed.
The solution is to use an operation property. An operation property can transport typeless text data from policy to policy and can easily be set and queried. Use the set operation property action, the operation property noun, or the if operation property condition to use operation properties. Avoid issuing the same query multiple times if you can.
The general recommendation is to create what is possible with reasonable effort in DirXML® Script. XSLT is a valid way of doing things in Identity Manager, but it is easier on other people to understand what a policy is doing, if it is be implemented in DirXML Script.
One limitation of DirXML Script that forces the use of XLST is the XML document does not conform to XDS as specified in the nds.dtd. Typical examples here are input and output transformation policies of some of the generic drivers, such as Delimited Text, SOAP, or JMS.
For more information about the nds.dtd, see the Identity Manager 3.6 DTD Reference.