Background Jobs

Some work in Al-Mohaseb takes too long to finish while you wait on a page: posting many transactions, importing a file, or building a large report. Al-Mohaseb runs that work as a background job. You can keep working, and the Jobs screen shows every job of your site, how far it has got, and whether anything went wrong.

Menu	Tools > Jobs
Permission	View background jobs (to see jobs and their progress). Manage background jobs (to also pause, resume, cancel and requeue jobs, and to run the diagnostic job).
Feature	Almohaseb Jobs. It is turned on automatically by the features that need it, such as Accounting.

Can't find it?

What you see depends on your role. If the menu, a button or a setting on this page is missing, ask your administrator to give you the permission listed above or to turn on the feature. Only administrators can turn features on and change site settings.

People who can see jobs see every job of the site, not only the jobs they started.

How a job works

A job does its work in small steps called batches, for example 200 rows of an import at a time. After each batch, the job saves its place, like a bookmark. This saved place is called a checkpoint. Because of this:

• A job that is paused, interrupted or restarted continues from its last saved place. It never starts over, and it never does the same batch twice.
• Canceling a job stops it, but it does not undo the batches it already finished.
• Long jobs take turns with other jobs. A long job switches between Running and Queued while it waits for its next turn. This is normal.
• If a problem looks temporary (for example the database was briefly unreachable), the job waits a little and tries again by itself.

What the statuses mean

Status	What it means	What you can do
Queued	The job is waiting for its turn. It may be new, between turns, or waiting to try again after a temporary problem. When Next run shows on the details page, the job waits until that time.	Pause or cancel it.
Running	The job is working now.	Pause or cancel it. It stops after the batch it is working on.
Paused	Someone paused the job. It keeps its place.	Resume or cancel it.
Completed	The job finished and every item was processed.	Nothing.
Completed with warnings	The job finished, but some items could not be processed or it raised warnings.	Open the job and review Items that could not be processed.
Failed	The job stopped because of an error that trying again would not fix by itself.	Read Last error, fix the cause, then requeue the job.
Needs attention	The job kept hitting a problem and has used all of its tries.	Read Last error, fix the cause, then requeue the job.
Canceled	Someone canceled the job before it finished.	Nothing. Start the work again from the screen that started it if you still need it.

When a job has failed tries and is Queued or Needs attention, the list shows a second badge with a circular arrow, such as 2 / 5: the number of failed tries so far, out of the number allowed.

Finished jobs (Completed, Completed with warnings, Failed and Canceled) are deleted automatically after a retention period, 30 days unless your site is set up differently. Jobs with the status Needs attention stay until someone deals with them.

View the jobs

1. Open Tools > Jobs. The newest jobs are at the top.
2. Each row shows the job's name and type, its status, its progress, and when it was queued.
   • The progress bar shows N of M items when the job knows how many items it has. Otherwise it shows N items processed so far.
   • If your site lets you choose the layout, the List and Grid buttons switch between a list and a table with the columns Job, Status, Progress, Queued and Actions.
3. Click the job's name, or Details, to open its details page.

Find a job

Type in the search box at the top of the list and press Enter, or click the magnifying glass. Some examples:

• status:needs-attention shows the jobs that need someone to look at them.
• status:active shows every job that has not finished (queued, running, paused or needs attention).
• queued:this-month shows jobs queued this month, in the site's time zone.
• import shows jobs whose type contains "import". Text without a term name searches the job type.
• sort:oldest lists the oldest jobs first. sort:priority lists the most urgent first.

You can also pick a status from the drop-down next to the search box (All statuses shows every status). Click the question-mark button next to the search box to open Available filters, which lists every term this list understands. See Searching and filtering lists for how terms, dates and the drop-down work together.

Read a job's details

The details page shows the status, the job type and, when the job knows how many items it has, a progress bar with the percentage done. While a job is Queued or Running, the page refreshes itself every few seconds.

Field	What it shows
Processed	The number of items done, and the total when it is known.
Queued	When the job was added, and who started it.
Started	When the job first started working.
Finished	When the job reached a final status.
Next run	For a queued job that is waiting: the earliest time it runs again.
Failed attempts	Failed tries so far, out of the number allowed before the job needs attention.
Slices	The number of turns the job has taken. A long job takes several turns so other jobs can run in between.
Warnings	The number of warnings the job raised. Shown only when there are some.

Last error appears in red when the job's most recent try failed. It says what went wrong.

Items that could not be processed appears when some items were skipped, for example rows of an import with a bad value. The table shows the Item (such as a row number) and the Problem. A job keeps only the first ones (100 unless your site is set up differently); when there are more, the page says The first N are shown. The total count is in the heading.

Pause and resume a job

1. Open the job's details page.
2. Click Pause. A queued job pauses at once. A running job pauses after the batch it is working on, so it can take a moment.
3. To continue, open the job and click Resume. The job continues from where it stopped.

Pause appears for Queued and Running jobs, and Resume for Paused jobs.

Cancel a job

1. Open the job's details page.
2. Click Cancel. The message says The job was canceled. A running job stops after its current batch.

Cancel appears for every job that has not finished. Canceling cannot be undone, and the batches the job already finished stay done.

Requeue a job that failed or needs attention

1. Open the job and read Last error.
2. Fix the cause, or ask the person who can. For example, correct the file or the setting the error names.
3. Click Requeue. The message says The job was queued again from its last checkpoint.

The job continues from its last saved place with a fresh set of tries; it does not repeat the work it already did. Requeue appears only for Failed and Needs attention jobs.

If the job changed while you were looking at it (for example it finished), you see The job cannot do that in its current state. Refresh the page to see where it is now.

Cancel or requeue several jobs at once

1. In Tools > Jobs, tick the check box of each job. Use the check box at the top of the list to select every job on the page.
2. Open the Actions menu that appears and choose Cancel or Requeue.
3. Confirm. The message says how many jobs were updated.

Jobs that cannot take the action are skipped. For example, Requeue only changes jobs that are Failed or Needs attention, and Cancel skips jobs that have already finished.

Check that background jobs work

The Run diagnostic job button on Tools > Jobs queues a job that does no real work: it counts through 1,000 items in small batches. Use it after a new installation or a server change, or when jobs seem stuck, to check that jobs start and run on your site.

1. Open Tools > Jobs and click Run diagnostic job.
2. The details page of the Diagnostic job opens. Watch it go from Queued to Running to Completed.

If the diagnostic job stays Queued for more than a few minutes while no other job is running, jobs are not starting on your site. Contact your administrator.

Tips and troubleshooting

• The Jobs menu or the buttons are missing. You need the View background jobs permission to see Tools > Jobs, and Manage background jobs for Pause, Resume, Cancel, Requeue, the Actions menu and Run diagnostic job. See Roles and permissions.
• A job switches between Running and Queued. It is taking turns with other jobs, which is normal for long jobs.
• A job failed with "No handler is registered for the job type". The feature that runs this kind of job is turned off. Ask your administrator to turn it on, then requeue the job.
• A job says "The job stopped responding and was queued again from its last checkpoint." The server restarted or the job was interrupted. The job continues by itself; nothing is lost.

New words on this page, such as batch and checkpoint, are explained in the Glossary.