Management of search containers (complex searches)

Introduction

The search containers (formerly called Complex searches) are used to select data from the application. They are used in many areas, primarily to provide data to applications connected via interfaces: Word documents, Excel sheets and Jasper reports receive their data via such search containers.

The structure of the search containers in the form "1 main search is linked to n sub-searches" was chosen for the following reasons:

• Clarity: Each of the partial searches can select area-related data independently of the other partial searches.

• Simple execution of complex search queries: Several searches are executed sequentially in one step. The selection results of individual searches are used as selection criteria in the subsequent searches. The result is a mixed dataset that is made up of the selection result fields of all searches.

• Possible to represent an 'OuterJoin': Even if no data is found in one of the partial searches, a result dataset is determined. The selection result fields of the unsuccessful partial search simply remain empty.

Complex searches are configured in the Search container management node.

Each search container can be assigned to a category. Such an assignment means that only those search containers are available in the corresponding administration area that are assigned to it via the appropriate category.

Structure of the search containers

A search container can consist of any number of partial searches. Such a collection of searches must of course be brought into a structural order. The entry in the "Type" column is used for this purpose. Different types of partial searches are available depending on the category of the search container.

*This refers exclusively to an export, which is called via the Evaluations\Excel-Export menu. An export via the mask script or BPM is only possible when using a search container with a main search.

The three most important search types are presented below using the example of single letters.
The three possible search types Main Search, Detail Search and Table Search are available here. There is a basic specification: the first search in this order (and only this one) is assigned the type Main Search.

Search type Main Search

The "Main search" type elevates the search set in this way above the other search. By default, each of the other partial searches are linked to it. This results in a two-level hierarchy: the main search is on the upper level, the other searches on an equal ranking on the lower level. The main search has three special characteristics compared to the other searches:

• Its search mask is displayed to the user during serial tasks and evaluations so that he can restrict the result set. This means that only the fields of this search are available to the user as input fields.

• The main search is the only search in the search container that can receive information from the application at the time of execution. This information is passed to the search as a parameter. The search can then use it to restrict the selection or pass it on to the other partial searches as its own output parameter.

• The main search is the only search that can provide values for the other searches. This is done using the output parameters. (The only exception here is when a table search is linked to a detail search for search containers of the "QUOTE" type in order to obtain further information on an entry in the quote table, such as a picture of the offered item.)

Search type Detail Search

A detail search is an advanced search that is linked to the main search (or, in the special case described above, to a table search) via the input/output parameters.

Detail searches are usually used to select data from other entities. The following special features apply to detail searches:

• The link to the main search is made via an OuterJoin link. This means that even if one or more detail searches do not select any data, a result is determined on the basis of the other successful searches. The selection result fields of the unsuccessful detail searches remain empty in this case. Example: If the contact person is selected in a detail search for a customer in the main search, the selection result will always be successful, even if no contact person exists for the customer.

• Reusability: Often you want to use the same fields several times when selecting data from an entity. This is the case, for example, if you want to output several employees in one letter: the office employee, the field service employee and the logged on employee. For this purpose, an "employee" detail search can be included several times in the search container. It is then linked to the appropriate field in the main search using the output parameters.

• Clarity: By dividing a query over many areas into several detail searches, the search container remains easy to understand.

Search type Table Search

The table search is used to select data that is displayed in a single letter document (quote, contract, single letter) or in a report in the form of a table. For example, all quote items can be output in the form of a table in a quote document. In the default case, the table search is linked to the main search using the input and output parameters. In the example, the table search receives the quote number for which it is to deliver the items as input parameter. (If the table search is not linked to the main search, all selected data of this table search is displayed in the document. Such a link is more likely to be the exception.)

Procedure for creating a search container

The easiest way to create a new search container is to take an existing one and create a copy using the Copy button in the top toolbar. The search container is copied in full along with all partial searches. Changes to the new partial searches created in this way have no effect on the original search.

If a search container is to be created from scratch, the following steps must be carried out:

1. In the design phase, the desired search results are grouped according to entities or independent units of content. Each of these groups corresponds to a search.

2. Creating a new search container under a unique name via the button of the same name.

3. Create or add the partial search(es). The smallest search container consists of a single search, which is of the type "Main Search". It does not require any output parameters, since there are no searches to be linked.

4. Define the main search with sequence number 1. This search has the type Main Search.

5. Optional definition of detail searches. Any number of detail searches can be defined.

6. Optional definition of table searches. Any number of table searches can be defined. Generally, the table search is linked to the main search, but this is not absolutely necessary.

7. The added searches must be linked via the input/output parameters.

8. Save the new search container with automatic validation.

You can create the partial searches manually as XML descriptions and import them using the administration console (Search / Import Complex Searches node). See the instructions on creating advanced searches.

Linking of partial searches

As soon as the search container consists of more than one partial search, the task is to link these searches together. The application requires such links: A search container that contains an unlinked detail search cannot be saved. The following links of partial searches are possible:

• Main search with detail search

• Main search with table search

• Table search with detail search (the exceptional case described above for "QUOTE" type search containers)

A link in the form "Detail search with detail search" is not possible.

In the case of a link, we speak of a leading and a dependent search. The leading search passes its link information via an output parameter that the dependent search receives via its input parameters. In a search container, the main search is always the leading search. It returns the output parameters that the detail search receives as a dependent search.

The text below describes the default case "Main search with detail search". (The exceptions can be derived from the explanations.) As an example, we define the following: A business partner is selected in the main search. The Employee Office is to be found for this business partner in a detail search. Both searches are available as partial searches. This results in the following procedure for our example:

1. The "Employee Office" field must be available in our main search. In addition, the check mark for "Export in search result" must be set in its properties dialog box.

2. Double-clicking on the "Output parameter" field in the main search opens the corresponding dialog. After clicking on "Add" in the list displayed in the left-hand column, select the "Employee Office" field. Enter a name for the new output parameter in the right-hand column. In the example, we call the new parameter "MIT_ID". The dialog then closes.

3. We now switch to the detail search for the employee. Here you have to perform two actions: prepare a field in the search to accept the output parameter (step 4) and then enter the link in the "Input parameter" column (step 4).

4. In our example, we get the Employee Office as output parameter. However: what exactly do we get? The employee's token or their name? Surprisingly, it is a value that usually remains in the background: the primary key. This is actually stored in these lookup fields. It is automatically replaced on the mask by a more understandable field (in this case the employee token). In the detail search we must now take this into account. We do this by including the "primary key" field in this search. Here, too, we check the box by "Export in search result".
   Now we have to set this "Primary key" field to a state where it can be compared with the output parameter "MIT_ID". To do this, we select the condition "is one of". From the list of parameter values offered, we select "Placeholder (filled at execution time)" and add it to the list by entering <RETURN>. Then we close the dialog.

5. As the last step of the link, we now create an input parameter for the detail search. There we double-click on the Input parameters field. After clicking on "Add" we select from the left-hand column the only value offered: the "Primary key" field. This is due to the setting made under step 4 "Is one of" - "Placeholder (filled at execution time)".
   In the right-hand column we select from the list the appropriate output parameter from the main search: here the value "MIT_ID". After closing the dialog, the necessary actions are performed. The search can now be saved.

It can therefore be summarized: the main search provides the output parameters that are then used as criteria (input parameters) by the dependent partial searches. (The same applies to the link between table search and detail search.) Parameters are variables in which the selection result of individual fields of a search is stored temporarily. In the leading search, the output parameters are defined in the Output Parameters column. In the dependent search, you can use these output parameters in the Input Parameters column. In this case, the output parameter is assigned to a field of the dependent search.

Input parameters for the main search

The foregoing relates to linking of searches with each other. However, the same procedure is also used when it comes to determining which data the main search should find. While the user is asked directly via the search mask for the conditions for data selection in reports and serial letters, the appropriate data is "automatically" included in the single letter. Here, therefore, the suitable selection criterion is entered in the background in a certain form "by the application". Parameters that are passed to the main search are also used for this selection.

This can be clearly displayed on a search container for single letter templates: in such single letter searches, the main search is based on the "Activities" entity. Since this main search functions as a dependent search, you must perform the steps listed above in steps 4 and 5 for the detail search:

1. You must include the "Primary key" field from the Activities entity, again with the check mark for "Export in search result" and the condition "Is one of" - "Placeholder (filled at execution time)".

2. Then, in the main search, go to the "Input parameters" column and select this field in the left-hand column as described above. In the right-hand column you get a list of parameters which you have not stored yourself, but which are provided by the application: among others, these are PK, PARENTPK, PKCOPE, USERPK... For our search the entry PK is the correct value. This is used to transmit the primary key of the entity that is currently open. This entity is the open activity. This means that the main search can restrict the search condition to exactly this activity.

The available parameters have the following contents:

• PK: The value of the primary key from the current entity.

In the case of the single letter in the activity, this is the primary key of the activity.
In the case of the quote document, this is the primary key of the quote.

• PKCOPE: The value of the primary key of the selected contact person from the activity.

  

  Hinweis

  This parameter is only available in the single letter.

• PARENTPK (special case entity-specific single letter): The value of the primary key from the master entity. Usually the primary key of the entity in which the activity was created, for example, customer, contact person, and so on. (see special case entity-specific single letter).

Conditions for the links

• The parameters PK, PARENTPK, PKCOPE are reserved and must therefore not be used as output parameters.

• The input parameters must be unique. This means that in the dependent search, an input parameter can only be assigned to a field once. It is therefore not possible to assign another field to this input parameter. As an alternative to this, a second output variable with the same content could be defined in the leading search.

• The output parameters can be used more than once in the search. This means that in the leading search, an output parameter can be assigned to several fields simultaneously. This makes it possible, for example, to select several business partners within the search container and present them to the user.

• When defining an input parameter, only existing output parameters can be used as variables (this is already ensured in the application)

• When defining an input parameter, you can only use fields that are defined as placeholders (filled at execution time) (this is already ensured in the application).

• Input parameters of the main search (for example: PK, PARENTPK, PKCOPE) cannot be used in other partial searches. If this is desired, these input parameters must be provided as output parameters in the main search.

Example:

Conditions for search containers

• There is exactly one main search. This must be in the first position in the list of searches (sequence number 1).

• There are no or any number of detail searches.

• There are no or any number of table searches.

• For each search, the administrator must assign a unique name (Alias Name column) within the complex search.

• All detail searches must be linked to the main search or a table search.

• A table search must not be linked to another table search. It can be linked to the main search or not linked at all.

• At least one field with the Show in lists attribute activated should exist for each main and detail search. Background: Duplicates may appear in the selection dialog, since the identifying detail data is not displayed.

• Linking the partial searches fulfills the conditions mentioned above.

• Each field that uses the Placeholder (filled at execution time) argument must be defined as an input parameter.

• No search result fields may be used in optional queries.

All conditions listed here are checked in the background when a search container is saved. If there is an error, a message is displayed. The search container can only be saved when all criteria are fulfilled.

Hints for creating search containers

Figure: 'Show in list' search field attribute

If the result set generated for an advanced search contains several datasets, a selection list is displayed. This list only contains fields from the search for which the 'Show in list' attribute has been set.

Example: Serial letter - Dialog for selecting the address data.

When creating an advanced search, you should therefore activate the Show in selection lists attribute for fields that make the selection result identifiable. This attribute can be set for the relevant fields using the Edit search button.

Figure: Problems when creating extended searches via the GUI

If several searches are linked, the input parameters must be defined as execution time placeholders.

Notes on standard document searches

Single letter in the activity

The Activity with field must contain a contact person. The following information should be present in the contact person:

• Address

• Department or Department Addition

• Salutation

• Letter Salutation

Serial letter

The following conditions apply to the default serial letter search:

• They can only be sent to contact persons.

• Each contact person is assigned to a business partner.

• The serial letter checkbox is set at the contact person.

• The contact person has a postal address.

Serial email

The following conditions apply to the default serial email search:

• They can only be sent to contact persons.

• Each contact person is assigned to a business partner.

• The serial email checkbox is set at the contact person.

• The contact person has an email address.

Quote generation

The following conditions must be met in the quote:

• The contact person must be populated in the quote. As with the single letter for the activity, the above information on the contact person should be present.

• The quote must be assigned to an inquiry.

• The main business partner must be populated in the inquiry.

• Ideally, the following fields should be populated, but this is not absolutely necessary:

  • Quote Date

  • Quote Value (sum of he items)

  • Quote Currency

    • Nachtext3
      The image for the quote document can be selected in the Posttext3 field on the Profile tab.

    • Pretext1

    • Nachtext1
      Optionally, a text module can be selected in the fields Pretext1-3, Posttext1-2, Terms of Delivery and Terms of Payment.

    • Signatory1 and Signatory2 (employees)

    • Fields in the employee: Signature, Department, Telephone extension.

Mini serial letter
It is already possible to select several addressees. A corresponding number of single letters are created and assigned to the entity. However, there is no synchronization between the generated documents. The changes must be made manually in each individual document.