Eran Kampf
Eran Kampf
4 min read

Duet Behind the Scenes: Bounded Items

Binding to Outlook item (Mail, Task, Contact, etc.) is one of the main features that differentiates Duet’s user experience from other OBA products such as Snap-Ins, Extensio etc. What exactly are bounded items? and how is binding implemented?

What are Bounded Items?

A bounded item is a simple Outlook item, which can be an email, appointment, contact etc. with an attached schema that defines it as a specific presentation object (presentation objects discussed in the previous post) and carries the business data related to that object. We call this a payload.

The payload is an encrypted XML containing the presentation object reference and business data mentioned above and attached to the Outlook item as a custom property.

For example, a payload attached to a contact item that represents a CRM customer would probably contain data such as the customer’s ID, company he works at, etc.

Before we examine how this payload is built, maintained and displayed to the user we first have to take a step back and understand how its schema defined. Or to be more accurate, how we define a presentation object.

Bound Item Definitions

If you remember the metadata illustration from the first post, one of the key parts in a presentation object’s metadata definition is its Data Definitions as displayed in the illustration:

image

A presentation item’s Data Definitions contain the following information:

  1. Presentation object name- A unique resource name identifying this presentation object type
  2. Outlook definitions -Specifies the Outlook item type this objects relates to and its default folder location.
  3. Synchronization behavior – Type of synchronization used to synchronize to the backend.
  4. Business Data Schema – A schema for the business data this object carries with it
  5. Data Mapping to\from Outlook Properties – A set of mappings that define how the Outlook item’s default fields (Such as Subject, Location, Start\End Time) map to\from values in the item’s business data.

If we look at a definition for a CRM Customer object again, its name would be something like “urn:sap:duet:crm:customer” and its business data would probably contain name and contact information (address, phone numbers). This data would be mapped to the relevant Outlook fields (phone numbers to Contact item phone properties, address to the Contact item address property etc.) so that when the user edits the object the changes will be propagated back to the business data payload (and eventually to the backend).

This data definition, termed Bound Item Definition looks like this:

<BoundItemDefinition Name="urn:sap:duet:crm:customer" xmlns="http://schemas.microsoft.com/OBA/2005/BoundItemDefinition">
  <Outlook DefaultFolder="CRM Contacts" MessageClass="IPM.Contact" />
  <Synchronization>
    <Behavior>Always</Behavior>
  </Synchronization>
  <Properties>
    <Property Name="Crm.Customer.FirstName" Type="String">
      <Behavior>OutlookToXml</Behavior>
      <Outlook Name="FirstName" />
      <Xml XPath="/ns0:CRMContact/Name" Namespaces="ns0='urn:sap:duet:crm:customer'" />
    </Property> <Property Name="Crm.Customer.LastName" Type="String">
      <Behavior>OutlookToXml</Behavior>
      <Outlook Name="LastName" />
      <Xml XPath="/ns0:CRMContact/ns0:LastName" Namespaces="ns0='urn:sap:duet:crm:customer'" />
    </Property>
    ...
  </Properties>
  <XmlTemplate>
    <s0:CRMContact xmlns:s0="urn:sap:duet:crm:customer">
      <s0:FirstName>String</s0:FirstName> <s0:LastName>String</s0:LastName> <s0:FileAsName>String</s0:FileAsName> <s0:Comapany>String</s0:Comapany> <s0:JobTitle>String</s0:JobTitle>  ...
    </s0:CRMContact>
  </XmlTemplate>
</BoundItemDefinition>

Binding an Item

The process of binding an item is where we take a regular Outlook item and mark it has a presentation object. Basically we’re taking a regular Outlook item and marking it as a presentation object. The item’s behavior and schema for the business data attached to it are according to the presentation object’s data definitions. When binding an item the Duet platform adds 3 custom properties to the item:

  1. BoundItemId – A unique ID to represent this bounded item.
  2. BoundItemType – The type of presentation object that the item represents
  3. BoundData – The business data the item carries (payload).

In our example, a bounded IPM.Contact object representing a customer would have urn:sap:duet:crm:customerIn as its BoundItemType and the following XML as its BoundData:

<s0:CRMContact xmlns:s0="urn:sap:duet:crm:customer">
  <s0:FirstName>Eran</s0:FirstName>
  <s0:LastName>Kampf</s0:LastName>
  <s0:FileAsName>Kampf, Eran</s0:FileAsName>
  <s0:Comapany>SAP Labs Israel</s0:Comapany>
  ...
</s0:CRMContact>

The values in the BoundData are populated according to the data mapping rules specified in the bound item definition for our customer object.

Security Considerations

The BoundData can contain confidential information. Once retrieved from the backend systems we would like to limit access to it specifically to the user who got the information. Otherwise, sensitive information which is part of the user’s item can leek if, for example the user forwards the item to someone or if an IT administrator (or anyone else who has access to the user’s mailbox) looks at the item.

We use DPAPI to encrypt the BoundData using the current user’s credentials so that only the Duet user who received the data can decrypt it. This way, even if someone else gets hold of the BoundData value he has no way to decipher it…

This also means that when forwarding a Duet item the receiving side will not have Duet information available and will see the item as a regular unbounded Outlook item. I’ll discuss how forwarding of bounded items is performed in a future post dedicated to forwarding…