Creating a Set Fields action

To define a Set Fields action, you first identify the data source option for the field value or values to be set. The procedures in this section describe how to create a Set Fields action that uses the following data source options:

  • CURRENT SCREEN (active links) or CURRENT TRANSACTION (filters and escalations)
  • SERVER (active links, filters, and escalations)
  • SAMPLE DATA (active links, filters, and escalations)

For information about using the data source options SQL, FILTER API, and WEB SERVICES, see the sections referenced in Defining-Set-Fields-actions-to-assign-values-based-on-conditions.

Depending on the option selected, the Set Fields panel changes to allow you to define the specific data to retrieve. For all data source options, the Set Fields panel includes a table containing the columns Field and Value, where you define the fields to be changed with the Set Fields action, and the value to enter in each field.

For example, the following figure shows a Set Fields action in the Sample: DialogYes active link from the AR System server sample application.

Set fields panel for active link using CURRENT SCREEN data source

ALSetFields-SampleAppDialogYesDS.gif

To use the CURRENT SCREEN or CURRENT TRANSACTION data source

When you define the data source for a Set Fields action as CURRENT SCREEN (active links) or CURRENT TRANSACTION (filters and escalations), the field is set with a value that is not from the database. You can set the field value by getting a value from another field in the current request (active links or filters), by defining a static value, by using a AR System server keyword, or by using the result of a function, process, or arithmetic operation.

  1. Right-click the If Actions or Else Actions panel header.
  2. Select Add Action > Set Fields.
  3. From the Data Source list, select CURRENT SCREEN (active links) or CURRENT TRANSACTION (filters and escalations.) This is the default setting.
  4. In the field mapping table, click the first blank row in the Field column, and then click the ellipsis button to open the Field Selector dialog box.
  5. In the Field Selector dialog box, enter the field to which you want to assign a value in the Field column.
  6. In the Value column for this field, build an expression to define the value to set, as described in Using-field-names-field-values-and-expressions-in-workflow.
    You can set the field value using another field in the current request, a keyword, a static value, or other data sources, such as the result from a process, function, filter API. For information about using external data sources, see Defining-Set-Fields-actions-to-assign-values-based-on-conditions.

  7. When the expression is complete, click OK to close the Expression Editor dialog box.

    If you enter a server name and form different than the CURRENT SCREEN, but you do not reference a field from another form, there is no need to retrieve a value from the database, and the server name and form revert to CURRENT SCREEN when the workflow object is reopened. Also, If you enter a form different than the CURRENT TRANSACTION but you set the field by using a static value or a keyword or if you do not set the field from another form, there is no need to retrieve a value from the database, and the form reverts to CURRENT TRANSACTION when the workflow object is reopened.

  8. To change additional fields using the same Set Fields action, continue selecting fields in the Field column, and then define the appropriate expression in the Value column.

    If you have dependent fields, you should always break up the set fields into multiple Set Field actions so that field dependencies are executed correctly.

Using the SERVER data source

When you define the data source for a Set Fields action as SERVER, you can set the field value by getting a value from another request or form, as follows:

  • For active links, from another request in this form or from another form on this server or another server.
  • For filters and escalations, from another request in this form or from another form on this server. You can also use static values, AR System server keywords, and the results of a function, process, or arithmetic operation with the SERVER data source. 

    To use data from a server that is determined dynamically at runtime, use the data source SAMPLE DATA instead of SERVER. See Using the SAMPLE DATA data source.

Progressive Web Application (PWA) supports the Set Field actions by using the SERVER data source. To see the behavior in Progressive View, see Set Field actions by using the SERVER data source in Progressive Views.

 To use the SERVER data source

  1. Right-click the If Actions or Else Actions panel header.
  2. Select Add Action > Set Fields.
  3. From the Data Source list, select SERVER.
  4. (Active links only ) From the Server Name list, select the server that contains the data to be retrieved.
    To cause another server to appear in the Server Name list, you must be logged in to that server. You can also enter the server name manually, but you must be able to log on to the specified server with the current user name and password. Otherwise, the Login dialog box does not appear for the other server.
  5. In the Form Name field, select the form from which the Set Fields action should retrieve data:
    • If the source form is the primary form for the active link, filter, or escalation, no change is required. The primary form appears in the Form Name field by default.
    • To select a different form as the source form, click the ellipsis button and then select the appropriate form from the Available Forms list.
      To locate a form quickly in the list, use the Filtering Options or the Locate field in the Form Selector dialog box. See Viewing-objects-in-an-object-list.

  6. Use the Qualification field to build an expression to find the request that contains the values you want to retrieve. Click the ellipsis button to use the Expression Editor.
    You can also type the expression directly in the Qualification field. See Using-buttons-and-menu-bar-items-to-execute-active-links
    In the Expression Editor, the primary form for the active link, filter, or escalation is the "current form." If you selected another form in the Form Name field ( step 5), you can use fields from that form in the expression as well.

    Warning

    When you use the Qualification field to retrieve data for the Set Field action, the action runs a query to retrieve a list of the requests to get data values from. Therefore, optimize the Set Field If qualification for best system performance.

  7. From the If No Requests Match list, select a handling option to control how the system responds when no matches are found in the selected form.
    • Display 'No Match' Error—Returns an error message and stops processing.
    • Set Fields to $NULL$—Sets field values obtained from a qualification expression to NULL unless the values are static or are based on keywords.
      For example, suppose a field value is based on this expression:
      $fieldName$ + " on " + $SERVER$
      If no matches are found, $fieldName$ is set to NULL, and only the static value and the value based on the keyword appear in the field:
      onserverName
  8. From the If Multiple Requests Match list, select a handling option to control how the system responds when multiple matches are found in the selected form.
    • Display 'Multiple Match' Error—Returns an error message and stops processing.
    • Use First Matching Request—Inserts the value of the first request that meets the qualification.
    • Set Fields to $NULL$—Sets field values obtained from a qualification expression to NULL unless the values are static or are based on keywords.
      For example, suppose a field value is based on this expression:
      $fieldName$ + " on " + $SERVER$
      If multiple matches are found, $fieldName$ is set to NULL, and only the static value and the value based on the keyword appear in the field:
      onserverName
    • Display a List (active links only)—Displays a selection list so the user can select the appropriate request. The selection list uses the form's result list specification.
    • Use First Matching Request Based On Locale—Returns localized information to determine the match.
      The contents of the Locale field (special field ID 160) are used along with the current user's locale to select the best match. If there are several matches with the same locale, then the first match is returned.
      If there is no localized server or no Locale field in the form, this option becomes the same as Use First Matching Request option. For more information about using the Locale field with localizing search menus, see Localizing-menus.
  9. Use the field mapping table to map the fields and values from the source form to the current request as follows:

    • To use matching field IDs to automatically map the values of all matching fields from the source form to the current form, select the Matching IDs check box. The field mapping table is disabled, and you cannot select specific field mappings.
      In this case, all matching field IDs (except for table columns, panel holders, and core fields such as Modified Date and Request ID) from the source form are automatically set in the current form.

      Tip

      When you use Matching IDs, the values are dynamic. This means that only the setting is stored as part of the Set Fields action, and not the actual values. Therefore, you can add data fields to these forms at a later stage and the action will use them when executed.

    • To use the Auto Map dialog box, click Auto Map.
      The Auto Map dialog box opens with all matching fields entered in the list. To delete a field you do not want to update, select the field and click Remove. After making selections in the Auto Map dialog box, click OK.

      Tip

      You can use Auto Map to map fields according to the field name or field ID. When you use Auto Map with field names, the mappings are dynamic. However, when you use Auto Map with field IDs, the mappings are stored with the form. In this case, if you later add fields to the forms, they will not be part of the action and must be added manually.

    • To map specific fields and to use an expression to define the value, follow the steps described in Using-field-names-field-values-and-expressions-in-workflow.
      In the Field column, select the fields to which you want to assign a value. In the Value column, use the expression editor to define the value to set from the source form.
      To set the field value using other data sources, such as the result from a process, function, filter API, and so on, see Defining-Set-Fields-actions-to-assign-values-based-on-conditions.
  10. Save the active link, filter, or escalation.

Set Fields actions by using the SERVER data source in Progressive Views

The Set Field from Server action is a logical action that sets the values of the fields from a remote form. There is no change to the user interface. Only when there is Display as List, a blade comes to show the list of entry data as per your need to select an item in a table list. That item is used by the Set Field action to perform the action.

The following image shows the Set Fields action in Progressive Views:

set-field-from server.png

Using the SAMPLE DATA data source

To create a Set Fields action that uses runtime information to identify the source server and form, use the SAMPLE DATA data source. For general information about using SAMPLE DATA, see Using-a-dynamic-data-source-or-destination-in-workflow. 

To use a dynamic data source in a Set Fields action, your application must include the following objects and functionality:

  • If the server and form name for the source data are taken from fields on the primary form, the workflow or user interaction must be designed to populate these fields before executing the Set Fields action.
  • The sample form must contain fields with the same field IDs as the potential Set Fields source form on the runtime servers. You use the "sample" fields on this form to complete the field mapping section of the Set Fields action. The "sample" form must contain field IDs that exist on any dynamic source forms that are used at runtime.
  • All potential Set Fields source forms must contain fields with the correct field IDs.
  • If the server and form name for the source data are not taken from keywords, the primary form must contain fields to hold the runtime values of server name (for active links) and form name (for all workflow types). These fields can be populated by workflow or the values can be entered by a user (if active link).

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*