Show TOC Start of Content Area

This graphic is explained in the accompanying text Constructing a KM Document Template and Provider  Locate the document in its SAP Library structure

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.

Caution

You should have in mind that implementation depends mainly on the business object resource you want to expose.

Before you start, you need to:

●      Familiarize yourself with the basic steps in exposing a business object data in GP. For more information, see Exposing Business Object Data in the GP Context.

●      Set up your project in NetWeaver Developer Studio. For more information, see Setting Up Your Project.

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.

Note

You can do this in the initialize() method of your handling class, for example KMDocumentTemplateHandler.

Initializing Services

import com.sap.caf.eu.gp.bo.api.IGPBusinessObjectUtilityManager;

import com.sap.caf.eu.gp.bo.api.GPBusinessObjectFactory;

import com.sapportals.wcm.service.IServiceFactory;

import com.sapportals.wcm.service.IServiceTypesConst;

import com.sapportals.wcm.service.ServiceFactory;

import com.sapportals.wcm.service.indexmanagement.IIndexService;

import com.sap.caf.eu.gp.exception.api.GPInvocationException;

import com.sapportals.wcm.WcmException;

 

private IGPBusinessObjectUtilityManager managerUtility;

private IIndexService indexService;

 

private void initialize() throws WcmException, GPInvocationException{

 

   // instantiate the utility manager

   managerUtility = GPBusinessObjectFactory.getUtilityManager();

   // Retrieve the global service Factory of the KM Platform

   IServiceFactory serviceFactory = ServiceFactory.getInstance();

   // Retrieve the Index Service

   indexService = (IIndexService) serviceFactory.getService(IServiceTypesConst.INDEX_SERVICE);

   ...

}

 

       2.      Construct the type definition of the wrapper.

                            a.      Create a label and a structure.

                            b.      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.

                            c.      Create labels for the newly-created attributes.

Creating a Type Definition (Structure and Attributes)

import com.sap.caf.eu.gp.structure.api.IGPAttributeInfo;

import com.sap.caf.eu.gp.structure.api.IGPLabel;

import com.sap.caf.eu.gp.structure.api.IGPStructure;

import com.sap.caf.eu.gp.structure.api.IGPStructureInfo;

import com.sap.caf.eu.gp.structure.api.GPStructureFactory;

 

private IGPLabel completeDocumentLabel;  

private IGPStructureInfo documentStructureInfo;

 

private static final String NAME_STRUCTURE_NAME = "Name";

private static final String NAME_STRUCTURE_CREATED = "Created";

private static final String NAME_STRUCTURE = "Documents";

private static final String NAMESPACE = "com.sap.bc.er.bo.provider.km.KMDocumentTemplate";

 

private static IGPLabel NAME_LABEL_STRUCTURE;

private static 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

IGPAttributeInfo structureName = 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

IGPAttributeInfo structureCreated = 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.

Note

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

import java.util.Collection;

import java.util.Iterator;

import com.sap.caf.eu.gp.bo.utility.api.IGPBusinessObjectAttributeLocator;

 

private IGPBusinessObjectAttributeLocator 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;

}

 

       2.      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

import com.sap.caf.eu.gp.bo.template.api.IGPBusinessObjectTemplateDetail;

import com.sap.caf.eu.gp.bo.template.api.IGPBusinessObjectTemplateOverview;

 

private static final String NAME_TEMPLATE = "KM_Documents";

private static final String TITLE_TEMPLATE = "Documents";

private static 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);

Recommendation

The IGPBusinessObjectTemplateDetail and IGPBusinessObjectTemplateOverview 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.

Note

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

       3.      Implement a template reader based on the GP interfaces IGPPlainTemplateReader and IGPPatternTemplateReader. You can do this in a separate class, for example KMDocumentTemplateReader.

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

import com.sap.caf.eu.gp.bo.aspect.api.IGPBusinessObjectAspect;

import com.sap.security.api.IUser;

import com.sap.caf.eu.gp.bo.utility.api.IGPBusinessObjectEndpoint;

 

// create an object aspect by specifying SAP system and locator restriction

public IGPBusinessObjectAspect 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

public IGPBusinessObjectTemplateDetail 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...

Note

The createObjectAspect() method is implemented in step 1 in the procedure below.

       2.      Register the business object provider:

Registering A Business Object Provider

// instantiate the BO Provider

KMDocumentBOProvider documentBOProvider = new KMDocumentBOProvider();

// instantiate the business object registry

IGPBusinessObjectProviderRegistry boProviderRegistry = 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

import com.sap.caf.eu.gp.bo.aspect.api.IGPBusinessObjectAspect;

import com.sapportals.wcm.repository.IResource;

import com.sapportals.wcm.repository.IResourceContext;

import com.sapportals.wcm.repository.ResourceContext;

import com.sapportals.wcm.repository.ResourceException;

import com.sapportals.wcm.repository.ResourceFactory;

import com.sap.caf.eu.gp.exception.api.GPEngineException;

import com.sap.security.api.IUser;

 

public IGPBusinessObjectAspect 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

      Enumeration locatorEnum = 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);

   }

}

 

       2.      Instantiate a business object aspect through the KMDocumentBOProvider:

 

IGPBusinessObjectAspect boAspect = documentBOProvider.readObjectAspect(user, endpoint, name, id, locator);

 

 

       3.      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

import java.util.Enumeration;

import java.util.Vector;

import com.sapportals.wcm.service.indexmanagement.retrieval.search.IFederatedSearch;

import com.sapportals.wcm.service.indexmanagement.IWcmIndexConst;

import com.sapportals.wcm.WcmException;

import com.sapportals.portal.security.usermanagement.UserManagementException;

 

public Enumeration createObjectAspectEnumeration(

                                 IUser user,

                                 String name,

                                 IGPStructure restriction,

                                 IGPBusinessObjectAttributeLocator locator)

throws GPEngineException, 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 );

   }

}

 

       4.      Retrieve an object aspect enumeration through the KMDocumentBOProvider:

 

Enumeration boAspectEnumeration = 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.

End of Content Area