Dynamic value assistance using DFS

Continuing my collaboration with John Sweeney (or his collaboration with me), today we’ll examine the DFS Schema service and do so in .NET as a direct-to-WSDL consumer. This tutorial builds upon a previous tutorial; so, if you’re not already familiar with it, please read this post and play with this sample. You’ll also need and be familiar with using Documentum Administrator (DA) and Documentum Composer 6.5 SP1.

Thanks to John for doing the legwork in this tutorial and for allowing me to share it all with you here. (Although, I’d really like to see John blog about this directly; he has a lot to share.)

Not only can the DFS Schema service return value-assist values, it also supports dynamic value assistance, including the handling of dependencies (e.g. one attribute value-assist dynamically built based on the value of another attribute).

This tutorial demonstrates how to use the DFS Schema service to perform dynamic value-assist tasks. Knowledge of Documentum Administrator, Documentum Composer 6.5 SP1, DFS 6.5 SP1, Visual Studio 2008 and WSDL-based consumption of DFS with .NET is assumed.

Before we begin, we’ll need to create users, groups and an object type to use as test data.

Step 1 – Create users and groups (to be performed with Documentum Administrator)

1. Create three groups named writers, reviewers and publishers in your repository.

2. Create six users. Name them appropriately, but for this tutorial, they will be referred to as User1–6. Put the users in the new groups, as specified in the following chart:

  Group   Members
  writers   User1, User2
  reviewers   User3, User4
  publishers   User5, User6

Step 2 – Create a new object type (to be performed with Documentum Composer 6.5 SP1)

1. Open Documentum Composer and create a new project.

2. Add a new type called kb_document with a supertype of dm_document.

3. Add a new attribute to the type named document_state (as shown in the following image).

4. Expand the document_state attribute and select Value mapping.

5. In the Conditional Assistance section, click New…

6. Add Draft,Review,Publish as values of Fixed List (as shown in the following image) and click OK.

Your Conditional Assistance section should now look like this:

7. Add another new attribute to the type named assigned_to as shown in the following image.

8. Expand the assigned_to attribute and select Value mapping.

9. In the Conditional Assistance section, click New…

10. Add the following query:

select users_names from dm_group where group_name = 'writers'

Set the other fields (as shown in the following image).

The value-assist list will be populated with users who are members of the writers group by default, when document_state does not have a value of Review or Publish.

11. In the Conditional Assistance section, click New…

12. Add the following query:

select users_names from dm_group where group_name = 'reviewers'

Set the other fields (as shown in the following image).

The value in the Expression field will cause the value-assist list to be populated with users who are members of the reviewers group, but only when document_state has a value of "Review."

13. In the Conditional Assistance section, click New…

14. Add the following query:

select users_names from dm_group where group_name = 'publishers'

Set the other fields (as shown in the following image).

The value in the Expression field will cause the value-assist list to be populated with users who are members of the publishers group, but only when document_state has a value of "Publish."

Your Conditional Assistance section should now look like the following:

15. Install the Documentum project to your repository.

Step 3 – Retrieve the value-assist list (using C# and the .NET Framework 3.0 or higher)

Note: the ServiceContextHeader class used in this tutorial comes from this prior sample, as noted above.

The following code snippet will return group members in the ValueAssist Values list. A PropertySet is created for document_state. The value of document_state will alter the dynamic-assist values for the assigned_to property.

// Get a reference to the DFS Schema service
SchemaServicePortClient schemaService =  
    new SchemaServicePortClient("SchemaServicePort"); 

StringProperty sp = new StringProperty();
sp.name = "document_state"; 
// assigned_to will have different dynamic-assist values, 
// depending upon the value set here
sp.Value = "Publish"; // or Review or Draft

// Create a PropertySet for document_state, which assigned_to depends upon
PropertySet ps = new PropertySet();
ps.Properties = new Property[1];
ps.Properties[0] = sp; 

using (OperationContextScope scope = 
           new OperationContextScope(schemaService.InnerChannel))
{
    // Add the ServiceContextHeader info to the outgoing request
    OperationContext.Current.OutgoingMessageHeaders.Add(
        new ServiceContextHeader(repositoryName, userName, password)); 

    // Get the values for the assigned_to property
    ValueAssist valueAssist = schemaService.getDynamicAssistValues(
        repositoryName, "DEFAULT", "kb_document", "assigned_to", ps, null); 

    // Display the values
    if (valueAssist != null || valueAssist.Values != null)
    {
        foreach (string s in valueAssist.Values)
            MessageBox.Show(s, "Value Assist Value");
    }
}

The following table shows the expected results:

  document_state value   assigned_to values
  Draft   User1, User2
  Review   User3, User4
  Publish   User5, User6

It is worth noting that if you execute SchemaService.getTypeInfo for kb_document, and examine the assigned_to property, you can determine that the property has dependencies. The returned TypeInfo.PropertyInfos[n].Dependencies will contain an entry for document_state. You can check this beforehand as a way of determining if setting one property (document_state) should trigger a refresh of the value list (calling getDynamicAssistValues again). This is very useful for a picklist property page where the values of one list depend on the value of another.

Here endeth the lesson… :-)

Update 2/6/2009: In order for you to spend more time understanding dynamic value assistance with DFS, I’ve uploaded a Visual Studio project to EDN here. Enjoy.

-Craig
http://craigrandall.net/
@craigsmusings