Part 3: Developing with K2 connect

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.
   

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.
   

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
   

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

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.
    

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.

    Property	New Friendly Name
    COMP_CODE	CompanyCode
    JOBTXT	JobTitle
    ORGTXT	Department
    POSTXT	Position

    
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.
    

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.

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.

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.

    Property	Friendly Name
    CITY	City
    COMP_CODE	Company
    COUNTRY	Country

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.

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.

   Name	Declarer	DataType	Direction
   InputEmpID	Flat	Int64	In
   InputDate	Flat	DateTime	In

   
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.
    

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.

1. In Visual Studio, publish the EmployeeDataServiceObject.
   
2. Click Yes to confirm you want to replace the existing Service Object.
   
3. You should see a dialog that states the Service Instance was refreshed. Close the confirmation notice.
   

We'll take a minute now to test the update Service Object and SmartObject using the SmartObject Service Tester.

4. Launch the SmartObject Service Tester utility. (C:\Program Files (x86)\K2 blackpearl\Bin\SmartObject Service Tester.exe)
5. Expand the ServiceObject Explorer and navigate to our K2 connect Service Object. We want to locate the EmployeeDataServiceObject, then review the properties and methods it contains.
6. Confirm the new properties and methods we added are shown.
   One thing to note is that importance of friendly names. You should see now how much of a difference it makes for a person developing the SmartObject to be able to easily distinguish the names and purposes of the properties they are working with.
   

Minimize the SmartObject Service Tester. We will use it again in a later step.

In the next few steps, we are going to edit the existing SmartObject and extend the 'read' method to include the additional methods that we added to look up the job information and the company information.

When using multiple BAPIs in a sequence (when those BAPIs need to transfer data between each other such as an employee ID) we need to expose each method as a separate Service Object, then 'chain' the methods together inside of the SmartObject.

7. Return to Visual Studio and open the SAPEmployees SmartObject.
   
8. Click to highlight the ReadEmpByEmpID method, then click Edit.
   
9. On the wizard landing page, CHECK the option to Run the wizard in Advanced Mode, then click Next.
   
10. Change the method Type to Read and confirm the Transaction is set to Continue, then click Next.
    
11. On the Configure Method Parameters (Optional) screen there are no changes, so just click Next.
12. On the Service Object Methods screen, we will add the two new service objects we created previously. Click Add.
    
13. Use the Context Browser to navigate to the ReadJobDataByEmpID method of the EmployeeDataServiceObject Service Object. Drag, then drop, the method into the Service Object Method text box.
    

Notice the Input Property and Return Property values load. We need to map the input parameter to the SmartObject method to establish a communication link between the two.

14. Click to highlight the p_InputDate input parameter. Click Assign. Map it to the existing p_InputDate Parameter for the SmartObject method.
    
    
15. Repeat this step and Assign the p_InputEmpID to the existing p_InputEmpID Parameter for the SmartObject method.
    

Now we need to create SmartObject properties for the Return values. We cannot map these to existing properties because they do not exist in the SAPEmployees SmartObject. We will create new properties instead.

16. Click to highlight the JobInfo_CompanyCode Return property, then click Assign. Click Create. Confirm (or enter) the JobInfo_CompanyCode Property Name. Click OK twice to return to the Edit Service Object Method screen.
    
17. Repeat these steps to create properties for the remaining Return Property values.

    Return Property Name	Bound to SmartObject Property
    JobInfo_JobTitle	SAPEmployees.JobInfo_JobTitle
    JobInfo_Department	SAPEmployees.JobInfo_Department
    JobInfo_Position	SAPEmployees.JobInfo_Position

    
18. Click OK to save the new method.

We've just added the first of the additional methods required to read additional employee details. What is especially significant here is that we retrieved the employee's CompanyCode as part of this method, so now we can use that property to call the ReadCompDataByCompCode method and retrieve information about the company that the employee works for. We will use the CompanyCode as the input parameter for retrieving data from the company details method.

19. Begin by selecting Add to attach a new Service Object Method.
    
20. Using the Context Browser, navigate to, then Add, the ReadCompDataByCompCode method to the Service Object Method text box.
    
21. Just like before, we need to assign a property to the p_InputCompanyCode input parameter. Click to highlight the p_InputCompanyCode parameter, then click Assign. Change the Map To value to Property, then select the JobInfo_CompanyCode Name from the drop-down list.
    
22. Repeat the step above and Assign each of the Return Properties to new SmartObject properties. Remember to Create a new property with the same name value as the Return Property. (Highlight return value > Assign > Create)

    Return Property Name	Bound to SmartObject Property
    CompanyData_Company	SAPEmployees.CompanyData_CompanyName
    CompanyData_City	SAPEmployees.CompanyData_City
    CompanyData_Country	SAPEmployees.CompanyData_Country

    
23. Click OK to accept the property mappings. Click Next, then Finish to complete the SmartObject Method wizard.

We can see now that the ReadEmpByEmpID method now calls three separate Service Object methods to build a collection of detailed employee information. This method can now retrieve employee personal details, the employee's job details and the employee's company details.


24. Save your project.

Our final step in building the SmartObject properties is to add a property to capture the returned XML employee communication data. Generally, we want to return XML properties as 'Memo' data types, but we can manually map XML properties to SmartObject properties as well.

25. In the SmartObject Properties pane, click Add.
    
26. Create a new SmartObject Property called
    CommunicationXML
    then make its data Type a Memo.
    
27. Edit the ReadEmpByEmpID SmartObject Method.
    
28. Click through the Next buttons until you get to the Service Object Methods screen. Click Assign, then use the Context Browser to navigate to and Add, the ReadEmpCommunicationsasXML method.
    
29. Assign the p_InputDate input parameter to the existing SmartObject parameter with the same name. Assign the p_InputEmpID input parameter to the existing SmartObject parameter with the same name.
    

Now we need to bind the CommunicationXML Return Property to the new SmartObject property 'Memo' property.

30. Click to highlight the CommunicationXML Return Property. Click Assign. On the XML Property Mapping screen, click Add.
    
    In the Add XML Property Mapping screen, select the connect node, then set the XML Mapping Type to Xml. Set the Map To value to Property. Select the CommunicationXML [Memo] property we created earlier from the Name drop-down list. Click OK twice to complete this mapping.
    
31. Back on the Edit Service Object Method screen, confirm the CommunicationXML property is mapped to the SAPEmployees SmartObject. Click OK, then Finish to complete setting up the method to return the XML property.
    
32. Save and then Deploy the updated SAPEmployees SmartObject. When the deployment has completed successfully, you can close Visual Studio. We have completed all of Visual Studio steps for this tutorial.
Known issue. In some versions of Visual Studio, you will see an error when trying to deploy the updated SmartObject. The work-around is to open K2 Studio (Start > scroll to K > K2 > K2 Studio), open the K2connectDev project (navigate to where you saved it), then deploy the project. Continue with the tutorial.

Step 6a Review

We have now updated the SAPEmployees SmartObject to call the additional methods that return more detailed information about the employee. Remember each method is a separate call to different SAP BAPIs, so this way, we can build up a composite SmartObject which returns data from different SAP BAPIs, passing in return properties from one method as the input parameters for a subsequent method.

Remember also that we could have added any other Service Method as an additional method, so you could have included data from any other system as part of the SAPEmployees detailed information. For this learning module, we are only using data from SAP, but the principle is the same: we can "chain" multiple service method calls in a single SmartObject method call to build up a SmartObject that combines data from different systems, (as long as we define the sequence of operations correctly and we pass values between method calls correctly).

We also added a new XML property to return a BAPI Structure as an XML property rather than "flattening" it to a collection of SmartObject properties.

In the step part we will test our updated SmartObject.

1. Open the SmartObject Service Tester once again. Expand the SmartObject Explorer and navigate to the ReadEmpByEmpID method for the SAPEmployees SmartObject. Right-click the method and select Execute Method.
   
2. Recall that we have two parameters that are required: the input date and the employee's ID. Locate the p_InputDate input parameter, then CHECK the box to the left of the date value, then confirm the date value reflects the current date. For the p_InputEmployeeID value, enter
   1037
   then click Execute.
If you get an error, restart the K2 service and then try to execute the method again. This error can happen when the SmartObject definition was updated but the K2 service is "holding on" to the old definition in memory.

3. You should see a list of the additional properties (JobTitle, Department, Company and so on) along with an XML property containing the email records for the employee.

   
   

Step 6b Review

In this step, we returned to the SmartObject Service Tester and confirmed our additional methods (and XML property) have been configured properly. At this point, we are now ready to use the SmartObject within K2 Workflows and SmartForms.

The next step is optional if time allows, but it nicely demonstrates the use of our extended SmartObject in a SmartForm View.

1. Launch K2 Designer. (Start > scroll too K > K2 > K2 Designer)
2. Click BROWSE on the landing page. Navigate to the K2connectDev node, then expand the SmartObjects folder. Right-click the SAPEmployees SmartObject, then select the option to Design View.
3. On the General screen, Name the new View
   Employee Details View
   then change the Category to the Views category, then confirm the View Type is an Item View. The Data Source should already show the SAPEmployees SmartObject (remember, we designed the View from this SmartObject). Click CREATE.
   
4. Select the option to Create Labels and Controls.
The Create Labels and Controls option allows you to select which controls you want on your view. This option is often used when designing a view from a SmartObject. The Create Layout Table Only option creates a blank table where you can individually add the controls you need.
5. On the Create Labels and Controls settings screen, leave the default number of Columns at 2. Select all of the fields to Include on the View in Display Only mode. Leave the remaining settings as is and click OK.
   
6. Locate the Communication XML control (it should be in the last row) and extend its table cell so that it is merged with the cell to the right. (Click once in the first cell, then click the Merge Cell to the Right icon found in the View Canvas menu bar.)
   
   
7. To save time, we will not format the View's styling or layout. Click FINISH to complete the View build. The Finish button can be found new the lower right corner of the View design canvas.

We have a few more steps to complete before we can test our expanded SmartForms configuration. Next, we will generate a Form from the SearchEmpByLastName list View. Then we will add a Rule for when a row in the list View is clicked. We will configure this Rule to populate the Employee Details View and pass the Employee ID from the selected row to the Details View.

8. From the Category Browser, Right-click the SearchEmpByLastName View and select the option to Generate Forms.
   
9. Change the Name of the Form to
   Employee Data
   then CHECK the option to Save and edit the Form. UNCHECK the option to Refresh the List View when the Form loads. Click OK to continue.
   
10. The Form will now open with the design canvas in the LAYOUT screen. We will now add the rules for populating the Employee Details View. Click the RULES tab found in the breadcrumb bar. On the Rules screen, click Add Rule.
    
Rules consist of events, conditions and actions. A valid rule contains at least one action.

• Events define when the rule should run, such as when a button is clicked, or when the form loads. (Events are optional, you can define "event-less" rules that you can call from other rules.)
• Conditions define whether the rule should run. If the criteria are true, continue the rule, and if the criteria are not met, stop the rule. For example, a condition might evaluate a form to confirm that required fields have content. (Conditions are optional - not all rules will require conditions.)
• Actions define what the rule should do. For example, show a message, start a workflow, or enable a form field. Rules can contain multiple actions that are run in sequence or in parallel.
11. Confirm that the Events tab is active. Locate the When a View raises an event event and click it once to add it to the rule definition pane. Since we only have one View on this Form, the View name should already indicate the SearchEmpByLastName View. Click the select method link and select the List item click method.
    
12. Now switch to the Actions tab. We've told K2 the event is when a list item on this view is clicked, now we need to tell K2 what to do after the list item is clicked. (In our case, we don't need a condition, but if you were to have conditions, you would add them prior to adding the action.)
13. On the actions screen, locate the Open a subview and execute a method action (under the Subview Interaction heading) and click it once to add it to the rule definition pane.

This action is telling K2 to open another view as a subview (think pop-up window), then execute a method. In our case, the method will be to populate the subview (the Employee Details View) with the details of the employee that was selected from the list. We will configure the method to pass the employee's ID from the list item to the subview so that K2 knows which employee record to retrieve for the details view.


14. Click the select View link the, navigate to, and select, the Employees Details View. Click the select method link and select the ReadEmpByEmpID method that we previously created in Visual Studio.
15. Now we need to map the input parameters that are required for this method. Recall that they consist of the p_InputDate and the p_InputEmployeeID properties. Click the (configure) link.
16. Click the Input Mappings tab. Expand the Context Browser, then drag the System Values > Current Date into the p_InputDate Parameter.
17. Now we need to add the employee ID parameter. We will find this value located in the Employee Data (Form) node, then SearchEmpByLastName (View), then SAPEmployees SmartObject, then Employee Info_Employee Number property. Drag this property into the p_InputEmployeeID Parameter.
    
18. Click FINISH to complete the subview method. Click OK to complete the Rule configuration. Finally, click FINISH once again, to complete the Form build.

To close out this tutorial, we will test our extended configurations.

19. From the Category Browser, click once on the Employee Data Form. Click the Runtime URL link found in the Properties pane.
    
20. The Employee Data Form will open in your browser. Search for wildcard value
    B*
    
21. When the list of employees is returned, click on one of the records. The subview should pop up with that details from the employee selected.
    

Step 6c Review

In this step, we tested the extended Service Object Method configurations. We generated an item View, then a Form. We configured Rules that will populate a subview (the Employee Details View) with the extended methods (job and company information) when a row is clicked in the list View.

What is significant here is that we are able to use multiple sources of data and return it to one location. While we are using data from an SAP system, we don't have to. We could "mix and match" data from multiple data source types and return them in one SmartObject.

Last, if you are new to SmartForms, this step gave you a nice introduction to Rules: Events and Actions and how you can configure them to provide additional information to your users in a subview format.