core: FindEntity (Preprocessor)

The FindEntity preprocessor is used to access an entity (or its ID or other data) in an Import for another entity. The data returned by the preprocessor is applied to a newly created target element within the parent XML node. This target element virtually replaces the preprocessor node within the XML structure of the imported entity.

►NOTE◄ If the referenced data concerns an XML attribute of the imported entity, the preprocessor core:FindEntityAttribute (Preprocessor) must be used.

The following structure can be integrated into the import structure by loading the template preProcessor:FindEntity (see Lobster SCM templates) at the position where a target element with the data of the entity to be integrated should appear at runtime.

The entity to be integrated is determined by a Search. Only the first match will be considered as a search result.
Optionally, a Wertauflöser can be defined to specify a detail from the data of the referenced entity as a return value.

images/download/attachments/58590306/image2020-9-28_11-12-36-version-1-modificationdate-1601284358140-api-v2.png

Parameter	Type	Meaning	Content (fixed value/example)
xsi:type	String attribute	type of preprocessor	`core:FindEntity`
type	String attribute	entity type for the Search to be performed	base:Role
target	String attribute	name of the target element replacing the `preProcessor` node	role
returnId	Boolean attribute	defines the return value (only ID or complete entity)	`true / false`
`search`	Subnode	defines a Search for the specified entity type	See example
resolver	Subnode	defines a Wertauflöser to apply to the returned entity	See example

►NOTE◄ The Wertauflöser (resolver) is disregarded if the parameter returnId is set to true, as this returns only the ID (id) instead of an entity.

Example:

By a Single import, a new user 'importDemo' should be created, assigned to the role 'Administrator' and the company 'SL Germany'. This user should also be assigned the address of the company 'SL Germany'.

Since a user cannot be created without a password, the passwordHash attribute is used to assign a default password (see Importing user accounts with a password).
The first preprocessor appears in the roles element of the base:User object, where the ID (returnId:true) of the 'Administrator' role is searched for at runtime. It creates a target element of the element type role.
The second preprocessor appears in the companies element of the base:User object, where the ID (returnId:true) of the company 'SL Germany' is searched for at runtime. It creates a target element of the element type company.
The third preprocessor appears defined as a target element the user's address node and assigns the address of the company 'SL Germany' to it, which is determined from the search result by a Wertauflöser.

Altogether, the Single import is defined by the following XML structure:

<?xml version="1.0" encoding="UTF-8"?>
<core:Import action="CREATE" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:core="CORESYSTEM" xmlns:base="SCM.BASE" >
  <base:User active="true" locale="de" username="importDemo" passwordHash="plain:n!mda321">
    <roles>
      <!-- Preprocessor is replaced by element <role>ID_of_role_Administrator</role> at runtime -->
      <preProcessor xsi:type="core:FindEntity" returnId="true" type="base:Role" target="role"> 
        <search>
          <core:SimplePropertySearch stringValue="Administrator" compareType="==" projection="roleName"></core:SimplePropertySearch>
        </search>
      </preProcessor>
    </roles>
    <companies>
      <!-- Preprocessor is deplaced by element <company>ID_of_company_SL_Germany</company> at runtime -->	
      <preProcessor xsi:type="core:FindEntity" returnId="true" type="base:CompanyAccount" target="company">
        <search>
          <core:SimplePropertySearch stringValue="SL Germany" compareType="==" projection="address.name1"></core:SimplePropertySearch>
        </search>
      </preProcessor>
    </companies>
    <!-- Preprocessor is replaced by element <address>Company_address_of_SL_Germany</address> at runtime -->	
    <preProcessor xsi:type="core:FindEntity" returnId="false" type="base:CompanyAccount" target="address">
      <search>
        <core:SimplePropertySearch stringValue="SL Germany" compareType="==" projection="address.name1"></core:SimplePropertySearch>
      </search>
      <resolver property="address"> <!-- only the address is extracted from the company account -->
        <core:RootEntityResolver rootType="base:CompanyAccount"></core:RootEntityResolver>
      </resolver>
    </preProcessor>
  </base:User>
</core:Import>