Programmer's Guide:
Using Item Routing

Item routing is an eRoom feature that lets you set up simple workflows. The eRoom user interface lets you set up routing buttons for Folder Pages or Inbox Pages. These routing buttons appear below the attachments box on a page. Each routing button has a name and is associated with a destination folder in the same eRoom. To use a routing button, the user selects one or more items in the attachments box and clicks one of the routing buttons, which moves the selected items to the destination folder associated with the routing button.

Routing Sources and Targets

SAAPI exposes eRoom's routing features using the concepts of routing sources and routing targets. A Routing Source is a Folder Page or Inbox Page where routing can be initiated. Objects which can act as routing sources implement the IERURoutingSource interface. Routing Sources manage an ordered collection of Routing Targets, which are the SAAPI equivalent of the eRoom user interface routing buttons. Routing Targets, which implement IERURoutingTarget, store a name (the name that appears on the routing button), and a pointer to a destination Folder Page or Inbox Page.

Routing Targets are ordered by indices, with a beginning index value of 1. In the eRoom user interface, the routing buttons that correspond to the Routing Targets appear from left to right, in the same order as the indices of the Routing Targets in the collection.

Operations on Routing Targets, such as creating, deleting, modifying or reordering them, are not applied until you call the Update method in IERURoutingSource. To cancel changes in progress, use the Revert method. To remove all Routing Targets in a collection, use the Clear method.

Creating and Deleting Routing Targets

To create a Routing Target, first get the IERURoutingSource interface for a Folder Page or Inbox Page object. Next, call the CreateRoutingTarget method. When you create a Routing Target, you must supply the index of the position it should occupy in the collection. If you specify the index of an existing Routing Target, the new Routing Target returns the index you specify, and the Routing Target previously at that position, and all Routing targets to its right, are moved one position to the right. Supplying an index value of 0 for this method inserts the new target after the last existing target.

The following example creates a new Routing Target:

Dim SubmitFolder as IERUFolder
Dim ApprovedFolder as IERUFolder
Dim RoutingSource as IERURoutingSource
Dim NewTarget as IERURoutingTarget
Set SubmitFolder = MyRoom.GetItemByPath("/Expense Reports/New Reports");
Set ApprovedFolder = MyRoom.GetItemByPath("/Expense Reports/Approved");

Set RoutingSource = SubmitFolder
' Insert a new Routing Target in the first position
Set NewTarget = RoutingSource.CreateRoutingTarget(1, "Approve", ApprovedFolder)
RoutingSource.Update

To delete one or more Routing Targets, call the Delete method in IERURoutingTarget for each Routing Target object, then call Update on the Routing Source.

' Delete the first routing target on the page
RoutingSource.RoutingTargets(1).Delete
RoutingSource.Update

Enumerating, Modifying, and Reordering Routing Targets

To enumerate the collection of Routing Targets contained by a Routing Source, use the RoutingTargets property of IERURoutingSource:

Dim Target as IERURoutingTarget
For Each RoutingTarget in MyFolder.RoutingSource.RoutingTargets
' Do something
Debug.Print RoutingTarget.Name & " routes objects to " _
  & RoutingTarget.Target.PrincipalItem.Path
Next

To modify the name or target item of a Routing Target, use the Name or Target properties:

Dim MyTarget as IERURoutingTarget
Set MyTarget = MyRoutingSource.RoutingTargets(1)
MyTarget.Name = "Rejected"
MyTarget.Target = RejectionFolder
MyRoutingSource.Update

To reorder existing Routing Targets, use the SetTargetPosition method, specifying the Routing Target and the new position to give it.. The specified Routing Target is repositioned according to the same rules as CreateRoutingTarget.

' Swap the first and second routing targets
MyRoutingSource.SetTargetPosition(MyRoutingSource.RoutingTargets(2), 1)
MyRoutingSource.Update