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', '~', '~~', ...);

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

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_listx" : [ [ {
    "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 metadata = require('common/metadata');
let objects = require('common/objects');

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);

Vorhandene Filter bei load, save und merge

---

Die folgenden Filter können Sie bei load, save und merge ü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(obj);

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');