Verwendungsarten (usage) der metadata-collection.yml

In der metadata-collection.yml geben Sie an, für welche Bereiche (Verwendungsarten) innerhalb von agorum core die Metadaten gültig sein sollen. Hierzu dient die Angabe usage:

collection_04:   
  displayName: Test Metadaten Sammlung 04
  usage:     
     - docform
     - acic

In diesem Beispiel ist die Kollektion collection_04 für docform und für die Suche (acic = agorum core information center) gültig.

Diese Verwendungsarten existieren:

common

Bei jedem Metadatum können Sie mit common für alle Verwendungsarten Parameter überschreiben.

In folgendem Beispiel ist das Metadatum hervorgehoben:

-test_metadata_collection_01:
  displayName: Test Metadaten Sammlung 01
  usage:
    - docform
    - cmis
    - acic

  docform:

  acic:
    # overwrite title of acic
    title: 'Metadaten 01'

  items:
    - test_string:
      acic:
        title: 'Ein tolles Suchfeld'
        # remove auto subquery
        subQuery:
    - test_string_multi:
      acic:
        # disable for search
        unavailable: true
    - test_date:
      docform:
        # disable for docform
        unavailable: true
    - test_date_multi:
      acic:
        # overwrite complete subquery
        query: '${subQuery} allfields:agorum_metadata_collection_test_date_multi'
        subQuery:
        - query: '${value}'
          queryPart: 'agorum_metadata_collection_test_date_multi:[${valueFrom} TO ${valueTo}]'
          name: 'agorum_metadata_collection_test_date_multi_from_to'
          type: 'date-range'
          titleFrom: 'x ab Datum (yyyy-mm-dd)'
          titleTo: 'x bis Datum (yyyy-mm-dd)'
          # convert: 'dateString'
    - test_long:
      acic:
        subQuery:
        - title: 'Eine Untersuche'
          name: 'test_long'
          query: 'irgendwas:(${value})'
    - test_long_multi:
    - test_double:
    - test_double_multi:
    - test_boolean:
    - test_boolean_multi:
    - invoice_number:
      docform:
        extractor: date
        optional: true
    - invoice_date:
      common:
        displayName: 'Das Rechnungsdatum'
      docform:
        extractor: date
        optional: true
    - invoice_items:
      # when entries are defined in items, then only these entries are used, in this case only number
      items:
        - number:

In diesem Beispiel wurde für das Metadatum invoice_date ein common angegeben. Der Parameter displayName gilt somit für alle oben angegebenen Verwendungsarten:

• docform
• cmis
• acic

Die Felder für die Metadaten, etwa displayName, arbeiten mit einer Rangreihenfolge/Hierarchie.

• Ist etwa ein displayName in der metadata.yml beim Metadatum definiert und auch hier im common, verwendet das System die Angabe des displayNames im common.
• Die Angabe in der metadata.yml beachtet das System nicht mehr.

docform

Setzen Sie als Verwendungszweck docform, verwendet das System die Kollektion, etwa MusterfirmaEingangsRechnung wie im unteren Beispiel angegeben als docform-Dokumentyp. Der Dokumententyp enthält die angegebenen Metadaten.

# Defaults
_group: agorum.metadata.collection.test
_prefix: agorum_metadata_collection_test_
_default:
  type: string

# Hier soll das _prefix nicht verwendet werden
-MusterfirmaEingangsRechnung:
  displayName: Musterfirma Eingangsrechnung
  usage:
    - docform

  docform:

  items:
    - -acmf_rechnungsNummer:
      docform:
        extractor: string
    - -acmf_rechnungsDatum:
      docform:
        extractor: date
    - -acmf_betragBrutto:
      docform:
        extractor: currency
    - -acmf_betragNetto:
      docform:
        extractor: currency
    - -acmf_betragMwSt:
      docform:
        extractor: currency
    - -RgPosition:
      items:
        - acmf_positionsNummer:
          docform:
            extractor: string
        - acmf_artikelBezeichnung:
          docform:
            extractor: string
        - acmf_positionsBetrag:
          docform:
            extractor: currency
    - -MwStOK:
      displayName: Bruttobetrag entspricht nicht der Summe von Netto- und MwSt-Betrag
      docform:
        verifier: javascript
        verifierParameters: AC.eq(acmf_betragNetto+acmf_betragMwSt,acmf_betragBrutto)
        type: verify
        optional: false

Parameter

Zusätzlich können Sie pro Kollektion und Metadatum weitere Angaben speziell für docform tätigen. In welcher Reihenfolge Sie diese im Skript angeben, ist irrelevant.

extractorParameters: "let ac = require('ac'); if (!value){ 1 } else{ ac.parseDouble(value,'de'); }"

extractorParameters

Als extractor können Sie alle Werte angeben, die im docform-Dokumententyp im Feld Extraktion zu finden sind. In der Spalte extractor stehen die Werte, die Sie als extractor in der metadata-collection.yml angeben können.

acic

Setzen Sie als Verwendungszweck acic, verwendet das System die Kollektion, etwa test_metadata_collection_01 wie im unteren Beispiel angegeben als Filter in der Suche. Der Filter enthält die angegebenen Metadaten.

• Der Filter trägt den Namen agorum.metadata.collection.test_metadata_collection_01.
• Das System setzt in diesem Falle immer agorum.metadata.collection. vor den Collection-Namen.

-test_metadata_collection_01:
  displayName: Test Metadaten Sammlung 01
  usage:
    - acic

  acic:
    # overwrite title of acic
    title: 'Metadaten 01'
    acl: 'ACL_test_metatdata_collection_01'

  items:
    - test_string:
      acic:
        title: 'Ein Suchfeld'
        # remove auto subquery
        subQuery:
    - test_string_multi:
      acic:
        # disable for search
        unavailable: true
    - test_date:
    - test_date_multi:
      acic:
        # overwrite complete subquery
        query: '${subQuery} allfields:agorum_metadata_collection_test_date_multi'
        subQuery:
        - query: '${value}'
          queryPart: 'agorum_metadata_collection_test_date_multi:[${valueFrom} TO ${valueTo}]'
          name: 'agorum_metadata_collection_test_date_multi_from_to'
          type: 'date-range'
          titleFrom: 'x ab Datum (yyyy-mm-dd)'
          titleTo: 'x bis Datum (yyyy-mm-dd)'
          # convert: 'dateString'
    - test_long:
      acic:
        subQuery:
        - title: 'Eine Untersuche'
          name: 'test_long'
          query: 'irgendwas:(${value})'
    - test_long_multi:
    - test_double:
    - test_double_multi:
    - test_boolean:
    - test_boolean_multi:
    - invoice_number:
    - invoice_date:
    - invoice_items:
      # when entries are defined in items, then only these entries are used, in this case only number
      items:
        - number:

Zusätzlich können Sie pro Kollektion und Metadatum weitere Angaben speziell für die Suche tätigen. Grundsätzlich können Sie hierbei alle Einstellungen verwenden, die auch bei Filterdefinitionenen möglich sind. Allerdings müssen Sie diese in yml-Schreibweise definieren. Zusätzlich können Sie optional den Parameter dataSourceParameter angeben. Das obige Beispiel zeigt einige Anwendungsfälle.

Globale Einstellungen des Filters beeinflussen

Beispiel

# ...
-test_metadata_collection_01:
  displayName: Test Metadaten Sammlung 01
  usage:
    - acic

  acl: published

  acic:
    # overwrite title of acic
    title: 'Metadaten 01'
    #additionalBaseQuery: 'weitere Einschränkung der baseQuery'
    listConfig: 'Standard'
    listType: 'detail' # oder 'explorer'
    favorite: true
    # disableDefaultFilter: true
    filterSelection:
      "agorum.metadata.collection.name.agorum_metadata_collection_test_string":
        value: true
        subQuery:
          "agorum.metadata.collection.filter.subquery.agorum_metadata_collection_test_string":
            value:
              - test
          
     sortConfig: 
      - name: 'sortconfig_score_desc'
        text: 'Bester Treffer' 
        sort:
          - property: score
            direction: DESC
            
      - name: 'sortconfig_name_asc'
        text: 'Name (A-Z)' 
        sort:
          - property: name
            direction: ASC
            
      - name: 'sortconfig_createdate_desc'
        text: 'Erstelldatum (neu-alt)'
        sort:
          - property: createDate
            direction: DESC
            
      - name: 'sortconfig_lastmodifydate_desc'
        text: 'Zuletzt geändert (neu-alt)' 
        sort:
          - property: lastModifyDate
            direction: DESC
            
      - name: 'sortconfig_updatedate_desc'
        text: 'Intern aktualisiert (neu-alt)'
        sort:
          - property: updateDate
            direction: DESC
            
      - name: 'sortconfig_lastaddeddate_desc'
        text: 'Hinzufügedatum (neu-alt)' 
        sort:
          - property: lastAddedDate
            direction: DESC
            
      - name: 'sortconfig_contentsize_desc'
        text: 'Dateigröße (groß-klein)' 
        sort:
          - property: contentSize
            direction: DESC

    sortConfigName: 'sortconfig_updatedate_desc'*
    exportConfig:
      - name: 'exportconfig_all_default'
        text: 'Suchergebnis exportieren '
        export:
          output:
            resolveHeader: true
            exportMax: 100
            metadataCollection: 'agorum_metadata_collection_test_test_metadata_collection_01'

# ...

Parameter

Einen Namen für filterSelection definieren

Da das System die Namen der Collections automatisch bildet, müssen Sie diese in der Filterselection speziell angeben.

• Lautet ein Feld etwa test_string, lautet der vollständige Name für die filterSelection agorum.metadata.collection.name.agorum_metadata_collection_test_string.
• Bei einer subQuery lautet der vollständige Name agorum.metadata.collection.filter.subquery.agorum_metadata_collection_test_string.

cmis

-test_metadata_collection_01:
  displayName: Test Metadaten Sammlung 01
  usage:
    - cmis

  items:
    - test_string:
    - test_string_multi:
    - test_date:
    - test_date_multi:
    - test_long:

Für cmis-Dokumententypen existieren keine weiteren Einstellmöglichkeiten.

Geben Sie zusätzlich zum hier definierten Namen das Präfix agorum: an.

Das Ergebnis für CMIS sieht etwa so aus:

Dokumententyp: agorum:test_metadata_collection_01

Angabe von Propertys

agorum:agorum_metadata_collection_test_test_string

Angabe ohne Präfix der metadata collection

agorum:test_string

form

Setzen Sie als Verwendungszweck form, schalten Sie in der Bedienoberfläche im Detailfenster und dort in der Registerkarte Übersicht die angegebene Kollektion frei. Ein Benutzer kann dort etwa die Kollektion setzen oder bearbeiten:

daten:
  displayName: Beispiel Daten
  usage:
    - acic
    - form

Verwendungszweck form schaltet Metadata-Kollektion im Feld Typ frei

Mit den im nächsten Beispiel fett hinterlegten Angaben bei aon und deren Parameter können Sie des Weiteren die Bedienoberfläche beeinflussen:

# global
_group: agorum.workflow.samples.metadata.collection
_prefix: agorum_workflow_samples_metadata_collection_

# defaults
_default:
  type: string

daten:
  displayName: Beispiel Daten
  usage:
    - acic
    - agorum.workflow.samples.metadata.collection
    - form

  form:
    showEmpty: true

  items:
    - data_type:
    - data_description:
      - agorum.workflow.samples.metadata.collection:
        displayType: textArea
    - data_create_date:
      form:
        showEmpty: true

    - data_items:
      form:
        aon:
          showAppend: true
          showRowDelete: true
          showRowMove: true
          maxItems: 0
      items:
      - pos_position:
      - pos_description:
        form:
          aon: 
            label: 'Bezeichnung 1'
            actions:
              duplicate: true
              setColumnValues: true
      - pos_menge:

Parameter bei allen Feldern

Parameter bei „data_items“ (Liste)

Parameter bei „form“ und „pos_description“

Metadata-Kollektion bearbeiten

Sie können des Weiteren alle Parameter der form.element.list setzen, siehe Eigenschaften.

mapping_source

Setzen Sie als Verwendungszweck mapping_source, können Sie die metadata collection samt deren Metadaten als Quellmapping definieren.

• Mappings benötigen Sie etwa für die Knoten Daten konvertieren sowie für die DATEV-Knoten.
• Die Mappings stellen Sie in den Knoten über den Mapping-Editor ein.

Beispiel

invoice_incoming:
  displayName: Eingangsrechnung
  usage:
    - mapping_source  1 

  mapping_source:  2 
    mapping:
     displayName: '${displayName} - [${name}]'

 1 
Setzen Sie bei der metadata collection invoice_incoming den usage mapping_source, taucht diese metadata collection im Mapping-Editor beim Erstellen eines neuen Mappings im Feld Quelle auf.

Ein neues Mapping erstellen Sie rechts über .

Mapping-Editor: metadata collection invoice_incoming mit dem displayName Engangsrechnung im Feld Quelle wählen

# register mappings
- MetaDB: /MAIN_MODULE_MANAGEMENT/mappings/[ agorum.invoice ]

 2 
Der Abschnitt mapping_source ist optional. Wenn Sie ihn nicht angeben, nimmt das System den definierten displayName aus der metadata.yml und zeigt diesen in der Bedienoberfläche an.

Parameter

displayName (optional)

Definiert den Anzeigenamen der einzelnen Einträge im Mapping-Editor.

• Jeder Eintrag steht für ein Metadatum.
• Das System nimmt den definierten displayName aus der metadata.yml und zeigt diesen im Mapping-Editor an, sofern Sie den Parameter nicht angeben.

Beispiel

mapping_source:
    mapping:
     displayName: '${displayName} - [${name}]'

• Das System zeigt aufgrund des displayNames jedes Metadatum mit seinem displayName, also dem Anzeigenamen, im Mapping-Editor an.
• Das System zeigt aufgrund der Angabe - [${name}] den Namen des Metadatums in eckigen Klammern an.

Darstellung des displayNames im Mapping-Editor

mapping_target

Setzen Sie als Verwendungszweck mapping_source, können Sie die metadata collections als Zielmapping definieren.

• Mappings benötigen Sie etwa für die Knoten Daten konvertieren sowie für die DATEV-Knoten.
• Die Mappings stellen Sie in den Knoten über den Mapping-Editor ein.

Beispiel

invoice_incoming:
  displayName: Eingangsrechnung

# Kopfbereich
  usage:
    - mapping_target  1 
      
  mapping_target:
    mapping:
      displayName: '${name}'
      transformation: 'ItemsToList' # oder ObjectToObject
      validations:
        - mandatory

...
...
# Positionsbereich
 items:
    - agorum_accounting_document_number:
      mapping_target:
        mapping:
          mandatory: true # oder false
          template: '${value:f}'
          regex: '^([A-Z]{3})$'
          help: '<p>Anzuzeigender Hilfetext für die Rechnungsnummer'
          disabled: false # oder true

 1 
Setzen Sie bei der metadata collection invoice_incoming den usage mapping_target, taucht diese metadata collection im Mapping-Editor beim Erstellen eines neuen Mappings im Feld Ziel auf.

Ein neues Mapping erstellen Sie rechts über .

Mapping-Editor: metadata collection invoice_incoming mit dem displayName Engangsrechnung im Feld Ziel wählen

# register mappings
- MetaDB: /MAIN_MODULE_MANAGEMENT/mappings/[ agorum.invoice ]

Parameter im Kopfbereich unterhalb von usage

# Kopfbereich
  usage:
    - mapping_target
      
  mapping_target:
    mapping:
      displayName: '${name}'
      transformation: 'ItemsToList' # oder ObjectToObject
      validations:
        - mandatory

displayName (optional)

Definiert den Anzeigenamen der einzelnen Einträge im Mapping-Editor.

• Jeder Eintrag steht für ein Metadatum.
• Das System nimmt den definierten displayName aus der metadata.yml und zeigt diesen im Mapping-Editor an, sofern Sie den Parameter nicht angeben.

Beispiel

mapping_target:
    mapping:
     displayName: '${name}'

Das System zeigt aufgrund des angegebenen displayNames jedes Metadatum mit seinem Namen im Mapping-Editor an.

Darstellung des displayNames im Mapping-Editor

validations (optional)

Definiert, dass das System entweder ausschließlich Pflichtfelder (- mandatory) oder ausschließlich reguläre Ausdrücke (- regex) bei Metadaten und deren Werte prüft.

Das System prüft im Standard sowohl Pflichtfelder als auch reguläre Ausdrücke, sofern Sie den Abschnitt validations nicht angeben.

Beispiel

  mapping_target:
    mapping:
      displayName: '${name}'
      validations:
        - mandatory # oder - regex

• Pflichtfelder sind alle Einträge rechts im Mapping-Editor, die das System ausgegraut darstellt.
• Ein Pflichtfeld benötigt immer ein zugewiesenes Metadatum (linker Eintrag).
• Welches Metadatum ein Pflichtfeld ist, definieren Sie über den Parameter mandatory im Positionsbereich.

Eintrag im Mapping-Editor als Pflichtfeld

So führen Sie die Prüfung durch:

1. Klicken Sie im Mapping-Editor auf Prüfen.
2. Wählen Sie über die Objektauswahl ein Dokument.
   
   Das System zeigt im Standard alle Dokumente an, die vom Typ der jeweiligen Quellkollektion sind.
3. Klicken Sie auf Prüfung.
   
   Wenn Sie auf Fehler klicken, erhalten Sie nur Metadaten, deren Werte fehlen oder nicht dem regulären Ausdruck entsprechen, sofern Sie einen solchen im Parameter regex im Positionsbereich angegeben haben.

Prüfung im Mapping-Editor

transformation

Definiert einen dieser Konvertierungstypen:

• ObjectToObject
• ItemsToList

Beispiel

  mapping_target:
    mapping:
      displayName: '${name}'
      validations:
        - mandatory
      transformation: 'ItemsToList' # oder ObjectToObject

ObjectToObject

Dieser Typ erzeugt eine konvertierte Kopie des Quellobjekts.

Quellobjekt

{
  "firstName": "Max",
  "lastName": "Mustermann"
}

Im Mapping definieren Sie etwa, dass das System lastName in name konvertieren soll.

Ergebnis

{
  "firstName": "Max",
  "name": "Mustermann"
}

ItemsToList

Dieser Typ fügt etwa Rechnungsdaten mit Positionen und Kopfdaten zu einer flachen Objektstruktur zusammen, sodass daraus ein flaches Array entsteht.

Quellobjekt

{
 "invoiceID": "12345",
 "positions": [
  {
    "net_amount": 24.00,
    "article_number": "248127381"
  },
  {
    "net_amount": 3.00,
    "article_number": "333227381"
  }
 ]
}

Im Mapping definieren Sie etwa, dass das System invoiceID, net_amount und article_number auf invoice_id, amount und articleNumber konvertieren soll.

Ergebnis

[
  {
   "invoice_id": "12345",
   "amount": "24.00",
   "articleNumber": "248127381"
  },
  {
   "invoice_id": "12345",
   "amount": "3.00",
   "articleNumber": "333227381"
  }
]

Parameter im Positionsbereich unterhalb von items

# Positionsbereich
 items:
    - agorum_doku_invoice_number:
      mapping_target:
        mapping:
          mandatory: true # oder false
          template: '${value:f}'
          regex: '^([A-Z]{3})$'
          help: '<p>Anzuzeigender Hilfetext für die Rechnungsnummer'
          depends: 'agorum_accounting_document_supplier_number'
          #disabled: false # oder true

mandatory

Beispiel

# Positionsbereich
 items:
    - agorum_doku_invoice_number
      mapping_target:
        mapping:
          mandatory: true # oder false

• Pflichtfelder sind alle Einträge rechts im Mapping-Editor, die das System ausgegraut darstellt.
• Ein Pflichtfeld benötigt immer ein zugewiesenes Metadatum (linker Eintrag).
• Pflichtfelder können Sie im Mapping-Editor nicht löschen.

Eintrag im Mapping-Editor als Pflichtfeld

template (optional)

Definiert ein Template für das Metadatum, das im Mapping-Editor als Ersetzungsausdruck dient.

• Der Ersetzungsausdruck erscheint, wenn Sie auf neben einem Eintrag klicken.
• Sie können alle Schreibweisen der JavaScript-Bibliothek office/fill-template verwenden.

Beispiel

# Positionsbereich
 items:
    - agorum_doku_document_id:
      mapping_target:
        mapping:
          template: '${value:f}'

Angegebenes Template als Ersetzungsausdruck im Mapping-Editor

regex (optional)

Definiert einen regulären Ausdruck für das Metadatum.

Beispiel

# Positionsbereich
 items:
    - agorum_doku_invoice_number:
      mapping_target:
        mapping:
          regex: ^[a-zA-Z0-9]+$

• Das System prüft den Eintrag / das Metadatum, das Sie auf der linken Seite im Mapping-Editor angeben, auf das hinterlegte RegEx.
• In diesem Beispiel darf das Metadatum nur drei große Buchstaben von A bis Z als Wert besitzen.

So führen Sie die Prüfung durch:

1. Klicken Sie im Mapping-Editor auf Prüfen.
2. Wählen Sie über die Objektauswahl ein Dokument.
3. Klicken Sie auf Prüfung.
   
   Wenn Sie auf die Schaltfläche Fehler klicken, erhalten Sie nur Metadaten, deren Werte fehlen oder nicht dem regulären Ausdruck entsprechen, sofern Sie einen solchen angegeben haben.

Angezeigte Fehler bei der Prüfung im Mapping-Editor

• In diesem Beispiel zeigt das System drei Fehler für die Rechnungsnummer an, da der Wert RE291941-1 nicht dem regulären Ausdruck entspricht.
• Erlaubt sind nur drei Großbuchstaben von A bis Z.
• Wenn Sie im Mapping-Editor ein Positionsmetadatum als Quelle ausgewählt haben, zeigt das System wie hier im Beispiel etwa die Rechnungsnummer dreimal an. Es wiederholt den Fehler also für jede Position. In diesem Falle enthält die Rechnung RE291941-1 drei Artikelpositionen.

help (optional)

Zeigt einen Hilfetext zum jeweiligen Metadatum an.

Beispiel

# Positionsbereich
 items:
    - agorum_doku_invoice_number:
      mapping_target:
        mapping:
          help: '<p>Anzuzeigender Hilfetext für die Rechnungsnummer'

Klicken Sie im Mapping-Editor neben dem Metadatum auf , um den Hilfetext zu sehen.

Hilfetext beim Metadatum im Mapping-Editor

depends (optional)

Definiert ein abhängiges Metadatum.

Geben Sie den vollständigen Namen des Metadatums an.

Beispiel

# Positionsbereich
 items:
    - agorum_doku_invoice_pos_number:
      mapping_target:
        mapping:
          depends: 'agorum_doku_invoice_description'

Wenn Sie im Mapping-Editor wie in diesem Beispiel das Metadatum agorum_doku_invoice_description als Zielfeld wählen, erzeugt das System darunter automatisch einen weiteren Eintrag mit dem Metadatum agorum_doku_invoice_pos_number.

Abhängiges Metadatum

disabled

Beispiel

# Positionsbereich
 items:
    - agorum_doku_invoice_pos_number:
      mapping_target:
        mapping:
          disabled: true # oder false

Metadatum agorum_doku_invoice_pos_number steht als Zielfeld nicht mehr zur Verfügung