SearchTask (Integration function)
The SearchTask (Integration function) function allows you to query content from the Lobster Data Platform / Orchestration database (see Search API) in the mapping (phase 3) of a profile.
The search query is defined via the XML structure of a SearchTask object in parameter a, which can be built and tested interactively with the Search builder.
The XML structure can refer in the syntax @PARAM_X@ (with X from {B,C,D,E,F,G,H,I,J}) to the values of the optional parameters b-j from the function call.
Similarly, the syntax @VARIABLENNAME@ can be used to access the values of variables from the context of the profile.
The return value of the function is always the search result of a specific SearchResult object (SearchResult, TupleSearchResult or CsvSearchResult, see Search types) as text in XML format.
The optional parameter k can be used to parse this structure into a named DOM object, e.g. to evaluate this object with the function get value from XML () using XPath expressions.
Parameter
|
Parameter |
Description |
Example |
Note |
|
a |
XML structure of a SearchTask object |
SearchTask
<?xml version="1.0" encoding="UTF-8"?><core:SearchTask ... entity="base:User"> <base:LobsterDataLoginRequest userName="admin" selectedRole="1" selectedCompany="1"/> <core:TupleSearch> <core:SimplePropertySearch projection="address.name1" compareType="=="/> <core:PropertyProjection property="username"/> <groupBy/> </core:TupleSearch></core:SearchTask>
|
A 'query' can be created and tested interactively with the Search builder. The XML structure of the SearchTask object is then displayed in the XML tab. This query definition can then simply be pasted via the clipboard as a static value for parameter a and edited if necessary. Often – in contrast to the very simple example on the left – data from the runtime context in the profile must be included in the search so that it delivers the 'right' results. For this purpose, the XML can be applied to variables or parameters whose values are inserted at runtime from the context of the profile call. Especially for more complex application cases, it can be helpful to integrate the XML structure of the SearchTask object into the target structure of the profile, so that the 'search' can be linked to source data via mapping and dynamically constructed at runtime. Then parameter a is filled using the function create xml from node()(see a more detailed example below). Even then the XML definition can include parameters and variables. |
|
b-j |
Parameters which – similar to regular variables between two '@' characters – can be addressed in the XML definition of the search |
SearchTask
<?xml version="1.0" encoding="UTF-8"?><core:SearchTask ... entity="base:User"> <base:LobsterDataLoginRequest userName="admin" selectedRole="501" selectedCompany="@MSG_CALL_SCM_Company_id@"/> <core:TupleSearch> <core:SimplePropertySearch projection="@PARAM_B@" compareType="=="/> <core:PropertyProjection property="@PARAM_C@"/> <groupBy/> </core:TupleSearch></core:SearchTask>Based on the above example, parameters and variables were inserted here:
|
To get the same search results as in the static case above, the following conditions must be met:
|
Examples
In the following example, all Shipments with the working status 'Released' (RELEASED) are searched.
The corresponding search was built via the Search builder and inserted via the menu item Orchestration templates as a sub-node SearchTask to the node SearchNode (with the option set 'Only for SQL') (see Creating static target structures).
The execution of the Search is triggered by function calls for the executeSearch field in the Data node:
The function create xml from node()returns the XML of the SearchTask node:
The XML structure of the SearchTask node is taken as result in parameter a of the SearchTask (Integration function) function, which executes the search and stores the result in the DOM object searchResult (parameter k)
The following getResult field uses the function get value from XML()to evaluate the DOM object with an XPath expression:
In the example, the getResult field is assigned the ID (id) of the first shipment that the Search returns.
A Tuple search should identify a specific Users account in Lobster Data Platform / Orchestration via two parameters (username, and address.accNumber) and – if a match exists – return its ID (id).
|
|
As in the previous example, the Search builder (left) is used to build a suitable SearchTask object. The references to parameters can be entered directly as comparative values in the respective conditions. Ideally, this is only done after the query has been tested with concrete sample data. The XML structure of the SearchTask object can then be displayed in the XML tab. For the current example the following structure results:: XML
<?xml version="1.0" encoding="UTF-8"?><core:SearchTask ... entity="base:User" skipCsvEnvelope="false" tryUseExistingConnection="true"> <base:LobsterDataLoginRequest ... /> <core:TupleSearch> <core:SearchJunction junction="CONJUNCTION"> <core:SimplePropertySearch projection="username" compareType="==" stringValue="@PARAM_B@"/> <core:SimplePropertySearch projection="address.accNumber" compareType="==" stringValue="@PARAM_C@"/> </core:SearchJunction> ... <core:PropertyProjection property="id"/> ... <groupBy/> </core:TupleSearch></core:SearchTask>From the XML tab in the Search builder this structure can be copied to the clipboard and pasted as the value of a variable in the profile:
|
As a concrete use case, the Tuple search with changing parameters predefined in the variable var__searchUserId shall be used to update the accounts of certain Users via Batch import.
►NOTE◄ Since the Tuple search identifies the Users to be updated through the returned ID (id), the search node can be disabled in the batch node of the import if assigned as a value for the id attribute in the User node.
In the batch node of the BatchImport structure a calculation field searchUserId has been added, which links two function calls:
First, the SearchTask (Integration function) function selected in the screenshot above is called, which accesses the variable var_searchUserId via parameter a.
The 'search parameters' b and c are assigned values of source fields ('username' and 'account') so that each iteration of the batch node performs an individual search.
The search result is stored by parameter k as a DOM object named searchResult.
The function get value from XML()accesses the value of the first column (item[1]) of the first row (row[1]) within the result node of the TupleSearchResult structure (see Tuple search) via the XPath expression //row[1]/item[1]. Since the search uses only one projection (id), this is the ID of the first match, if there are any matches at all. This value is assigned to the searchUserId field as the calculation result. The id_attr field in the User object can copy this value to the target searchUserId field, for example, using the function copy().
Within a profile, a Tuple search is intended to find all Users whose address is assigned a specific account number (address.accNumber) in order to check whether this account number is uniquely assigned.
|
|
The Search builder (left) is used to build a suitable SearchTask object. Here the reference to the parameter b can be entered directly as a comparison value in the respective conditions. Ideally, this is only done after the query has been tested with concrete sample data. The XML structure of the SearchTaskobject can then be displayed in the XML tab. For the current example the following structure results: XML
<?xml version="1.0" encoding="UTF-8"?><core:SearchTask ... entity="base:User" skipCsvEnvelope="false" tryUseExistingConnection="true"> <base:LobsterDataLoginRequest ... /> <core:TupleSearch> <core:SimplePropertySearch projection="address.accNumber" compareType="==" stringValue="@PARAM_B@"/> ... <core:PropertyProjection property="id"/> <core:PropertyProjection property="username"/> <groupBy/> </core:TupleSearch></core:SearchTask>This structure is copied directly from the XML tab in the Search builder to the clipboard. |
In the target structure a calculation field is provided with two function calls
First, the SearchTask (Integration function) function is executed with parameter a for assigning the XML structure from the clipboard as static text value.
Parameter b is linked to a source data field account , which defines the account number to be checked.
The search result is stored by parameter k as a DOM object named searchResult.
The DOM object searchResult (parameter a) returned as search result is then evaluated with the function get value from XML().
The XPath expression (//@count) returns the number of lines within the TupleSearchResult structure (see Tuple search), which are passed as an attribute in the search header.