Job Information Methods

Functions
*hash	info.getJobOverview (softdate $date=now()-1D, any $jobids, bool $useSqlCache=True)
	gets job overview, params: [date, [jobids]]: If no date is given, default = last 24 hours More...
*hash	info.getJobOverviewFromName (softdate $date=now()-1D, *string $name, bool $useSqlCache=True)
	gets job overview, params: [date, [name]]: If no date is given, default = last 24 hours More...
*hash	info.getJobMetadata ()
	retrieves job metadata (optional params: list of job ids), returns: job info keyed by name More...
*hash	info.getJobMetadataFromName (string $name)
	retrieves job metadata from the name, returns: job info keyed by name More...
list	info.getJobList ()
	retrieves a list of all jobs without the code field More...
*hash	info.getJobStatus (softint $jiid)
	returns NOTHING if the job instance ID is not valid or a hash giving job instance status corresponding to the job instance ID passed as an argument More...
*list	info.getJobInstanceList (any $jobid, *softdate $date=now()-1D, any $stati, softint $rownum=get_option("row-limit"))
	gets a list of job instance ids (not more than 100 by default, can be overridden with the 4th argument), params: jobid (single value or list), date, [statuses, num rows] More...
*list	info.getJobInstances (*softlist $jobids, *softlist $statuses, *softdate $modified, softint $rownum=get_option("row-limit"), *softint $offset, *softlist $sort, *softlist $jiids, *softbool $desc, *softbool $full)
	gets a list of job instance ids, params: jobid, condition, number of rows (100 default) More...

Detailed Description

Function Documentation

* list info.getJobInstanceList	(	any	$jobid,
		*softdate	$date = now() - 1D,
		any	$stati,
		softint	$rownum = get_option("row-limit")
	)

gets a list of job instance ids (not more than 100 by default, can be overridden with the 4th argument), params: jobid (single value or list), date, [statuses, num rows]

Parameters

$jobid	a single jobid or a list of jobids to query
$date	an optional cutoff date, if the date parameter is not passed, then the cutoff date is set to 24 hours in the past; the cutoff date is used with the job_instance.modified column; only rows with a modified date greater than or equal to the date passed will be returned
$stati	a single job status or a list of job statuses to check; see Job Data Status Descriptions for possible values
$rownum	the maximum number of rows to return

Returns

a list of integer job instance IDs

Note

if more than one jobid is given, there is no way to differentiate the jobid from the list returned because only a flat list of job_instanceid values is returned

Exceptions

PARAMETER-ERROR	missing jobid parameter, invalid date passed, or invalid job status passed
JOB-ACCESS-ERROR	Role Based Access Control is enabled and the calling user does not have the right to access one or more of the given jobids

* list info.getJobInstances	(	*softlist	$jobids,
		*softlist	$statuses,
		*softdate	$modified,
		softint	$rownum = get_option("row-limit"),
		*softint	$offset,
		*softlist	$sort,
		*softlist	$jiids,
		*softbool	$desc,
		*softbool	$full
	)

gets a list of job instance ids, params: jobid, condition, number of rows (100 default)

Parameters

$jobid	the jobid to query
$statuses	a list with requested statuses in expanded form ('ERROR') or NOTHING
$modified	a limit (>=) for MODIFIED columnn or NOTHING
$rownum	the maximum number of rows to return

Returns

NOTHING if no rows match the criteria, or a list of hashes with the following keys:

• job_instanceid: the job instance ID being queried
• jobid: the jobid (metadata ID)
• jobstatus: the current status of the job (see Job Data Status Descriptions for possible values)
• sessionid: the application session currently running the job, otherwise 0
• started: the time the job instance was started
• completed: the time the job instance completed (with any status)
• modified: the time the job instance was last modified

Exceptions

JOB-ACCESS-ERROR

Role Based Access Control is enabled and the calling user does not have the right to access one or more of the given jobids

list info.getJobList

(

)

retrieves a list of all jobs without the code field

Returns

a list of hashes with the following keys for all jobs in the database:

• name: the unique name of the job
• jobid: the unique job ID
• description: job description
• version: version number of the job
• sessionid: if single_instance is True, then this field could be non-0, meaning that the job is currently running in that instance
• active: True if active, False if not
• run_skipped: True if the job should be executed immediately if a trigger time was missed due to down time, False if not
• [recurring]: if this field is present, this gives the number of seconds between job executions, and the cron fields will not be present
• [minute]: cron field: minutes when the job can be executed
• [hour]: cron field: hours when the job can be executed
• [day]: cron field: days when the job can be executed
• [month]: cron field: months when the job can be executed
• [wday]: cron field: week days (0 = Sunday) when the job can be executed
• [last_executed]: the date/time the job was last executed (if not present, the job has not yet been executed)
• [expiry_date]: the date/time the job will expire; if this date is present, the job will not run automatically after this date
• created: the date/time the job was loaded into the database
• modified: the date/time the job was modified in the database
• single_instance: if True, then this job can only be started on one Qorus instance at a time
• groups: a list of RBAC group names that this job is a member of

Note

if this method is called externally, and the user has a limited list of accessible jobs, then only information about the jobs the user can access is returned

* hash info.getJobMetadata

(

)

retrieves job metadata (optional params: list of job ids), returns: job info keyed by name

Returns

NOTHING if no job can be matched to any of the given ids (or no jobs are in the system if no id is passed), or a hash keyed by job name where the value is a hash of job information with the following keys:

• name: the unique name of the job
• jobid: the unique job ID
• description: job description
• version: version number of the job
• sessionid: if single_instance is True, then this field could be non-0, meaning that the job is currently running in that instance
• active: True if active, False if not
• run_skipped: True if the job should be executed immediately if a trigger time was missed due to down time, False if not
• code: the source code of the job
• [recurring]: if this field is present, this gives the number of seconds between job executions, and the cron fields will not be present
• [minute]: cron field: minutes when the job can be executed
• [hour]: cron field: hours when the job can be executed
• [day]: cron field: days when the job can be executed
• [month]: cron field: months when the job can be executed
• [wday]: cron field: week days (0 = Sunday) when the job can be executed
• [last_executed]: the date/time the job was last executed (if not present, the job has not yet been executed)
• [expiry_date]: the date/time the job will expire; if this date is present, the job will not run automatically after this date
• created: the date/time the job was loaded into the database
• modified: the date/time the job was modified in the database
• single_instance: if True, then this job can only be started on one Qorus instance at a time
• lib: a hash keyed by library object type (key values: "functions", "classes", "constants"); the value of each key will be a list of hashes with the following keys (empty lists mean no objects of that type are listed as library objects of the workflow):
  • name: the name of the library object
  • version: the version of the library object
  • id: the ID of the library object (referencing the tables, FUNCTION_INSTANCE, CLASSES, or CONSTANTS)
• groups: a list of RBAC group names that this job is a member of

Exceptions

JOB-ACCESS-ERROR

Role Based Access Control is enabled and the user does not have access to the given job

* hash info.getJobMetadataFromName

(

string

$name

)

retrieves job metadata from the name, returns: job info keyed by name

Parameters

$name

the name of the job to query

Returns

see info.getJobMetadata() for information about the return value

Exceptions

JOB-ACCESS-ERROR

Role Based Access Control is enabled and the user does not have access to the given job

* hash info.getJobOverview	(	softdate	$date = now() - 1D,
		any	$jobids,
		bool	$useSqlCache = True
	)

gets job overview, params: [date, [jobids]]: If no date is given, default = last 24 hours

Parameters

$date	the minimum date to check for changes; job_instance rows with a modified date before this date will not be reported; the default value is 24 hours from the current date and time
$jobids

Returns

NOTHING if no information is available, otherwise a hash where the keys are job names and the values are hashes with the following keys:

• jobid: the jobid of the job
• version: the version of the job
• [COMPLETE]: the number of job instances with status OMQ::JS_Complete in the given time frame
• [ERROR]: the number of job instances with status OMQ::JS_Complete in the given time frame
• [IN-PROGRESS]: the number of job instances with status OMQ::JS_InProgress in the given time frame (should never be > 1 for a given job)
• [CRASH]: the number of job instances with status OMQ::JS_Crash in the given time frame

Exceptions

PARAMETER-ERROR	the date passed was not valid
JOB-ACCESS-ERROR	Role Based Access Control is enabled and the user does not have access to the given job

Note

if this method is called externally, and the user has a limited list of accessible jobs, then only information about the jobs the user can access is returned; if the user requests a particular job and does not have access to that job, then a JOB-ACCESS-ERROR exception is raised

* hash info.getJobOverviewFromName	(	softdate	$date = now() - 1D,
		*string	$name,
		bool	$useSqlCache = True
	)

gets job overview, params: [date, [name]]: If no date is given, default = last 24 hours

Parameters

$date	the minimum date to check for changes; job_instance rows with a modified date before this date will not be reported; the default value is 24 hours from the current date and time
$name	the optional name of the job to check; if no name is passed, then all accessible jobs will be reported

Returns

see info.getJobOverview() for the return value

Exceptions

UNKNOWN-JOB	the job name given does not exist
PARAMETER-ERROR	the date passed was not valid
JOB-ACCESS-ERROR	Role Based Access Control is enabled and the user does not have access to the given job

Note

if this method is called externally, and the user has a limited list of accessible jobs, then only information about the jobs the user can access is returned; if the user requests a particular job and does not have access to that job, then a JOB-ACCESS-ERROR exception is raised

* hash info.getJobStatus

(

softint

$jiid

)

returns NOTHING if the job instance ID is not valid or a hash giving job instance status corresponding to the job instance ID passed as an argument

Parameters

$jiid

the job instance ID to query

Returns

NOTHING if the job instance ID is not valid or a hash giving job instance status corresponding to the job instance ID passed as an argument with the following keys:

• job_instanceid: the job instance ID being queried
• jobid: the jobid (metadata ID)
• sessionid: the application session currently running the job, otherwise 0
• jobstatus: the current status of the job (see Job Data Status Descriptions for possible values)
• [info]: the information saved against the job (if any)
• started: the time the job instance was started
• completed: the time the job instance completed (with any status)
• modified: the time the job instance was last modified
• errors: if any errors were raised against the job instance, they will appear as hashes in a list assigned to this key; the hashes will have the following keys:
  • job_errorid: the unique ID of the error in the job_errors table
  • severity: the severity of the error (see Error Severity Codes for possible values)
  • error: the error code
  • description: description of the error
  • [info]: any additional data saved against the error
  • business_error: True if the error is a business error, False if not
  • created: the date/time the error was created
• audit: if any audit events were created for the given job instance, they will appear as hashes in a list assigned to this key; the hashes will have the following keys:
  • audit_eventid: the audit event ID (unique key in the AUDIT_EVENTS table)
  • [related_audit_eventid]: related audit event ID
  • audit_event_code: the audit event code (see Audit Event Codes for possible values)
  • [audit_user_event]: the user audit event code string (present only when audit_event_code is OMQ::AE_USER_EVENT)
  • [reason]: the reason for the event
  • who: the initiator of the event
  • source: a string describing the source of the event
  • [info1]: an informational string about the event
  • [info2]: an informational string about the event
  • created: the date/time the audit event was created
  • event: the string description corresponding to the audit_event_code (see Audit Event Strings for possible values)

Exceptions

JOB-ACCESS-ERROR

Role Based Access Control is enabled and the user does not have access to the given job instance ID