Data Models for the Duet Sales Order Management Solution
Applies to: Duet Enterprise for Microsoft SharePoint and SAP Server 2.0 | Office 2010 | SharePoint Server 2010
In this article
Mapping Objects in the SAP Environment for Representation in SharePoint
Configuring and Using the Sales Order BDC Models
The Sales Order Header External Content Type
The Sales Order Item External Content Type
Updating, Creating, and Deleting Sales Order Data
Summary of Relationships
Data that originates in a line-of-business system such as SAP is considered "external data" because its source is external to the SharePoint content database. For the Duet Sales Order Management solution, to be able to access and manipulate external data within SharePoint, you need to create external content types. External content types are representations within SharePoint of external data structures and the operations that can be performed on those data structures. The information that describes specific external data structures and how to connect and interact with them—that is, the metadata that composes an external content type—is defined in an XML file that is maintained in the Metadata Store by the Business Data Connectivity (BDC) service. This XML file is called a BDC model.
Mapping Objects in the SAP Environment for Representation in SharePoint
For the Duet Sales Order Management solution, two BDC models have been developed to represent and manipulate within SharePoint some of the data associated with the Sales Order business object type from the SAP back-end system. The Sales Order business object type in SAP ERP is a complex object associated with a large number of attributes that can be used to define real-world sales orders as logical entities in extensive detail. This business object type in the SAP back-end system is the basis of the Duet Sales Order Management solution, but to interact with data associated with this object in SharePoint, the data needs to be simplified. Facets of this object are therefore represented by several different data types in the Service Consumption Layer (SCL) in the SAP environment. These data types make it easier to interact with an SAP Sales Order business object type in SharePoint by factoring certain parts of the complex Sales Order object into simpler, more manageable, objects.
The three main data types defined in the SCL relevant to the Duet Sales Order Management solution are SalesOrderHeader, SalesOrderHeaderDetails, and SalesOrderItemDetails. These simplified data types in turn are exposed to SharePoint through the methods of web services that are developed in the SCL. These web services are based on the creation of service interfaces in the SCL that define the operations that can be carried out on the SCL data types. External content types are then created in SharePoint based on the data exposed by these web services (through entry points on the Service Interfaces defined in the SCL). Any number of external content types can be created based on the data exposed by the web services, depending on the requirements of the solution you are developing. For the Duet Sales Order Management solution, we are working with sales orders in terms of sales order "headers" and sales order "items". A sales order header can be thought of as a kind of bill or description of a sales transaction (that is, an order) and that transaction includes one or more individual items. There is a one-to-many relationship between sales order headers and the individual items that compose a sales order.
To represent the logical constructs of sales order headers and sales order items in the Duet Sales Order Management solution, we developed two BDC models, SalesOrderHeader.bdcm and SalesOrderItem.bdcm, that define a Sales Order Header external content type and a Sales Order Item external content type. The Sales Order Header external content type includes operations to return information from both the SalesOrderHeader and SalesOrderHeaderDetails data types that are defined in the SCL of the SAP environment, and the Sales Order Item external content type includes operations to return information from the SalesOrderItemDetails data type in the SCL. These two external content types constitute the foundation of the Duet Sales Order Management solution.
Configuring and Using the Sales Order BDC Models
To use the BDC models included with the Duet Sales Order Management solution in your development environment, you must to modify the models based on your environment. In particular, you need to specify in the models the appropriate WSDL URLs and endpoint URLs based on the configuration of the web services defined in the SCL. (For details related to the configuration of web services in the SAP environment, see Sections 5.10 and 5.11 of the SAP Duet Enterprise Developer Guide.) Depending on your configuration, you may need to specify a value for the WcfMexDocumentUrl property of the LobSystem entity in the model and a value for the WcfEndpointAddress property of the LobSystemInstance entity, along with the appropriate security credentials.
<LobSystems>
<LobSystem Type="Wcf" Name="SCLManageSalesOrder">
<Properties>
<Property Name="ReferenceKnownTypes" Type="System.Boolean">true</Property>
<Property Name="WcfMexDiscoMode" Type="System.String">[Specify appropriate mode here.]</Property>
<Property Name="WcfMexDocumentUrl" Type="System.String">[Specify WSDL URL or MEX endpoint here.]</Property>
<Property Name="WcfProxyNamespace" Type="System.String">BCSServiceProxy</Property>
<Property Name="WildcardCharacter" Type="System.String">*</Property>
</Properties>
<AccessControlList>
<AccessControlEntry Principal="STS|SecurityTokenService|http://sharepoint.microsoft.com/claims/2009/08/isauthenticated|true|http://www.w3.org/2001/XMLSchema#string">
<Right BdcRight="Execute" />
</AccessControlEntry>
<AccessControlEntry Principal="DOMAIN\USER">
<Right BdcRight="Edit" />
<Right BdcRight="Execute" />
<Right BdcRight="SetPermissions" />
<Right BdcRight="SelectableInClients" />
</AccessControlEntry>
</AccessControlList>
<LobSystemInstances>
<LobSystemInstance Name="SCLManageSalesOrder">
<Properties>
<Property Name="ShowInSearchUI" Type="System.String"></Property>
<Property Name="UseStsIdentityFederation" Type="System.Boolean">true</Property>
<Property Name="WcfAuthenticationMode" Type="System.String">PassThrough</Property>
<Property Name="WcfEndpointAddress" Type="System.String">[Specify service endpoint address here.]</Property>
<Property Name="WcfImpersonationLevel" Type="System.String">Identification</Property>
</Properties>
</LobSystemInstance>
</LobSystemInstances>
For additional information on configuring BDC models for use with Duet Enterprise, see How To: Create a BDC Model for Duet Enterprise in the MSDN Library.
After you modify the BDC models based on the URLs specific to the web services that provide access to your SAP data in the SCL, you can import the models into the BDC Metadata Store through Central Administration in SharePoint. For specific instructions on importing BDC models in SharePoint, see the steps in the section "Importing a BDC model" in the topic Manage BDC models (SharePoint Server 2010) in the MSDN Library.
Note
When you import into Business Connectivity Services the BDC models that accompany the Duet Sales Order Management solution, you may receive warnings because no Limit filters are set on the Finder methods for the external content types that are defined in the models. In a production environment, you may want to consider adding Limit filters. The Business Data Connectivity Service in SharePoint 2010 is configured by default to return no more than 2000 items from external data sources. See Filters and Throttling in the BDC in patterns & practices SharePoint Guidance 2010 in the MSDN Library.
The Sales Order Header External Content Type
The BDC model that defines the Sales Order Header external content type is specified in the file SalesOrderHeader.bdcm. For the Duet Sales Order Management solution, we identified a subset of the attributes of the SAP Sales Order business object type to be made available through the SCL for use in SharePoint. This subset of attributes is defined and encapsulated by several data types in the SCL of the SAP environment, which will be exposed to SharePoint through a web service proxy. The BDC model that defines the Sales Order Header external content type implements a SpecificFinder stereotyped method (which is represented as a Read Item operation in SharePoint Designer) based on the ReadSalesOrder web method of the web service proxy that provides access to the data in the SAP system. This method returns a value that corresponds to the SalesOrderHeaderDetails data type established in the SCL in the SAP environment, providing access to all of the attributes of the back-end Sales Order business object type that we want to expose to SharePoint through the web service, such as SalesOrderNumber, PurchaseOrderNumber, and DeliveryDate. This return value and the data fields it contains are described in the BDC model as follows.
<Parameter Direction="Return" Name="ReadSalesOrder">
<TypeDescriptor TypeName="BCSServiceProxy.SalesOrderByIDResponse_syncDataType, SCLManageSalesOrder" Name="ReadSalesOrder">
<TypeDescriptors>
<TypeDescriptor TypeName="BCSServiceProxy.SalesOrderHeaderDetails, SCLManageSalesOrder" Name="SalesOrderHeader">
<TypeDescriptors>
<TypeDescriptor TypeName="System.String" ReadOnly="true" IdentifierName="SalesOrderSclKey" Name="SalesOrderSclKey" DefaultDisplayName="Sales Order SCL Key" />
<TypeDescriptor TypeName="System.String" ReadOnly="true" Name="SalesOrderNumber" DefaultDisplayName="Sales Order Number" />
<TypeDescriptor TypeName="System.String" Name="PurchaseOrderNumber" DefaultDisplayName="Purchase Order Number" />
<TypeDescriptor TypeName="System.String" Name="SoldToParty" DefaultDisplayName="Sold-To Party" />
<TypeDescriptor TypeName="System.String" Name="SalesOrganization" DefaultDisplayName="Sales Organization" />
<TypeDescriptor TypeName="System.String" Name="DeliveryDate" DefaultDisplayName="Delivery Date" />
<TypeDescriptor TypeName="System.String" Name="OrderType" DefaultDisplayName="Order Type" />
<TypeDescriptor TypeName="System.Decimal" ReadOnly="true" Name="NetValue" DefaultDisplayName="Net Value">
<Properties>
<Property Name="Decimal Digits" Type="System.Int32">4</Property>
</Properties>
</TypeDescriptor>
<TypeDescriptor TypeName="System.String" Name="Currency" DefaultDisplayName="Currency" />
</TypeDescriptors>
</TypeDescriptor>
</TypeDescriptors>
</TypeDescriptor>
</Parameter>
The data returned by this implementation of the SpecificFinder method is displayed in detailed views in the Duet Sales Order Management solution of individual sales order headers (such as the views displayed by forms accessible from the list item menu of items in SharePoint lists).
The BDC model for the Sales Order Header external content type also includes an implementation of the Finder stereotyped method (represented as a Read List operation in SharePoint Designer). This method is defined in the model based on the QuerySalesOrder web method of the web service proxy. This method returns an array of objects that correspond to the SalesOrderHeader data type that is defined in the SCL of the SAP system. These objects expose a subset of the attributes that are exposed by the SalesOrderHeaderDetails data type, comprising only the following five attributes:
SalesOrderSclKey
SalesOrderNumber
PurchaseOrderNumber
SoldToParty
SalesOrganization
These fields are displayed as columns in the external list that is created and associated with the Sales Order Header external content type in the Duet Sales Order Management solution.
For a thorough description of the SalesOrderHeader and SalesOrderHeaderDetails data types as they are defined in the SAP environment, see Section 5.2.4 of the SAP Duet Enterprise Developer Guide.
The Sales Order Item External Content Type
The model that defines the Sales Order Item external content type is specified in the file SalesOrderItem.bdcm. As with the Sales Order Header external content type, this external content type is based on data types that are defined in the SCL of the SAP environment. In particular, the BDC model that defines the Sales Order Item external content type implements a SpecificFinder stereotyped method based on the ReadSalesOrderItem web method of the web service proxy that provides access to the SAP system. This method returns an object that corresponds to the SalesOrderItemDetails data type defined in the SCL. The return value and the data fields it contains are described in the BDC model as follows.
<Parameter Direction="Return" Name="ReadSalesOrderItem">
<TypeDescriptor TypeName="BCSServiceProxy.ItemByIDResponse_syncDataType, SCLManageSalesOrderItem" Name="ReadSalesOrderItem">
<TypeDescriptors>
<TypeDescriptor TypeName="BCSServiceProxy.SalesOrderItemDetails, SCLManageSalesOrderItem" Name="Item">
<TypeDescriptors>
<TypeDescriptor TypeName="System.String" ReadOnly="true" IdentifierName="ItemSclKey" Name="ItemSclKey" DefaultDisplayName="Item SCL Key" />
<TypeDescriptor TypeName="System.String" ReadOnly="true" Name="ItemNumber" DefaultDisplayName="Item Number" />
<TypeDescriptor TypeName="System.String" Name="SalesOrderSclKey" DefaultDisplayName="Sales Order SCL Key" />
<TypeDescriptor TypeName="System.String" Name="SalesOrderNumber" DefaultDisplayName="Sales Order Number" />
<TypeDescriptor TypeName="System.String" Name="MaterialNumber" DefaultDisplayName="Material Number" />
<TypeDescriptor TypeName="System.String" Name="ShortText" DefaultDisplayName="Short Text" />
<TypeDescriptor TypeName="System.Decimal" Name="Quantity" DefaultDisplayName="Quantity">
<Properties>
<Property Name="Decimal Digits" Type="System.Int32">4</Property>
</Properties>
</TypeDescriptor>
<TypeDescriptor TypeName="System.String" Name="SalesUnit" DefaultDisplayName="Sales Unit" />
<TypeDescriptor TypeName="System.Decimal" Name="NetPrice" DefaultDisplayName="Net Price">
<Properties>
<Property Name="Decimal Digits" Type="System.Int32">4</Property>
</Properties>
</TypeDescriptor>
<TypeDescriptor TypeName="System.String" Name="Currency" DefaultDisplayName="Currency" />
<TypeDescriptor TypeName="System.Decimal" Name="NetValue" DefaultDisplayName="Net Value">
<Properties>
<Property Name="Decimal Digits" Type="System.Int32">4</Property>
</Properties>
</TypeDescriptor>
<TypeDescriptor TypeName="System.String" Name="Plant" DefaultDisplayName="Plant" />
</TypeDescriptors>
</TypeDescriptor>
</TypeDescriptors>
</TypeDescriptor>
</Parameter>
The BDC model that defines the Sales Order Item external content type includes an implementation of the Finder stereotyped method, defined based on the QuerySalesOrderItem web method of the web service proxy. This method simply returns an array of the same kind of object that the ReadSalesOrderItem method returns. In the Duet Sales Order Management solution, then, for sales order items, the same fields are displayed in detailed views for specific items as are displayed in the external list created for the Sales Order Item external content type.
Updating, Creating, and Deleting Sales Order Data
In addition to providing the basic mechanisms for reading and displaying sales order data in external lists and forms, the BDC models that define the Sales Order Header and Sales Order Item external content types also provide for creating, updating (that is, editing) and deleting headers and items. To support these operations on the external content types in SharePoint, the external data source (in this case, a set of web services) must provide support for these operations. The Service Interface on which the web services for the Duet Sales Order Management solution are based has been configured with the appropriate methods to allow for creating, updating, and deleting sales order headers and items. (For details of the implementation of these methods in the Service Interface of the SCL, see Section 7 of the SAP Duet Enterprise Developer Guide.)
The methods defined in the Service Interface for creating, updating, and deleting must be represented (that is, "modeled") in the BDC models by implementation of equivalent stereotyped methods. To support, for example, updating a sales order header or item, you need to implement the Updater stereotyped method (represented in SharePoint Designer as an Update operation). For the Sales Order Header external content type, this stereotyped method is implemented by a method called UpdateSalesOrder, which takes as input an object that corresponds to the SalesOrderHeaderDetails object defined in the SCL—the same object returned by the ReadSalesOrder method that is an implementation of the SpecificFinder stereotyped method.
The operations for creating and deleting sales order headers and items are supported in their respective external content types by implementations of the Creator and the Deleter stereotyped methods.
Summary of Relationships
The various data types and objects in the back-end SAP system and in the SCL and how they relate to the representative external content types created in BCS can be difficult to keep straight. Figure 1 illustrates the relationships among the various components involved in the Duet Sales Order Management solution.
Figure 1. Data types and objects for the Duet Sales Order Management solution
.gif "Duet Sales Order Management solution data types")
In the next topic in this walkthrough, Developing the Primary Components for the Solution, we use Visual Studio 2010 to develop the main functional parts of the Duet Sales Order Management solution based on the external content types defined in the BDC models.
See Also
Concepts
How To: Create a BDC Model for Duet Enterprise
Other Resources
Walkthrough: Creating Your Own BDC Model