Add Request in Workflow

Description

This package contains two plugins to facilitate sending samples to a workflow while they are currently running in a workflow and from within the workflow itself:

1. Add request from selection
2. Add request automatically

The package also contains two custom fields needed for some specific implementations (see Configuration section):

• On protocol step:
  • Requests to add: A field of type dynamic choice, multiple choice with a selection of requestables.
• On Request:
  • Next Requests: A field of type dynamic choice, multiple choice with a selection of requestables.

And one macro to add requests automatically:

• Add request automatically

By default, SLIMS allows samples to be sent to a Workflow from the Content module or via an Order, but not from within a Workflow step. This package provides a solution to work around these default functionalities.

Both plugins contained in this package run on a selection of samples and schedule each selected sample to a chosen request.

The behavior of the two plugins differ in the following aspects:

1. Add request from selection:
   1. The request(s) for the selected sample(s) are selected by the user. User feedback (selecting the request) is required to finish the step.
   2. The request(s) selection applies to all selected samples. If different samples should be scheduled to different requests, the user will run the plugin several times.
   3. This plugin can only have “Usage ELN” (it is executed in a protocol run step).
2. Add request automatically:
   1. The request(s) for the selected sample(s) are calculated automatically (see the How to use the package section). No user feedback is required and the plugin may run automatically (usage macro automatically running at start of step).
   2. The request(s) may depend on the samples. Selected samples may be scheduled for different requests.
   3. This plugin can have “Usage ELN” (need to manually start the plugin) or “Usage macro” (via plugin used as a SLIMS GATE flow macro step).

This table illustrates the differences:

*YES/NO: The requests calculated automatically may depend on the sample or not, depending on the implementation (refer to the Configuration details below).

Note: The plugins in this package can only add requestables of type Workflow. It is not possible to add Default (analytical workflows) or Content requestables.
The plugins may run from analytical workflows, with some limitation as explained in the How to use the package > Usage in analytical workflows section.

How to use the package

Pre-requisites

• The plugins contained in this package can run from a workflow step (directly in the step or through a macro).
  • Consequently, the necessary contents, requests, workflows, and orders should be already configured in SLIMS.
  • If the macro is used in the step it can be set to “Run on start of step” to remove any needed interactions from the user.
• The plugins run from standard workflows and can only add requestables from the Workflows module which are non-analytical. Additionally, to use this flow with a requestable that has Target: Sequencing settings, some additional configuration is needed: see the Extension section.
• The plugins may also run in analytical workflows (still only to add non-analytical requestables) but some limitations are expected and explained in the Usage in analytical workflow section below.

Configuration

Plugins

The following configuration parameters have similar meaning in both plugins and can be customized to the user’s needs:

• id, name and icons: These parameters can be customized similarly to any other plugin.
• linkToOrder: True/false option that controls whether the assigned requests are also linked to the initial order or not (default is true). This option should be set to false if the original samples are send to the workflow from the Content module.
• revertOrderStatusUID: The unique identifier (UID) of an order status (default value stts_ordr_registered). If option linkToOrder is true, the order is reverted to this status, contents and requests are linked, and then the order is scheduled again.

The configuration parameters specific to the Add request from selection plugin are:

• fetchRequestablesForSelectionImplementation:  The name of the bean that fetches requestables to be presented for selection with two choices:
  • fetchAllRequestables: All requestables of type Workflow are returned.
    All requestables of type Workflow are presented to the user for selection.
  • fetchRequestablesFromProtocolStepField: Requestables defined in the custom field xpst_cf_fk_requestsToAdd (parameter requestablesFilterFieldName) are returned.
    The requestables available for selection are defined on a custom field of the protocol step so that the user will be presented with a choice between those requestables.
• requestablesFilterFieldName: The name of the protocol step field to fetch requestables for selection (default value xpst_cf_fk_requestsToAdd).
  This field should be a dynamic choice datatype on the table Requestables. Multiple choice is the default configuration, but single choice is also supported.
• selectionGridFields: Map of fields to show in the selection grid.Map defining the columns to show in the selection grid. Keys are the SLIMS field names (e.g. “rqbl_name”) and values are the displayed header name (e.g. “Requestables). The default map is:
  • wrfl_name: “Workflow”
  • rqbl_name: “Requestable”
  • start_queu_name: “Start queue”
  • end_queu_name: “End queue”

  If a key has no value, the SLIMS label will be displayed. For example:

  • rqbl_name:

This is not recommended as both rqbl_name and wrfl_name would be displayed as “Name.”
Available fields: Requestables fields (e.g. rqbl_name) and display fields of tables linked to the requestable (e.g. wrfl_name).

The configuration parameters specific to the Add request automatically plugin are:

• pluginUsage: Possible usages are:
  • macro: Can be used in a macro step and, for example, run automatically on start of step (default usage).
  • eln: To be triggered manually in a protocol run step.
• fetchRequestablesByContentImplementation: The name of the bean that fetches requestables by content, with two choices:
  • fetchContentRequestablesFromCurrentRequestField: Requestables defined in the custom field rqst_cf_fk_nextRequests (parameter requestablesToAddFieldName) are returned.
    For each selected sample, the plugin finds the associated initial request. On the request, a field “Next Requests” should be present and list one or more Requestables. The content is scheduled with those next requestables.
    This implementation allows different requests to be added by content because “Next Requests” is defined on each current Request. Note: This implementation cannot be used if the samples with the initial request are mixed.
  • fetchContentRequestablesFromProtocolStepField: Requestables defined in the custom field xpst_cf_fk_requestsToAdd (parameter requestablesToAddFieldName) are returned.
    The requestables for next requests are defined on a custom field of the protocol step. All selected contents are scheduled with those next requestables.
    All contents get the same next requests in this implementation. 
• requestablesToAddFieldName: The name of the request field to fetch requests to add (default value rqst_cf_fk_nextRequests).
  This field should be a dynamic choice on the table Requestables. Multiple choice is the default configuration, but single choice is also supported.

Protocol step/request

With the default configuration, to use the “Add request from selection” plugin, the field “Requests to add” should be filled out on the protocol step with all the possible requests the user should have available.

The plugin “Add request automatically” is configured by default to add the requestable that is set on the original request of the content in the field “Next request.” This field should be filled out manually for each content when the first request is added (this can only be done in the Workflows module). If the next request should always be the same based on a specific logic, it is advised to set an automatic completion of this field via Groovy or change the plugin configuration to use the value of the “Requests to add” field on the protocol run step.

Usage in Analytical Workflows

The plugins in this package may run in analytical workflows, but can only schedule non-analytical workflow requestables (i.e. requestables created in the Workflow Management module, in the Requestable tab).

Also the following limitations apply:

• Parameter “linkToOrder” should be set to false (it is not possible to link a non-analytical request to an analytical order).
• Implementation “fetchContentRequestablesFromCurrentRequestField” will not work. The provided implementation cannot find the original current request starting from an analytical workflow.

Step by Step Usage Procedure

The plugin Add request from selection can be configured to be the SLIMS GATE flow that will be executed in a protocol run step.

In the protocol run step, the user must select the content(s) (one or multiple), then click on the plugin icon to start.

The plugin will show a list of possible Requestables to add. The user must then select the request(s) to add and click “Finish.”

All the selected requests will be added to all the selected contents. The flow can be run multiple times with a different selection to assign different requests to different contents.

The plugin Add request automatically can be configured to be the SLIMS GATE flow that will be executed in a protocol run step (usage ELN) or in a macro step (usage macro).

If usage is ELN, the plugin must be started after the content(s) have been selected (like for the Add request from selection plugin). However, no further feedback is asked and the applicable requests are added automatically.

If usage is macro, the plugin must be still started from a protocol run step via a macro that has previously been defined. In this case, the macro can also be configured to start automatically at start of the step.
As for usage ELN, no further feedback is asked of the user.

Extension

Usage with Requestable that have Sequencing settings as target

If the Requestable that should be added to the sample has the field Target set to Sequencing settings, it is required to add a Fixed sequencing settings on the Requestable and add the following Groovy to the field “Panel” on the Request table.

Where to Look Next

These references have further information on how to configure or use the package contents after the initial installation and integration.

• SLIMS Administrator Manual:
  • Electronic Lab Notebook → Protocols → Protocol Steps (Restrict and specify extra options about macros, Can execute SLIMS GATE Flows)
  • Electronic Lab Notebook → Miscellaneous → Macro (Execute SLIMS GATE Flow)