Single import
The Single import is the easiest way to Import a single object per 'job'. In contrast, a Batch import allows several objects to be processed in the same 'job'.
The Import page provides an overview of the interaction between Lobster Data Platform / Orchestration and Lobster_data and the general structure of an import profile.
In the following, only the details of the configuration of the target structure for the import are explained, which apply for the Single import as well as the Batch import.
The structure used for the Single import corresponds exactly to the content of an individual batch node of a Batch import. The following comments on the details in the structure therefore apply to both Import methods.
In practice, the Batch import structure is often used for importing individual objects, as this allows access to additional functionality only available for the Batch import.
Elements of the target structure for a single import
When creating an import profile for a Single import , the target structure is ideally created from the Lobster Data Platform / Orchestration template for the core:Import-object (for details, see Lobster SCM templates).
The following screenshot shows a target structure generated from the core:Import template, in which – starting from the original state – the fixed value CREATE was assigned to the action_attr field:
Overview of the standard components of the import structure:
|
Component |
Type |
Description |
Notes |
|
action_attr |
Field/Attribute |
determines the import action to be performed (see section 'Import actions' below) |
Required field |
|
rememberAs_attr |
Field/Attribute |
stores a reference to the current object under the name specified as text value for later access via core:GetObjectFromBatch (Preprocessor) |
optional |
|
event_attr |
Field/Attribute |
specifies a Custom action event, to be dispatched by the DISPATCH_EVENT import action via import |
Required field for |
|
eventStorage |
Node |
assigns values to event variables in the context of DISPATCH_EVENT values (see section 'Dispatch custom action event' below) |
optional for |
|
search |
Node |
defines an optional Search, which – if used at all – must return a uniquely identified entity as an object for the execution of the import |
optional |
Definition of the object structure
The template does not contain a placeholder for the 'payload' of the import, which must be defined by creating or inserting an additional subnode of the 'Import' node. Lobster SCM templates can also be used for this.
In the following, the abstract description object structure will be used to address this node and the substructure it contains, since the specific node name is usually determined by the respective entity type.
►NOTE◄ In principle, the target structure of an import profile can also contain several object structures, provided that it is ensured that these are handled strictly alternatively at runtime. If it is guaranteed that only one of the alternative object structures will be effective at runtime, different entity types can be addressed on the basis of the same import profile, for example, depending on specific content of the input data.
Import actions
For the import, the name of one of the following actions must be specified by the attribute 'action' (action_attr field):
|
Action (action_attr) |
Description |
|
CREATE |
The import should create a new object. The specification of an internal ID (id) within the object structure is optional.
►IMPORTANT◄ In general, the designation of a specific ID (id) for the entity to be created should be avoided, as this by-passes the automatic generation internal ids, which may lead to conflicts with internally generated IDs at a later time. |
|
UPDATE |
The import should update an existing object, which must be uniquely identified by explicitly specifying an id or by defining a Search (search nodes).
|
|
CREATE_OR_UPDATE |
The import is to create or update the object uniquely identified by specifying an internal ID (id) or via a Search.
►IMPORTANT◄ In general, the designation of a specific ID (id) for the entity to be created should be avoided, as this by-passes the automatic generation internal ids, which may lead to conflicts with internally generated IDs at a later time. |
|
CREATE_OR_NOTHING |
The import should create a new object, unless the condition in the search node (required for this action) identifies exactly one match among existing objects.
►IMPORTANT◄ In general, the designation of a specific ID (id) for the entity to be created should be avoided, as this by-passes the automatic generation internal ids, which may lead to conflicts with internally generated IDs at a later time. |
|
UPDATE_OR_NOTHING |
The import should update an existing object, which must be uniquely identified by explicitly specifying an id or by defining a Search (search nodes).
|
|
DELETE |
The import should delete the object uniquely identified by specifying an internal ID (id) or by a Search.
|
|
DISPATCH_EVENT |
Instead of a generic import action, a Custom action event should be executed.
|
Dispatch custom action event
A Custom action event can be dispatched by an import profile with or without transferring data (via variables and/or as object data) to the event. The different variants are demonstrated by the following examples:
Variant 1: Dispatch custom action event without transferring data:
In the simplest application case, the import profile – for example, in response to a certain 'message' sent to Lobster_data from another system – should dispatch a certain Custom action event in Lobster Data Platform / Orchestration without the necessity to exchange detailed data.
In this case the target structure of the profile could look as compact as this:
|
|
|
The example results in the following target file (with namespace declarations skipped):
<?xml version="1.0" encoding="UTF-8"?><core:Import ... action="DISPATCH_EVENT" event="XF_TEST_EVENT"></core:Import>Variant 2: Dispatch a custom action event by transferring data to variables:
In another case, a certain key value (here: 'SILENT') is to be passed to the same event via a variable 'eventMode', which Event handling may evaluate and respond to, e.g. by suppressing certain output functions (mail dispatch etc.).
|
|
►NOTE◄ While the template contains the fields key_val and value_val, in both cases the field type_attr must be completed for the required typing of the data. The variable name is always the xsd:string, type, other types are also possible for the value (e.g. for more complex contents). In addition, the 'XML Namespace' property of the fields must be set to xsi. It is important that the target file represents the data as it usually appears in the 'storage'. Corresponding structures can also be compiled via Tests and transferred to the target structure by Creating static target structures. |
The example results in the following target file (without namespace declarations)
<?xml version="1.0" encoding="UTF-8"?><core:Import ... action="DISPATCH_EVENT" event="XF_TEST_EVENT"> <eventStorage> <data> <entry> <key xsi:type="xsd:string">eventMode</key> <value xsi:type="xsd:string">SILENT</value> </entry> </data> </eventStorage></core:Import>Variant 3: Dispatch custom action event by transferring object data
If the target file of an import profile with the DISPATCH_EVENT import action contains data from an object structure, this is considered as an 'input value' (more precisely: 'input object') for the custom action event. Event handling can then work with this data context and, among other things, use Check type in the 'Validating rule'.
If the 'object data' refers to the ID (id) of an existing entity, or if the search node defines a Search that returns a unique search result, the corresponding entity is considered to be the basis for this data context to which deviating contents from the object structure are overlayed as an update. If a specified ID does not exist or the Search returns no result, the data context only contains the explicit assignments from the object structure. If an event handling dispatched by the custom action event executes the Save changes later action, the DISPATCH_EVENT action implies a CREATE_OR_UPDATE action: Either a uniquely identified existing entity is updated or a new one is created.
►NOTE◄ Since the object structure determines the entity type for the Search defined in the search node, a Search is not executed if the target file contains no object data. However, object data only appears in the target file if at least one field of the object structure is assigned a value statically or by mapping. If this is undesirable because it could override the data of the 'found' entity, the Search should be performed elsewhere, e.g. in a calculation node with the Lobster_pro: SearchTask (_data function) function, to be able to assign the 'found' ID (id) as a value for the id_attr field of the object structure.
Example
Sending a specific message to Lobster_data (from an external system) should trigger the deactivation of a Lobster Data Platform / Orchestration user identified in the message by 'username'.
Technically, this requires updating the 'Active' field of the user object to which the username in question is assigned to the value false Lobster Data Platform / Orchestration requires the username to be unique by definition.
Configuration:
|
|
|
Runtime example:
The profile sends the following destination file to Lobster Data Platform / Orchestration when a message is received specifying that a user with the user name TEST should be deactivated:
<?xml version="1.0" encoding="UTF-8"?><core:Import ... action="UPDATE"> <search> <core:SimplePropertySearch projection="username" compareType="==" stringValue="TEST"></core:SimplePropertySearch> </search> <base:User active="false"> </base:User></core:Import>If a user with the username TEST exists for which write access is granted, it is deactivated.