Parameters

You can create parameters within a business rule component. Each parameter becomes a data map entry that includes a name (key) and a value. The value can be a literal value or can include a reference to another data map entry that is resolved at run time.

Note: You should not define parameters in a conditional business rule component.

Tip: You can configure whether the value of each parameter remains fixed throughout the execution of a business rule component by configuring the sticky attribute of the business rule component.

The following is the syntax for specifying parameters.

Important! Content in a business rule is case sensitive. This includes business rule component names, attributes, and values.

Note: If you create a parameter, you must specify a name for it as the value for parameterKey. You are not required to specify parameterValue. Do not begin and end the name with an exclamation point (!), because that syntax is used for reserved keys.

About the syntax documentation

<parameter parameterKey="Name_of_parameter" dataType="STRING|INTEGER|BOOLEAN|NUMBER|BINARY|DATE" resolveValue="true|false">

<parameterValue>Initial_value_of_parameter</parameterValue>

</parameter>

</parameters>

Built-in Parameters

Loftware Enterprise SP includes built-in parameters for some types of business rule components.

Parameters for dataService

Built-in parameters are available for use in dataService business rule components. The appropriate parameters vary depending on the type of data service.

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.

Parameters for dateTime

Built-in parameters are available for use in dateTime business rule components.

dateTime Parameters

The following built-in parameters exist for a dateTime business rule component.

Parameter	Description
DAYSTOADD	Days to Add. Number of days by which to increment the value specified by the data. To return a time different from the current date and time on the Loftware Application Server, specify a positive or negative amount of time in days, relative to the time of processing. A positive number returns a time later than the time of processing. The default value is 0, which causes the time of processing to be returned.
FORMAT	Format. The date/time format to apply to the data. For a description of the date/time formats and the placeholders available, see Time Values in Loftware Enterprise SP.

Parameter

Description

DAYSTOADD

Days to Add. Number of days by which to increment the value specified by the data.

To return a time different from the current date and time on the Loftware Application Server, specify a positive or negative amount of time in days, relative to the time of processing. A positive number returns a time later than the time of processing. The default value is 0, which causes the time of processing to be returned.

FORMAT

Format. The date/time format to apply to the data. For a description of the date/time formats and the placeholders available, see Time Values in Loftware Enterprise SP.

Syntax Tips

Additional information is available about the following items.

dataType or valueType

The type of data that the component returns or to which it refers. The default value is STRING.

Additional details for specific types of components.

For a parameter, the dataType specifies the data type of the parameter value. For a parameter in a dataService business rule component, the result map for a JDBC data service can be represented as a string.
For a comparison in a condition, the valueType specifies the data type of a value to be compared.
A dateTime business rule component always returns a value with a data type of STRING regardless of the dataType specified.
For an exportData business rule component, only STRING and BINARY are supported for the dataType element.

Value	Description
STRING	A text string. Any number or date/time included is treated as text.
INTEGER	A signed integer value.
NUMBER	A signed decimal value.
BOOLEAN	A value of true or false.
BINARY	An array of bytes.
DATE	A date/time value stored in one of the following formats: Epoch time The number of seconds since 00:00:00 UTC on 1 January 1970, not including leap seconds. yyyy-MM-dd hh:mm:ss

parameterKey

parameterValue

The initial value of the parameter. This value must be of the type specified by dataType. If this value includes a data map entry, whether it is resolved to the value of that data map entry at run time is determined by resolveValue. The value of the parameter can be changed at run time by the business rule.

Representing a result map

For a parameter in a dataService business rule component, the result map for a JDBC data service can be represented as a string in which the values for the columns are separated by vertical bars.

The following is an example of a result map.

Column Name	Required	Display	Display Name	Type	Display Length
QUANTITY			Quantity	number	5

The following is the string representation of the preceding result map:

resolveValue

For a parameter value, whether to treat any data map entries within the parameter value literal text or resolve them to their associated values. The default value is false.

For an XML Data business rule component, whether to treat the value of data as literal XML data or as a data map entry pointing to XML data. The default value is false.

Value	Description
true	For a parameter value, any data map entries within the parameter value are resolved to their associated values at run time. For an XML Data business rule component, the value of data is interpreted as a data map entry that points to XML data, and is resolved to the value to which the data map entry points at run time.
false	For a parameter value, the parameter value is interpreted as literal text. For an XML Data business rule component, the value of data is interpreted as literal XML.

Value

Description

true

For a parameter value, any data map entries within the parameter value are resolved to their associated values at run time.

For an XML Data business rule component, the value of data is interpreted as a data map entry that points to XML data, and is resolved to the value to which the data map entry points at run time.

false

For a parameter value, the parameter value is interpreted as literal text.

For an XML Data business rule component, the value of data is interpreted as literal XML.

Tip: For assistance with a business rule that you have created or to have Loftware create business rules for you, contact Loftware's Professional Services Group.