Skip To Content

WorkflowConnection

Summary

The WorkflowConnection object provides access to methods for creating or getting a Workflow Manager job.

Discussion

Jobs are created from a job type template. All of the properties for the new job are automatically inherited from the job type and can be updated after creation using the Job methods.

Properties

PropertyExplanationData Type
jtcPath
(Read Only)

Returns the path to the workflow connection file (.jtc) in the ArcGIS Pro project.

If there is an existing ArcGIS Pro connection, it will return the complete path to the workflow connection file. If a connection to the workflow manager database is created using Connect, the jtcPath property can be used to get the manually entered workflow connection path for establishing connection.

String

Method Overview

MethodExplanation
createJob ({job_type_id}, {job_type_name}, {job_type_description}, {callback})

Creates a new job based on a job type.

createSD (output_directory, service_name, {connection_file_path}, {folder_name}, {description}, {mininstances}, {maxinstances}, {maxusagetime}, {maxwaittime}, {maxidletime})

Creates a Service Definition (.sd) file of the Workflow Manager service type that can be published to a specified GIS server.

getJob (jobID)

Return a single job using its job ID.

getQualifiedTableName (table_name)

Returns a fully qualified table name for a table in a Workflow Manager database.

queryJobs (fields, tables, {aliases}, {where}, {order_by})

Queries jobs based on criteria and returns a QueryResult object then allows access to a list of jobs and job properties that meet the criteria.

Methods

createJob ({job_type_id}, {job_type_name}, {job_type_description}, {callback})
ParameterExplanationData Type
job_type_id

The ID of the job type from which to create a new job.

Integer
job_type_name

The name of the job type from which to create a new job.

String
job_type_description

The properties of the job type that can be customized and assigned to a new job being created, provided as the JobTypeDescription object.

JobTypeDescription
callback

The callback argument is used when the job is set to automatically execute after being created. It 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 TypeExplanation
Job

Returns the job created as a Job. A list of Job objects is returned when multiple jobs are created by providing a list of Geometry objects in the JobTypeDescription and the LOI are not set to be unioned.

To create a new job requires a job type name, a job type ID, or a job type description.

The following script creates two jobs in the Workflow Manager database: one defined by the job type name and the other by the job type ID.

import arcpy

#Establish a connection to a Workflow database
conn = arcpy.wmx.Connect(r'c:\test\Workflow.jtc')

#Create a Workflow Job of type Data Edits
job = conn.createJob(job_type_name="Data Edits")

#Create a Workflow Job of type 5
job2 = conn.createJob(job_type_id = 5)

The following script creates a job in the Workflow Manager database using the customized job type description. The customized job description provides the LOI, assigns the job to a user, assigns a data workspace to the job, assigns a parent using the ID, assigns a parent job version, adds a prefix to the job, and assigns a version for the job.

import arcpy

#Establish a connection to a Workflow database
conn = arcpy.wmx.Connect(r'c:\test\Workflow.jtc')

#Create a polygon geometry for LOI
coordList = [[-105.0, 39.0], [-100.0, 39.0], [-100.0, 35.0], [-105.0, 35.0]]
array = arcpy.Array([arcpy.Point(x, y) for x, y in coordList])
loi = arcpy.Polygon(array)

#Create a job type description with customized properties
desc = {'LOI': 'loi', 'assignedTo':'amiller', 'assignedType': 'User', 'dataWorkspaceID':'{DB245005-0D1E-47B8-AE39-CC08530A6C9D}', 'jobTypeName':'Quality Control', 'parentJobID': '9999', 'parentVersionName': 'sde.Default', 'prefix':'QA_', 'versionName':'QA_QC'}

#Create a Workflow Job of type Quality Control
job = conn.createJob(job_type_description=desc)
createSD (output_directory, service_name, {connection_file_path}, {folder_name}, {description}, {mininstances}, {maxinstances}, {maxusagetime}, {maxwaittime}, {maxidletime})
ParameterExplanationData Type
output_directory

The folder path for the the output (.sd) file.

String
service_name

The name of the service. The name can only contain alphanumeric characters and underscores. The name cannot be more than 120 characters in length.

String
connection_file_path

The path and file name of the ArcGIS Serverconnection file (.ags).

String
folder_name

The folder name to which to publish the service definition. If the folder does not currently exist, it will be created. The default folder is the server root level.

String
description

The description summary.

String
mininstances

The minimum number of instances a service will start and make available for use.

(The default value is 1)

Integer
maxinstances

The maximum number of instances a service can start and make available for use.

(The default value is 2)

Integer
maxusagetime

The maximum time, in seconds, that a service can be used. For expected long running tasks increase the default time.

(The default value is 600)

Integer
maxwaittime

The maximum time, in seconds, that a client will wait to connect with an instance before timing out. When all instances are busy processing requests, subsequent requests are queued. If this time-out elapses before an instance becomes available the task will fail.

(The default value is 60)

Integer
maxidletime

The maximum time, in seconds, that an instance will continue to be active before pool shrinking occurs. Any instances above the minimum number of instances that have not been used will be shut down once the idle maximum time value has elapsed.

Integer
Return Value
Data TypeExplanation
String

The output path to the resulting .sd file.

createSD is the first step to automating the publishing of a Workflow Manager service type to a GIS Server using ArcPy. The output created from the createSD is a Service Definition file (.sd) representing the Workflow Manager service type, it is a combination of information about the server and a set of service properties.

A Service Definition can be authored without knowing the specific server connection information. In this case, the connection_file_path parameter may be omitted.

Once the output Service Definition file is created it can be uploaded and published as a Workflow Manager service to a specified GIS server using the Upload Service Definition. This takes the Service Definition file, copies it to the server, extracts the required information and publishes the GIS resource. For more information, see overview of the Publishing toolset

If using ArcGIS Pro then the specified GIS server must be federated to a portal.

Create a Workflow Manager service definition file and publish it to a federated GIS Server.

import arcpy

#Establish a connection to a Workflow database
conn = arcpy.wmx.Connect(r'c:\test\Workflow.jtc')

# Create the service definition file with connecting to the federated ArcGIS Server

conn.createSD(r'c:\test\SD','Workflow', None, 'serverfolder','service description',2,4,3000,300,2000)

# Publish the service using the service definition file
arcpy.UploadServiceDefinition_server(r'c:\test\SD\workflow.sd', 'https://servername.domain:6443/arcgis')
getJob (jobID)
ParameterExplanationData Type
jobID

The ID of the job to return.

Integer
Return Value
Data TypeExplanation
Job

Returns the job as a Job.

Provides an easy way to retrieve a job.

Get a job from a Workflow Manager database.

import arcpy

#Establish a connection to a Workflow database
conn = arcpy.wmx.Connect(r'c:\test\Workflow.jtc')

#Access a Workflow Job
job = conn.getJob(99999)
getQualifiedTableName (table_name)
ParameterExplanationData Type
table_name

The table name to qualify.

String
Return Value
Data TypeExplanation
String

Returns the fully qualified table name.

Get a fully qualified table name from a Workflow Manager database.

import arcpy


#Establish a connection to a Workflow database
conn = arcpy.wmx.Connect(r'c:\test\Workflow.jtc')

#Enter a tablename in the Workflow database
tablename = conn.getQualifiedTableName("Trails")
queryJobs (fields, tables, {aliases}, {where}, {order_by})
ParameterExplanationData Type
fields

Fields from the query table(s) to be returned for the jobs that meet the criteria.

String
tables

Tables in the Workflow Manager database used to query jobs.

String
aliases

Alias names defined by the user for the returned fields. The alias names are listed in the same order as the corresponding fields.

String
where

A where clause used to query jobs.

String
order_by

The fields used to order the query results.

String
Return Value
Data TypeExplanation
Object

QueryJobs method returns QueryResult object and allows access to the list of jobs and job properties returned by the query.

The QueryResult object is a list of QueryRow referenced to a certain job and QueryField referenced to a certain job's property, returned from QueryJobs method.

The following script runs a query to find and print the names of jobs assigned to the current user.

import arcpy

#Establish a connection to a Workflow database
conn = arcpy.wmx.Connect(r'c:\test\Workflow.jtc')

#Run a query for the jobs assigned to the current user and print each job name
for row in conn.queryJobs("JOB_NAME,ASSIGNED_TO","JTX_JOBS","Job Name,Assigned To", "ASSIGNED_TO = '[SYS:CUR_LOGIN]'", "JOB_NAME").rows:
	print(row[0])

Code sample

The following script creates one job and gets another from a Workflow Manager database.

import arcpy

#Establish a connection to a Workflow database
conn = arcpy.wmx.Connect(r'c:\test\Workflow.jtc')

#Create a Workflow Job of type Data Edits
job = conn.createJob(job_type_name="Data Edits")

#Access a Workflow Job
job = conn.getJob(99999)