Friday, September 14, 2012

Build a Composite SmartObject in 15 minutes or Less

Creating a SmartObject in K2 Studio can be really intimidating. There's associations, properties, and methods all over the place. Where do you start? In this post, I'm going to walk you through creating a simple composite SmartObject in 15 min or less. Satisfaction guaranteed!

Before we proceed to develop what you need, let's go through what this post entails:

  • Prep time: Length of reading the following paragraphs
  • Cook time: 15 min
  • Skill-level: Comfortable with K2 Studio and SmartObjects
  • Ingredients:
    • Two SmartObjects
      • In my example, I'll be using a list that has a many-to-one relationship. In this example, the lists are Master Deliverables and Templates.
        • I'll translate this to SharePoint speak: Deliverables has a column that looks up to Templates and allows a single value.
    • A get method for both SmartObjects
      • We're retrieving data from two disparate sources so we'll use the same method in both lists.
        • Building a composite SmartObject with other methods would be similar to this approach. The only change would be the SmartObject's required fields

Preparation

Why use a composite and not an association? Associations are a reference between SmartObjects via a foreign-key relationship and can be built across different platforms. Composite SmartObjects more or less give you a single, flat table. Since SmartObject References are my BFF, I wanted to use them in my process. I tried binding my two SmartObjects using SmartObject references, but the results weren't stellar. An association would do the trick, but you're still working with two SmartObjects. By creating a composite SmartObject, I could have that single flat table and reference it to my liking.

Before diving into K2 Studio and building a composite SmartObect I wanted to validate that a composite SmartObject was the route I wanted to go. What I did was open up the Smart Objects Service Tester and tested my join. If you haven't used the SO Service Tester before, you can find it at C:\Program Files\K2 Blackpearl\Bin\SmartObject Service Tester.exe

  1. To do so, right click on the SmartObject and select Join SmartObject
  2. Click Get All SmartObjects to retrieve all SmartObjects in your environment
  3. Select the SmartObject you want to join
  4. Now select your join properties. In this example, the Master Deliverables library field TemplateID is the ID in the Templates library
  5. Click Generate Join . Since this is a super-simple example, I'm not going to go into detail about the type or scope of the join.
  6. Click Execute
  7. Validate that the executed SmartObject is to your liking. You can apply filters via the right-hand panel in the Join window. Tweak until you're satisfied.

Like cooking, it helps to write down your SmartObject recipe so when you're actually slicing, dicing, and sautéing in K2 Studio, you're not wracking your brain wondering about the ingredients, quantities, and cook time. Addtionally, one thing to keep in mind at this point is the use of common field names between the two SmartObjects. For example, ID, Name, Modified, Created By. These are just some of the out of the box columns, but I bring this to your attention because often user created columns between lists may share the same name. We'll need to be aware of these columns later on when we're building our method.

Wouldn't it be awesome to save your SmartObject right here and now and start using it in your processes? Unfortunately you can't. But fret not, now that you've finished the preparation steps you'll have this new SmartObject cooking and ready to eat, I mean use, in your process in 15 minutes.

Cooking

  1. Open up your K2 Studio project
  2. Add a new project item
  3. Select SmartObject and name it to reflect the data sources
    • In this example it'll be CompositeDeliverableTemplates
  4. In the Methods section of the ribbon, click Remove All
    • This will get rid of all of the default method
  5. In the Methods section of the ribbon, click Add
    • This will start the method wizard where we will add our existing methods from our two SmartObjects
  6. Run the Method Wizard in Advanced Mode
  7. For the name, type Get Composite. For Type, select List (aka the Get Method). For Transaction, select Continue
    • Click Next
  8. Skip the Configure Method Parameters screen
  9. At the Add Service Method screen, expand the Context Browser
    • In the environment, expand the ServiceObjectServer
    • Find and expand your SharePoint site
    • Find the SmartObject for the list
    • Expand the SmartObject and select the Get List method



      You've now added a SmartObject Method for one SharePoint list to your SmartObject. Now we just need to map out its properties.
  10. Click Create All
    • This will create all the SmartObject Properties for this method.
  11. Click OK
  12. You've now added the first SmartObject and its properties. Repeat Step 9 for the other SmartObject. Do NOT map the properties for the second smart Object.

    This is where you'll want to slow down a little. K2 can auto-map the inputs from the other SmartObject, but in most cases you probably don't want to join your SmartObjects by fields like Created and Content Type. Since there are common, shared name fields like the aforementioned columns, as well as ID and Title, you can get really sloppy with your SmartObject Properties if you're not careful. You don't want your query to come back with null or totally wrong fields. Since we're making a single, flat table it's best to rename the properties in your second SmartObject to reflect their source.

    This is where you'll want to use the field you used in your join operation in the Preparation section. In this example, Deliverables:TemplateID is the ID in the Template SmartObject.

  13. When editing your second Service Object Method
  14. In the Input Property Section, click on ID
  15. Click Assign
  16. From the SmartObject Property Name dropdown, select ID
  17. Click Create
  18. When prompted, give the property a unique, distinguishable name like TemplateID
  19. Note: If you want to add any additional fields for the join, now would be the time. This would be beneficial to save time building filters in processes later on.

  20. Click Next in the SmartObject Method Wizard
  21. The Service Method Links screen is essentially going to let you determine how the SmartObject is going to be built using data from two different locations

  22. Click Add
  23. Since this is a many to one relationship, place your many SmartObject in the top Service Object and your one SmartObject in the second Service Object. In this example Master Deliverables is in the top field and Templates is in the bottom.

  24. You can configure the Link Type in one of four ways:
  25. Matching values in both objects: Retrieves data when the Service Object Maps
  26. All Values for First Object: Retrieves the entire first Service Object
  27. All Values for Second Object: Retrieves the entire second Service Object
  28. All Values for Both Objects: Retrieves everything from both Service Objects
  29. I recommend using matching values in both objects or All Values for Second Object. This will depend on your mapping, but in this example both of the links return the same number of items.

     

  30. To finish the link, in the Service Object section find the property name you created in step 12.5. In this example,TemplateID
  31. Click Assign
  32. Select ID
  33. Click OK

  34. Click Next and Finish the wizard
  35. Deploy the SmartObject
  36. Fire up the SmartObject Tester and test your SmartObject
    • You can find your newly deployed SmartObject at SmartObject Explorer>Project Name
  37. Right click on the SmartObject's name and click Execute SmartObject
  38. Presentation

    Have 5 more minutes to spare? Great! Obviously if you've made it this far, you can see that it doesn't take long to build composite SmartObjects. One thing to keep in mind is that if you're joining two very large SmartObjects, a Get method is going to be taxing on the server. You can save some compute and increase your query time by weeding out some of the unnecessary fields (I'm looking at you Copy Source!)

    You can remove unwanted fields from your SmartObject via K2 Studio.

    1. Open your composite SmartObject
    2. In the SmartObject Properties section, select the unwanted field
    3. In the properties section of the ribbon, click Remove
    4. When prompted if you want to remove the field, click OK

    In my experience pruning a SmartObject's properties, it'll deploy and test great, but occasionally I'll get interesting errors modifying the SmartObject in K2 Studio and can't deploy the SmartObject anymore. Speaking from experience, err on the side of caution and save often.