...

This article describes how to build folder structures ('virtual' folders') in product version 4. The new folder structure replaces the familiar subfolders from of 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 simplereasier.

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 Find here a presentation that explains how folder structures are set up and used (German only): Widget Connectorurlhttp://youtube.com/watch?v=U5dMdgl3T2I

Folder Structure Configuration

...

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:

...

Figure 1: Standard structure of a folder

Children tree definition

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

[
  {
    "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

...

[ ]

...

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.

...

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'.

...

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.

...

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

...

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.

...

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

...

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

...

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

...

[ ...,
  {
    "title": "Documents",
    "key": "Docs",
    "field": "eoxdocument.eoxdoctype",
    "sort": "title"
  },
... ]

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

...

created

...

Created

...

Date of object creation.

...

creatortitle

...

Modified

...

'Name, Firstname' of creator.

...

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.

...

Condition grammar

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

...

#LASTYEAR#

...

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

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

...

Reference tree definition

Beginning with product version 5.16 an additional tree is offered that shows all objects referencing the current folder.

The structure tree that was described in the first section is able to show all children of a folder. If you model id references to the folder it is useful to show also these references to the current folder. There may be many other referencing objects and it is useful to be able to navigate to them. 

Since product version 5.16, it is possible to model and use a reference tree to an object. Contrary to the structure tree, which is selecting all children, the reference tree is selecting all objects that have references to a target object. For example, you have two other objects, project and task that reference to a target object. The object 'project' defines an id reference field named 'participants' and the other object 'task' defines two reference fields named 'reviewer' and 'responsible'. We have 3 modeled id reference fields to the target object. The condition that is used to select these referencing object is this : 

project.participants=#TARGETID# OR task.responsible=#TARGETID# OR task.reviewby=#TARGETID#

The default reference tree that is used for this is:

[ 
{
        "title": "project",
        "title_locales": {
          "en": "Project",
          "de": "Projekt"
        },
        "key": "ReferenceType#project",
        "type": "project",
        "folder": [
          {
            "title": "participants",
            "title_locales": {
              "en": "Participants",
              "de": "Teilnehmer"
            },
            "key": "Referencefield#project.participants"
          }
        ]
      },
      {
        "title": "task",
        "title_locales": {
          "en": "Task",
          "de": "Aufgabe"
        },
        "key": "ReferenceType#task",
        "type": "task",
        "folder": [
          {
            "title": "Responsible",
            "title_locales": {
              "de": "Verantwortlich",
              "en": "Responsible"
            },
            "key": "Referencefield#task.responsible",
            "condition": "task.responsible=#TARGETID#"
          },
          {
            "title": "reviewby",
            "title_locales": {
              "de": "Prüfung von",
              "en": "Review by"
            },
            "key": "Referencefield#task.reviewby",
            "condition": "task.reviewby=#TARGETID#"
          }
        ]
      }

Each referencing type is given as a folder and each referencing field is a subtree element. To distinguish between the task responsible and the task reviewer an additional condition is set, that is using the current target id. 

List of tree node element properties

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

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

[ ...,
  {
    "title": "Documents",
    "key": "Docs",
    "field": "eoxdocument.eoxdoctype",
    "sort": "title"
  },
... ]

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

Condition grammar

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

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

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

{
  "title": "Edited in August 2016",
  "key": "Edited2016_08",
  "condition": "modified(YEAR)=2016 AND modified(MONTH)=08"
}

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

"condition":"modifier=#CURRENTUSER#"

"condition": "modifier!=#CURRENTUSER"

"condition": "version<4"

"condition": "version>1"

"condition": "version>=1"

"condition": "version<=1"

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

"

condition": "

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

"

condition": "

doc.active=null"

"condition": "

doc.active=false"

"

condition": "

doc.active=

true"

"condition": "

"condition": "version<4"

"condition": "version>1"

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

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

"condition": "doc.active=null"

"condition": "doc.active=false"

"condition": "doc.active=true"

"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.

[
 {
  "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.

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

Complex folder structure

The following complex example shows how to configure subnodes.

...

...

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 shortest configuration with only one node. This node offers access to a list of all objects within the context folder.

[
 {
  "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.

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

Complex folder structure

The following complex example shows how to configure subnodes.

[
    {
      "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": "AllModified by Martin",
          "key": "CommonModifiedByMartin",
          "foldercondition": [ "modifier='Bartonitz'",
          "folder": [
  {          {
"title": "Created by me",           "keytitle": "CreatedByMeModified by Martin by years",
              "conditionkey": "creator=#CURRENTUSER#"modifiedyear",
          },    "field": "modified",
   {           "titlemethod": "Modified by meyearhistogram",
          "key": "ModifiedByMe", }
         "condition": "modifier=#CURRENTUSER#" ]
        },
        {
          "title": "ModifiedBy by otherstypes",
          "key": "ModifiedByOthertype",
          "conditionfield": "modifier!=#CURRENTUSER# AND modifier!='Bartonitz'type"
        },
        {
          "title": "Modifiedby byfile Martintype",
          "key": "ModifiedByMartinmimetypegroup",
          "conditionfield": "modifier='Bartonitz'mimetypegroup",
          "folder": [
  },
         {
   
          "title": "ModifiedYear by Martin by yearsof modification",
  
           "key": "modifiedyear",
   
          "field": "modified",
   
          "method": "yearhistogram"
        },
   }     {
     ]     "title": "Year of  },
        {creation",
          "titlekey": "By typescreatedyear",
          "keyfield": "typecreated",
          "fieldmethod": "typeyearhistogram"
        },
        {
          "title": "byBy file typecreator",
          "key": "mimetypegroupcreator",
          "field": "mimetypegroupcreatortitle"
        },
        {
          "title": "Year of modification",
          "key": "modifiedyearBy modifier",
          "fieldkey": "modifiedmodifier",
          "methodfield": "yearhistogrammodifiertitle"
        },
        {
          "title": "YearTime period of creationmodification",
          "key": "createdyearModifiedRange",
          "fieldmethod": "createddaterange",
          "methodfield": "yearhistogrammodified"
        },
        {
          "title": "By creatorTime period of creation",
          "key": "creatorCreatedRange",
          "fieldmethod": "creatortitledaterange",
          },
"field": "created"
       { }
      ]
  "title": "By modifier"},
    {
      "keytitle": "modifierSickness notification",
   
      "fieldkey": "modifiertitlesicknessnotification",
        },
    "type": "sicknessnotification",
   {      "folder": [
    "title": "Time period of modification",{
          "keytitle": "ModifiedRangeLonger then 3 days",
          "methodkey": "daterangesicknessnotificationlong",
          "fieldcondition": "modifiedsicknessnotification.numberdays>3"
        },
        {
          "title": "Time period of creationBy years",
          "key": "CreatedRangeyear",
          "method": "daterangeyearmonthhistogram",
          "field": "createdsicknessnotification.begin",
        }  "folder": [
   ]     },     {

     "title": "Sickness notification",       "key": "sicknessnotificationdays",
      "type": "sicknessnotification",       "foldermethod": [
     "sum",
   {           "title": "Days"Longer,
 then 3 days",           "keyfield": "sicknessnotificationlongsicknessnotification.numberdays",
          "condition": "sicknessnotification.numberdays>3"  }
      },    ]
    {    },
      "title": "By years",{
          "keytitle": "yearChild sick",
          "methodkey": "yearhistogramsicknessnotificationchild",
          "fieldcondition": "sicknessnotification.sickness!='employee' AND sicknessnotification.beginsickness!=null",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "sicknessnotification.numberdays"
            }
          ]
        },
        {
          "title": "ChildEmployee sick",
          "key": "sicknessnotificationchildsicknessnotification",
          "condition": "sicknessnotification.sickness!='employee' AND sicknessnotification.sickness!=null",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "sicknessnotification.numberdays"
            }
          ]
   ]     }
   },   ]
    },
{    {
      "title": "EmployeeVacation sickmanagement",
  
       "key": "sicknessnotificationholidays",
  
       "conditiontype": "sicknessnotification.sickness='employee'vacation",
   
      "folder": [
        {
        {  "title": "By year",
          "key": "daysyear",
  
           "method": "sumyearhistogram",
  
           "titlefield": "Daysvacation.holidayfrom",
          "folder": [
  "field": "sicknessnotification.numberdays"         {
   }           ]
"key": "days",
       }       ]
"method": "sum",
   },     {       "title": "Vacation managementDays",
      "key": "holidays",       "typefield": "vacation.holidaysrequested",
         "folder": [  }
      {    ]
      "title": "By year",},
        {
          "keytitle": "yearApproved by me",
          "methodkey": "yearhistogramHolidaysApprovedByMe",
          "fieldcondition": "vacation.holidayfromapprovedby=#CURRENTUSER#",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "vacation.holidaysrequested"
            }
          ]
        },
        {
          "title": "ApprovedNot byyet meapproved",
          "key": "HolidaysApprovedByMeHolidayNotApproved",
          "condition": "vacation.approvedby=#CURRENTUSER#null",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "vacation.holidaysrequested"
            }
          ]
        },
        {
          "title": "Not yet approvedApproved",
          "key": "HolidayNotApprovedHolidayApproved",
          "condition": "vacation.approvedby!=null",
          "folder": [
            {
              "key": "days",
              "method": "sum",
              "title": "Days",
              "field": "vacation.holidaysrequested"
            }
          ]
        }
      ]
    },
    {
      "title": "Statement of earnings",
      "key": "statementofearnings",
      "type": "statementofearnings",
      "folder": [
        {
          "titlekey": "Approvedyear",
          "keytitle": "By "HolidayApprovedyears",
          "conditionfield": "vacation.approvedby!=null",statementofearnings.yearofpayment"
        }
  "folder": [   ]
    },
    {
      "title": "Contract documents",
      "key": "dayscontract",
       
      "methodtype": "sumcontractdocuments",
          "folder": [
   "title": "Days",    {
          "fieldtitle": "vacation.holidaysrequested"By type",
          "key": "type",
}           ]"field": "contractdocuments.type"
        }
      ]
    },
    {
      "title": "Statement of earningsDocuments",
      "key": "statementofearningsdocuments",
      "type": "statementofearningsdocument",
      "folder": [
        {
          "keytitle": "yearBy status",
          "titlekey": "By yearsstate",
          "field": "statementofearningsbasicdocument.yearofpaymentstatus"
        }
      ]
    },
    {
      "title": "Contract documents",
      "key": "contract",
      "type": "contractdocuments",
      "folder": [
        {
          "title": "By type",
     ]

'Unplugged' - Additional Examples

Vacation Management / Urlaubsverwaltung

The following example shows a configuration for a personnel file. There are two object types for vacation management ("Urlaubsverwaltung") in the file. 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

This is an example of the configuration for the vacation management only:

[
  {
    "title": "Urlaubsverwaltung",
    "key": "typeurlaubv",
    
     "fieldcondition": "contractdocuments.type"
        }
      ]
    }type='abwesenheit' OR type='urlaubsverwaltung'",
    {"folder": [
		{
			"title": "Urlaubsantrag",
			"key": "ulantr",
			"titlecondition": "Documentsabwesenheit.art='Urlaub'",
			"folder": [
				{
					"title": "Geschäftsjahre",
					"hide": true,
					"key": "documentsyear",
      "type
					"field": "documentabwesenheit.geschaeftsjahr",
      					"folder": [
        {
          						{
							"title": "By statusGenehmigt",   
       							"key": "state",
          							"hide":true,
							"field": "basicdocument.status",
							"showempty":true,
							"folder":       }
      ]
    }
]

'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 Removed

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

[
  {
    "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"
	}
][
								{
									"title": "Tage",
									"method": "sum",
									"key": "days",
									"field": "abwesenheit.tage"
								 }
							]
						}
					]
				}
			]
	},
	{
		"title": "Urlaubsanspruch",
		"key": "ulantr2",
		"type": "urlaubsverwaltung"
	},
    {
      "title": "Project",
      "key": "Year",
      "type": "project",
      "field" : "project.startday",
      "method" : "yearhistogram",
      "expanded": true,
      "folder":[{
        "title": "Projects",
        "hide":true,
        "key": "ProjectMonth",
        "type": "project",
        "field" : "project.startday",
        "method" : "monthhistogram",
        "expanded": true
      }]
  }

]

Specific settings for Elasticsearch

A limitation regarding 'conditions' was introduced with the Elasticsearch version that is used in yuuvis® RAD 8.16.

Reason: https://github.com/elastic/elasticsearch/issues/55303

To solve this, this property is introduced: indices.query.bool.max_nested_depth

For more details, see this documentation: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-settings.html

Solution for yuuvis® RAD since 8.16 LTS

1. Add this line to the elasticsearch.yml file in the config folder of the elasticsearch installation:
   indices.query.bool.max_nested_depth: 100
2. Restart the service.