Modifying Forms to Submit Tasks to the Background Queue

Use these steps to include a task that runs in the background on a form.

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.

For more information about TaskMan, see the Administration Guide or Creating and Customizing Reports.

To set up the form where you want the background task to run:
1. Add a component called BackgroundQueue of type ObjMenuItem to the form. On the Behavior tab, add RunBackgroundQueue as the primary event.
2. 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) )
3. 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 will be inserted into the ActiveBGTasks table with status READY and will be run by TaskMan. If TASKSTATUS is set to WAITING, the task will be entered in the ActiveBGTasks table with status WAITING. TaskMan ignores any records in this table with status other than READY or RUNNING.
  - TASKNUMBER is an optional keyword used to specify a variable name that will hold 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.
To create a background task:
1. Create a new record on the Background Task Definitions form.
2. Specify a task name, for example, RunCustomerOrderReport, and a description.
3. Specify an executable name:
  - For a report, specify the name of the report (for example, CustomerOrder) in the first "executable" field and the type of executable (RPT) in the second field. The report definition (.RPT file) for this report must be placed in the TaskMan\Reports folder on the server where TaskMan and a report generating module are installed.
  - For a stored procedure, specify the procedure name in the first field and select SP in the second field.
  - For an executable program, specify the program name and path (for example, c:\Infor\myprog) in the first field and select EXE in the second field.
    Either specify the complete path or use a path relative to the directory containing TaskMan on the server. For example, if you have an executable program called MyProg.exe that resides in mydirectory/mysubdirectory under the Infor TaskMan directory, you specify mydirectory/mysubdirectory/MyProg
    
    If you want TaskMan to handle the executable's connections to a database, the database must be identified to TaskMan through the TaskMan Configuration utility, and the executable must use the B~ substitution keywords to connect. Otherwise, it is up to the executable to handle all database connections.
  - For an IDO method, specify the method name (in the format IDO.Method - for example, MyProgID.SLSites.MyTestMethod) in the Executable Name field and select IDOMTH in the Executable Type field.
    For the task parameters, pass a comma-separated list of parameters that match the IDO method's parameters. You can either pass bare values (for example, "MyParameter1,MyParameter2") or use ~LIT~ syntax if white space is significant (for example, " MyParameter1,MyParameter2 ").
    
    When processing tasks of type IDOMTH, TaskMan requires a configuration with the same name as the site name. On the computer where TaskMan is running (typically the utility server), you must create a configuration where the configuration name matches the database site name, if one doesn't already exist.
4. Click the buttons on the form to specify any report options or excluded tasks.
5. Save the record.
Call your new background task as an event handler from the form.
You can see which tasks are currently running by opening the Active Background Tasks form.

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