Subscribe to PortalGuard's Quarterly Newsletter for News & Updates on the Latest Release! Click to Subscribe

How to Use the PortalGuard Batch Import Utility


Problem

You want to configure and use the PortalGuard Batch Import utility to pre-enroll specific information for multiple user accounts.

Solution

Configure the PortalGuard Batch Import Utility appropriately and create a properly configured 'import.csv' file to import the required information. 

Quick Navigation

Batch Import Pre-Requisites

Prior to configuring and running the Batch Import Utility, you must first update PortalGuard's 'Bootstrap Configuration' to allow users to run the utility.  Follow the steps below to add users as administrators for the Batch Import Utility:

  1. On the PortalGuard Server, open the PortalGuard Configuration Editor and click on the 'Edit Bootstrap' button.
  2. Navigate to the 'Policies' tab. 
  3. In 'Batch Importers' field, input a comma-separated list of usernames that should be allowed to utilize the Batch Import Utility. Your final result should resemble the following:
  4. Click on the 'Save' button. 
  5. Click on the 'Apply to PortalGuard Server' button and then click the 'Sync' button on the following screen to apply these changes. 

Important Note: The Batch Import Utility requires your Security Policy to be configured to utilize the data being imported.  For example, if you want to utilize SMS OTP delivery for Self-Service Password Reset or Two-Factor Authentication, your PortalGuard Security Policy MUST be configured to accept and utilize that particular 'Authentication Method'.  If the policy that applies to a specific user does not allow for the action you are trying to import, the import attempt will result in a failure. 

Configuring the Batch Import Settings

  1. On the PortalGuard server, navigate to the C:\Program Files\PistolStar\PortalGuard\bin directory.
    • Note: If you installed PortalGuard on a separate drive, please be sure to navigate accordingly. 
  2. Right-Click the 'PG_BatchImport.exe' application and choose 'Run as administrator'.
  3. Leave the 'Runtime Log Level' set to 'Trace' and ensure the 'Create Audit Log' option is checked.
  4. On the following screen, update the three fields under 'Server Access' as needed:
    • 'PortalGuard Server:
      • The base URL to your PortalGuard website - include the protocol as needed (i.e. https://pgtest.int)
    • 'Administrative Username':
      • The username to run the Batch Import Utility as - this should match one of the usernames defined in the 'Bootstrap Configuration' as a 'Batch Importer'
    • 'Administrative Password':
      • The password for the user listed as a 'Batch Importer'
  5. Next, you will need to determine which 'CSV Headers' to look for based on the information you wish to import.  
    • Please refer to the Batch Loading Users Into PortalGuard KB article for more information on the various options.
    • Please note that 'Username' must ALWAYS be the first 'CSV Header', and these headers are Case-Sensitive.
  6. For our example, we will be configuring the Batch Import Utility to import the SMS-Capable Phone Number for OTP Delivery.  The required 'CSV Headers' for this import are:
    • Username
    • EnrolledPhone
    • EnrolledPhoneCanSMS
    • EnrolledPhoneCountry
      • IMPORTANT NOTE: If your PortalGuard instance does not utilize a 3rd Party SMS provider and is configured to use the 'Email-to-SMS-Gateways' option for SMS delivery, an additional headers is required: EnrolledPhoneProvider
  7. When finished, your settings should resemble the following:
  8. Click the 'Save' button.
  9. If you receive a permissions error when saving these settings, you will need to reconfigure the settings after running the application as administrator. 
  10. To confirm the settings saved, either locate the new 'batchimport.settings.xml' file in the bin folder, or reopen the utility to validate the settings visually. 

Formatting the CSV File

Once the Batch Import Utility has been configured to expect and process the appropriate information, you will need to create and modify an 'import.csv' file for the process.  This file is important, as it will contain all information that gets imported into PortalGuard via the Batch Import Utility.  Proper formatting is necessary, as a single typo may throw off the entire import process. The steps below cover the proper configuration to match the settings configured above. 

  1. Using an Administrative Text Editor (i.e. Notepad ++), create a new file named 'import.csv'. 
    • It is important to ensure the file is saved as a .csv file and not with the .txt extension
  2. The first line of the file should contain the values for the 'CSV Headers', separated by a single comma character:
  3. Each line after the first should contain the relevant information for a single user, beginning with the Username and with each value separated by a single comma character. In this example, each row should have four (4) different values separated by commas.  Each value is defined below:
    • 'Username'
      • The Username to point to the User Profile to be updated with the remaining information. 
    • 'EnrolledPhone'
      • The phone number for the user without spaces or formatting characters (i.e. 1234567890).
    • 'EnrolledPhoneCanSMS'
      • Set this value to '1' for mobile phones.
    • 'EnrolledPhoneCountry'
      • The 2-letter Country Code for this phone number.  This allows PortalGuard to determine which country code should be used when delivering an OTP to this number.
  4. Your final result should resemble the following:
  5. IMPORTANT NOTE: Be sure that there are no extra characters (including spaces) before or after any data point.  You should also ensure that there is not an extra blank line at the end of the file.  The 'import.csv' file must be configured exactly in order to run without error. 
  6. Save this file to the C:\Program Files\PistolStar\PortalGuard directory.
  7. Copy the file into the C:\Program Files\PistolStar\PortalGuard\bin directory.
    • When the Batch Import Utility is run, it destroys the source 'import.csv' file stored in the bin directory.  Having a copy in the base PortalGuard directory prevents you from having to start from scratch each time you run the utility. 

Running the Utility

After configuring the Batch Import Utility settings and saving a populated and correctly formatted 'import.csv' file, you can run the utility itself to perform the import.  The utility is run as a Command Line application, with a simple command switch.  As a Command Line Application, additional commands can be given for additional functionality as needed.  For more information on these additional commands, please refer to the Batch Loading Users Into PortalGuard KB article.  For our purposes, we will simply be running the utility by following the steps below. 

  1. Open Command Prompt as an administrator
    • Note: On Windows Server 2016 you can simply right-click the start menu and choose 'Command Prompt (Admin)'
  2. Use the 'cd' command to change directories to the C:\Program Files\PistolStar\PortalGuard\bin directory.
  3. Type the first few characters of the application name (i.e. 'PG_B' and hit the tab key to autofill to 'PG_BatchImport.exe'.
  4. Add a space and then the '-run' command:
  5. If the 'import.csv' file is located in the same directory and formatted correctly, you should see something similar to the below output:
    • NOTE: Each user will result in a new set of lines in this output, so do not be surprised if your attempt yields much more data.  
  6. If you see any errors or 'Failed' responses, please refer to the PG_Log file to determine the cause.  If you submit a support ticket, be sure to include a compressed version of this log file for our reference. 

REV. 11/2018 | PortalGuard

  • 76
  • 02-Nov-2018
  • 226 Views