Advanced Action Handlers

Action Handlers provide a way to extend the reconcile and post process performed by GDBM XI with configurable and customizable actions. GDBM XI runs custom business logic or out-of-the-box action handlers that are configured based on your organization’s needs. Action handlers are implemented as webhooks, a real-time HTTP-based API that allows GDBM XI to quickly inform other systems of versions being processed, including responding to behaviors from those systems when appropriate.

There are three types of action handlers:

1. Fire and Forget: Intended for portions of business logic where only a notification of the process happening is required. Reconcile or post process does not need a response back from the action handler. Fire and Forget examples include logging- or notification-type action handlers.

2. Immediate Response: Used for cases that require little processing, but the processing results can impact whether the reconcile or post process for a version should continue. By using an ActionHandlerCompleted response body for this action handler type, GDBM XI can react appropriately.

   The following is an ActionHandlerCompleted example:

   {
       "workflowSessionId": "9a3268df-a535-46ea-b420-0af739a82c8b",
       "orchestrationId": "d2ef08b7-5d43-42bb-9653-741049f802b4",
       "actionHandlerName": "My Action Handler",
       "success": false,
       "errorMessage": "Action Handler failed for reason XYZ."
   }

   • workflowSessionId: The Azure Service Bus uses this ID internally for message ordering. This property is needed when putting a message on Azure Service Bus back to GDBM XI. The WorkflowSessionID comes from the ActionPayload, which is received by your action handler via HTTP and should not be changed.

   • orchestrationId: This ID is the unique schedule processing ID of the version. Each independently configured schedule has its own unique ID, which is derived from the ActionPayload. The ActionPayload is received by your action handler via HTTP and should not be changed.

   • actionHandlerName: This is used internally for logging and should be something recognizable.

   • success: This Boolean return value indicates whether the action handler was successful in processing. This instructs GDBM XI to stop processing (if false) or continue (if true) when you have an action handler of a type other than Fire and Forget. This also determines if further action handlers or processing for a version should continue. If your action handler should not impact the process and further action handlers and actions, return true or consider using the Fire and Forget response type.

   • errorMessage: This sizeable text field documents why an action handler is unsuccessful and is logged as part of the GDBM XI process.

   The following is an ActionPayload:

   {
       "workflowSessionId": "6d5067c6-a450-49d6-80e9-806a0723ac98",
       "featureServiceUrl": "",
       "tenantId": "EditorTest",
       "arcFmSessionId": "889ce9a0-e9ee-4e7d-b271-cd2a73aa4eaa",
       "orchestrationId": "21a9658c-99d7-4a02-a680-6d6f1837f575",
       "action": 0,
        "versionID" : "8887553a-001f-4033-8bde-4af855505b49", 
       "versionName": "testUser.SN_78AFCD",
       "properties": {
           "recipient": "daniel.rouleau@se.com",
           "subject": "test"
       }
   }

   • workflowSessionId: The Azure Service Bus uses this ID internally for message ordering. This property is needed when putting a message on Azure Service Bus back to GDBM XI. The WorkflowSessionID comes from the ActionPayload, which is received by your action handler via HTTP and should not be changed.

   • orchestrationId: This ID is the unique schedule processing ID of the version. Each independently configured schedule has its own unique ID, which is derived from the ActionPayload. The ActionPayload is received by your action handler via HTTP and should not be changed.

   • versionId: This ID is assigned by Esri as the GUID of the version.

   • versionName: This is used to name the Esri version.

   • featureServiceUrl: This is the feature service that manages the version being processed.

   • arcFMSessionId: This contains the ID of the session If the version is associated with Session Manager (optional).

   • tenantId: This is your organization name and is used primarily for out-of-the-box action handlers. This is also useful for distinguishing between environments (dev, test, or prod).

   • action: This is the enumeration value for the action that is currently running (e.g., BeforeReconcileLoop, AfterReconcile, etc.).

   • properties: These custom properties are defined in Solution Center and are passed to the Action Handler.

3. Service Bus Response: Intended for the most complex scenarios that require additional processing beyond the typical web request timeout allowance. Examples of service bus response action handlers are UpdateSubnetwork and ValidateNetworkTopology. Since both operations run longer than others, the GDBM XI process starts the action handler and pauses the process until notified via Azure Service Bus that the process has completed.

   TIP: GDBM XI times out after waiting two minutes for an action handler response. After two minutes, it’s assumed the action handler failed and it’s marked as such.

GDBM XI action handlers use hash-based message authentication codes (HMACs) for message signatures, using the SHA-256 hashing function and a customer-defined cryptographic key (configured on the Settings tab). This allows action handlers to validate message authenticity and the integrity of the message contents. Out-of-the-box action handlers that pertain to ArcGIS Enterprise and accessing versions use a configured named user and Azure Relay to access ArcGIS Enterprise securely.