Constructing a KM Document Template and Provider

The following example shows you how to create a Guided Procedures (GP) template and provider to wrap a Knowledge Management (KM) Document business model defined in an SAP system. In essence, you create a template corresponding to the particular business object resource, create and register a provider and then instantiate a single aspect of the business object (BO) data to use it in GP.

Before you start, you need to:

Modeling the Template Structure

  1. Initialize the relevant managers and services.

    In our example, we have to instantiate the business object utility manager, the global service factory of the KM platform and the indexing service.

  1. Construct the type definition of the wrapper.
    1. Create a label and a structure.
    2. Add attributes to the structure.

      In the particular example, we need to add some document properties: name, description, date of creation, target URL and so on.

    3. Create labels for the newly-created attributes.
      Creating a Type Definition (Structure and Attributes) 
      importcom.sap.caf.eu.gp.structure.api.IGPAttributeInfo;
      importcom.sap.caf.eu.gp.structure.api.IGPLabel;
      importcom.sap.caf.eu.gp.structure.api.IGPStructure;
      importcom.sap.caf.eu.gp.structure.api.IGPStructureInfo;
      importcom.sap.caf.eu.gp.structure.api.GPStructureFactory;
       
      privateIGPLabel completeDocumentLabel;  
      privateIGPStructureInfo documentStructureInfo;
       
      privatestatic final String NAME_STRUCTURE_NAME = "Name";
      privatestatic final String NAME_STRUCTURE_CREATED = "Created";
      privatestatic final String NAME_STRUCTURE = "Documents";
      privatestatic final String NAMESPACE = "com.sap.bc.er.bo.provider.km.KMDocumentTemplate";
       
      privatestatic IGPLabel NAME_LABEL_STRUCTURE;
      privatestatic IGPLabel NAME_LABEL_STRUCTURE_DESCRIPTION;
       
      ...
      // create a label and structure for the document object
      completeDocumentLabel= GPStructureFactory.createLabel(NAME_STRUCTURE, NAMESPACE);
      documentStructureInfo=
               GPStructureFactory.getStructureInfo(completeDocumentLabel);
      documentStructureInfo.setMultiplicity(IGPStructureInfo.MULITIPLICITY_0_N);
              
      // add an attribute for structure name and set its multiplicity
      IGPAttributeInfostructureName = documentStructureInfo.addAttribute(
                                            NAME_STRUCTURE_NAME,
                                            NAMESPACE,
                                            IGPAttributeInfo.BASE_STRING);
      structureName.setMultiplicity(IGPAttributeInfo.MULITIPLICITY_1_1);
       
      // add an attribute for creation date and set its multiplicity
      IGPAttributeInfostructureCreated = documentStructureInfo.addAttribute(
                                            NAME_STRUCTURE_CREATED,
                                            NAMESPACE,
                                            IGPAttributeInfo.BASE_DATE);
      structureCreated.setMultiplicity(IGPAttributeInfo.MULITIPLICITY_1_1);
           
      // by analogy, add attributes for: description, created by, modified by, date // modified, target URL
       
      // create labels for all attributes specified above
      NAME_LABEL_STRUCTURE= GPStructureFactory.createLabel(
                                            NAME_STRUCTURE,
                                            NAMESPACE);
      NAME_LABEL_STRUCTURE_DESCRIPTION= GPStructureFactory.createLabel(
                                            NAME_STRUCTURE_DESCRIPTION,
                                            NAMESPACE);
      ...

Constructing a Restriction Locator and Template

  1. Implement a method that constructs a locator. The locator defines a restriction based on the type definition.

In the particular case, we create a locator that represents the whole structure of the business object. You may also create a locator that is a subset of the structure.

Creating An Attribute Locator 
importjava.util.Collection;
importjava.util.Iterator;
importcom.sap.caf.eu.gp.bo.utility.api.IGPBusinessObjectAttributeLocator;
 
privateIGPBusinessObjectAttributeLocator createTemplateLocator() throws GPInvocationException {
   IGPBusinessObjectAttributeLocator locator = managerUtility.createLocator(completeDocumentLabel);
     
   Collection attributes = documentStructureInfo.getAttributes();
   // for each attribute in the structure, add a locator
   for (Iterator iter = attributes.iterator(); iter.hasNext();) {
      IGPAttributeInfo attr = (IGPAttributeInfo) iter.next();
      locator.addLocator( attr.getLabel() );
   }    
   return locator;
}
  1. Create a template with the type definition and restrictions above. You should use the following interfaces: 
    • IGPBusinessObjectTemplateDetail
      - provides basic template data and the parameters specified in the locator
    • IGPBusinessObjectTemplateOverview
      - specifies only basic data (name and description)
      Creating A Template Detail and Overview 
      importcom.sap.caf.eu.gp.bo.template.api.IGPBusinessObjectTemplateDetail;
      importcom.sap.caf.eu.gp.bo.template.api.IGPBusinessObjectTemplateOverview;
       
      privatestatic final String NAME_TEMPLATE = "KM_Documents";
      privatestatic final String TITLE_TEMPLATE = "Documents";
      privatestatic final String DESCRIPTION_TEMPLATE = "documents";
       
      // create detailed template providing the document structure and locator
      IGPBusinessObjectTemplateDetail templateDetail = managerUtility.createTemplateDetail(NAME_TEMPLATE,
                                           TITLE_TEMPLATE,
                                           DESCRIPTION_TEMPLATE,
                                           documentStructureInfo,
                                           locator,
                                           true);
      // create a template overview
      IGPBusinessObjectTemplateOverview templateOverview = managerUtility.createTemplateOverview(NAME_TEMPLATE,
                                             TITLE_TEMPLATE,  
                                             DESCRIPTION_TEMPLATE,
                                             true);

The 
IGPBusinessObjectTemplateDetailIGPBusinessObjectTemplateOverview
and are based on a core implementation that only stores object references. This implementation is not mandatory. You should create your own implementation if it fits your needs better.

Depending on the locator you define, you may create more than one template based on the same business object model.

  1. Implement a template reader based on the GP interfaces 
    IGPPlainTemplateReaderIGPPatternTemplateReaderKMDocumentTemplateReader
    and . You can do this in a separate class, for example .

    In this implementation you can specify how to retrieve:

    • A template detail or overview enumeration
    • A template detail name enumeration

Implementing and Registering a BO Provider

  1. Implement your own business object provider using the IGPBusinessObjectProvider interface. The implementation must provide metadata for business object types, as well as for life cycle methods of the business object instances in the framework. You can do this in a separate class, for example 
    KMDocumentBOProvider
    .

    In the implementation you may include, for example:

    Implementing A Business Object Provider 
    importcom.sap.caf.eu.gp.bo.aspect.api.IGPBusinessObjectAspect;
    importcom.sap.security.api.IUser;
    importcom.sap.caf.eu.gp.bo.utility.api.IGPBusinessObjectEndpoint;
     
    // create an object aspect by specifying SAP system and locator restriction
    publicIGPBusinessObjectAspect readObjectAspect(
                                      IUser user,
                                      IGPBusinessObjectEndpoint endpoint,
                                      String name,
                                      String id,
                                      IGPBusinessObjectAttributeLocator locator)
       throws GPEngineException, GPInvocationException {
       KMDocumentTemplateHandler documentTemplateHandler = KMDocumentTemplateHandler.getInstance();
       return documentTemplateHandler.createObjectAspect(user,name,id,locator)
    }
     
    // create a template detail by specifying SAP system endpoint
    publicIGPBusinessObjectTemplateDetail readTemplateDetail(
                                      IUser user,
                                      IGPBusinessObjectEndpoint endpoint,
                                      String name)
       throws GPEngineException, GPInvocationException {
       KMDocumentTemplateHandler documentTemplateHandler = KMDocumentTemplateHandler.getInstance();
       return documentTemplateHandler.readTemplateDetail();
    }
    // create aspect enumeration, template overview, and so on...
  2. Register the business object provider:
    Registering A Business Object Provider 
    // instantiate the BO Provider
    KMDocumentBOProvider documentBOProvider =newKMDocumentBOProvider();
    // instantiate the business object registry
    IGPBusinessObjectProviderRegistryboProviderRegistry = GPBusinessObjectFactory.getProviderRegistry();
    // add the new provider
    boProviderRegistry.addProvider(documentBOProvider);

Creating and Instantiating a BO Aspect and Enumeration

  1. Implement a method that creates an object aspect by specifying a user, resource and locator. You can do this in the 
    KMDocumentTemplateHandler
    class, for example.

    The method should copy the attributes of the resource to the structure of the template instance (aspect).

    Creating A Business Object Aspect 
    importcom.sap.caf.eu.gp.bo.aspect.api.IGPBusinessObjectAspect;
    importcom.sapportals.wcm.repository.IResource;
    importcom.sapportals.wcm.repository.IResourceContext;
    importcom.sapportals.wcm.repository.ResourceContext;
    importcom.sapportals.wcm.repository.ResourceException;
    importcom.sapportals.wcm.repository.ResourceFactory;
    importcom.sap.caf.eu.gp.exception.api.GPEngineException;
    importcom.sap.security.api.IUser;
     
    publicIGPBusinessObjectAspect createObjectAspect(IUser user, String name, String id, IGPBusinessObjectAttributeLocator locator) throws GPEngineException, GPInvocationException {
       try {
          // retrieve the resource
          RID rid = RID.getRID(id); 
          IResourceContext resourceContext = new ResourceContext(user);    
          IResource resource = ResourceFactory.getInstance().getResource(rid, resourceContext);
                     
          // build the GP structure
          IGPStructure document = GPStructureFactory.getStructure(documentStructureInfo);       
          // set the attribute values
          EnumerationlocatorEnum = locator.createLocatorEnumeration();
          while (locatorEnum.hasMoreElements()) {
             IGPBusinessObjectAttributeLocator   attrLocator = (IGPBusinessObjectAttributeLocator) locatorEnum.nextElement();
             if ( attrLocator.getLabel().equals( NAME_LABEL_STRUCTURE_NAME )) {
                document.setAttributeValue( NAME_STRUCTURE_NAME,
                                            NAMESPACE,
                                            resource.getName());
             } else   if ( attrLocator.getLabel().equals( NAME_LABEL_STRUCTURE_DESCRIPTION )) {
                document.setAttributeValue( NAME_STRUCTURE_DESCRIPTION,
                                            NAMESPACE,
                                            resource.getDescription());
             } else if ( attrLocator.getLabel().equals( NAME_LABEL_STRUCTURE_CREATED )) {
                document.setAttributeValue( NAME_STRUCTURE_CREATED,
                                            NAMESPACE,
                                            resource.getCreationDate());
             }
             // by analogy, set all other attribute values
             ...
          }
          return managerUtility.createAspect(id, document);
       } catch (ResourceException e) {
          throw new GPEngineException(LOCATION, e);
       }
    }
  1. Instantiate a business object aspect through the 
    KMDocumentBOProvider
    : 
     
    IGPBusinessObjectAspectboAspect = documentBOProvider.readObjectAspect(user, endpoint, name, id, locator);
    		 
 
  1. Implement a method that creates an object aspect enumeration by specifying a user, structure restriction and locator. You can do this in the 
    KMDocumentTemplateHandler
    class, for example.
    Creating An Object Aspect Enumeration 
    importjava.util.Enumeration;
    importjava.util.Vector;
    importcom.sapportals.wcm.service.indexmanagement.retrieval.search.IFederatedSearch;
    importcom.sapportals.wcm.service.indexmanagement.IWcmIndexConst;
    importcom.sapportals.wcm.WcmException;
    importcom.sapportals.portal.security.usermanagement.UserManagementException;
     
    publicEnumeration createObjectAspectEnumeration(
                                     IUseruser,
                                     Stringname,
                                     IGPStructurerestriction,
                                     IGPBusinessObjectAttributeLocatorlocator)
    throwsGPEngineException, GPInvocationException {
       try {
          Vector objectAspects = new Vector();
          IFederatedSearch fedSearch = (IFederatedSearch) indexService.getObjectInstance( IWcmIndexConst.FEDERATED_SEARCH_INSTANCE );     
          ...
          // build the query based on the BO restriction structure      
          // retrieve results from the search
          // for each resource found, build the GP structure and set attributes
          // add the new development object to the vector
          objectAspects.add(managerUtility.createAspect( resource.getRID().toString(), document));
          return objectAspects.elements();
       } catch (WcmException e) {
          throw new GPEngineException( LOCATION, e );
       } catch (UserManagementException e) {
          throw new GPEngineException( LOCATION, e );
       }
    1. }
      1. Retrieve an object aspect enumeration through the 
        KMDocumentBOProvider
        : 
         
        EnumerationboAspectEnumeration = documentBOProvider.readObjectAspectEnumeration(user, endpoint, name, restriction, locator);

Result

Once you have implemented a provider and constructed a template, you can use it in GP. You need to create a callable object and add to it a parameter that is a reference to the data retrieved from the business object model.

For this purpose, you must explicitly create the structure type definition of the new parameter. It should be equivalent to the type definition of the template (described above) based on the restriction of the locator.

For more information on how to add parameters to a callable object, refer to Creating Callable Objects .

Consequently, for each instantiation of the callable object, you should create an aspect of the business object and fill in the actual values into this structure.