AppSettings Configuration

Here, we'll go over the JSON configuration options available in the appSettings.json file.

{
  "JobFlow": {
    "Messaging": {
      "Connections": {
        "ServiceBusQueue": {
          "ConnectionStringName": "SB"
        },
        "AnotherRedis": {
          "Type": "Redis",
          "ConnectionStringName": "Redis2"
        }
      },
      "Transports": {
        "Defaults": {
          "Connection": "Redis"
        },

        "ValidatePayment": {
          "Name": "validate-payment",
          "Connection": "Hangfire"
        },
        "CreatePayment": {
          "Name": "create-payment"
        },
        "RingBell": {
          "Name": "ring-bell"
        },
        "SendEmail": {
          "Name": "send-email",
          "Connection": "AnotherRedis"
        },
        "JobSchedule": {
          "Name": "job-schedule",
          "Connection": "ServiceBusQueue"
        }
      }
    },
    "Documents": {
      "MaxConcurrencyRetries": 10,
      "Storage": {
        "Redis": {
          "TTL": "00:10:00"
        },
        "AZ1": {
          "Type": "AzureStorage",
          "ConnectionStringName": "AzureStorage"
        }
      },
      "DefaultStorage": {
        "WorkItems": "Redis",
        "Attachments": "Redis"
      }
    }
  },
  "ConnectionStrings": {
    "Redis": "RedisConnectionString",
    "Redis2": "Redis2ConnectionString",
    "AzureStorage": "AzureStorageConnectionString",
    "SB": "ServiceBusConnectionString"
  }
}

All the JobFlow options go under the "JobFlow" key, though you are free to name the section whatever you'd like. It is processed using the AddConfiguration extension method on the JobFlowConfigurationBuilder. See JobFlowConfigurationBuilderExtensions for more information about loading the configuration.

Messaging Options

"Messaging": {
  "Connections": {
    "ServiceBusQueue": {
      "ConnectionStringName": "SB"
    },
    "AnotherRedis": {
      "Type": "Redis",
      "ConnectionStringName": "Redis2"
    }
  },
  "Transports": {
    "Defaults": {
      "Connection": "Redis"
    },

    "ValidatePayment": {
      "Name": "validate-payment",
      "Connection": "Hangfire"
    },
    "CreatePayment": {
      "Name": "create-payment"
    },
    "RingBell": {
      "Name": "ring-bell"
    },
    "SendEmail": {
      "Name": "send-email",
      "Connection": "AnotherRedis"
    },
    "JobSchedule": {
      "Name": "job-schedule",
      "Connection": "ServiceBusQueue"
    }
  }
},

This section is split into two parts.

Connections

"Connections": {
  "ServiceBusQueue": {
    "ConnectionStringName": "SB"
  },
  "AnotherRedis": {
    "Type": "Redis",
    "ConnectionStringName": "Redis2"
  }
},

In here, we describe the external connections used by the transports. Each item in here is treated as a separate, unique connection even if the same connection string (and thereby, the same server) is used.

Each item can contain:

Type - the server type, as defined by the transport types added in the configuration (i.e. Redis, ServiceBusQueue, etc.). If not set, the name of the connection item is used instead - for example, "ServiceBusQueue" is used for the type in the first defined connect.
ConnectionStringName - the connection string to use. This also defaults to the name of the connection item as well.

As an example, say a Transport (discussed below) is configured to use the "Redis" connection. Since that connection is not explicitly defined, the following defaults would be used:

"Redis": {
    "Type": "Redis",
    "ConnectionStringName": "Redis"
}

As another example, if the "ServiceBusQueue" connection is referenced, the following data is used:

"ServiceBusQueue": {
    "Type": "ServiceBusQueue",  // defaults to the item name
    "ConnectionStringName": "SB
}

Transports

  "Transports": {
    "Defaults": {
      "Connection": "Redis"
    },

    "ValidatePayment": {
      "Name": "validate-payment",
      "Connection": "Hangfire"
    },
    "CreatePayment": {
      "Name": "create-payment"
    },
    "RingBell": {
      "Name": "ring-bell"
    },
    "SendEmail": {
      "Name": "send-email",
      "Connection": "AnotherRedis"
    },
    "JobSchedule": {
      "Name": "job-schedule",
      "Connection": "ServiceBusQueue"
    }
  }
},

This is the section that describes the transport mechanisms used to dispatch jobs to workers. It essentially defines how to access the queues (or other communication mechanisms).

The Defaults transport are settings that will be used if no named settings exist elsewhere in the section.

Name - the "container" name within the Transport - a queue name, for example. If Name is not specified, then the Transport name itself ("ValidatePayment", for instance) is used instead.
Connection - the name of the connection configuration to use. This has no default and therefore will throw an error if not set. However, it can be set "globally" using the "Defaults" configuration item.

If we look at the CreatePayment section as a first example, we see Name is the only setting. In this case, the Connection from the Default section is used. In essence, the end result would be:

"CreatePayment": {
    "Name": "create-payment",
    "Connection": "Redis"
}

Taking a look at JobSchedule, we see that each item is set, override all defaults. Note that JobSchedule is a system-defined, required Transport. See the System Defined Transport Names section below.

If a Transport is requested, but there is no explicit section defined for it, the Default section is used for everything. In this case, as stated above, the requested Transport name is used for the "container" name. For instance, is the Transport "ReportPayment" is requested, the effective configuration will look like:

"ReportPayment": {
    "Name": "ReportPayment",
    "Type": "Redis"
}

System Defined Transport Names

While most Transports are defined with the user-defined rules, there are some Transports that the core system uses. The names are defined in SystemConstants

As stated in the previous section, if those Transports are not explicitly defined in the configuration, then the Default settings are used for each.

Important

The JobSchedule Transport must support scheduling. In other words, the Transport must have the Scheduling flag set from TransportOptionFlags. If that flag is not set for the Transport, an application configuration validation exception will occur.

Document Options

  "Documents": {
    "MaxConcurrencyRetries": 10,
    "Storage": {
      "Redis": {
        "TTL": "00:10:00"
      },
      "AZ1": {
        "Type": "AzureStorage",
        "ConnectionStringName": "AzureStorage"
      }
    },
    "DefaultStorage": {
      "WorkItems": "Redis",
      "Attachments": "Redis"
    }
  }
},

DocumentOptions

Configures document and storage options.

Storage Configuration

"Storage": {
  "Redis": {
    "TTL": "00:10:00"
  },
  "AZ1": {
    "Type": "AzureStorage",
    "ConnectionStringName": "AzureStorage"
  }
},

StorageOptions

Configuration for the document storage. Each section defines a particular storage location, which is configured in the FlowDefinition in the application or plugin Startup class. For example, to use the "AZ1" storage for a particular item, the following configuration would be used:

c.ConfigureFlowDefinitions(c =>
{
    c.Add<DoorbellPressedMessage>("Doorbell", new Core.Flows.FlowDefinitionSettings
    {
        StorageTypeNames = new()
            { { SystemDocumentCollection.WorkItems, "AZ1" },
            { SystemDocumentCollection.Attachments, "Redis" } }
    });
});

This configuration would store all core WorkItem documents in the "AZ1" storage (which is configured to use Azure Storage) and all other attachments in Redis.

Default Storage

"DefaultStorage": {
  "WorkItems": "Redis",
  "Attachments": "Redis"
}

If no storage is explicitly specified for a particular Flow definition (as seen above), then the default storage is used. This section defines which storage to use as the default.

One can get away without defining a default if only one type of storage system is added during the JobFlow configuration. If multiple systems are added, then a default must be defined (a ConfigurationException will occur).

Table of Contents