Introduction to ILM Web Services

The ILM Web Service is based on two key standard protocols: WS-Transfer and WS-Enumeration.

When we describe the two protocols we must be careful to distinguish the “request” and the “response.” In our discussions, we assume that there is one client communicating with the ILM Service, and we assume that the ILM Service acts as a server. A request is a message sent from the client to the server. Each request in the context of ILM’s web services has an operation or action which the client is requesting the ILM Service to perform. The ILM service processes the request and then returns a response. A response is a message sent from the server to the client. Please read ILM’s official documentation to understand the very interesting and powerful workflows that get fired when the ILM Service processes requests. These workflows are an excellent extensibility point in ILM in their own right. We will discuss them after covering the web services.

The two protocols of interest, WS-Transfer and WS-Enumeration, specify the way in which a service performs operations – the verbs, so to speak. They provide operations like “Get”, “Delete”, and “Enumerate.” However, the protocols do not specify the way in which a service represents data – the nouns. In ILM we chose to represent ILM object instances as XML elements. Recall from our terminology above that an object has a collection of attributes. Let’s say that a Person object has attributes “first name,” “last name,” “display name.” The object instance may be represented in the protocols as such:

<Person>

<FirstName>Samantha</FirstName>

<LastName>Smith</LastName>

<DisplayName>Sam Smith</DisplayName>

</Person>

Please note that we say “Person” is an object and “FirstName”, “LastName”, and “DisplayName” are attributes. It is important to note that we do not represent attributes as XML Attributes but instead we represent them as child XML Elements. Also, please note that ILM “2” has a “flat” schema. That is, attributes may only be simple data types and thus you cannot nest data. For instance, the following cannot happen:

<Group>

<Members>

<Person/>

<Person/>

</Members>

</Group>

Instead, you must refer to other objects using the reference data type:

<Group>

<Member>[ReferenceId]</Member>

<Member>[ReferenceId]</Member>

</Group>

In a later topic (Topic #14) we’ll discuss how to get ILM’s schema for XML representations.

In addition to the default XML representations of ILM objects, we also created an extension to WS-Transfer for representing individual attributes.  We call the extension Transfer Extensions for Identity Management Operations or TEIMO for short. TEIMO is useful when a client only wants a specific subset of all attributes and wishes to save space on transferring attributes across the wire. A representation of an ILM object using the extensions may look like the following:

<PartialAttribute>

<AttributeType>FirstName</AttributeType>

<AttributeValue><rm:FirstName>Samantha</rm:FirstName></AttributeValue>

</PartialAttribute>

Please note that the representation using the extension depends on the object instance and attributes requested. In the previous example, it appears the client only requested the “FirstName” attribute of a Person object. A client consuming the extension response must know that the returned object instance is a Person whereas a client consuming the default response may look at the parent XML element to determine it’s a Person object. We will cover the extension in more depth in a later post (Topic #12).

In next week’s posts we’ll talk about the two standards and our extension in depth.  We encourage you to continue to read about and play with ILM “2” RC.