What does the background process do?

The Background Processor enables the handling of the following functions associated with the use of the Akumina Forms:

• Triggering of workflow of Form Submissions (Workflow options - All stages)
• Sends email notifications of Form Submissions (Notification option)
• Creation of Form Submission Data exports and emailing of links to the form submission exports
• Flushes Cache around Form Submission Counts when a new Form Submission exists

SMTP configuration

Set the following values in the interchange.settings.config file. This is required for Emailing of Form Submission – Notification option, and sending emails with links to the Form Submission Data Exports.

<add key="akumina:SMTPHost" value="" />

<add key="akumina:SMTPUser" value="" />

<add key="akumina:SMTPPassword" value="" />

<add key="akumina:SMTPPort" value="" />

Generating an Encrypted Password

If Key Vault is not being used, then the following is a method to generate an encrypted password.

Execute the following command:

Akumina.Interchange.BackgroundProcessor.exe encrypt myplaintextpassword > encryptedpassword.txt

 

Contents of encryptedpassword.txt,  the value goes into interchange.settings.config

Configuration Options

There are four options for configuring the Background Processor:

1. Within the local interchange web context
   • Does not use Console App
   • Configuration Handled within interchange.settings.config only
2. Azure Web Jobs
   • Uses Console App
   • Configuration Handled within both the App.config and interchange.settings.config
3. Scheduled Task
   • Uses Console App
   • Configuration Handled within both the App.config and interchange.settings.config
4. OAUTH Tokens
   • Uses Console App
   • Configuration Handled within both the App.config and interchange.settings.config

*Note: If Interchange is running as an Azure WEB site, you must use the keyVault password mode, see below for interchange.settings.config key/values

IMPORTANT: The “BackgroundUser” user specified below MUST have one of the following permissions levels so that it can read/write to the required forms lists: Site Collection Adminstrator for the Site Collection – in this case the user will have full access and does not need to be added to any other groups Owner on the Parent Site if all subsites inherit permissions from the Parent site. Owner on the Parent Site and EACH subsite if the subsites break inheritance and use unique permissions interchange.settings.config file

<!-- establish the Forms Processing Site Collection to be used with the background processor -->

  <add key="akumina:FormsProcessingSiteCollection"value="https://**.sharepoint.com/sites/****" />

<!-- this is the SHAREPOINT user who initiates the background process calls -->

  <add key="akumina:BackgroundUser" value="user@tenant.onmicrosoft.com" />

  <!-- set this encrypted password, see documentation on how generate the encrypted value from your actual password, this key is NOT used if you set BackgroundPasswordMode to keyvault  -->

  <add key="akumina:BackgroundPassword" value="password from backgroundprocessor.exe console app" />

  <!-- submission tracker key needs to match whatever you set in the background processor configuration, if you are using EnableLocalSubmissionsTracker to true, the SubmissionTrackerKey set once to a RANDOM GUID -->

  <add key="akumina:BackgroundProcessorKey" value="GUID INPUT HERE"/>

  <!-- This needs to be set to true for Forms functionality if you are not setting up the background processor from AzureWeb Jobs or a Scheduled Task, the Interchange website will handle the background process -->

  <add key="akumina:EnableLocalSubmissionsTracker" value="true"/>

  <!-- possible settings are protecteddata or keyvault - if you are using keyvault please see documentation on how to set this up, keyvault is required if you are using Azure WEB instance with an External background processor – possible values: protecteddata/keyvault -->

  <add key="akumina:BackgroundPasswordMode" value="protecteddata"/>

 

*Note: If Interchange is running as an Azure WEB site, you must use the keyVault password mode, see below for interchange.settings.config key/values

IMPORTANT: The “BackgroundUser” user specified below MUST have one of the following permissions levels so that it can read/write to the required forms lists: Site Collection Adminstrator for the Site Collection – in this case the user will have full access and does not need to be added to any other groups Owner on the Parent Site if all subsites inherit permissions from the Parent site. Owner on the Parent Site and EACH subsite if the subsites break inheritance and use unique permissions App.config file

<!-- this is the your Interchange URL -->

<add key="akumina:InterchangeUrl" value="https://urltointerchange.com" />

<!-- Request timeout, set to 30 seconds, if the request takes more than 30 seconds then the connection is dropped, this is to prevent overloading the server -->

<add key="akumina:BackgroundRequestTimeout" value="30000"/>

<!-- BackgroundProcessorKey needs to match whatever you set in your interchange.settings.config, set once to a RANDOM GUID -->

<add key="akumina:BackgroundProcessorKey" value="RANDOM GUID TO MUST MATCH THE VALUE IN THE INTCHANGE.SETTINGS.CONFIG"/>

<!-- Number of form submissions to process each time the console app is run -->

  <add key="akumina:SubmissionsTrackerBatchSize" value="1"/>

Interchange.settings.config file

<!-- establish the Forms Processing Site Collection to be used with the background processor -->

  <add key="akumina:FormsProcessingSiteCollection"value="https://**.sharepoint.com/sites/****" />

<!-- this is the SHAREPOINT user who initiates the background process calls -->

  <add key="akumina:BackgroundUser" value="user@tenant.onmicrosoft.com" />

<!-- set this encrypted password, see documentation on how generate the encrypted value from your actual password, this key is NOT used if you set BackgroundPasswordMode to keyvault  -->

  <add key="akumina:BackgroundPassword" value="password from backgroundprocessor.exe console app, be sure to run on same machine as interchange" />

  <!-- submission tracker key needs to match whatever you set in the background processor configuration, if you are using EnableLocalSubmissionsTracker to true, the SubmissionTrackerKey set once to a RANDOM GUID -->

  <add key="akumina:BackgroundProcessorKey" value="GUID INPUT HERE"/>

  <!-- This needs to be set to true for Forms functionality if you are not setting up the background processor from AzureWeb Jobs or a Scheduled Task, the Interchange website will handle the background process -->

  <add key="akumina:EnableLocalSubmissionsTracker" value="false"/>

  <!-- possible settings are protecteddata or keyvault - if you are using keyvault please see documentation on how to set this up, keyvault is required if you are using Azure WEB instance with an External background processor - possible values: protecteddata/keyvault -->

  <add key="akumina:BackgroundPasswordMode" value="protecteddata"/>

Interchange running as an Azure WEB site specific settings web.config file

 <location path="api/config/getSiteAddresses">

   <system.web>

 <authorization>

 <allow users="*"/>

 </authorization>

 </system.web>

 </location>

 <location path="api/background/formsubmissions">

 <system.web>

 <authorization>

 <allow users="*"/>

 </authorization>

 </system.web>

 </location>

 <location path="api/background/marksubmissionasprocessed">

 <system.web>

 <authorization>

 <allow users="*"/>

 </authorization>

 </system.web>

 </location>

 <location path="api/background/senddownloadlink">

 <system.web>

 <authorization>

 <allow users="*"/>

 </authorization>

 </system.web>

 </location>

 <location path="api/background/sendnotificationemails">

 <system.web>

 <authorization>

 <allow users="*"/>

 </authorization>

 </system.web>

 </location>

 <location path="api/background/marksubmissionstatus">

 <system.web>

 <authorization>

 <allow users="*"/>

 </authorization>

 </system.web>

 </location>

Background user should follow format: "Domain\User"

Interchange.settings.config file

<!-- establish the Forms Processing Site Collection to be used with the background processor -->

  <add key="akumina:FormsProcessingSiteCollection"value="https://**.sharepoint.com/sites/****" />

<!-- this is the SHAREPOINT user who initiates the background process calls -->

  <add key="akumina:BackgroundUser" value="user@tenant.onmicrosoft.com" />

  <!-- submission tracker key needs to match whatever you set in the background processor configuration, if you are using EnableLocalSubmissionsTracker to true, the SubmissionTrackerKey set once to a RANDOM GUID -->

  <add key="akumina:BackgroundProcessorKey" value="GUID INPUT HERE"/>

  <!-- This needs to be set to true for Forms functionality if you are not setting up the background processor from AzureWeb Jobs or a Scheduled Task, the Interchange website will handle the background process -->

  <add key="akumina:EnableLocalSubmissionsTracker" value="false"/>

  <!-- possible settings are protecteddata or keyvault - if you are using keyvault please see documentation on how to set this up, keyvault is required if you are using Azure WEB instance with an External background processor - possible values: protecteddata/keyvault -->

  <add key="akumina:BackgroundPasswordMode" value="keyvault"/>

<!-- See Azure Keyvault Setup Document -->

<add key="akumina:KeyVaultClientId" value=" "/>

<add key="akumina:KeyVaultClientSecret" value=" "/>

<add key="akumina:KeyVaultSecretUri" value=" "/>

  <!-- Settings for serialization for the background process -->

  <add key="akumina:JsonSerializeObjectTypes" value="System.Security.SecureString,Akumina.Interchange.Core.Entities.Connector.WidgetInstance,Newtonsoft.Json.Linq.JObject,Web.Areas.Admin.Models.Dss,Core.Entities.Connector.DigiConfig,System.Dynamic.ExpandoObject,Akumina.Interchange.Core.Entities.Connector.WidgetDefinition"/>

 

Configuring Azure Web Jobs Timer

• Open the BackgroundProcessor.zip
• Make changes to BackgroundProcessor.config (app.config) detailed above
• Zip the contents of this directory into a new .zip file
• Create a Web Application on Azure (App Service on new Azure Portal) – use the one that already exists for hosting Interchange
• Go to WebJobs and Add a new web job
• Specify the Web Job name, upload .zip file of the console app debug directory, set type to “triggered” and set the schedule using CRON expression, Click OK. The example below will execute every minute. (0 */1 * * * *)

Use this document to configure background processor to use OAuth Tokens instead of username/password-based credentials. In addition to background process, OAuth tokens used to control admin level functionalities such as workflow, query list of sites, etc., As of this writing (release 4.0 patch2) the following keys are required inside ~/interchange.settings.config

<add key="akumina:BackgroundUser" value="OAuth:Background" /> <add key="akumina:BackgroundTenantId" value="<YOUR TENANT ID>"/>

The Tenant ID is the value we currently use in Site Creator for the “Subscription ID”

Acquiring the 'Tenant ID' (wrongly labeled as Subscription ID in Akumina AppManager) = Directory ID (in Azure)

To acquire the Tenant ID on O365

Click on Admin> Expand Admin Center (left column) click on “Azure Active Directory”

On the “Azure Active Directory admin center” click on Azure Active Directory > Properties > and Copy the Directory ID, the Directory ID is the Tenant ID

The following 2 keys will be added to the interchange.settings.config

<add key="akumina:BackgroundUser" value="OAuth:Background" /> <add key="akumina:BackgroundTenantId" value=""/>

To restrict the user to set the OAuth Token you may follow the convention of the key as shown below

<add key="akumina:BackgroundUser" value="OAuth:Background~emailaddress" />

For example

<add key="akumina:BackgroundUser" value="OAuth:Background~oauthuser@domain.com" /> Configuring OAuth in AppManager

1. Log in to AppManager, as the Site Collection Administrator or Owner on site this user must have the same user permissions as the old Background Processor User.
2. Click on GEAR (/admim/console).
3. By clicking on “Acquire OAuth Forms Token” button you confirm that your current logged in user’s authorization will be used to execute all forms-based queries such as add/remove Akumina forms and supported features including start/stop Akumina workflow events.
4. If the token successfully acquired, then you will see the following confirmation

How the Token acquiring process works On the Image Above

1. “Acquire OAuth Forms Token” – click to acquire token
2. Token stored into Azure Table (Secured by Client-Side and Server-Side encryption with custom key)
3. Background Processor requests to AppManager (Continuous polling)
4. AppManager requests to Table storage for an acquired token, if the token is valid, a request made to Azure Active directory for an access token to process the data. The newly acquired token is also updated in Azure table storage.

Things to Know:

1. A lifetime of the token varies from 90 days to 365 days, but this token can be updated or revoked any time.
2. Manually updating token using “Acquire OAuth Forms Token” button is required every 90 days to 365 days.

Note:  If you see this error in the forms processor:

5.2.0 STOREDRV.Submission.Exception:SendAsDeniedException.MapiExceptionSendAsDenied;

Failed to process message due to a permanent exception with message Cannot submit message.

Update the Global Settings in App Manager, and configure System Email field. It means the RELAY has blocked the FROM Address which is what this field defines.

This is only an issue when using:

<add key=”akumina:SMTPHost” value=”smtp.office365.com” />