General

Security

Please note our Statement regarding the Security Improvements here:

https://portrait.atlassian.net/wiki/spaces/PA7/pages/1029117068/Draft+7.0.0+-+Reisalpe#Security-Improvements-Notice

And make adjustments to Permissions for Forms, Actions 2.0, Sections as needed.

Procedure

1. Please make a backup of your entire configuration this may include the following files. You can download the entire folder directly via <yourInstance.com>/config by rightclick on a folder and select download.

2. Upload the new icon-badge.png

3. Shut down the portrait instance via docker-compose down. (stop is not enough)

4. Update the application-prod.yml - details below

5. Update the .env file to use the latest version:
   Example: (use the latest 7.x that is available) see https://install.portrait.app/ for all versions

   Code Block
   BACKEND_TAG=stable-7.0.0 FRONTEND_TAG=stable-7.0.0 PYTHON_RUNTIME_TAG=stable-7.0.0

6. Startup the instance via docker-compose up -d

7. RECOMMENDED: Elasticsearch Index Space Optimization

   1. Go to the sources config in the admin view and DELETE all ELO indexes.

   2. Restart Portrait to rebuild the indexes completely

If you have a larger YML Config you could also upgrade smaller parts by commenting out some parts and go from there.

Upload new Icon

We extended the icon sets for push notifications. A new icon ‘logo-badge.png’ has been added.
Download this file and add it to the icons folder. As this icon requires specific formats (format, transparency, …) in order to be correctly displayed by multiple devices we recommend to use the default one we provide.

File:

Image Modified

technical details https://notifications.spec.whatwg.org/#badge-resource

The icon will be shown based on the users os and design. Example on android

Image Modified

Application Config Update (application-prod.yml)

These Guide mainly describes the breaking changes and needed updates in order to migrate old instances. For a full list of new features see our full release notes https://portrait.atlassian.net/wiki/pages/resumedraft.action?draftId=1029117068

Section

Actions:

Reference: https://portrait.atlassian.net/wiki/spaces/PA7/pages/edit-v2/1103593474#Migration-Section-Action-to-new-configuration

For Links that were previously build with handlebars in the source. These can now be build with directly in the section. In addition you can specify conditions whenever a link should be displayed for an entry or not.

Details:

Actions

Actions for links:

before

- label: 'Manufacturer Info'
  key: 'CtaManufacturerInfo'
  type: 'action'
  icon: 'info'
  appearance: 'primary'
  showInTableHeader: false
  showInDetailList: true

after

actions:
  - label: 'Manufacturer Info {{Name}}' # Handlebar
    key: 'CtaManufacturerInfo'
    type: 'LINK' # [LINK, FORM ]
    condition:
      - expression: '{{gt Amount 0}}'
    value: 'https://www.google.com?q={{ModelCode}}'
    icon: 'info' # Handlebar

Actions for triggering forms:

before

- label: 'Bearbeiten'
  type: 'form'
  key: 'edit_vacation'
  icon: 'edit'
  showInTableHeader: false
  showInDetailList: true
  options:
    forwardFields:
      - key
      - VACATION_EMAIL
      - VACATION_DATE
      - VACATION_STATUS

after

actions:
  - label: 'Bearbeiten' # Handlebar
    key: 'edit_vacation'
    type: 'FORM' # [LINK, FORM ]
    condition:
      - expression: "{{eq VACATION_EMAIL PORTRAIT_USER_EMAIL}}"
    value: 'edit_vacation'
    icon: 'info' # Handlebar
    forwardFields:
      - key
      - VACATION_EMAIL
      - VACATION_DATE
      - VACATION_STATUS

Inline Image in HTML

If you previously used the indexing of Files to display Images inline via HTML you have to set a flag to store the files in the public directory.

Enable Public cache folder

publicCache: true

full example:

sourceSpecific:
  mask: Application Entry
  files:
    publicCache: true
    nesting: 1
    mask: Application Attachment

Disable File download - optional

In addition you may want to disable the download of these files now:

- name: sectionid
  disableFiles: true

see

https://portrait.atlassian.net/wiki/spaces/PA7/pages/edit-v2/1029117068#ELO-Sources-Files-Indexing

Example disabledFiles: false (default)

Image Modified

Example disabledFiles: true

Image Modified

Handlebars - Field Processors

ELO

GUID’s

With this version we switch to a more classic approach how ELO uses

GUID’s. In ELO, the identifier for an

Sord now includes the surrounding brackts.

See also: https://portrait.atlassian.net/wiki/spaces/PA7/pages/1029117068/Draft+7.0.0+-+Reisalpe#ELO-Sources-IDs

Example

A practical example, where this is needed, is the Orgchart view

Additional helper

We added a bunch of new helpers. Check them out and optimize your config as needed

:

• https://portrait.atlassian.net/wiki/spaces/PA7/pages/1029114243/Field+Processors#In

• https://portrait.atlassian.net/wiki/spaces/PA7/pages/1029114243/Field+Processors#Working-with-numbers

• https://portrait.atlassian.net/wiki/spaces/PA7/pages/1029114243/Field+Processors#Working-with-boolean

• https://portrait.atlassian.net/wiki/spaces/PA7/pages/1029114243/Field+Processors#Mathematics-Operations

Source

ELO

Administration base and Chaosablage

When indexing Elements within the

Administration base (“Administration” Folder) and “Chaosablage” results are per default now ignored, this can be changed with

sourceSpecific:
        blacklistChaosablage: false #default, if not set: true
        blacklistAdministration: false #default, if not set: true

In addition, you can also provide own folder GUIDs that will be excluded.

Details

, see: ELO sources

SQL Sources

We increased the security measurements whilst dealing with SQL write operations. This means, the SQL query will be parsed as prepared statement. For safety reasons, we enforce this style now for every SQL query. These changed are valid for all DML Statements. DDL Statements are not supported anymore.

Example

Given this example for the createNewCompany form.

In this given example, the form-data will be inserted into the table DemoOrganigram via the connection organigram.

The FieldProcessors can either be used to format fields or as a fallback in case of an optional field in the form. If not supplied the Query would fail as there would be no valid parameter :Name if not set previously. With the given FieldProcessor the fallback is an empty string.

Details, see: https://portrait.atlassian.net/wiki/x/pQNXPQ

Forms based on existing Entries - Mode and Scope

It is now possible to link forms to existing entries. This allows Portrait administrators to further increase their application security and data consistency. To achieve this goal, we introduced multiple configuration options.

Update-Mode

With the new Mode Update you make the ‘previous’ entry-fields available as variables to be used for Field Processors, SQL queries or further processing in your Python script. In other words, the Create-Mode ignores existing entries - and therefore shouldn’t be used if you need conditions or security.

We recommend that you rework forms which are updating existing entries to increase security by using “update mode” and “scope strict”. This way, input validation will be forced and allows you to get a consistent data store all the time.

Strict-Scope (ELO only)

Furthermore the scope setting was introduced. This was necessary, since it was possible in Portrait 6.x to manipulate unrelated Sord’s in ELO with some “bad-actor-energy”. We won’t go into details here.

However, with Portrait 7.x things changed with the setting the scope to STRICT. This will prevent editing unrelated Sord's which are not indexed in Portrait.

Therefore, it is highly recommended to apply this configuration.

Plausibility check

In addition a check is applied:

• SQL and Python

  • If a form is submitted and no corresponding entry is found in the Portrait index, the operation is cancelled.

• ELO

  • If a form is submitted and no corresponding entry is found in the Portrait index AND the scope is set the STRICT, the operation is cancelled

Summary

Still unsure, what to do? We got your back:

If you have forms, that submit data to ELO, add the mode property to the onSubmit settings and set it accordingly. It will be either: CREATE, UPDATE or DELETE. Also set the scope property to STRICT.

If you have forms, that submit data to SQL or Python, add the mode property to the onSubmit settings and set it accordingly. It will be either: CREATE or UPDATE.

Please read our docs on the given use-case, wholeheartedly:

• Post Processing (onSubmit) - In general, no matter the destination.

• ELO - use the form data in ELO. You will find a separate chapter about the improved security considerations.

• SQL - use the form data in SQL prepared statements.

• Python - use the form data in python scripts.

• BLP 5.1 - start ELO BLP processes.

This examples shall round it up:

Examples

This examples shall round up the previous:

ELO - Update an entry

You have a form in Portrait, that should edit an indexed entry in Portrait and ELO. The config:

- id: edit_entry_withELO
  onSubmit:
    mode: UPDATE
    source: sectionID
    scope: STRICT
    ...

ELO - Delete an entry

You have a form in Portrait, that should delete an indexed entry in Portrait and ELO. The config:

- id: delete_entry_withELO
  onSubmit:
    mode: DELETE
    source: sectionID
    scope: STRICT
    ...

Python - Update an entry

You have a form in Portrait, that should edit an indexed entry in Portrait and run a py-script. The config:

- id: edit_entry_withPy
  onSubmit:
    type: Python
    mode: UPDATE
    source: sectionID
    ...

SQL - Update an entry

You have a form in Portrait, that should edit an indexed entry in Portrait and SQL. The config:

- id: edit_entry_withSQL
  onSubmit:
    type: SQL
    mode: UPDATE
    source: sectionID
    ...

BLP5.1 - Trigger a process

You have a form in Portrait, that should start a process in BLP5.1. The config:

- id: edit_entry_with_BLP51
  onSubmit:
    type: BLP5.1
    ....