comet.jobs¶

Creation and execution of a queue of jobs.

Documentation¶

Creation and execution of a queue of jobs.

If you want to process many documents in one action, you will be familiar with the problem: InDesign® only closes documents at the very end of the entire action at the so-called idle time.

Until then, the documents remain in memory and you only need to have opened enough documents or large enough documents to cause InDesign® to crash due to memory overflow.

The queue solves this problem by only starting the individual jobs of the overall action at idle time. Once the individual job is finished, the queue waits until InDesign® has also closed the document for the job in the background.

Only then will the next job be processed, again at idle time.

All you have to do is inform the queue of the document being processed (so that the queue knows whether it has to wait at all and for what).

To do this, enter the following instruction in the job script after opening the document:

comet.jobs.registerDocument(comet.document.getFront())

The following table describes the behavior of the queue in the different situations:

Queue behavior¶
Document	With registration	Without registration
Open and close	Processing waits until the document is also closed in the background. Only then is the next job processed.	The next job is started immediately after the end of the current job and the document remains open in the background until the next idle time. In short, you might as well not use the job queue at all.
Open only	Processing only continues once the document has been closed. This option is particularly useful for manual editing of publication documents: The queue loads and opens the next document. The document can then be edited manually. On saving and checking in the document the next document to be processed is loaded and opened immediately.	The next job is started immediately after the end of the current job. Preferably use this option to open a list of documents or to checkout and open them.
No document opened	It is of course possible that a job does not open a specific document at all, but processes the current document (or none at all). In this case, the job IDs could contain ‘any’ information, e.g. the URL of a file to download. In this case, the next job is started immediately after the end of the current job.

Once all jobs have been processed, processing of the queue is automatically deactivated and must be reactivated with start() to process further jobs.

Queue script¶

Jobs are added to the queue using the add() function.

The call defines the script (the action) that is to be executed for the job. For this script to ‘know’ what it should do, the call also defines a so-called job ID, which can be evaluated by the script as a global variable.

As a rule, the job ID contains either the (complete) path of an InDesign® document or the document ID of a publication document. However, you can also enter any other description here - the only decisive factor is how the executing script evaluates this description.

The job ID does not have to be unique in the queue.

The job ID is provided to the executing script as the global variable gJobsQueueID. The following table describes some typical job IDs:

Job IDs¶
Job ID	Example
Document path	Open, edit and save the document $DESKTOP/aaa.indd in a job queue:¶ doc = comet.document.open(comet.gJobsQueueID) #gJobsQueueID contains the path comet.jobs.registerDocument() #Our document is the front document here ... if doc.canSave(): doc.save() doc.close()
Document ID	Open, edit and save the document with the ID 268516810 in a job queue:¶ comet.publication.checkoutByID(comet.gJobsQueueID) #gJobsQueueID contains the publication ID comet.jobs.registerDocument() #Our document is the front document here ... comet.publication.checkinByID(comet.gJobsQueueID)
URL	Download the file of the URL http://www.hi13.de/aaa.png to my desktop:¶ comet.file.download(comet.gJobsQueueID, '$DESKTOP/abc.png') #gJobsQueueID contains the URL
Any	Split a string delimited by ‘+++’ and log the values¶ values = comet.gJobsQueueID.split('+++') #gJobsQueueID contains a '+++'-delimited string comet.wlog(values)

Methods¶

comet.jobs.add(jobsQueueID, action)¶

Add a job to the queue. Processing of the jobs is started with start().

Parameters:

jobsQueueID (str) –
Description of the job.

The value is passed to the executing script in the global variable gJobsQueueId and usually contains the ID or path of a document that is to be processed.

However, you can also use any other identifier, which you then evaluate accordingly in the job script (the action).
action (int | str) –
The action to execute for the job.

The parameter type can be:
- int
  ID of a defined action of the data connection to execute for the job.
- str
  Complete filepath to the script to execute for the job.

Return type:

None

Raises:

TypeError – When parameter types are invalid
ValueError –
- When parameter action is int and is < 1
- When parameter action is str and is empty
CometError – On internal error

Available:

InDesign®

CScript:

jobs::add

Examples:

Create a job for each of five existing documents. A new document is then to be created in a further job. At the end of the script, the queue processing of the jobs is started.

#!py
#pragma plain

import comet

def main():
    actionPath = '$DESKTOP/bbb.cpp'
    comet.jobs.add('$DESKTOP/aaa.indd', actionPath)
    comet.jobs.add('$DESKTOP/bbb.indd', actionPath)
    comet.jobs.add('$DESKTOP/ccc.indd', actionPath)
    comet.jobs.add('$DESKTOP/ddd.indd', actionPath)
    comet.jobs.add('create', actionPath)

    jobs = comet.jobs.getQueue()

    comet.wlog(f'Jobs in queue: {len(jobs)}')

    comet.jobs.start()

    return 0

Simple script for a queue job. It is important to open and close the target document and to register the document in the queue using the variable gOpenedDoc.

#!py
#pragma plain

import comet

def main():
    openDocs: list[comet.CDocument] = comet.document.getOpen()
    comet.wlog(f'# Working on "{comet.gJobsQueueId}", {len(openDocs)} docs are already open')

    if comet.gJobsQueueId == 'create':
        comet.document.create()
    else:
        comet.document.open(comet.gJobsQueueId)

    doc = comet.document.getFront()

    comet.setOutput('gOpenedDoc', doc)

    #Create a text frame
    frame = comet.frame.createTextFrame((0.0, 0.0, 100.0, 100.0))

    frame.setFillColor((0, 153, 204))
    frame.setRotation(-20.0)

    if doc.canSave():
        doc.save()

    doc.close()

    comet.wlog(f'# Work on "{comet.gJobsQueueId}" done.')

    return 0

comet.jobs.start()¶

Starts the processing of the jobs in the queue.

Once all jobs have been completed, processing of the queue is automatically deactivated and must be reactivated with start(). to process further jobs.

Return type:: None
Raises:: CometError – On internal error
Available:: InDesign®
CScript:: jobs::start

comet.jobs.isActive()¶

Is queue processing activated?

Returns:: Whether the job queue is running.
Return type:: bool
Available:: InDesign®
CScript:: jobs::active

comet.jobs.stop(clear=False)¶

Stop processing the jobs in the queue.

Parameters:: clear (bool) – Should all jobs that are still in the queue also be removed?
Return type:: None
Raises:: CometError – On internal error
Available:: InDesign®
CScript:: jobs::stop

comet.jobs.clear(stop=False)¶

Remove all pending and unstarted jobs from the queue.

Parameters:: stop (bool) – Should the processing of the queue also be deactivated?
Return type:: None
Raises:: CometError – On internal error
Available:: InDesign®
CScript:: jobs::clear

comet.jobs.getQueue()¶

Get data for all jobs still in the queue.

Returns:

A list of entries in the queue.

The entries are tuples containing:

int: Action ID
str: Path of the action
int: Job state
- -1: Not started
- >= 0: Being processed. How many documents were opened at the start?
str: Job identifier.

Return type:

list[tuple[int, str, int, str]]

Raises:

CometError – On internal error

Available:

InDesign®

CScript:

comet.jobs.registerDocument(document)¶

Register the processing of a document by a queue script.

If a queue script has registered a document, the queue waits after the script has finished until the registered document has been closed by InDesign® in the background.

Parameters:

document (None | CDocument) –

The document to register.

The parameter type can be:

None
Use the script document.
CDocument
A document.

Return type:

None

Raises:

TypeError – When parameter types are invalid
ValueError – When parameter document is None and there is no script document
CometError –
- When the script is called in the wrong context
- On internal error

Available:

InDesign®

CScript:

jobs::register_doc

comet.jobs¶

Documentation¶

Queue script¶

Methods¶

Table of Contents

Previous topic

Next topic

This Page