Version 2.4 is a legacy release, and these documents are no longer being maintained.

Manage jobs

AtoM relies on Gearman in order to execute certain long-running tasks asynchronously to guarantee that web requests are handled promptly and work loads can be distributed across multiple machines. This ensures time and/or resource-intensive tasks do not timeout when running via the web browser.

Important

You must have the necessary dependencies installed and configured to be able manage asynchronous jobs in AtoM. See: Asynchronous jobs and worker management.

Prior to AtoM 2.2, only the ingest of Archivematica DIPs was processed asynchronously. See Upload DIP for more details.

As of AtoM 2.2, the ability to generate a PDF or RTF finding aid from archival descriptions, and the ability to manage PREMIS rights inheritance, are now also handled as asynchronous jobs in AtoM. Later versions of AtoM have increasingly used the job scheduler to handle long-running operations, including publication status updates, imports and exports, move operations, print reports, and more.

Users can see the status of job requests by navigating to edit Manage > Jobs.

An image of the Manage menu

Using the Jobs page

When first arriving on the page, users will see a table showing the status of any ongoing jobs, as well as any previous jobs that have not been cleared by another user. See below for more information on permissions and the Manage jobs page.

An image of the Jobs page

Start date: When the job was first requested.

End date: When the job completed. A status of “N/A” implies that the job is still executing.

Job name: Internal name of the job executed; indicates the type of job being performed. Examples include:

Job status: Jobs can have 1 of 3 statuses:

  • Running - The job is currently being executed. Refresh the page for an updated status.
  • Completed - The job completed successfully.
  • Error - The job failed to complete as requested. If there is any further information, it will be included in the “Info” column of the Jobs table.

If the job is related to a specific record, then the Job status column will also include a blue arrow icon - this acts as a hyperlink to the related record.

Info: Provides any available additional information about the status of a job. The Info column also includes a link to the full report from the console of the job, also known as the Job details page. For more information, see below: The Job details page.

User: The username of the AtoM user who initiated the job.

An image of the Jobs page tab

The Jobs page also includes a tab that allows users to view only those jobs that are currently still being executed (e.g., a status of “Running”). This can be useful when a large number of jobs are being executed simultaneously, and/or the list of jobs has not been cleared in some time. Click on the blue hyperlink to switch the view from “All jobs” to “Active jobs”. AtoM will refresh the page and the table will be limited to the selected view.

Jobs page button block options

An image of the Jobs page button block

Refresh and Auto refresh

The jobs page will not automatically update when there is a change in a job’s status - to see an updated status, such as whether or not a running job has completed successfully or failed, the user must refresh the page. This can be done either by manually refreshing the browser, or using the “Refresh” button in the button block at the bottom of the jobs page.

An image of the Jobs page auto-refresh option when engaged

In cases where a lot of jobs are running or a constant and automated status update is desirable, users can click the Auto refresh button. Doing so will cause the browser to automatically refresh every 5 seconds, until the auto-refresh option is disengaged. When engaged, the Auto refresh button will show a checkmark inside the circle on the button.

Export history CSV

In case users would like to clear completed jobs but keep a record outside of AtoM of previous jobs performed, a CSV export of the Jobs table is available. Like the display table in the user interface, the output contains columns for startDate, endDate, jobName, jobStatus, jobInfo, and jobUser.

An example image of the Jobs page CSV export

Clear inactive jobs

Clicking this button will remove any inactive jobs regardless of status (i.e. completed or failed jobs) created by you from the Jobs page. Any jobs still processing, or jobs created by another user, will not be affected.

Note

You can only clear jobs that you have initiated.

If all inactive jobs have been cleared and there are no current jobs running, AtoM will indicate this in the jobs page with a message.

An example image of the Jobs page when there are no jobs

See also

The Administrator’s manual has an installation page for setting up Gearman and asynchronous job support in AtoM. The page also includes some examples of how to manage workers and jobs from the command-line - see: Gearman Job Worker.

The Job details page

When a job is executed, the task is run by one of the AtoM workers managed by the Job scheduler, and all job details are captured by the console and recorded to the AtoM worker log. The Job details page provides users with this output via the user interface. This can be useful in many cases - for example, troubleshooting a job that has failed. Additionally, some import options allow users to skip matched records and report them in the Job details instead - an administrator can then review the output found on the Job details page against the original import to determine what records where skipped during import. For more information on imports, see: Import/export.

An example image of the Job details page

Jobs and user permissions

Access to the Jobs page functionality is dependent on your user role. See User roles, Manage user accounts and user groups, and Edit permissions for more information on managing user roles in AtoM.

All authenticated (e.g. logged in) users can access the Jobs page. However, most users will only see jobs and be able to clear jobs which they have started. Only an administrator can see the status of all jobs - however, like all users, administrators can only clear jobs that belong to them.

Back to top