Package com.smartgwt.client.docs

# Interface ReifyAddWorkflowTask

public interface ReifyAddWorkflowTask

### Reify OnSite: Adding Custom Workflow Tasks

You can define your own custom Workflow tasks and add them to Reify's Workflow Editor. This allows your designers to cover additional use cases entirely within the visual design tool, without having to write code.

To create a new Workflow task type and add editing support, the steps are:

1. Create a subclass of `ProcessElement` (or one of ProcessElement's subclasses) which performs the desired task, and load that class in Reify.
2. Create a `component schema` for the task inheriting from the same superclass schema as the task itself.
3. Use standard Smart GWT UI components to create a UI for editing your new workflow task, called a "task editor", and load this editor in Reify.
4. Register the new task editor with the Workflow Editor so that new and existing tasks of the new type can be edited.

Do I need a custom Workflow task?

Before you start building a custom Workflow task and editor, consider whether other approaches might work as well or nearly as well:

1. Custom services

If you are trying to connect to some kind of enterprise-specific web service, you probably do not need a custom Workflow task but rather just a custom DataSource; see the `Adding Custom DataSources to Reify` overview instead.

Note that DataSources in Reify can serve as a model for any kind of network service, not just databases that store records. For example, if you have something like a proprietary messaging system with inputs similar to an email (recipient, subject, message text), it may seem like a custom Workflow task is needed, but this could also be modelled as a DataSource where recipient, subject, etc are simply DataSource fields, and a message is sent by performing a DataSource "add" operation. However, it may be worthwhile to add a custom Workflow task in this case in order to provide a specialized editing interface, or simply to make it more obvious how to perform the task.

2. Actions on UI components

If you have added custom UI components to Reify, you might want to add custom Workflow tasks for the custom actions that those components support. However, an alternative approach is to make those actions accessible as a "setter method" and have designers invoke the action via the built-in Set Properties workflow task.

For example, you might have a component with two very different display modes, and APIs like `switchToModeOne()` and `switchToModeTwo()`, and you might think of creating a custom Workflow class to call these APIs. However, another approach would be to create a "setter method" like `setMode(newMode)`, add it to the Component Schema for the custom component, and have designers change mode via the Set Properties built-in workflow task.

Workflow Task

A new workflow task must inherit from `ProcessElement` or one of its subclasses like `ScriptTask` or `ComponentTask`. The implementation of the task must include an override of `ProcessElement.executeElement()` or other more specific subclass method like `ScriptTask.execute()`. Be sure to return the correct value to keep the process moving.

By adding `ProcessElement.typeTitle` and `ProcessElement.classDescription` property values, the `WorkflowTaskDescriptor.title` and `WorkflowTaskDescriptor.description` properties are not needed when referencing your custom task.

The JavaScript implementation of the task can be loaded in Reify by adding a dependency in the `globalDependencies.xml` file as detailed in `"Adding Custom Components to Reify"`. Alternately, see `"Runtime Customization"` for a different means to load the implementation file.

Task Schema

A `component schema` is needed for the new task so that the configuration can be serialized and deserialized correctly. The schema can be declared in XML or in JavaScript code. In either case, the following attributes are required in addition to fields matching each task property:

- `ID` = same name as your task class
- `serverType` = "component"
- `inheritsFrom` = class name of your task superclass
- instanceConstructor = same name as your task class

As with the new workflow task implementation, the schema needs to be loaded into Reify. See the section above for two means of loading the schema.

Workflow Task Editor

A task editor is needed for any task that has properties the user can change. If a task doesn't have any properties, like a logout task, there is no need to implement an editor at all. For the `com.smartgwt.client.tools.WorkflowTaskDescriptor` created below, don't provide an `editTask()` implementation.

Otherwise, an editor component is needed to edit the properties for an instance of your new workflow task. Custom code that is used by your `editTask()` method should be included for Reify as detailed in Workflow Task above.

To aid in writing custom task editors there are several classes on which to base your editors. You can start with `com.smartgwt.client.tools.WorkflowTaskEditor` or, if your workflow task derives from `ComponentTask`, use `com.smartgwt.client.tools.WorkflowComponentTaskEditor`. There are also some custom editors that are useful for editing the task properties:

- `com.smartgwt.client.tools.WorkflowValuesBindingEditor`
- `com.smartgwt.client.tools.WorkflowCriteriaBuilder`
- `com.smartgwt.client.tools.WorkflowDynamicValueItem`
- `com.smartgwt.client.tools.WorkflowTemplatedTextItem`

Register Task Editor

For the `Workflow Editor` to show your new task in the Add task choices and to edit existing tasks of your new type, a `com.smartgwt.client.tools.WorkflowTaskDescriptor` must be registered with Reify. easiest way to configure the descriptor is to add it to the default Reify task descriptors found in `[webroot]/tools/visualBuilder/workflowTasks.xml`.

As can be seen by looking at workflowTasks.xml, tasks are specified using a tree structure similar to that shown in the tree XML loading example. This tree structure exactly maps into the add task choices menu in the Workflow Editor. The properties that can be set on nodes are documented on `com.smartgwt.client.tools.WorkflowTaskDescriptor`.

Alternately, a new task descriptor can be added by calling `Reify.registerWorkflowTaskDescriptor()` which makes it possible to do this with `"Runtime Customization"`.