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 Orchestration 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 Resolvers can be defined to specify a detail from the data of the referenced entity as a return value.

NOTE: The Resolvers (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 Resolvers.

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>