search-utils - Hilfsbibliothek für die Suche verwenden

Verwendung

let searchUtils = require('/agorum/roi/customers/agorum.composite/js/aguila/search/search-utils');

Die Suche mit den Einstellungen des Benutzers aufrufen

Der Benutzer kann in der Home-Bar (kleines Zahnrad neben der Sucheingabe) einstellen, wie sich die Standardsuche öffnet. Verwenden Sie Funktion showSearchWindow, wenn sich die Suche programmtechnisch öffnen soll.

Beispiel

Das System öffnet die Suche und gibt als Sucheingabe optionaler Suchstring mit.
Das System wählt die Standardkonfiguration Alles (ac_all).
Beim Öffnen gelten die Einstellungen des Benutzers, ob er etwa im Standard den Detailbereich und den Filter angezeigt haben möchte.

let searchUtils = require('/agorum/roi/customers/agorum.composite/js/aguila/search/search-utils');

let settings = searchUtils.loadSearchWindowSettings();
searchUtils.showSearchWindow({
  type: 'agorum.composite.acic',
  query: 'optionaler Suchstring',
  settingName: 'ac_all',
}, settings, 'Titel der Suche');

Den CSV-Export mit exportSearch() erstellen

Sie erstellen mithilfe der Bibliothek search-utils einen CSV-Export auf Basis eines Suchergebnisses.

Die Funktion exportiert anhand einer Konfiguration oder einer mitgegebenen Suche oder eines Filters ein Suchergebnis als CSV-Datei.
Sie können den Export in einem Filter oder in einer Suche definieren oder als Bibliothek aufrufen.

Einfacher Aufruf als Bibliothek

let searchUtils = require('/agorum/roi/customers/agorum.composite/js/aguila/search/search-utils');

searchUtils.exportSearch({
  query: 'nameextension:pdf W*',
  uuid: true,
  resolveHeader: true
});

Mögliches Ergebnis

Name;Beschreibung;Ersteller;Erstelldatum;Dateigröße;Zuletzt geändert durch;Letzte Änderung;uuid
"Willkommen.pdf";;"roi";"2020-09-03T13:50:23.698Z";"185688";"roi";"2020-09-03T13:50:23.899Z";"6a233b20-edec-11ea-9888-02420a0a0012"

Das System wandelt im Standard alle Werte in Zeichenketten.
Das System wandelt Datumswerte in einen Standard ISO-String.
Sie können die Formatierung der Werte über einen eigenen rowHandler individuell gestalten.

Rückgabewert

Das System erzeugt eine CSV-Datei im temporären Verzeichnis des Benutzers im Unterordner acic-exports, wenn es die Funktion aufruft.
Sie erhalten die ID der Ausgabedatei zurück.

Die Einstellungen in der Suche laden

Das System versucht, aus den folgenden Parametern Filter oder Einstellungen zu laden. Ist dies nicht möglich, führt es stattdessen die mitgegebene Suche aus.

Hinweis: Sind weder settingName, settings oder filter angegeben, so muss eine query oder baseQuery zur Verfügung stehen.

settingName

Definiert den Namen der zu ladenden Einstellung (setting) in der Suche.

Geben Sie den internen Namen des Filters mit, der laden soll, etwa für den Filter Alles der Name ac_all.

settings

Setzt eine eigene Liste von Filtern.

Das System lädt im Standard alle zur Verfügung stehenden Filter.

filter

Definiert gewählte Filter-Elemente im Filterbereich.

Beschreibung der Filter siehe agorum.composite.search.filter

filterSelection

Gibt eine Selektion des Filters mit.

Die Selektion schränkt etwa im Filter Alles auf Dokumententypen oder das Änderungsdatum ein.

Suche

query

Gibt eine normale Solr-Suche mit.

Diese Suche erscheint im Suchfeld.

baseQuery

Gibt eine normale Solr-Suche mit.

Diese Suche erscheint nicht im Suchfeld.
Rufen Sie die Bibliothek auf, ist die Suche gleich zu query.

Sortierung

Alle folgenden Parameter sind optional.

sort

Definiert die Sortierung der Suche und somit der Ausgabedatei.

Beispiel

// optional
sort: [{
  property: 'name',
  direction: 'ASC'
}],

sortConfig

Definiert eine bereits existierende Sort-Konfiguration.

Beispiel für Einstellungen in der Suche

let baseFilter = require('/agorum/roi/customers‎/agorum.composite‎/js‎/aguila‎/acic‎/settings‎/base-filter');

// ...
sortConfig: baseFilter.defaultSortConfig(),

sortConfigName

Definiert eine bereits existierenden Sort-Konfiguration anhand des Namens.

Setzen Sie zuvor entweder mit settingName eine Konfiguration in der Suche oder belegen Sie sortConfig, um den Parameter sortConfigName verwenden zu können.

Beispiel

sortConfigName: 'sortconfig_name_asc',

Spalten (header) konfigurieren

Die ausgegebenen Daten orientieren sich über den definierten Header. Um Daten zusammenzustellen, existieren mehrere Wege.

Sie können eine Listenkonfiguration in der Suche wählen. Anhand dieser erstellt das System den Header.

listConfig

Definiert den Namen einer bestehenden Listenkonfiguration im agorum core explorer.

Beispiel

istConfig: 'agorum.composite.asa.list.export.Default',

Sie können alternativ einen eigenen Header oder eine metadata collection mitgeben.
Den Header und die metadata collection steuern Sie über den Parameter Output (Ausgabe).
Durch den Handler beforeQuery können Sie den Header im Nachhinein verändern und erweitern.
Der Standardwert lautet agorum.composite.asa.list.export.Default.

Output (Ausgabe)

Die folgenden Einstellungen steuern den Aufbau der Ausgabedatei. Das System fasst diese unter dem Parameter output zusammen.

Alle folgenden Parameter sind optional.

exportFile

Definiert die Ausgabedatei (agorum core-Objekt) oder den Namen der Ausgabedatei.

Das System:

erzeugt keine neue Ausgabedatei, sondern überschreibt die vorhandene, wenn Sie ein agorum core-Objekt angeben
benennt die Datei standardmäßig wie den Namen von settings oder, falls dieser nicht vorhanden ist, benennt sie nach dem aktuellen Datum im Format dd-MM-yyyy HH-mm
legt die erzeugte Ausgabedatei in den tmp-Ordner des Benutzers unter home:tmp/acic-exports

header

Definiert einen Header.

Geben Sie header als String getrennt mit delimitier oder als Array (mit name + displayName) ohne delimitier an.
Das System verwendet die Angabe listConfig, wenn Sie keinen Header angeben.
Ist listConfig ebenfalls nicht belegt, verwendet das System die listConfig agorum.composite.asa.list.export.Default.

resolveHeader

Definiert, ob das System den Header auflöst.

Lädt das System eine Liste im agorum core explorer, so übernimmt es den dort definierten displayName.
Geben Sie eigene Header an, versucht das System, diese anhand der Metadaten-Definition oder den handler aufzulösen.
Sie können den Header durch den handler selbstständig setzen.

rowHandler

siehe Handler

afterQueryHandler

siehe Handler

encoding

Definiert die Zeichenkodierung der Datei (Standard: UTF-8).

delimitier

Definiert die Trennzeichen für die CSV-Datei (Standard: ;).

exportMax

Grenzt die erhaltenen Einträge auf eine bestimmte Anzahl ein.

Verwenden Sie diesen Parameter zu Testzwecken, um etwa 1000 Objekte schnell einzufügen und eine Übersicht zu erhalten, ob die Handler funktionieren und die Daten vollständig aufbereitet sind.

uuid

Wert	Beschreibung
true	Fügt die UUID automatisch dem Header hinzu.
false (Standard)	Fügt die UUID NICHT automatisch dem Header hinzu.

metadataCollection

Definiert eine metadata collection, die zur Generierung des Headers und der zu verwendenden Daten dient.

Parameter in der MetaDB als systemweite Standards einstellen

Die folgenden Parameter finden Sie in der Administration > MetaDB unter:

MAIN_MODULE_MANAGEMENT/customers/agorum.composite.acic/export

Parameter	Beschreibung
encoding	ISO-8859-15 (oder UTF-8, oder andere encodings)
delimitier	; (oder , oder jedes beliebige andere Zeichen)
exportMax	1000 (oder jede beliebige andere Zahl)

Beispiel 1 mit einfachen Header-Angaben

output: {
  exportFile: 'logfile_name.csv',
  header: 'name;createdate;customHeader', 
  resolveHeader: true,
  rowHandler: '/agorum/roi/customers/test/js/row-handler',
  afterQueryHandler: '/agorum/roi/customers/test/js/after-query',
  beforeQueryHandler: '/agorum/roi/customers/test/js/before-query', 
  encoding: 'UTF-8',
  delimitier: ';',
  uuid: true,
  exportMax: 500 // max items, to export
}

Beispiel 2 mit detaillierteren Header-Angaben

output: {
  exportFile: 'logfile_name.csv',
  header: [
    {
      name: 'name',
      displayName: 'Name'
    },
    {
      name: 'createdate',
      displayName: 'Erstelldatum'
    },
    {
      name: 'customHeader',
      displayName: 'Eigener Header'
    }
  ],
  resolveHeader: true,
  rowHandler: '/agorum/roi/customers/test/js/row',
  afterQueryHandler: '/agorum/roi/customers/test/js/after-query',
  beforeQueryHandler: '/agorum/roi/customers/test/js/before-query',
  encoding: 'UTF-8',
  delimitier: ';',
  exportMax: 500 // max items, to export
}

Beispiel 3 mit der Angabe einer metadata collection

output: {
  resolveHeader: true,
  metadataCollection: 'agorum_demo_test_collection',
  encoding: 'UTF-8',
  delimitier: ';',
  exportMax: 500 // max items, to export
}

Handler

Über den Parameter Handler geben Sie Skripte mit, um sich in den Export einzuhängen und ihn zur Laufzeit zu manipulieren.

rowHandler

Das System ruft diesen Parameter für jedes Element aus dem Suchergebnis auf.
Das System übergibt alle gesammelten Informationen über das Objekt, mindestens jedoch die UUID + den Namen des Objekts.
Rückgabe muss der Datensatz sein. Wird stattdessen kein Wert oder null übergeben, so wird die Zeile zwar geschrieben, aber ohne Daten.
Informationen, die in einer Row vorhanden sind, aber nicht als Header definiert sind, werden nicht in der CSV-Datei ausgegeben. Bereiten Sie diese daher im Handler beforeQuery vor oder geben Sie diese von Anfang an als Header mit.
Die Namen der Struktur müssen exakt den Namen des Headers entsprechen (nicht der Übersetzung, also dem displayName).

Beispiel

Das folgende Beispiel holt das Objekt anhand der UUID und setzt die zwei neuen Spalten newCol und identifier.

Hinweis: Übergeben Sie neue Spalten, müssen diese im Header vorkommen, da sie sonst nicht im Export erscheinen.

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

function rowHandler(row) {
  // console.log('rowHandler', row);
  
  let object = objects.tryFind(row.uuid);
  if (object) {
    let md = metadata().load(object, 'identifier').data();

    row.newCol = 'created by handler: ' + row.name;
    row.identifier = md.identifier;
  }
  return row;
}

module.exports = {
  rowHandler: rowHandler
};

beforeQuery

Dieser Handler erhält folgende Parameter in data mit und kann diese verändern:

header
export file
query
baseQuery

Wie im rowHandler können die Informationen komplett verändert oder gelöscht werden, indem null zurückgegeben wird. Dann greift bei header und exportFile das Standardverhalten.

Beispiel

Das folgende Beispiel ergänzt den Header um die zwei Felder newCol und indentifier mit einem optionalen Anzeigenamen:

function beforeQuery(data) {
  let header = data.header;

  header.push({
    name: 'area',
    displayName: 'Area'
  });

  header.push({
    name: 'identifier',
    displayName: 'Identifier'
  });

  return data;
}

module.exports = {
  beforeQuery: beforeQuery
};

afterQuery

Das System ruft nach dem kompletten Auswerten und Zusammenbauen der Query den Handler afterQuery auf.
Der Handler erhält im Parameter data die fertige Query übergeben und kann diese manipulieren.
Es muss data mit der neuen Query zurückgegeben werden.

Beispiel

function afterQuery(data) {
  // console.log('data', data.query);

  // modify the query
  data.query += ' name:ac*';
 
  return data;
}

module.exports = {
  afterQuery: afterQuery
};

Verpflichtende Parameter

Kombinieren Sie verschiedene Einstellungen, können einige Parameter verpflichtend werden. Fehlen diese, so meldet die Bibliothek einen Fehler.

Sie müssen eines der nachfolgenden Felder zwingend mitgeben: settingName, settings, filter, query, baseQuery
Das System ignoriert settingName, wenn Sie den Parameter filter.
Das Verwenden einer Filterkonfiguration und eines angegebenen Filters ist widersprüchlich.

Weitere Beispiele

Beispiel mit allen Parametern

searchUtils.exportSearch({
  settingName: 'ac_all',
  // settings: ['xxx'], // fill with correct settings
  // filter: ['xxx'], // filter with correct settings
  // filterSelection: ['xxx'], // fill with correct filterSelection
  query: 'AB*',
  // baseQuery: 'nameextension:pdf',
  /**
  sort: [{ // optional
    property: 'name',
    direction: 'ASC'
  }],
  /**/
  /**/
  sortConfig: baseFilter.defaultSortConfig(),
  sortConfigName: 'sortconfig_name_asc',
  /**/

  listConfig: 'ExportStandard',
  output: {
    exportFile: 'logfile_name.csv',
    header: 'name;createdate;customHeader', // optional csv header, if not defined, use from listConfig, or none
    resolveHeader: true,
    // rowHandler: '/agorum/roi/customers/test/js/row',   
    // afterQueryHandler: '/agorum/roi/customers/test/js/after-query',   
    // beforeQueryHandler: '/agorum/roi/customers/test/js/before-query', 
    encoding: 'UTF-8',
    delimitier: ';', // renamed from seperator
    exportMax: 500 // max items, to export
  }
});

Beispiel zur Verwendung einer Konfiguration in der Suche

searchUtils.exportSearch({
  settingName: 'ac_all',
  query: 'test',
  sortConfigName: 'sortconfig_name_asc',
  output: {
    exportFile: 'logfile_name.csv',
    // resolve names, if defined in metadata.yml
    resolveHeader: true,
    
    // optional js handler
    // rowHandler: '/agorum/roi/customers/test/js/row',   
    // afterQueryHandler: '/agorum/roi/customers/test/js/after-query',   
    // beforeQueryHandler: '/agorum/roi/customers/test/js/before-query', 
    
    encoding: 'UTF-8',
    delimitier: ';',
    exportMax: 100 // max items, to export
  }
});

Beispiel mit diversen Attributen und Metadaten

searchUtils.exportSearch({
  query: 'inpath:9999 allfields:ag_packagename',
  sort: [{ 
    property: 'name',
    direction: 'ASC'
  }],
  
  output: {
    resolveHeader: true,
    header: [
      {
        name: 'name',
        displayName: 'Name'
      },
      {
        name: 'id'
      },
      
      // direktes Metadaten Attribut
      {
        name: '~~area[0]',
        displayName: 'Area'
      },
      
      // metadatum
      {
        name: 'ag_packageName'
      }   
    ]
  }
});

Beispiel eines Exports in eigenes Datei-Objekt

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

// Datei suchen, ob bereits vorhanden
let file = objects.tryFind('/agorum/roi/Files/Demo/test-export-file.csv');
if (!file) {
  // Datei ist noch nicht vorhanden, anlegen
  file = objects.create('file', {
    name: 'test-export-file.csv',
    target: objects.find('/agorum/roi/Files/Demo')
  });
}

searchUtils.exportSearch({
  query: 'inpath:9999 allfields:ag_packagename',
  sort: [{ 
    property: 'name',
    direction: 'ASC'
  }],
  
  output: {
    exportFile: file,
    resolveHeader: true,
    header: [
      {
        name: 'name',
        displayName: 'Name'
      },
      {
        name: 'id'
      },
      
      // direktes Metadaten Attribut
      {
        name: '~~area[0]',
        displayName: 'Area'
      },
      
      // metadatum
      {
        name: 'ag_packageName'
      }   
    ]
  }
});