C.3 Interpreting Trace During Identity Manager Operations

C.3.1 When a Rule Executes

An Identity Manager policy contains one or more rules. Each rule comprises of one or more conditions and actions that will be performed when the conditions are met. When Identity Manager engine evaluates the condition set for a rule, the trace displays Evaluating Selection Criteria for the rule followed by the rule’s name.

If the complete condition is true, the rule execute its actions. If the condition is false, the rule’s actions are skipped and the rule is rejected.

The rule rejected message does not mean that there is an issue in the logic. Each rule reacts to certain events and conditions. It is normal that several rules are skipped. For example, you instructed Identity Manager to reject rules that handle only users when processing a group event while synchronizing both users and groups.

Before a rule executes its actions, the trace displays Applying Rule followed by the rule’s name. Identity Manager evaluates the conditions using boolean logic. Note that the trace displays a condition group in parenthesis and the outcome of evaluating the logic of the condition group after the parenthesis. This information is useful particularly when the condition is comparing something to true or false.

The trace shows each action in the rule’s logic and also displays details about the processing needed to evaluate the arguments of the action. The first line contains the actual action that will be executed and its arguments. This is followed by each individual portion of the argument being resolved. It then shows the argument’s value that will be used in the action.

In this example, the argument for Set Operation Destination DN command is composed of three items: an unmatched Source DN token, a comma character, and the value of a global variable. The final value of the argument (cn=ablanston,dc=local) that Identity Manager uses in the command appears after Arg Value.

C.3.2 During Driver Startup

You can capture useful information about a driver in a trace, such as GCV information, initialization parameters, and filter information during the driver initialization.

When the driver initialization process starts, the driver reads the named passwords list, information from the driver object, and the objects that store the actual policies, rules, and stylesheets. During this process, the trace displays messages such as Reading XML attribute vnd.nds.stream; full DN of the object, and the attribute that the driver reads in addition to other information that the driver reads.

Below is a sample trace from an eDirectory driver startup:

[01/02/17 10:26:15.451]:eDirectory Driver :Reading named passwords list.
[01/02/17 10:26:15.469]:eDirectory Driver :Named passwords:
[01/02/17 10:26:15.570]:eDirectory Driver :Reading XML attribute
vnd.nds.stream://OESNW_TREE/idm/services/driverset/eDirectory+Driver#DirXML-EngineControlValues.
[01/02/17 10:26:16.113]:eDirectory Driver :Reading XML attribute
vnd.nds.stream://OESNW_TREE/idm/services/driverset#DirXML-ConfigValues.
[01/02/17 10:26:16.126]:eDirectory Driver :Reading XML attribute
vnd.nds.stream://OESNW_TREE/idm/services/driverset/eDirectory+Driver#DirXML-ConfigValues.
[01/02/17 10:26:16.180]:eDirectory Driver :Global Configuration Values:
[01/02/17 10:26:16.182]:eDirectory Driver : Name: enable-password-subscribe Value: true
[01/02/17 10:26:16.184]:eDirectory Driver : Name: enable-password-publish Value: true
[01/02/17 10:26:16.185]:eDirectory Driver : Name: publish-password-to-nds Value: true
[01/02/17 10:26:16.186]:eDirectory Driver : Name: publish-password-to-dp Value: false
[01/02/17 10:26:16.188]:eDirectory Driver : Name: enforce-password-policy Value: true
[01/02/17 10:26:16.190]:eDirectory Driver : Name: reset-external-password-on-failure Value:
true
[01/02/17 10:26:16.205]:eDirectory Driver : Name: notify-user-on-password-dist-failure Value:
true
[01/02/17 10:26:16.206]:eDirectory Driver : Name: ConnectedSystemName Value: eDirectory Driver
[01/02/17 10:26:16.208]:eDirectory Driver : Name: dirxml.auto.treename Value: OESNW_TREE
[01/02/17 10:26:16.209]:eDirectory Driver : Name: dirxml.auto.driverdn
Value: \OESNW_TREE\idm\services\driverset\eDirectory Driver
[01/02/17 10:26:16.223]:eDirectory Driver : Name: dirxml.auto.driverguid Value: {044F4400-
B953-11dc-968B-000C290066AE}

Below is the meaning of each line in the trace:

The first step is the driver start. At this point, the driver tries to read the named passwords list.
There is a header before listing the names on the named password list. The header is blank because this driver did not have any named passwords configured.
The engine reads the value from the DirXML-EngineControlValues attribute. This attribute resides in the Identity Vault object called Identity Vault Driver under the driverset.services.Identity Manager container under the tree named OESNW_TREE.
The engine reads the value from the DirXML-ConfigValues attribute that resides in the Identity Vault object called driverset under services.Identity Manager container under the tree named OESNW_TREE.
The engine reads the value from the DirXML-ConfigValues attribute that resides in the Identity Vault object called Identity Vault Driver under driverset.services.Identity Manager container under the tree named OESNW_TREE.
A header is shown before listing the Global Configuration Values.
This and the remaining lines show the GCV’s names and values that will be used in the policy’s logic.
As the driver initialization continues, the driver reads the values for certain attributes and shows them in the trace. If the driver is using the Remote Loader, you also need to see the Remote Loader connection messages in the Remote Loader trace. The driver initialization continues reading information from the needed objects until it finishes initializing all of them and then proceeds to query the shim for identifying the driver class.
The shim responds to the query with information about its type, version, activation level, and capabilities. There is a possibility that some queries are sent and messages are exchanged in the process, such as a query from the shim to the driver for its GUID and Public Key attributes. The driver initialization completes when you see the following message in the trace:
```
[12/06/17 10:26:26.467]: Identity Vault Driver ST:Transitioned from state '%+C%14CStarting%-C' to state '%+C%14CRunning%-C'.
```
After this message, the events start coming in the trace. If you are looking at fixing the driver initialization problems, set the engine trace to level 4 and read the information line by line until you see an error message with more details.

C.3.3 During Query Processing

A query is an out of band request that stops the normal flow of events until it is processed. The engine stops processing the current event until the query is processed. A query can be issued by a condition within a rule, by an action within a rule, or by certain noun tokens inside an action’s parameters. You can issue a query within XSLT code. Such queries act exactly the same way as the query issued by using DirXML Script.

The path of a query path varies based on its source and destination. Therefore, information printed in the trace also varies.

A query can follow the following paths:

Straight into Identity Vault without passing through policies.
To the application, but passing the channel-independent translation logical block.
Straight into the application without passing through policies.

Example 1

A query from a channel is sent to the connected application and passes through the translation logic. At the same time, policies and rules in the driver’s Subscriber channel are processing a modify event from the Identity Vault.

When a rule issues a query, the original modify event stops processing until the query results are returned. The result of a query always returns a status message. A success in the status message means that the query is issued without errors. However, it does not mean that any results are returned.

A query in the Identity Manager trace (level 2 or above) prints "Query from policy" text. The below figure shows the query element containing User class with single entry as the scope of the search for the value of DirXML-EntitlementRef attribute.

The trace prints Pumping XDS to eDirectory message when the query enters the Identity Vault. This message is printed every time an event or a command enters the Identity Vault. When the result of the query is received, the trace prints Query from policy result message. The result always contains a status element and an instance element with a single object. In case no objects are found, the Identity Vault returns no instance elements. It returns one instance element for each object.

After the results of the query are returned to the rule that issued it, the original event processing is resumed.

Example 2

A query passes through the Outbound Association Reference Processor, Schema Mapping policy set, and Output Transformation policy set of the engine, and then handed over to the driver shim before it is passed to the connected application.

When a rule (one from the Event Transformation Policy set) issues a query, the original modify event stops processing until the query results are returned.

The connected application returns the results of the query to the driver shim. The driver shim then builds the XDS document with a status element and zero or more instance elements. This XDS document then passes through the Input Transformation policy set, Schema Mapping policy set, and Inbound Association Reference Processor before it returns to the rule that issued the original query.

Note that this is the only case where both query and its elements pass through the driver logic. This occurs because Identity Manager assumes that anything issued from within a driver channel is in the Identity Vault format. For the application to understand what is requested, the event must converted to the application format. Conversely, any results from the application must converted back to the Identity Vault format before it is processed.

After the results of the query are returned to the rule that issued it, the original event resumes processing.

Example 3

A query passes through the Outbound Association Reference Processor, Schema Mapping policy set, and Output Transformation policy set of the engine, before it is passed to the connected application.

When a rule (one from the Output Transformation Policy set) issues a query, the original modify event stops processing until the query results are returned. In this case, the query is directly passed to the driver shim. The driver shim directly returns the query result to the rule that issued the query.

After sending the query result, the driver resumes processing the original event.

Identity Manager processes queries in the same way regardless of whether the query is issued from a condition or an action. However, the trace displays changes based on the source that issued the query.

When a query is issued from a condition: The condition that issued the query appears only after the query result is returned. This is because the trace shows a rule’s condition with its evaluation result on the same line. To evaluate this condition, Identity Manager engine needs the query’s results.
When a query is issued from within an action: The action is shown before the query is issued. This is because the result is not necessary to display the action in the trace.

C.3.4 When Direct Commands are Processed

Direct commands can follow three paths just like queries.

Straight into Identity Vault without passing any policies
To the application, but passing the channel-independent translation logic
Straight into the application, without passing policies

The trace shows a command preceded by Direct command from policy text. It is easy to track the destination and path of a command by reading the first line in the trace after the command is issued.

C.3.5 During add-association Events

When Identity Vault sends an add event to a driver shim, and if the driver shim executes the event in the connected application, it returns both the status message and an add-association command to the Identity Vault. This command follows the same flow as the status message before it is processed.

The below example shows the XDS for an <add-association> event. The driver sends 39dad26730eb37478932f7b9d505116f as an association value to the Identity Vault. This is a value that the shim knows that uniquely identifies the newly created entry in the connected application.

The <add-association> ties back to the original event through its event-id XML attribute. The driver shim also generates the destination DN by copying the source-DN of the original event.

In addition, the driver shim sends some additional XML elements (tags) along with the association value, but they are not part of it. The status message that the driver sends also contains those XML elements. Those XML elements are the properties of the operation. Operation properties are never sent to the shim. The Identity Manager engine strips the properties from the source event before handing over the event to the driver shim, and adds them back to the result of the event.

Since the properties of the operation are not sent to the shim and are added back to the returned results, the Identity Manager engine uses these properties to save information about the original event. This information is used in the logic that processes those results.

The add-association event then passes the translation processor, and right after that the destination object in the Identity Vault obtains an association. An add event from the Publisher channel already has the association value in the event that the engine uses to build the association when it creates the object in the Identity Vault. Therefore, you do not see an add-association command.

The add association rule can forcefully add an association to an object in the Identity Vault. For more information about the rule, see Add Association in the NetIQ Identity Manager - Using Designer to Create Policies.

C.3.6 Cases with No Trace Excerpts

There are certain cases where trace is not printed. For example, policies and rules in the driver’s Subscriber channel are processing a modify event from the Identity Vault and a command is sent from inside a channel to the connected application.

When a rule issues a direct command, the original modify event stops processing until a status message is received from the command. In this case, the modify event issued by the rule passes through the data transformation logical blocks of the engine, the driver shim, and then reaches the connected application. The connected application then performs the required action and returns a status message (success or error status). The driver shim builds the XDS document with a status element that contains the result. This XDS document passes through the data transformation logical blocks before it is returned to the rule that issued the command.

Note that this is the only case where both modify event and its resulting status elements pass through the driver logic. This occurs because Identity Manager assumes that anything issued from within a driver channel is in Identity Vault format. For the application to understand what is being requested, the event must be converted to the application format. Conversely, any result from the application must be converted to an Identity Vault format before it can be processed.

When the rule receives the result of its direct command, Identity Manager resumes processing the original event.

Example

Policies and rules in the driver’s Subscriber channel are processing a modify event from the Identity Vault and a policy inside the Input Transformation policy set or the Output Transformation policy set issues a direct command to the application.

When a rule issues a command, the original modify event stops processing until the command’s results are returned. In this case, the modify event is directly handed to the driver shim. The driver shim directly sends the result of the event to the rule that issued it.

When the results of the command are returned to the rule that issued it, the driver resumes processing the original event.

Both queries and direct commands follow very similar paths in the engine, and these paths are different from the regular event flow. A driver can have several instances of queries and direct commands. It is a good practice to remember the information that the trace displays for them when they start and stop.