Microsoft Identity Integration Server 2003 Developer Reference

ma-connection

The <ma-connection> element stores information about the connection between the management agent and the connected directory. The management agent reports the server it connected to, in addition to any servers it failed to connect to. The management agent reports error information that can be helpful when debugging a problem.

Usage

<ma-connection/>

Attributes

None.

Child Elements

Element Description
<connection-result> A non-localized string giving the current status of the connection. The list of possible values are in the Remarks section.

Note  This value should be the same as the <connection-result> for the last <incident> in the <connection-log>.
<server> The name of the server the management agent connected to, if it successfully connected to a server. In most cases the name will be the DNS name. This element must be present or the user interface will not display the connection log.

For management agents where a list of preferred servers can be configured (that is, Active Directory or Exchange 5.5), the server name displayed in this element is informative. The server connection order is not defined in these instances.
<connection-log> A sequential list of the connection attempts against the servers, including cases where the connectivity dropped.

Parent Elements

Element
<step-details>

Child Element Sequence

The tree shows the ordering and number of child elements. Child elements in a Sequence must appear in the order given and child elements in a Choice are mutually exclusive. Sequences and Choices can be nested. Element names are followed by the minimum and maximum occurrences.

Sequence
	connection-result
<connection-result> A non-localized string giving the current status of the connection. The list of possible values are in the Remarks section.

Note  This value should be the same as the <connection-result> for the last <incident> in the <connection-log>.

 
 (Exactly 1)
	server
<server> The name of the server the management agent connected to, if it successfully connected to a server. In most cases the name will be the DNS name. This element must be present or the user interface will not display the connection log.

For management agents where a list of preferred servers can be configured (that is, Active Directory or Exchange 5.5), the server name displayed in this element is informative. The server connection order is not defined in these instances.

 
 (Minimum = 0; Maximum = 1)
	connection-log
<connection-log> A sequential list of the connection attempts against the servers, including cases where the connectivity dropped. 
 (Exactly 1)
Sequence

Remarks

The <ma-connection> element may appear for both import and export runs for call-based management agents.

The following lists the possible values for <connection-result>.

Value Description
successful-connection Successful connection to the connected directory.
failed-connection Connection to the connected directory has failed for a reason other than authentication. Generally, the connected directory error element will be present to assist in troubleshooting.
dropped-connection The connection between the management agent and the connected directory no longer exists. The management agent will try to reconnect to the connected directory in many cases. Generally, the connected directory error element will be present to assist in troubleshooting.
failed-authentication Authentication is not possible using the supplied credentials.
failed-permission Insufficient rights to access a container in the connected directory. This error is only expected for LDAP management agents which search different connected directory containers. Generally the connected directory error element will be present to assist in troubleshooting and the error literal will indicate the name of the container where the problem occurred.
failed-search A container or table search failed with an unexpected error. Generally, the connected directory error element will be present to assist in troubleshooting and the error literal will indicate the name of the container it had trouble searching.
warning-no-watermark The management agent cannot read the watermark when doing a full import. This error is only expected for the management agent for Sun ONE Directory Server 5.1 (formerly iPlanet Directory Server) when the initial management agent configuration was completed when the connected directory had change log enabled. Later when the connected directory change log is turned off, if the management agent configuration is not updated, this warning will occur when a full import is done.

Example Code

The following example shows a pseudo <ma-connection> section:

<ma-connection>
   <connection-result>a string from documented list</connection-result>
   <server> name of server </server>
   <connection-log>
	<incident>
		 <connection-result> string from list </connection-result>
		 <date> yyyy-mm-dd hh:mm:ss </date>
		 <server> name of server </server>
		 <cd-error>
			<error-code> some MA-specific number</error-code>
			<error-literal>some literal</error-literal>
			…
		 </cd-error>
	</incident>
	<incident>
		 <type> connection-attempt|connection-dropped </type>
		 <connection-result> string from list </connection-result>
		 <date> yyyy-mm-dd hh:mm:ss </date>
		 <server> name of server </server>
		 <cd-error>
			<error-code> some MA-specific number</error-code>
			<error-literal>some literal</error-literal>
			…
		 </cd-error>
	</incident>
	…
   </connection-log>
<ma-connection>

Element Information

Can be empty No