4.4    Exercise: Working with the ES Repository and Registry

In Chapter 3, we created and configured the technical systems, business systems, products, and SWCVs. In this exercise, we’ll create all the design objects necessary to support the information exchange between the backend system of Reader’s Paradise and Book Fountain.

4.4.1    Exercise Description

The customer (in this case, Reader’s Paradise) has asked you to build an SAP PO interface to support the automatic exchange of purchase orders between its procurement backend system and its supplier, Book Fountain. The functional requirements also indicate that before you can send the order to the supplier, you first need to convert and map the input into the supplier’s message structure. Based on the specifications of the business process, you also know that the interface will be asynchronous; that is, no direct answer from the supplier side is expected. Remember, at this stage of the development process, it’s less important to know which systems are going to use the design objects. Those additional details will become clear when we discuss the configuration done in the Integration Builder part of the Integration Directory.

4.4.2    Exercise Solution Approach

To achieve your goals, you’ll need the following design objects:

• All three SWCVs, imported from the SLD into the ES Builder
• A repository namespace for each imported SWCV
• Data and message types for the sending and receiving service interfaces
• Two asynchronous service interfaces: an outbound service interface for the sender component and an inbound service interface for the receiver component
• An operation mapping and a message mapping to transform the input XML structure into the output XML structure as expected by the receiver system

Good to Know

As a best practice, we strongly recommend introducing and applying naming conventions for SAP PO developments before you start any integration scenario. You can create your own set of naming conventions, but you can also reuse or extend existing naming conventions available from the SAP PO community on the Internet.

We’ll now continue with the next steps of the exercise by initiating the design time in the ES Repository.

4.4.3    Exercise Step-by-Step Solution

The next sections will provide a step-by-step solution.

Importing Software Component Versions in the ES Repository

We’ll start by importing all three SWCVs we created in the SLD into the Integration Builder. Then, we’ll start adding our design objects to the different SWCVs.

The SWCVs that we’ll import into the ES Builder are as follows:

• SWC_READERSPARADISE
• SWC_BOOKFOUNTAIN
• SWC_MAPPINGS

To import the SWCVs, follow these steps:

1. Navigate to the landing page of SAP PO, and click on the Enterprise Services Builder link (see Figure 4.7). Open a web browser, and go to http://<hostname>:<port>/dir. Log in with your SAP PO credentials when prompted.
   

   Figure 4.7    SAP PO Landing Page

2. Press (Ctrl) + (N), or navigate to the top menu, and click on Object (see Figure 4.8).
3. Select Import from SLD, and click on the Display button to populate the list with available SWCVs from your SLD.
   

   Figure 4.8    Create Object Screen from the ES Builder

4. From this screen, you can search for and select the SWCVs (one at a time) that you want to import into your development environment. Type the name of the SC, “SWC_READERSPARADISE”, into the search bar, and click on Import.
5. Select the correct entry from the list, and click on the Import button to start the import process (see Figure 4.9).
   

   Figure 4.9    Import of SWCVs

6. When you’re finished, you should now see the details of the imported SWCV in the Create Object window. If that is the case, then you can proceed by clicking on Create (see Figure 4.10).
   

   Figure 4.10    Creating the SWCV from SLD

7. You should now see a new editor window open on the right side of your screen, displaying the new SWCV. Before you can press (Ctrl) + (S) or click on the Save button, you need to select the desired original language for this object from the dropdown menu. Repeat steps two to six for the remaining two SWCVs (SWC_BOOKFOUNTAIN and SWC_MAPPINGS). Then, click on Save. Note that the Namespaces panel at the bottom of the page contains no entries yet; however, we’ll work on namespaces in the next part of the exercise (see Figure 4.11).

Figure 4.11    Configuring and Saving SWCVs

Creating Repository Namespaces

Now that you’ve imported and configured the SWCVs, you’re ready to start creating the necessary design objects for your file to FTP integration scenario. Follow these steps:

1. Click Object from the main menu or press (Ctrl) + (N) to create a new repository object. In this case, you’ll create a repository namespace in each of the new SWCVs. Fill in the following values (see Figure 4.12):
   • Namespace: “urn:readersparadise.com:scm:procurement:erp”
   • Software Component Version: “SWC_READERSPARADISE” (You can find this by clicking on the Value List; select the correct one, and click on Create.)
2. Click on Save (see Figure 4.13).
   

   Figure 4.12    Create the New Repository Namespace

   

   Figure 4.13    Save the New Repository Namespace

3. Repeat the previous step for the two remaining SWCVs. The namespaces for the two other SWCVs are as follows:
   • SWC_BOOKFOUNTAIN: urn:readersparadise.com:scm:procurement:supplier
   • SWC_MAPPINGS: urn:readersparadise.com:scm:procurement

After you’ve finished creating the new namespace for each SWCV, the contents of your SWCV should look like Figure 4.14.

Figure 4.14    SWCV with New Repository Namespace

Good to Know

At this stage of design time, you’ll start building up a change list (per SWCV) that contains all creations, changes, and deletions made to saved activities performed in the ES Builder. From the moment you activate a change list, its contents will be visible and available to the rest of the developer team and the SAP PO environment.

Before activation, you have the option to reject specific changes or the entire change list. You can also see other change lists and assign them to other users. Finally, you can query and look into the contents of previously activated (i.e., closed) change lists (see Figure 4.15).

Figure 4.15    Repository Change Lists

Creating Data Types, Message Types, and Service Interfaces

You’re now about to create your service interfaces, which are the arteries of every integration scenario built on top of SAP PO. First, however, we need to lay some groundwork, the theoretical explanation of how you’re going to tackle this task.

When designing custom service interfaces in SAP PO, you can decide whether to apply a top-down or a bottom-up development approach. Our advice is to follow the bottom-up approach instead of top-down, for two reasons:

• It follows the SOA design principle of contract first.
• It fits perfectly into a model-driven development style in which the application logic (e.g., service interfaces, GUIs, etc.) is based on the underlying information model rather than the opposite.

In addition, when you’re creating the service interfaces, all message types, data types, and external definitions will be ready and available there for you to select.

Enough theory for now; let’s go back and focus on our main goal, which is the completion of the design-time objects for this exercise.

Start by creating two data types, one message type, and an outbound service interface for the sender component for the integration scenario by following these steps:

1. Click on Object from the main menu, or press (Ctrl) + (N) to create a new repository object. Click on Interface Objects and then on Data Type.
2. Fill in the following values:
   • Name: “DT_OrderItem” (“DT” is our naming convention for data types)
   • Namespace: “urn:readersparadise.com:scm:procurement:erp”
   • Software Component Version: “SWC_READERSPARADISE”
3. Click on Create.
4. Now that you’ve created your data type, complete the fields that will carry the order information during runtime. Enter the values shown in Figure 4.16, and save your work.
   

   Figure 4.16    Creating the Data Type for DT_OrderItem

   Now, create the second data type for the sender component, which will contain additional header fields at the order level (not to be confused with the SOAP header) in the payload. Follow these steps:
5. Click on Object from the main menu, or press (Ctrl) + (N) to create a new repository object. Click on Interface Objects and then on Data Type.
6. Fill in the following values:
   • Name: “DT_Order”
   • Namespace: “urn:readersparadise.com:scm:procurement:erp”
   • Software Component Version: “SWC_READERSPARADISE”
7. Click on Create.
8. Complete the fields contained in this new data type structure. Note that you can now start reusing your own data types (see the OrderItems element in Figure 4.17). Choose DT_OrderItem for the definition of this new structure by selecting it from the Type dropdown menu or by selecting the Type column and pressing the (F4) key. Complete the data type as shown in Figure 4.17, and click on Save when you’ve finished.

Figure 4.17    Creating the Data Type for DT_Order

Now you can create the message type, which in fact represents the root element of the outbound service interface. Assign your previously created data type DT_Order as your main data type for this new message type. Follow these steps:

1. Click on Object from the main menu, or press (Ctrl) + (N) to create a new repository object. Click on Interface Objects and then on Message Type.
2. Fill in the following values:
   • Name: “MT_PurchaseOrder” (“MT” is our naming convention for message types)
   • Namespace: “urn:readersparadise.com:scm:procurement:erp”
   • Software Component Version: “SWC_READERSPARADISE”
3. Click on Create.
4. Select DT_Order for Data Type Used.
5. When you finish, your message type should look like Figure 4.18. Don’t forget to save your work.

Figure 4.18    Creating the Message Type for MT_PurchaseOrder

Now that you’ve defined the message type, you can create the outbound service interface by following these steps:

1. Click on Object from the main menu, or press (Ctrl) + (N) to create a new repository object. Click on Interface Objects and then on Service Interface.
2. Fill in the following values:
   • Name: “SIOA_PurchaseOrder” (“SIOA” is our naming convention for service interface outbound asynchronous)
   • Namespace: “urn:readersparadise.com:scm:procurement:erp”
   • Software Component Version: “SWC_READERSPARADISE”
3. Click on Create.
4. The new service interface is displayed on the screen. Leave all default values for the attributes (category, interface pattern, and security profile) as is. You can change the operation name to something else if desired, but it isn’t necessary for this exercise. Make sure that the Mode selected is Asynchronous, and proceed to select the Message Type MT_PurchaseOrder from the Name column dropdown menu in the Messages area at the bottom of the screen. The final product should look like the one shown in Figure 4.19. Save your work when you finish.

Figure 4.19    Creating the Service Interface for SIOA_PurchaseOrder

You’ve now created all the necessary objects for the sender component of the integration scenario, but you still have to create the same types of design objects for the receiver component.

You’ll notice that there are some differences between the data types on the sender and receiver side. That difference is represented by the contents of the data types on both sides (i.e., DT_Order [sender] and DT_item [receiver]). The definition of the internal XML structure for the purchase order message is provided by Book Fountain. Create the design objects (data type, message type, service interface, operation mapping, and message mapping) discussed ahead, using the same general instructions as explained for the sender side, but take into consideration that there are some differences in the internal message structures for the receiver service interface.

You need to create one data type, one message type, and an inbound service interface for the receiver component for the integration scenario.

To begin designing objects for the receiver component in SWC_BOOKFOUNTAIN, follow these steps:

1. Create data type DT_Item. In this case, you want to use one single data type to describe both header and line items in one structure. On the sender side, you described two separate data types for header and line items (see Figure 4.20).
   

   Figure 4.20    Creating Data Type DT_Item

2. Create message type MT_CustomerOrder using the new data type DT_Item (see Figure 4.21).
   

   Figure 4.21    Creating Message Type MT_CustomerOrder

3. Create service interface SIIA_CustomerOrder using message type MT_CustomerOrder. Make sure you change the Category attribute to Inbound, and the Mode of the interface must be Asynchronous (see Figure 4.22). Here, “SIIA” is our naming convention for service interface inbound asynchronous.

Figure 4.22    Creating Service Interface SIIA_CustomerOrder

You’ve now finished the creation of sender and receiver design objects. The next and final step of this part of the exercise is to construct the mapping and translation of the input message into the output message. For that purpose, you’ll create new mapping objects in SWC_MAPPINGS.

You need to create an operation mapping that will be in charge of mapping the inbound service interface operation into the outbound service interface operation. Imagine if you had a service interface with multiple operations instead of only one (like the one in the example); then, you could have many different operation mappings for all of them. You also need to create the message mapping that actually performs the real mapping and message translation tasks in the background.

Because we decided to use the bottom-up approach, start by creating the message mapping and then the operation mapping:

1. Click on Object from the main menu, or press (Ctrl) + (N) to create a new repository object. Click on Mapping Objects and then on Message Mapping.
2. Fill in the following values:
   • Name: “MM_SIOA_PurchaseOrder_to_SIIA_CustomerOrder” (Another option for a logical name could be, for instance, based on the message types: “MT_PurchaseOrder_to_MT_CustomerOrder”; “MM” is our naming convention for message mapping.)
   • Namespace: “urn:readersparadise.com:scm:procurement”
   • Software Component Version: “SWC_MAPPINGS”
3. Click on Create.
4. The new message mapping editor is displayed on the screen. You can now select the source and target messages from the menu; choose the Definition tab and the leftmost button, as shown in Figure 4.23. Select MT_PurchaseOrder from SWCV_READERSPARADISE and MT_CustomerOrder from SWCV_BOOKFOUNTAIN.
   

   Figure 4.23    Selecting Source and Target Message

5. Now that you’ve selected the correct message types, you can take care of the mapping and transformation. Perform the mapping using drag and drop from source to target. Your mapping should look like the one shown in Figure 4.24.

Figure 4.24    MT_PurchaseOrder_to_MTCustomerOrder Message Mapping

Before you can finish your mapping, you need to perform a final action. As you already may have noticed, the source message contains a complex element called Address, which contains different children elements. On the target side, there is one simple type element (of type string), which carries all address details of an order separated by commas. You have to concatenate the different values contained in the source address into one single field on the target message. You’ll use a standard, out-of-the-box function for this purpose. Follow these steps:

1. Drag the concat function (located at the very bottom of the mapping editor) and all necessary source and target fields to the mapping area (see Figure 4.25).
   

   Figure 4.25    Concat Function in Message Mapping

2. Note that you need to add the concat function two times because it only accepts two inputs per function. Double-click on both concat functions, and add a comma as the Delimiter String (see Figure 4.26). When finished, test your mapping by selecting the Test tab and entering some data in the source structure, and then click on the Test button in the lower left part of the screen. If you’re happy with the test results of the mapping, then save your work.

Figure 4.26    Delimiter String Parameter in the concat Function

You’re only one step away from finishing the exercise for this chapter. Let’s see how all the pieces come together when you create the operation mapping:

1. Click on Object from the main menu, or press (Ctrl) + (N) to create a new repository object. Click on Mapping Objects and then Operation Mapping.
2. Fill in the following values:
   • Name: “OM_SIOA_PurchaseOrder_to_SIIA_CustomerOrder” (“OM” is our naming convention for operation mappings.)
   • Namespace: “urn:readersparadise.com:scm:procurement”
   • Software Component Version: “SWC_MAPPINGS”
3. Click on Create.
4. The new operation mapping editor is displayed on the screen. You can now select the source and target service interfaces from the menu; choose the Definition tab and the leftmost button, as shown in Figure 4.27. Select SIOA_PurchaseOrder from SWCV_READERSPARADISE and SIIA_CustomerOrder from SWCV_BOOKFOUNTAIN.
5. Select MM_SIOA_PurchaseOrder_to_SIIA_CustomerOrder as the Mapping Program. Save your work (see Figure 4.27).
6. Go to the Change Lists Overview tab, and activate all change lists for the created design objects.

Figure 4.27    Creating Operation Mapping for Service Interfaces