Package com.smartgwt.client.docs

# Interface TaskInputExpression

public interface TaskInputExpression
A TaskInputExpression is a way to specify a value in the declarative workflow system (`Process` / `Task`) that is derived from the running `process state`, the `output` of a previous task in the process, or from global context such as `ruleScope`.

For example, in `FormEditNewRecordTask`, `taskInputExpressions` are allowed in the `initialValues` specified for the task, making it very easy to build a process that fetches data from the server and populates a form with that data.

Similarly, in `GridFetchDataTask`, `taskInputExpressions` are allowed in the `criteria` specified for the task, as the `Criterion.value` for any criterion.

`TaskInputExpressions` are designed to be visual-tool-friendly so that it's easy to visually wire together processes in the `Workflow Editor`.

A TaskInputExpression is a String prefixed with "$input", "$inputRecord", "$ruleScope", "$state" or "$last" followed by an optional dot-separated hierarchical path, which can specify either an atomic data value (String, Number) or Record from the input data. For example, if the `Process.state` represented in JSON were:

      {
         orderId:5,
         orderItems: [
            {name:"Pencils", quantity:3, itemId:2344}
         ],
         orderUser: { name:"Henry Winkle", address:"...", ... }
      }

.. and a task specified an `inputs` of "orderId" and an inputFieldList of "orderItems","orderUser", then:

- $input is the value 5
- $inputRecord.orderUser.name is "Henry Winkle"
- $inputRecord.orderItems[0] is the first orderItems Record ({name:"Pencils", ... })

"$ruleScope" can be used to pull values from a `ruleScope` `ruleContext` when configured in `Process.ruleScope`.

- $ruleScope.property references the ruleContext "property" field

Two others sources of input are "$state" and "$last". The former references the contents of the `Process.state` and the latter the `transient state`.

- $state is the full contents of the process state
- $state.orderId is the "orderId" field of the process state (5 from the example above)
- $last is the full output of the previous task executed in the process
- $last.property is the "property" field of the previous task executed in the process
- $last[service].property or $last[DSRequestTask].property references the last "DSRequestTask" output in the "property" field
- $ruleScope.property references the ruleScope "property" field

The last two sources of input are "$lastRequest" and "$lastResponse". These are the objects `dsRequest` and `dsResponse` representing the last `DSRequestTask`, `DSFetchTask`, `DSAddTask`, `DSUpdateTask` or `DSRemoveTask` DataSource operation as returned in the operation's `callback`. A common usage would be to reference $lastResponse.totalRows to know how many rows were returned from a fetch.

#### Transient state outputs

Most tasks pass the output from the previous task as their output (i.e. passed through) making it easy to refer to earlier output without referencing the task type. Tasks that work with records or interact with the user, however, typically provide task-specific output as detailed below:

- DSRequestTask: the contents of dsResponse.data.
- ScriptTask: the result of `execute()` or, for an asynchronous task, the value passed to `setOutput()`.
- StateTask: the value assigned to the outputField.
- UserTask: the values of the targetForm or targetVM when the task completes.
- AskForValueTask: an object with "value" and "canceled" properties.
- FetchRelatedDataTask: the first fetched record.
- GridFetchDataTask: the contents of dsResponse.data.
- GridTransferSelectedTask: the first transfered record.
- GridSelectRecordsTask: on a select, the set of newly selected records, even if other records are also selected. On a deselect, the entire set of de-selected records.
- FetchRelatedDataTask: the first fetched related record.
- FormSaveDataTask: an object with "valuesValid" and "errors" properties.
- FormValidateValuesTask: an object with "valuesValid" and "errors" properties.
- GetPropertiesTask: an object with selected properties and values retrieved.