Extending Existing Service Objects, Using Structures and XML Properties

This tutorial uses the Service Objects created in the Developing with K2 connect (basics) tutorial. If you have not already completed the Developing with K2 connect (basics) tutorial, please do so now before beginning this tutorial. This tutorial begins at Step 5 since it follows from the previous tutorial.

In Step 5, we will extend the EmployeeDataServiceObject (Service Object) with additional methods and properties. We will learn how to define custom structures for complex return properties and how to add other BAPIs to an existing Service Object. Finally, we will learn how to return a complex property such as an XML property.

Overview

In the previous exercise, we created a simple SAPEmployees SmartObject with two methods: List and Read. Suppose that the organization would like to get more detailed information about an employee with the "Read" method, for example their Job Title, the Company that they work for and the employee's email address(es).

As it happens, all of this information is available from various SAP BAPIs. Consider the diagram below. We will be using two different BAPIs in this exercise: BAPI_EMPLOYEE_GETDATA and BAPI_COMPANY_GETDETAIL.

We used BAPI_EMPLOYEE_GETDATA in the previous steps and specifically we returned some fields from the PERSONAL_DATA return structure in the employee read method. In this step, we will use two other return structures for the same BAPI: ORG_ASSIGNMENT, where we can obtain the employee's job title, position and the organization they work for along with the COMPANY_CODE, and COMMUNICATION structure, which is a collection of e-mail addresses for the user. Since this is a collection, we will return data from this structure as an XML property.

To retrieve data about the company that the employee works for, we will use the BAPI_COMPANYCODE_GETDETAIL BAPI. Note that the ORG_ASSIGNMENT structure of the BAPI_EMPLOYEE_GETDATA method has a COMP_CODE return property: this is the return property we will use to retrieve the company information from the BAPI_COMPANY_GETDETAIL call.

Because Step 5 is quite extensive, we will break it down into three sections:

  • Step 5a: Create a new service then manually configure the parameters and structure
  • Step 5b: Add a method to retrieve the company information
  • Step 5c: Update an existing method to include the employee's contact emails as an XML property

In this step, we will add a new service to our project, then manually define the parameters that we need. Two of the parameters will be input parameters and the third parameter will be a structure. After setting up our parameters, we will map them to output data fields, which essentially 'binds' the input data fields to the output data fields.

Step 5a Tasks

  1. Using the K2 connect Test Cockpit, execute the BAPI_EMPLOYEE_GETDATA BAPI method. Use the following values for the input parameters:
    DATE: Current Date
    EMPLOYEE_ID: 1037
    then review the contents of the ORG_ASSIGNMENT return structure.
    NOTE: You may need to provide credentials if you are working with the Single Sign On configuration that was set up in Part 2. The SAP system credentials are:
    Username: K2Learning
    Password: K2pass!
  2. In the EmployeeDataServiceObject, add a New Service and name it JobData.
  3. Add a Custom Method to the new service and name it ReadJobDataByEmpID.

    4. Next, we'll add and configure the parameters we need for our service call. In our case, we will add a date and an employee ID for our input parameters.

  4. Add a Parameter. This will be the parameter we need for the input date. Configure the parameter with the following options:
    Name: InputDate
    Declarer: Flat
    Datatype: DateTime
    Direction: In
  5. Add a second Parameter for the employee ID with the following options:
    Name: InputEmpID
    Declarer: Flat
    Datatype: Int64
    Direction: In

    6. Now we will manually define the structure we need for the employee's job data. Recall that a structure contains a number of properties, which we will define as well.

  6. Add the BAPI_EMPLOYEE_GETDATA method to the Internal Functions pane.
  7. Back in the Function Interface pane, Add a Parameter that we will define as our structure parameter. Name the new parameter JobInfo then select <New> for the Declarer.
  8. Name the new structure JobInfoStructure then select BAPIP0001B as the template we want to copy from. (The copy from Template link is located in the Structure Definition pane.)
  9. After clearing all of the pre-selected properties, manually select the following properties for the new structure: COMP_CODE, JOBTXT, ORGTXT, POSTXT
  10. Give each new property a friendly name. Use the table below as a guide.
    PropertyNew Friendly Name
    COMP_CODECompanyCode
    JOBTXTJobTitle
    ORGTXTDepartment
    POSTXTPosition
  11. Go back to the Function Interface screen. Change the JobInfo Declarer value to Structure. Change the DataType to JobInfoStructure. Change the Direction to Out.

    12. Now we need to define the mappings so that K2 connect knows how to pass the manual parameters we defined into and out of the BAPI.

  12. Open the Data Mapping screen. Map the InputDate input data field to the DATE() output data field.
  13. Map the InputEmpID input data field to the EMPLOYEE_ID output data field.
  14. Finally, map the ORG_ASSIGNMENT return structure to the JobInfo structure. (Both of these values are found near the bottom of the Mappings categories.)
  15. Go back to the K2 Service Object Designer and Save your project.
  1. Open the K2connectDev project in Visual Studio if it is not already open. Open the Solution Explorer, then open the EmployeeDataServiceObject Service Object.
  2. Use the K2 Service Object Designer treeview to navigate to the BAPI_EMPLOYEE_GETDATA BAPI. You may need to provide credentials if you are working with the Single Sign On configuration that was set up in Part 2. The SAP system credentials are:
    Username: K2Learning
    Password: K2pass!
  3. Right-click the GETDATA method and test it with the K2 connect Test Cockpit. Load the interface, then enter the following parameters (only):
    DATE: CHECKED - current date
    EMPLOYEE_ID: 1037
  4. Execute the method, then review the contents of the ORG_ASSIGNMENT return structure.

    5. In the next few steps, we will add a new service method that will retrieve the employee's job data. To give you more insight into structures, we will manually define the method.

    Specifically, we are going to retrieve the job data as a separate service call because we did not need the content as part of the EmployeeData service. If we don't need the content returned, then it doesn't make sense to include it in the service call.

  5. In the Service Object Design canvas, click Add Service. Rename the new service to
    JobData
    then press <ENTER> to commit the change.

    6. Recall that we previously added the 'list' and 'read' methods by dragging them from the BAPI list of methods into the EmployeeData service container. This time, we will define a custom method, essentially building the method from scratch.

  6. Click the Add Custom Method link located just below the JobData service title. Change the Function Name to
    ReadJobDataByEmpID

    7. Next, we'll add and configure the parameters we need for our service call. In our case, we will add a date and an employee ID for our parameters.

  7. Click the Add Parameter link. Change or confirm the following parameter values:
    Name: InputDate
    Declarer: Flat
    Datatype: DateTime
    Direction: In

    8. This is the standard date parameter expected by many SAP BAPIs. We will map these input parameters to the BAPI's input parameters manually.

  8. Click the Add Parameter link to add our employee ID input parameter. Change or confirm the following values:
    Name: InputEmpID
    Declarer: Flat
    Datatype: Int64
    Direction: In
  9. Save your project.
  10. From the K2 Service Object Explorer treeview, drag, then drop, the BAPI_EMPLOYEE_GETDATA method into the Internal Functions pane.

    11. Now we will manually define the structure we need for the employee's job data. Recall that a structure contains a number of properties, which we will define as well.

  11. Click on Add Parameter (back in the Function Interface pane). Name the new parameter
    JobInfo
    then for the Declarer value, select <New>.
  12. Name the new structure
    JobInfoStructure
    then click the Copy from Template option found in the Structure Definition pane.
  13. In the Template drop-down list, select BAPIP0001B, then Clear All of the pre-selected properties. CHECK the following properties to include in our custom structure: COMP_CODE, JOBTXT, ORGTXT, POSTXT.
  14. Click OK to save the selections. (See image above for reference.)
  15. In the Structure Declaration pane, rename each property with a friendly name.
    PropertyNew Friendly Name
    COMP_CODECompanyCode
    JOBTXTJobTitle
    ORGTXTDepartment
    POSTXTPosition
  16. Click Go Back to return to the Function Interface screen. Change the Declarer for the JobInfo parameter to Structure, then change the DataType to JobInfoStructure and finally, change the Direction to Out.
    Let's break this down a bit. Very simply put, a structure returns multiple properties for a single parameter. Because there could potentially be multiple datatypes within a single structure, we essentially create our own custom datatype (JobInfoStructure) that includes the package of properties and their datatypes. The flow of data is where the Direction comes in. We have 'in-coming' (In) parameters that are coming into SAP as filtering criteria, then we have 'out-going' parameters (Out) that are returning content, based on the filters.

    17. Now we need to define the mappings so that K2 connect knows how to pass the manual parameters we defined into and out of the BAPI.

  17. Click the Data Mapping link to begin.

    18. Data mapping links the 'input' data fields with the 'output' data fields or structures. The left side contains the data structure for the filter, or in-coming data value. The right side contains the structure for the BAPI, or out-going data value. We map the two together by connecting one side to the other.

  18. Click, then drag the InputDate parameter over to the right side so that it is mapped to the DATE() property.
  19. Repeat the process once again for the InputEmpID parameter and map it to the EMPLOYEE_ID property.
  20. Scroll down to the last section in the left-side column. Locate the Ref node. Map the ORG_ASSIGNMENT structure to the JobInfo structure found in the last node on the right-side.
  21. Click Go Back, the Go Back once again. Save your project.
Step 5a Review

This last step was a long complicated procedure, but there is a reason we wanted to show you this approach. First things first: for this particular BAPI, we could have dragged and dropped the BAPI into the Service and selected the parameters and properties like we did before, so strictly speaking this longer procedure wasn't necessary for this particular BAPI. However, there may be times when you want to call multiple BAPIs in the same method, when you want to write some code as a completely custom function, or you may want to write some code to transform a parameter from one type into another type. In those cases you will need to manually define custom methods, define the parameters, design the structures and complete the mappings. We want you to be familiar with this approach so you know how to define these manually.

In Step 5b, we will add another new service, then configure the method to return the company details for an employee. For this step, we will return to the simple drag and drop process for adding new methods.

Step 5b Tasks

  1. Start by creating a new filter in the Rfc / Bai Explorer with the following details:
    Filter Name: Company BAPIs
    Function: BAPI_COMP*
  2. From the new filter, run the BAPI_COMPANYCODE_GETDETAIL method using the K2 connect Test Cockpit, then review the results in the COMPANYCODE_DETAILS table.
  3. Open the structure details for the COMPANYCODE_ADDRESS structure, then Clear All of the properties. We won't be using them in this exercise.
  4. Add a New Service and name it CompanyData.
  5. Add the BAPI_COMPANYCODE_GETDETAIL method to the new service.
  6. Change the Function Name to ReadCompDataByCompCode.
  7. Show the Structure for the COMPANYCODE_DETAIL structure.
  8. Rename the Function to CompanyData.
    then select the properties below to be included in this structure. Give each property a friendly name as well.
    PropertyFriendly Name
    CITYCity
    COMP_CODECompany
    COUNTRYCountry
  9. Return to the Function Interface, then give the following two entries a friendly name:
    COMPANYCODE_DETAIL: CompanyData
    COMPANYCODEID: InputCompanyCode
  10. Return to the Service Object Designer, then Save your project.

To get us started, we will take a minute to locate and run the method we need to return company details.

  1. In the K2 Service Object Designer explorer, add a new filter under the Rfc / Bapi Explorer node. For the filter details, enter the following:
    Filter Name: Company BAPIs
    Function: BAPI_COMP*


  2. Expand the new company filter and locate the BAPI_COMPANYCODE_GETDETAIL BAPI method. Run the method in the K2 connect Test Cockpit using 1000 for the Company Code and reviews the results returned for the COMPANYCODE_DETAILS table. We specifically will be working with the COMP_NAME, CITY AND COUNTRY properties.
  3. Add a new Service called
    CompanyData
    then press <ENTER> to commit the new name. Drag the BAPI_COMPANYCODE_GETDETAIL method into the service.

  4. Change the Function name to
    ReadCompDataByCompCode
  5. In the Function Interface screen, click Clear All. Notice that the fields aren't un-checked, because they are either structures or required input parameters. We need to "step into" each BAPI structure and select the fields to return.
  6. Click on COMPANYCODE_ADDRESS and then Show Structure.
  7. Click Clear All to remove the address details. In the real world, you would most likely want to include address details, but for our sample, we will not be using any of the address details. Click Function Interface to return to the previous screen.
  8. Click the COMPANYCODE_DETAIL structure and select Show Structure.
  9. Rename the Function to
    CompanyData
  10. Clear All of the pre-selected properties, then select the following: CITY, COMP_NAME and COUNTRY.
  11. Use the table below as a guide to give each of the properties friendly names.
    PropertyFriendly Name
    CITYCity
    COMP_CODECompany
    COUNTRYCountry
  12. Click Function Interface to return to the landing page.
  13. Rename the COMPANYCODE_DETAIL structure to
    CompanyData
  14. Rename the COMPANYCODEID property to
    InputCompanyCode
  15. Click Go Back to return to the Service Object Designer, then Save your project.
Step 5b Review

In this step, we added an additional method to return company details for the employee. When we eventually publish this service object, this method will become a separate K2 Service Object Method. (In a later lab exercise, we will add this Service Object method to our existing Employee SmartObject Read operation.)

In the next part, we will add another method to return the employee's communication data as an XML property.

In this step, we will add a method to return an employee's communication details. We will return the email address as an XML property. When working with XML properties, we will define custom methods so that we can manage how the data is treated.

Step 5c Tasks

  1. Add a new custom method to the EmployeeData service object. Name the new function ReadEmpCommicationsasXML.
  2. Add two new input parameters (input date and input employeeID) using the table below as a guide for the values.
    NameDeclarerDataTypeDirection
    InputEmpIDFlatInt64In
    InputDateFlatDateTimeIn
  3. Add the BAPI_EMPLOYEE_GETDATA BAPI to the Internal Functions.
  4. Add a third new parameter and name it
    CommunicationXML
    then generate a New Declarer. Name the function
    CommunicationXMLStructure
    then mark the structure as an XML Property.
  5. For the Structure Definition, select the Copy from Template option. Change the Template to BAPIP0105B then select the following options (only): USERID, USERTYPE, USERID_LONG (We don't need friendly names for these.)
  6. Go Back to the Function Interface screen and change the Declarer to Collection and the Direction to Out. Change the Datatype to CommunicationXMLStructure.
  7. The next step is the map the input parameters. On the Function Interface screen, access Data Mappings. Map the InputDate to the DATE() input. Map the InputEmpID to the EMPLOYEE_ID input.
  8. Finally, map the COMMUNICATION Ref to the CommunicationXML (Out) parameter.
  1. On the K2 Service Object Designer canvas, locate the EmployeeData service, then select Add Custom Method.

  2. Name the new function
    ReadEmpCommunicationsasXML
  3. Click on Add Parameter to add two new input parameters for the input date and the employee's ID. Use the values in the table below as a guide.
    NameDeclarerDataTypeDirection
    InputEmpIDFlatInt64In
    InputDateFlatDateTimeIn
  4. In the Rfc / Bapi Explorer expand the Employee BAPIs node, then drag the BAPI_EMPLOYEE_GETDATA BAPI into the Internal Functions pane.
  5. In the Function Interface, click Add Parameter. Name the new parameter
    CommunicationXML
    then select <New> for the Declarer.
  6. Change the Structure Name to
    CommunicationXMLStructure
    then CHECK the option to mark this structure as an XML property.
  7. In the Structure Definition pane, select the Copy from Template option.
  8. Change the Template menu to BAPIP0105B, then select the following properties: USERID, USERTYPE, USERID_LONG
  9. Click OK, then Go Back to the Function Interface screen. (We don't need to rename any of these properties.)
  10. Change the Declarer to Collection and the Direction to Out. Change the Datatype to CommunicationXMLStructure.

    11. Now we need to define how the parameters are sent to and retrieved from the BAPI by configuring the data mapping.

  11. Click the Data Mappings link.
  12. Using the same process as we did configuring the JobData service, map the InputDate input parameter to the DATE() input. Map the InputEmpID to the EMPLOYEE_ID input.
  13. Then map the COMMUNICATION node from the Ref node to the CommunicationXML - Out property. (Both of these located at/near the bottom of their parent nodes.
  14. Click Go Back twice to return to the K2 Service Object Designer. Confirm the new ReadEmpCommunicationsasXML method appears in the EmployeeData service.
  15. Save your project.
Step 5c Review

In this step, we added another method to return the employee's COMMUNICATION info as an XML property. The XML option is useful when the structure returns multiple items, or when you want to manipulate the XML property yourself in code.

In this example, the employee could potentially have multiple e-mail addresses, so that's why are returning this property as a XML property.

When using XML properties you usually need to define custom functions so that you can control the XML property. If the XML contains a collection of items, you need to map it to a Collection declarer.