Job

Summary

The Job object provides access to properties and methods to interact with a Workflow Manager (Classic) job.

Discussion

A Job is a single unit of work that is carried out within an organization. It may have one or many people working on it. It can work with a single dataset, multiple datasets, or no data at all. A Job is created based on a template known as a Job Type, which is configured with the desired properties and components (such as the Workflow and Maps) that will be used in the job.

Properties

Property	Explanation	Data Type
assignedTo (Read and Write)	The user name or group to which the job is assigned.	String
assignedType (Read and Write)	The type of assignment for the job. Below is a list of valid strings to use when setting the job assignment. If an invalid string is used, the job will default to unassigned. User—A user in the workflow database Group—A group in the workflow database Unassigned—No job assignment	String
createdBy (Read and Write)	The user name of the user who created the job.	String
createdDate (Read Only)	Returns the date the job was created.	DateTime
currentSteps (Read Only)	Returns a list of step IDs representing the steps that are active in the workflow.	List
description (Read and Write)	The description of the job.	String
dueDate (Read and Write)	The date the job was scheduled to end.	DateTime
endDate (Read Only)	Returns the date the job ended.	DateTime
hasAOI (Read Only)	Returns True when the job has an area of interest defined. Legacy: This method has been deprecated. Use hasLOI instead.	Boolean
hasLOI (Read Only)	Returns True when the job has a location of interest (point or polygon) defined.	Boolean
ID (Read Only)	Returns the job ID.	Integer
jobTypeID (Read Only)	Gets the ID of the job type for the job.	Integer
name (Read and Write)	The job's name.	String
notes (Read and Write)	The notes associated with the job to share information with other users.	String
owner (Read and Write)	The user name of the user who owns the job.	String
parent (Read and Write)	The ID of the parent job for the current job.	Integer
parentVersion (Read and Write)	The name of the parent version of the job.	String
percentComplete (Read Only)	Returns the percent completion for the job.	Double
priority (Read and Write)	The priority of the job.	Integer
startDate (Read and Write)	The date the job was scheduled to start.	DateTime
startedDate (Read Only)	Returns the date the job was started.	DateTime
status (Read and Write)	The status name for the job. The statuses available for use are those defined as status types in the database.	String
versionExists (Read Only)	Returns True when a version exists for a job.	Boolean
versionName (Read and Write)	The name of the version for the job.	String

Method Overview

Method	Explanation
addAttachment (storage_type, source_location)	Adds an attachment to the job.
addDependency (depends_on_job_id, {held_on_type}, {held_on_value}, {dependent_on_type}, {dependent_on_value})	Adds a dependency to a job to restrict progression of the job past a certain point until another job has progressed past a given point.
addHold (hold_type_id, {comment})	Adds a hold to a job to suspend job activity.
deleteAttachment (attachment_id)	Deletes an attachment associated with the job.
deleteJobMap ()	Deletes the job map associated with the job.
executeStep ({step_id}, {callback})	Executes a step in the workflow.
getAttachments ()	Returns all attachments associated with the job as a list of Attachment objects.
getExtendedPropertyTable (tableName)	Returns a single extended property table based on its fully qualified table name.
getHolds ()	Returns the holds associated with the job as a list of Hold objects.
getPendingDays (consider_hold)	Returns the number of days that the job has been pending. This can also optionally consider the holds and subtract them from the number of days the job was pending.
getWorkflow (jobID)	Returns a job's Workflow using the job ID.
listExtendedProperties ()	Lists the fully qualified name of all extended property and linked property tables associated with the job.
logActivity (activity_type, {message})	Logs an activity in the job history to describe an action on the job.
markStepAsComplete ({step_id}, {callback})	Marks a step in the workflow as complete.
releaseHold (hold, {comment})	Releases the hold associated with a job and marks it as an inactive hold.
retrieveAttachment (attachment_id, destination_location)	Retrieves the file attachments associated with the job to a location on disk.
retrieveJobMap (destination_location)	Retrieves the job map to a location on disk.
save ()	Saves any changes made to the job back to the Workflow Manager (Classic) database.
sendNotification (notification_type)	Sends a notification based on an event in the job life cycle.
setAOI (aoi)	Sets the area of interest (AOI) polygon for the job. Legacy: This method has been deprecated. Use setLOI instead.
setDataWorkspace (data_workspace_id)	Sets the data workspace for the job.
setLOI (loi)	Sets the location of interest (LOI) for the job. The LOI can be either a point (POI) or polygon (AOI).
setStepAsCurrent (step_id)	Sets a step in the workflow as the current active step.
storeJobMap (source_location)	Saves a map in the Workflow Manager (Classic) database and associates it to the job as the job map to be used for editing.

Methods

addAttachment (storage_type, source_location)

Parameter	Explanation	Data Type
storage_type	The type of attachment to be added. EMBEDDED—The file is stored in the Workflow Manager (Classic) database. LINKED—The link to the file path is stored in the Workflow Manager (Classic) database. URL—The URL link is stored in the database.	String
source_location	The file path or URL for the attachment to be added.	String

The attachments provide a way to add information to the job. The following types of attachments can be added to a job:

• Embedded—The file is stored in the Workflow Manager (Classic) database.
• Linked—The link to the file path is stored in the Workflow Manager (Classic) database.
• URL—The URL link is stored in the database.

addDependency (depends_on_job_id, {held_on_type}, {held_on_value}, {dependent_on_type}, {dependent_on_value})

Parameter	Explanation	Data Type
depends_on_job_id	ID of the job on which the current job will depend.	Integer
held_on_type	Indicates whether the current job (to which the dependency is being added) will be held at a step or status. When the job is held at a step, the step cannot be executed until the dependency is released. When the job is held at a status, the job's status cannot change until the dependency is released. The dependency is released when the other job reaches the step or status as defined in the dependency criteria. (The default value is STEP)	String
held_on_value	The value of the step or status at which the current job will be held. This value can be the ID of a step as an integer or job status as a string.	Variant
dependent_on_type	Indicates whether the current job (to which the dependency is being added) will be dependent on a step or status of the other job. When the dependent job is held at a step or status of the other job, the dependent job cannot progress until the other job reaches the step or status defined in the dependency. Once the other job reaches step or status as defined in the dependency criteria the dependency is released and the dependent job can progress. (The default value is STATUS)	String
dependent_on_value	The value of the step or status of the other job on which the current job will be dependent. This value can be the ID of a step as an integer or job status as a string. (The default value is CLOSED)	Variant

Job dependencies allow you to model relationships between jobs, allowing you to restrict progress of a job until another job has progressed past a certain point. Restrictions can be placed on the following parts of a job: Status or Step.

When the job that is restricting the workflow of another reaches the point defined in the dependency, the restricted job is automatically released and is able to work.

addHold (hold_type_id, {comment})

Parameter	Explanation	Data Type
hold_type_id	The ID of the hold type template to be used to create the job hold.	Integer
comment	The comment to be stored as a reason for adding the hold.	String

Holds suspend the job activity for an indefinite amount of time until it is released. A hold can be applied to a job for reasons including the following:

• Insufficient funding
• Technical problems
• Missing data
• Lack of resources

deleteAttachment (attachment_id)

Parameter	Explanation	Data Type
attachment_id	The ID of the attachment to be deleted.	Integer

The attachments provide a way to add information to the job.

deleteJobMap ()

The job map has the layers used for editing required as part of the job.

executeStep ({step_id}, {callback})

Parameter	Explanation	Data Type
step_id	The ID of the step to be executed. The step ID is optional; if a step ID is not provided, the current step will be executed.	Integer
callback	The callback argument passes a function that prompts the user for a response based on input from the step type. When executing a question step, for example, the callback takes the possible step response options and allows the user to choose the next step. It is also used when the next step in the workflow cannot be determined so a user can select the path to follow.	Function

Return Value

Data Type	Explanation
WorkflowExecutionResult	Returns a WorkflowExecutionResult object, which stores the step's return code.

Provides a way to execute a step in the workflow.

getAttachments ()

Return Value

Data Type	Explanation
Attachment	The attachments associated with the job are returned as a list of Attachment objects.

The attachments provide a way to add information to the job. The following types of attachments can be added to a job:

• Embedded—The file is stored in the Workflow Manager (Classic) database.
• Linked—The link to the file path is stored in the Workflow Manager (Classic) database.
• URL—The URL link is stored in the database.

getExtendedPropertyTable (tableName)

Parameter	Explanation	Data Type
tableName	The fully qualified table name of the extended property table to be returned.	String

Return Value

Data Type	Explanation
ExtendedProperty	Returns the extended property table as the ExtendedProperty object.

The business-specific information stored as part of the job as extended properties are returned as the ExtendedProperty object.

getHolds ()

Return Value

Data Type	Explanation
Hold	The job holds returned as a list of Hold objects.

Holds suspend the job activity for an indefinite amount of time until it is released. A hold may be applied to a job for reasons including the following:

• Insufficient funding
• Technical problems
• Missing data
• Lack of resources

The information about a Hold is never deleted from the system and can be queried.

getPendingDays (consider_hold)

Parameter	Explanation	Data Type
consider_hold	Flag to determine whether to consider the holds when calculating the number of pending days.	Boolean

Return Value

Data Type	Explanation
Integer	Returns the number of days the job has been pending.

Pending days refers to the number of days the job has been worked on or the number of days the job has been pending before being completed. The start date used for the calculation is either the Start Date if it was set or the Created Date otherwise. The end date for the calculation is either the current date or the End Date if the job is closed.

getWorkflow (jobID)

Parameter	Explanation	Data Type
jobID	The ID of the job.	Integer

Return Value

Data Type	Explanation
Object	Returns the workflow as a Workflow object.

Provides an easy way to retrieve a job's workflow.

listExtendedProperties ()

Return Value

Data Type	Explanation
String	List of fully qualified names of all extended property and linked property tables associated with the job.

The names of tables that store business-specific information with the job as extended properties and linked properties can be retrieved.

logActivity (activity_type, {message})

Parameter	Explanation	Data Type
activity_type	The ID or the name of an ActivityType.	String
message	The custom message to be appended to the existing message in the ActivityType.	String

The Job history contains a log of everything that has happened throughout the life of the job. Each of the items in the log are time stamped with the time of entry and stamped with the current user at that time. A message is also stored along with the record, explaining what happened at that point in time.

markStepAsComplete ({step_id}, {callback})

Parameter	Explanation	Data Type
step_id	The ID of the step to be marked as complete. The step ID is optional; if a step ID is not provided, the current step will be executed.	Integer
callback	The callback argument passes a function that prompts the user for a response based on input from the step type. When marking a question step complete, for example, the callback takes the possible step response options and allows the user to choose the next step. It is also used when the next step in the workflow cannot be determined so a user can select the path to follow.	Function

Provides a way to mark a step as complete.

releaseHold (hold, {comment})

Parameter	Explanation	Data Type
hold	The hold to be released provided as a Hold object.	Hold
comment	The comment to be stored as a reason for releasing the hold.	String

The hold suspends the job activity for an indefinite amount of time until it is released. Once a hold is released, the information about it is never deleted from the system and can be queried.

retrieveAttachment (attachment_id, destination_location)

Parameter	Explanation	Data Type
attachment_id	The ID of the attachment to be retrieved.	Integer
destination_location	The folder location where the attachment will be stored. A name for the file to be saved with or without the file extension can also be provided. If no name is provided, the attachment is saved with the default name stored with the job.	String

The attachments provide a way to add information to the job. The following types of attachments can be retrieved from a job:

• Embedded—The file is stored in the Workflow Manager (Classic) database.
• Linked—The link to the file path is stored in the Workflow Manager (Classic) database. It can be retrieved only if you have access to the file path.

retrieveJobMap (destination_location)

Parameter	Explanation	Data Type
destination_location	The folder location where the job map will be stored. A name for the map to be saved can also be provided. If no name is provided the job map is saved with the default naming scheme defined for the job map.	String

The job map has the layers used for editing required as part of the job.

save ()

sendNotification (notification_type)

Parameter	Explanation	Data Type
notification_type	The name of the notification type template to be used to send the email notification associated with the job.	String

Email notification can be triggered during the life cycle of a job to provide information about an event related to the job. Examples of sending notifications include the following:

• Job assigned or reassigned
• Job created
• Job closed

setAOI (aoi)

Parameter	Explanation	Data Type
aoi	The AOI polygon to be assigned to the job.	Geometry

Define's an area of interest for a job. To get a job's area of interest polygon, use the Get Job AOI tool.

setDataWorkspace (data_workspace_id)

Parameter	Explanation	Data Type
data_workspace_id	The GUID of the data workspace to be made active for the job.	String

Set the data workspace for a job. To get a job's data workspace, use the Get Job Data Workspace tool.

setLOI (loi)

Parameter	Explanation	Data Type
loi	The point or polygon to be assigned as the location of interest for the job.	Geometry

Defines the location of interest for a job. To get a job's location of interest, use the Get Job AOItool.

setStepAsCurrent (step_id)

Parameter	Explanation	Data Type
step_id	The ID of the step to be set as the current step.	Integer

Provides a way to set a step in the workflow as the current active step.

storeJobMap (source_location)

Parameter	Explanation	Data Type
source_location	The file path that has the map to be stored in the Workflow Manager (Classic) database.	String

The job map has the layers used for editing required as part of the job.