ELO

The ELO post-processing step allows you to store attributes and files from https://portrait.atlassian.net/wiki/spaces/PA/pages/98554 in ELO.

Result of the ELO post-processing

MODE: Create

  • A new folder in ELO is created

  • the folder mask is assigned to the folder

  • the mask attributes are assigned to the folder

  • the map field attributes are assigned to the folder

  • Attachments are uploaded as child Elements to the folder

  • the file mask is assigned to each uploaded attachment

  • if configured: a workflow is started

MODE: Update

  • Updates an existing folder in ELO - identified by ObjectID or GUID

  • If a folder mask is configured: an updated folder mask is set

  • If a path is configured: moved the folder to the new location (including all subfolders/files)

  • If a folder name is configured: updated the folder name

  • Update the mask attributes: new values are added. If a value already exists, it will be overwritten. Old values that are not overwritten will stay

  • Update the map field attributes. new values are added. If a value already exists, it will be overwritten. Old values that are not overwritten will stay

  • Attachments are uploaded as child Elements to the folder

  • the file mask is assigned to each uploaded attachment

  • if configured: a workflow is started

MODE: Delete

  • A single Sord Object in ELO is deleted - identified by ObjectID or GUID

Summary of naming conventions in ELO

Sord

A sord in ELO is any object. This can be a Folder, File, …

Folder

The Folder in ELO is a container that

  • has ONE assigned Folder mask

  • has N mask attributes (map-like key-value pairs) - also called objectkeys. These are directly connected to the assigned Folder mask. e.g. A Folder with the mask ‘invoice' has a mask attribute ‘invoice number’ but no attribute ‘birthday’.
    The mask attributes are String values only with a maximum length of 255 characters.

  • has N map field attributes (map-like key-value pairs) - in ELO they are shown in the tab ‘Additional Infos’. They are used in various Business Solutions and Forms. Each attribute has an assigned domain (objekte, formdata, ...) and a type (string or blob). The type string is limited to a maximum length of 255 characters.

  • has N child elements

    • other Folders

    • Files

File

These are actual BLOB files like JPG, PDF, …

They have:

  • ONE assigned File mask

as well as

  • N mask attributes

  • N map field attributes

However, Portrait only allows setting the file mask. Attributes are only supported to be stored in the folder.

Detailed process description

MODE: Create

The creation process is done in the following order

  • User submits Form

  • Handlebars are applied, see order below

  • Validations

    • Validation of Mask attributes - fieldProcessor + dialog "fields": [{...}]

    • Validation of Folder mask - mask

    • Validation of File mask - fileMask

  • Folder is created or copied - according to path,folderName and sourcePath

  • Folder mask is set

  • Mask attributes are set

  • Map fields are set

  • Attachments, with the correct File mask, are uploaded

  • Workflow is started

There is no transaction. If one step fails some data might already be written to ELO

Validation of Mask attributes

Checked:

  • Each mask attribute value can only contain max 255 characters.

Not Checked:

  • The mask attribute is available in the folder mask. In this case, the attribute is ignored and not written to ELO.

Validation of Folder/File mask

Checked:

  • If the configured mask is allowed to be set to a Sord of the type folder/file

MODE: Update

Same as in the CREATE mode. However, not all configurations are required.

  • Path: if empty the folder won’t get moved and stays on the same path

  • folderName: if empty the folder won’t get renamed.

MODE: Delete

  • User submits Form

  • A single Sord Object in ELO is deleted - identified by ObjectID or GUID

Configuration for MODE: CREATE

 

 

 

 

onSubmit.type

Must be ELO

onSubmit.connection

ID of the ELO connection - see https://portrait.atlassian.net/wiki/spaces/PA/pages/98329

onSubmit.mode

must be CREATE

onSubmit.path

Optional

Path of the folder. The path can already exist in ELO, if not it is created during the first form submission.

is used as a path seperator. Therefore, can NOT be contained inside the variables. An Error will be throws if the supplied parameters contain an

Handelbars are supported.

Example Handlebars for the path:
"¶Portrait¶SERVICE_PROTOCOL¶{{SERVICE_PROTOCOL_PRIORITY}}"

If no path is given, the submitted forms are stored in the Chaosablage.

onSubmit.folderName

Required

Name of the folder that gets created when a form is submitted.

Handelbars are supported.

Example Handlebars for the folder name:
"{{now format=\"yyyy-MM-dd\"}} - {{SERVICE_PROTOCOL_ISSUE}}"

onSubmit.sourcePath

Optional

If provided the sord object, includings all its content and set attributes, is copied and used as the base Folder.

The target will be onSubmit.path and the name of the copied sord onSubmit.folderName

Example:

"¶Administration¶Business Solutions¶common¶Configuration¶Common file types¶Service Call Template"

onSubmit.mask

Name of the folder mask in ELO.

The mask must already be created in ELO and allowed to be set to an folder Sord.

If empty the default folder mask from elo is determied and applied.

onSubmit.fileMask

Name of the file mask in ELO.

The mask must already be created in ELO and allowed to be set to an document Sord.

If empty the default file mask from elo is determied and applied.

onSubmit.fieldProcessor

See Mask Attributes below

onSubmit.maps

See Map Attributes below

onSubmit.workflow

Name of the ELO workflow Template, that will be started on the created folder.

Optional: If no value is given, then no workflow is started.

onSubmit.workflowname

The name of the workflow instance which is started.

Support for https://portrait.atlassian.net/wiki/spaces/PA/pages/122224641

Available variables:

  • FOLDER_NAME → the Sord Name of the created/updated Folder

  • All others as specified here:

Default: {{FOLDER_NAME}}

So the default workflowname is the same as the created/updated folder.

onSubmit.index

The id of the that will be reindexed with the changed items. Works for CREATE, UPDATE and DELETE

Mask Attributes

There are two methods to configure which Mask attributes are selected to be written:

  • 1:1 mapping of the dialog field names - this happens automatically

"pages": [ { "label": "Person", "fields": [ { "name": "damaged_person_first_name", "displayText": "Vorname *", "description": "First name", "type": "TextBox", "options": { "required": true, "confirmation": true } } ]

A mask attribute with the key ‘damaged_person_first_name’ is selected.

  • fieldProcessors

fieldProcessor: - field: CM_WA_COMPANY value: "{{damaged_company_name}}"

A mask attribute with the key ‘CM_WA_COMPANY’ is selected.


The attributes are only marked to be written. At runtime, it is determined if the keys are available to be written for the configured folder mask. If some attributes are not available to be set for this mask they are simply ignored and not written.

The methods can also be combined:

Now 3 values will be marked to be written:

  • damaged_person_first_name

  • damaged_person_last_name

  • CM_WA_FULLNAME

Map Attributes

Map attributes can be configured via the maps YML parameter

At runtime, the list domains and types are grouped together. For each domain and type the data is written separately.

Handlebars

The handlebars support the usage of the form parameter. In addition, we provide the following use of parameters from the user that submitted the form:

Constants

PORTRAIT_USER_ID

unique user id

cNkXPLhKjXMFiFYvYvcGOdmHRrTOxesEfcWmoteLGUMyyqslLyEV

PORTRAIT_USER_NAME

name of the user

Linda Jackson

PORTRAIT_USER_EMAIL

email

linda.jackson@larsens.portraitapp.co

PORTRAIT_USER_ROLE

assigned role

ADMIN

User Custom Fields

<key_of_custom_field>

<value_of_custom_field>

The value set in the View.
Different for each user. The Value from the logged in user is used.

During the form submission, the handlebars are applied in this order:

  1. Fieldprocessors

  2. onSubmit.path, onSubmit.folderName

Therefore the result of the field processes can influence the onSubmit config.

Example ELO post-processing in Portrait

Example configuration:

Overview of the newly created Folder 'Mod2 - Löscheinsatz - 2023 …' in ELO.
The map attributes are also set according to the configuration. Notice that CM_WA_DESC is a blob field and therefore not shown in the UI of ELO. The domain of the map attribute is also only visible in the SQL database.

Configuration for MODE: UPDATE

 

 

 

 

onSubmit.type

Must be ELO

onSubmit.connection

ID of the ELO connection - see

onSubmit.mode

must be UPDATE

onSubmit.path

Optional

Path where the updated folder is moved to. The path can already exist in ELO, if not it is created during the first form submission.

is used as a path seperator. Therefore, can NOT be contained inside the variables. An Error will be throws if the supplied parameters contain an

Example Handlebars for the path:
"¶Portrait¶SERVICE_PROTOCOL¶{{SERVICE_PROTOCOL_PRIORITY}}"

If no path is given, then the folder won’t get moved.

onSubmit.folderName

Optional

Name of the folder that gets created when a form is submitted.

Example Handlebars for the folder name:
"{{now format=\"yyyy-MM-dd\"}} - {{SERVICE_PROTOCOL_ISSUE}}"

If no folderName is given, then the folder won’t get renamed.

onSubmit.sourcePath

Not supported for update, use path instead to move folders.

onSubmit.mask

Name of the folder mask in ELO.

The mask must already be created in ELO and allowed to be set to an folder Sord.

If empty the folder mask won’t be changed

onSubmit.fileMask

Name of the file mask in ELO.

The mask must already be created in ELO and allowed to be set to an document Sord.

If empty the default file mask from elo is determied and applied.

onSubmit.fieldProcessor

See Mask Attributes below

onSubmit.maps

See Map Attributes below

onSubmit.workflow

Name of the ELO workflow, that will be started on the created folder.

Optional: If no value is given, then no workflow is started.

onSubmit.index

Optional

The id of the that will be reindexed with the changed items. Works for CREATE, UPDATE and DELETE

Example ELO post-processing in Portrait

Example configuration:

Config for Dialog

 

Configuration for MODE: DELETE

 

 

 

 

onSubmit.type

Must be ELO

onSubmit.connection

ID of the ELO connection - see

onSubmit.mode

must be DELETE

onSubmit.dialog

JSON with the correct formatted Forms

must contain one field with the name 'key'. This is theObjectID or GUID of the object to be deleted. You can use EntryFields to present existing entries to the user and select the ObjectID or GUID

onSubmit.index

The id of the that will be reindexed with the changed items. Works for CREATE, UPDATE and DELETE

Basic Example:

Config for Dialog

 

Troubleshooting

If you encounter some issues, look in the portrait backend log file. Watch out for error messages directly from ELO, which is logged during the process.
Example:

[TICKET:0ACDA9...][Die Maske Verkauf kann nicht für Ordner verwendet werden.]

 

The entire process is non-atomic, which means that in the case of an error, some data might have already been written to ELO. Some actions are required to classify the post-process step as a success, while others are not. Here is an overview:

Cause

Error Level

Results in

Cause

Error Level

Results in

ELO folder can’t be created.

The form data or files will not be stored in ELO.
The frontend will show an error and log the response from ELO.

Folder mask can’t be set.

The form data or files will not be stored in ELO.
The frontend will show an error and log the response from ELO.

The portrait field name does not match a field name in the ELO mask.

This metadata field will be ignored and not stored in ELO.
Post-processing continues normally.

Attachment can’t be uploaded to ELO.

This attachment will be ignored and not stored in ELO.
Post-processing continues normally.

Workflow can’t be started.

Application will log an error.
Post-processing continues normally.

 

Copyright Treskon GmbH.