Documentation Center

Variables inside the background task configuration

Referencing environment variables inside the background task configuration is useful when exact configuration value varies from server to server and therefore cannot be single-sourced. Environment variables are resolved at the moment background task service is being initialized with the actual values set on that specific server.

Using variables

Normally, a background task gets its parameters from the background task configuration. This way the background task parameters are defined in a single place and can be easily accessed by the task regardless of which server or service executes it. Sometimes, however, it is not easy (or even possible) to provide a value that would work on every server. The typical case is the file path, which may differ from one server to another. For example, the PUBLICATIONEXPORT event type needs to know the export location, which can be a different folder depending which server picks up the task.

To solve this problem, background task configuration allows referencing environment variables. Environment variable can be provided as a value of any element or attribute. The easy way to set the environment variables for the lifetime of the background task service is to add them to the background task service's appsettings.json file. When the background task service is being initialized, every environment variable is replaced with the actual value.

Environment variable values for BackgroundTask handlers

In the appsettings.json file, configure variables in the variables element within the BackgroundTask section. Background task service will read these values during initialization and use them to set the actual environment variables.

The following example shows how to provide environment variable values within the background task service configuration file:

{
  "BackgroundTask": {
    "Variables": {
      "ISHPROJECTAPPPATH": "C:\InfoShare\App",
      "ISHPROJECTDATAPATH": "C:\InfoShare\Data",
      "ISHPROJECTWEBPATH": "C:\InfoShare\Web",
      "JAVA_HOME": "C:\\EclipseTemurinOpenJDK\\jdk-17+35"
    }
  }
}

Variable references in a BackgroundTask handler

The following example shows within the XML configuration how to provide the PUBLICATIONEXPORT references %ISHPROJECTDATAPATH% in the value of exportlocation and exportspeclocation parameters:

<handler eventType="PUBLICATIONEXPORT">
      <scheduler executeSynchronously="false" />
      <authorization type="authenticationContext" />
      <execution timeout="01:00:00" recoveryGracePeriod="00:10:00" isolationLevel="None" />
      <activator>
        <net name="ExportObjects">
          <parameters>
            <parameter name="exportlocation">%ISHPROJECTDATAPATH%\ExportService\Data\DataExports</parameter>
            <parameter name="exportspeclocation">%ISHPROJECTDATAPATH%\ExportService\Data\WatchFolder</parameter>
            <parameter name="separatelng">yes</parameter>
            <parameter name="requestedmetadata">
              <ishfields>
                <ishfield name="FSTATUS" level="lng" />
              </ishfields>
            </parameter>
            <parameter name="raiseevent">ZIPFILES</parameter>
            <parameter name="filenameprefix">
              <ishfields>
                <ishfield name="FTITLE" level="logical" />
              </ishfields>
            </parameter>
          </parameters>
        </net>
      </activator>
     <errorHandler maximumRetries="0" />
</handler>