Connect to Data using Connector

The Connector dialog box is used throughout File-AID/EX to connect to data. The fields on the dialog box vary depending on the task being performed. The procedure below outlines the general use of the dialog box and describes the fields that may be encountered.

To create a new data connector

From the Connector Name list, select <new> to create a new connector.

Complete the fields by referring to the following field descriptions. Not all fields below will appear on the dialog box.

Field	Description
Connector Type	Select the type of data to which to connect. The list of available connector types can vary by File-AID/EX application and can vary by context (such as Source or Target modes in ConverterPro).
Connector Name	Type a name for this Connector. Connector names must begin with a letter and contain only alphanumeric characters and underscores. If left blank, a name is automatically generated but can be modified. After the connection is created, this name will appear in the Connector Name list and also in the Project Tree view.
File Name	Type the complete path and file name or click Browse to navigate to the directory where the file resides.
Host or Server	Host name or IP address of the host machine where the DBMS resides.
Alias Name	The DB2 database alias defined in the DB2 Client Configuration Utility.
Database Name	The name of your database or instance.
SID/Instance Name/Service Name	Security Identifier for an Oracle database. This is a unique name serving as a security feature that is used to identify a group of users on the network. See the database administrator for the actual name. The SID/Instance Name/Service Name determines if you are part of the group and are allowed access.
Port Number	Address or port that the database server is listening on. Valid port numbers include 1 through 65,535.
User ID	User ID for the DBMS.
Password	Password for the DBMS. Warning Important If you connect to data via an external authentication server, you do not have to enter your password manually. For more information, see To connect to data via an external authentication server.
JDBC Driver	Select the JDBC driver. All valid drivers in the genericjdbc folder appear in this list.
Refresh	Searches the genericjdbc folder, and updates the JDBC Driver list.
Connect String	Enter the JDBC connection string used to access this database instance. The drop-down list contains common templates that can be modified to match the data. Click the ellipsis in this field to open a larger text box to enter values. For MongoDB connector enter the connect string in the following format:
Use Service Name	Select or clear this check box depending on whether you want to use the service name to connect to Oracle databases. Then enter the service name in the Service Name field.
Use Trusted Connection (or Use OS Authentication)	Select or clear the selection depending on whether you want to use a trusted connection to authenticate the data connection against the requesting user's user ID> If the user ID is valid, the connection will be allowed. Then you select this checkbox and if you are using a remove server, you need to include ;DOMAIN=<domain_name> at the end of the Database Name/Alias field.
Schema Name	Enter the name of the schema designated for the database.
Show all tables/views	In ComparePro and ConverterPro: Select to view all database tables and views in the database.
Show table filter	In ComparePro and ConverterPro: Select to filter out some of the tables or views and select only specific database tables or views for viewing. Open the Selection List Filter dialog box where desired tables/views can be selected.
Show all collections	(For MongoDB connector only) Select to view all collections in the database.
Show Collection Filter	(For MongoDB connector only) Select to specify the pattern. Collections that match the specified patter are displayed.
SQL Query	In ConverterPro: Click this radio button to specify that you want to create an SQL Query. When you click Next, the SQL Query Entry window will appear where you can create your SQL query. File-AID/EX does not validate your SQL Query syntax. You must be sure that you enter a valid SQL query. Refer to the ConverterPro online help for information on SQL query entry. Warning Important This field is only available on the ConverterPro Data Sources tab or from the Data Generation Function Wizard when you use an external data source and select a relational or MS Access connector type. It is not available for the Data Privacy Manager lookup connectors.
PSB Name Filter	In ConverterPro: You can type a specific PSB name, such as INVSTOCK, or you can specify a filter for the list of PSB names, such as INV*.
Access Profile Dataset Name	In ConverterPro: Type the data set name that was created on the mainframe by the File-AID/EX Enterprise installation. This data set contains allocation profiles that allow File-AID/EX client users to connect to predefined IMS environments. This data set, called the "LOAD LIBRARY FOR EPARMS" is created during the mainframe setup in the Install Manager. For more information, see Task 4, Create a LOADMBR for Direct IMS Access (Optional) in the "Installing File-AID/EX Enterprise Edition" section.
Profile Member	In ConverterPro: Type the member name as defined by the Enterprise installer. This member gives ConverterPro clients access to IMS PSB and DBD entries in a user-controlled manner. This name is assigned by the mainframe installer as the "EPARM member" in the Install Manager. For more information, see Task 4, Create a LOADMBR for Direct IMS Access (Optional) in the "Installing File-AID/EX Enterprise Edition" section.
Symbolic Substitutions	In ConverterPro: (Only available for IMS DLI.) Type the data set name symbolic values as defined by the mainframe installation. Warning Important Multiple symbolic values can be defined but you must always specify all defined values.
Target Action (Exist/Not Exist)	(ConverterPro Target connectors only). This list displays actions that will be executed if a target exists or does not exist while running a conversion. Target actions are based on the target connector type. Refer to the ConverterPro online help for a description of all of the Target actions. Not every target action is available for every connector type, and they are only available for data targets.

Click Connect to validate the connection. A connection validation message appears stating that the connection was either successful or unsuccessful. If the information is invalid, an error message appears.
- If the connection was successful, click OK to continue.
- If the connection was unsuccessful, click Details to find out why the connection was unsuccessful, then click to close the message box.
Optionally, click Save As Template to save the connection as a template for later use.
Click Next to continue with the task that invoked the Connector dialog box.

Important

After this template is saved, it will appear in the list of templates whenever <connector templates> is selected.

To create a new data connector template

From the Connector Name list, select <new> to create a new connector.
Complete the fields by referring to the field descriptions above. Not all fields below will appear on the dialog box.
Click Connect to validate the connection. A connection validation message appears stating that the connection was either successful or unsuccessful. If the information is invalid, an error message appears.
- If the connection was successful, click OK to continue.
- If the connection was unsuccessful, click Details to find out why the connection was unsuccessful, then click to close the message box.
Click Save As Template to save the connection as a template for later use. In the Save Connection As Template dialog box that appears, type a name for the connection, optionally add a description, designate a repository from the repository list, and decide whether to save a user ID and password as part of the connector template.
Warning
Important
After the template is saved, it will appear in the list of templates whenever<connector templates> is selected.
Click Next to continue with the task that invoked the Connector dialog box.

To connect to data using an existing connector template

From the Connector Name list, select <connector templates> to open a previously saved connector template. The Open Connection Template dialog box appears.
Warning
Important
The list of the templates shows only those templates that can be used in the current context in the current application.
Double-click a previously defined connector. The dialog box reappears and displays connection fields that are autopopulated based on the connector chosen.
Click Connect to validate the connection. A connection validation message appears stating that the connection was either successful or unsuccessful. If the information is invalid, an error message appears.
- If the connection was successful, click OK to continue.
- If the connection was unsuccessful, click Details to find out why the connection was unsuccessful, then click Close to close the message box.
Optionally, change the connector name or any other field.
Click Next to continue with the task that invoked the Connector dialog box.

To connect to data via an external authentication server

If the Central Credentials Provider service is installed on one of your Windows servers, you can use it to log into your databases without entering your password. Your password can be retrieved through REST API calls by using this service. The Central Credentials Provider is a service provided by CyberArk.

While connecting to a database in ConverterPro, you can use the external authentication for the following database types:

MS SQL Server
Oracle
Sybase
DB2 UDB

To enable CyberArk-based external authentication in ConverterPro, you must add the following required certificate path (keystorePath) and certificate password parameters in the appropriate .vmoptions files, depending on your environment setup.

For Standard Installation:

ConverterPro
Path:

C:\Users\<username>\BMC\<Workbench>\eclipse\plugins\com.compuware.fileaid.ex.standalone.product.apps.x64_23.6.1.v20241224-0735_105\launch\fa_convpro.vmoptions

Embedded Execution Server
Path:

C:\Users\<username>\BMC\<Workbench>\eclipse\plugins\com.compuware.fileaid.ex.standalone.product.executionserver.x64_23.7.1.v20250309-1640_79\launch

fa_exsrvr.vmoptions

fa_exbatch.vmoptions (If running a batch program)

Embedded Communication Manager
Path:

C:\Users\<username>\BMC\<Workbench>\eclipse\plugins\com.compuware.fileaid.ex.standalone.product.commgr.x64_23.7.1.v20250309-1640_79\launch\fa_commgr.vmoptions

If using standalone Execution Server or Communication Manager:

Standalone Execution Server
Path:

C:\Program Files\BMC\File-AID_EX\Dme\fa_exsrvr.vmoptions

Standalone Communication Manager
Path:

C:\Program Files\BMC\File-AID Services\MMCServer\eclipse\plugins\com.compuware.fileaid.ex.standalone.product.commgr_23.6.1.v20241224-0735_105\launch\fa_commgrsvc.vmoptions

Parameters to Add in Each .vmoptions File:

-DkeystorePath=path_to_cacerts     (Use '/' forward slash)
-Dpassword=changeit

These settings allow secure SSL communication between ConverterPro and CyberArk's Central Credentials Provider.

Perform the following steps to use an external authentication server:

From the Connector Name list, select <new> to create a new connector.
Complete the fields by referring to the field descriptions above. Do not enter the DBMS password.
Select the Enable External Authentication check box. The External Authentication button is enabled and the Password field is disabled.

Click External Authentication.
In the external authentication login window, enter the details of the external authentication sever. Note that entering the Database name and the Safe name is not mandatory. You can save the entered details into an XML file. For more information, see Saving details to a template or to an XML file.

To validate the entered details, click Validate.
Warning
Important
When you click External Authentication again after validating details successfully, the previously entered details appear on the external authentication login window. If you update any of these details incorrectly and click Validate, the previously validated information is lost and the external authentication login window displays empty fields.
Click Connect. You are connected to the database.
When connecting with an external authentication server, the following error message is displayed if an SSL certificate is missing:

If you are using a stand-alone external authentication server, you must import its SSL certificate into the Java keystore through the following command:
keytool -import -alias CyberArkAlias -keystore <<Workbench installation folder>>\eclipse\jre\lib\security\cacerts -file <<certificate file>>
If you have a stand-alone installation of File-AID/EX, you should also import the SSL certificate into its <<installation folder>>/JRE/lib/security/cacerts file.

Saving details to a template or an XML file

To save all details of data sources as a template, click Save As Template. In addition to the details entered in the external authentication window, the template saves all the fields in the display.

When you connect to a database the next time from ConverterPro, you can select the saved template from the Connector Name list. All details are automatically populated.

After you create the ConveterPro specification once, you can save it and use it again without having to re-enter details. To save all details of data sources, data targets, and mapping, use File > Save as XML.

The XML file stores the following details:

Consider the following details before using this XML file:

You can modify this XML and use it to connect to a database via CyberArk.
In the USER tag, CyberArkCredentialName indicates a CyberArk credential set, which is used to access DBMS the password.
If the value of the IsLoginWithCyberArk variable is set to False, you cannot use the external authentication server to log on to a database.
The Password field in the USER tag is left empty for an external authentication.