Include PageDD:Folder Structure APIDD:Folder Structure API

Table of Contents

outline	true

Introduction

This article describes how to build folder structures ('virtual' folders') in product version 4. The new folder structure replaces the familiar subfolders from version 3.3. The new structure is based on the configuration of each context folder.

You configure the folder structure in a text file in the designer. In future versions, a graphical tool will make configuration simpler.

The client 4.x gets the folder structure by requesting the new microservice named Structure Service.

For more general information, refer to the Frequently Asked Questions.

The following presentation explains how folder structures are set up and used (German only):

Widget Connector

url	http://youtube.com/watch?v=U5dMdgl3T2I

Folder Structure Configuration

This section describes the Folder Structure API. This API leads to individual folder structures for a folder (German: Ordner).

The REST calls used to request the folder structure for a single folder are documented here.

Syntax

Currently, the folder structure configuration is a text file written in a JSON-based syntax. In the future, the configuration will be supported by a visual editor and preview similar to that for forms.

Structure Service Testing Tool

Beginning with version 4.3, a testing tool is available to help you validate structure configurations. For more information, refer to the testing tool documentation.

Standard structure

If no individual folder structure configuration is given for a folder, the standard structure offers the 'structure elements' (German: Strukturelemente) as shown in the client:

Image Added

Figure 1: Standard structure of a folder

The configuration for the standard structure is shown in the following code sample. The details are explained below.

Code Block

[
  {
    "title" : "All objects",
    "title_locales" : {
      "de":"Alle Objekte",
      "es":"Todos los objetos",
      "fr":"Tous les objets",
	  "it":"Tutti gli oggetti",
	  "pt":"Todos os objetos",
	  "ru":"Все объекты",
      "zh":"所有對象"
    },
    "key" : "Types",
    "field" : "type",
    "expanded" : true,
    "showempty" : true
  },
  {
    "title" : "Edited by me",
    "title_locales" : {
      "de":"Von mir bearbeitet",
      "es":"Editado por mí",
      "fr":"Edité par moi",
      "it":"Modificato da me",
      "pt":"Editado por mim",
      "ru":"Отредактировано мной",
      "zh":"由我編輯"
    },
    "key" : "ModifiedByMe",
    "condition" : "modifier=#CURRENTUSER#"
  },
  {
    "title": "Editors",
    "title_locales" : {
      "de":"Bearbeiter",
      "es":"Editores",
      "fr":"Éditeurs",
      "it":"Editors",
      "pt":"Editores",
      "ru":"редакторы",
      "zh":"編者"
    },
    "key": "Modifier",
    "field": "modifiertitle"
  },
  {
    "title" : "Modification range",
    "title_locales" : {
      "de":"Bearbeitungszeitraum",
      "es":"Rango de modificación",
      "fr":"Plage de modification",
      "it":"Gamma di modifica",
      "pt":"Faixa de modificação",
      "ru":"Диапазон модификации",
      "zh":"修改範圍"
    },
    "key" : "ModifiedRange",
    "method" : "daterange",
    "field" : "modified"
  }
]

List of structure terms

Term

Description

[ ]

mandatory

Opens and closes the whole folder structure configuration. Use JSON syntax for arrays.

{ }

mandatory

Opens and closes the configuration of a node, as well as each subnode. Use a comma ( , ) to separate sets of curly brackets ( { } ). Use JSON syntax for objects.

key

mandatory

There is a unique key for each level in the tree. It is used to reference the results in the structure tree.

title

mandatory

The label for the key.

field

optional

The contents of the index field referenced here are displayed as subfolders in the structure. The value of 'field' can be the technical name of general object attributes (see chapter 'List of general object attributes') or of individual index data with the format 'technical and normalized name of object type'.'technical name of index field' (qualified technical name).

If the field is one of an abstract object type, all objects of the derived object types are shown in the corresponding list of objects.

Info

title	Note

Only lower-case characters are allowed.

condition

optional

Use 'condition' to filter objects. For more information, see the chapter 'Condition grammar'

method

optional

Use 'method' to aggregate objects in the following ways:

daterange: for fields of type date and date/time. Aggregates objects by today, yesterday, this week (last seven days), last week, this month, last month, this year and last year.
yearhistogram: for fields of type date and date/time. Aggregates objects by year.
sum: Adds up the values of the referenced 'field'.
avg: Build the average of the referenced 'field'.
min: Gets the minimum value of the referenced 'field'.
max: Gets the maximum value of the referenced 'field'.

The default, if 'method' is not given, is 'count'. The aggregation will count the objects referenced by 'field'.

size

optional

For count aggregations, the structure service returns the 10 top results. If you want more results, you can set a higher size (e.g. 10,000), for example if 'showempty' is used and there are more than 10 structure elements.

Note: A higher size can decrease the performance of the aggregation. It is not recommended to set a high size on each structure element definition.

The size property can only be used if the method is 'count'.

If the field reference is a catalog, it is not needed to set the size in the structure element definition. The size is automatically set to the number of possible elements in the catalog. But it is still possible to override this behavior by setting a size.

folder

optional

To set up subfolder structures

hide

optional

A boolean that can be used to hide a folder from the result. It can be used to "pull-up" all child results. The result folder is always hidden from the result and all child results are shown in the parent result folder of this element.

expanded

optional

A boolean that controls whether a folder with substructure is shown expanded when the object view is opened. Default is 'false' (not shown expanded).

Supported since product version 3.32

showempty

optional

A boolean that controls whether a folder with substructure shows all folders, regardless of whether an object can be found for it. Default is 'false' (no empty folders are shown).

This property can only be used, if the possible child elements are known. The element must have a field property. The child elements are known if a fixed catalogue is used, the 'type' field is used, or if a 'showemptylist' property is provided for a string field.

showemptylist

optional

'showemptylist' can be used for fields from type catalog and string. If use the elements of the list are shown even if no object with the value is given. If such element is marked in the structure tree it is offered within the create object menu and preset in the create form.

In case of a fields from type catalog the list values must be the data values of the catalog.

Code Block
..., { "title": "Documents", "key": "Docs", "field": "eoxdocument.eoxdocumenttype", "showempty": true, "showemptylist": ["Whitepaper","Correspondence"] },

Supported since product version 4.10

hideempty

optional

A boolean that controls whether a node folder element is shown if all child elements are empty. If set to 'true', the node element is hidden from the result, if the count of objects - the aggregations - are zero. If at least one child element is available, the folder element is shown.

The property 'showempty' controls the behaviour for empty child elements, while the property 'hideempty' controls the behaviour of the parent element.

Supported since product version 4.12

contextcondition

optional

The element is only visible, if the context folder condition matches.
In the following example the node 'Candidate' is only shown if the personalfile class is a 'Applicant'.

Code Block

language	js

[
  {
    "key":"CandidateInformation",
    "title":"Candidate",
	"contextcondition":"personalfile.class='Applicant'",
	"folder":[ ... ]
  }
]

Hint: If a contextcondition is used, the service is doing a additional call to the eleasticsearch to resolve the index data of the context folder. If used to often, this will decrease the performance.

Supported since product version 4.12

List of general object attributes (term: 'field')

technical name	English name	Description
created	Created	Date of object creation.
creatortitle	Modified	'Name, Firstname' of creator.
filesize	Filesize	Size of the content in bytes.
mimetypegroup	File type	Group of files whose extension references one application. Examples: pdf, word, excel, image
modified	Edited	Date the object was last edited.
modifiertitle	Editor	'Name, Firstname' of last editor.
version	Version	Current version number (count starts with 1).

Condition grammar

The structure definition term "condition":"<condition grammar>" is used to define a search filter. This section describes the tokens used.

Token

Use

Description

#CURRENTUSER#

Placeholder

During runtime, the logged-in user name is used for filtering

#CURRENTYEAR#

Placeholder

During runtime, the current year is used for filtering

#LASTYEAR#

Placeholder

During runtime, the last year is used for filtering

#TODAY#

Placeholder

During runtime, today is used for filtering

#YESTERDAY#

Placeholder

During runtime, yesterday is used for filtering

#THISWEEK#

Placeholder

During runtime, this week is used for filtering. Example:

Code Block

language	js

{
  "title": "Edited by me this year",
  "key": "EditedByMeThisYear",
  "condition": "modifier=#CURRENTUSER# AND modified=#THISWEEK#"
}

#LASTWEEK#

Placeholder

During runtime, the last week is used for filtering

#THISMONTH#

Placeholder

During runtime, this month is used for filtering

#LASTMONTH#

Placeholder

During runtime, the last month is used for filtering

YEAR

Modifier

A field modifier that can be used on datetime or date fields. It provides access to the year value of the field.
Example:

Code Block

language	js

{
  "title": "Edited in 2016",
  "key": "Edited2016",
  "condition": "modified(YEAR)=2016"
}

PARENT

Modifier

A field modifier that can be used to resolve a hierarchical catalog node.
This example shows all children of node with the value Europe which may be its countries:

Code Block

language	js

{
  "title": "Employees in Europe",
  "key": "EmpEurope",
  "condition": "personalfile.continent(PARENT)='Europe'"
}

It can be used on catalogue fields. The parent node itself is always included.

=

Operator

Equability comparing.
Example:

Code Block

language	js

"codition":"modifier=#CURRENTUSER#"

!=

Operator

Compares two values. Result is true if they are not equal.
Example:

Code Block

language	js

"condition": "modifier!=#CURRENTUSER"

<

Operator

Compares two values, result is true if first value is less than second one.
Example:

Code Block

language	js

"condition": "version<4"

>

Operator

Compares two values, result is true if first value is greater than second one.
Example:

Code Block

language	js

"condition": "version>1"

AND

Operator

Combines logically two terms.
Example:

Code Block

language	js

"condition": "doc.status!='new' AND doc.status!=null"

OR

Operator

Combines logically two terms.
Example:

Code Block

language	js

"condition": "doc.status='started' OR doc.status='tobereworked'"

null

Value

Without value.
Example:

Code Block

language	js

"condition": "doc.active=null"

false

Value

For comparing Boolean fields.
Example:

Code Block

language	js

"condition": "doc.active=false"

true

Value

For comparing Boolean fields.
Example:

Code Block

language	js

"condition": "doc.active=true"

[0-9]

Value

Integer value.
Example:

Code Block

language	js

"condition": "doc.amount>4711"

Configuration examples

This chapter explains the configuration syntax step by step.

One single folder for listing all context folder objects

The configuration is based on JSON syntax. The definition begins and ends with square brackets [ ]. Inside the brackets are lists, enclosed in curly brackets { }, of parameters defining the node attributes. The first example defines the smallest configuration with only one node. This node offers access to a list of all objects within the context folder.

Code Block

title	Single node

[
 {
  "key":"all", 
  "title":"All objects"
 }
]

One folder for each object type

The next example extends the node by grouping all objects by type, as shown for the first node in Figure 1.

Code Block

title	Single node with leaves

[
 {
  "key":"all",
  "title":"All objects", 
  "field":"type",
  "showempty":true
 }
]

Complex folder structure

The following complex example shows how to configure subnodes.

Code Block

title	Complex configuration with many nodes and leaves

[
    {
      "title": "All",
      "key": "Common",
      "folder": [
        {
          "title": "Created by me",
          "key": "CreatedByMe",
          "condition": "creator=#CURRENTUSER#"
        },
        {
          "title": "Modified by me",
          "key": "ModifiedByMe",
          "condition": "modifier=#CURRENTUSER#"
        },
        {
          "title": "Modified by others",
          "key": "ModifiedByOther",
          "condition": "modifier!=#CURRENTUSER# AND modifier!='Bartonitz'"
        },
        {
          "title": "Modified by Martin",
          "key": "ModifiedByMartin",
          "condition": "modifier='Bartonitz'",
          "folder": [
            {
              "title": "Modified by Martin by years",
              "key": "modifiedyear",
              "field": "modified",
              "method": "yearhistogram"
            }
          ]
        },
        {
          "title": "By types",
          "key": "type",
          "field": "type"
        },
        {
          "title": "by file type",
          "key": "mimetypegroup",
          "field": "mimetypegroup"
        },
        {
          "title": "Year of modification",
          "key": "modifiedyear",
          "field": "modified",
          "method": "yearhistogram"
        },
        {
          "title": "Year of creation",
          "key": "createdyear",
          "field": "created",
          "method": "yearhistogram"
        },
        {
          "title": "By creator",
          "key": "creator",
          "field": "creatortitle"
        },
        {
          "title": "By modifier",
          "key": "modifier",
          "field": "modifiertitle"
        },
        {
          "title": "Time period of modification",
          "key": "ModifiedRange",
          "method": "daterange",
          "field": "modified"
        },
        {
          "title": "Time period of creation",
          "key": "CreatedRange",
          "method": "daterange",
          "field": "created"
        }
      ]
    },
    {
      "title": "Sickness notification",
      "key": "sicknessnotification",
      "type": "sicknessnotification",
      "folder": [
        {
          "title": "Longer then 3 days",
          "key": "sicknessnotificationlong",
          "condition": "sicknessnotification.numberdays>3"
        },
        {
          "title": "By years",
          "key": "year",
          "method": "yearhistogram",
          "field": "sicknessnotification.begin",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "sicknessnotification.numberdays"
            }
          ]
        },
        {
          "title": "Child sick",
          "key": "sicknessnotificationchild",
          "condition": "sicknessnotification.sickness!='employee' AND sicknessnotification.sickness!=null",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "sicknessnotification.numberdays"
            }
          ]
        },
        {
          "title": "Employee sick",
          "key": "sicknessnotification",
          "condition": "sicknessnotification.sickness='employee'",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "sicknessnotification.numberdays"
            }
          ]
        }
      ]
    },
    {
      "title": "Vacation management",
      "key": "holidays",
      "type": "vacation",
      "folder": [
        {
          "title": "By year",
          "key": "year",
          "method": "yearhistogram",
          "field": "vacation.holidayfrom",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "vacation.holidaysrequested"
            }
          ]
        },
        {
          "title": "Approved by me",
          "key": "HolidaysApprovedByMe",
          "condition": "vacation.approvedby=#CURRENTUSER#",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "vacation.holidaysrequested"
            }
          ]
        },
        {
          "title": "Not yet approved",
          "key": "HolidayNotApproved",
          "condition": "vacation.approvedby=null",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "vacation.holidaysrequested"
            }
          ]
        },
        {
          "title": "Approved",
          "key": "HolidayApproved",
          "condition": "vacation.approvedby!=null",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "vacation.holidaysrequested"
            }
          ]
        }
      ]
    },
    {
      "title": "Statement of earnings",
      "key": "statementofearnings",
      "type": "statementofearnings",
      "folder": [
        {
          "key": "year",
          "title": "By years",
          "field": "statementofearnings.yearofpayment"
        }
      ]
    },
    {
      "title": "Contract documents",
      "key": "contract",
      "type": "contractdocuments",
      "folder": [
        {
          "title": "By type",
          "key": "type",
          "field": "contractdocuments.type"
        }
      ]
    },
    {
      "title": "Documents",
      "key": "documents",
      "type": "document",
      "folder": [
        {
          "title": "By status",
          "key": "state",
          "field": "basicdocument.status"
        }
      ]
    }
]

'Unplugged' - Additional Examples

Vacation leave management / Urlaubsverwaltung

The following example shows a configuration for a personnel file. In the file are two object types for vacation leave management ("Urlaubsverwaltung"). You access the two object types, "Leave available" ("Urlaubsanspruch") and "Leave requested" ("Urlaubsantrag"), under this heading. The next level aggregates the years. Leave requests are aggregated in the next level down using the status catalog. The sum of relevant days for each status type is displayed here. Since there is only one "Leave available" object type per year, no "Business year" is necessary on the additional level.

Image Added

Following is an example of the configuration for the leave management only.

Code Block

language	js
linenumbers	true

[
  {
    "title": "Urlaubsverwaltung",
    "key": "urlaubv",
    "condition": "type='abwesenheit' OR type='urlaubsverwaltung'",
    "folder": [
		{
			"title": "Urlaubsantrag",
			"key": "ulantr",
			"condition": "abwesenheit.art='Urlaub'",
			"folder": [
				{
					"title": "Geschäftsjahre",
					"hide": true,
					"key": "year",
					"field": "abwesenheit.geschaeftsjahr",
					"folder": [
						{
							"title": "Genehmigt",   
							"key": "state",
							"hide":true,
							"field": "basicdocument.status",
							"showempty":true,
							"folder": [
								{
									"title": "Tage",
									"method": "sum",
									"key": "days",
									"field": "abwesenheit.tage"
								 }
							]
						}
					]
				}
			]
	},
	{
		"title": "Urlaubsanspruch",
		"key": "ulantr2",
		"type": "urlaubsverwaltung"
	}
]

Versions Compared

Old Version 2

New Version 3

Key

Introduction

Folder Structure Configuration

Syntax

Structure Service Testing Tool

Standard structure

List of structure terms

List of general object attributes (term: 'field')

Condition grammar

Configuration examples

One single folder for listing all context folder objects

One folder for each object type

Complex folder structure

'Unplugged' - Additional Examples

Vacation leave management / Urlaubsverwaltung

Page Comparison

Versions Compared

Old Version 2

New Version 3

Key

Introduction

Folder Structure Configuration

Syntax

Structure Service Testing Tool

Standard structure

List of structure terms

List of general object attributes (term: 'field')

Condition grammar

Configuration examples

One single folder for listing all context folder objects

One folder for each object type

Complex folder structure

'Unplugged' - Additional Examples

Vacation leave management / Urlaubsverwaltung