Workflow Manager custom steps

Available with Standard or Advanced license.

Available with Workflow Manager license.

ArcGIS Workflow Manager for Desktop provides several custom steps. The source code for each of these is provided as part of the developer kit. The following outlines the process steps and what they can do.

Steps library

The Steps library contains steps that can be executed in both the desktop and server environments. The steps and their arguments and return codes are outlined below.

1. AddJobHold

   JTXSteps.AddJobHold

   Adds a hold to the current job.

   Hold Type Name:
   	/holdType:<hold type> (required) 
   Hold Comment:
   	/holdComment:<string> (optional)
   

   Return codes:
   • 1 = Success
   • 0 = Failure
2. CheckAOI

   JTXSteps.CheckAOI

   Checks if a location of interest (LOI) exists for the current job.

   No Argument
   

   Return codes:
   • 1 = If job has an LOI
   • 2 = If job does not have an LOI
3. CleanUp

   JTXSteps.CleanUp

   Cleans up the job based on the arguments. Enable the Administration system settings to allow users to delete versions owned by other users. This will prompt for a user name and password.

   Note:

   When deleting a version owned by a different user, you must specify the geodatabase super user's credentials.

   Version Cleanup:
   	/version|v (optional)
   MXD Cleanup:
   	/mxd|m (optional)
   Attachment Cleanup:
   	/attachments|a (optional)
   

   Return codes:
   • 0 = Success
4. CloseJob

   JTXSteps.CloseJob

   Closes a job as a step, as opposed to it being a manual process once the workflow is completed.

   No Argument
   

   Return codes:
   • 0 = Success
5. CreateJob

   JTXSteps.CreateJob

   Creates a child job based on the arguments.

   Job Type ID:
   	Job Type Name:
   	/jobtypename:<job type name> (required)
   Assign to Group:
   	/assigngroup:<group to assign to> (optional)
   Assign to User:
   	/assignuser:<user to assign to> (optional)
   Job Type ID:
   	/jobtypeid:<job type ID> (deprecated)
   

   Return codes:
   • 0 = Success
6. CreatePDF

   JTXSteps.CreatePDF

   Creates a PDF document of the job's basemap and attaches it to the job.

   Initial Directory:
   	/initdir:<initial directory> (optional)
   Do not Attach File To Job:
   	/noattach (optional)
   Resolution (dpi):
   	/resolution:<dpi> (optional)
   Attach File To Job:
   	/attach (deprecated)
   

   Return codes:
   • 0 = Success
7. CreateVersion

   JTXSteps.CreateVersion

   Creates the version for the job. The protection level of the version is specified by one of the following arguments: Version, Access, or Scope.The step supports the traditional data workspace and the feature service data workspace.

   /scope:<public|private|protected> (optional)[default:private]
   

   Return codes:
   • 0 = Success
8. ExecuteGPTool

   JTXSteps.ExecuteGPTool

   Executes a geoprocessing tool, model, or script without displaying the geoprocessing dialog box. The integer output from a tool can be used as a return code to guide the path of the workflow upon the tool's completion.

   Toolbox Path (explicit full path to the tbx file combined with toolbox name):
   		/toolboxpath:<toolboxpath> (required)
   Display Name of the Tool in the toolbox:
   	/tool:<tool> (required)
   Parameter to override on the tool (can be specified multiple times):
   /param:<ParamName>:<ParamValue> (optional)
   Flag to attach the log to the job once the tool has completed:
   /attach:(optional)
   Output parameter to use as return value:
   /outParam:<parameter name>
   

   Return codes:
   • 0 = Success
   • 1 = Failure

   Note:

   When the outParam argument is used, the success return code is the value returned as the output parameter from the geoprocessing tool, and the cancel return code becomes -1 in this case.

9. ExecuteSQL

   JTXSteps.ExecuteSQL

   Executes an SQL statement.

   Database to Send SQL:
   	/database:<jtxsystem|data> (required)SQL Command:
   	/sql:<sql command>
   

   Return codes:
   • 0 = Success
10. ExecuteURL

    JTXSteps.ExecuteURL

    Executes a URL without displaying a browser to show the response.For example, you can execute a geoprocessing service or any other web service as a workflow step.

    URL to execute:
    	/url:<url> (required)
    Request Timeout:
    	/timeout:<timeout in seconds> (optional)
    Proxy Server: 
     /proxy:<proxy> (optional)
    Flag to add a comment to the job with the response:
     /addjobcomment(optional)
    Post Data:
     /postdata:<data to post> (optional)
    

    Return codes:
    • 200 = Success
11. ExecuteWorkflow

    JTXSteps.ExecuteWorkflow

    Executes another workflow associated with a job type.

    Job Type Name:
    	/jobtype:<job type name> (required)Flag to not use AOI:
    	/donotuseaoi (optional)Flag to not use version:
    	/donotuseversion (optional)Flag to not copy activities to the parent job's history:
     /donotcopyactivities (optional)
    

    Return codes:
    • 0 = Success
12. ReturnValue

    JTXSteps.ReturnValue

    Retrieves the value of the extended property or token passed, which is the return code for the next path in the workflow.

    Return value:
    	/value:<Extended properties field> (required):
    

13. ReassignJob

    JTXSteps.ReassignJob

    Reassigns the job.

    Assign Type:
    	/assignType:<user|group> (required)
    Assign To:
    	/assignTo:<user or group name> (required)
    

    Return codes:
    • 0 = Success
14. SendNotification

    JTXSteps.SendNotification

    Sends a notification of the type specified by the argument.

    /notifType:<type> (required)
    

    Return codes:
    • 0 = Success
15. SetVersion

    JTXSteps.SetVersion

    Sets the job's version to a named version. For example, set the job's version to QC version to validate edits that were posted in that version. If there is no step argument, the job version will be reset to the original version.The step supports the traditional data workspace and the feature service data workspace.

    Version to use as job version: 
    /version:<versionName> (optional)
    

    Return codes:
    • 0 = Success
16. UpdateExtentFeatureClass

    JTXSteps.UpdateExtentFeatureClass

    Updates a feature class with job information to provide visual status.

    Feature Class to Update (must be in data geodatabase):
    	/fclass:<fully qualified feature class name> (required)
    Job ID Field (field to put job ID in):
    	/jobfield:<field name> (optional)
    Date Field (field to put date/time):
    	/datefield:<field name> (optional)
    

    Return codes:
    • 0 = Success
17. VersionExists

    JTXSteps.VersionExists

    Checks if the job already has a geodatabase version.The step supports the traditional data workspace and the feature service data workspace.

    No Argument
    

    Return codes:
    • 1 = Version exists
    • 2 = Version doesn't exist
    • 3 = No data workspace selected

DesktopSteps library

The DesktopSteps library contains steps that can be executed only from the desktop because of the pop-up user interfaces. The steps and their arguments and return codes are outlined below.

1. AddAttachments

   JTXDesktopSteps.AddAttachments

   Adds a linked, embedded, or URL attachment to the job.

   No Argument
   

   Return codes:
   • 1 = Success
   • 0 = Failure
2. CopyFile

   JTXDesktopSteps.CopyFile

   Copies a file from one location to another.

   Source File:
   	/src:<source file path> (optional)
   Destination File:
   	/dest:<destination file path> (optional)
   File Title:
   	/title:<file title> (optional)
   

   Return codes:
   • 0 = Success
3. CreateJobAdvanced

   JTXDesktopSteps.CreateJobAdvanced

   Creates a job and allows you to define the parent/child relationship with dependencies on the job. When creating a child job, the start date, due date, data workspace, and priority are copied from the parent job, while the job assignment is copied from the job type's default properties if a value is not specified in the step arguments.The step supports creating a version for the job with a traditional data workspace and a feature service data workspace. When the child job is set with a feature service data workspace, the parent version can only be sde.Default.

   Job Type Name:
   	/jobtypename:<job type name>(required)
   Assign To Group:
   	/assigngroup:<group to assign to>(optional)
   Assign To User:
   	/assignuser:<username to assign to> (optional)
   Dependency will be created and current job held at this step:
   	/dependThisStep (optional)
   Dependency will be created and current job held at the next step in the workflow:
   	/dependNextStep (optional)
   Dependency status (current job held until new job reaches this status):
   	/dependStatus:<Status Type Name> (optional)
   Use the current job's AOI as the new job's AOI:
   	/useparentaoi (optional)
   Create new jobs based on the overlap between the current job's AOI and this feature class:
   	/aoiOverlapFeatureClassName:<fully qualified feature class name >(optional)
   Default number of jobs to create:
   	/numberJobs:<number of jobs to create> (optional)
   A version will be created for the new job(s) based on this selection:
   	/createVersionSetting:<the version to use as the parent version> (optional)
   A version will be assigned to the new job(s) based on this selection:
   	/assignVersionSetting:<the existing version the job will be assigned to>(optional)
   New job(s) extended properties value will be set to one of the current job's extended properties values 
   specified by JTX Token) or to the given string value. To set multiple extended properties values at once separate 
   each entry by a semicolon:
   	/setExtendedProps: 
   <ChildJobFullyQualifiedExtendedPropertiesTableName.FieldName=
   [JOBEX:ParentJobFullyQualifiedExtendedPropertiesTableName.FieldName]>; 
   <ChildJobFullyQualifiedExtendedPropertiesTableName.FieldName=
   [JOBEX:ParentJobFullyQualifiedExtendedPropertiesTableName.FieldName]>;...(optional)
   Due date of the new job:
   	/dueDate:<due date of the new job>(optional)
   Job duration:
   	/jobDuration:<duration of the new job>(optional)
   New Job will be created as a child of the existing job:
   	/child(optional)
   

   Return codes:
   • 0 = Success
   • 1 = Failure
4. DefineAOI

   JTXDesktopSteps.DefineAOI

   Shows a tool to allow the user to define a location of interest.

   No Argument
   

   Return codes:
   • 1 = Success
   • 0 = Failure
5. EditExtendedProperties

   JTXDesktopSteps.EditExtendedProperties

   Displays the job's one-to-one (1-1) extended properties as a pop-up form to allow the user to provide required properties. This step can be included multiple times in the workflow with different extended properties to be opened at different stages of the workflow. This gives you the ability to choose only some extended properties configured on the job type to be displayed in the pop-up. The extended properties can be selected by opening the argument editor or by typing in the arguments box. All properties selected honor the properties set on the job type, such as visible, editable, and so on. If no arguments are specified, all the extended properties selected on the job type will be displayed when the steps are run.The argument editor displays all the tables and fields configured for all the job types in the repository; however, if properties are selected that are not configured on the job type, they will not be displayed in the pop-up form.The argument is composed of the extended property table name and field name. For example, if you want to display the RequestorName field from the RequestorInformation table, the argument would be /Property: RequestorInformation.RequestorName.

   /Property:<Property Name>
   

   • 1 = Success
6. LaunchArcMap

   For the step JTXDesktopSteps.LaunchArcMap, when executed, ArcMap will start. The layers will be resourced to the job version and the map will be zoomed to the job's location of interest.

   Learn more about step arguments for the LaunchArcMap step

   Return codes:

   • 0 = Success

7. LaunchGPTool

   JTXDesktopSteps.LaunchGPTool

   Executes geoprocessing tools from your workflows. The integer output from a tool can be used as a return code to guide the path of the workflow upon the tool's completion.

   Toolbox Path (explicit path to the tbx file):
   	/toolboxpath:<toolboxpath> (optional)
   Toolbox Name (if in system toolboxes):
   	/toolbox:<toolbox> (optional)
   Display Name of the Tool in the toolbox:
   	/tool:<tool> 
   Parameter to override on the tool (can be specified multiple times):
   	/param:<ParamName>:<ParamValue> (optional)
   Flag to attach the log to the job once the tool has completed:
   	/attach (optional)
   License enumeration code for any additional license that should be used in the execution of the tool:
   	/license:<enum value> (optional)
   Output parameter to use as return value:
    /outParam:<parameter name>
   

   Return codes:
   • 1 = Success
   • 0 = Cancel

   Note:

   When the outParam argument is used, the success return code is the value returned as the output parameter from the geoprocessing tool, and the cancel return code becomes -1 in this case.

8. SelectDataWorkspace

   JTXDesktopSteps.SelectDataWorkspace

   Shows a form that allows you to pick the data workspace for your job from a list of already configured data workspaces.

   No Argument
   

   Return codes:
   • 1 = Success
   • 0 = Failure

The LaunchArcMap step

The expected behavior of the LaunchArcMap step with no arguments is detailed in the following table.

This describes the expected behavior for the LaunchArcMap step provided with Workflow Manager.

Job type map document defined?	LaunchArcMap with data workspace and version	LaunchArcMap with data workspace and no version	LaunchArcMap with no data workspace
Yes	ArcMap is opened using the map document defined. Layers are resourced to the job's version based on the feature class's short name. The map is zoomed to the area of interest. Note: The short name is the feature class name, not the fully qualified name. For example, Streets instead of NIS.Streets. Also note that no matter how the basemap was originally defined, any short name matches should be resourced.	This works the same as the scenario when a version exists, except the default version for the data workspace is used for resourcing the layers.	No changes are made to the layer sources. The map is zoomed to the LOI.
No	ArcMap opens with a blank document. In this case, since no map exists, there are no layers to resource. Once layers are added to the map, the Add Data button on the Workflow Manager toolbar will take you directly to the version defined for the job or the default version for the selected data workspace.	This works the same as the scenario when a version exists.	ArcMap opens with a blank document. The Add Data button on the Workflow Manager toolbar is unavailable. If an LOI exists for the job, the Zoom To LOI tool can be used.

Basemap layers are not repointed in the map opened by Workflow Manager.

Note:

The JTXMxLaunch.exe executable for opening ArcMap is no longer included with the Workflow Manager installation. Upgrade any steps that use that utility to open ArcMap to use the custom step object JTXDesktopSteps.LaunchArcMap.

Caution:

If an ArcGIS Pro maps (.mapx) stored in the Workflow Manager repository and ArcGIS Pro map (.mapx), layout (.pagx), or web map stored in ArcGIS Online or Portal for ArcGIS is used with Job Types and steps configured for ArcGIS Desktop, it will not open and an error message will be displayed. Furthermore, if the step is run with a feature service data workspace in ArcGIS Desktop, it will not open and an error message will be displayed.

Argument descriptions

The LaunchArcMap step has many optional parameters available, allowing you to customize its execution for your needs without writing code.

The Launch ArcMap step argument editor and the step type Execution tab are shown with the default behavior configured.

Note:

The layers in the map must reference data from a data workspace in your Workflow Manager system for the version and user connection information to be repointed. If the map layers reference data from a data workspace in your Workflow Manager system, but there is no job version specified for the job, the map layers are repointed to the default database version for the data workspace. The map layers are not repointed in the following scenarios:

• If the job map is not defined, a blank map will open because there are no layers to repoint.
• If the step is configured to change only the version and the layers in a job map are not from a data workspace, the layers are displayed with a broken data source.
• If the layers are not from a data workspace and are selected for repointing in the job type properties, the layers are displayed with a broken data source.
• If the layers are not from a data workspace and are not selected for repointing in the job type properties, the layers are repointed to the default database version.

Learn more about maps and versioning

Descriptive name	Argument example	Behavior
Zoom to LOI.	/aoifactor:3 or /nozoomloi	With the default behavior, the map is panned to the job's AOI and zoomed by a factor of 1 to the shape's geometry. Optionally, you can choose to not pan or zoom the map using the /nozoomloi option. Or you can zoom to the AOI with a greater zoom factor using the /aoifactor argument. The zoom factor does not apply to a POI. For a single POI, the map will be zoomed to 1:2,000, and for multiple POIs, the map will zoom to their extent.
Do not change any connection information.	/norepoint	The default behavior, when /norepoint is not used, changes all the layers in the map to the current data workspace and, optionally, the job's version.
Change only the version for job's data workspace.	/changeversiononly	If you choose to use the /changeversiononly option, the version of the layers in the job type's map document will be changed. The data user and connection information will be left as they were originally configured. All layers from the data workspace will be repointed irrespective of whether they are selected for repoint in the job type properties or not. The layers that are not from the data workspace are displayed with a broken data source. Note: When using individual logins, this option does not repoint the map layers and they point to the default version.
Save MXDs.	/nosavemxd	The default behavior, when the /nosavemxd argument is not used, saves the job's map document in the Workflow Manager database. Thus, every time you open the job's map document using this step in the workflow, the last saved map from the database is retrieved. However, if you choose to use the /nosavemxd option, the job's map document will not be saved in the Workflow Manager database. Thus, if you change the extent of the job map and close it, the new extent will not be saved, and the next time, the map will still open with the original extent. Note: ArcMap displays a message to save the map every time a map is closed, but with /nosavemxd, the map is not saved even when you click Yes on the ArcMap message. If your map documents are large, you may need to adjust the MAXBLOBSIZE SDE configuration setting. This option also allows you to switch jobs in ArcMap without clearing out the map document.
Clip Data Frame to AOI.	/cliptoaoi	The default behavior, when the /cliptoaoi argument is not used, shows all the data in the map document that can be viewed. When the /cliptoaoi option is used, the data frame in the job's map document is clipped to the shape of the AOI. Note: This does not create a definition query on the layers. All features in the layers on the map are still accessible through their respective tables.
Wait for ArcMap to close (suspend Workflow Manager).	/nowait	The default Workflow Manager application behavior, when the /nowait argument is not used, is to hide while the ArcMap process is running. This means that the user cannot interact with the Workflow Manager application while working in ArcMap. When the /nowait option is used, ArcMap is launched in a separate process, allowing the user to interact with the Workflow Manager application while ArcMap is running. Note: This option was added because the Launch process asynchronously option for workflow steps is not available for Custom Step Objects.
Use existing ArcMap session.	/useexisting	The default behavior, when the /useexisting argument is not configured, is to open a new ArcMap session during the execution of the step. With the /useexisting option, if an ArcMap session is open when the step is executed, Workflow Manager opens the job's map document in that existing session. If there isn't an ArcMap session open, Workflow Manager will open a new one.
Store MXDs in shared location.	/mxdfolder:"D:\Data\JTXMapDocuments"	With the default behavior, no alternative location is configured, and the job's map documents are stored in the Workflow Manager database. If your map documents are large, you may need to adjust the MAXBLOBSIZE SDE configuration setting. If you choose to store the map documents in an alternative location, Workflow Manager will not save the map documents in the database but will save them to that location for future use.
Use Alternative MXD.	/mxd:"D:\Data\JTXTemplates\Editing.mxd"	With the default behavior, the step uses the job type's default map document as the basemap document for LaunchArcMap. If you choose to use this option, Workflow Manager will load the map document or template configured for the argument. Note: ArcGIS Pro maps (.mapx) can be used as an alternative to MXD for steps configured for ArcGIS Pro.
Run ArcMap Command.	/guid:esriArcMapUI.AddDataCommand	Once ArcMap has finished loading, the button represented by the ProgID entered is programmatically pushed.
Load Task Assistant workflow.	/taworkflow:"LotSplit"	With this argument configured, once ArcMap is opened, Workflow Manager opens the task assistant workflow configured. The workflow name passed in is the alias of the task assistant workflow stored in the Workflow Manager system. Multiple workflows can be passed in by adding additional /taworkflow entries or by choosing the desired workflows in the argument editor.
Store Task Assistant History in Job History.	/storetahistory	With this argument configured, the task assistant workflow is added to the job history by default. You can still choose to attach this as a text file using the Workflow Manager tools.