Publishing and Updating an Existing Service Object and SmartObject

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.

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.