Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core Module und Plugins > agorum core client areas

agorum core client areas Tools-Bibliothek

Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des Plugins agorum core client areas. Aktualisieren Sie das hier beschriebene Plugin, um die Dokumentation verwenden zu können.

Das Plugin agorum core client areas wird mit einer Bibliothek ausgeliefert, die für die Verwaltung von Mandanten verwendet wird. Diese Bibliothek bietet Funktionen zur Erstellung, Aktualisierung und Verwaltung von Mandanten und deren Benutzern.

Verwendung

Sie können mit agorum core client areas Mandanten in agorum core einrichten und dasselbe agorum core-System für Zugriffe von unterschiedlichen Einrichtungen oder Abteilungen benutzen. Die Benutzer und Daten der Mandanten werden dabei vollständig getrennt verwaltet. Mit der Tools-Bibliothek können Sie die Mandantenadministration automatisieren.

Binden Sie dazu die Bibliothek stets am Anfang eines Skripts ein:

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

Funktionen

Allgemeine Parameter

Für die meisten Funktionen sind zwei Parameter erforderlich:

Parameter	Beschreibung	Pflicht	Standard
identifier	Definiert eine Kennung für den Mandantenbereich. Standardmäßig wird client-areas verwendet. Sie dürfen folgende Zeichen nicht verwenden: `<, >, :, ", /, \, \|, ?, *` und Punkt am Ende.	ja	client-areas
number	Definiert die eindeutige Nummer des Mandanten. Sie dürfen folgende Zeichen nicht verwenden: `<, >, :, ", /, \, \|, ?, *` und Punkt am Ende. Der Wert muss zwischen 1 und 8 Zeichen liegen.	ja	-

createArea

Die Funktion createArea erstellt einen neuen Mandanten.

Syntax

clientTools.createArea({
  identifier: 'client-areas',
  number: '123456',
  name: 'client name',
});

Parameter

Zusätzlich zu den allgemeinen Parametern können Sie folgende Parameter angeben:

Parameter	Beschreibung	Pflicht	Standard
name	Der Name des Mandanten.	nein	-
users	Eine Liste von Benutzerobjekten, die erstellt oder aktualisiert werden sollen.	nein	-
addresses	Eine Liste von Adressobjekten, die erstellt oder aktualisiert werden sollen.	nein	-
settings	Ein Objekt mit zusätzlichen Einstellungen.	nein	-

Beispiel für das Anlegen eines neuen Mandanten mit Adressinformation und Benutzer


let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

clientTools.createArea({
  identifier: 'client-areas',
  number: '99',
  name: 'test client',
  users: [
    {
      name: 'Max Mustermann',
      password: 'agorum',
      givenName: 'Max',
      familyName: 'Mustermann',
      emailaddress: 'max.mustermann@example.com',
      language: 'de',
    },
  ],
  addresses: [
    {
      address_type: 'invoice',
      company_name: 'agorum Software GmbH',
      street: 'Vogelsangstr.',
      house_number: '22',
      zip: '73760',
      city: 'Ostfildern',
      country: 'de',
      email: 'rechnung@agorum.com',
      contact: 'Herr Ansprechpartner',
    },
  ],
});

Beispiel für das Anlegen eines neuen Mandanten mit Adressinformation, Benutzer und zusätzlichen Einstellungen

Wenn Sie zusätzliche Einstellungen oder Benutzerfunktionen verwenden (siehe Mandantenverwaltung anpassen), können Sie die entsprechenden Informationen mit einem Aufruf nach folgendem Muster mitgeben:


let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

clientTools.createArea({
  identifier: 'client-areas',
  number: '98',
  name: 'test client',
  users: [
    {
      name: 'Marion Musterfrau',
      password: 'agorum',
      givenName: 'Marion',
      familyName: 'Musterfrau',
      emailaddress: 'marion.musterfrau@example.com',
      language: 'de',
      features: ['feature1'],
    },
  ],
  settings: {
    'agorum.client.areas.sampleClientSettings': {
      sample_setting_1: 'Value 1',
      sample_setting_2: 2,
    },
  },
  addresses: [
    {
      address_type: 'invoice',
      company_name: 'agorum Software GmbH',
      street: 'Vogelsangstr.',
      house_number: '22',
      zip: '73760',
      city: 'Ostfildern',
      country: 'de',
      email: 'rechnung@agorum.com',
      contact: 'Herr Ansprechpartner',
      settings: {
        'agorum.client.areas.sampleAddressSettings': {
          sample_setting_1: 'Value 1',
          sample_setting_2: 2,
        },
      },
    },
  ],
});

Rückgabewert

Wenn die angegebenen Daten nicht richtig sind, enthält die Rückgabe eine Fehlermeldung mit weiteren Informationen. Beispiel:

Error: User "Max Mustermann" already exists, please use another user name

modifyArea

Die Funktion modifyArea aktualisiert einen bestehenden Mandanten.

Der Aufruf entspricht ansonsten dem Aufruf von createArea.

deleteArea

Die Funktion deleteArea löscht einen Mandanten komplett, synchron mit allen Benutzern, Daten und Berechtigungen. Die Funktion ist erst beendet, wenn der Löschvorgang komplett abgeschlossen ist.

Achtung: Die Daten sind danach komplett gelöscht und können nicht wiederhergestellt werden.

Parameter

Siehe die allgemeinen Parameter.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

clientTools.deleteArea({
  identifier: 'client-areas',
  number: '98',
});

deleteAreaTask

Die Funktion deleteAreaTask löscht einen Mandanten im Hintergrund, komplett, mit allen Benutzern, Daten und Berechtigungen. Die Funktion setzt das Löschen auch fort, wenn das System neu gestartet wird.

Achtung: Die Daten sind danach komplett gelöscht und können nicht wiederhergestellt werden.

Parameter

Siehe die allgemeinen Parameter.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

clientTools.deleteAreaTask({
  identifier: 'client-areas',
  number: '98',
});

listAreas

Die Funktion listAreas fragt eine Liste aller vorhandenen Mandanten ab.

Parameter

Sie müssen für diese Funktion keine Parameter angeben.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

let clientList = clientTools.listAreas();

clientList;

Rückgabewert

Sie erhalten als Rückgabe ein Array mit Angaben zu den Mandaten nach folgendem Muster:

[ 
 {
  "identifier" : "client-areas",
  "number" : "99",
  "name" : "test client"
 } 
]

areaInfo

Die Funktion areaInfo fragt Informationen zu einem über die Mandantennummer angegebenen Mandanten ab.

Parameter

Siehe die allgemeinen Parameter.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

let info = clientTools.areaInfo({
  identifier: 'client-areas',
  number: '99',
});

info;

Rückgabewert

Sie erhalten ein Objekt mit Mandanteninformationen nach folgendem Muster zurück.

{
  "identifier" : "client-areas",
  "number" : "99",
  "settings" : {
    "agorum.client.areas.sampleClientSettings" : {
      "sample_setting_1" : "Value 1",
      "sample_setting_2" : 2
    }
  },
  "addresses" : [ {
    "zip" : "73760",
    "country" : "de",
    "settings" : { },
    "address_type" : "invoice",
    "city" : "Ostfildern",
    "street" : "Vogelsangstr.",
    "company_name" : "agorum Software GmbH",
    "contact" : "Herr Ansprechpartner",
    "house_number" : "22",
    "email" : "rechnung@agorum.com"
  } ],
  "name" : "test client"
}

createUser

Die Funktion createUser erstellt einen Benutzer für einen Mandanten.

Parameter

Zusätzlich zu den allgemeinen Parametern können Sie folgende Parameter angeben:

Parameter	Beschreibung	Pflicht	Standard
name	Definiert den eindeutigen Anmeldenamen des Benutzers.	Ja	-
password	Definiert das Passwort des Benutzers.	Ja	-
givenName	Vorname des Benutzers, mit dem der Benutzer in agorum core angezeigt wird.	Ja	-
familyName	Nachname des Benutzers, mit dem der Benutzer in agorum core angezeigt wird.	Ja	-
emailaddress	Definiert die E-Mail-Adresse des Benutzers.	Ja	-
language	Definiert die initiale Sprachauswahl für den Benutzer.	nein	de (Systemstandard)
readOnlyMode	Boolescher Wert, der angibt, ob der Benutzer nur Lesezugriff hat.	nein	false
features	Möglichkeit zum Aktivieren optionaler Funktionen, siehe Zusätzliche Benutzerfunktionen aktivierbar machen.	nein	-

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

clientTools.createUser({
  identifier: 'client-areas',
  number: '99',
  name: 'user',
  password: 'agorum',
  givenName: 'User',
  familyName: 'FamilyName',
  emailaddress: 'user.FamilyName@agorum.com',
  language: 'de',
  readOnlyMode: 'false',
  features: ['feature1', 'feature2'],
});

Rückgabewert

Wenn die angegebenen Daten nicht richtig sind, enthält die Rückgabe eine Fehlermeldung mit weiteren Informationen. Beispiel:

Error: User "Max Mustermann" already exists, please use another user name

modifyUser

Die Funktion modifyUser ändert die Daten eines vorhandenen Mandantenbenutzers.

Parameter

Siehe createUser-Parameter.

Wird features komplett weggelassen, werden diese beim Benutzer nicht verändert.
Wird password komplett weggelassen, wird das Passwort nicht verändert.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

clientTools.modifyUser('user.1', {
  identifier: 'client-areas',
  number: '123456',
  name: 'user.2',
  password: 'agorum',
  givenName: 'User',
  familyName: 'Two',
  emailaddress: 'user.2@agorum.com',
  language: 'de',
});

Rückgabewert

Wenn die angegebenen Daten nicht richtig sind, enthält die Rückgabe eine Fehlermeldung mit weiteren Informationen. Beispiel:

Error: User not found: user.1

lockUser

Die Funktion lockUser sperrt einen vorhandenen Mandantenbenutzer.

Parameter

Zusätzlich zum Benutzernamen siehe die allgemeinen Parameter.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

clientTools.lockUser('user.2', {
  identifier: 'client-areas',
  number: '123456',
});

Rückgabewert

Wenn die angegebenen Daten nicht richtig sind, enthält die Rückgabe eine Fehlermeldung mit weiteren Informationen. Beispiel:

Error: User "user.1" not found.

unlockUser

Parameter

Zusätzlich zum Benutzernamen siehe die allgemeinen Parameter.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

clientTools.unlockUser('user.2', {
  identifier: 'client-areas',
  number: '123456',
});

Rückgabewert

Wenn die angegebenen Daten nicht richtig sind, enthält die Rückgabe eine Fehlermeldung mit weiteren Informationen. Beispiel:

Error: User "user.1" not found.

listUsers

Die Funktion listUsers fragt eine Liste aller Benutzer eines Mandanten ab.

Parameter

Siehe die allgemeinen Parameter.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

let users = clientTools.listUsers({
  identifier: 'client-areas',
  number: '123456',
});

users;

Rückgabewert

Die Funktion liefert ein Array von Benutzernamen zurück. Beispiel:

[ "user.2" ]

userInfo

Die Funktion userInfo liest die Detailinformationen eines Benutzers und gibt diese zurück.

Parameter

Sie benötigen nur den Benutzernamen.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

let userInfo = clientTools.userInfo('user.2');

userInfo;

Rückgabewert

Sie erhalten als Rückgabe ein Objekt mit den Benutzerinformationen. Beispiel:

{
  "features" : [ "feature1", "feature2" ],
  "clientIdentifier" : "client-areas",
  "givenName" : "User",
  "familyName" : "Two",
  "name" : "user.2",
  "emailaddress" : "user.2@agorum.com",
  "language" : "de",
  "clientNumber" : "123456",
  "locked" : false,
  "readOnlyMode" : false
}

availableFeatures

Die Funktion availableFeatures fragt eine Liste aller konfigurierten Benutzerfunktionen ab, siehe Zusätzliche Benutzerfunktionen aktivierbar machen.

Parameter

Sie benötigen keine Parameter.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

let features = clientTools.availableFeatures();

features;

Rückgabewert

Die Funktion liefert ein Array von Benutzerfunktionen zurück. Beispiel:

[ {
  "displayName" : "Client Administrator",
  "name" : "agorum.client.areas.admin",
  "description" : "This feature allows the user to manage users within their client."
}, {
  "displayName" : "Weitere Einstellungen",
  "name" : "agorum.client.areas.clientExtraSettings",
  "description" : "Zugriff auf Weitere Einstellungen zulassen."
} ]

saveSettings

Die Funktion saveSettings speichert zusätzliche Mandanteneinstellungen, vorausgesetzt Sie verwenden Zusatzeinstellungen.

Parameter

Siehe die allgemeinen Parameter. Die zusätzlichen Mandanteneinstellungen sind abhängig von Ihrer Konfiguration, siehe Mandanteneinstellungen.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

clientTools.saveSettings(
  // definition of the client
  {
    identifier: 'client-areas',
    number: '123456',
  },

  // name of the settings to save, as defined in handler
  'agorum.client.areas.sampleClientSettings',

  // the values that should be saved
  {
    sample_setting_1: 'Value 1',
    sample_setting_2: 2,
  }
);

loadSettings

Die Funktion loadSettings fragt die zusätzlichen Mandanteneinstellungen ab, vorausgesetzt Sie verwenden Zusatzeinstellungen.

Parameter

Siehe die allgemeinen Parameter. Der Name der Zusatzeinstellungen ist abhängig von Ihrer Konfiguration, siehe Mandanteneinstellungen.

Beispiel

let clientTools = require('/agorum/roi/customers/agorum.client.areas/js/lib/tools');

let settings = clientTools.loadSettings(
  // definition of the client
  {
    identifier: 'client-areas',
    number: '123456',
  },

  // name of the settings to load, as defined in handler
  'agorum.client.areas.sampleClientSettings'
);

settings;

Rückgabewert

Die Funktion liefert eine Liste der Benutzerfunktionen zurück. Beispiel:

{
  "sample_setting_1" : "Value 1",
  "sample_setting_2" : 2
}