Add and configure Define Location

The Define Location step allows you to identify where work needs to be performed for a job. The location can be a point, line, or polygon in an existing feature service, in an ArcGIS Pro project, or in a web map in the ArcGIS Workflow Manager web app.

If the step is run in the Workflow Manager web app and Map is chosen as the location method, the web map configured in the step appears in the job tile. If help text is configured for the step, it appears at the bottom of the job tile. Selectable layers appear on the map, and all additional layers, except the Job Location layer, are read-only. Use the Manage Layers widget to change the visibility of individual layers and use the Draw A Feature or Select Features widget to define the location for the job.

Note:

If the job's location is already defined, it can't be edited, but can be replaced by drawing or selecting new features.

If the step is run in ArcGIS Pro and Map is chosen as the selection method, the Job Location layer is added to the map configured in the step when the step is run and the Create Features pane appears with the Job Location layer. If help text is configured for the step, it appears at the bottom of the job tile. Use the Create Features pane to define the location for the job.

The type of geometry used for the job's location is based on the geometry type configured in the step. Consider the following conditions when defining a job's location:

• Only features with the correct geometry type can be saved as the job's location.
• If more than one polygon or multiple line features of the correct geometry type are selected, the location is saved as a multipart feature.
• Drawing a location in the Workflow Manager web app removes any existing selections and selecting features removes drawn locations.

If Map is chosen as the location method, the following actions can be performed when the step is run:

• The job's location can be defined.
• The step can be canceled by clicking Cancel.
• The step can be finished by clicking Proceed.

If Geometry is chosen as the location method, the job's location is automatically defined when the step is run and the step completes automatically. If the geometry returned by an Arcade expression is null or invalid, the step fails. If the geometry type returns an Arcade expression that doesn't match the geometry type configured in the step, the step fails.

Configure the step

Do the following to configure the step:

1. Create or edit a workflow diagram to access the Step Library panel.
2. Drag Define Location from the Step Library panel to a connection arrow of a step on the workflow canvas.

   Learn more about adding steps to a workflow diagram

   The Step Details panel appears.

3. Provide a name for the step in the Step Name text box.
4. Optionally, add the message that you want to appear when the step is run in the User Prompt text box.

   If the user prompt contains plain text and Arcade expressions, format the text as follows:

   'This job is currently assigned to ' + JobOwner($Job) + '.'

   Tip:

   Click This input supports Arcade Expressions and choose an ArcGIS Arcade expression to add it to its associated text box.

5. Click the Geometry Type drop-down arrow and choose a geometry selection type for the job location.

   You can also use ArcGIS Arcade expressions to provide a dynamic value.

6. Choose one of the following options:
   • Map—Allow a user to define the job's location on a map.
   • Geometry—Automatically define the job's location using coordinates in Esri JSON format.
7. If you chose Map, perform these steps:
   1. Choose Location Method options as necessary:
      • Select—Select existing features on the map.
      • Draw—Create features with the drawing tools in ArcGIS Pro or the widgets in the Workflow Manager web app.
   2. In the Map section under Web Map, click Add to add the web map you want to work with in the Workflow Manager web app.

      The Define Location Step dialog box appears.

      Note:

      Web maps cannot be used to define a location in ArcGIS Pro. You must provide the name of the map you want to work with in an ArcGIS Pro project to define a location.

   3. Choose one of the following options to specify where the web map is located:
      • This Enterprise—Add a web map that is available on the same portal as Workflow Manager.
      • ArcGIS Online—Add a public web map located on ArcGIS Online.
      • Other—Add a public web map located on another portal.
   4. If you chose Other, type the URL for the portal that contains the web map in the Portal URL text box and press Enter.

      For ArcGIS Enterprise, use the format https://webadaptorhost.domain.com/webadaptorname.

   5. Type the item ID for the web map in the Item ID text box.
   6. Provide a name for the web map in the Reference Name text box.
   7. Click OK.

      The web map URL appears in the Step Details panel.

      Note:

      The web map can be edited by clicking Edit or deleted by clicking Remove.

   8. Provide the name of the map you want to work with in your ArcGIS Pro project in the ArcGIS Pro text box.
   9. Optionally, if Enable Search is configured for your web map, provide a definition query, search text, or an Arcade expression in the Search Text text box to zoom to an initial map extent when the step is run in the Workflow Manager web app.
8. If you chose Geometry, use the following examples to define the job's location using coordinates in Esri JSON format.

   You can use a string, an Arcade expression, or a combination of the two to define the location.

   Define a point location using a JSON string.

   {"x" : -118.15, "y" : 33.80, "spatialReference" : {"wkid" : 4326}}

   Define a point location using an Arcade expression.

   '{"x":' + JobOutputValue($Job, '6d3a2e62-41f3-0ca5-d14a-bf87b8e4e4ec', 'testx') + ', "y":' + JobOutputValue($Job, '6d3a2e62-41f3-0ca5-d14a-bf87b8e4e4ec', 'testy') + ', "spatialReference" : {"wkid" : ' + JobOutputValue($Job, '6d3a2e62-41f3-0ca5-d14a-bf87b8e4e4ec', 'wkid') + "}}"

   Define a point location using an Arcade expression that converts coordinates in GeoJSON to EsriJSON format.

   {GeoJsonToEsriJson(JobExtendedProperty($Job, 'assets', 'geojson'), 'Point'), "spatialReference" : {"wkid" : 4326}}

   Define a location using the shape field.

   JobExtendedProperty($Job, '<table_name>','shape')

   Note:

   The shape field is the name of the field used for obtaining the geometry from an extended properties table.

   The default spatial reference is Web Mercator Auxiliary Sphere (wkid 3857). If the geometry returned by the Arcade expression has a different spatial reference, the location is defined and the spatial reference is converted to wkid 3857.

9. Click the Options tab.
10. Configure Step Options as necessary.
    • Manual—Run the step manually.
      • Optional—Allow the step to be finished without being run.
    • Automatic—Run the step as soon as it becomes active.

      Note:

      If your workflow diagram is configured to automatically run a sequence of steps that includes the Evaluate Data Quality or the Run GP Service step, steps that attempt to run after the user token that started the sequence of steps expires will not run automatically. You must have a license for the ArcGIS Workflow Manager Server Advanced role to continue running more automated steps without manual intervention.

    • Run on a Schedule—Run the step according to a schedule you set.

      Learn more about scheduling options

11. Optionally, provide help text for the step in the Step Help text box.

    You can also use ArcGIS Arcade expressions to provide a dynamic value for the step help. If the step help contains plain text and Arcade expressions, you must format the text as follows:

    
    'For further assistance, please contact' + JobCreator($Job) + '.'

12. Optionally, click the Style tab to change the shape and color of the step.
13. Optionally, click the About tab and provide a description for the step in the Step Description text box.

    Tip:

    The About tab also contains the step's ID that can be used with dynamic job properties to obtain a step's output. Click Copy Step ID to copy the step ID to your clipboard.

Return value

When the step is completed, its return value is stored to indicate the result of the step. The return value can be immediately evaluated using paths to determine the next steps in the workflow. You can also retrieve the return value for completed steps throughout the workflow using ArcGIS Arcade expressions. The following table lists the step's return values:

Return value	Description
S000001	The step completed successfully.
F000001	The step failed to complete successfully.

Output value

When the step is completed, its output value is stored and can be used to determine the path the workflow follows or can be used as inputs for other steps throughout the workflow. The following table lists the step's output value:

Output	Description
<Location>	Returns the location that was defined.