This article will guide the reader in a graphical way through IDM Out-of-Band events. It assumes that the reader is already familiar with IDM and basic trace reading, and have read the first part of this series at Comprehending IDM Traces - part 1. The present Article will detail Queries, Direct Commands from Policy, Status messages and Add-Association events.
Lets start out by defining what Out of Band Requests are. Out of Band Requests are events that are handled differently than regular IDM events. Some can be triggered by certain conditions or actions within a Rule, some are just results of other events.
The Out of Band requests include:
A query goes through different paths based on where it is issued and where it goes to obtain the information. It can be issued by a condition within a Rule, by an action within a rule or even by certain noun tokens inside an action's parameters. It is possible to issue a query from within XSLT code, and such queries behave exactly the same way as the ones issued from within DirXML-Script code.
A <query> always has a <status> coming back as a result. If any values are returned, those come inside an <instance> event. It is easy to track its destination and path by the first line in the trace after the <query> document is issued, as can be seen in this table:
Now, this concept is really important: the path followed by a query varies based on its source and destination. This means that the information displayed in the trace will vary accordingly. Also, as per the table above, we have basically 3 paths that can be followed:
With that in mind, lets go over some diagrams and trace fragments to make this concept easier to understand. On the diagrams below, the legend on the lower corner shows the source and destination for the query that diagram.
So lets start with a query going straight into eDirectory. In this diagram, a modify event came from eDirectory and is being processed normally by the policies and rules in the driver's Subscriber channel.
When a rule (in our example, placed in the Event Transformation Policy set) issues a <query>, the original <modify> event will stop processing until the <query> results are returned. The result of a query will always return a <status> message. Note that a "Success" in this status message just means that the query was issued without errors to the destination, it does not mean that any results were returned. If the query has one or more results, those will come inside an <instance> element. If a query has zero results, there won't be an <instance> document in the <output> document returned.
Lets tie this diagram with an IDM trace. All queries print in the IDM trace (level 2 or above) the text "Query from policy". For this example, we can see from the <query> element that the class we want is "User", and that the scope for the search is a single entry. Lastly, we want to get back the value of the attribute named "DirXML-EntitlementRef".
Here our <query> hits eDirectory, as is indicated in the trace by the text "Pumping XDS to eDirectory". This text will appear in an IDM trace every time any event or command reaches eDirectory. It is by no means exclusive to queries.
Now the result of the <query> comes back. All <query> results are preceded by the text "Query from policy result" in the IDM trace. This result contains one <status> element, and that will always be the case with queries. It also contains a single <instance> element, and that means a single object was found. If zero objects were found, no <instance> element would be returned. If multiple objects are found, we would have one <instance> element for each object found.
Other important information we can gleam from this excerpt is that even though we found the entry, the attribute whose value we requested is empty. If the attribute had any value at all, that value would have returned as a child of the <instance> element inside an <attr> element.
After the results of the <query> are returned to the rule that issued it, processing will continue on the original event.
At this point we finished reviewing a query straight into eDirectory. To keep things simple there will be no trace excerpts in the next 2 diagram sets.
Now let us review a <query> coming from inside a channel to the connected application, passing the translation piece. In this diagram, again a modify event came from eDirectory and is being processed by the policies and rules in the driver's Subscriber channel.
When a rule (in our example, one from the Event Transformation Policy set) issues a <query>, the original <modify> event will stop processing until the <query> results are returned.
In this case, however the <query> itself will pass through the Outbound Association Reference Processor, Schema Mapping policy set and Output Transformation policy set. After passing those 3 pieces of the engine, the <query> will be handed over to the driver shim and finally to the connected application.
The connected application will then return the results of the <query> to the driver shim. The driver shim then will build the XDS document with a <status> element and zero or more <instance> elements, based off of what was returned. This XDS document will then pass through the Input Transformation policy set, Schema Mapping policy set and Inbound Association Reference Processor before being returned to the rule that issued the original query.
Note that this is the only case where both the <query> and its elements pass through any driver logic. This happens because IDM assumes that anything issued from within a driver channel is in eDirectory format. For the application to understand what is being requested the event will need to be converted to the application format. Conversely, any results from the application will need to be converted back to an eDirectory format before it can be processed.
Like last time, after the results of the <query> are returned to the rule that issued it, the original event will continue being processed by the driver.
Lastly, lets review a <query> coming from inside the translation pieces - Input Transformation policy set or Output Transformation policy set - and going directly to the application. In this diagram, again a modify event came from eDirectory and is being processed by the policies and rules in the driver's Subscriber channel.
When a rule (in our example, one from the Output Transformation Policy set) issues a <query>, the original <modify> event will stop processing until the <query> results are returned.
In this case the <query> is handed directly to the driver shim, and its results come straight from the driver shim to the rule that issued the <query>
Like last time, after the results of the <query> are returned to the rule that issued it, the original event will continue being processed by the driver.
By now you should be familiar with queries. One last warning is that any event can be suspended when a <query> is issued. Since there is one scenario where a <query> passes through other policies, it is possible to have that <query> being paused by another <query> (or by a direct command from policy). There is no risk of an infinite loop, since the second Out of Band request will be issued from inside the translation portion of the driver (3rd scenario discussed above), and go straight to its destination, be it eDirectory or the connected application.
There is another peculiarity with queries in IDM traces. Although the query process is the same regardless on if whether was issued from a Condition or an Action, the display in the IDM trace changes slightly based on which of the two 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. That happens because the trace shows a Rule's condition with their evaluation result on the same line, and to be able to evaluate this condition the IDM engine will need 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 IDM trace.
A Direct Command goes through variouspaths based on where it is issued and where it goes. It is meant to write information directly into either the source or the destination datastore. A Direct Command can be issued by an action within a rule, or from within XSLT code.
A Direct Command always has a <status> coming back as a result. It is easy to track its destination and path by the first line in the trace after the XDS <modify> is issued, as can be seen in the table below:
Direct Commands have 3 paths they can follow, just like queries. Let's now go over the diagrams and trace excerpts.
In our example below, a <modify> event is sent from eDirectory and is processed by the driver's Subscriber channel:
When the rule issues our command, the original event is suspended until the command finishes executing. Since a command is a change, this will also appear as a <modify> event, so be careful not to mix the original event with the Out of Band one.
When a rule (in our example, one from the Event Transformation Policy set) issues a Direct Command, the original <modify> event will stop processing until the <status> message resulting from our command comes back.
In the trace, the command will be preceded by the text "Direct command from policy". As we can see in the diagram below, the command is a <modify> event.
Here we have the whole command. In this example the driver is sending back changes to 2 attributes: "Object Class" and "DirXML-ADAliasName". Those changes are going to object "\PWFILTER-TREE\idm\users\estika".
Here our <modify> hit eDirectory, as is indicated in the trace by the text "Pumping XDS to eDirectory". This text will appear in an IDM trace every time any event or command reaches eDirectory.
Before seeing the <status> XDS piece, we can see the command's result in a "DirXML Log Event". It is important to realize that regardless of success or failure of this command, the original event will continue processing once the rule receives back the <status> document.
And as the <status> document get back to the rule that originated our Direct Command, we see the text "Direct command from policy result". Since we have such clear markers for the start and end of this Out of Band event, we could skip through it quickly by searching for the end marker. So whenever we see the starting marker - "Direct command from policy" - do a search for the ending marker - "Direct command from policy result" - to continue following the original event.
After the results of the <modify> are returned to the rule that issued it, the original event will continue being processed.
At this point we have finished reviewing a Direct Command that went straight into eDirectory. To keep things simple, there will be no trace excerpts in the following 2 diagram sets.
Now lets review a command going from inside a channel to the connected application. It will pass through the translation pieces. In this diagram, a modify event comes from eDirectory and is being processed by the policies and rules in the driver's Subscriber channel.
When a rule (in our example, one from the Event Transformation Policy set) issues a Direct Command, the original <modify> event will stop processing until the <status> message resulting from our command comes back.
In this case, however the <modify> issued by the rule will pass through the Outbound Association Reference Processor, Schema Mapping policy set and Output Transformation policy set. After passing those 3 pieces of the engine is that the <modify> will be handed over to the driver shim and finally to the connected application.
The connected application will then perform the action we sent, and return something back, be it a success or an error. The driver shim will then build the XDS document with a <status> element that contains the result. This XDS document will then pass through the Input Transformation policy set, Schema Mapping policy set and Inbound Association Reference Processor before being returned to the rule that issued the command.
Note that this is the only case where both the <modify> and its resulting <status> elements pass through any driver logic. This happens because IDM assumes that anything issued from within a driver channel is in eDirectory format. For the application to understand what is being requested the event needs to be converted to the application format. Conversely, any results from the application will need to be converted back to an eDirectory format before it can be processed.
And again, once the rule gets the result for its Direct Command, the original event continues processing.
Lastly, let's review a Direct Command from policy coming from inside the translation processor - Input Transformation policy set or Output Transformation policy set - and going directly to the application. In this diagram, a modify event came out of eDirectory and is being processed by the policies and rules in the driver's Subscriber channel.
When a rule (in our example, one from the Output Transformation Policy set) issues the command, the original <modify> event will stop processing until the command's results are returned.
In this case the <modify> is handed directly to the driver shim, and its results come straight from the driver shim to the rule that issued it.
Like last time, after the results of the command are returned to the rule that issued it, the original event will continue being processed by the driver.
At this point the reader should be familiar with both queries and direct commands. They both follow very similar paths in the engine, and these paths are different from the regular event flow. Keep in mind that a driver can have several instances of both types of events. Remembering the text displayed in the IDM trace when they start and stop can be very useful to track or skip them as needed.
Status messages are responses to events processed. They pass through the Translation Processor portion of the driver logic for normal events. They flow in the opposite direction as the event they report on, being processed after leaving the Translation Processor.
For each processed event we will have a corresponding "DirXML Log Event" audit message in the trace. Sometimes this message may appear before the XML first appears in the trace, sometimes afterward.
All status messages get sent to the auditing subsystem. That means they go to the Publisher/Subscriber status log attributes, and to Audit/Sentinel if the system is configured to send them events.
From the several different possible status that can be returned, 2 merit special attention:
Now lets go over some diagrams and tie them to traces showing how to follow status messages issued for events that were processed following the normal channel flow.
For this example, a <modify> event was sent via the Subscriber channel to the connected application. After the driver shim performs the action in the connected application, it will return a <status> message to the engine.
As we can see below, the resulting status was "success". Also, the status message matches the original event via its event-id XML attribute. That is how both the engine and the driver shim are able to match an outgoing event with the returned status message.
As can be seen in the next 2 diagrams, the <status> will then pass through the translation pieces and finally be processed by the engine. If the returned <status> is "success", "warning" or "error", the event will be removed from the TAO (cache) file.
For this example, a <modify> event was sent via the Publisher channel to eDirectory. After the IDM engine performs the action in eDirectory, it will return a <status> message to be sent to the driver shim.
Status messages coming in this direction show the "DirXML Log Event" message before displaying the <status> XDS. As we can see here, the resulting status was "success". Like in the previous case, a status message matches the original event via its event-id XML attribute.
As can be seen in the next 2 diagrams, the <status> will then pass through the translation pieces and finally be sent to the driver shim. In this example, the shim is running on a remote loader, so our trace will show us sending the <status> XDS to the remote loader. To see what the shim actually did in this case we would need the Remote Loader trace as well.
It is important to notice that we can get "DirXML Log Event" messages when an event is vetoed, or when the IDM engine encounters a runtime error while trying process an action or token. Those will be sent to the auditing subsystem, but will not generate a <status> XDS in the trace, since they are not the result of an event or command.
Also, there is one rule action that can issue its own status to be logged immediately in the auditing subsystem. Its details can be found at the IDM docs. At the time of this writing, this URL leads directly to it inside IDM 3.6.1 docs: https://www.netiq.com/documentation/idm36/policy_designer/data/dostatus.html
The IDM engine generally handles adding the association to the eDirectory object on its own. To help this process, any events coming from a connected system come with what should be used as the association value inside an <association> element. Most of the time there is no message in the IDM trace regarding when an object had its DirXML-Associations attribute modified by the IDM engine.
Now, in the case of an <add> event coming from eDirectory, if the shim executed it successfully in the connected application, it will return both the <status> message and an <add-association> command. This command will follow the same flow as the <status> message before being processed, as we will see in the diagrams below.
Below we can see the XDS for the <add-association> event. In this example we have the value "39dad26730eb37478932f7b9d505116f" coming back as the association to be added in eDirectory. 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 has to generate the destination DN, and does so by copying the source-DN of the original event.
In addition, there are also some XML elements (tags) coming back along with the association value, but they are not part of it. Notice that the <status> message coming back also has those XML elements. Those XML elements are operation properties. Operation properties are never sent to the shim. The IDM engine strips them from the source event before handing it over to the driver shim, and adds them back to the results of the event as we can see below.
Since operation properties do not get sent to the shim and are added back to the returned results. We can use operation properties to save information about the original event; information that will be used in the logic that processes those results.
The <add-association> event will then pass the translation processor, and right after that the destination object in eDirectory will have an association.
Note that add events coming from the publisher channel already have the association value in the event, and the IDM engine uses that to build the association during the creation of the object in eDirectory. As a result we will not see an <add-association> command.
Finally, there is one rule action that can forcefully add an association to an object in eDirectory. Its details can be found at the IDM docs. At the time of this writing, this URL leads directly to it inside IDM 3.6.1 docs: https://www.netiq.com/documentation/idm36/policy_designer/data/doaddassociation.html
Hopefully by now you are more familiar with IDM and will be able to understand most pieces of an IDM trace.
Support
Documentation
Learning Services
Partner Programs
-
MigrationDeletedUser
-
Cancel
-
Vote Up
0
Vote Down
-
-
Sign in to reply
-
More
-
Cancel
Comment-
MigrationDeletedUser
-
Cancel
-
Vote Up
0
Vote Down
-
-
Sign in to reply
-
More
-
Cancel
Children