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.

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