Using the  bpEmailImport Utility

The bpEmailImport utility (bpEmailImport.exe) allows you to send formatted emails to a process either on a schedule or any time an email is received. Using bpEmailImport.exe, you can set the conditions and format under which you'd like to import the emails.

The executable file, bpEmailImport.exe, is located in the c:\Program Files\BP Logix\Process Director\ directory by default. You can copy this utility to any computer that has Internet Explorer 6 or higher installed.

Cloud installation customers can download the utility from the Downloads section of the BP Logix support site.

Connection Tab #

OAuth Tab #

Version 2.22 of the utility has an OAuth tab to configure OAuth authentication for mail services that use Microsoft's Modern Authentication or Google OAuth systems to access the service. The properties on this tab enable access to Azure or Google, and are required in addition to the properties on the Connection tab. While the Connection properties enable connection to a specific email inbox, the OAuth properties grant access to OAuth-protected services.

Microsoft Modern Authentication (MMA)

For Microsoft/Azure MMA, There are three fields that must be configured to enable OAuth authentication with the mail service. Use of OAuth from Microsoft with the E-mail Import Utility requires the existence of a properly configured Azure Active Directory (AAD) Registered App.

Important Creating the AAD Registered App and integrating it with OAuth will require in-depth knowledge of Azure. As such, assistance from your IT personnel may be required.

Microsoft OAuth integration requires three pieces of data that correspond to the three properties that must be configured on the OAuth tab. These three properties must be obtained from Azure, and can be accessed only after creating the AAD Registered App for the OAuth connection.

The Tenant, Client ID and Client Secret properties are obtained as follows:

Additionally, the AAD Registered App requires the following settings:

API Permissions
  • Delegated Microsoft Graph permission IMAP.AccessAsUser.All
  • The administrator must grant consent to this permission after its addition
Authentication Settings
  • Allow public client flows: Yes (on)
  • Organizations that use a hybrid Federated Identity environment must enable Azure Active Directory Pass-Through Authentication. Otherwise, the utility will be unable to connect to the specified user accounts, and an error will be generated.

A more detailed explanation of how OAuth works and is configured on Azure-based systems is available in the SharePoint OAuth Datasource topic.

Google OAuth

For Google OAuth, v2.25 of the bpEmailImport utility enables connections to Google. Only two Properties are required to implement the OAuth authentication. Both of these properties are available in the Google Developer Console for your account, and can be copied from there to the corresponding properties in bpEmailImport.

Filtering Tab #

Options Tab #

Scheduling Imports #

Using the Windows Scheduler, you can run the Email Import utility via a command line argument, e.g.,

bpEmailImport.exe -w "http://ServerName.com/" -s "mail.MailServer.com" -u "user1" -p "" -i "Test Partition" --delete

The Email Import utility can be called by using a number of command line switches, which are described below. While in the command line interface, you can also see the full list of available switches by invoking the "/?" help switch, e.g., bpEmailImport /?

The available command line switches correspond to the properties that are accessible in the GUI, as described above.

SWITCH DESCRIPTION
-W The Process Director's web services URL
-S The location of the mail server
-I The partition into which mail will be imported
-U The Process Director user for web service authentication
-P The Process Director password for web service authentication
-T The protocol used to get mail from the server (IMAP or POP3)
-F The Process Director folder into which the mail is imported
-L The folder in which bpEmailImport's logs will be saved
--port The port used to connect to the mail server
--ssl Tells bpEmailImport to use SSL to connect to the mail server
--popuser The mail server authentication user
--poppassword The mail server authentication password
--imapfolder The mailbox folder from which the mail will be pulled
--leave Tells bpEmailImport to leave mail on the server
--leavefile The file in which bpEmailImport records the mail it downloads
--imapmovefolder The mailbox folder into which mail will be moved
--delete Tells bpEmailImport to delete mail after download
--limitsize The maximum attachment size (in bytes) to download
--strip Tells bpEmailImport not to download mail attachments
--Nextension Tells bpEmailImport to add file extension to uploaded mail
--addRef Adds attachments as references to uploaded mail
--oauthtenant Provides the OAuth Tenant
--oauthclient Provides the OAuth Client ID
--oauthclientsecret Provides the OAuth Client Secret
--overwrite Tells bpEmailImport to overwrite existing uploaded mail
--limitcount The maximum number of emails to import
--maxage Maximum email age (in seconds) to download
--delay The delay (in milliseconds) between each mail upload
--filterfrom Only import mail where the from field matches this regex
--filtersubject Only import mail where the subject field matches this regex
--filterbody Only import mail where the body field matches this regex
-N
--no-gui
Runs bpEmailImport in command line mode

Optional Meta Data XML Files #

The import utility can include Meta Data with each of the files being uploaded to Process Director. This Meta Data can set the categories and attributes for the document on the server. This occurs if the option is selected to allow associated Meta Data files on the import dialog. If this option is selected the import utility will attempt to find matching file names with “.XML” appended to the name. For example, if the import utility finds a file named mydoc.pdf, it will attempt to locate the mydoc.pdf.xml file for the Meta Data. The Meta Data XML file must be of a certain format to be recognized as valid Meta Data. The XML file must contain the following structure and tags.

<META_DATA>
    <INPUT_META_DATA>
        <META_NAME>external_attribute_name</META_NAME>
        <META_VALUE>attribute_value</META_VALUE>
    </INPUT_META_DATA>
    <INPUT_META_DATA>
        <META_NAME>external_attribute_name_2</META_NAME>
        <META_VALUE>attribute value 2</META_VALUE>
    </INPUT_META_DATA>
</META_DATA>

The <META_NAME> must match an External Name in a category attribute for the document to be assigned to that category. If a matching External Name isn't found in the category tree the Meta Data is discarded after the upload completes.

For example, assume you have a category named Operations that contains a subcategory named Quality with an attribute name of ActionManager. You can assign this entire category tree (i.e. Operations.Quality) to the imported document by using a matching External Name in the ActionManager attribute. If the external name in the ActionManager attribute is set to “manager_name”, the XML for the imported document would look as follows:

<META_DATA>
    <INPUT_META_DATA>
        <META_NAME>manager_name</META_NAME>
        <META_VALUE>John Smith</META_VALUE>
    </INPUT_META_DATA>
</META_DATA>

To set values for checkboxes, the values YES and NO correspond to a checked state and an unchecked state, respectively.

Date values vary based on locale: if you’re in the USA, use mm/dd/yyyy. If you’re elsewhere, use dd/mm/yyyy.

Using the Utility on a Remote Machine #

The executable file, bpEmailImport.exe, is located in the c:\Program Files\BP Logix\Process Director\ directory by default. You can copy this utility to any computer that has Internet Explorer 6 or higher installed, and has Web Services running. When you do so, ensure that you also copy over the Aspose.Email.dll file into the same folder as you place the email import utility. Both files must be in the same folder for bpEmailImport.exe to run correctly.

Simply execute bpEmailImport.exe to launch and configure the import dialog settings.