Monitor > Process Server Configuration > Dispatch Service
  

Dispatch Service

Use the dispatch service to create dispatch configurations that throttle requests made to Process Server.
The requests could be HTTP/S messages, message events, or other Transport Layer Security (TLS) requests. You can queue requests, dispatch requests in batches, and control the maximum number of requests that run concurrently.
For example, you have a frequently used process that quickly dispatches asynchronous requests to Process Server. At runtime, if thousands of these requests execute simultaneously, the result can overwhelm the server and the service being invoked. Use the dispatch service to send requests in batches and to ensure that only a few requests are processed at the same time.
You can use the dispatch service for services that run on the Secure Agent. You cannot use the dispatch service for services that run on the cloud server.
Create a dispatch configuration for a service or process group. At runtime, Application Integration chooses the dispatch configuration in the following order of preference:
  1. 1Service Name
  2. 2Process Group
  3. 3System Default
For example, the service processA_event1 has the following dispatch configurations that apply to it:
When Process Server executes processA_event1, the processA_event1 dispatch configuration applies.
The dispatch service applies to all requests except for subprocess invokes that contain boundary events. For example, if a subprocess step contains a message event, the dispatch service will not apply to the subprocess.
However, if you use a service call step to add a subprocess, the dispatch applies to all subprocess configurations, including subprocesses with boundary events.

Default and Custom Dispatch Services

Process Server has default dispatch services.
The following table shows the default dispatch services and their purpose:
Default Dispatch Service
Purpose
SystemDefault
Applies to all services.
avBusinessConnectionRESTService
Applies to service connectors.
avCreateAnyEntityService
Enables the host runtime to PUT records using a database connection.
avDeleteAnyEntityService
Enables the host runtime to DELETE records using a database connection.
avHostEnvironmentRuntimeAccess
Enables the host runtime to access records using a database connection.
avHostRuntimeCall
Enables the host runtime to GET records using a database connection.
avProxyToProcess
Enables a process to call other processes as a services.
jmsEnqueueService
Applies to the JMS automated step.
sfHostEnvironmentRuntimeService
Enables the host runtime to access a Salesforce database using a Salesforce connection.
To create a custom dispatch configuration, go to Server Configuration and select a Secure Agent. Then, go to Queues > Dispatch Queue.

Dispatch Service Components

The dispatch service uses the concurrent pool and the in-memory and persistent queues to control the flow of requests to Process Server.
The dispatch service uses the following pool and queues:
Concurrent Pool
The concurrent pool stores requests that Process Server processes at the same time. The number of listeners available to process requests depends on the Max Concurrent value.
In-Memory Queue
The in-memory queue stores requests in the dispatch service memory. The dispatch service moves requests into the in-memory queue when the Max Concurrent value has been reached.
When the concurrent pool has space, requests move from the in-memory queue to the concurrent pool.
You loose requests in the in-memory queue if the Secure Agent restarts unless you enable persistence.
Persistent Queue
The persistent queue stores in-memory queue requests if you enable persistence. The persistent queue holds requests in the database.
Requests move from the persistent queue to the concurrent pool when a listener frees up.
If the Secure Agent restarts and requests are only in the in-memory queue and not in the persistent queue, the requests are lost.
The following image shows how the dispatch service throttles requests:
This image shows how requests move through the dispatch service.
For more information, see the Sample Dispatch Configurations.

Creating a Custom Dispatch Configuration

Perform the following steps to create a custom dispatch configuration:
  1. 1Log in to Application Integration Console.
  2. 2Go to Server Configuration and select a Secure Agent.
  3. 3Go to Queues > Dispatch Queues > Add.
  4. 4In the New Dispatch Queue dialog box, configure properties and then click OK.
The following image shows a sample New Dispatch Queue dialog box for the 00000S service:

Dispatch Service Configuration

Configure the following properties to create a custom dispatch configuration:
Property
Description
Name
The name of a service definition.
To view a service definition name, go to Processes > Select Process Version Number > My Role > Service column.
For example, in the following My Role section of the Deployed Process Version Details page, the service name is 0BQGwyKeJVBie6UGrJHaqI/Print_Hello_World-1:
If you enter a service definition name, the dispatch configuration governs all instances of the service, regardless of the process that contains the service.
You cannot change the name of a saved dispatch configuration. To edit the name, delete the dispatch configuration and then create a new one.
Max Concurrent
The maximum number of requests that Process Server can hold in the concurrent pool.
Default: 15.
Max In-Memory
The maximum number of requests that Process Server can hold in the in-memory queue.
If you enable persistence, the dispatch service rejects requests that exceed the Max Queued value.
If you do not enable persistence, the dispatch service rejects requests that exceed the Max In-Memory value.
Default: 300.
Max Queued
The maximum number of requests in the persistent queue.
If you enable persistence, the dispatch queue service rejects requests that exceed the Max Queued value.
If you do not enable persistence, the dispatch service rejects requests that exceed the Max In-Memory value.
Default: 300.
Timeout (seconds)
The maximum amount of time, in seconds, that a single request can take to execute within the dispatch service.
If a request takes longer that the timeout value to execute, it moves out of the dispatch service and the next pending request executes.
If a request times out of the dispatch service, Process Server continues to execute outside of the dispatch configuration. As a result, you might see different values on the Processes list and the Server Configuration > Queues > Dispatch Queue list.
Default: 300 seconds.
Persistent
Select the Persistent option to save pending requests to the persistent queue. If you select this option and the Secure Agent restarts, the dispatch configuration continues to execute queued requests.
If you do not select the Persistent option, pending requests are saved only in the in-memory queue and are lost if the Secure Agent restarts.
Default: Not selected.
For information about how you can use these properties to throttle requests, see the Sample Dispatch Configurations.

Monitoring a Dispatch Configuration

Use the Dispatch Queue page to monitor dispatch configurations
The following table describes the columns that on the Dispatch Queue page:
Column
Description
Name
The dispatch configuration name.
Executing
The number of requests running under the dispatch configuration.
Queued
The number of requests queued by the dispatch configuration.
Requests move from Queued to Executing when any of the following events occur:
  • - A request completes.
  • - A request times out.
  • - A request moves out of the queue because you purged queued requests.
Average Time (ms)
The average time, in milliseconds, for which a listener in the concurrent pool works on a request.
Consumed
The number of requests that have passed through the dispatch configuration. This number does not include rejected messages.
Rejected
The number of requests that were rejected by the dispatch configuration.
This number does not include timed out requests. For details, see Timeout (Seconds).
Status
The status of the dispatch configuration.
A dispatch configuration can be in the following states:
  • - Active: The dispatch configuration is running and can send queued requests to Process Server.
  • - Suspended: The dispatch configuration is paused. Pending queued requests remain in the queue until dispatch configuration is resumed.
  • - Pending Delete: There are queued requests that need to be consumed. If you see this status, delete the dispatch configuration and refresh the browser.
The following table describes the actions that you can take on one a dispatch configuration:
Action
Description
Reset Statistics
Sets the Executing and Average Time (ms) values to zero.
Suspend Execution
Stops sending requests to Process Server. Requests remain in a queue until you resume the dispatch configuration.
Resume Execution
Resumes dispatching new requests to the engine.
Purge Queued Requests
Deletes all pending requests from the in-memory queue and the persistent queue. Process Server does not execute these requests.
Use this action in unusual circumstances that require clearing the queue.
Delete Configuration
Removes the dispatch configuration. The status will be Pending Delete until you refresh the browser.
Requests do not go to Process Server after you select Delete Configuration. If there are queued requests, the configuration is removed after all requests are consumed.

Sample Dispatch Configurations

This section contains an explanation of some sample dispatch configurations.
Example 1. Example 1
The following table shows a sample dispatch configuration:
Property
Value
Max Concurrent
15
Max In-Memory
200
Max Queued
1000
Timeout (seconds)
55
The dispatch configuration receives 10,000 requests.
The following table describes the events that occur when each request takes 50 seconds or 60 seconds, and if persistence is enabled or not enabled:
Persistence/Time Taken per request
50
60
Not Enabled
  • - Every 50 seconds, 15 requests move from the Queued column to the Executing Column.
  • - The dispatch service processes 200 requests and rejects 9800 requests. Process Server does not execute the rejected messages.
  • - All 200 requests are successfully processed because the Timeout value is higher than the time taken to complete a request
  • - The value in the consumed column is 200 and the value in the rejected column is 9800.
  • - If the Secure Agent restarts before 200 requests are processed, queued requests are lost because they were saved to the in-memory queue and not to the persistent queue.
  • - Every 55 seconds, 15 requests move from the Queued column to the Executing Column. This is because the Timeout value is lower than the time that a request takes to complete.
  • - The dispatch service processes 200 requests and rejects 9800 requests. Process Server does not execute the rejected messages.
  • - The 200 requests do not complete within the purview of the dispatch service because the Timeout value is lower than the time taken to complete a request. Process Server continues to execute the timed-out messages after the messages leave the dispatch service.
  • - The value in the consumed column is 200 and the value in the rejected column is 9800.
  • - If the Secure Agent restarts before 200 requests are processed, queued requests are lost.
Enabled
  • - Every 50 seconds, 15 requests move from the Queued column to the Executing Column.
  • - The dispatch service processes 1000 requests and rejects 9000 requests. Process Server does not execute the rejected requests.
  • - The dispatch service processes 1000 requests successfully because the Timeout value is higher than the time taken to complete a request.
  • - The value in the consumed column is 1000 and the value in the rejected column is 9000.
  • - If the Secure Agent restarts before 1000 requests are processed, pending requests execute after the restart. This is because requests were saved to the persistent queue.
  • - Every 55 seconds, 15 requests move from the Queued column to the Executing Column. This is because the Timeout value is lower than the time that a request takes to complete.
  • - The dispatch service processes 1000 requests and rejects 9000 requests. Process Server does not execute the rejected requests.
  • - The 1000 requests do not complete within the purview of the dispatch service because the Timeout value is lower than the time taken to complete a request. Process Server continues to execute the timed-out messages after they leave the dispatch service.
  • - The value in the consumed column is 1000 and the value in the rejected column is 9000.
  • - The value in the consumed column is 200 and the value in the rejected column is 9800.
  • - If the Secure Agent restarts before 1000 requests are processed, pending requests execute after the restart. This is because requests were saved to the persistent queue.
Example 2. Example 2
The following table shows a sample dispatch configuration:
Property
Value
Max Concurrent
4
Max In-Memory
20
Max Queued
10
Timeout (seconds)
7
The dispatch configuration receives 50 requests.
The following table describes the events that occur when each request takes 50 seconds or 60 seconds, and if persistence is enabled or not enabled:
Persistence/Time Taken per request
5
10
Not Enabled
  • - Every 5 seconds, 4 requests move from the Queued column to the Executing Column.
  • - The dispatch service processes 20 requests and rejects 30 requests. Process Server does not execute the rejected requests.
  • - The dispatch service successfully processes 20 requests because the Timeout value is higher than the time taken to complete a request
  • - The value in the consumed column is 20 and the value in the rejected column is 30.
  • - If the Secure Agent restarts before 20 requests are processed, queued requests are lost because they were saved to the in-memory queue and not to the persistent queue.
  • - Every 7 seconds, 4 requests move from the Queued column to the Executing Column.
  • - The dispatch service processes 20 requests and rejects 30 requests. Process Server does not execute the rejected requests.
  • - The 20 requests do not complete within the purview of the dispatch service because the Timeout value is lower than the time taken to complete a request. Process Server continues to execute the timed-out messages after they leave the dispatch service.
  • - The value in the consumed column is 20 and the value in the rejected column is 30.
  • - If the Secure Agent restarts before 20 requests are processed, queued requests are lost because they were saved to the in-memory queue and not to the persistent queue.
Enabled
  • - Every 5 seconds, 4 requests move from the Queued column to the Executing Column.
  • - The dispatch service processes 20 requests and rejects 30 requests. Process Server does not execute the rejected requests.
  • - The dispatch service successfully processes 20 requests because the Timeout value is higher than the time taken to complete a request
  • - The value in the consumed column is 20 and the value in the rejected column is 30.
  • - If the Secure Agent restarts before 30 requests are processed, pending requests execute after the restart. This is because requests were saved to the persistent queue..
  • - Every 7 seconds, 4 requests move from the Queued column to the Executing Column.
  • - The dispatch service processes 20 requests and rejects 30 requests. Process Server does not execute the rejected requests.
  • - The 20 requests do not complete within the purview of the dispatch service because the Timeout value is lower than the time taken to complete a request. Process Server continues to execute the timed-out requests after the requests leave the dispatch service.
  • - The value in the consumed column is 20 and the value in the rejected column is 30.
  • - If the Secure Agent restarts before 30 requests are processed, pending requests execute after the restart. This is because requests were saved to the persistent queue.

Troubleshooting the Dispatch service

When you use the dispatch service, you might face situations where you are unable to move forward.

The number of requests in the Executing column of the Request Dispatch Service page is different from the number of processes running on the Active Processes page. I'm sure that my requests have not timed out.

Potential Reason: You have invoked a process that calls a subprocess.
Potential Solution: On the Deployed Process Version Detail page, change the Persistence Type setting for the process and subprocess and retry the process invoke.
Toggle between persistent (Full or Persist) and non-persistent (Final, Brief, or None) settings

I invoked a process 5 times but I see hundreds of requests in the Queued column. These requests are moving slowly and I think my Secure Agent is going to crash.

Potential Reason: You have invoked a process that calls a subprocess that in turn calls a subprocess. This layering might go deep.
Potential Solution: Create multiple dispatch services for the different sub processes that your process calls. Each dispatch configuration runs and throttles services individually, which speeds up service execution.

Additional Controls Related to the Dispatch Service

As you monitor dispatch services, you can use other configuration settings to help monitor and manage an overflow of requests to Process Server. If there appear to be issues, it could be because the dispatch service's Max Queued value is being exceeded.
Use the following commands to determine if requests are being rejected: