Skip to main content

Connect Database

Das Add-on Connect Database für KIX Pro ermöglicht die Nutzung von Datenbankverbindungen als Datenquelle zur weiteren Verwendung in KIX. Für den konkreten Einsatz bedarf es einer entsprechenden Konfiguration.

Unterstützt werden die Datenbank- Managementsysteme: PostgreSQL, MariaDB/MySQL oder MS SQL via ODBC.

Voraussetzungen

Die Anbindung einer Datenbank-Datenquelle erfordert den direkten Zugriff auf die relevante Datenbank mittels Authentifizierung via Nutzername und Passwort. Das betreffende DBMS muss dabei via Datenbank- Socket-Verbindung erreichbar sein.

Einrichtung

Die Einrichtung der Datenbankverbindungen und der Datenquellen erfolgt im Explorer des Admin-Moduls unter Connect .

Für die Nutzung einer externen Datenquelle muss beides eingerichtet sein.

ConnectDB_Verbindungen.png

Abb.: Menü zur Einrichtung einer Datenbankverbindung

ConnectDB_Datenquelle.png

Abb.: Menü zur Einrichtung der benötigten Datenbank-Datenquellen

Einrichten von Datenbankverbindungen

Die Einrichtung und Konfiguration von Datenbankverbindungen erfolgt schrittweise im Menü Connect > Verbindungen. Hinterlegen Sie hier die Verbindungsparameter zur Datenbank. Beim Speichern versucht KIX die Datenbankverbindung aufzubauen. Gelingt dies nicht, werden Sie darauf hingewiesen und können die Einstellungen korrigieren.

Eine Datenbankverbindung benötigt für den Zugang zur Datenbank die Angaben zum Host, den Datenbank- Namen sowie den Nutzernamen und das Passwort, mit dem die Datenbank geschützt sind. Diese Angaben müssen bereitgestellt und im DSN-Feld eingetragen werden. Halten Sie diese Informationen bereit.

ConnectDB_Verbindung-einrichten1.png

Abb.: Einrichten einer Datenbankverbindung - Schritt 1

ConnectDB_Verbindung-einrichten2.png

Abb.: Einrichten einer Datenbankverbindung - Schritt 2

Parameter

Beschreibung

Name

Der Name der Datenverbindung

z. B.: SimpleERP (Database)

Typ

Typ der Datenverbindung

z. B.: DB

Definiert, wie der Zugriff auf die Datenquelle erfolgt.

Die zur Verfügung stehende Auswahl ist abhängig von den installierten Zusatzmodulen.

Kommentar

Optionaler Kommentar

Beispiel

ERP Datenbank; enthält Daten zu: - Kunden und Kontakten - Produktkategorien, Produktverfügbarkeit im Lager - Bestellungen, Artikelbestellungen - Rechnungen

Gültigkeit

de-/aktiviert Datenquelle für weitere Nutzung

Mögliche Parameter: valid | invalid

DB Typ

Datenbanktyp, zu dem verbunden werden soll.

Diese Angabe ist relevant, wenn der Typ nicht aus DSN ersichtlich ist.

z. B.: postgresql | mysql | mssql

DSN

Für den Datenbankzugriff hinterlegen Sie hier:

  • den Host, auf dem die Datenbank liegt

  • den Datenbank-Name

  • die Zugangsdaten zur Datenbank (Nutzer und Passwort)

Beispiel:

DBI:Pg:dbname=erp;host=192.168.130.107;
DBI:Pg:dbname=kix;host=db;
DBI:ODBC:Driver={ODBC Driver 17 for SQL Server};Server=<FQDN/IP>,<Port>;Database=<Database>;UID=<login>;PWD=<password>

Ersetzen Sie im Beispiel die folgenden Parameter durch Ihre Werte:

  • <FQDN/IP>

  • <Port>

  • <login>

  • <password>

Hinweis

Der Zugriff auf einen MS SQL-Server erfolgt mittels ODBC. Achten Sie im DSN auf die Angabe von Nutzername und Passwort.

Beide Angaben werden bei ODBC-Verbindung direkt im DSN definiert. Die Einzelparameter "DB-Nutzer" und "DB-Password" sind dann nicht  relevant.

DB-Nutzer

Nutzername/Login mit dem der Datenbank- Zugriff erfolgt.

Diese Angabe kann bei Zugriff auf einen MS SQL-Server entfallen, da der Nutzername bereits im DSN angegeben wird.

z. B.: erpuser | kix

DB-Passwort

Passwort des Nutzers mit dem der Datenbank-Zugriff erfolgt.

Diese Angabe kann bei Zugriff auf einen MS SQL-Server entfallen, da das Passwort bereits im DSN angegeben wird.

z. B.: SuperSecretPassword | kix

Einrichten von Datenbank-Datenquellen

Eine Datenbank-Datenquelle besteht aus allgemeinen Angaben und zwei parametrisierbaren SELECT- Statements, welche einer Datenbankverbindung zugeordnet sind. Beide Abfragen sind dabei nicht auf eine einzelne Datenbanktabelle/View begrenzt, sondern können alle verfügbaren Datenbanktabellen/Views einbinden. Spezielle Einschränkungen, Bedingungen oder Vereinigungen ("JOIN") können direkt in den Abfragen definiert werden.

Die Einrichtung und Konfiguration von Datenbank-Datenquellen erfolgt im Explorer des Admin-Moduls unter Connect > Datenquellen.

Für die nachfolgende Beschreibung wird angenommen, dass eine einfache Datenbank mit der Tabelle "Servicequotas (DB)" als Datenquelle dient und die Tabelle folgende Struktur aufweist:

erp=> \d servicequotas;
                        View "public.servicequotas"
    Column     |           Type           | Collation | Nullable | Default
---------------+--------------------------+-----------+----------+---------
 id            | integer                  |           |          |
 customer_no   | character varying(32)    |           |          |
 customer_name | character varying(255)   |           |          |
 comments      | character varying(512)   |           |          |
 quota         | integer                  |           |          |
 startdate     | timestamp with time zone |           |          |
 enddate       | timestamp with time zone |           |          |
erp=>

Schritt 1 - Kopfdaten

ConnectDB_Datenquelle-Kopfdaten.png

Abb.: Datenquelle einrichten - Schritt 1

Hinweis

Der apiResourceName wird aus dem vergebenen Namen erstellt. Dieser ist erforderlich für die Ansprache der Datenquelle via der Backend-REST-API von KIX oder für die Einbindung der Datenquelle in Widget- oder Sidebartabellen. Die Bildung des apiResourceName erfolgt durch:

  • Ersetzung der Großbuchstaben durch Kleinbuchstaben

  • Ersetzung der Leerzeichen durch Unterstrich ("_")

  • Entfernung von ungültigen Zeichen wie Ziffern oder Sonderzeichen.

    Unterstrich ("_") wird akzeptiert. 

Die Datenquelle ist in der Rest-API via /datasources/<apiResourceName> erreichbar.

Parameter

Beschreibung

Name

Der Name der Datenquelle.

z. B.: "Servicequotas (DB)"

→ apiResourceName: servicequotas_DB

Typ

Typ der Datenquelle

z. B.: DB

Die Auswahlliste ist abhängig von den installierten Zusatzmodulen.

Verbindung

Name der zu nutzenden Datenquelle (Auswahlliste)

z. B.: "Simple ERP (Database)"

Rollen

Schränkt die Verwendung der Datenquelle auf Basis von KIX-Berechtigungsrollen ein.

Nur Nutzer mit den hier gewählten Rollenzuordnungen können die Daten aus der KIX-Datenquelle einsehen und im Rahmen ihrer Berechtigungen nutzen.

z. B.: Customer Manager, Customer Reader, Ticket Agent, Ticket Reade

Kommentar

Optionaler Kommentar

z. B.: "Diese Datenquelle liefert beliebige Leistungskontingente aus der ERP- Datenquelle."

Gültigkeit

  • gültig: Die Datenquelle einschließlich der darüber bezogenen Daten können in KIX eingesehen und verwendet werden.

  • (temporär) ungültig: Die Datenquelle ist inaktiv.

    Es werden keine in der Datenquelle angegebenen Daten  bezogenen oder im KIX verwendet.

Schritt 2 - Datenbankabfragen

ConnectDB_Datenquelle_DBabfragen.png

Abb.: Beispiel-Einrichtung Datenquelle - Schritt 2

Bei der Einrichtung von Datenbankabfragen/ SELECT-Statements wird zwischen Listenanfrage ("List Select Statement") und Detailanfrage ("Item Select Statement") unterschieden. Für beide werden separate Abfragen eingerichtet.

Das System unterstützt mit Vorgabewerten, die angepasst werden müssen. Für eine Datenbank- Datenquelle sind beide Angaben erforderlich.

Parameter

Beschreibung

Beispiel

List Select Statement

Listenanfragen dienen der Ermittlung einer Reihe von Einträgen, die bspw. in einer Feldeingabe zur Auswahl angeboten werden.

Typischerweise sind diese kurz gehalten, beinhalten kleinere Ergebnismengen (z.B. nur ID, Name, Erklärung) und haben weiter gefasste Bedingungen, die eine Nutzereingabe für Suchbegriffe (sogenannte Suchkriterien) zulassen.

Das Ergebnis einer Listenanfrage wird für die Anzeige von Auswahlwerten in Eingabefeldern oder zur Anzeige eines Einzelwerts genutzt.

Wichtig: Der Alias "ID" muss immer vorhanden sein!

Beispiel

SELECT 
  id as "ID", 
  customer_no AS "cno", 
  customer_name AS "cname", 
  quota 
FROM servicequotas WHERE 
  ${Parameters.Search?1=1}, 
  AND startdate > '${Parameters.StartDate?2020-01-01 00:00:00}';

Die Notation ${Parameters.Search? 1=1} ist der Platzhalter für die anzuwendenden Suchkriterien (z.B. bei Eingabe in einem Autocomplete-Feld). Die Fallback-Bedingung (1=1) stellt syntaktisch korrektes SQL sicher, falls kein Suchkriterium verwendet wird.

Die Bedingung AND startdate > '${Parameters.StartDate?2020-01-01 00:00:00}' ist eine feste Bedingung, die in jeder Abfrage angewandt wird. Wird kein Datum übergeben verwendet die Abfrage automatisch 2020-01-01 00:00:00 als Startdatum.

SELECT

id as "ID", customer_no AS "cno",

customer_name AS "cname", quota

FROM servicequotas WHERE

${Parameters.Search?1=1} AND startdate > '$

{Parameters.StartDate?2020-01-01 00:00:00}';

Item Select Statement

Detailanfragen dienen der Anzeige eines konkreten Eintrags aus der Datenquelle.

Sie sind relevant, wenn alle Angaben eines konkreten Eintrags benötigt werden. Dabei werden i. d. R. mehrere Spalten bezogen und z. B. in einer Sidebar als Tabelleneinträge oder an einem Feldwert als Info-Popup dargestellt.

Beispiel

SELECT 
  id as "ID", 
  customer_no AS "cno", 
  customer_name AS "cname", 
  quota,
  comments,
  startdate, 
  enddate
FROM servicequotas WHERE id = ${Parameters.ID?0};

Im Beispiel umfasst die Detailanfrage zusätzlich den konkreten Wert der Quota und in welchem Zeitbereich sie gilt. Entsprechend werden mehr Spalten in der Abfrage zurück geliefert.

Ein Einzeleintrag wird immer auf Basis der ID-Spalte identifiziert. Entsprechend ist die Bedingung id = ${Parameters.ID?0}; immer anzugeben.

Sollte kein Schlüsselwert zur Abfrage übermittelt werden wird ein Eintrag mit id=0 gesucht. Dieser ist i. d. R. nicht vorhanden ist und liefert daher kein Ergebnis liefert. Damit wird syntaktisch korrektes SQL sichergestellt.

Umbenennung von Datenquellen

Das Umbenennen von Datenquellen ist jederzeit möglich. Alle bestehenden Verwendungen erfordern daraufhin manuelle Anpassungen. Dies betrifft insbesondere die Konfiguration der GUI (SysConfig), Ticketvorlagen und Aktionen. Der alte apiResourceName muss dann durch den neuen apiResourceName ersetzt werden.

Verwendung von Datenquellen (Beispiele)

Verwendung von Datenquellen in Dynamischen Feldern

Connect_Database.png

Abb.: Schema der Verwendung von Datenquellen

Szenario:

An einem Ticket soll erfasst werden, welche Quota gilt. Dazu wird ein dynamisches Feld eingerichtet, welches von Agenten gesetzt und in Detailansichten mit der Darstellung von Einzelangaben zur Quota eingesehen werden soll.

Um dies zu erreichen, ist im KIX folgendes zu konfigurieren:

  1. Einrichtung von Datenbankverbindung und Datenquelle

    Es wird vorausgesetzt, dass eine Datenbankverbindung (bspw. SimpleERP) sowie eine Datenquelle (bspw. Servicequotas (DB) ) bereits eingerichtet wurden.

    (s. auch: Einrichten von Datenbank-Datenquellen und Einrichten von Datenbankverbindungen

  2. Anlegen des Dynamischen Feldes ServiceQuota im Menü System > Dynamische Felder

    Konfigurationsparameter des Dynamischen Feldes:

    • Name: ServiceQuota

    • Label: Service Quota

    • Feldtyp: Data Source

    • Objekttyp: Ticket

    • SSP-Sichtbar: nein

    • Konfiguration:

      • Data Source: Servicequotas (DB)

      • Display Pattern: <quota> (<cname>)

      • Default Display Columns

        • 1: quota / Quota

        • 2: cname/Org.-name

        • 3: comments/Comments

        • 4: startdate/From

        • 5: enddate/Until

      • Cache TTL: 0

      • Count Min: 1

      • Count Max: 1

  3. Einrichten der Ticketaktion (Setze) Service Quota im Menü Ticket > Aktionen

    • Schritt 1 - Aktionsinformationen

      • Referenz Objekt: Ticket

      • Name: ServiceQuota

      • Label: Service Quota

      • Nutzungskontext: Agent

      • Nutzereingabe erforderlich: ja

    • Schritt 2 - Filter

      • Rollen: Ticket Agent

    • Schritt 3 - Pre Actions

      • leer

    • Schritt 4 - Eingabefelder

      • Service Quota - set in mask

        Für Beschränkung der offerierten Auswahlen durch eine Suche nach dem Organisations-Namen werden Erweiterte Optionen definiert:

        1. Ergänzung des Abschnitts LOADINGOPTIONS um Angaben zum filter.

          <SEARCH_VALUE> dient als Platzhalter für das Suchmuster, welches später vom Anwender eingegeben wird.

        2. Ergänzung des Abschnitts LOADINGOPTIONS um Angaben zum query.

          Es werden dadurch nur die Einträge offeriert, deren Startdatum nicht vor dem 23.04.2022 liegt.

          Es können Platzhalter wie <KIX_TICKET_DynamicField_SomeDateTimeField> oder auch <SEARCH_VALUE> verwendet werden.

          Die LOADINGOPTIONS sind nur zur Einschränkung/Aufbereitung der Listenanfragen zu verwenden. Für die Detailanfragen muss die von der Listenanfrage gelieferte ID als eindeutiger Kenner für den abzurufenden Eintrag genügen.

        {
  "option": "LOADINGOPTIONS",
  "value": {
    "expands": [],
    "filter": [
      {
        "filterType": "OR",
        "operator": "LIKE",
        "property": "cname",
        "type": "STRING",
        "value": "<SEARCH_VALUE>"
      }
    ],
    "query": [
      [ "StartDate" , "2022-04-23 00:00:00"]
     ],
     "includes": [],
     "limit": null,
     "sortOrder": null
  }
},

    • Schritt 5 - Post Actions

      • leer

  4. Darstellung des Dynamischen Feldes in den Ticketdetails

    1. Navigieren Sie im Explorer zu System > GUI Konfiguration > Agentenportal.

    2. Suchen und öffnen Sie den Schlüssel ticket-details-info-card (Ticket Details)

    3. Binden Sie im SysConfig-Schlüssel das Dynamische Feld ServiceQuota ein

      (s. auch Werte Dynamischer Felder anzeigen).

      Sie können nachfolgenden Codeblock verwenden:

      {
   "componentId": "dynamic-field-value",
   "componentData": {
        "name": "ServiceQuota"
    },
   "conditions": [
        {
            "property": "DynamicFields.ServiceQuota",
            "operator": "NE",
            "value": null
        }
   ]

    4. Klicken Sie nach dem Speichern Ihrer Änderungen am Konfigurationsschlüssel auf Lade Frontend-Konfigurationen neu.

    Das Dynamische Feld ServiceQuota ist nun in den Ticketdetails enthalten, sodass dessen Wert angezeigt werden kann.

    ConnectDB_DF-in-Ticketdetails.png

    Abb.: Anzeige des Dynamischen Feldes "ServiceQuota" in den Ticketdetails

    Alternativ dazu können Sie das Dynamische Feld auch in andere Ansichten einbinden.

Verwendung von Datenquellen in Sidebar-Tabellen

Connect_DatabaseDashboard.png

Abb.: Schema der Verwendung von Datenquellen in KIX

Szenario:

Zu einer Organisation sollen an jedem Ticket der Organisation alle Bestellungen eingesehen werden können. In KIX sind die Kundennummern bekannt, die auch im ERP für Kundenorganisationen verwendet werden. Um dies zu erreichen, ist im KIX folgendes zu konfigurieren:

  1. Einrichtung der Datenbankverbindung

  2. Einrichtung der Datenquelle (= Datenbank-Tabelle)

  3. Einrichtung Dynamisches Feld OrderListSidebar

  4. Einrichtung des Sidebar-Widgets Order List in den Ticketdetails

Für die nachfolgende Beschreibung wird angenommen, dass eine einfache Datenbank mit den Tabellen "orders" und "customers" als Datenquelle dient. Es wird ferner angenommen, dass die Tabellen folgende Struktur aufweisen:

erp=> \d orders;
                                    Table "public.orders"
    Column    |          Type          | Collation | Nullable |           Default           
--------------+------------------------+-----------+----------+------------------------------
 id           | integer                |           | not null | generated always as identity
 customer_id  | integer                |           |          |
 order_number | character varying(255) |           | not null |
 description  | character varying(512) |           | not null |
 order_date   | date                   |           | not null |
...
 
erp=> \d customers;
                                   Table "public.customers"
    Column     |          Type          | Collation | Nullable |           Default           
---------------+------------------------+-----------+----------+------------------------------
 id            | integer                |           | not null | generated always as identity
 customer_name | character varying(255) |           | not null |
 customer_no   | character varying(32)  |           | not null |
 addr_street   | character varying(255) |           |          |
 addr_city     | character varying(128) |           |          |
 addr_zip      | character varying(16)  |           |          |
 addr_country  | character varying(128) |           |          |
 url           | character varying(255) |           | not null |
 comments      | character varying(512) |           | not null |
...
erp=>

  1. Einrichtung der Datenbankverbindung

    Es wird vorausgesetzt, dass eine Datenbankverbindung (bspw. SimpleERP) bereits eingerichtet wurde.

    (s. auch: Einrichten von Datenbankverbindungen)

  2. Einrichtung der Datenquelle

    Zum Einrichten der Datenquelle navigieren Sie zu Connect > Datenquellen und nehmen Sie folgende Konfiguration zur Einrichtung der Datenquelle vor:

    • Name: OrderList (DB)

    • Typ: DB

    • Verbindung: SimpleERP (DB)

    • Rollen: Customer Manager, Customer Reader, Ticket Agent, Ticket Reader

    • Kommentar: kann entfallen

    • Gültigkeit: gültig

    • List Select Statement:

      SELECT
   o.id as "ID",
   c.customer_no,
   o.order_number AS "OrderNumber",
   o.order_date AS "Date"
FROM
  orders o LEFT JOIN customers c ON (o.customer_id = c.id)
WHERE ${Parameters.Search?1=0};

      Die Fallback-WHERE-Bedingung 1=0 hat zur Folge, dass keine Einträge gelistet werden, wenn keine gültige Suchanfrage übergeben wird.

    • Item Select Statement:

      SELECT
   o.id as "ID",
   c.customer_no,
   o.order_number AS "OrderNumber",
   o.description AS "Description",
   o.order_date AS "Date"
FROM
  orders o LEFT JOIN customers c ON (o.customer_id = c.id)
WHERE o.id = ${Parameters.ID?0};

  3. Einrichtung Dynamisches Feld OrderListSidebar im Menü System > Dynamische Felder

    Das Feld dient lediglich zum Tragen der Konfiguration der Datenquelle und der Vorgabespalten in der Sidebar, sofern diese nicht weitere oder weniger Spalten definiert.

    Das Feld muss nicht eingesetzt werden um einen Wert am Ticket zu hinterlegen.

    • Name: OrderListSidebar

    • Label: Order List Sidebar

    • Feldtyp: Data Source

    • Objekttyp: Ticket

    • SSP-Sichtbar: nein

    • Konfiguration:

      • Data Source: OrderList (DB)

      • Display Pattern: <quota> (<cname>)

      • Default Display Columns

        • 1: OrderNumber/ OrderNumber

        • 2: Date/Date

        • 3: Description/Description

        • 4: c.customer_no/Customer Number

      • Cache TTL: 0

      • Count Min: 1

      • Count Max: 1

  4. Einrichtung Sidebarwidget Order List in den Ticketdetails

    Tipp

    Dieses Beispiel zeigt die Verwendung von festen Parametern zur Einschränkung einer Listenanfrage.

    Als Parameter können auch variable (durch den Nutzer änderbare) Eingabewerte in Dialogen dienen. Damit können abhängige Eingaben über mehrere Felder abgebildet werden, z.B. "Produktlinie → Produkt → Model" oder "Auftrag → Auftragsposition".

    ConnectDB_Sidebar_DataSourceDB.png

    Abb.: Sidebarwidget "Order List" in den Ticketdetails

    1. Navigieren Sie im Explorer zu System > GUI Konfiguration > Agentenportal.

    2. Suchen und öffnen Sie den Schlüssel ticket-details-info-card (Ticket Details)

    3. Ergänzen Sie den nachfolgenden Codeblock im Array sidebars:

      {
  "instanceId": "ticket-details-datasource-orderlist",
  "configuration": {
    "id": "ticket-details-datasource-orderlist",
    "name": "Order List from DataSource",
    "type": "Widget",
    "widgetId": "table-widget",
    "title": "Translatable#Order List",
    "actions": [],
    "subConfigurationDefinition": null,
    "configuration": {
        "id": "ticket-details-datasource-orderlist-widget",
        "name": "orders from data source",
        "type": "TableWidget",
        "objectType": "DataSourceRequestItem",
        "sort": [],
        "subConfigurationDefinition": null,
        "configuration": {
            "id": "ticket-details-datasource-orderlist-table",
            "name": "orders from datasource",
            "type": "Table",
            "objectType": "DataSourceRequestItem",
            "loadingOptions": {
              "filter": [
                {
                  "filterType": "OR",
                  "operator": "LIKE",
                  "property": "c.customer_no",
                  "type": "STRING",
                  "value": "<KIX_ORG_Number>"
                }
              ],
              "sortOrder": null,
              "query": null,
              "limit": 35
            },
            "specificLoadingOptions": {
              "dfName": "OrderListSidebar"
            },
            "displayLimit": 15,
            "tableColumns": [
              {
                "name": null,
                "property": "OrderNumber",
                "showText": true,
                "showIcon": true,
                "showColumnTitle": true,
                "showColumnIcon": false,
                "size": 250,
                "sortable": true,
                "filterable": true,
                "hasListFilter": false,
                "dataType": "STRING",
                "resizable": true,
                "defaultText": "",
                "translatable": true,
                "titleTranslatable": true,
                "useObjectServiceForFilter": false
              },
              {
                "name": null,
                "property": "Date",
                "showText": true,
                "showIcon": true,
                "showColumnTitle": true,
                "showColumnIcon": false,
                "size": 100,
                "sortable": true,
                "filterable": true,
                "hasListFilter": true,
                "dataType": "STRING",
                "resizable": true,
                "defaultText": "",
                "translatable": true,
                "titleTranslatable": true,
                "useObjectServiceForFilter": false
              }
            ],
            "headerHeight": 1.75,
            "rowHeight": 1.75,
            "emptyResultHint": "Translatable#0 orders found.",
            "fixedFirstColumn": false
          },
          "showFilter": false,
          "shortTable": false,
          "predefinedTableFilters": [],
          "cache": false,
          "resetFilterOnReload": true
        },
        "minimized": false,
        "minimizable": true,
        "icon": "fas fa-shopping-cart",
        "contextDependent": false
      },
      "size": "large",
      "permissions": []
    },

    4. Speichern Sie die Änderung.

    5. Klicken Sie im Header der SysConfig auf Lade Frontend-Konfigurationen neu, um die Ansicht im Frontend zu aktualisieren.

    Danach wird das Widget in der rechten Seitenleiste angezeigt.

Verwendung von Datenquellen in Macro Actions

Connect_Database.png

Abb.: Schema der Verwendung von Datenquellen

Szenario: Inventarisierung Asset Management

In der KIX Asset-Datenbank gibt es eine Assetklasse Quota, in deren Einträgen die Anzahl der pro Kunde und Servicevertrag inkludierten Service-Calls beschrieben wird. Die Informationen wie viele Calls zulässig sind, liegen im ERP in einer einfachen Datenbanktabelle mit den Spalten Kundennummer, Kundenname, Calls u. a. vor. Diese Daten sollen aus der ERP-Datenbank in die KIX-Asset-Datenbank importiert und aktuell gehalten werden.

Um dies zu erreichen, ist im KIX folgendes zu konfigurieren:

  1. Erstellung der Assetklasse Quota

  2. Einrichtung der Datenbankverbindung

  3. Einrichtung der Datenquelle (= Datenbank-Tabelle)

  4. Einrichtung des Automatisierungsjobs

Ausschnitt Quelldaten:

kix=# SELECT * FROM servicequotas;
 id | number  |            name          | comments | quota |       startdate        |        enddate        
----+---------+--------------------------+----------+-------+------------------------+------------------------
  1 | MY_ORGA | My Organisation          |          |   100 | 2021-01-01 00:00:00+00 | 2022-01-01 00:00:00+00
  3 | MAMU    | Mustermann GmbH          |          |    60 | 2021-01-01 00:00:00+00 | 2022-01-01 00:00:00+00
  4 | TWD     | Torchwood Ltd.           |          |    39 | 2021-01-01 00:00:00+00 | 2022-01-01 00:00:00+00
  5 | FKLHZ   | Fackelholz AG            |          |    36 | 2021-01-01 00:00:00+00 | 2022-01-01 00:00:00+00
  6 | capeIT  | c.a.p.e. IT GmbH         |          |    71 | 2021-01-01 00:00:00+00 | 2022-01-01 00:00:00+00
  7 | HRMSHL  | Harmony Shoal            |          |    45 | 2021-01-01 00:00:00+00 | 2022-01-01 00:00:00+00
  8 | ITKOM   | IT Kommunikations GmbH   |          |    43 | 2021-01-01 00:00:00+00 | 2022-01-01 00:00:00+00
...

  1. Erstellung der Asset-Klasse Quota

    Als Voraussetzung muss eine Assetklasse Quota eingerichtet sein. Dazu wird die nachfolgende, einfache Assetklassen-Definition angenommen (s. auch: Eine Asset-Klasse anlegen oder bearbeiten):

    [
    {
        Key             => 'OrgNumber',
        Name            => 'Org. Number',
        Searchable      => 1,
        CustomerVisible => 1,
        Input           => {
            Type => 'Text',
        },
    },
    {
        Key             => 'Quota',
        Name            => 'Quota',
        Searchable      => 1,
        CustomerVisible => 1,
        Input           => {
            Type => 'Text',
        },
    }
];

  2. Einrichtung von Datenbankverbindung und Datenquelle

    Es wird vorausgesetzt, dass eine Datenbankverbindung (SimpleERP) sowie eine Datenquelle (Servicequotas (DB) ) bereits eingerichtet wurden.

    (s. auch: Einrichten von Datenbank-Datenquellen und Einrichten von Datenbankverbindungen

  3. Einrichtung Automatisierungs-Job

    1. Navigieren Sie im Explorer zu Automatisierung > Jobs. 

    2. Konfigurieren Sie den Job wie folgt:

      • Schritt 1 - Job Informationen

        • Job Typ: Synchronisation

        • Name: Synchronize Service Quotas from ERP

        • Optionaler Kommentar:

          Holt alle Servicekontingente der Kundenorganisationen aus der ERP-Datenbank und erstellt/aktualisiert für jedes ein Asset der Klasse "Quota".

        • Gültigkeit: gültig

      • Ausführungsplan

        • Wochentag(e): Montag, Dienstag, Mittwoch, Donnerstag, Freitag, Samstag, Sonntag

        • Zeit: 4:00

      • Aktionen

        Die Aufgabe des Automatisierungsjobs ist es, alle Servicequotas abzufragen und für jeden Eintrag ein Asset in der Asset-Datenbank zu erstellen oder dieses zu aktualisieren, wenn vorhanden.

        Damit geprüft werden kann, ob ein Asset bereits existiert, wird der Name einer Servicequota als eindeutig innerhalb der Assetklasse vorausgesetzt.

        Da die Angaben der ERP-Datenbank nicht direkt in eine Asset-Struktur eingefügt werden können, müssen diese zuvor aufbereitet werden.

        Es ergibt sich die folgende Liste an Macro Actions:

        1. Action: Get List Of Items From Data Source

          (Konfigurationsparameter der Macro Action s.: Get Item List From Data Source )

          ConnectDB_JobAssetSync_GetItemListFromDS.png

          • ItemList: CompanyList

          • Data Source: Servicequotas (DB)

          • Search:

            {
  "Item": {
    "AND": [
      {
        "Field": "customer_no",
        "Operator": "LIKE",
        "Type": "STRING",
        "Value": "%"
      }
    ]
  }
}

          • Parameters:

            • {} (leer/keine Angaben)

        2. Action: Loop

          (Konfigurationsparameter der Macro Action s. Schleife )

          ConnectDB_JobAssetSync_Loop.png

          • Values: ${CompanyList}

          • Loop Variable: CurrCompany

          • Macro: Synchronisation

            1. Aktion: Get Item From Data Source

              Achtung: Struktur beachten! Gehört zu Macro unter Loop

              (Konfigurationsparameter der Macro Action s.: Get Item From Data Source )

              ConnectDB_JobAssetSync_GetItemFromDS.png

              • Item: CurrCompanyData

              • Data SourceServicequotas (DB)

              • Item ID: ${CurrCompany.ID}

            2. Aktion: XSL Transformation

              Achtung: Struktur beachten! Gehört zu Macro unter Loop

              (Konfigurationsparameter der Macro Action s.: XSL Transformation)

              ConnectDB_JobAssetSync_XSLT.png

              • TransformedData: CurrQuotaAssetData

              • Data: ${CurrCompanyData}

              • XSL Template:

                <?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:KIX="urn:KIX">
<xsl:output method="xml" encoding="utf-8" indent="yes"/>
  <xsl:template match="RootElement">
    <root>
      <xsl:variable name="AssetName"><xsl:value-of select="cname"/></xsl:variable>
      <AssetID><xsl:value-of select="KIX:AssetGetIDByClassAndName('Quota', $AssetName )"/></AssetID>
      <ClassID>93</ClassID> <!-- AssetClassID for "Quota" +++ check ID before flight !!! -->
      <Version>
        <DeplStateID>16</DeplStateID> <!-- Production -->
        <InciStateID>1</InciStateID>  <!-- Operational -->
        <Name><xsl:value-of select="$AssetName"/></Name>
        <Data>
          <OrgNumber><xsl:value-of select="cno"/></OrgNumber>
          <Quota><xsl:value-of select="quota"/></Quota>
        </Data>
      </Version>
    </root>
  </xsl:template>
</xsl:stylesheet>

              • Force Array Tags: [leer]

              • Suppress Empty: Undefined

              • Debug: no

            3. Aktion: Create or update an asset

              Achtung: Struktur beachten! Gehört zu Macro unter Loop

              (Konfigurationsparameter der Macro Action s.: Asset erstellen oder aktualisieren

              ConnectDB_JobAssetSync_CreateUpdateAsset.png

              • AssetID: ResultAssetID (oder leer)

              • VersionID: ResultVersionID (oder leer)

              • Asset JSON Object: ${CurrQuotaAssetData|JSON}

    Ergebnis:

    Nach einer manuellen oder automatischen Ausführung des Jobs werden Assets angelegt bzw. aktualisiert:

    ConnectDB_JobAssetSync_Result.png

Verwendung der KIX Datenbank

Sie können auch die KIX-eigene Datenbank anbinden. Die dafür erforderlichen Zugangsdaten können - ausgehend vom Docker Host - aus der Backend-Konfiguration ermittelt werden:

# access KIX backend service...
user@dockerhost:/opt/kix-on-premise/deploy/linux$ docker exec -it kixpro-backend-1 bash
 
# check currently used database setting in KIX configuration...
I have no name!@4be1ec32c580:/opt/kix$ cat /opt/kix/config/01main | grep Database
'DatabaseHost'   => 'db',
'Database'       => 'kix',
'DatabaseUser'   => 'kix',
'DatabasePw'     => 'Password',
'Database::Type' => 'postgresql',
'DatabaseDSN'    => "DBI:Pg:dbname=<KIX_CONFIG_Database>;host=<KIX_CONFIG_DatabaseHost>;",
I have no name!@4be1ec32c580:/opt/kix$
 
# resulting DSN...
DBI:Pg:dbname=kix;host=db;

Achtung

Beachten Sie, dass die Verwendung von KIX-eigenen Strukturen von Updates beeinflusst werden kann.

Sollten eigene DB-Strukturen angelegt werden (z. B. Views), versehen Sie diese konsequent mit einem spezifischem Präfix, z. B. "acme_orderlists".

In diesem Abschnitt: