Entity Configuration Business Service Control Framework

Configuration The configuration is stored in the file confbsc.xml, inside the entityViews element. New Entities can be created by adding new Entity definitions to that configuration, or behaviour of existing Entities can be changed. In this release, we support creation of new Entities and customization of Entities based on tModels TM. The following example shows a commented configuration of a Categorization entity, derived from a tModel. It corresponds to a taxonomy tModel used by the Registry. The individual parts of the configuration will be described below Page 577 Configuration Example 25. Definition of an XML document -- Definition of a new entity, based on a TModel TM. We specify an icon, a localizable name caption and localizable description. -- entity entityId=xsd type=TM icon=xsd.gif captionKey=bsc.entityViews_xsd_caption descriptionKey=bsc.entityViews_xsd_description -- Categorization together with type attribute above tells the framework how to identify this type of entities -- categorization keyedReference tModelKey=uddi:uddi.org:resource:type keyValue=xsd categorization -- Views tells the BSC which components and tasks should be used to display information about the entity or to manipulate with the entity -- views view type=list task=browseresourcesxsds parameter paramName=entityId paramValue={entityId} parameter paramName=editableMode paramValue={editableMode} view view type=listMy task=browseresourcesxsds parameter paramName=entityId paramValue={entityId} parameter paramName=editableMode paramValue={editableMode} parameter paramName=filterMyEntities paramValue=true view view type=create task=publishresourcesxsdscreateXSDResource parameter paramName=requiredCategories paramValue={categoryBag.KeyedReferenceArrayList} view view type=edit task=publishresourcesxsdseditXSDResource parameter paramName=tModelKey paramValue={entityKey} view view type=find task=searchresourcesschemas parameter paramName=editableMode paramValue={editableMode} view view type=searchResults component=resourcesXsdResults parameter paramName=query paramValue={query} parameter paramName=var paramValue={var} view view type=detail task=browsexsdDetail parameter paramName=tModelKey paramValue={entityKey} view view type=treeContextMenu component=contextMenu_xsdList view type=pageMenu task=catalogxsdMenu view component=xsdsSubscriptionView type=subscriptionChangeView view type=delete task=publishresourcesxsdsunpublishXSDResource parameter paramName=tModelKey paramValue={entityKey} Page 578 Configuration view views -- References defines how to make associations with this type of entity, what keyedReferences to use and who can make the association -- references -- One or more references, leading to this entity type. -- reference refName=schema captionKey=bsc.entityViews_xsd_refSchema_caption descriptionKey=bsc.entityViews_xsd_refSchema_description -- originTypes may be either entityIds, or UDDI entity types. No origin means all entities match originTypexmloriginType -- originTypexmloriginType keyedReference tModelKey=uddi:uddi.org:resource:reference keyName=definition reference reference refName=schemaOfSource captionKey=bsc.entityViews_xsd_refSchemaOfSource_caption descriptionKey=bsc.entityViews_xsd_refSchemaOfSource_description originTypexsltoriginType keyedReference tModelKey=uddi:uddi.org:resource:reference keyName=transformation-source reference reference refName=schemaOfDestination captionKey=bsc.entityViews_xsd_refSchemaOfDestination_caption descriptionKey=bsc.entityViews_xsd_refSchemaOfDestination_description originTypexsltoriginType keyedReference tModelKey=uddi:uddi.org:resource:reference keyName=transformation-destination reference reference refName=dependencyOnXSD captionKey=bsc.entityViews_dependencyOnXSD_caption descriptionKey=bsc.entityViews_dependencyOnXSD_description keyedReference tModelKey=uddi:systinet.com:dependency keyName=tModel reference references entity Entity Definition The Business Service Control Entity definition element introduces a new Entity recognized by the Business Service Control. The entity has an id, a title, an optional description and an icon. Page 579 Entity Definition Table 92. Entity definition attributes Required Description Attribute Yes An unique identifier that identifies this entity type. It should start with lowercase letter, and use only alphanumeric characters. entityId Yes This string serves as a key to the resource bundle, which stores to actual string used for the entity caption. See below regarding handling of singular and plural forms. captionKey No The key into the resource bundle, for the string that provides a short decription of the entity type. The description may contain HTML markup. descriptionKey When the Business Service Control needs to print a noun, that describes a collection of entities, it uses the string denoted by the captionKey resource bundle key. In the case the Business Service Control needs to print a singular noun, which stands for the entity type, it uses the key with _single suffix. All strings are taken from the resource bundle srcBSCMessages.properties , unless specified otherwise by the captionKey attribute see Section 3.8.1, Business Service Control Localization for details. The icon attribute is relative to directory webrootgfxtree. The icon is displayed in navigation trees to provide an unique visual appearance for the entity type. Example 26. Definition of a XML document -- The XML Document entity is derived from UDDI TModel. The definition also defines what name and icon should display for this type of data. -- entity entityId=xml type=TM icon=xml.gif captionKey=bsc.entityViews_xml_caption descriptionKey=bsc.entityViews_xml_description categorization -- XML Documents are characterized by a keyedReference for the uddi:uddi.org:resource:type taxonomy, with xml value. -- keyedReference tModelKey=uddi:uddi.org:resource:type keyValue=xml categorization entity Entity Categorization As noted in the overview, an UDDI data structure may be used to represent several abstractions - Entities. An Entity is characterized by two things: • basic UDDI type • categorization The basic UDDI type is one of: BE Business Entity Page 580 Entity Categorization BS Business Service BT Binding Template TM tModel The UDDI entity needs to be of the specified type in order to be recognized as the particular BSC Entity. In addition, you may specify mandatory keyedReferences, which the UDDI entity needs to have. The BSC Entity that has most keyedReferences matching the UDDI data will be selected. If there remains a choice, one is chosen at random. Zero or more keyedReferences can be specified. When no categorization is present, all appropriate UDDI structures match, regardless of their contents. When specified, each keyedReference entry can have the following attributes: Table 93. keyedReferenceAttributes Required Description Attribute yes A tModel key of the taxonomy used for categorization tModelKey no The keyName of the required keyedReference. If the attribute is omitted, keyNames are ignored. keyName no The keyValue of the required keyedReference. If the attribute is omitted, keyValues are ignored any matches. keyValue Page 581 Entity Categorization Example 27. Definition of a XML document -- This is a definition of a WSDL service. It is derived from the Business Service UDDI structure BS -- entity entityId=service type=BS icon=service.gif captionKey=bsc.entityViews_service_caption descriptionKey=bsc.entityViews_service_description categorization -- A WSDL service is characterized by having the uddi:uddi.org:wsdl:types category with service value, according to the WSDL to UDDI mapping Technical Notes -- keyedReference tModelKey=uddi:uddi.org:wsdl:types keyValue=service categorization entity -- This is a specification of a XSL Transformation entity. It is derived from a TModel UDDI structure TM -- entity entityId=xslt type=TM icon=xslt.gif captionKey=bsc.entityViews_xslt_caption descriptionKey=bsc.entityViews_xslt_description categorization -- The XSLT resource is characterized by the resource:type category which must have the xslt value, according to the proposed mapping Technical Note. -- keyedReference tModelKey=uddi:uddi.org:resource:type keyValue=xslt categorization entity Note There must be an uncategorized Entity defined for each of the UDDI structures, to serve as a catch-all for data that does not match any specific entity. The default Business Service Control configuration provides such Entities. Entity Views A View stands for a visualization of some aspect, or an abstract task, that is available for the entity. Some tasks may or may not be available, depending on whether an appropriate View is available for the rendered data. The Business Service Control implementation uses View definitions to lookup tasks and components, which are appropriate for handling the data presentation, or to perform operations on the data. A View is identified by a viewType. There can be at most one View for the particular viewType defined for the given entity. If such View is not defined, the Entity does not support the relevant visualization, or operation. The following table summarizes the supported viewTypes. Page 582 Entity Views Table 94. Predefined View types Required Description viewType No Embeddable component, that provides a search results for a given type of Entity. The Component should accept a query, and render the matching results on the screen. These Components are used in Reports, Quicksearch etc. searchResults No Task for editing a specific entity. The task accepts an entity key, and produces a screen form, wizard suitable for editing the entity. edit Yes Provides a task that displays detailed information for an entity. The task accepts the key of the entity to display. This View is mandatory to ensure that information about any entity can be reached. detail No Provides a searching task for the entity. The task is supposed to display a form and results of the search. find No Provides a Component to render subscription results for the particular entity type. The Component accepts the list of subscriptions to filter and display as a parameter subscriptionChangeView No Provides a Task with a Wizard or a form to create a new entity. The Task may process a parameter that identifies a parent structure where the new entity should be stored. create No Provides a Task for deleting the entity. The Task should accept a single key, or a collection of keys as a parameter, and it should handle deletion of a single or several entities. delete No Provides a task, which displays all entities of the particular type. The Task accepts a parameter, which turns edit functions onoff. These tasks should not require login. list No Provides a task, which displays all entities of the type owned by the logged-in user; otherwise, the function is just as with the list view. listMy No Provides a context menu for the Catalog tree. If missing, there will not be a context menu for the entity. treeContextMenu No Provides a Task that displays the entitys menu when the Entity is selected in the Catalog tree. If missing, the entity will not be shown in Catalog at all. pageMenu Each view can take some parameters. The parameters are passed by the code that invokes the View, and the framework passes them to the Views implementation component or task. The caller must be able to use the same parameters for invoking a View on different Entity types to remain independent of implementation details of individual Entities. To achieve this, the View definition not only contains parameter names, but also uses a simple mechanism to translate Views parameters to the implementation Component or Task parameters. This is achieved by allowing JSTL EL expressions as parameter values. The parameter definition in the View configuration specifies the name of the parameter passed to the implementation Component or Task paramName and EL expression to construct the value from the parameters passed by the caller paramValue. Those EL expressions are evaluated in the context of a special component used to invoke Views, so all parameters, request and session variables can be used to create the resulting value. Page 583 Entity Views The following example shows a definition for the Detail View for the Service entity. Note how the general entityKey parameter, which is applicable to all Detail Views, translates to a specific parameter of the particular implementation Task. Example 28. Classification of data in Java -- We declare a view of type detail, which is implemented by the Task browseserviceDetail -- view type=detail task=browseserviceDetail -- The implementation task accepts serviceKey parameter, we have to adapt the Views parameter to the custom name. -- parameter paramName=serviceKey paramValue={entityKey} view References Entities may have some relationships or associations between them. An association between A and B is established by creating a keyedReference, with the tModelKey that identifies the type of the relationship and a keyValue which holds the entityKey of the other side of the association. Only directed associations between two UDDI entities are supported, however because of Registry query capabilities, it is also possible to navigate in the reverse direction of an association - and Business Service Control supports that with the Referenced By action. A reference is defined by: refName An identifier that identifies this reference. keyedReference A keyedReference which is used to represent the association in the Registry. The tModelKey is mandatory, the keyName tag is optional: if present, the keyedReference must have such keyName value in order to form this reference. originType Zero or more originTypes can be specified to restrict which Entities can establish associations. If no originType is present, the association can originate at any type of entity. When originType is present, only the listed entity types can serve as origins for the association. Multiple originType values are supported. The permitted values are the values of the id Entity definition attribute. In addition, values that represent the UDDI structure types are permitted BE, BS, BT, TM. When an UDDI structure type is specified, the Reference can originate from any entity derived from that UDDI structure. Note The permitted origins should be a subset of the relationship Taxonomy compatibility list. If you permit an originType, whose UDDI structure is incompatible with the relationship Taxonomy, you will not be able to add such references associations to entities. The Business Service Control presents References to other entities on Detail pages of entities, and provides Referenced By action for an entity to discover where the entity is referenced from. References defined in this configuration can also be added by the Business Service Control user using the Add Reference Wizard. Page 584 References The following example shows how Policies can be associated with an arbitrary Entity. We define a reference to the policy entities, with a certain tModelKey according to the WS-Policy specification, and we do not restrict who can use such a reference. Example 29. Policy Entity -- Definition of the Policy entity -- entity entityId=policy type=TM icon=policy.gif captionKey=bsc.entityViews_policies descriptionKey=bsc.entityViews_policies -- Some categorization that identifies the entity -- categorization keyedReference tModelKey=uddi:schemas.xmlsoap.org:policytypes:2003_03 keyValue=policy keyName=policy categorization views -- List of views, not important for this example -- ... views references -- We define a Reference named refLocalPolicy, with a localizable caption and description. originTypes specifier is missing, so this Reference can originate from any type of Entity. -- reference refName=refLocalPolicy captionKey=bsc.entityViews_policy_refLocalPolicy_caption descriptionKey=bsc.entityViews_policy_refLocalPolicy_description -- This Reference will be stored using a keyedReference, that have tModelKey set to uddi:schemas.xmlsoap.org:localpolicyreference:2003_03 and keyName set to Associated Policy -- keyedReference tModelKey=uddi:schemas.xmlsoap.org:localpolicyreference:2003_03 keyName=Associated Policy reference references entity How to classify UDDI data If a Component wants to smoothly integrate, it should ask the Entity Configuration to classify the data it works with. Then it can write proper nouns to the web page, and use tasks and components configured for the entity instead of using hardcoded links. The first step is obviously to find out what Entity the data correspond to. In Java, you will use the EntityHelper to determine the classification: Page 585 How to classify UDDI data Example 30. Classification of data in Java UDDIObject fromInstance; Assume, that the fromInstance variable is initialized to an UDDIObject instance Extract CategoryBag from whatever UDDI structure we have CategoryBag fromCatBag = BscObjectUtilities.getCategoryBagfromInstance, true; Get the list of KeyedReferences KeyedReferenceArrayList fromKr = fromCatBag.getKeyedReferenceArrayList; Lookup the appropriate Entity definition from Entity Configuration EntityHelper.Entity myEntity = helper.findEntityByCategorizationfromKr, fromType; The code snipped provides you with an EntityHelper.Entity instance, which describes the data type. Please refer to API documentation for details how to use the retrieved data. Using Entities in JSP pages The EntityHelper API class is designed for simple usage from JSPs. For classification, you may use the following snippet: Example 31. Classification of data in JSP -- The instance variable should be initialized to some UDDIObject instance. The entityType variable will be created and set to the appropriate EntityHelper.Entity instance by the tag. -- bsc:setEntityClassification var=entityType instance={instance} The bsc:setEntityClassification is a JSP alternative to call the findEntityByClassification method of the EntityHelper class. Note the usage of the bscEntityClassifier. This is session variable, provided by the Business Service Control Framework so the EntityHelper API is accessible from JSP pages. If you are given an entityId instead of a data structure, you may easily refer to the EntityHelper.Entity instance using an EL expression in the JSP: Example 32. Classification of data in JSP -- The entityId variable should be initialized to one of the entity types as defined in bsc.xml The bscEntityClassifier contains a framework-provided instance of the EntityHelper API, which provides a Map of available entities for easy lookup from JSP. -- c:set var=bscEntityType value={bscEntityClassifier.entities[entityId]} Page 586 Using Entities in JSP pages In order to use the Entitys caption or description, the procedure described in Localization guide must be used, to make use of the appropriate localized string. We recommend using the following pattern: Example 33. Classification of data in JSP -- First, get the entity type for the given entityId, we are expected to work with -- c:set var=bscEntityType value={bscEntityClassifier.entities[entityId]} -- Handle embedded bundle path specification, see localization guide for the details. The evaluated bundle name and key name will be placed into named request variables -- syswf:parseResourceKey key={bscEntityType.captionKey} defaultBaseName=com.systinet.uddi.bui.framework.BSCMessages varBundle=bundleName varResource=finalCaptionKey -- Load the bundle, which actually contains the key. Note that the bundle name may not be known at design time, as it may be embedded in the generalized resource bundle key -- fmt:setBundle basename={bundleName} var=dynamic_Message -- Setup two variables, one holding plural noun for entity caption, the other will hold the singular -- fmt:message key={finalCaptionKey} var=entityCaption bundle={dynamic_Message} fmt:message key={finalCaptionKey}_single var=entityCaption_single bundle={dynamic_Message} -- Finally, format some message properly localizing it through a bundle, and substitute the entity nouns in it. Note that the message itself can control whether plural or singular is used - it can use {0} to denote plural and {1} for singular noun. -- fmt:message key=some_message_key bundle={myBundle} fmt:param value={entityCaption} fmt:param value={entityCaption_single} fmt:message The snippet first parses the resource bundle key provided as entity.captionKey property, then loads the appropriate ResourceBundle using the fmt:setBundle standard tag. Note the bundle key naming convention used to load the singular and plural nouns for the Entity type. Page 587 Using Entities in JSP pages Using Views When working with some data structure, you may directly invoke a Component, using syswf:component, or make a link to a specific task using syswf:control. If you work on a mixture of data structures, each structure may require a different Component to display itself, or a different Task to perform the action. When the Entity Configuration changes, so that, for example, the task URI of the Edit operation changes, pages which use hardcoded component names or task URIs may become inconsistent with the rest of the UI. You may perform the operation in an abstract way, using the invokeEntityView Component. You need to pass in enough information to identify the entity type and you need to specify the type of invoked View see above for the overview of supported view types. Parameters defined by the View specification will be forwarded to the View component or task. You may pass additional parameters, but you have to prefix them with the prefix view_ so that they are recognized and forwarded. Example 34. Invoking a Component configured in Entity Configuration -- The following code invokes a searchResults, which produces a table of results for the entity and the passed query. The code is taken out from Reports tab implementation -- syswf:component prefix={tabId} name=invokeEntityView -- The desired viewType -- syswf:param name=viewType value=searchResults -- The query to process, taken from a prepared Map of queries for individual entity types -- syswf:param name=query value={entityQueries[type.id]} -- Output parameter, component stores the result list in a temporary to allow the caller to find out whether the result list is empty -- syswf:param name=var value=references_tmp -- Propagates the type of the entity, to cover the case the view is reusable and is used for multiple entity types -- syswf:param name=entityId value={type.id} syswf:component Page 588 Using Views Example 35. Linking to a Task configured in Entity Configuration -- This snippet invokes a Create Wizard for the given entity. -- syswf:component name=invokeEntityView prefix=create syswf:param name=entityId value={entityId} syswf:param name=viewType value=create -- A HTML link will be generated -- syswf:param name=mode value=anchor -- Text for the hyperlink -- syswf:param name=caption value=Link text syswf:component You may also need to determine whether a certain View is available. The EntityHelper.Entity provides you with all supported views as a java.util.Map, so you use the contents from a JSP easily: Example 36. Linking to a Task configured in Entity Configuration -- Set the entity type into a variable, for convenience -- c:set var=bscEntityType value={bscEntityClassifier.entities[entityId]} -- Check whether the desired view is available -- c:if test={not empty bscEntityType.views[create]} -- Do some fancy stuff -- ... c:if The presence of a View indicates, that a certain function is available for an entity. You may conditionally change the page appearance based on such an indication. Linking to a Detail page In places where an entity is mentioned, it is often appropriate to link to the entity Detail page. There is a special component showEntityName for this purpose. It renders the entitys name as a hyperlink to the entitys Details. Page 589 Linking to a Detail page Example 37. Linking to entity details -- This example shows how to create a link to the detail page of an Entity. The entity is given by its key, UDDI type and the keyedReferences. -- syswf:component name=showEntityName prefix=name1 syswf:param name=entityKey value={key} syswf:param name=uddiType value=TM syswf:param name=keyedReferences value={keyedReferenceArrayList} syswf:component -- The following example shows how to use UDDI structure itself, if it is available to link to the relevant entity detail -- syswf:component name=showEntityName prefix=n_{row.key} syswf:param name=entityInstance value={theStructure} -- We override the rendered string with a custom value. If this was omitted, the entity name would be printed as the hyperlink text -- syswf:param name=instanceName value=Some string syswf:component A description of the component and its parameters can be found in file jspbrowseshowEntityName.jsp, which you can find in bsc.jar or in the BSC work directory.

3.8.5. Permission support

Business Service Control contains powerful support for user permission evaluation on selected objects. The developer can easily find out, if the current user is allowed to manipulate some object. This feature takes into consideration object ownership, Access Control Lists, groups and API permissions. Data classes T h e A P I c o n t a i n s t w o i m p o r t a n t J a v a t y p e s . T h e f i r s t i s t h e c l a s s com.systinet.uddi.bui.framework.component.util.permission.UserContext . An instance is created automatically, when a user logs into the Business Service Control and it is available in the global session under key userContext. The instance holds the groups that the user is member of and a list of his permissions. Then there is an interface com.systinet.uddi.bui.framework.component.util.permission.DataFeeder. It is the developers responsibility to create and feed an instance of its implementation. There are two implementations available. com.systinet.uddi.bui.framework.component.util.permission.UDDIDataFeeder is initialized with list of UDDI keys and it fetches specified UDDI structures from Oracle Service Registry. If these structures are already available, then it is better to use com.systinet.uddi.bui.standard.component.util.permission.BuiDataFeeder for performance reasons. PermissionEvaluator T o c h e c k u s e r p e r m i s s i o n s i n J a v a c o d e y o u m u s t u s e c l a s s com.systinet.uddi.bui.framework.component.util.permission.PermissionEvaluator . It contains public methods Page 590 PermissionEvaluator to check whether the user can create a business service in the given business entity, or binding template in the given business service, and to check whether the user can update or delete a specified business entity, business service, binding template or tModel. These methods take a UDDI key, the UserContext and a DataFeeder implementation as arguments. Example 38. ParseResourceKey tag - Usage Example boolean allowed = PermissionEvaluator.checkPermissionDeleteTMtModelKey, userContext, dataFeeder; checkPermission tag To check user permissions in JSP, there is a tag checkPermission. In addition to a UDDI key, the UserContext and a DataFeeder implementation, it accepts operation and var attributes as arguments. It specified variable receives the result of the check. Table 95. checkPermission tag Parameters Required Description Param yes Name of the variable that will hold the result of the check. var no Scope for the new variable. scope yes Operation identifier. One of create, edit and delete. operation yes The key of the UDDI structure for which we want to check permissions. key yes Container for user account specific data. Typically available in global session, if the user is logged in. userContext yes Data object holding information about UDDI structures on this page. dataFeeder Example 39. ParseResourceKey tag - Usage Example bsc:checkPermission var=permission operation=edit key={row.key} userContext={globalSession[userContext]} dataFeeder={dataFeeder} c:if test={permission} syswf:control targetTask=publishendpointseditEndpoint caption=Delete mode=image src=gfxiconi_edit.gif syswf:param name=bindingKey value={row.key} syswf:control c:if

3.8.6. Components and Tags

This section describes selected components and tags of the Business Service Control BSC framework and components of the Business Service Control. The BSC Framework is a set of components and tags used by developers to develop Business Service Control components. For complete documentation of these components, see the Java Doc located in the REGISTRY_HOMEdocbsc-api directory. • Framework Components • Framework Tags • Business Service Control Components Page 591

3.8.6. Components and Tags