JavaScript-Bibliothek common/metadata

Diese Bibliothek bietet Funktionen zum Laden oder Speichern von Objekt-Metadaten.

• Für die Konvertierung und Zuordnung der Metadaten werden die Definitionen aus dem Metadaten-Designer verwendet.
• Es müssen dort alle verwendeten Metadaten definiert sein.
• Wenn Sie die empfohlene Datei metadata.yml zum Erstellen von Metadaten verwenden, sind die Metadaten automatisch im Metadaten-Designer vorhanden.

Verwendung

Binden Sie die Bibliothek stets am Anfang eines Skripts ein:

let metadata = require('common/metadata');

Funktionen

load

Lädt entweder alle oder bestimmte Metadaten eines Objekts.

Das System lädt alle Metadaten, inklusiver interner, die direkt auf dem Objekt sitzen. Falls Sie dies nicht wünschen, verwenden Sie stattdessen folgenden Aufruf. Dadurch werden die internen Metadaten nicht ausgegeben:

metadata().load(object, '~') 

Beispiel

// alle Metadaten
let all = metadata().load(object [, filter1 [, filter2 [, ...]]]).data();
// filter siehe unten
// Zugriff auf diese Daten, etwa:
// all.name
// all.description


// ausgewählte Metadaten
let some = metadata().load(object, 'name', 'acmf_kundenName').data();
// Zugriff auf diese Daten, etwa:
// some.name
// some.acmf_kundenName

// gefilterte Metadaten
let acmf = metadata().load(object, /^acmf_/).data();
// Zugriff auf diese Daten, etwa:
// acmf.acmf_kundenName
// acmf.acmf_kundenNummer

all

Lädt alle benutzerdefinierten (keine eingebauten) Metadaten, die entweder auf dem Objekt selbst definiert sind oder darauf vererbt wurden, oder Metadaten vom Typ list.

Unterschied zu merge():

• all(): Gibt bei vererbten Metadaten alle Werte als verschachteltes Array zurück
• merge(): Gibt bei vererbten Metadaten nur den ersten Wert zurück

Beispiel

let data = metadata.all(object, /^acmf_/);

// Filtern nach Metadaten
// Sie können auch mehrere Filter angeben,
// deren Daten dann gesammelt zurückgegeben werden:
let dataMulti = metadata.all(object, /^acmf_/, 'identifier', '~', '~~' /*, weitere Filter */);

// Laden der direkten und vererbten Metadaten
metadata().load(object, '~', '~~').data();

Beispiel Metadatum vom Typ „list“

// Laden von nicht vererbten Listenmetadaten:
metadata.all(object, '~');

// Ergebnis:
{
  "agorum_accounting_document_item_list" : [ {
    "number" : "123"
  } ]
}

Das System gibt vererbte Metadaten immer als verschachteltes Array aus:

// Laden von vererbten Listenmetadaten:
metadata.all(object, '~~');

// Ergebnis:
{
  "agorum_accounting_document_item_list" : [ [ {
    "number" : "456"
  } ] ]
}

merge

Lädt die Metadaten des Objekts selbst als auch Werte, die nur darauf vererbt wurden.

• Existiert für einen Schlüssel mehr als ein Wert, so wird nur der erste Wert geladen.
• Die Funktion bildet das Verhalten der load-Methode der älteren filingassistant/metadata-Bibliothek ab.

Beispiel

// Kundeninfos der zu document gehörigen Akte abrufen
let kunde = metadata().merge(document, /^acmf_kunde/).data();

save

Schreibt Metadaten auf ein Objekt.

Beispiel

let data = {
  name: 'Name xy',
  acmf_kundenName: 'Name AG'
};

// einzelnes Objekt
metadata(data).save(object [, filter1 [, filter2 [, ...]]]);
// filter siehe unten

// mehrere Objekte
let m = metadata(data);

objects.forEach(object => m.save(object));

Beispiel zum Entfernen von Metadaten

let data = {
  name: null, // metadata "name" wird vom Objekt entfernt
  acmf_kundenName: '' // metadata "acmf_kundenName" bleibt erhalten und hat den Wert ''
};

metadata(data).save(object);

data

Gibt die geladenen Metadaten als JavaScript-Objekt zurück.

Diese Methode wird nach load() oder merge() aufgerufen, um auf die tatsächlichen Metadaten-Werte zuzugreifen.

 

Syntax

let metadataObject = metadata().load(object).data();

 

Rückgabewert

Ein JavaScript-Objekt mit den geladenen Metadaten als Schlüssel-Wert-Paare.

 

Beispiel

let objects = require('common/objects');
let metadata = require('common/metadata');

let object = objects.find('58551300-adbd-11f0-af40-02420a0a0012');

let m = metadata().load(object, 'name', 'description');
let data = m.data();

console.log('Name: ' + data.name);
console.log('Beschreibung: ' + data.description);

Arbeiten mit Listenmetadaten

Lesen von Listenmetadaten

Siehe Beispiele unter all und Beispiel Metadatum vom Typ list.

Schreiben von Listenmetadaten

let objects = require('common/objects');
let metadata = require('common/metadata');

let object = objects.find('58551300-adbd-11f0-af40-02420a0a0012');

// Setting new list meta data
metadata({
  agorum_accounting_document_item_list: [
    { number: '123', description: 'Position 1' },
    { number: '456', description: 'Position 2' },
  ],
}).save(object);

// Adding to an existing meta data list
let existing = metadata.all(object, 'agorum_accounting_document_item_list');
existing.agorum_accounting_document_item_list.push({ number: '789', description: 'Position 3' });
metadata(existing).save(object);

getFields

Gibt die Metadaten-Felddefinitionen aus dem Metadaten-Designer zurück. Optional können Filter übergeben werden, um nur bestimmte Felder abzurufen.

Diese Funktion ist nützlich, um programmatisch herauszufinden, welche Metadaten im System definiert sind und welche Eigenschaften diese haben.

 

Syntax

let fields = metadata.getFields([filter1 [, filter2 [, ...]]]);

 

Parameter

• filter (optional): Ein oder mehrere Filter, um die zurückgegebenen Felder einzuschränken. Es gelten dieselben Filtermechanismen wie bei load, save, merge und all (siehe Abschnitt Vorhandene Filter).

 

Rückgabewert

Ein Array von Objekten mit folgenden Eigenschaften pro Feld:

Eigenschaft	Typ	Beschreibung
name	string	Technischer Name des Metadatums
type	string	Datentyp des Metadatums (z. B. string, date, long, double, boolean, list)
multi	string	Gibt an, ob das Feld mehrere Werte aufnehmen kann
displayName	string	Anzeigename des Metadatums
description	string	Kurzbeschreibung des Metadatums
descriptionLong	string	Ausführliche Beschreibung des Metadatums
inheritance	string	Vererbungstyp: builtIn, inherited oder notInherited
format	string	Format des Metadatums (z. B. Datumsformat)
defaultValue	string	Standardwert des Metadatums
readOnly	boolean	Gibt an, ob das Feld schreibgeschützt ist
optional	boolean	Gibt an, ob das Feld optional ist
restricted	boolean	Gibt an, ob das Feld eingeschränkt ist
mappedName	string	Interner zugeordneter Name des Metadatums
displayType	string	Anzeigetyp für die Oberfläche
verificationRegex	string	Regulärer Ausdruck zur Validierung
verificationType	string	Art der Validierung
verificationFailText	string	Fehlermeldung bei fehlgeschlagener Validierung
dataSource	string	Datenquelle für das Metadatum
item	object	Bei Listenmetadaten: Beschreibung der Unterfelder (gleiche Struktur wie ein Feld)

 

Beispiel

let metadata = require('common/metadata');

// Alle Felddefinitionen abrufen
let allFields = metadata.getFields();

// Nur Felder mit bestimmtem Präfix abrufen
let acmfFields = metadata.getFields(/^acmf_/);

// Nur nicht vererbte Felder abrufen
let nonInherited = metadata.getFields('~');

// Bestimmtes Feld abrufen
let nameField = metadata.getFields('name');

// Ergebnis ist ein Array, z. B.:
// [
//   {
//     name: 'acmf_kundenName',
//     type: 'string',
//     displayName: 'Kundenname',
//     inheritance: 'notInherited',
//     readOnly: false,
//     ...
//   },
//   ...
// ]

 

Vorhandene Filter bei load, save, merge und getFields

Die folgenden Filter können Sie bei load, save, merge und getFields übergeben.

• Mit den Filtern können Sie gezielt bestimmte Metadaten wählen.
• Die Filter beziehen sich immer auf den Namen des Metadatums, nicht auf den Inhalt.
• Allgemein können Sie beliebig viele Filter übergeben. Alle unten beschriebenen Möglichkeiten können Sie beliebig mischen.

Filtermöglichkeiten

Möglichkeit 1

Ein Filter kann der Name eines Metadatums sein:

// ausgewählte Metadaten 
let some = metadata().load(object, 'name', 'acmf_kundenName').data();

In diesem Beispiel wird nur das Metadatum name und acmf_kundenName geladen.

Möglichkeit 2

Ein Filter kann ein regulärer Ausdruck sein:

// ausgewählte Metadaten 
let some = metadata().load(object, /^acmf_kunde/).data();

In diesem Beispiel werden alle Metadaten geladen, die mit acmf_kunde beginnen.

Möglichkeit 3

Ein Filter kann ein '~' sein. Diese Schreibweise definiert Metadaten, die nicht vererbt werden:

// ausgewählte Metadaten 
let some = metadata().load(object, '~').data();

In diesem Beispiel werden alle Metadaten geladen, die nicht vererbt werden.

Möglichkeit 4

Ein Filter kann ein '~~' sein. Diese Schreibweise definiert Metadaten, die vererbt werden:

// ausgewählte Metadaten 
let some = metadata().load(object, '~~').data();

In diesem Beispiel werden alle Metadaten geladen, die vererbt werden.

Beispiele mit Filter

// ausgewählte Metadaten 
let some = metadata().load(object, 'name', 'description', '~~').data();

Hier werden alle vererbten Metadaten geladen. Ferner werden die Attribute name und description des Objekts (egal ob vererbt oder nicht) geladen.

Benutzer-Metadaten

Bestimmte Benutzer-Metadaten (User-Tags), etwa user_ag_tags, kann nur der jeweilige Benutzer setzen oder lesen.

Hierbei ist die Session des Benutzers entscheidend, für welchen Benutzer dieses Metadatum gesetzt wird:

/* global sc */
let objects = require('common/objects');
let metadata = require('common/metadata');

// Getting an agorum core object
let object = objects.find('<object id>');

metadata({
  user_ag_tags: ['Test'],
}).save(object);

In dem obigen Beispiel wird Test als User-Tag auf das Objekt gesetzt. Dabei ist entscheidend, mit welchem Benutzer die Session (sc) verbunden ist.

Im folgenden Beispiel wird demonstriert, wie mit einer Admin-Session ein Benutzer-Metadatum für einen anderen Benutzer gesetzt werden kann:

/* global sc */
let objects = require('common/objects');
let metadata = require('common/metadata');

// get session as user
let scUser = sc.asUser(objects.find('user:demo'));

// initialize object session as user 
let objectsUser = objects(scUser);

// get object with session of user
let object = objectsUser.find('<object id>');

// set user tag on object of other user (here: demo)
metadata({
  user_ag_tags: ['Test'],
}).save(object);

clearUser

Entfernt ein bestimmtes Benutzer-Metadatum von einem Objekt für alle Benutzer.

Diese Funktion ist hilfreich, wenn Sie ein benutzerspezifisches Metadatum vollständig von einem Objekt entfernen möchten, unabhängig davon, für welche Benutzer es gesetzt wurde.

Diese Funktion ist besonders nützlich in folgenden Szenarien:

• Bereinigung von Benutzer-Metadaten bei Objektmigrationen
• Zurücksetzen von benutzerspezifischen Einstellungen auf Objekten
• Löschen veralteter Benutzer-Metadaten im Rahmen von Wartungsarbeiten

 

Syntax

metadata.clearUser(object, metadataKey);

 

Parameter

• object (agorum.Object): Das agorum core Objekt, von dem das Benutzer-Metadatum entfernt werden soll
• metadataKey (string): Der Name des zu entfernenden Benutzer-Metadatums (muss mit user_ beginnen)

 

Beispiel

Voraussetzung für dieses Beispiel: Sie haben ein Metadatum user_doc_test_string definiert.

/* global sc */

let objects = require('common/objects');
let metadata = require('common/metadata');

let object = objects.find('/agorum/roi/Files/Demo/Willkommen.pdf');
/*
let write = user =>
  metadata({
    user_doc_test_string: 'test (' + user.name + ')',
  }).save(objects.sc(sc.asUser(user)).find(object));

write(objects.find('user:roi'));
write(objects.find('user:demo'));
*/

metadata.clearUser(object, 'user_doc_test_string');