JavaScript-Bibliothek adapter-objects

Diese JavaScript-Bibliothek bietet Funktionen, um einen E-Mail-Adapter zu verwalten.

Ein E-Mail-Adapter holt in bestimmten Intervallen automatisch E-Mails aus einem beliebigen E-Mail-Postfach oder durch manuellen Abruf per IMAP ab und archiviert diese E-Mails in agorum core (siehe agorum core mailadapter administrieren).

Voraussetzungen

Um einen E-Mail-Adapter über diese JavaScript-Bibliothek anzulegen, müssen Sie diese Voraussetzungen erfüllen:

Das Modul Mail adapter muss aktiviert sein.
Sie besitzen ausreichende JavaScript-Kenntnisse.
Sie verstehen die verschiedenen Bibliotheken von agorum core.

Verwendung

Diese Bibliothek binden Sie stets am Anfang eines Skripts ein:

let value = require('adapter/objects');

Sie können der Bibliothek auch einen SessionController übergeben, dessen Berechtigungen Sie für Objektzugriffe verwenden möchten.

let value = require('adapter/objects')(sc);

Funktionen

create

Legt einen E-Mail-Adapter an.

Syntax

let value = adapterobjects.create('objectType', data);

Parameter

Parameter	Beschreibung	Pflicht	Standard-Wert	Weitere Informationen
objectType	Definiert, dass das System einen E-Mail-Adapter erstellt. Möglicher Wert mailadapter	Ja	–	Beispiele
data	Enthält die restlichen Parameter des Aufrufs wie nachfolgend beschrieben.	Ja	–	Beispiele

Parameter für die Daten des E-Mail-Adapters

Parameter	Beschreibung	Pflicht	Standard-Wert	Weitere Informationen
name	Benennt den E-Mail-Adapter.	Ja	–	Anwendung/Beispiel
type	Definiert den Server-Typ. Unterstützter Server-Typ ist IMAP.	Ja	–	Anwendung/Beispiel
description	Definiert die Beschreibung des E-Mail-Adapters.	Nein	–	Anwendung/Beispiel
path	Definiert den Pfad des E-Mail-Adapters (als String).	Nein	Ordnerobjekt mit dem Pfad /agorum/roi/Files	Anwendung/Beispiel
target	Definiert den Zielordner, in den das System den E-Mail-Adapter ablegt.	Nein	–	Anwendung/Beispiel
userName	Definiert den Benutzernamen (die E-Mail-Adresse).	Nein	–	Anwendung/Beispiel
password	Definiert ein Passwort für die adaptierte Mailbox.	Nein	–	Anwendung/Beispiel
host	Definiert einen Host für den E-Mail-Adapter.	Nein	–	Anwendung/Beispiel
mailboxPath	Definiert den Pfad zu den E-Mails, die das System abholt.	Nein	–	Anwendung/Beispiel
isSSL	Definiert, ob das Zielsystem SSL-Verschlüsselung unterstützt.	Nein	true	Anwendung/Beispiel
keep	Definiert, ob das System die Daten in der Mailbox nach Abholung löscht.	Nein	true	Anwendung/Beispiel
updateInterval	Definiert, in welchem Intervall der Adapter die Mailbox abruft.	Nein	–	Anwendung/Beispiel
updateStartTimeX	Definiert, wann der Adapter täglich (in x) die Synchronisierung beginnt.	Nein	0	Anwendung/Beispiel
filter	Schränkt die abzuholenden E-Mails mithilfe von Regulären Ausdrücken ein.	Nein	–	Anwendung/Beispiel

name – Anwendung/Beispiel

name: 'Mailadapter 1',

type – Anwendung/Beispiel

type: 'imap',

description – Anwendung/Beispiel

description: 'Mailbox 1',

path – Anwendung/Beispiel

Sie können auch Ordner angeben, die das System neu erzeugt.

Bei keiner Angabe setzt das System den Namen des E-Mail-Adapters als Ordnernamen und legt den E-Mail-Adapter unter dem Standardpfad in Dateien ab.
Das System interpretiert den Pfad als absoluten Pfad, wenn das erste Zeichen / ist, ansonsten relativ unterhalb des als target angegebenen Ordners.

Standardpfad

/agorum/roi/Files/

In folgendem Beispiel ist der Ordner Demo bereits vorhanden. Das System legt den Ordner E-Mail-Adapter an:

path: '/agorum/roi/Files/Demo/E-Mail-Adapter',

target – Anwendung/Beispiel

Das System sucht gezielt den angegebenen Ordner. Sie müssen am Anfang ein Objekt definieren und in dieses Objekt die objects-Bibliothek laden:

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

Sie können den Parameter path auch mit dem Parameter target kombinieren. In diesem Fall geben Sie bei target den Pfad an und bei path nur die Ordner, die Sie neu hinzufügen möchten.

Hinweis: Wenn Sie target und path kombinieren, dürfen Sie bei path kein / voranstellen. Durch / wird target ignoriert und nur path betrachtet, was zu einer Fehlermeldung führen würde.

Das folgende Beispiel zeigt eine Kombination aus path und target:

target: objects.find('/agorum/roi/Files/Demo'),            
path: 'E-Mail-Adapter für Rechnungen/Adapter 1',

userName – Anwendung/Beispiel

userName: 'demo@agorum.com',

passwort – Anwendung/Beispiel

password: 'agorum',

host – Anwendung/Beispiel

host: 'imap.web.de',

mailboxPath – Anwendung/Beispiel

Bei keiner Angabe archiviert das System alle E-Mails aus der Mailbox.

Die Bezeichnungen für die Ordner können unterschiedlich sein.
Verwenden Sie die Ordnernamen aus Ihrem System.

mailboxPath: '/', // archiviert alle E-Mails aus der Mailbox

mailboxPath: 'INBOX', // archiviert nur die E-Mails aus dem Ordner INBOX

iSSL – Anwendung/Beispiel

isSSL: true, // das Zielsystem  unterstützt SSL-Verschlüsselung 

isSSL: false, // das Zielsystem unterstützt KEINE SSL-Verschlüsselung

keep – Anwendung/Beispiel

keep: true, // löscht die Daten aus der Mailbox nach Abholung

keep: false, // belässt die Daten in der Mailbox nach Abholung

updateInterval – Anwendung/Beispiel

updateInterval: 0,

updateStartTimeX – Anwendung/Beispiel

updateStartTimeHour: 0,
updateStartTimeMinute: 0,

filter – Anwendung/Beispiel

Das System holt nur die gefilterten Daten bei einer Ausführung des E-Mail-Adapters ab. Weitere Informationen zu den Filtern (Regular Expressions) finden Sie unter Regular Expressions.

filter: [
              {
                attribute: 'FROM',
                value: '.*Absender.*'
              },
              {
                attribute: 'SUBJECT',
                value: '.*Betreff.*'
              },
              {
                attribute: 'TO',
                value: '.*Empfänger.*'
              },
              {
                attribute: 'CC',
                value: '.*cc.*'
              },
              {
                attribute: 'BCC',
                value: '.*bcc.*'
              },
              {
                attribute: 'TEXT',
                value: '.*bodytext.*'
              },
              {
                attribute: 'ATTACHMENT',
                value: '.*Attachment.name.*'
              }
            ]

Beispiele

Diese Beispiele zeigen die Anwendung der Funktion.

Beispiel 1: Maximale Anzahl an Parametern

Dieses Skript wendet alle vorhandenen Parameter an.

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

let data = {
            name: 'Beispiel-E-Mail-Adapter', 
            description: 'Hier zeigen wir Ihnen ein Beispiel für einen E-Mail-Adapter.',
            target: objects.find('/agorum/roi/Files/Demo'), 
            path: 'E-Mail-Adapter/E-Mail-Adapter 1', 
            userName: 'demo@agorumcore.com',
            password: 'agorum',
            host: 'imap.meinefirma.de',
            mailboxPath: '/' ,
            type: 'imap',  
            isSSL: true,   
            keep: true,    
            updateInterval: 0,
            updateStartTimeHour: 0, 
            updateStartTimeMinute: 0,
            filter: [
              {
                attribute: 'FROM',
                value: '.*Absender.*'
              },
              {
                attribute: 'SUBJECT',
                value: '.*Betreff.*'
              },
              {
                attribute: 'TO',
                value: '.*Empfänger.*'
              },
              {
                attribute: 'CC',
                value: '.*cc.*'
              },
              {
                attribute: 'BCC',
                value: '.*bcc.*'
              },
              {
                attribute: 'TEXT',
                value: '.*bodytext.*'
              },
              {
                attribute: 'ATTACHMENT',
                value: '.*Attachment.name.*'
              } 
            ]
          
};

adapterobjects.create('mailadapter', data);

Beispiel 2: Minimale Anzahl an Parametern

Dieses Skript wendet die minimale Anzahl an Parametern an. Sie können es etwa zum Anlegen eines Adapters bei einem Projekt verwenden, bei dem der Ursprung der Mailbox noch unbekannt ist.

let adapterobjects = require('adapter/objects');

let dataMinimum = {
  name: 'Adapter für Rechnungs-E-Mails',
  type: 'imap',   
};

adapterobjects.create('mailadapter', dataMinimum);

Nachträgliche Änderungen können Sie entweder direkt im E-Mail-Adapter vornehmen, oder Sie verwenden die Funktion undefined>update.

Rückgabewerte

Sie erhalten das Adapter-Objekt als ID zurück.

Verwendung

Diese Funktion verwenden Sie, wenn Sie einen E-Mail-Adapter per Skript anlegen möchten.

Mit folgendem Aufruf erhalten Sie außerdem einen bereits existierender E-Mail-Adapter zurück:

let mailadapter = adapterobjects.tryCreate('mailadapter', data);

Exceptions

Sie erhalten eine Fehlermeldung, wenn der E-Mail-Adapter bereits existiert.
Sie erhalten eine Fehlermeldung, wenn das angegebene target nicht existiert.

mailFolders

Zeigt die Ordner der Mailbox an, die der E-Mail-Adapter verwendet.

Syntax

let value = adapterobjects.mailFolders('objectType', data);

Parameter

Parameter	Beschreibung	Pflicht	Standard-Wert	Weitere Informationen
objectType	Definiert, dass das System die Ordner eines E-Mail-Adapters anzeigt. Möglicher Wert mailadapter	Ja	–	Beispiel
data	Enthält die restlichen Parameter des Aufrufs wie nachfolgend beschrieben.	Ja	–	Beispiel

Parameter für die Daten des E-Mail-Adapters

Parameter	Beschreibung	Pflicht	Standard-Wert	Weitere Informationen
object	Definiert, welchen E-Mail-Adapter das System abfragen soll.	Ja	–	Anwendung/Beispiel

object – Anwendung/Beispiel

object: objects.find('/agorum/roi/Files/Demo/E-Mail-Adapter/E-Mail-Adapter 1/Beispiel-E-Mail-Adapter')

Beispiel

let adapterobjects = require('adapter/objects');

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

let data = {
   object: objects.find('/agorum/roi/Files/Demo/E-Mail-Adapter/E-Mail-Adapter 1/Beispiel-E-Mail-Adapter')
};

let mailFolders = adapterobjects.mailFolders('mailadapter', data);
mailFolders.join('\n');

Rückgabewerte

Sie erhalten die Ordner des E-Mail-Adapters zurück.

[ 
  Drafts
  INBOX
  INBOX/ABC-In-Box
  InboxFilter
  OUTBOX
  SENTBOX
  Sent Items 
]

Verwendung

Diese Funktion verwenden Sie, wenn Sie die synchronisierten Ordner eines E-Mail-Adapters abrufen möchten.

Exceptions

Zu dieser Funktion existieren keine Exceptions.

sync

Synchronisiert den E-Mail-Adapter.

Syntax

adapterobjects.sync('objectType', data);

Parameter

Parameter	Beschreibung	Pflicht	Standard-Wert	Weitere Informationen
objectType	Definiert, dass das System einen E-Mail-Adapter synchronisiert. Möglicher Wert mailadapter	Ja	–	Beispiele
data	Enthält die restlichen Parameter des Aufrufs wie nachfolgend beschrieben.	–	–	–

Parameter für die Daten des E-Mail-Adapters

Parameter	Beschreibung	Pflicht	Standard-Wert	Weitere Informationen
object	Definiert, welches Objekt das System synchronisiert.	Ja	–	Anwendung/Beispiel
action	Ermöglicht es, eine alternative Art der Synchronisierung zu verwenden.	Ja	–	Anwendung/Beispiel

object – Anwendung/Beispiel

Die Synchronisation findet als Hintergrundprozess statt.
Das System stößt die Synchronisation nur einmal an.

object: adapter,

action – Anwendung/Beispiel

action: 'folder',

Die folgenden Punkte gelten nur für action: folder:

Die Synchronisierung findet nicht als Hintergrundprozess statt, sondern der Funktionsaufruf kehrt erst nach Abschluss zurück.
Während der Synchronisation blockiert das System das Browserfenster, in dem Sie das Skript ausführen.
In diesem Browserfenster können Sie folglich keine Eingaben mehr tätigen, bis das System den übergebenen Ordner komplett synchronisiert hat.

Beispiele

Gesamten E-Mail-Adapter synchronisieren

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

let adapter = objects.find('/agorum/roi/Files/Demo/E-Mail-Adapter/E-Mail-Adapter 1/Beispiel-E-Mail-Adapter');

let data = {
  object:  adapter,  
};

adapterobjects.sync('mailadapter', data);

Einzelnen Ordner des E-Mail-Adapters synchronisieren

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

let folder = objects.find('/agorum/roi/Files/Demo/E-Mail-Adapter/E-Mail-Adapter 1/Beispiel-E-Mail-Adapter/INBOX');

let data = {
  object:  adapter,
  action: 'folder'  //--> KEIN Hintergrundprozess 
};

adapterobjects.sync('mailadapter', data);

Rückgabewerte

Zu dieser Funktion existieren keine Rückgabewerte.

Verwendung

Diese Funktion verwenden Sie, wenn Sie einen E-Mail-Adapter oder einzelne Ordner des E-Mail-Adapters synchronisieren möchten.

Exceptions

Sie erhalten eine Fehlermeldung, wenn der angegebenen E-Mail-Adapter nicht existiert.
Sie erhalten eine Fehlermeldung, wenn die angegebenen Ordner des E-Mail-Adapters nicht existieren.

test

Testet die Erreichbarkeit des angegebenen Postfachs des E-Mail-Adapters.

Syntax

let value = adapterobjects.test('objectType', data);

Parameter

Parameter	Beschreibung	Pflicht	Standard-Wert	Weitere Informationen
objectType	Definiert, dass das System das Postfach eines E-Mail-Adapters testet. Möglicher Wert mailadapter	Ja	–	Beispiel
data	Enthält die restlichen Parameter des Aufrufs wie nachfolgend beschrieben.	Ja	–	Beispiel

Parameter für die Daten des E-Mail-Adapters

Parameter	Beschreibung	Pflicht	Standard-Wert	Weitere Informationen
object	Definiert, welches Objekt das System testet.	Ja	–	Anwendung/Beispiel

object – Anwendung/Beispiel

object: mailadapter,

Beispiel

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

let mailadapter = objects.find('/agorum/roi/Files/Demo/E-Mail-Adapter/E-Mail-Adapter 1/Beispiel-E-Mail-Adapter');

let data = {
  object: mailadapter
};
   
adapterobjects.test('mailadapter', data);

Rückgabewerte

Sie erhalten einen booleschen Wert zurück.

Wert	Beschreibung
true	Der E-Mail-Adapter ist erreichbar.
false	Der E-Mail-Adapter ist nicht erreichbar.

Verwendung

Diese Funktion verwenden Sie, wenn Sie einen E-Mail-Adapter testen möchten.

Exceptions

Zu dieser Funktion existieren keine Exceptions.

update

Ändert einen bereits angelegten E-Mail-Adapter.

Syntax

let value = adapterobjects.update('objectType', data);

Parameter

Parameter	Beschreibung	Pflicht	Standard-Wert	Weitere Informationen
objectType	Definiert, dass das System einen E-Mail-Adapter ändert. Möglicher Wert mailadapter	Ja	–	Beispiel
data	Enthält die restlichen Parameter des Aufrufs wie nachfolgend beschrieben.	Ja	–	Beispiel

Parameter für die Daten des E-Mail-Adapters

Sie können alle in der Funktion create verwendeten Parameter anpassen, außer path und target.

Diese Parameter sind updatefähig:

name
description
userName
password
host
mailboxPath
type
isSSL
keep
updateInterval
updateStartTimeHour
updateStartTimeMinute
filter

Beispiel

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

let obj = objects.find('/agorum/roi/Files/Demo/E-Mail-Adapter/E-Mail-Adapter 1/Beispiel-E-Mail-Adapter');

let dataMinimum = {
  name: 'Rechnungs-Adapter'
};

adapterobjects.update('mailadapter', obj, dataMinimum);

Rückgabewerte

Sie erhalten den geänderten E-Mail-Adapter als ID zurück.

Verwendung

Diese Funktion verwenden Sie, wenn Sie einen bereits angelegten E-Mail-Adapter ändern möchten.

Exceptions

Zu dieser Funktion existieren keine Exceptions.