Modifying forms to submit tasks to the background queue

The application runs reports as background tasks that are placed on a "queue" to be run in order. You can also set up other tasks to run in the background. The TaskMan service polls the list of Active Background Tasks and executes any new task that is posted to the queue with a status of READY.

  1. To set up the form for which you want the background task to run:
    1. Add a MenuItem component called BackgroundQueue to the form.
    2. On the Behavior tab, add RunBackgroundQueue as the primary event.
    3. Create a RunBackgroundQueue event of type Run Form As Modal Child.
      The parameters for the event should be as shown in this example, where GenerateReport is the name of the form's Run Background Task event: BackgroundQueue( SETVARVALUES(BGTaskName=V(BGTaskName), RunTaskEvent=GenerateReport) )
    4. Add parameters to the end of the parameter string for the Run Background Task event that submits the task:
      TASKSTATUS(V(BGTaskStatus))TASKNUMBER(BGTaskNumber)

      Use these keywords and parameters:

      • TASKSTATUS is an optional input parameter to BGTaskSubmit. If the TASKSTATUS keyword is omitted, or if its value is anything other than WAITING, the task is inserted into the ActiveBGTasks table with a status of READY and is run by TaskMan. If TASKSTATUS is set to WAITING, the task is entered in the ActiveBGTasks table with a status of WAITING. TaskMan ignores any records in this table with a status other than READY or RUNNING.
      • TASKNUMBER is an optional keyword used to specify the name of a variable that holds the TaskNumber generated when a record is inserted into the ActiveBGTasks table.
      • You can include substitution keywords that are replaced by appropriate values after the task is submitted to TaskMan.
  2. Create a background task.
    For the procedure, see Creating a background task definition.
  3. Configure the form event you created in Step 1 to run the background task you just created.
  4. Save your work and test the form event to make sure it works as expected.
You can use the Active Background Tasks form to see which tasks are currently running.

After TaskMan has completed the task, even if it fails, you can view details about its execution on the Background Task History form. Details include:

  • Task description
  • Return status
  • User who submitted the task
  • Messages triggered by the task
Related topics