Na2009 enus sm_11

Chapter 11: Job Queue

Page 503

CHAPTER 11: JOB QUEUE

Objectives

The objectives are:

Activate job queue.

Set up a job queue.

Use the job queue.

Check errors.

Introduction

In Microsoft Dynamics® NAV, you can schedule certain tasks to run at specified

intervals. This is implemented through the job queue functionality.

When you add a recurring task (that is, a job) to the job queue, the program

executes a predefined codeunit or report according to the specified schedule.

You can set jobs to run once, or on a recurring basis. For example, you might

want to run the Salesperson - Sales Statistics report weekly, to track sales by

salesperson each week, or you might want to run the Process Service E-mail

Queue codeunit daily, to make sure pending e-mails to customers regarding their

service orders are sent out in a timely fashion.


Page 504

Activating the Job Queue

Before using the job queue, you must activate it in the program. Use the Job

Queue Setup window to activate and deactivate the job queue.

1. Go to Departments > Administration > Application Setup > Job

Queue.

2. Under Tasks, click Job Queue Setup. The Job Queue Setup

window opens.

FIGURE 11.1 THE JOB QUEUE SETUP WINDOW

3. Select the Job Queue Active check box and click OK to close the

window.

A check mark in this field ensures that the job queue is active and

jobs will be processed. If the field is cleared, it means that the job

queue is inactive, and no jobs will be processed.


Page 505

Setting Up a Job Queue

The Job Queue Entry Card Window

You may need to insert new or verify the predefined jobs in the job queue. Use

the Job Queue Entry Card window for this purpose.


Queue.

2. Under Lists, click Job Queue Entries.

3. In the Job Queue Entries list place, select the line with the relevant

object to run and double-click it to open the Job Queue Entry Card

window.

FIGURE 11.2 THE JOB QUEUE ENTRY CARD WINDOW

The General FastTab

The Object Type to Run field contains the type of object that is to be run for

this job. Click the AssistButton in the field to view two possible options: Report

and Codeunit. This type has to match the type of the object identified in the

Object ID to Run field.

The Object ID to Run field contains the ID of the object that is to be run for this

job. Click the AssistButton to open the Objects window to select the needed ID.

The program automatically fills in the Object Name to Run field with the name

of the object selected in the Object ID to Run field.

mk:@MSITStore:C:/Program%20Files/Microsoft%20Dynamics%20NAV/60/RoleTailored%20Client/en-US/master.chm::/sm_a.chm::/T_472_8.htm



Page 506

FIGURE 11.3 THE OBJECTS WINDOW

The Parameter String field contains a text string that is used as a parameter by

the job when it is run.

The User ID field contains the user ID of the user that has inserted the job in the

queue and is usually filled in by the program.

The Maximum No. of Attempts to Run field is used to set up how many times

the program tries to run a task.

This is useful for situations where a task can be unresponsive at times (for

example, because it depends on some external resource that is not always

available).

The No. of Attempts to Run field cannot be edited and contains the number of

attempts that have actually been made to run a task. This number is automatically

incremented for each attempt to run the task.

NOTE: If the number of the No. of Attempts to Run field exceeds the number

specified in the Maximum No. of Attempts to Run field, an error message is

generated.

The Last Modified Date/Time field contains the date and time when the job is

created. The program inserts the value automatically.

The Expiration Date/Time field contains the date and time when the job

expires, that is, a date and time after which the job is not to be run.

The Earliest Start Date/Time field contains the earliest date and time when the

job can be run.


Page 507

The Priority field is used to assign a priority to the job. The value can be used to

provide some “load balancing” when the Minimum Job Queue Priority and

Maximum Job Queue Priority fields in the Job Queue Process window are set

up in a certain way.

The Status field contains the status of the task. This field is updated

automatically. It has the following values:

Ready (the job is ready to be run).

In Process (the job is running).

On Hold (the default value when a job is inserted).

Error (the program detected an error when running the job).

However, you can change the status manually by using the following two

functions:

Reset Status (sets the status to Ready).

Set On Hold (sets the status to On Hold).

The Recurrence FastTab

The Recurring Job field determines if the job is recurring. If the field is

selected, the job is recurring.

The following fields determine whether the job is run on certain days:

Run on Mondays

Run on Tuesdays

Run on Wednesdays

Run on Thursdays

Run on Fridays

Run on Saturdays

Run on Sundays

The Starting Time and Ending Time fields determine the earliest and latest time

of the day the job is to be run.

The No. of Minutes between Runs field determines how many minutes there

must be (at a minimum) between runs of a task. This is only relevant if the

Recurring Job check box is selected.



mk:@MSITStore:C:/Program%20Files/Microsoft%20Dynamics%20NAV/60/RoleTailored%20Client/en-US/master.chm::/sm_a.chm::/T_471.htm



Page 508

Using the Job Queue

In the Service application area, there are two predefined jobs that you can let the

job queue run automatically at specific intervals:

Codeunit 5917 Process Service E-Mail Queue

Codeunit 5918 ServOrder-Check Response Time

Checking the Response Time on Service Orders

You can set up a job that checks the response time for service items if those items

belong to service orders with status Pending and if their repair status is set to

Initial.

The job automatically creates e-mail warning messages that servicing of the item

starts soon and puts these warnings in the service e-mail queue to send to a

responsibility center or to any other e-mail address specified in the Service Mgt.

Setup window. In the Service Mgt. Setup window, set the amount of time in

hours to wait for a response before sending the next warning message. On the

General FastTab of the Service Mgt. Setup window, fill in at least the First

Warning Within (Hours) and Send First Warning To fields for the job to run

properly.

The program calculates the response date and time of a service order line using

the following formula:

Order Date\Order Time + Response Time (Hours) within the

working time periods that are:

• service hours for a contract if a certain item line is

serviced against the contract

• default service hours.

Also, the program considers holidays set up for base

service calendar.


Queue.


3. In the Job Queue Entries list place, select the second line and

double-click it to open the Job Queue Entry Card window for

Codeunit 5918.

4. On the General FastTab:

In the Earliest Start Date/Time field, type “t” to enter the current

date and specify the exact time for the job queue to be run.

On the Recurrence FastTab:

In the Starting Time and Ending Time fields, specify the period of

the day the job is to be run, for example “10:00 AM” and “10:00

PM” respectively.


Page 509

In the No. of Minutes between Runs field, type “1”.

The Job Queue Entry Card window looks like this.

FIGURE 11.4 THE JOB QUEUE ENTRY CARD FOR THE SERVORDER-CHECK RESPONSE TIME CODEUNIT

5. Click OK.

6. Go to Departments > Service > Administration.

7. Under Setup, click Service Setup. The Service Mgt. Setup window

opens.

8. On the General FastTab, change the values in the following fields:

First Warning Within (Hours): “16”

Second Warning Within (Hours): “0”

Third Warning Within (Hours): “0”

Click OK to apply changes.

Once the preliminary steps are done, you can use the job queue entry. As a result

of running the ServOrder-Check Response Time codeunit, the appropriate

entries are created in the E-Mail Queue.

To enable the proper functioning of the job queue, install the Application Server

for Microsoft Dynamics NAV.

For more information on installing the Application Server, refer to the

Installation & System Management: Application Server for Microsoft Dynamics

NAV guide.

1. Set the work date to the current date by typing “t” in the Set Work

Date window.

2. Click Home > Service Orders.


Page 510

3. Create a new service order:

On the General FastTab:

Customer No.: 40000

Notify Customer: By E-Mail

On the Details FastTab, fill in the Order Date field with the current

date.

4. On the Lines FastTab:

Service Item No.: 16

Change the value in the Response Time (Hour) field to “1”.

According to the service management setup, this triggers the first

warning.

5. Click OK to close the Service Order window.

6. Start Microsoft Dynamics NAV – Classic Application Server with

the JOBQUEUE parameter.

The job queue can also be executed from the Microsoft Dynamics NAV client by

running Codeunit 448 Job Queue Dispatcher. In this case, the job queue is run

until the Microsoft Dynamics NAV client is closed.


Queue.

8. Under Lists, right-click Job Queue Log Entries and then Open In

New Window. The Job Queue Log Entries window appears

containing lines for the success running of Codeunit 5918.

Note that the job queue log entries are created every minute

according to the job setup.

FIGURE 11.5 VERIFYING THE CREATION OF THE JOB QUEUE LOG ENTRIES

To view the e-mail queue entries created while executing the ServOrder-Check

Response Time job:

9. Go to Departments > Service > Order Processing.

10. Under Periodic Activities, right-click View E-Mail Queue and then

click Open In New Window. The Service E-Mail Queue window

opens showing one warning message.


Page 511

FIGURE 11.6 VERIFYING THE CREATION OF THE E-MAIL QUEUE ENTRIES

The entries that the program created after executing the Checking the Response

Time on Service Orders job can be sent manually from the Service E-Mail

Queue window or automatically using the Sending E-Mails to Customers job.

Sending E-Mails to Customers

You set up a job that automatically sends e-mail messages stored in the e-mail

queue. These messages typically notify customers that their service orders are

completed, or alert the responsible individuals that the response time for the

service orders is approaching.


Queue.


3. In the Job Queue Entries list place, select the first line and double-

click it to open the Job Queue Entry Card window for Codeunit

5917.

4. On the General FastTab, in the Earliest Start Date/Time field, type

“t” to enter the current date and specify the exact time for the job

queue to be run.

5. On the Recurrence FastTab:

a. In the Starting Time and Ending Time fields, specify

the period of the day the job is to be run, for example

“10:00 AM” and “10:00 PM” respectively.

b. In the No. of Minutes between Runs field, type “1”.

The Job Queue Entry Card window looks like this.


Page 512

FIGURE 11.7 THE JOB QUEUE ENTRY CARD FOR THE PROCESS SERVICE E-MAIL QUEUE CODEUNIT

6. Click OK.

7. Under Lists, right-click Job Queue Log Entries and then Open In

New Window. The Job Queue Log Entries window appears

containing lines for the success running of Codeunit 5917.

Note that the job queue log entries are created every minute

according to the job setup.

FIGURE 11.8 VERIFYING THE CREATION OF JOB QUEUE LOG ENTRIES WITH STATUS SUCCESS

To view the e-mail queue entries processed while executing the Process Service

E-Mail Queue job:

1. Go to Departments > Service > Order Processing.

2. Under Periodic Activities, right-click View E-Mail Queue and then

click Open In New Window. The Service E-Mail Queue window

opens showing one warning message.


Page 513

FIGURE 11.9 VERIFYING THE CREATION OF SERVICE E-MAIL QUEUE WITH STATUS PROCESSED

Note that the successfully sent entries have status Processed.


Page 514

Excluding a Specific Job While the Job Queue Is Running

To exclude a specific job from the job queue that is running, do the following:


Queue.


3. Browse to the job that needs to be stopped and double-click to open

it.

4. In the Action Pane of the Job Queue Entry Card window, click

Related Information > Job Queue > Set On Hold.

The program changes the value in the Status field from Ready to On

Hold.

Stopping the Job Queue

The job queue stops running all scheduled jobs as soon as the Job Queue Active

check box is cleared in the Job Queue Setup window.

Note that there is no mechanism to restart the same instance of the job queue

after it stops as a result of power failure or any other externally caused event.

Overview of the Job Queue Processes

To get an overview of all job queue processes, do the following:


Queue.

2. Under Lists, right-click Job Queue Processes and then click Open

In New Window. The Job Queue Processes window opens.

FIGURE 11.10 THE JOB QUEUE PROCESSES WINDOW

The Last Job Processed On field shows when a job queue last processed a job.

This information can be used to estimate whether a job queue is still running, or

whether it has stopped and further troubleshooting is required. This field is

updated every 10 seconds, or between jobs automatically.

From this window, you can activate or deactivate the currently selected job queue

process by clicking Actions > Functions > Activate Job Queue



Page 515

Session/Deactivate Job Queue Session. A check mark in the Active field

reflects the current status of the job queue process.

Also, you can set priorities of the currently selected job queue process by

clicking Actions > Functions > Set Priorities.

FIGURE 11.11 THE JOB QUEUE PROCESS PRIORITY WINDOW

If the values in the Minimum Job Queue Priority and Maximum Job Queue

Priority fields of the Job Queue Processes window are the same, the process

will handle only jobs with this exact priority. In this way, it is possible for you to

fine-tune what jobs are run.




Page 516

Checking Errors

If the job queue detects an error while running a job, you can view the error

message the program logs in the Job Queue Log Entries window.

For example, an error can be generated in case you forget to specify the value in

the Object ID to Run field when setting a job.

FIGURE 11.12 THE JOB QUEUE LOG ENTRIES WINDOW WITH ONE LINE FOR ERROR MESSAGE


Page 517

Lab 11.1 –Setting Up the ServOrder-Check Response Time and Process Service E-Mail Queue Jobs

In this lab, you will practice setting up the ServOrder-Check Response Time and

Process Service E-Mail Queue jobs.

Scenario

You work in the Service Department of CRONUS International Ltd, and your

task is to set up service warnings to check whether the program creates warning

messages for all three service order response time warnings. Also, you need to

verify whether the e-mail messages are sent for all entries placed into the E-Mail

Queue in the Service Management application area.

Challenge Yourself

Perform the necessary setup in the Job Queue Entry Card window for

Codeunits 5917 and 5918.

Need a Little Help?

1. Set up 24, 12 and 6 hours as the first, second and third warning

interval correspondingly.

2. Set up the recurring jobs for Codeunits 5918 and 5917 with five and

two minute periods respectively.

3. Create a service order and add a service item to the service order

line.

4. Start the job queue.

5. Verify that three warnings are created in the Service E-Mail Queue

window (for the first, second and third response warning periods).

6. Check that all three warning messages are successfully sent. Check

the time of sending, and e-mail address. Check that no errors are

created in the Job Queue Log Entries window.

7. Finish the order and check that the appropriate message is sent to the

customer.

Step by Step

Perform the preliminary setup of warning intervals.

1. Check that your current system date\time is set to April, 24, 2009,

3:00 PM.

2. In the Set Work Date window, type “t” to set the work date to

current date.

3. Go to Departments > Service > Administration.

4. Under Setup, click Service Setup.

5. On the General FastTab of the Service Mgt. Setup window that

opens, change the values in the following fields:


Page 518

Field Value

First Warning Within (Hours) 24

Second Warning Within (Hours) 12

Third Warning Within (Hours) 6

6. Click OK.

Set up the recurring jobs.


Queue.


3. In the Job Queue Entries list place, select the second line and

double-click it to open the Job Queue Entry Card window for

Codeunit 5918.


In the Earliest Start Date/Time field, type “t” to enter the current

date.

5. On the Recurrence FastTab:

In the No. of Minutes between Runs field, type ”3”.

6. Click OK.

7. Repeat steps 3 to 6 to setup the job for Codeunit 5917. But type “2”

in the No. of Minutes between Runs field.

Create a service order.

1. Click Home > Service Orders.

2. In the Action Pane, click New to create a new service order.


Customer No.: 10000

Notify Customer: By E-Mail

4. On the Lines FastTab:

Service Item No.: 4

5. Change the value in the Response Time (Hours) field to “30”.

Note that the program updates the response date and time.

Verify that the updated response date and time are not earlier than

the current system date time plus the period of the first warning

(considering the formula for response date and time calculation).

Start the job queue.

1. In the Job Queue Entry Card window for Codeunit 5918, click

Related Information > Job Queue > Reset Status, and click OK.

2. Repeat step 1 to start the job for Codeunit 5917.

3. To speed up the process, change the date and time properties on your

computer to 4\27\2009, 4:00 PM.


Page 519

4. Wait up to three minutes and verify that the line for the first warning

is created in the Job Queue Log Entries and Service E-Mail Queue

windows. Check that the warning message is successfully sent to the

customer.

5. Change the date and time properties on your computer to 4\28\2009

and verify that the second warning is successfully sent.

6. Change the date and time properties on your computer to 4\29\2009

and verify that the third warning is successfully sent.

7. Change the service order status to Finished and accept the message

that follows.

On completing this task, the Job Queue Log Entries and Service E-Mail Queue

windows looks like this.

FIGURE 11.13 THE JOB QUEUE LOG ENTRIES CREATED FOR THE THREE WARNING MESSAGES

FIGURE 11.14 THE PROCESSED SERVICE E-MAIL QUEUE


Page 520

Summary

The Job Queue functionality within Microsoft Dynamics NAV allows running

scheduled jobs automatically at specified intervals. With this functionality it is

easy to start and stop the job queue whenever needed.

The chapter gives a detailed description of the Job Queue Entry Card window

where a job can be created and set up for the job queue.

Also, the chapter explains how to use the job queue by the example of checking

the response time on service orders and sending e-mails to customers and how to

check errors when the job queue detects these.


Page 521

Test Your Knowledge

1. Which field in the Job Queue Entry Card window indicates that the job is

periodical?

( ) Starting Time

( ) Ending Time

( ) Recurring Job

( ) Priority

2. True or False:

The value in the Status field in the Job Queue Entry Card window is

updated automatically, and it cannot be changed manually.

3. Complete the following sentence:

A job can be set up that checks the response time for service items if those

items belong to service orders with status ______________ and if their repair

status is set to____________.

4. What must be done if there is a need to stop a specific job while the job

queue is running?


Page 522

5. What must be set up to have the program automatically send warnings on the

response time for service orders?


Page 523

Quick Interaction: Lessons Learned

Take a moment to write down three Key Points you have learned from this

chapter:

1.

2.

3.


Page 524

Solutions

Test Your Knowledge

1. The value of which field indicates that the job is periodical?

( ) Starting Time

( ) Ending Time

(√) Recurring Job

( ) Priority

2. True or False:

The value in the Status field in the Job Queue Entry Card window is

updated automatically, and it cannot be changed manually.

MODEL ANSWER:

False: The value in the Status field in the Job Queue Entry Card window is

updated automatically; however, it can be changed manually by using the Reset

Status and Set On Hold functions.

3. Complete the following sentence:

A job can be set up that checks the response time for service items if those

items belong to service orders with status ______________ and if their repair

status is set to____________.

MODEL ANSWER:

A job can be set up that checks the response time for service items if those items

belong to service orders with status Pending and if their repair status is set to

Initial.

4. What must be done if there is a need to stop a specific job while the job

queue is running?

MODEL ANSWER:

To stop a specific job while the job queue is running, change the status of the job

from Ready to On Hold by using the Set On Hold function.

5. What must be set up to have the program automatically send warnings on the

response time for service orders?

MODEL ANSWER:

A job must be set up to check the response time on service orders and a job must

be set up to send e-mails to have the program automatically send warnings on the

response time for service orders.

Technology

Na2009 enus sm_11