Microsoft Dynamics NAV Sustained Engineering Team Blog : Job Queue

Job Queue in Microsoft Dynamics NAV 5.0

martinni — Wed, 19 Dec 2007 16:40:00 GMT

Introduction
With Microsoft Dynamics NAV 4.0 we had a job scheduling mechanism available in the Service Management module. The purpose for the job scheduler in Microsoft Dynamics NAV 4.0 is to give the possibility for scheduling tasks and their recurrence.

In Microsoft Dynamics NAV 5.0 the Job Queue was introduced. The Job Queue is primarily made for Outlook Integration, but has been extended to also include the previous job scheduling mechanism from Microsoft Dynamics NAV 4.0. The purpose of the Job Queue is to provide a mechanism for data processing on a server.

Job Queue Concept

The new Job Queue in Microsoft Dynamics NAV 5.0 is build over the following concept:

The Job Queues Entry table is where users or processes can enter a request for execution of a report or a codeunit. The Server (NAS) will look periodically into the Job Queue Entry table to see if there is a Job to execute.

The NAS will when it finds a Job Queue Entry, read it, delete it from the table (unless it is a recurring job) and then start running the requested job (report or codeunit).

When the report or codeunit finishes, the NAS will write a ‘response’ into the Job Queue Response table. In case the calling process has requested this (as is the case for the Outlook integration). The NAS will also insert a record into the Job Queue Log Entry table to record that it has processed a Job (this is not shown on the drawing).

Security

The Microsoft Dynamics NAV permission system determines whether a user has access to run the specified object or not. The permission system will also check if the user has access to the data accessed by the specified object.

Important Note: If permissions are copied from the demo data, users will have permissions to run all objects. Access for each user will in this case only be limited by permissions for data. The job queue will however use the NAS for executing the objects. The NAS is defined as a specific user with specific permissions in Microsoft Dynamics NAV. This means that the objects executed from the Job Queue will be executed with the permissions of the NAS-user. To prevent the situation where access to data and objects are not based on the user permissions and instead of being based on the NAS-user permissions we have introduced an extra requirement for objects to be run via the Job Queue; The user must have explicit permission to run the object that is requested to be run – even if the user has been given the usual default ‘all objects’. In other words, if the user needs to run report 1 via the job queue, the user must have explicit rights to run report 1.

When to Use

If a codeunit have done some processing and generated a result it must be possible to pass the result back to the user or process. This is where it is beneficial to provide a Job Queue Entry record as a parameter to the codeunit being called.

The Job Queue Entry record has a number of fields whose only purpose is to carry parameters into and out of the codeunit. These fields are copied to the Job Queue Response record. This also means that codeunits that are to be run via the job queue must be specified with the Job Queue Entry record as parameter in the OnRun trigger. Actually this provides one extra level of security, as this prevents users from running random codeunits via the Job Queue. If the user needs to pass on parameters to a report, the only way to do so is by wrapping the report execution into a codeunit which then parses the input parameters and enters them into the reports before executing it.

Follow this link for how to setup

Follow this link for usage example

Martin Nielander
Program Manager

This posting is provided "AS IS" with no warranties and confer no rights. You assume all risk for your use.

How to Set Up Job Queue in Microsoft Dynamics NAV 5.0

martinni — Wed, 19 Dec 2007 15:30:00 GMT

The Job Queue is handling the order of batch jobs and code units that are setup to run at a given time. The application server reads from the job queue and determines what job to run next. Several parameters can be set up to determine this.

Prerequisites

Before you can setup and execute a job queue you will need to:

1. Install Microsoft Dynamics NAV 5.0

2. Install Microsoft Dynamics NAV Application Server

a. Make sure that the NAV Application Server service is a user registered in NAV and on the SQL Server, if SQL Server is the database server for NAV

b. Startup parameters for the application server: <jobqueue>

3. Create your job queue entries (See Job Queue usage example here)

4. Activate the job queue

Create a Job Queue Entry

The Job Queue Entry Card window in figure x-1 shows the actual job. It can either be a single instance or a re-occurring job. Therefore there are two tabs in this window: General and Recurrence.

Via the Job Queue Entry Card it is possible to setup a limitation for attempts to start a specific job. If a limitation is needed a value should be entered in the Maximum No. of Attempts field. The field No. of Attempts to Run will list how many times the current job has been attempted to run. Also the time intervals as to when the job should try to start are setup here in the Earliest Start Date/Time field.

Figure x-1: Job Queue Entry Card

The different Status codes are:

· Ready

· On hold

· In process

· Error

If the job is performed successfully it will be removed from the list in the Job Queue Entries Card window unless it is a recurring job.

The Recurrence tab on the Job Queue Entry Card is used to setup recurrence of each Job Queue Entry.

The Job Queue Entry administrator should, as a good practice; set the Job Queue to On Hold before changing the different settings in the Job Queue Entry Card. Once the Job Queue Entry administrator is done with the setup of a Job Queue Entry the Reset Status will activate the job.

Figure x-2: Job Queue Entry Card – Reset status

On the recurrence tab, the jobs can be set to be scheduled only on specific week days.

The Job Queue Entries List will list all current job queues; the window is displayed in figure x-3. Go to the Administration menu - Application Setup - Job Queue and then click Job Queue Entries and press F5 to get the Job Queue Entry List.

Figure x-3: Job Queue Entry List

The Job Queue Entry List displays the Status of the job, the User ID of the user that initiated the job in addition to the Object ID in question. If the status is ready then the application server can run the scheduled job. The application server will run the listed jobs based on entries in fields: Earliest Start Date/Time and Priority. While the job is running, it will be listed in the Job Queue Processes window figure x-4.

Figure x-4: Job Queue Processes window

The Job Queue Log Entries displays a list of jobs which already have been running.

Figure x-5: Job Queue Log Entries

The Job Queue Log Entries will also display any error messages for Job Queue Entries that went wrong. Each line represents a Job Queue Entry. If the job ended with errors during the expedition of the Job Queue Entries the error message will be listed as the last column in the Job Queue Log Entries. The error message limitation is 1000 characters.

Activate the Job Queue

The Job Queue function is activated or deactivated in the Job Queue Setup window. Select the field Job Queue Active to make the job queue active.

Figure x-6: The Job Queue Setup

You should now be able to set up the Job Queue for CodeUnits and Reports in Microsoft Dynamics NAV 5.0.

I would like to add a special thanks to Rikke Lassen and Bardur Knudsen for making this blog a reality.

Martin Nielander
Program Manager

This posting is provided "AS IS" with no warranties and confer no rights. You assume all risk for your use.

Job Queue Example in Microsoft Dynamics NAV 5.0

martinni — Tue, 18 Dec 2007 19:17:00 GMT

What if all posting routines in Microsoft Dynamics NAV could be scheduled to a more sufficient time of the day?

The example in this blog shows how the job queue functionality can be used to allow background posting of sales orders.

In this example the sales order will contain creation of a new field that indicates if the sales order has been scheduled for posting or not. A filter is also introduced, so that the user doesn’t see Sales Orders that are scheduled for posting. We will also create a Job Queue entry for every sales order and thereby handle every sales order independently. Another possibility could be to add functionality that could handle all scheduled sales orders at one go.

The example also includes some error handling – meaning that if the job queue for some reason can’t post the Sales order, the status is changed to failed, and the Sales Order will reappear on the list of Sales orders the user will have to handle.

Changed Objects

To provide an overview, the modified (and the new) objects are listed here:

Add a Status Field to the Sales Header

Note that we introduce space for an error message (in case of Posting Error). The error text could be made available as a ‘lookup’ value in the status field.

Modify the Filter in the Sales Order Form

We need to make the sales orders that are scheduled for posting in the job queue disappear from the view in form 42. Note also, that we have made the Job Queue Status field visible on the form.

Modify the Post (F11) Function Call

When the user presses Post or F11, codeunit 81 is called directly with the Sales Header record as parameter. So let’s modify codeunit 81:

Note that when inserting the JobQueueEntry, it’s primarily the User ID field that is filled other fields are filled with default values. Note also that we specify the job queue to run a codeunit “Sales Order Post via Job Queue”, which is new and created for this example. The sales order to be posted is specified using the GETPOSITION function and entered into the Parameter String field of the Job Queue Entry. The Job Queue Entry record has several parameter fields that can be used in various situations.

Codeunit “Sales Order Post via Job Queue”

Note that a codeunit that is being run by the job queue has to have the Job Queue Entry record as parameter. And as described in the last section, you also need to explicitly give the users permission to run codeunit 9000 – unless they are specified as ‘SUPER’.

GUI Not Allowed on NAS

Some codeunits display some kind of progress indicators using the dialog. When executing code on a NAS, no GUI operations are allowed. Hence, all updates of the progress dialog window in codeunit 80 needs to be wrapped with a IF GUIALLOWED THEN...

Security and Permissions

The default security setup in NAV relies entirely on restrictions on data access. By default all users have access to all forms, codeunits, reports etc. except the data, they process or show. Since the Job Queue mechanism has no way of sensing what data will be affected by running e.g. codeunit 9000 (that then runs codeunit 80 that runs codeunit 12 …) we have chosen to require specific execution permission to codeunits and report that are going to be run by the job queue.

And that’s it. Now go on and post the sales order and see what happens.

I would like to add a special thanks to Rikke Lassen and Bardur Knudsen for making this blog a reality.

Martin Nielander
Program Manager

This posting is provided "AS IS" with no warranties and confer no rights. You assume all risk for your use.