Data Service Block: Get First Row

In a business rule designed in the Configurator, you can add a Get First Row component block to retrieve the first row in the result of a query of a JDBC data service and add the data to the data map A repository for the data for use when responding to a print request. Each data map entry is composed of a name (key) and a value..

Tip: Before you can add a component block to a business rule, you must create a component set by specifying a trigger that controls when component blocks in the component set are run.

Property	Description
Data Ref	A property of the print job or the name of a data map entry where the row of data will be saved to the data map. If the data map entry does not already exist, it is created. Tip: Unless the query is designed to retrieve a value appropriate for one of the items in the following list, it is recommended that you select Manually Entered and enter the name of a data map entry where the row of data can be saved. You can select from the following for a data ref. Manually Entered A property that allows a Designer or administrator to type in the value for a property rather than select it from a list. For a data ref, value must be the fully-qualified name of a data map entry. Job Detail Name A digital representation of a label generated by a print job. Job details can be altered during the print job by using Formula data sources, Script data sources, and business rules. Job Name What is submitted for processing. A job is separated into print jobs and print job details based on the processing rules. A job defines which processes to use. Label Template A digital representation of a label that can be combined with variable data and used by print jobs to generate print job details. Number of Duplicates The number of times to reprint a label by using the same data and without changing the value in any incrementing or decrementing field. Each duplicate printed label is identical. Pages of Labels The number of times to print the content for the labels in a layout. Each page is identical, including the value in any incrementing or decrementing field. Printer A physical printer, print queue, or other target for output, such as an image file or a PDF file. Printer Tray To which output tray to direct printed labels or documents. If a printer has only one output tray or otherwise does not support this feature, this is ignored. For Windows drivers the tray is the name of the tray that supplies the paper. The name corresponds to the configured tray name in the driver setup (not case sensitive). For PCL 5e drivers the tray is the ID number of the tray that supplies the paper. The ID corresponds to the configured tray number in the driver setup. Quantity of Labels The number of times to print a label by using the same data. Each printed label produced is identical except for any incrementing or decrementing field.
Data Service	The fully-qualified path to an existing data service in Loftware Enterprise SP. Tip: You can use the Relative Path check box to control whether the path is represented as an absolute path or a relative path. Using a relative path may be helpful if an object is likely to be transferred to a different Loftware Enterprise SP instance A Loftware Application Server and a Loftware Database Server that are associated with each other by a Loftware Enterprise - SP License.. The check box is available to select after the object has been saved for the first time. For more information, see Relative Paths.
Use Parameters?	Whether to add parameters for use in the data service. Note: This functionality is comparable to editing the data service in Data Services and adding parameters. However, the parameters exist only when this business rule is used to run the data service. Tip: You can use a parameter to define the query to be run by the data service. Tip: You can add or remove parameters by clicking or .
Parameter Name	The name (key) of a parameter that can be used in the data service defined in Data Services . For a list of built-in parameters, see the section following this table.
Parameter Value	A print job property or the name of a data map entry to be used in the data service. Also, whether to interpret it as a literal value or as a data map entry. If the data map entry does not already exist, it is created. You can select from the following for a data ref. Manually Entered A property that allows a Designer or administrator to type in the value for a property rather than select it from a list. For a data ref, value must be the fully-qualified name of a data map entry. Job Detail Name A digital representation of a label generated by a print job. Job details can be altered during the print job by using Formula data sources, Script data sources, and business rules. Job Name What is submitted for processing. A job is separated into print jobs and print job details based on the processing rules. A job defines which processes to use. Label Template A digital representation of a label that can be combined with variable data and used by print jobs to generate print job details. Number of Duplicates The number of times to reprint a label by using the same data and without changing the value in any incrementing or decrementing field. Each duplicate printed label is identical. Pages of Labels The number of times to print the content for the labels in a layout. Each page is identical, including the value in any incrementing or decrementing field. Printer A physical printer, print queue, or other target for output, such as an image file or a PDF file. Printer Tray To which output tray to direct printed labels or documents. If a printer has only one output tray or otherwise does not support this feature, this is ignored. For Windows drivers the tray is the name of the tray that supplies the paper. The name corresponds to the configured tray name in the driver setup (not case sensitive). For PCL 5e drivers the tray is the ID number of the tray that supplies the paper. The ID corresponds to the configured tray number in the driver setup. Quantity of Labels The number of times to print a label by using the same data. Each printed label produced is identical except for any incrementing or decrementing field.

Built-in Parameters

JDBC Data Service Parameters

The following built-in parameters exist for 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..

Parameter	Description
batchSize	Batch Size. The maximum number of rows returned by the query. You can specify up to 1000 rows.
password	Database Password. The password associated with the user name used when establishing a connection to the database.
query	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.
url	JDBC Connection URL. The connection string for the database used for this data service. For information about the format, see JDBC Connection URL Formats.
username	Database Username. The user name used when establishing a connection to the database.

File Data Service Parameters

The following built-in parameters exist for a File data service A connection to a plain text file or an image file that is external to Loftware. A File data service or an HTTP data service drives Alternate data sources used in documents..

Parameter	Description
fileMaxSizeMb	Max Size (MB) The maximum amount of data to retrieve from the external file for use in Loftware Enterprise SP. Note: A maximum data size of 5 MB is recommended and set by default.
fileTextData	Data Type Whether the URL points to an image, PDF, plain text, or XML file. The following values can be used. Image: Data is an image or a PDF file. Note: Loftware Enterprise SP supports images that use an RGB color model and one of the following file formats: PNG, GIF, JPG, BMP, SVG, or PCX. Text: Data is free form plain text. XML: Data is an XML file. These values are not case sensitive. If not explicitly defined, the default value is Image.
password	Password The password associated with the user name used when establishing a connection to the URL.
resultMap	Result Name A name by which to refer to the data returned by the data service. To print an external file such as a PDF without associating the file with a label template, enter the !INLINE_DOCUMENT! reserved key.
url	URL The URL pointing to the external file from which data can be retrieved. For information about the format, see URL Formats for File Data Services. Note: A Designer who can change this parameter can access any file.
username	Username The user name used when establishing a connection to the URL.

HTTP Data Service Parameters

The following built-in parameters exist for an HTTP data service A connection to plain text data or image data that is external to Loftware. A File data service or an HTTP data service drives Alternate data sources used in documents.. The accepted values for a parameter or whether the parameter is valid may vary depending on whether the value of fileRequestMethod is GET or POST.

Parameter	Description
custom	Custom Content Type For a custom data type, the type of data to send using the format type/subtype. This parameter is valid only if the value of fileTextData is Custom.
fileMaxSizeMb	Max Size (MB) The maximum amount of data to retrieve from the external file for use in Loftware Enterprise SP if using the GET method, or to send from Loftware Enterprise SP if using the POST method. Note: A maximum data size of 5MB is recommended and set by default.
filePostBody	Body The data to send to the URL. For text-based data types, you can enter the data, formatted as appropriate for that data type. Alternatively, you can enter the fully-qualified name (key) of a data map entry A name (key) and value pair in the data map for a job. for which the value is the data to be sent. For Image, PDF, and Custom data types that are not text-based, you must use the latter approach. This parameter is valid only if the value of fileRequestMethod is POST. The expected format of the data depends on the value of fileTextData.
filePostData	Data Type if using POST method The data type of the data to send via the URL if using the POST method. The following values can be used. Custom: Data is of a custom data type defined by the custom parameter. Image: Data is an image. Note: Loftware Enterprise SP supports images that use an RGB color model and one of the following file formats: PNG, GIF, JPG, BMP, SVG, or PCX. JSON: Data is a standard JSON package. PDF: Data is a PDF file. Text: Data is free form plain text. XML: Data is an XML file. These values are not case sensitive. If not explicitly defined, the default value is Text. This parameter is valid only if the value of fileRequestMethod is POST.
fileRequestMethod	Request Method Whether the HTTP data service uses the GET method to retrieve data or the POST method to send data. GET: Request data from a specified URL. Data is passed in the URL. (Default) POST: Send data to create or update a resource at a specified URL. Data is passed in the request body. Note: This value is case sensitive.
fileTextData	Data Type if using GET method The data type of the data to retrieve via the URL if using the GET method. The following values can be used. Image: Data is an image or a PDF file. Note: Loftware Enterprise SP supports images that use an RGB color model and one of the following file formats: PNG, GIF, JPG, BMP, SVG, or PCX. Text: Data is free form plain text. XML: Data is an XML file. These values are not case sensitive. If not explicitly defined, the default value is Image. This parameter is valid only if the value of fileRequestMethod is GET.
password	Password The password associated with the user name used when establishing a connection to the URL.
resultMap	Result Name Required. A name (key) by which to refer to the data returned by the data service. To print an external file, such as a PDF, without associating the file with a label template, enter the !INLINE_DOCUMENT! reserved key. When the POST method is used, the result name receives the response code for the HTTP transaction, such as 200 OK or 404 Not Found.
url	URL The URL pointing to the external file or endpoint from which data can be retrieved or sent. Examples A file name is typically used when retrieving data and a folder name when sending data. https://www.example.com/Folder/File.txt https://www.example.com/post Note: A Designer who can change this parameter can access any file.
username	Username The user name used when establishing a connection to the URL.

SOAP Web Service Data Service Parameters

The following built-in parameters exist for a SOAP Web Service data service.

Parameter	Description
ADD_JSON_TO_MAP	Whether to allow JSON data to be added to the data map. Tip: If you set this parameter to true, you can set ADD_XML_NODES_TO_MAP to false so that only JSON data is added to the data map.
ADD_RAW_XML_TO_MAP	Whether to allow raw XML data to be added to the data map. Tip: If you set this parameter to true, you can set ADD_XML_NODES_TO_MAP to false so that only raw XML data is added to the data map.
ADD_XML_NODES_TO_MAP	Whether to allow XML nodes to be added to the data map.
ADDRESS	Web Service Address. The link for connecting to a web service.
authType	Authentication Type. The authentication type for connecting to the web service. None: Do not require authentication. Basic: Require a user name and password to connect to the web service.
ENVELOPE	Envelope. The XML for the SOAP envelope element. This is the root element of a SOAP message and defines the XML document as a SOAP message.
HTTP_HEADERS	HTTP Headers. The names and values that define the operating parameters of the HTTP transaction.
password	Password. The password of the credentials to use when connecting to the web service.
RESULT_PATH	Result Path. The path to the subset of data that you want returned from the web service. If XPATH_OVERRIDE is true, this is the XPath expression of the subset of data that you want returned from the web service. For more information, see Example: Result Path and XPath Override below. If XPATH_OVERRIDE is false, this value is not used.
resultMap	Result Name. The name of the XML Data business rule component to be used. The default name is WS_RESULT.
SECURITY_HEADER	Security Header. A security header that provides credentials for connecting to the web service.
username	User Name. The user name of the credentials to use when connecting to the web service.
WSDL_URL	WSDL URL. The link to a Web Services Description Language (WSDL) that you can use to communicate with a web service. A WSDL is an XML-based language for defining an interface. A WSDL describes how a service can be called, what arguments can be used, and what type of data is expected to be returned.
XPATH_OVERRIDE	XPath Override. Whether to define the subset of data that you want returned from the web service by the XPath expression entered as the Result Path. For more information, see the example that follows. true: The value of RESULT_PATH is the XPath expression of the subset of data that you want returned from the web service. false: The entire data set is returned.

Example: Result Path and XPath Override

If the configuration of the web service in Data Services contains the following values:

Result Path	/getCountryResponse/country
XPath Override

Result Path	/[local-name()='Envelope']/[local-name()='Body']/[local-name()='getCountryResponse']/[local-name()='country']
XPath Override

and the SOAP response from the web service is the following:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Header/>

<SOAP-ENV:Body>

<ns2:getCountryResponse xmlns:ns2="http://spring.io/guides/gs-producing-web-service">

<ns2:country>

<ns2:name>Spain</ns2:name>

<ns2:population>46704314</ns2:population>

<ns2:capital>Madrid</ns2:capital>

<ns2:currency>EUR</ns2:currency>

</ns2:country>

</ns2:getCountryResponse>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Then the following data map entries result:

/Body/name/!TEXT! Spain

/Body/population/!TEXT! 46704314

/Body/capital/!TEXT! Madrid

/Body/currency/!TEXT! EUR

For more information about XPath, see "Scripting, Java, and XML" in External Links.