Advanced SmartObjects: Methods

SmartObject methods define the actions or operations you can perform on a SmartObject, such as create, read, update, and delete. Methods are often used to populate the values contained in SmartObject properties. A SmartObject's methods are associated to one or more Service Object methods, which tells K2 which service object method(s) to call when the SmartObject method is executed.

When editing a SmartObject in advanced mode, you can edit the methods for that SmartObject in the Methods tab, as shown below. You can use the Methods tab to view, add, edit, and delete SmartObject methods.

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 method(s) to which the SmartObject method is bound.
Service The name of the service instances where the bound service object methods exist.

You can use the SmartObject Methods tab to:

  • configure the underlying service object methods that are bound to the SmartObject's methods
  • limit the number of available methods on a SmartObject
  • edit the mappings between the service object method's parameters
  • configure input properties and return properties
  • configure the SmartObject method parameters
  • edit the SmartObject's properties
  • call multiple service object methods in a single SmartObject method (sometimes referred to as SmartObject method chaining) to create a composite SmartObject

See the following resources for more information:

Click Add to launch the wizard to add a new method, then select the service object method you want to add. 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/insert 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 methods that do not return a record, for example disabling an account.
The type of method could determine whether the method is available for use in certain configurations. For example, when working with a SmartForm rule or configuration that expects a collection of items from a SmartObject, you may only be able to select the list 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 defines how K2 handles 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. 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 clicking the Assign button, or you can click Auto Map or Create All 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 when 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. However, you can click Create All to automatically create SmartObject properties for every service object property which also get auto-mapped.

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

Fields Description and notes
Input Property Name The display name of the input properties for the method. Input properties are values that you often have to provide before executing the method, such as the ID of the record you want to load.
Return Property Name The display name of the return properties for the method. Return properties are the values that are returned by the underlying system when the method is executed.
Type The data type of the property. See SmartBox properties for a listing of the available data types.
Required Whether the input property is required or not. Required properties require a value before the SmartObject method executes.
Bound To Displays the service object property to which the SmartObject property is bound.

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 following System value options are available:

  • This SmartObject's display name
  • This SmartObject's GUID
  • This SmartObject's system name
  • Current User's Identity (FQN)
  • Current User's E-mail
  • Current User's Account Name
  • Current User's Display Name
  • Current User's Manager's Account Name
  • Current Date
  • Current Time
  • Current Date and Time

Fields Description and notes
This SmartObject's display name The display name of the SmartObject that executes the service object. Mostly used if the service object method needs to know which SmartObject it was called by.
This SmartObject's GUID The GUID (Global Unique Identifier) of the SmartObject that executes the service object. Mostly used if the service object method needs to know which SmartObject it was called by
This SmartObject's system name The system name of the SmartObject that executes the service object. Mostly used if the service object method needs to know which SmartObject it was called by.
Identity

The user identity that executes the SmartObject. This value is most often used if you need to know which user executed the SmartObject method.

This value is not based on the Authentication Mode configured on the service instance of the service object method, but rather the user executing the SmartObject method. For example, if you configured the service instance authentication with Static credentials using username K2Admin, and Denallix\Bob executes the SmartObject, the Identity fields will be based on K2:Denallix\Bob. You can use this option with any authentication mode on the service instance, including Static and ServiceAccount, and pass in the executing user's identity for auditing or security purposes.

The following user properties are available:

Field Example
Current Users Identity FQN (Fully Qualified Name) K2:Denallix\Bob
Current User's E-mail bob@denallix.com
Current User's Account Name Denallix\Bob
Current User's Display Name Bob Magio
Current User's Manager's Account Name Denallix\Codi

For more information about using this field, see Sending Identity Information to a Line of Business System.
Date and Time

These properties use the current date/time of the server. Map these properties to DateTime, Date/Time type service object properties respectively to avoid any regional settings conversion problems.

If these properties are mapped to string type service object properties, they are passed in as UTC time using the ISO8601 standard format (yyyy-MM-dd HH:mm:ss.fffZ).

These properties are very useful for auditing purposes to ensure that all date and time audit information uses a server value that is administered and secured centrally.

The following date and time properties can be used:

Field Example
Current Date and Time 2019-12-20 09:45:00
Current Date 2019-12-20
Current Time 09:45:00

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

Actions Description
Add Add an additional service object method binding to the SmartObject to build a composite SmartObject.
Edit Select a service object method and click Edit to modify the existing service object method bindings.
Remove Removes the selected method binding. Note that this action might break the SmartObject and applications that rely on this SmartObject.
Remove All Removes all method bindings listed. Note that this action might break the SmartObject and applications that rely on this SmartObject.
Move Up Select a method and then click Move Up to move the method higher so that it is executed earlier.
Move Down Select a method and then click Move Down to 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 configured 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, such as when a property of one method is necessary for a later method to execute.

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 list method. When the list method executes, the service property bindings are validated and the service method link is applied to the retrieved data.
See the topic How To: Add a service method link in an advanced SmartObject for an example of using Service Method links.

Fields / Actions Description
Service Method 1 This displays the original/first service object method.
Service Method 2 This displays the subsequent linked service object method.
Link Type Represents how the methods are linked, essentially inner or left/right/full outer joins.
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 service method links.

Service object methods might have parameters that need to be specified when the method is called. For example, a read method might require an ID or some other unique value to retrieve a specific record. Typically, you configure method parameters to handle this type of input. You can add parameters to SmartObject methods by clicking Add in the Configure ServiceObject method parameters section of the Details tab. The Add parameter screen opens and allows you to configure the method parameter. 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

Unlike input properties for a method that are optional, method parameters are required when the SmartObject method executes.

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 simply 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 or parameter to which the parameter is mapped. In other words, if the method expects a text for the Login Name, select Text as the parameter type.

How parameters are shown

When editing rules in SmartForms, SmartObject method parameters are shown in the Mapping Destinations screen 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

Considerations

  • Take care when editing existing SmartObjects, especially if renaming or deleting existing properties or methods. If you rename, change or delete a property or method, you could break an application that requires that property or method.