DesignCreate a Database Data Source

To create a Database data source, a DesignerClosed Person who creates and designs label templates, forms, and applications for use by Data Providers. should use this procedure.

Before You Begin: A Data Service AdministratorClosed A local administrator who creates and configures data services for use by Designers who configure Database data sources and Alternate data sources. must create the data service with which you intend to associate the Database data source. (If you are a Data Service Administrator, see Configure a JDBC Data Service for more information.)

  1. In Label Design Label Design or Application Design , open an existing label template or form, or create a new label template or form.
  2. In the View tab, click Data Sources.
  3. Click Database, and click Add Data Source. The Database Data Source dialog box is displayed.
  4. In the General Data box, enter a Data Source Name by which to refer to this label data source.

    Note: The name of a label data source can include letters and numbers. Additionally, the following characters are permitted but cannot begin or end the name: double quotation marks, single quotation marks, grave accents, hyphens, underscores, and periods.

  5. If you want to specify where in the data map the database search result should go, enter text in the Data Ref field. Otherwise, you can leave this field blank.
  6. In the Data Service box, select the data service to use, and then click Next.
  7. Edit the data service configuration. Depending on how the data service is configured, you may be able to edit some of the configuration information or data service parameters that were provided by the Data Service Administrator.
    1. If text boxes are displayed, you can enter either static values or data refs using the format ${<DataRef>}. After you begin typing in the field, a message may be displayed about the type of data required until you finish entering a value or data ref. For information about default parameters, see Configuration Parameters for JDBC Data Services.
    2. If a Result Map is displayed, you can configure which columns are displayed to a Data ProviderClosed 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.. For more information, see Configuration Parameters for JDBC Data Services.
    3. If you want the Data Source Results dialog box to display so the Data Provider must manually click a row to select it, leave both Auto Select First Row or Auto Select Single Row check boxes clear.
    4. If you want to automatically insert data into the form from the first row returned by the SQL Query, select the Auto Select First Row check box. If this option is selected, the Data Source Results dialog box is not displayed.
    5. If a single row is returned by the SQL query and you want to automatically insert the data into the form, select the Auto Select Single Row check box. If this option is selected, the Data Source Results dialog box is not displayed.

      Note: If you select this option, it is recommended that you include at least one Prompt field in the Form that is populated by the results to provide confirmation to the Data Provider that the query was executed.

    6. When you have finished configuring the data service parameters, click Next.
  8. If the label template must support on-demand printing, click Add Trigger and configure at least one triggerClosed A means of running an action, rule, or data service. Includes a trigger source if interactive (such as a button, a prompt, or a form) and a trigger event (such as clicking a button, entering text at a prompt, loading a form, or submitting a job). For example, you can specify a particular button as a trigger source that Data Providers can click to perform a query of a database. that a Data ProviderClosed 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. can use to run the SQL Query on the database. Repeat for additional triggers if needed.

    Tip: If you have not yet created the field that should serve as the Trigger SourceClosed A field that is used in conjunction with a trigger event to interactively run an action, rule, or data service. For example, a button that runs a query when clicked, a prompt that runs a query when submitted, or a form that runs a query when loaded., you can skip this step and select the trigger when you create the field.

    • To query the data source when a button is clicked, for Trigger Source select the name of a Button field and for Trigger Event select onClick.
    • To query the data source after submitting data at a prompt, for Trigger Source select the name of a Prompt field and for Trigger Event select onCommit.
    • To query the data source when the form is loaded, for Trigger Source select /Body and for Trigger Event select onLoad.
  9. If the label template must support both on-demand printing and integrations, click Add Trigger again.

    Note: If the label template is not required to support on-demand printing, then no trigger is needed.

    1. For Trigger Source, select Do Not Run.
    2. For Trigger Event, select Enqueue.
    3. For Trigger Key, enter the name of a data map entryClosed A name (key) and value pair in the data map for a job. that will manage whether the data source should be run. It is recommended that this data map entry not be used for any other purpose. The value of this data map entry does not affect how it functions as a trigger key.
      • When the trigger key exists in the data map, the data source will not run. This is appropriate when using the label template with an integration. This is also appropriate if you need to prevent the data source from running in some situations when using on-demand printing.
      • When the trigger key does not exist in the data map, the data source is run. This is appropriate when using the label template for on-demand printing.

      Important! For an integration, if the data map entry specified for Trigger Key does not exist, then the data source is queried and the first row of data is automatically returned. This occurs regardless of whether Auto Select First Row and Auto Select Single Row Result are selected.

  10. Assigning values for Trigger PriorityClosed The order in which actions, rules, or data services that have otherwise identical triggers are run. Priority values are compared only if the actions have the same trigger source, trigger event, and trigger key (if any). The type of trigger source is irrelevant. Among actions, rules, or data services with otherwise identical triggers, the trigger source with the lowest value for priority is run first. is necessary only if more than one data source in a label template includes a trigger with the same trigger source, trigger event, and trigger key (if any). In that situation, you can assign different values for Trigger Priority for these otherwise identical triggers, and the data source with the lower value for Trigger Priority is run first.
  11. Click OK.

In the Data Sources pane, the Database section now lists the Database data source that you created. Expand the Database data source to display the names of columns from the database that you can use as data sources. You can drag a column data source onto a field in the Label view such as a Variable Text or Barcode field to assign the data source as the data ref for that field, or you can enter a data ref manually. You can create a formula and select the data refs for the database columns for use in the formula.

Note: The format by which to refer to a database column data source is /<DatabaseDataSourceName>/<ColumnName>.

Important! You can configure how a data source runs by clicking and dragging Run Data Source from the Insert tab to a control, a form, or the Form view of a label template. For more information, see Adding Controls, Label Template Properties and Commands, or Form Properties.