Summary

The Fountayn Listener is a product that automates the process of manually uploading files to the Fountayn application. The Listener detects files and sends them across https to the Fountayn servers for parsing and insertion into existing clinical applications.  

Table of Contents

• Initial Startup
• Set Up Automated User
  • Configure Listener Role in DA
  • Set Up EULA Exempt Account
  • Add Listener Account to Trial Manager
• Set up the Listener for the Study
  • Determine the Regular Expression
    • Basic filename
    • Regex Groups
    • File Extension
    • Examples
      • Medication Log
      • Pain Log
      • Additional Log
  • Set up the Listener at the Study Level
  • Complete the Listener File Type Form
  • Set up the Listener at the Site Level
• Configure Listener XML File
  • Access and Run Listener Executable
  • Edit Listener File
    • Complete Directory Attributes
    • Complete Environment Information
    • Complete Listener Account Information
    • Complete Interval and Shutdown Information
    • Complete File Import Information
    • Complete File Import Information for Multiple File Types
• Start the Listener
• Shut Down the Listener
  • Reading Error Codes
• Troubleshooting

The Listener runs on the client’s server and utilizes an eClinical user account to access one of the Fountayn environments and transfer the files. The listener can be configured to work with any environment: Secure, Approve, Test and Design.

Recommendation: As a safety measure, configure the Listener to upload cumulative files only. Depending on the Listener run interval, incremental files may or may not complete loading before the next run interval begins and any new data still pending will be lost.

Initial Startup

Prior to setting up the listener, it is important to get an accurate representation of the files being imported. This is especially important when configuring the regular expression used to specify how filenames should be interpreted by the listener.

For example, if the sample import file is labeled “test01.txt” but the actual imported filenames will include additional information related to the study name, subject identifier or other study-related items, this information needs to be included in the sample file. Without such information, the regular expression may not be configured properly, which could result in failed imports.

Set Up Automated User

Before the Listener can be configured, an account for an automated user must be created that has the Listener role and is EULA exempt. This account should only be assigned to those studies that are utilizing the Listener for file transfer.

Note: The Listener account password cannot have an ampersand included. It is recommended to proactively remember to change the listener password. The email notification that the password is expiring only triggers upon login to the system, so the email might not trigger due to inactivity of the listener account. 

Note: If you are working with 2 or more Trial Managers (Study A under TM A and Study B under TM B), you must use separate listener accounts for each. A listener account can only access a single Trial Manager (although a single listener account can service multiple trials under a single TM). If you are using Windows with 2 or more Trial Managers you will need to contact Fountayn to package the Listener to reflect multiple sub-clients.

Configure Listener Role in DA

1. In the Roles worksheet of the Data Architect file, add a new role called ‘FTYN Listener.’
2. Give the FTYN Listener role the following role attribute.

Note: Giving the FTYN Listener role any permissions other than the import data permission can result in errors. 

3. Compile the DA.

Set Up EULA Exempt Account

1. Follow the steps to create a new user account in Enterprise Manager.
   This new user account will be the Listener account.
2. In Enterprise Manager, select ‘Edit Eula Exempt Users.’
3. On the Exempt EULA Users screen, add the Listener user’s name and click the ‘Save’ button.

Add Listener Account to Trial Manager

1. In Enterprise Manager, check the checkbox beside the Trial Manager that should use the Listener.
2. Click the ‘Add Users’ button.
3. Enter the username of the Listener account and click the ‘Save’ button.
4. On the Roles screen, select the Listener role and click the ‘Save’ button.

Note: The Trial Manager must have the Listener role available in order to move forward with the Listener configuration. If the role is not available, contact your Software Implementation Specialist (SIS). 

Note: Do not give the Listener account any role other than the Listener role. Giving the Listener additional roles can cause errors in the system. 

Set up the Listener for the Study

After a study is enrolled in Trial Manager, the Listener File Type form must be completed at both the study and site level. This form creates the mapping for the Listener files to the appropriate Fountayn study.

Determine the Regular Expression

To complete the Listener File Type form discussed in the next section, you will need to enter a regular expression. This regular expression is used to specify how the name of the files being imported should be interpreted by the Listener. The regular expression is generally made up of the following three parts.

Basic filename

Optional. The part of the filename that will be the same for every file imported by the listener.

Regex Groups

Multiple groups can be included in the regular expression. Each group is defined by a set of parentheses. Groups are used to define the study identifier, site identifier and subject identifier if one is required.

File Extension

Required. The file extension for the imported files.

Examples

Medication Log

The following regular expression could be used with a listener that is configured to import medication logs in the txt file format. Each log filename includes a basic filename of “medicationLogs,” a study identifier, three-digit numeric site identifier and three-digit numeric subject identifier.

medicationLogs(XX3598)([0-9]{3})([0-9]{3}).txt

Pain Log

The following regular expression could be used with a listener that is configured to import pain logs in the xml or txt file format. Each log filename includes a basic filename of “painLogs,” a three-character study identifier and a four-digit numeric site identifier.

painLogs([a-z]{3})([0-9]{4}).(xml|txt)

Additional Log

The following regular expression could be used with a listener configured to import logs in the xml file format. Each log filename includes a four-character study identifier and a three-character and three-digit site identifier.

([a-z]{4})([a-z]{3}[0-9]{3}).xml

Set up the Listener at the Study Level

1. In Trial Manager select the study that will use the Listener.
2. In the Form Links table select ‘Setup.’
3. Click the ‘Add Listener File Type…’ link.

Complete the Listener File Type Form

As described in the previous section, a regular expression must be used to complete this form. Each example provided in this section pertains to the following Listener example:

If the Listener is to be configured to import medication logs, the following may be an acceptable filename: medicationLogs_XXX3598_101.txt where the “XXX3598” is the name of the study and the “101” is the name of the site.

1. Regular Expression for parsing file names: Enter the regular expression that should be used by the Listener to parse the file name.
   Example: medicationLogs_(XXX3598)_([0-9]{3}).txt
2. Regex Group Number for Study Identifier: Enter the number of the Regex Group that corresponds to the Study Identifier.
   Example: 1
3. Regex Group Number for Site Identifier: Enter the number of the Regex Group that corresponds to the Site Identifier.
   Example: 2
4. Regex Group Number for Record Identifier: Enter the number of the Regex Group that corresponds to the Subject Identifier.
   Example: Since the regular expression does not include a subject identifier, the number 2 can be used again.
5. Study Code used in the file naming convention: Enter the study code used within the file naming convention.
   Example: XXX3598
6. The action to perform when submitting this file type: Enter the name of the action that should be performed when submitting a file of this file type.
   Example: importData

Note: Ensure that the action does not contain any spaces before or after the value (e.g. 'importData' will cause the process to fail).

Set up the Listener at the Site Level

Once the study configuration is complete, each individual site where a file should be imported must also be configured.

Note: If the Listener is being used on multiple environments, each site in the appropriate environments must also be configured.

1. In Trial Manager access the Site page in the appropriate environment.
2. For the question labeled “Site Code used in the file naming convention,’ enter the site code that will be used as part of the filename.
   This process is the same as entering the Study Code at the study level.

Configure Listener XML File

After the Listener Account has been set up and Setup configuration completed, the Listener must be configured on your local server.

Access and Run Listener Executable

1. Request the Listener executable from your Software Implementation Spe.
2. Once the executable is received, run the executable
3. Review the instructions provided in the README file.

Edit Listener File

1. Before opening the Listener XML file, rename the ‘listener.xml.sample’ file to ‘listener.xml’
   If prompted to confirm that you want to change the file name extension, click ‘Yes.’
2. Open the newly named listener.xml file in a text editor such as TextPad or Notepad++.
   The listener.xml file contains a basic template demonstrating how to configure the listener.

Complete Directory Attributes

The first set of attributes in the listener.xml file pertains to the directories that should be used when working with the import files.

1. inputDirectory: Enter the name of the directory in which files are dropped to be picked up by the Listener.
2. outputDirectory: Enter the name of the directory in which successfully processed files are put when the transfer is complete.
3. failedDirectory: Enter the name of the directory in which unsuccessful files are put when the transfer fails.
4. logDirectory: Enter the name of the directory in which logs for successful and unsuccessful transfers are stored.

Complete Environment Information

The second set of attributes in the listener.xml file pertains to the hosting environment.

1. protocol: Enter the protocol in which the files are transferred.
   Generally the following value is used: https
2. host: Enter ‘secure.fountayn.com’ as the URL for the host where the Trial Manager can be accessed.
3. fileHost: Enter the name of the host where the files will need to be submitted based on the following list of acceptable values.
   • secure.fountayn.com 
   • approve.fountayn.com 
   • test.fountayn.com 
   • design.fountayn.com 
4. environment: Enter the name of the environment where the files will be submitted. The environment must be in all caps and should match the fileHost environment.
   • SECURE
   • APPROVE
   • TEST
   • DESIGN
5. port: Enter the port that should be used.
   Generally the following value is used: 443
6. webapp: Enter the name of the web application that will be used.
   Generally the following value is used: /clickFind

Complete Listener Account Information

The third set of attributes in the listener.xml file pertains to specifying the Listener account that should be used.

1. username: Enter the Fountayn user name for the configured Listener account.
2. password: Enter the Fountayn password for the username.
   

Complete Interval and Shutdown Information

1. pollInterval: Enter the time frequency with which the listener will look for new files.
   This frequency is measured in milliseconds.
2. shutdown: Enter the name of the file that the listener should look for to determine when to shut down.
3. runningWaitInterval: Enter the time in milliseconds that the Listener will wait before it checks to see if an import has completed.
   

Complete File Import Information

After the Listener attributes have been completed, a set of fileType attributes and parameters must be configured for each type of file that the Listener will import. As described below, the parameters correspond to parameters within the Data Architect file.

Note: This section describes how to complete the file when the Listener is only importing one type of file. If multiple types of files need to be imported, follow the steps described in this section as if they were for the first file type. Then see the next section for further instructions.

In this section refer to the block of code below. The line number is included at the beginning of every line.

1 <fileType fileRegex=".*" passiveImport="true" runningText="Running">
2 <parameter name="importID" value="import1"/>
3 <parameter name="import" value="true"/>
4 <parameter name="import1" value="FILE_OBJECT"/>
5 </fileType>

1. Line 1: If the language of the Listener account is in a language other than English, translate the word, “Running,” to the appropriate language.
   Example: RunningText=”corriendo”
   If the import is only for a single file type, the fileRegex value should only be ‘.*’ as noted above. The value of ‘passiveImport’ should remain ‘true’ in all cases.
2. Line 2: Enter the Import Id from the DA that corresponds to the import that the Listener should perform.
3. Line 4: Enter the Import Id from the DA that corresponds to the import that the Listener should perform.

Complete File Import Information for Multiple File Types

If only one type of import file will be imported, you can skip this section.

1. Copy the entire fileType block of code.
2. Paste as many copies of the block of code into the Listener file as needed.
3. For each fileType, edit the fileRegex attribute to match the regular expression set up for the file in the Listener File Type form.
4. Edit the ImportID and import parameter values as described in steps 2 and 3 of the previous section.

…
<fileType fileRegex=" painLogs([a-z]{3})([0-9]{4}).(xml|txt) 
"passiveImport="true" runningText="Running">
<parameter name="importID" value="import1"/>
<parameter name="import" value="true"/>
<parameter name="import1" value="FILE_OBJECT"/>
</fileType>

<fileType fileRegex=" medicationLogs(XX3598)([0-9]{3})([0-9]{3}).txt" 
passiveImport="true" runningText="Running">
<parameter name="importID" value="import2"/>
<parameter name="import" value="true"/>
<parameter name="import2" value="FILE_OBJECT"/>
</fileType>

</listener>

Start the Listener

After the listener.xml file has been completed, you can start the Listener.

1. In the Listener folder Double-click FountaynListener.exe
2. Open Task Manager to verify that processes with FountaynListener are running.

If no FountaynListener processes are running, double-check the listener.xml file and run the FountaynListener.exe file again.

The Listener can also be run as a background process by installing the listener as a service. Review the README file in the Listener folder for further details.

Shut Down the Listener

When it is time to shut down the Listener, the shutdown file specified in the listener.xml file needs to be added to the file directory. The name of this shutdown file must match the name specified in the listener.xml file exactly.

1. Open a text editor such as TextPad or Notepad++.
2. On the Desktop or in a personal folder, save a new blank document such that it has the same filename and file extension as the file designated in the listener.xml file.
3. When it is time to shut down the listener, move or copy the shutdown file into the directory with the FountaynListener file and listener.xml file.

The Listener will stop running until the shutdown file is removed and the Listener launched.

Reading Error Codes

There are three error codes that may display during the processing of files through the Listener. Each error code is defined and described below:

Troubleshooting

In setting up the Listener, there are multiple steps that have to be completed and in place for everything to work. The above steps, when followed properly, should allow the import to work as expected. However, if you run into issues, the following troubleshooting steps may help:

Need more help?

Please visit the Fountayn Contact Information page.