Defining Work Queues

Work queues represent the different tasks that are meant to be performed in a business process. Work items that are eventually performed by the operatives of a team are generated according to this definition. They are associated to a specific business process and as such are in the context of an instance of a certain definition.

Here, we'll define the "Perform Interview" queue.

Identification

Work queues are identified by their Name - this is a bried description of the work itself. An optional aribitrary Code can be provided to help sort work queues in listing or in searching.

The name of a work queue should specify what the operative that is assigned a work item should do. For example, "Verify if applicant checks requirements".

The name of a work queue should complete the sentence: "To go from state X to state Y, we need to _____".

TIP

The naming convention is a helpful guide, but there might be exceptions - for example, tasks that not change the state. Regardless, the sentence should still be in imperative mood.

Considering this, we can fill these fields in the following way:

Specification

The specification of a work queue defines who performs the items generated by the queue (the agent), what possible states these items have (which implies what actions are possible), and how this queue impacts the instance it is affiliated to.

There is also a Description that serves to describe the task in depth, if necessary.

Agent

Work Queues generate Work Items, which in turn are performed by an Agent. That agent can take the form of a:

• Human. Someone will perform the task at hand and let RecordM know when it is complete, cancelled, etc.
• RPA. A script written by a developer to be executed during this work queue.
• Wait.

Human

When there is a Human Agent, we must specify who that human (or humans) is. To do, we specify a Human Type:

1. Group. Explicitly state who the group to perform this queue is.
2. Group Field. When we don't know what group might need to complete the task at queue creation, we can specify a field of the Specific Data definition that will contain the group meant to perform this task. This field should be an $extRef to a UserM group.
3. User. We can also explicitly state a specific user to perform the task.
4. User field. When the user is not known at creation time, we can specify a field in the definition Specific Data that points to the user that should perform the task (as an $extRef to a UserM user).

For example, in our case, we want the person who performs the interview to be the owner of the offer. As such, we should specify the agent as such:

RPA

Some tasks can be automatized - like sending a rejection e-mail. In these cases, we can specify that the task is completed by an RPA agent, which is associated to a Groovy Concurrent script (likely written by a developer).

Possible states

The possible states of a work queue define how a work item generated by it can evolve over time and what actions are available to make it progress.

A complex task may go through a series of states before finally being complete. The list of possible states is as follows:

1. To Assign adds an additional work step that must be performed by someone, where they assign that work item to someone.
2. To Do means the task has work to be done.
3. In Progress allows the person performing the work to specify when they start the task and when they finish it.
4. Done is the most standard of states - it represents when a task is finished.
5. Pending allows for work to be paused and later resumed.
6. Error gives the task a chance to fail
7. Canceled adds the possibility of a task being cancelled (not to be confused with a task failing).

Because we want to time how long an interview usually lasts, we're going to select that In Progress is a possible state for our work queue. And since it needs to be done, it has a To Do state as well. As such, the selection is the following:

As we can see, there are two initial available actions: Complete and Start. The latter changes the state to In Progress and can then be completed.

Conditions

Work queues define when a work item needs to be launched/created (Launch Conditions) and when its completion is valid (Done Condition). These conditions are specified in the Business Process instance and are written in Groovy.

Launch Condition. The launch condition is a boolean expression that defines when this work condition should be launched. Most of the time, it'll take the form of the following expression. This expression tests whether the state has been changed to <state> (<state field name> is replaced by the name of state where the field is stored, same as the State Field in the process instance. ).

msg.field("<state field name>").changedTo("<state>")

Done Conditions. This condition signifies when a task is valid to be completed. When someone attempts to complete a work item, this boolean expression is checked. If it true, the work item is changed to Complete otherwise, an error message is shown. That error message is specified in the field Done Conditions Error Msg.

For example, if we wanted to check whether a field has a certain value, we can use the following expression.

data.value("<field name>") == "<value>"

TIP

In both conditions, the variable msg of type RecordmMsg is made available for the instance at work. For the On Done condition, the variable recordm of type RecordmActionPack is also available.

In our case, we don't want to allow the administrator to finish the task without first selecting whether the candidate has passed the interview - which he does by setting the field "Passed interview" as "Yes". In our example these conditions (and the error message) are specified as:

Task Conclusion

TIP

In the conditions, the variable msg of type RecordmMsg is made available for the instance at work.

We can also specify what happens when a task is done (or otherwise finished through an error or canceling). This is specified in the On * fields. Similarly to before, this is Groovy code, but unlike the conditions, it serves to alter the state of the instance, with code such as:

updates["<state field name>"] = "<new state>"

On Done. Is executed when the work item's state changes to done.

On Canceled. Only available when a work item has a Canceled state. Executes when an item is canceled.

On Error. Only available when a work item has an Error state. Executes when an item is said to have failed.

TIP

In all On *, the variable data of type RecordmInstance is made available, which allows access to the instance's fields and more. The variable recordm of type RecordmActionPack is also available. To update the instance at the end of the script, you can use the variables updates which a Groovy dictionary of field:new value updates to apply.

In our "Perform Interview" example, it looks like this:

Alternatives

Sometimes, a task will have multiple possible end states. For example, a candidate may be disqualified after an interview (state: "Not selected") or move onto the next phase (state: "Selected for final phase").

To have a branching state, we would instead use a code block like this, that uses an if before establishing the final state.

if( data.value("<field name>") == "<value>" ){ updates["<state field name>"] = "<new state>" }
if( data.value("<field name>") == "<other value>" ){ updates["<state field name>"] = "<other new state>" }

In these situations, the work item uses the data set in a field of the instance (<field name>) to make the decision. This is why a done condition to verify that the field has been filled is important.

Joins

A more complex example is when two or more tasks need to be done before altering the state. For example, before an application is selected it might be necessary for the administrator AND the HR manager to confirm it is appropriate.

When such a situation happens, it is called a join. The idea is similar to an alternative - an if that determines whether we advance to the next state. But now, instead of checking for a field that must be filled by hand, we check for a field that the other task must fill, while filling the field associated with this task.

Using the same example - the application would have a field "Administrator confirms" (with the options "Yes" and "No") and a field "HR confirms". Thus, the task "Confirm application is valid (Administrator)" would set "Administrator confirms" to "Yes" when completed and check whether "HR confirms" is set to "Yes". If it was, then it would advance the state. Otherwise, the "HR confirms" work queue would advance the state itself when it completed (because "Administrator confirms" is now set to "Yes").

The code for this On Done condition thus looks like:

updates["<field assciated to queue>"] = "<finished result>" ; // update field associated to this queue
if ( data.value("<field associated to parallel task>") == "<parallel finished result>" ) { updates["<state field name>"] = "<new state>" }  // change state if the other has finished

:::warn Good practice. These fields can technically run arbitrary groovy code and while it may be tempting to do so, the On * fields should only be used to alter the state of the instance, using the code examples shown above. Other code should be run through RPAs or other methods. This makes the code base more consistent and stable. :::

Error Checking

Business processes are associated to a visual diagram. This visual diagram is built from the previously specified code. If the diagram does not show up then there is likely an error in the specification of work queues. RecordM will try its best to find the source of the error and provide a helpful error message.

Conclusion

With that, you have your first work queue. By creating an instance of the central entity with the initial state of the work queue, you should be able to find a work item of that queue. It is recommended that a $references of work items is added to the definition of the central instance. This allows for users to quickly see what work needs to be done in regards to a particular entity.