Configuration Parameters for JDBC Data Services

The following panels and panes may be displayed when you configure a JDBC data service A connection to a database or spreadsheet that is external to Loftware. A JDBC data service drives Database data sources used in label templates. or a Database data source A connection to a database that acts as a data source and can serve as the data ref for a document field. A Database data source is associated with a Database data service..

A Data Service Administrator A local administrator who creates and configures data services for use by Designers who configure Database data sources and Alternate data sources. can limit which options are visible to a Designer Person who creates and designs label templates, forms, and applications for use by Data Providers.. The Auto Select First Row and Auto Select Single Row Result options are only displayed when configuring a Database data source.

Important! A Data Service Administrator can select the Is Parameter check box for a parameter in a data service to allow a Designer to customize that parameter for each Database data source. If the Is Parameter check box is cleared, then the parameter is not displayed in Database data sources.

Note: A Data Service Administrator can add custom parameters by clicking the Add Parameter button when configuring a Data Service. A Designer can add custom parameters by clicking the Add Parameter button when configuring a Database data source. See the Advanced section of this topic for more information.

Ribbon

Ribbon Commands

Icon	Command	Description
	New	Create a new object of a specific type.
	Open	Open an existing object.
	Save	Save the displayed object.
	Delete	Delete the displayed object.
	Undo Edits	Reverse the most recent action on an object.
	Redo	Reapply the previously undone action to an object.

File Menu

Command	Description
Close	Close the current object.
Close All	Close all objects that you have open.
Save	Save the object.
Save As	Save a copy of the object under a different name.
Delete	Delete the displayed object.

Home

Start and Stop Data Service

The Start Data Service and Stop Data Service functions control the availability of the data service to Designers and Data Providers.

Button	Command	Description
	Start Data Service	Make a data service available.
	Stop Data Service	Make a data service unavailable.

View

Properties Pane

The Properties pane allows you to describe the data service. It also displays the type of the data service and status information about the data service.

Option	Description
Service Name	The name for this data service.
Description	A description for this data service.
Data Service Type	The type of data service. JDBC Data Service JDBC Update Data Service File Data Service HTTP Data Service Link Data Service SOAP Web Service Data Service Serial Number Data Service
Configured Status	This property is not displayed until the data service has been saved for the first time. Started Stopped
Status	This property is not displayed until the data service has been saved for the first time. Service Up: The service is online. Service Down: The service is unreachable and possibly offline.
Creation Information	Created By: The user name of the creator of the data service. Created On: The date the data service was created. Modified By: The last user to change the data service Modified On: The date the data service was last changed.

Tags Pane

The Tag Values dialog box is available when viewing an object that supports tags. Click View > Tags to open the dialog box.

You can categorize an application, business rule, data service, device group, facility, field data catalog, form, image, integration, label template, layer object, layout, process, Remote Site, reusable object, user, or workflow template by assigning tags to it. Each tag has a category and a value. For a version-controlled object, tags cannot be changed in a previously checked-in version.

Button	Command	Description
	Assign Tag	Assign a tag to an object. The tag category must already exist.
	Delete Tag	Remove a tag that was assigned to an object.
	Edit Tag	Edit the tag Category and Value.

For more information about using tags, see Categorize a Data Service.

Service Management

Connection

The following options may be displayed in the Connection panel for a JDBC data service. You can also add custom options.

Parameter	Description
JDBC Connection URL	The connection string for the database used for this data service. This option is displayed only if Is Data Link is not selected. For information about the format, see JDBC Connection URL Formats. Note: In most cases, the Data Service Administrator should clear the Is Parameter check box so that this parameter cannot be configured in Database data sources by Designers.
Database Username	The user name used when establishing a connection to the database. This option is displayed only if Is Data Link is not selected. Note: In most cases, the Data Service Administrator should clear the Is Parameter check box so that this parameter cannot be configured in Database data sources by Designers.
Database Password	The password associated with the user name used when establishing a connection to the database. This option is editable only if Is Data Link is not selected. Note: In most cases, the Data Service Administrator should clear the Is Parameter check box so that this parameter cannot be configured in Database data sources by Designers.
Test URL	A button used to check the connection parameters to a database.
Show Testing Dialog	Select to open a window that will allow you to change and test different connection parameters

General

The following options may be displayed in the General panel for a JDBC data service.

Parameter	Description
Is Data Link	Whether to obtain the JDBC Connection URL and credentials from a Link data service. This parameter cannot be displayed or configured in Database data sources. If cleared, the URL and credentials from this JDBC data service are used. If selected, the URL and credentials from the Link data service specified in the Data Link field are used.
Data Link	The Link data service from which to obtain the JDBC Connection URL and credentials. This option is displayed only if Is Data Link is selected. This parameter cannot be displayed or configured in Database data sources.
Read Only Session	If selected, prevents the user from using this connection to make changes to the database during this session. This functionality may vary with the JDBC driver and database software used. Note: In most cases, the Data Service Administrator should clear the Is Parameter check box so that this parameter cannot be configured in Database data sources by Designers.
Batch Size	The maximum number of rows returned by the query. You can specify up to 1000 rows.
Session Expiration	Time (specified in seconds) allowed for a Data Provider Person or process that enters data into a form or other data entry view for a label that was configured by a Designer. A user acting as a Data Provider requires the DOCUMENT_PRINTER role or equivalent permissions. to select a row. The default value is 300 seconds.

SQL

The following options may be displayed in the SQLpanel for a JDBC data service. You can also add custom options.

For a JDBC data service, the Result Map displays the columns that are returned by the query. By altering the Result Map, you or a Designer can change which columns are displayed to a person acting as a Data Provider and change the name displayed for each column in results viewed by Data Providers. Optionally, you can configure a Result Map to limit which columns are available for use as data sources, and then prevent Designers from viewing or changing the Result Map by clearing the Is Parameter check box. Changes that you make to the Result Map do not alter the database.

Parameter	Description
SQL Query	The SQL query that the data service runs on the database. The query can be entered as part of the data service or can be passed as a parameter from a Database data source used in the label template. Note: If the Data Service Administrator selects the Is Parameter check box so that this parameter can be configured in Database data sources by Designers, then the Data Service Administrator should also select Is Parameter for Result Map.
Result Map	The columns provided by running the SQL Query. You can configure which columns are displayed to a Data Provider Person or process that enters data into a form or other data entry view for a label that was configured by a Designer. A user acting as a Data Provider requires the DOCUMENT_PRINTER role or equivalent permissions. and available to Designers for use as data sources. You can also configure the column display names and widths displayed to Data Providers in results. If the Data Service Administrator clears the Is Parameter check box so that this parameter cannot be configured in Database data sources by Designers, then the Data Service Administrator should also clear Is Parameter for SQL Query. Important! The Result Map is not dynamic. If the columns available in the database have changed, you must ensure that the data service is started and run the query again to see those changes reflected in the data service. In a Database data source, you must run the query again to retrieve changes to the associated data service. Column Name: The name of the column in the database and as it is displayed to Designers. You cannot change this value in the Result Map. Required: If selected, generates an error if a row in the query result does not include a value for a the column. You can change this value in the Result Map. Display: If selected, the column is displayed in results for Data Providers and in the Data Sources pane for Designers. You can change this value in the Result Map. Display Name: The name of the column as it is displayed to Data Providers. You can change this value in the Result Map. Type: The data type of values in the column. You cannot change this value in the Result Map. Display Length: The default width that will be used when displaying the column in the results to Data Providers. Data providers can manually adjust column widths. Changing this value does not limit the length of the data available to Data Providers. You can change this value in the Result Map. Run Query: Clear the existing Result Map, run the query, and populate the Result Map with the default information about the columns. If you customized the Result map, those changes are removed. Is Parameter: Selecting this option allows Designers to customize the Required, Display, Display Name, and Display Length values in the Result Map for Database data sources associated with this data service. Clearing this option prevents Designers from viewing or modifying the Result Map, but they can still view the names of columns for which Display is selected. Note: If you clear the Display check box for a particular column and clear the Is Parameter check box for the Result Map, then Designers cannot use that column as a data source or display it to Data Providers.

Parameter

Description

SQL Query

The SQL query that the data service runs on the database. The query can be entered as part of the data service or can be passed as a parameter from a Database data source used in the label template.

Note: If the Data Service Administrator selects the Is Parameter check box so that this parameter can be configured in Database data sources by Designers, then the Data Service Administrator should also select Is Parameter for Result Map.

Result Map

The columns provided by running the SQL Query. You can configure which columns are displayed to a Data Provider Person or process that enters data into a form or other data entry view for a label that was configured by a Designer. A user acting as a Data Provider requires the DOCUMENT_PRINTER role or equivalent permissions. and available to Designers for use as data sources. You can also configure the column display names and widths displayed to Data Providers in results.

If the Data Service Administrator clears the Is Parameter check box so that this parameter cannot be configured in Database data sources by Designers, then the Data Service Administrator should also clear Is Parameter for SQL Query.

Important! The Result Map is not dynamic. If the columns available in the database have changed, you must ensure that the data service is started and run the query again to see those changes reflected in the data service. In a Database data source, you must run the query again to retrieve changes to the associated data service.

Column Name: The name of the column in the database and as it is displayed to Designers. You cannot change this value in the Result Map.
Required: If selected, generates an error if a row in the query result does not include a value for a the column. You can change this value in the Result Map.
Display: If selected, the column is displayed in results for Data Providers and in the Data Sources pane for Designers. You can change this value in the Result Map.
Display Name: The name of the column as it is displayed to Data Providers. You can change this value in the Result Map.
Type: The data type of values in the column. You cannot change this value in the Result Map.
Display Length: The default width that will be used when displaying the column in the results to Data Providers. Data providers can manually adjust column widths. Changing this value does not limit the length of the data available to Data Providers. You can change this value in the Result Map.
Run Query: Clear the existing Result Map, run the query, and populate the Result Map with the default information about the columns. If you customized the Result map, those changes are removed.
Is Parameter: Selecting this option allows Designers to customize the Required, Display, Display Name, and Display Length values in the Result Map for Database data sources associated with this data service. Clearing this option prevents Designers from viewing or modifying the Result Map, but they can still view the names of columns for which Display is selected.

Note: If you clear the Display check box for a particular column and clear the Is Parameter check box for the Result Map, then Designers cannot use that column as a data source or display it to Data Providers.

Advanced

The following options may be displayed in the Advancedpanel for a JDBC data service. You can also add custom options.

Parameter	Description
Connection Test Query	A database query to be used for verifying whether the JDBC connection is valid. This query is run automatically during attempts to reestablish a connection to the database after a connection error has occurred. Example For an Oracle database, the following query can be used to test whether the connection to the database is functioning. It does not test a specific table. select 1 from dual
Add Parameter	Allows you to configure custom parameters for the data service. For each parameter that you create, you can configure the following: Variable Name: Name displayed to Data Service Administrators in the Configurationpanel of a data service. For a JDBC data service, if you select Is Parameter after you create the parameter, the Variable Name is also displayed to a Designer who creates a Database data source associated with this data service. Data Type: Whether the variable must resolve to a String, Integer, Number, Boolean, Character Large Object (CLOB Character Large Object. A data type designed to store a large amount of character data.), or Binary Large Object (BLOB Binary Large Object. A data type designed to store a large amount of binary data, such as an image.) value. After you have added a parameter, it is displayed in the Configurationpanel. Regardless of the data type selected, a text box is displayed in the data service so that a Data Service Administrator or a Designer can enter a data source to connect to the parameter. A message indicating the required data type is displayed to the Data Service Administrator or Designer when that individual begins to type in the text box for that parameter. For a JDBC data service, selecting the Is Parameter check box for a parameter allows Designers who use the data service to customize that parameter for each Database data source. Clearing the Is Parameter check box hides the parameter from Designers. A Data Service Administrator can delete a parameter created as part of the data service. The parameter is removed from existing Database data sources even if Is Parameter is selected. The default parameters cannot be deleted. Note: While configuring a Database data source, a Designer can add a custom parameter by clicking the Add Parameter Field button. A Designer can also delete parameters added to the Database data source.

Parameter

Description

Connection Test Query

A database query to be used for verifying whether the JDBC connection is valid. This query is run automatically during attempts to reestablish a connection to the database after a connection error has occurred.

Example

For an Oracle database, the following query can be used to test whether the connection to the database is functioning. It does not test a specific table.

select 1 from dual

Add Parameter

Allows you to configure custom parameters for the data service. For each parameter that you create, you can configure the following:

Variable Name: Name displayed to Data Service Administrators in the Configurationpanel of a data service. For a JDBC data service, if you select Is Parameter after you create the parameter, the Variable Name is also displayed to a Designer who creates a Database data source associated with this data service.
Data Type: Whether the variable must resolve to a String, Integer, Number, Boolean, Character Large Object (CLOB Character Large Object. A data type designed to store a large amount of character data.), or Binary Large Object (BLOB Binary Large Object. A data type designed to store a large amount of binary data, such as an image.) value.

After you have added a parameter, it is displayed in the Configurationpanel. Regardless of the data type selected, a text box is displayed in the data service so that a Data Service Administrator or a Designer can enter a data source to connect to the parameter. A message indicating the required data type is displayed to the Data Service Administrator or Designer when that individual begins to type in the text box for that parameter.

For a JDBC data service, selecting the Is Parameter check box for a parameter allows Designers who use the data service to customize that parameter for each Database data source. Clearing the Is Parameter check box hides the parameter from Designers.

A Data Service Administrator can delete a parameter created as part of the data service. The parameter is removed from existing Database data sources even if Is Parameter is selected. The default parameters cannot be deleted.

Note: While configuring a Database data source, a Designer can add a custom parameter by clicking the Add Parameter Field button. A Designer can also delete parameters added to the Database data source.