Package com.smartgwt.client.util.workflow

# Class DSRequestTask

java.lang.Object
com.smartgwt.client.core.BaseClass
com.smartgwt.client.util.workflow.ProcessElement
com.smartgwt.client.util.workflow.Task
com.smartgwt.client.util.workflow.DSRequestTask

All Implemented Interfaces:
  `HasHandlers`

Direct Known Subclasses:
  `DSAddTask`, `DSFetchTask`, `DSRemoveTask`, `DSUpdateTask`

public class DSRequestTask extends Task
A DSRequestTask (previously called ServiceTask) is an element of a `Process` which calls a DataSource operation, optionally using part of the `process state` as inputs or storing outputs in the process state. A special "export" `operationType` is supported to perform a server export based on criteria.

By default, a DSRequestTask takes the data indicated by `inputs` as detailed in `TaskIO` and uses the `inputRecord` as `DSRequest.data`. This means the input data becomes `Criteria` for "fetch" and "export" operations, new record values for an "add" operation, etc.

Alternatively, you can set `criteria` for a "fetch" and "export" operations, or `values` for other operationTypes. In both cases, you can use simple expressions like $input.fieldName to take portions of the input data and use it as part of the criteria or values.

OutputData and outputFieldList work as filters. You should determine which properties should be fetched into the process state. If you want to load all data without defining every property manually, you can pass a name started with '$'. The fetched record or records will be placed as a record or an array of records by the name without this specific symbol.

For example, if you specify 'id' and 'name' in outputFieldList, only these properties will be fetched in the process state. If you pass '$orderHeader' in outputField a whole record will be stored in the process state under the 'orderHeader' key.

See Also:
  - `OperationBinding.process`
  - `Server-Side Process Execution`

- ## Field Summary

  ### Fields inherited from class com.smartgwt.client.core.BaseClass

  `config, configOnly, factoryCreated, factoryProperties, id, scClassName`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DSRequestTask()`
  `DSRequestTask(JavaScriptObject jsObj)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `JavaScriptObject`
  `create()`
  `Criteria`
  `getCriteria()`
  Criteria (including AdvancedCriteria) to use for "fetch" and "export" operations.
  `ExportFormat`
  `getExportFormat()`
  The format in which the data should be exported.
  `String`
  `getFailureElement()`
  ID of the next sequence or element to proceed to if a failure condition arises from DataSource operation.
  `Criteria`
  `getFixedCriteria()`
  Criteria to be submitted as part of the DSRequest, regardless of inputs to the task.
  `Record`
  `getFixedValues()`
  Values to be submitted as part of the DSRequest, regardless of inputs to the task.
  `String[]`
  `getGroupBy()`
  List of fields to group by for a fetch.
  `String`
  `getInstanceDescription()`
  Overrides `ProcessElement.getInstanceDescription()` to prefer, in order: an instance-level `ProcessElement.description`; the `OperationBinding.description` of the `OperationBinding` this task invokes; and finally the inherited class-level `ProcessElement.classDescription`.
  `String`
  `getInstanceTitle()`
  Overrides `ProcessElement.getInstanceTitle()` to prefer, in order: the `OperationBinding.title` of the `OperationBinding` this task invokes; an auto-title derived from `operationId` via `DataSource.getAutoTitle()`; and finally the inherited class-level title (e.g.
  `String`
  `getOperationId()`
  The `operationId` to invoke.
  `DSOperationType`
  `getOperationType()`
  Type of operation to invoke.
  `static DSRequestTask`
  `getOrCreateRef(JavaScriptObject jsObj)`
  `String`
  `getOutputField()`
  Field in the `process state` where this task writes outputs.
  `String[]`
  `getOutputFieldList()`
  List of multiple fields in the `process state` where this task will write outputs.
  `Boolean`
  `getPassThruOutput()`
  Does this processElement pass through output from the last executed task (i.e.
  `SortSpecifier[]`
  `getSort()`
  An array of `SortSpecifier` objects used to set up the sort configuration for a fetch.
  `Map<String,SummaryFunctionType>`
  `getSummaryFunctions()`
  A mapping from field names to `summary functions` to be applied to each field for a fetch.
  `Record`
  `getValues()`
  Values to be submitted for "update", "add" and "remove" operations.
  `DSRequestTask`
  `setCriteria(Criteria criteria)`
  Criteria (including AdvancedCriteria) to use for "fetch" and "export" operations.
  `DSRequestTask`
  `setExportFormat(ExportFormat exportFormat)`
  The format in which the data should be exported.
  `DSRequestTask`
  `setFailureElement(String failureElement)`
  ID of the next sequence or element to proceed to if a failure condition arises from DataSource operation.
  `DSRequestTask`
  `setFixedCriteria(Criteria fixedCriteria)`
  Criteria to be submitted as part of the DSRequest, regardless of inputs to the task.
  `DSRequestTask`
  `setFixedValues(Record fixedValues)`
  Values to be submitted as part of the DSRequest, regardless of inputs to the task.
  `DSRequestTask`
  `setGroupBy(String... groupBy)`
  List of fields to group by for a fetch.
  `DSRequestTask`
  `setOperationId(String operationId)`
  The `operationId` to invoke.
  `DSRequestTask`
  `setOperationType(DSOperationType operationType)`
  Type of operation to invoke.
  `DSRequestTask`
  `setOutputField(String outputField)`
  Field in the `process state` where this task writes outputs.
  `DSRequestTask`
  `setOutputFieldList(String... outputFieldList)`
  List of multiple fields in the `process state` where this task will write outputs.
  `DSRequestTask`
  `setPassThruOutput(Boolean passThruOutput)`
  Does this processElement pass through output from the last executed task (i.e.
  `DSRequestTask`
  `setSort(SortSpecifier... sort)`
  An array of `SortSpecifier` objects used to set up the sort configuration for a fetch.
  `DSRequestTask`
  `setSummaryFunctions(Map<String,SummaryFunctionType> summaryFunctions)`
  A mapping from field names to `summary functions` to be applied to each field for a fetch.
  `DSRequestTask`
  `setValues(Record values)`
  Values to be submitted for "update", "add" and "remove" operations.

  ### Methods inherited from class com.smartgwt.client.util.workflow.Task

  `getExpressionValue, getInputFieldList, getInputRecord, getInputs, getInputsAsString, getInputsAsStringArray, getOutputExpression, getState, getStrictPaths, setInputFieldList, setInputs, setInputs, setInputs, setOutput, setOutputExpression, setState, setStrictPaths`

  ### Methods inherited from class com.smartgwt.client.util.workflow.ProcessElement

  `completeElement, convertToJavaScriptArray, executeElement, getBindOutput, getClassDescription, getComponentReferences, getCurrentProcess, getDescription, getDynamicValue, getEditorType, getElementDescription, getForceSingle, getID, getInvalidTaskMessage, getJsObj, getMockMode, getNextElement, getOrCreateJsObj, getProcessElements, getSupportsMultipleInputRecords, getTextFormulaValue, getTypeTitle, getUndefinedComponentMessage, getUnresolvedComponentMessage, getWaitDuration, getWaitFor, getWaitLocator, isCreated, isValid, objectReferencesLastTaskOutput, onInit, reset, setAttribute, setBindOutput, setClassDescription, setCurrentProcess, setDescription, setEditorType, setForceSingle, setID, setJavaScriptObject, setMockMode, setNextElement, setSupportsMultipleInputRecords, setTypeTitle, setUndefinedComponentMessage, setUnresolvedComponentMessage, setWaitDuration, setWaitFor, setWaitLocator, updateGlobalIDInCriteria, updateGlobalIDInTextFormula, updateGlobalIDInValueProperty, updateGlobalIDInValues, updateGlobalIDReferences, updateLastElementBindingReferences, updateLastElementInCriteria, updateLastElementInValueProperty, updateLastElementInValues`

  ### Methods inherited from class com.smartgwt.client.core.BaseClass

  `addDynamicProperty, addDynamicProperty, addDynamicProperty, addDynamicProperty, applyFactoryProperties, asSGWTComponent, clearDynamicProperty, createJsObj, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getRef, getRuleScope, getScClassName, getTestInstance, hasAutoAssignedID, hasDynamicProperty, internalSetID, internalSetID, isConfigOnly, isFactoryCreated, onBind, registerID, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setConfig, setConfigOnly, setFactoryCreated, setProperty, setProperty, setProperty, setProperty, setRuleScope, setScClassName`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### DSRequestTask

    public DSRequestTask()

  - ### DSRequestTask

    public DSRequestTask(JavaScriptObject jsObj)

- ## Method Details

  - ### getOrCreateRef

    public static DSRequestTask getOrCreateRef(JavaScriptObject jsObj)

  - ### create

    public JavaScriptObject create()
    Overrides:
      `create` in class `Task`

  - ### setCriteria

    public DSRequestTask setCriteria(Criteria criteria) throws IllegalStateException
    Criteria (including AdvancedCriteria) to use for "fetch" and "export" operations.

    Data values in this criteria prefixed with "$" will be treated as dynamic expressions which can access the inputs to this task as $input - see `TaskInputExpression`. Specifically, this means that for simple criteria, any property value that is a String and is prefixed with "$" will be assumed to be an expression, and for AdvancedCriteria, the same treatment will be applied to `Criterion.value`.

    If any data value should not be treated as dynamic (for example, a "$" should be taken as literal), you can place it in `fixedCriteria` instead.

    Ignored for any operationType other than "fetch" and "export". Update or delete operations should place the primary key to update in `values`.

    This property supports `DynamicCriteria` - use `Criterion.valuePath` to refer to values in the `Process.ruleScope`.

    Parameters:
      `criteria` - New criteria value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Task Input / Output`

  - ### getCriteria

    public Criteria getCriteria()
    Criteria (including AdvancedCriteria) to use for "fetch" and "export" operations.

    Data values in this criteria prefixed with "$" will be treated as dynamic expressions which can access the inputs to this task as $input - see `TaskInputExpression`. Specifically, this means that for simple criteria, any property value that is a String and is prefixed with "$" will be assumed to be an expression, and for AdvancedCriteria, the same treatment will be applied to `Criterion.value`.

    If any data value should not be treated as dynamic (for example, a "$" should be taken as literal), you can place it in `fixedCriteria` instead.

    Ignored for any operationType other than "fetch" and "export". Update or delete operations should place the primary key to update in `values`.

    This property supports `DynamicCriteria` - use `Criterion.valuePath` to refer to values in the `Process.ruleScope`.

    Returns:
      Current criteria value. Default value is null
    See Also:
      - `Task Input / Output`

  - ### setExportFormat

    public DSRequestTask setExportFormat(ExportFormat exportFormat) throws IllegalStateException
    The format in which the data should be exported. See `ExportFormat` for more information.
    Parameters:
      `exportFormat` - New exportFormat value. Default value is "csv"
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getExportFormat

    public ExportFormat getExportFormat()
    The format in which the data should be exported. See `ExportFormat` for more information.
    Returns:
      Current exportFormat value. Default value is "csv"

  - ### setFailureElement

    public DSRequestTask setFailureElement(String failureElement) throws IllegalStateException
    ID of the next sequence or element to proceed to if a failure condition arises from DataSource operation.
    Parameters:
      `failureElement` - New failureElement value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getFailureElement

    public String getFailureElement()
    ID of the next sequence or element to proceed to if a failure condition arises from DataSource operation.
    Returns:
      Current failureElement value. Default value is null

  - ### setFixedCriteria

    public DSRequestTask setFixedCriteria(Criteria fixedCriteria) throws IllegalStateException
    Criteria to be submitted as part of the DSRequest, regardless of inputs to the task. Will be combined with the data from the `Task.inputs` or with `criteria` if specified, via `DataSource.combineCriteria()`.
    Parameters:
      `fixedCriteria` - New fixedCriteria value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getFixedCriteria

    public Criteria getFixedCriteria()
    Criteria to be submitted as part of the DSRequest, regardless of inputs to the task. Will be combined with the data from the `Task.inputs` or with `criteria` if specified, via `DataSource.combineCriteria()`.
    Returns:
      Current fixedCriteria value. Default value is null

  - ### setFixedValues

    public DSRequestTask setFixedValues(Record fixedValues) throws IllegalStateException
    Values to be submitted as part of the DSRequest, regardless of inputs to the task. Will be combined with the data from the `Task.inputs` or with `values` if specified, via simple copying of fields, with `fixedValues` overwriting values provided by the `inputs`, but explicitly specified `values` overriding `fixedValues`.
    Parameters:
      `fixedValues` - New fixedValues value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getFixedValues

    public Record getFixedValues()
    Values to be submitted as part of the DSRequest, regardless of inputs to the task. Will be combined with the data from the `Task.inputs` or with `values` if specified, via simple copying of fields, with `fixedValues` overwriting values provided by the `inputs`, but explicitly specified `values` overriding `fixedValues`.
    Returns:
      Current fixedValues value. Default value is null

  - ### setGroupBy

    public DSRequestTask setGroupBy(String... groupBy) throws IllegalStateException
    List of fields to group by for a fetch.

    See the `Server Summaries overview` for examples of usage.

    Parameters:
      `groupBy` - New groupBy value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `setSummaryFunctions(java.util.Map<java.lang.String, com.smartgwt.client.types.SummaryFunctionType>)`
      - `Server Summaries`

  - ### getGroupBy

    public String[] getGroupBy()
    List of fields to group by for a fetch.

    See the `Server Summaries overview` for examples of usage.

    Returns:
      Current groupBy value. Default value is null
    See Also:
      - `getSummaryFunctions()`
      - `Server Summaries`

  - ### setOperationId

    public DSRequestTask setOperationId(String operationId) throws IllegalStateException
    The `operationId` to invoke.
    Parameters:
      `operationId` - New operationId value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getOperationId

    public String getOperationId()
    The `operationId` to invoke.
    Returns:
      Current operationId value. Default value is null

  - ### setOperationType

    public DSRequestTask setOperationType(DSOperationType operationType) throws IllegalStateException
    Type of operation to invoke. A special "export" operation type is supported to perform a server export based on criteria.
    Parameters:
      `operationType` - New operationType value. Default value is "fetch"
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getOperationType

    public DSOperationType getOperationType()
    Type of operation to invoke. A special "export" operation type is supported to perform a server export based on criteria.
    Returns:
      Current operationType value. Default value is "fetch"

  - ### setOutputField

    public DSRequestTask setOutputField(String outputField) throws IllegalStateException
    Field in the `process state` where this task writes outputs. See `TaskIO`.

    See `outputFieldList` for a shorthand method to save the full operation response data.

    Overrides:
      `setOutputField` in class `Task`
    Parameters:
      `outputField` - New outputField value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Task Input / Output`

  - ### getOutputField

    public String getOutputField()
    Field in the `process state` where this task writes outputs. See `TaskIO`.

    See `outputFieldList` for a shorthand method to save the full operation response data.

    Overrides:
      `getOutputField` in class `Task`
    Returns:
      Current outputField value. Default value is null
    See Also:
      - `Task Input / Output`

  - ### setOutputFieldList

    public DSRequestTask setOutputFieldList(String... outputFieldList) throws IllegalStateException
    List of multiple fields in the `process state` where this task will write outputs. See `TaskIO`.

    If `outputField` is also specified, it will be implicitly added to the `outputFieldList` if it is not already present.

    In addition to pulling individual fields from the task operation result and placing them into the process state the full response data can also be written into the process state without specifying individual fields. Prefix a destination field path with a "$" (ex. $orderHeader) causes the entire `dsResponse.data` to be saved.

    Overrides:
      `setOutputFieldList` in class `Task`
    Parameters:
      `outputFieldList` - New outputFieldList value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `Task Input / Output`

  - ### getOutputFieldList

    public String[] getOutputFieldList()
    List of multiple fields in the `process state` where this task will write outputs. See `TaskIO`.

    If `outputField` is also specified, it will be implicitly added to the `outputFieldList` if it is not already present.

    In addition to pulling individual fields from the task operation result and placing them into the process state the full response data can also be written into the process state without specifying individual fields. Prefix a destination field path with a "$" (ex. $orderHeader) causes the entire `dsResponse.data` to be saved.

    Overrides:
      `getOutputFieldList` in class `Task`
    Returns:
      Current outputFieldList value. Default value is null
    See Also:
      - `Task Input / Output`

  - ### setPassThruOutput

    public DSRequestTask setPassThruOutput(Boolean passThruOutput) throws IllegalStateException
    Does this processElement pass through output from the last executed task (i.e. transient state)?

    See `taskInputExpressions` for details on the transient state outputs.

    Note that this property does not affect the task at all but is an indicator to the user and to the workflow editor of the behavior of the task as coded (See `Process.passThruTaskOutput()`).

    Overrides:
      `setPassThruOutput` in class `ProcessElement`
    Parameters:
      `passThruOutput` - New passThruOutput value. Default value is false
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getPassThruOutput

    public Boolean getPassThruOutput()
    Does this processElement pass through output from the last executed task (i.e. transient state)?

    See `taskInputExpressions` for details on the transient state outputs.

    Note that this property does not affect the task at all but is an indicator to the user and to the workflow editor of the behavior of the task as coded (See `Process.passThruTaskOutput()`).

    Overrides:
      `getPassThruOutput` in class `ProcessElement`
    Returns:
      Current passThruOutput value. Default value is false

  - ### setSort

    public DSRequestTask setSort(SortSpecifier... sort) throws IllegalStateException
    An array of `SortSpecifier` objects used to set up the sort configuration for a fetch.
    Parameters:
      `sort` - New sort value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getSort

    public SortSpecifier[] getSort()
    An array of `SortSpecifier` objects used to set up the sort configuration for a fetch.
    Returns:
      Current sort value. Default value is null

  - ### setSummaryFunctions

    public DSRequestTask setSummaryFunctions(Map<String,SummaryFunctionType> summaryFunctions) throws IllegalStateException
    A mapping from field names to `summary functions` to be applied to each field for a fetch.

    See the `Server Summaries overview` for examples of usage.

    Parameters:
      `summaryFunctions` - New summaryFunctions value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `setGroupBy(java.lang.String...)`
      - `Server Summaries`

  - ### getSummaryFunctions

    public Map<String,SummaryFunctionType> getSummaryFunctions()
    A mapping from field names to `summary functions` to be applied to each field for a fetch.

    See the `Server Summaries overview` for examples of usage.

    Returns:
      Current summaryFunctions value. Default value is null
    See Also:
      - `getGroupBy()`
      - `Server Summaries`

  - ### setValues

    public DSRequestTask setValues(Record values) throws IllegalStateException
    Values to be submitted for "update", "add" and "remove" operations.

    Similar to `Criteria`, data values prefixed with "$" will be treated as a `TaskInputExpression`. Use `fixedValues` for any values that start with "$" but should be treated as a literal.

    Parameters:
      `values` - New values value. Default value is null
    Returns:
      `DSRequestTask` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getValues

    public Record getValues()
    Values to be submitted for "update", "add" and "remove" operations.

    Similar to `Criteria`, data values prefixed with "$" will be treated as a `TaskInputExpression`. Use `fixedValues` for any values that start with "$" but should be treated as a literal.

    Returns:
      Current values value. Default value is null

  - ### getInstanceDescription

    public String getInstanceDescription()
    Overrides `ProcessElement.getInstanceDescription()` to prefer, in order: an instance-level `ProcessElement.description`; the `OperationBinding.description` of the `OperationBinding` this task invokes; and finally the inherited class-level `ProcessElement.classDescription`.

    `OperationBinding.description` is checked before the generic `ProcessElement.classDescription` fallback because every concrete `DSRequestTask` subclass (`DSFetchTask` etc) always declares a non-empty `classDescription` - if the class-level fallback were checked first, the more specific operationBinding description would never be reached.

    See the IDocument on `getInstanceTitle()` - the same getOperationBinding()-degrades-to-the-DataSource-itself hazard applies here, and is guarded the same way (`binding != ds`). Left unguarded, this method returns the DataSource's own, often long, hand-authored business-context `DataSource.description` - meant to describe the whole DataSource to a human or an AI reading its schema, not one Task's instance description - identically for every task against that DataSource regardless of operation type, which is misleading rather than merely wrong.

    Overrides:
      `getInstanceDescription` in class `ProcessElement`
    Returns:
      description for this instance

  - ### getInstanceTitle

    public String getInstanceTitle()
    Overrides `ProcessElement.getInstanceTitle()` to prefer, in order: the `OperationBinding.title` of the `OperationBinding` this task invokes; an auto-title derived from `operationId` via `DataSource.getAutoTitle()`; and finally the inherited class-level title (e.g. "DataSource Fetch" for `DSFetchTask`).

    Overrides:
      `getInstanceTitle` in class `ProcessElement`
    Returns:
      title for this instance