Add to export job

Event action – Abstract

Purpose: If a single entity of an exportable type exists as a reference object, it is added to an existing or newly created Export job.

images/download/attachments/189439088/image-2024-11-27_16-26-45-version-1-modificationdate-1732721205595-api-v2.png

The Add to export job event action attempts to add an entity that exists as a reference object to an existing or newly created export job.

An exportable entity (see Meta Exchange extension) is expected as the reference object.

  • If the reference object is 'No value' ($null), the event action has no effect.

  • If the reference object is not an entity, an error message (and possibly a rollback) is triggered when Add to export job is executed.

  • If the reference object is an entity of a type that cannot be exported, the event action has no effect.

If an Export job already exists in the context of the session at runtime, the current reference object (including all dependent entities) is then added to it.

NOTE


Interactive export vs. automation

Executing the Add to export job event action largely matches the execution of the ribbon macro command 'Export/Export' (see Available commands) in the context of an entity.

The system does not check whether the Role of session applicable in the execution context has the authorization to export (~/Export/Export) for the specific entity type to which the reference object belongs.
This means that the event action can also be executed for entities in whose context the 'Export/Export' ribbon command is not available.

While the interactive export can be executed in the context of an overview for a multiple selection of entities (of the same type), the Add to export job event action does not accept a list of entities as a reference object. Therefore, to automatically add several entities to an Export job, several instances of the Add to export job event action or a For each loop event action must be used.

Configuration

The Add to export job event action does not use any parameters.

Examples

Simple use case

The user account with which the Company of session was created should be added to the current Export job in the context of event handling.

Configuration:

The value configuration for the Object resolver parameter determines the reference object to be exported via the following value resolver chain (see Chained resolver) within the Execute with event action displayed on the right:

  • The Company of session resolver delivers the company account selected in the applicable context.

  • The concatenated Object property resolver reads the Long value from the 'Creator' (creatorId) field that refers to the user account to be exported (see Users).

  • The Input object (type safe) resolver at the end of the chain returns the Long ID referenced user account as a complete entity.

    NOTE◄ As the creatorId field specifies a weak reference, it is possible that the user account entered as the creator has since been deleted. The value resolver then returns 'No value' ($null) as the reference object and the Add to export job event action has no effect.

In the Execute with event action block, the Add to export job event action adds the identified user account to the Export job.

images/download/attachments/189439088/image-2024-11-27_16-30-49-version-1-modificationdate-1732721449453-api-v2.png

More complex use case

In the context of event handling, all holiday groups (see Holiday groups) that contain at least one entry for the current year are added to an Export job.

A view is then opened for the Export job, if not already the case.

Configuration:

The holiday groups to be exported are determined in advance using the Search event action shown on the right:

  • The holidayGroups variable to which the search result list is assigned at runtime is named as the Save result as parameter.

  • The Entity parameter defines the relevant 'Holiday group' (HolidayGroup) entity type.

  • The Mode 'Result list' determines that the search result list of all matches is returned.

  • The Where condition is defined as a field restriction:

    • The 'entries.date' (entries.date) field is read as a check value (left) via Property projection. Access to the 'Entries' list field of the holiday group implies that a holiday group is considered a match if at least one entry fulfills the Field restriction.

    • A date range for the between comparison is provided as a compare value (right) via the Relative date range with time. The Type 'This year' (THIS_YEAR) from the dynamic enumeration Date range type is specified.


NOTE◄ Not selecting a Time zone indicates that the time zone applicable in the execution context is used. This is done on the assumption that the entries in the holiday group have been maintained for the same time zone. This can certainly have an effect on the search result, as the following example shows:

      • A holiday group was created in the context of a session with reference to the Europe/Berlin time zone. It contains only holidays for the next year, starting on 1 January (New Year).

      • This holiday group would incorrectly appear as a 'match'’ in the results list of this Search if it is executed in a context with reference to a ‘’later‘’ time zone (e.g. America/New York).

images/download/attachments/189439088/image-2024-11-27_16-37-5-version-1-modificationdate-1732721825183-api-v2.png

The screenshot on the right shows the Search event action described in detail above (here: collapsed), after which a For each loop action is executed:

  • The Resolver for entities parameter refers to the ‘result list’ from the search in the holidayGroups variable using the Variable resolver.

  • In the action block of the loop, the Add to export job event action is executed for each iteration so that all holiday groups from the search are added individually to the Export job.


NOTE◄ For simplification, we have assumed here that the event handling is executed in the context of a session with the ‘Super user’ role (or at least the corresponding permissions). It is generally recommended to execute an Export job. If the Search needs to take owner restrictions into account so that only holiday groups that the Company of session is authorized to ‘read’ are exported, the Search must be used in the action block of a Run as event action with a ‘restricted’ role.

images/download/attachments/189439088/image-2024-11-27_16-40-15-version-1-modificationdate-1732722015454-api-v2.png

The screenshot on the right shows the configuration for an Open view (Action), which opens a view for the Export job if one does not yet exist:

  • The View name parameter addresses the menu node name (administration/system/exportJob) for the Export job.

  • No Form data is transferred.

  • The Unique option is selected (default) so that no additional view is opened for the Export job if one already exists.


NOTE◄ The menu node name can only be used to specify the View name to be opened if the Export job menu item is available in the session. This is only the case if the Role of session has the authorisation ‘Administration/System/Import Job’ (administration/system/importJob).

Using the view name, however, the Open view (Action) can also display the view for the Export job in a session in which the ‘Administration/System/Import job’ authorisation is not available and in which the Export job and Import job menu items are not available:

de.lobster.scm.exchange::ExchangeIndex|listDetailsWindow

The Export job view is a combined view for the ‘Exchange index’ (ExchangeIndex) class.

images/download/attachments/189439088/image-2024-11-27_16-45-17-version-1-modificationdate-1732722317568-api-v2.png