This functionality requires the Advanced Server role license for ArcGIS Enterprise
Have you ever needed an easy way to determine what changes someone has made to a feature service in your ArcGIS Enterprise organization? I think a lot of GIS professionals would answer yes to that question. Now, what about using the information on what changed to automatically drive your organizational workflows forward without user input? That sounds more interesting, right?
Let’s start with some basics. What is a feature service webhook? Well, feature service webhooks allow you to subscribe to specific event triggers associated with feature services. For example, a webhook could be invoked when a new feature is created, or a feature is updated. Feature services have a capability called change tracking, which allows applications to easily track changes made to the layers and tables in a service. How do you get those changes? Using something called extract changes. The extract changes operation is used to retrieve changes so they can be displayed to the user. We should note that, at the time of this writing, feature service webhooks are supported with either hosted feature services or non-versioned referenced feature services. Reference more webhook prerequisites here.
How does Workflow Manager fit into this? At the 11.0 release, Workflow Manager introduced the ability to create jobs using webhooks. This meant that organizational processes such as updating or closing a work order in Cityworks, for example, could trigger a job to be created in Workflow Manager. Or if a new feature was created in a feature service, a job could be created in Workflow Manager to do some work. At the 11.1 release, we added the ability to capture the extracted changes in your output values for use in Workflow Manager jobs. Let’s take a look at a real-world example to see how this could work.
Note: At the time of this blog’s publishing date, webhook job creation in Workflow Manager is only available in ArcGIS Enterprise.
Set up
As a health and safety expert in your organization, you are concerned about hazards on work sites and their impacts on employee safety. As a result, you’ve developed a workflow in Workflow Manager to allow field workers to report hazards as they observe them and then create a job to effectively mitigate those hazards.
The workflow is fairly simple: a series of question steps ask whether field mitigation of the hazard is required, or GIS updates are needed, then a supervisor reviews steps along the way. The field workers are using ArcGIS Field Maps to submit their observations with a simple form as shown below:
The field worker can capture responses for these entries in Field Maps and use them to automatically populate certain steps or the workflow path can be directed without any user input.
For the webhooks side of things, some pre-work must be done to enable change tracking on your feature service. Once done, we can create a webhook receiver in Workflow Manager. This is done in the job template on the Automated Actions tab.
Creating the webhook receiver is fairly simple: enter authorization information, choose to attach the webhook payload as an attachment on the job, and configure outputs. In this case, we must check the Extract Changes check box to ensure changes are added as output values for the job.
Once complete, the changes can be saved, and the URL can be copied for the next step.
At this point, the webhook can be created in ArcGIS Server. We’ll use the URL copied from Workflow Manager as an input in this process.
With these steps complete, let’s see feature service webhooks and extract changes in action in Workflow Manager.
Job creation and use of extract changes
In ArcGIS Field Maps, a new hazard issue is recorded and submitted.
In Workflow Manager, a job is created and the first step runs automatically for us to review the submission.
In this workflow, we’ve used the output values from extract changes to insert text into the first step for the job’s assignee to review and determine if this is a valid submission or not.
These output values are found in the jobActionOutputs table in the hosted layer.
Note: You must have output values configured on the webhook in order for these entries in jobActionOutputs to be present. If you’re not sure how to configure the output values for your webhook request body, you can view the documentation for the endpoint or configure the webhook to attach the payload to the job and fire off a test, where you can then use that information to configure the output values.
The raw extract changes payload is attached to the job as well since we specified that during webhook receiver creation.
Note: The first step in your workflow must be run before the extract changes attachment is added to the job. If the first step is a manual step, you will need to run that step in order to see the second attachment on the job.
In this case, the review process is manual, but the workflow could be automated to direct the job down a certain path depending on the output values of the extract changes. For example, say you wanted a high priority submission to go down one path and all others go down a different path. This could be automated at the start of a workflow without a user needing to review it. We’ll review an example of how this could work later in the blog.
Other steps in this workflow also use the output values from extract changes in order to automatically populate information without user input during the job.
The Send Email steps utilize Arcade to pull information from the extract changes’ output values to dynamically display information that is relevant to the email recipient. You can start to see how extract changes can be valuable when working with feature service webhooks in Workflow Manager. We won’t go through this entire workflow in this blog but let’s take a look at the automated workflow example mentioned earlier to see how these extract changes output values can be used there.
Additional automation capabilities with extract changes output values
As mentioned earlier, the workflow above had a manual review process and used the extract changes’ output values as inputs to steps to produce dynamic text for each submission and job. Another use-case for extract changes’ output values is to use them to drive the workflow one direction or another. In the following example, we can direct the workflow down a path determined by the priority level of the Field Maps submission.
This has the potential to run parts of this workflow completely hands off. When the Field Maps submission is received, the Start Job step will run automatically. If the priority level is a value other than High, an email can be automatically sent to the submitter notifying them that the job will be closed, and the job closed without a user ever touching Workflow Manager.
Wrapping Up
Hopefully, you can start to see the use for feature service webhooks and extract changes in your own organizational workflows. In this blog, we discussed an example of a health and safety expert looking for ways to allow employees to report hazards and have the right people in the organization notified of those hazards to begin mitigation steps. We showed how you could use ArcGIS Field Maps to submit a form for hazard reporting and then use webhooks in ArcGIS Workflow Manager to automatically create jobs upon submission of the form. We showed how the changes from the feature service could then be used as part of a job in Workflow Manager to convey information, automatically populate inputs, or automatically drive workflows forward.
Being able to automatically use the information on the changes that were made to help drive your organizational workflows forward without user input can be very powerful, saving you time, increasing trust in organizational workflows, and automating otherwise tedious manual processes. If you’re already using webhooks in Workflow Manager, try adding in the extract changes option to see what impact it could have on your workflows.
We’d love to hear your feedback on this functionality or any other Workflow Manager related things. If you’re new to webhooks or Workflow Manager, check out our resources below to get started.
Learn More
- Check out our ArcGIS Workflow Manager resources blog to learn more.
Article Discussion: