Part 2: Testing the K2 connect Service Object and K2 SmartObject

This tutorial is a continuation of Configuring a K2 connect Destination. If you have not already completed Configuring a K2 connect Destination, please do so now before beginning this tutorial, as we will be using the destination for the exercises in this tutorial.

Using the same K2 connect destination that we configured in Configuring a K2 connect Destination, we will explore the available BAPIs in the SAP system, then test a specific BAPI with the K2 connect Test Cockpit. Essentially, we just want to check that our SAP environment is visible and that we can interact with BAPIs on the target SAP environment. From here, developers would normally take over and create Service Objects and SmartObjects for the SAP system (and that is expanded on in Part 3). For testing purposes, however, it is a good idea to generate a SmartObject so that we can verify that the entire SAP-connect-blackpearl stack is working as expected.

For this exercise, we will use the BAPI_EMPLOYEE_GETDATA BAPI. We will first test the BAPI using the K2 connect Test Cockpit. If the test is successful, we will create a new K2 connect Service Object, then publish it to a K2 connect server. We will generate a SmartObject, then use the SmartObject Service Tester to confirm our SAP connection is behaving as we expect it to.

We begin by exploring the business objects that are returned with our SAP destination.

BAPI stands for Business Application Programming Interface and is provided by SAP as a means to access SAP functions. Learn more about BAPIs.

Step 1 Tasks

  1. In Visual Studio, open the K2 Service Object Designer.
  2. Navigate to the K2LearningSAP destination that was created in Part 1. (The destination is located within the ERP Connect node.) Expand the K2LearningSAP node using the predefined user credentials we configured in Part 1.
  3. Navigate to the GETLIST method, found in the following directory: (Business Objects > Application Components > Personnel Management > Personnel Administration > Employee > Methods > GETLIST (BAPI_EMPLOYEE_GETDATA))
  4. Launch the K2 connect Test Cockpit. Load the interface and clear all of the input options. Next, set the following input parameters:
    DATE: Use the current date
    LASTNAME_M: A*
    Execute the method.
  5. Open the details for the PERSONAL_DATA Output and confirm there are results returned.
  1. Launch Microsoft Visual Studio. (Start > scroll to V > Visual Studio 2015)
  2. From the Visual Studio 'View' ribbon tab, select K2 Service Object Designer.
  3. In the K2 Service Object Designer tree, expand the ERP Connect node until the K2LearningSAP destination is visible. This is the destination we created in Part 1.
  4. Expand the K2LearningSAP destination. Once again, we are prompted for credentials (as we were when we tested the destination connection in Part 1). Because the username and password were embedded in the connection string, we can once again CHECK the option to use Predefined User Credentials. Click OK to continue.

    5. For our exercises, we will be primarily using the BAPI_EMPLOYEE_GETDATA method. In this step, we will browse to this method, then test it using the K2 connect Test Cockpit. From here, we will be able to view the actual data that is returned with this call.

  5. Using the image below as a guide, browse to the GETLIST method.
    (Business Objects > Application Components > Personnel Management > Personnel Administration > Employee > Methods > GETLIST (BAPI_EMPLOYEE_GETDATA))

    6. Next, we will test the method using the K2 connect Test Cockpit. If we have results returned for this method, our test will be successful!

  6. Right-click the GETLIST method, then click K2 connect Test Cockpit.
  7. The K2 connect Test Cockpit opens. Click Load Interface. This option will load both of the input (parameters) and the output (results) panes.

    8. First, we want to provide some input parameters so that we have specific results returned. We will provide the input Date (which will be the current date) and then a wildcard parameter for the Last Name.

  8. Begin by clicking the Clear All option in the Input pane. Next, CHECK the box for the DATE and confirm the current date is shown as the default value. Scroll down and CHECK the box for the LASTNAME_M option and enter
    A*
    as the parameter value. Click Execute when you have set the input parameters.
  9. Wait a few seconds, then click the Show Details link for the PERSONAL_DATA return in the Output pane. You should see a table with results returned.
    If there are no results, return to the Input pane and confirm the checkboxes for the DATE and LASTNAME_M are CHECKED in addition to parameter values being entered. You can also collapse the Input pane to provide more room for the Output table.
  10. Close the K2 connect Test Cockpit, but leave the K2 Service Object Designer and Visual Studio open.
Step 1 Review

In this step, we tested our K2 connect destination using the K2 connect Test Cockpit tool found in Visual Studio. This tool allows us to enter specific parameters that we want for our method call and confirm the results that are returned. This step is significant in that we now know that our K2 connect destination is communicating in other software, such as Visual Studio. This opens the door for us to create new Service Objects and SmartObjects, leveraging the methods (and returned data) we want from a SAP system.

In this step, we will create a new Visual Studio project, then add a K2 connect Service Object to the project. We will add the BAPI_EMPLOYEE_GETDATA method to the Service Object and configure specific functions and properties we want returned. Finally, we will auto-generate a SmartObject from the Service Object and publish them to the K2 Server.

Step 2 Tasks

  1. In Visual Studio, create a new K2 Empty Project and name it K2connectTest.
  2. Add a K2 connect Service Object and name it K2connectEmpData.
  3. Add the GETLIST method (from the previous step) to the Service Object, then add the following functions from the GETLIST method: Date(), LASTNAME_M, PERSONAL_DATA, RETURN()
  4. Complete the Service Object by configuring the following properties for the PERSONAL_DATA function: BIRTHDATE, FIRSTNAME, GENDER, LAST_NAME, NATIONAL, PERNO

    5. HINT: Click the PERSONAL_DATA function to highlight it, then select Show Structure to access the list of properties for that function.

  5. After selecting the functions and properties, return to the Service Object Designer canvas. In the K2 blackpearl Settings, generate a SmartObject for the K2connectEmpData Service Object. (Do not use the properties as parameters.)
  6. Publish the K2connectEmpData Service Object.
  1. Still in Visual Studio, create a new, K2 Empty Project (you may need to select the K2 Template in the left column to expose the K2 project templates). Name the new project
    K2connectTest
  2. In the Solution Explorer, add a new K2 connect Service Object to the project. Right-click the K2connectTest project, then select Add, then New Item.
  3. When the Add New Item screen opens, select K2 connect Service Object from the installed templates. Name the Service Object
    K2connectEmpData
    (If you do not see the K2 connect Service Object option, use the Search box to locate the K2 installed templates.)
    There are a number of limitations on the naming of Service Objects. For example, you cannot use a number to start the name or include periods in the name. If necessary, use underscores to separate words.

    4. Now that we have our Service Object in place, we will add the BAPI_EMPLOYEE_GETDATA (GETLIST) method. After adding the method, we will configure the functions and properties we want returned.

  4. Navigate to the BAPI_EMPLOYEE_GETDATA method once again if you have collapsed the ERP Connect nodes. (See Step 1 (e) for the treeview path if necessary.)
  5. Drag, then drop, the GETLIST method onto the K2 Service Object Designer canvas.
  6. Click the GETLIST link to open the Function Interface screen. (See the image above for the GETLIST link reference.)
  7. Click the Clear All link to clear the pre-selected properties. Select the following properties:
    DATE()This is the input date required for most SAP BAPIs.
    LASTNAME_MThis is the input parameter to search by the last name.
    PERSONAL_DATAThis is the structure of personal data returned by the BAPI. This property contains additional properties as well.
    RETURN()This is the return data (success message) returned by the BAPI.

    8. We can also "drill-down" into some functions, where we can expose the properties of the function. Think of this like a treeview. We can expand a topic and see more topics. We can view the structure of a function and view the properties that make up the structure. We can also select specific properties that we want included in our Service Object method call. In our case, we are going to configure the PERSONAL_DATA function so that only a specific set of its properties are returned.

  8. Click the PERSONAL_DATA function to highlight it. Notice that the Show Structure option appears in the upper right corner of the pane. Click Show Structure.
  9. Select Clear All in the Structure Declaration pane to clear the default property selections. Just as we did previously, CHECK the following properties so that only they are included with the PERSONAL_DATA function: BIRTHDATE, FIRSTNAME, GENDER, LAST_NAME, NATIONAL, PERNO
  10. Click the Go Back link in the upper right corner of the Service1 pane to complete the configuration of the GETLIST method.
  11. Save your K2 connect Service Object.

    12. Next we will auto-generate a SmartObject from the K2connectEmpData (Service Object). This is a quick and convenience option to use, especially when testing. In the real world, the best practice would be to manually create the SmartObject so that you have complete control over the properties and naming conventions.

  12. Click the K2 blackpearl Settings button located in the K2 Service Object Designer toolbar. CHECK the box to Generate SmartObject. Confirm that the option to Use Properties as Parameters is UNCHECKED.
  13. Click the Publish Service Object link to commit the Service Object and SmartObject to the K2 Server.
  14. Confirm that you see the SmartObject generated dialogue.
  15. Save your project.
Step 2 Review

In this step we created a K2 Empty Project in Visual Studio and added a K2 Service Object. We added the GETLIST method that we exposed with the SAP destination created in Step 1. We then edited the functions and selected a few functions that we will work with. We also edited the properties for the PERSONAL_DATA function. Finally, we generated a SmartObject from the K2connectEmpData Service Object and published it to the K2 Server.

In Step 1, we tested the SAP destination connection using the K2 connect Test Cockpit. Now, we will test the SmartObject that we created in Step 2 using the SmartObject Service Tester. This step is significant in that we are testing the SAP interaction from a K2 blackpearl perspective (versus K2 connect). With a successful test here, we will then be able to leverage the properties and methods returned by the SmartObject in other K2 artifacts such as SmartForms and K2 Workflows.

Step 3 Tasks

  1. Using the SmartObject Service Tester, execute the GETLIST method for the K2connectEmpData SmartObject. CHECK the p_DATE() property and confirm the default value is set as the current date. CHECK the p_LASTNAME_M property and for the value, enter A*, then confirm you have results returned.
  1. Launch the SmartObject Service Tester utility. Create a shortcut link on the desktop if necessary. You will be using the tester throughout the tutorial. (C:\Program Files (x86)\K2 blackpearl\Bin\SmartObject Service Tester.exe)

    2. If you are not familiar with the SmartObject Service Tester, we'll take minute now to give you a brief tour in the NoteBox below. If you are familiar with the utility, feel free to move on to the next step.

    First, notice there are two nodes, the ServiceObject Explorer and the SmartObject Explorer.


    The Service Object represents the properties and methods that have been "discovered" as part of the interaction with a specific data source. K2 uses Service Brokers as the connection strings (simply put) to the data source. K2 can "talk" to a number of data source types, such as CRM, SQL, SharePoint lists and using K2 connect, SAP systems. We can also create our own custom brokers as well. As we demonstrated in Step 2, we created a Service Object in Visual Studio that leveraged a K2 connect destination to a sample SAP environment. We then created a SmartObject from the Service Object. The SmartObject simply allows us to interact with the methods and properties in other K2 elements, such as SmartForms and K2 Workflows.

    Expand the ServiceObject Explorer node. Expand the K2 connect Service node, then the Connect Service for dlx node. (If working in your own environment, this value will likely be different.) Finally, expand the Connect Objects node and observe that the K2connectEmpData Service Object we previously created (and published) is shown.

    Now expand and explore the Properties and Methods for this Service Object. Notice the Properties are the PERSONAL_DATA properties we selected. The Method is the GETLIST method we added when we created the Service Object.

    Switch to the SmartObject Explorer and navigate to the SmartObject we auto-generated from this Service Object. The SmartObject node will be the Visual Studio project name, in our case K2connectTest. Once again, expand and explore the Properties and Methods for the K2connectEmpData SmartObject.

    To test our K2connectEmpData SmartObject, we will execute the GETLIST method and confirm we have results returned. Once we have confirmed the SmartObject is interacting with the SAP system, we are ready to use it in our K2 applications!

  2. Right-click the K2connectEmpData SmartObject and select Execute SmartObject.
  3. The Execute SmartObject settings screen opens. CHECK the box for the p_DATE() property and confirm the default date value is the current date. For the p_LASTNAME_M value, enter
    A*
    then click Execute. Confirm you have results returned in the Results pane located at the bottom of the screen.
    K2 automatically added the "p_" prefix to indicate the property is an input parameter.
    4. Errors? If you saw errors instead of results returned, there are a couple of configurations to check. If you see an error that indicates the password is missing, return to the K2 connect Administration console and select the K2 blackpearl Settings option. Confirm the SAP Authentication method 'Static Credentials' is selected and there is a value for both the username and the password. If you have to enter either of these values, you must refresh the Service Instance once again. Back in the SmartObject Service Tester, click the Refresh All link at the top of the screen to pass the login credentials to the Tester.

    A second possible error can occur if the destination is not set as the default destination. The K2 connect Server may not start properly if there is no default destination.
Step 3 Review

In Step 3, we tested the K2connectEmpData SmartObject by executing its GETLIST method, using the SmartObject Service Tester. This is significant step in that a successful test demonstrates that the K2 connect destination to the SAP environment is now visible to K2 blackpearl. With the K2connectEmpData SmartObject exposed in K2 blackpearl, we can now leverage the properties and methods (discovered in the SAP system) in other K2 elements such as SmartForms and K2 Workflows.

In this step, we will modify the SAP authentication and change it from static credentials to K2 SSO. K2 Single Sign-On caches the user's credentials and passes them through to SAP at runtime. Users can maintain their own SAP credentials via K2 Workspace. To test this concept, we will change the SAP authentication and refresh the service instance. Then we will refresh the service object in the SmartObject Service Tester and confirm the authentication change has migrated over to the utility settings. To complete the SSO configuration, we will access K2 Workspace and configure the SSO settings to cache our credentials.

Step 4 Tasks

  1. In the K2 connect Administration console, edit the Settings for the K2LearningSAP Destination and remove the username and password attributes from the Connection String. The string should now read: ASHOST=23.23.150.97 SYSNR=KR3 CLIENT=900
    You do not need to test the connection at this point.
  2. Edit the K2 blackpearl Settings and change the SAP Authentication from Static Credentials to K2 SSO. Refresh the Service Instance and allow K2 to restart the K2 connect server.
  1. Open the K2 connect Administration console (if it is not already open).

    2. Our first action is to remove the embedded login credentials from the destination connection string. Then, we will change the SAP Authentication method in the K2 blackpearl Settings from static to K2 SSO.

  2. Click Settings, then click Configure Destinations. Right-click the K2LearningSAP destination and select Destinations > Modify.
  3. On the K2 connect Destinations screen, remove the USER and PASSWD settings from the CONNECTIONSTRING property. The edited connection string should now read:
    ASHOST=23.23.150.97 SYSNR=KR3 CLIENT=900
    Click OK, then No to the test connection prompt.
  4. Click OK twice to return to the console landing screen.

    5. Now, we will edit the K2 blackpearl Settings to change the SAP authentication from static to K2 SSO.

  5. Click K2 blackpearl Settings. Change the SAP Authentication to K2 SSO. Click OK, then Yes to refresh the Service Instance. Click Yes once again when prompted about restarting the K2 connect Server.
  6. After a few seconds, you should see a dialog that indicates the Service Instance was successfully refreshed. Click OK to close the dialog, then OK once again to complete the K2 blackpearl Settings configuration.

    7. The next step for us is to confirm the K2connectEmpData Service Instance shows the updated authentication method in the SmartObject Service Tester. Once again, this is confirming that K2 blackpearl is showing the K2 connect changes.

  7. Launch the SmartObject Service Tester if it is not already open. In the ServiceObject Explorer, expand the K2 connect Service node, then the Connect Service for dlx node. (If you are working within your own environment, dlx is likely to be a different server name.)
  8. Right-click Connect Service for dlx and select Edit Service Instance.
  9. Confirm the Authentication Mode now reflects SSO (and not Static). Exit the Add Service Instance screen.

    10. Now we will execute the K2connectEmpData SmartObject and observe any changes in behavior since we have changed the authentication mode to SSO. First, we'll enter two parameters for our search filters: p_DATE() and p_LASTNAME_M.

  10. Switch to the SmartObject Explorer. Expand the K2connectTest node. Right-click the K2connectEmpData SmartObject. CHECK the box for the p_DATE() parameter and confirm the default value is the current date. Next, enter the following wildcard for the p_LASTNAME_M parameter:
    A*
    Click Execute to call the SmartObject method.
  11. You should see a prompt for the K2LearningSAP UserName. Click Cancel, then exit the Execute SmartObject screen, but do not exit the SmartObject Service Tester.
    Why did we see this prompt? Recall that we removed the embedded username and password from the connection string, then changed the SAP Authentication from Static Credentials to K2 SSO. When we execute the SmartObject, K2 looks for the cached SSO credentials. Because we have not configured the SSO yet, K2 prompted us instead, asking if we want to manually enter the username (subsequently password). In the next few steps, we will configure the K2 SSO to cache our own credentials. We manage this configuration in K2 Workspace.
  12. Launch K2 Workspace. (Start > scroll to K> K2> K2 Workspace)
  13. In the central pane, click Settings.
    14. K2 utilizes Active Directory as the primary means for user authentication. Not all back-end systems use Active Directory however, and this is where the SSO configuration comes into play. The SSO configuration allows users to configure a set of credentials for the alternate system they need to access. When a login attempt is made through K2, K2 passes the cached credentials on behalf of the user to the alternate system. It is important to understand that the K2 SSO credentials must be maintained. K2 SSO credentials are not updated automatically if the alternate system credentials are updated. K2 users do not need to have Administrator rights to access and maintain their SSO credentials. SSO credentials are cached against a security label. A security label is required for each SAP destination. Security labels are added automatically by K2 when a SAP Service Object is published. For more information on K2 connect Single Sign-On, see the K2 connect Product Documentation: Single Sign On.
  14. Again, in the central pane, locate the AUTO LOGIN section. Click the configure link in the K2Learning SAP row.
  15. Enter the following on the Edit Credentials screen:
    User Name: K2Learning
    Password: K2pass!
    More Data... Data: K2LearningSAP (Data is the destination name.)

    16. The last step for SSO configuration is to test it once again by executing the K2connectEmpData SmartObject using the SmartObject Service Tester. Recall that when we last executed the SmartObject, we were prompted for the SAP User Name. This time, with the K2 SSO credentials in place, our test should return results without any prompts.

  16. Access the SmartObject Service Tester and navigate to the K2connectEmpData SmartObject. Right-click the SmartObject and select Execute SmartObject.
  17. CHECK the box for the p_Date() parameter and confirm the default value is the current date. For p_LASTNAME_M parameter, enter
    A*
    then click Execute. Confirm there are results shown in the Results pane. Note also that we were not prompted to enter login credentials as K2 passed the K2 SSO credentials through to the SAP system on our behalf.
Step 4 Review

In this step, we edited the Settings for our K2LearningSAP destination and removed the username and password from the connection string. We then edited the K2 blackpearl Settings and changed the SAP authentication from static credentials to K2 SSO. We also refreshed the Service Instance for the K2connectEmpData Service Object. After testing the new settings with the SmartObject Service Tester, we noted that we were prompted for login credentials. After adding K2 SSO credentials for the K2LearningSAP destination, we executed the SmartObject once again, noting this time we had results returned without being prompted for login credentials.

In the next step, we will move away from K2 connect administration and explore more advanced options for developing with K2 connect.

Next Step: Part 3: Developing with K2 connect