Advanced SmartObjects: Methods

The Methods tab only displays when you are working with an Advanced SmartObject. You can use the Methods tab to view, add, edit and delete the SmartObject methods. You can also configure the underlying service object methods that are bound to the SmartObject's methods, and edit the mappings between the service object method's parameters, input properties and return properties, and the SmartObject method parameters or the SmartObject's properties.

This is sometimes necessary when you need to alter the way a particular SmartObject method is called from a workflow or form, when you need to call multiple service object methods in a single SmartObject method (sometimes referred to as SmartObject method chaining), or when you want to limit the number of available methods on a SmartObject.

Methods

Actions/Column Description
Add Opens the Add Method wizard to define a new service method binding.
Edit Opens the Edit Method wizard for an existing service method binding.
Remove Removes the method (note that removing a method might break applications that rely on this method).
Remove All Removes all the methods (note that removing all methods might break applications that rely on the SmartObject).
Name The Name of the SmartObject method.
Method Bindings Displays the service object methods that the SmartObject method is bound to.
Service The name of the service instances where the bound Service Object methods exist.

Adding a Method

Click on Add to launch the wizard to add a new method, and then select the service object method you want to add, or alternatively drag and drop a service object method from the ServiceObject Explorer panel into the Methods tab.

Selecting a Service Object method

Dragging and dropping a Service Object method into the methods tab

Use the Details page to configure the method name, type, transaction and parameters.

The Details screen

Fields Description and notes
Name Enter the display name of the SmartObject method. This is the method name shown to people calling the SmartObject, so specify a name that accurately reflects the purpose of the method.
Description Enter a description of the SmartObject method.
Type

Select the type of method that this SmartObject method should be classified as. Available options are:

  • Create - used to create a new record
  • Read - read the data for an existing record
  • Update - used to save/update an existing record
  • Delete - used for deleting existing records
  • List - return a collection of records
  • Execute - used for execute style methods that do not return a record
The type of method could determine whether the method is available for use in certain configurations. For example, when working with a Rule or configuration that expects a collection of items from a SmartObject, you may only be able to select the List type methods from the SmartObject. For this reason, ensure that you select the correct type of method.
Transaction

Specifies the action to be performed should the method fail. The Transaction option is mostly used when more than one service method binding exists for a SmartObject method, and it defines how K2 will handle subsequent service methods calls if a preceding service method call fails. Note that transaction support must be implemented in all the underlying service brokers for the transaction support to execute as defined. In other words, K2 does not do the transaction compensation and it must be supported in the line of business system, such as SQL Server.

  • Continue: The remaining service methods execute regardless. An error message is returned for the failed method. This is the default behavior.
  • Stop: The remaining service methods stop processing if a method fails.
  • Rollback: If a method fails, previously executed methods are rolled back.
Configure ServiceObject method parameters Use this section to define method parameters. See the Configure Method Parameters section

The inputs & Outputs screen is where you map Service Object Properties to SmartObject properties or parameters.

Inputs & Outputs screen

The input and return properties of the service object method are displayed on this page. You can map service object properties individually by selecting a property and then clicking the Assignbutton, or you can clickAuto MaporCreate Allbuttons to let K2 automatically map all current SmartObject properties to the service object method properties, using the property names to auto-map where possible and creating new properties where needed. See Advanced SmartObjects: Properties for more on defining and creating properties.

If there are no properties for the SmartObject, you must create the properties as part of the Assign step, or you can click Create All to automatically create SmartObject properties for all the service object properties, and K2 will also auto-map the properties once they are created.

Select a property and click Clear to clear the mapping for that specific property, or click the Clear All button to clear out all property mappings.

Fields Description and notes
Input Property Name The display name of the Input properties for the method.
Return Property Name The display name of the Return properties for the method.
Type The data type of the property.
Required Whether the input property is required or not. Required properties will require the consumer to provide a value for those properties when the consumer wants to interact with the SmartObject method.
Bound To Displays the Service Object Property that the SmartObject property is linked to.

Select a property and then click Assign to manually map the property to a method parameter, SmartObject property, System value or Specific value. Selecting Create All automatically creates new SmartObject properties for each return value. Selecting Auto Map automatically creates a mapping between any properties that are the same (for example mapping service object property "Id" to SmartObject property "ID". )

The ServiceObject Methods screen displays the Service Object method(s) that are configured for the current SmartObject method. You can add more than one service object method to create Composite SmartObjects.

Actions Description
Add Click to start adding an additional service object method binding to the SmartObject, to build a composite SmartObject.
Edit Select a Service Object method and clickEditto modify the existing service object method bindings.
Remove Removes the selected method binding. Note that this action might break the SmartObject and affect applications in your environment.
Remove All Removes all the method bindings listed. Note that this action might break the SmartObject and affect applications in your environment.
Move Up Select a method and then clickMove Upto move the method higher, so that it is executed earlier.
Move Down Select a method and then clickMove Downto move the method lower, so that it is executed later.
The order of the service object methods is important because at runtime, K2 executes the Service Object methods in the same order that the methods are displayed on this page. When building composite SmartObjects, you may need to take care to ensure that the service object methods are called in the correct sequence.

On the Service Method Links page you configure links between different service object methods. This option is only available if you added more than one service object method and you used a list method. When the list method executes, the service property bindings validates and the service method link applies to the retrieved data.

Fields / Actions Description
Service Method 1 This displays the original service object method.
Service Method 2 This displays the linked service object method.
Link Type Represents how the methods are linked.
Add Click Add to add a service method link.
Edit Select and click Edit to modify the existing service method link.
Remove Removes the selected service method link.
Remove All Removes all the service method links listed.

How to Add a Service Method Link

In this example, you want to compare a list of employee details with the Active Directory user list to find duplicate email addresses.

The example have two service objects namely the Employee List (contains employee details including an email address) and Active Directory 2 (contains user details including an email address). The service method for both these objects is the List method. You create an advanced SmartObject with a service method link configured between the service objects.

Create an advanced SmartObject called Global List. This advanced SmartObject is where you add the methods and configure the method links. From the Methods tab. Click Add and add the Employee List Get List Service Object Method. Select the method and click Edit.

Next you need to add the second service object method. On the Edit Method page, select the ServiceObject Methods tab and click Add.

From the Add ServiceObject method bindings screen, select the ellipsis and browse to Active Directory Service 2 > AD Users. Select the GetUsers method. Click OK.

Click Create All. Click OK. In this example you add the Active Directory 2 GetUsers method and bindings to then be configured in the method link.

On the Edit Method page click Next or the Service Method Links tab.

On the Service Method Links page you add and configure the method link. Click Add to create the link between the Employee and AD User methods.

The Add Service Method Link page shows.

The following link types are available:

  • Matching values in both objects - Returns data where matching values in both objects are detected
  • All values for first object - Returns all values for first object including matching values in second object
  • All values for second object - Returns all values for second object including matching values in first object
  • All values for both objects - Returns data for both objects

Fields / Actions Description
Service Object Method 1 This displays the original service object method.
Link Type Represents how the methods are linked.
Service Object Method 2 This displays the linked service object method.
Service Object This displays the first service object method.
Property Name This displays the property of the service object. Select the property and click Assign to assign a binding between the service properties.
Type The data type of the service property.
Bound To Displays the binding between the service properties.
Assign Assign a binding between the service properties.
Clear Removes the binding of the selected property.
Clear All Removes all the bindings of the service properties.

You need to assign at least one property to link the two services. Select a property and click Assign. In this example, select Email.

On the Bind Service Property screen, select a property to bind to. In this example, the Property Name menu contains properties from Service Object Method 2 which is the AD User Service Object. Select Email and click OK.

The Email property from the Employee List is now bound to the ADUser Email property. Click OK.

Click Finish to complete the service method link configuration.

The configured service method link shows as follows.

To edit an existing service object method link, select the link, click Edit and select the Service Method Links tab.

Service object methods might have parameters that need to be specified when the method is called. For example, a "Read" method might require you to provide the RecordId or some other unique value to retrieve a specific record. Typically, you would define method parameters to handle this type of required input. You can add parameters to SmartObject methods by clicking Add in the Configure ServiceObject method parameterssection of theDetailstab. TheAdd parameter screen opens, and you will configure the method parameter as needed.

As opposed in Input Properties for a method which are optional for the consumer to provide, method Parameters are required and values must be provided by the consumer of the SmartObject method.

Adding a method parameter

Field Description
Parameter name Enter the display name for the parameter. Try to use a name that is obvious to the consumer of the SmartObject so that they know what value should be provided for the parameter. For example, if the parameter is the user's login name, then name the parameter "Login Name" instead of "Name".
Parameter description Enter a description for the parameter. You can also use this area to enter a sample value for the parameter.
Parameter type Select the data type for the parameter (see Property types for a listing of available property types). Take care to select a data type that matches the expected data type of the property/parameter that the parameter will be mapped to. In other words, if the method expects a input type of "text" for the Login Name, select Text as the parameter type.

Once the parameter is defined, you can use the parameter in the Inputs&Outputs screen to map the parameter to a service object property.

Using a method parameter in the Service Object Method Inputs & Outputs screen

How Parameters surface to consumers

When using SmartForms, SmartObject method parameters are reflected in the Mapping Destinations of the SmartObject method action.

Method Parameter as shown in the SmartForms Designer

When using workflow designer, method parameters appear in the Input Mappings section.

Method parameters in workflow designer