Templates

Templates sind immer an Organisationen gebunden, wobei eine Data Management Komponente einer Organisation entspricht.

Von den Templates leiten sich die Assets ab.

Es gibt mehrere Möglichkeiten, ein Template für das Data Management zu erstellen.

Beachten Sie die Groß- und Kleinschreibung.
Das Data Management Modul ist case sensitive.

Template erstellen per API Call

Das Erstellen per API Call eignet sich vor allem, wenn mehrere bzw. zahlreiche Templates angelegt werden sollen.

Voraussetzungen

  • HTTP- oder REST-Client (z.B. soapUI)

  • HTTP Request:

    • URI: <schema>://<host>:<port>/ibis/rest/rc/am/protocol angepasst an Ihre spezifische Installation

    • HTTP Method: POST

    • Authentication: HTTP Basic Authentication

    • Login-Name, Passwort: Login-Name und Passwort des hier erstellten Users

    • Authorization Type: In soapUI auf "Preemptive" setzen

    • Request Body:

      <request>
          <context><!-- e. g. asset, person, template --></context>
          <method><!-- e. g. create, get, query, update --></method>
          <module>am</module>
          <parameters>
              <!-- ... -->
          </parameters>
      </request>

Siehe auch Data Management API.

Initiales Template erstellen

Für ein erstes leeres Template senden Sie mithilfe des HTTP-/Rest-Clients den folgenden Request an das Data Management:

<request>
    <context>template</context>
    <method>create</method>
    <module>am</module>
    <parameters>
        <return>true</return>
    </parameters>
</request>

Der Parameter return, der auf "true" gesetzt wird, weist das Data Management an, das neu erstellte Template zurückzugeben.

Die technische ID des neu erstellten Templates wird immer zurückgegeben.

Template erstellen per Template-Editor im BPC

Das Erstellen per Template-Editor eignet sich eher für einzelne Templates, da die Modulkomponenten hier händisch einzeln erstellt und konfiguriert werden.

  1. Im BPC-Administrationsbereich den Reiter "Data Management" öffnen.

  2. Die während der Installation angelegte Modulkomponente auswählen.

  3. Reiter "Organisation verwalten" wählen.

  4. Reiter "Vorlagen" wählen.

  5. Neue Vorlage anlegen.

    create template bpc 01
  6. XML-Struktur des Templates in den Editor schreiben/kopieren.

    create template bpc 02

Genereller Aufbau von Templates

<api>
    <organizationId>organizationID</organizationId>
    <locale>en</locale>
    <requests>
        <request>
            <module>am</module>
            <context>template</context>
            <method>create/update/delete</method>
            <parameters>
                <template>
                    <customId>Selbstgewählte ID</customId>
   			            <id>ID</id>
                        <labels>
                            <de>Template-Name auf Deutsch</de>
                        </labels>
                        <versionedAttributes>
                    	    <attribute>... </attribute>
                    	    <attribute>... </attribute>
                	    </versionedAttributes>
                        <unversionedAttributes>
                            <attribute>... </attribute>
                        </unversionedAttributes>
		                <use> ... </use>
                        <parents> ... </parents>
                        <children> ... </children>
                </template>
            </parameters>
        </request>
    </requests>
</api>

Die Elemente customId, id und use sind optional.

Template-Inhalte

Element Beschreibung Beispiel

ID

Ein Identifier, der bei der Erstellung des Templates generiert wird. Er wird (alternativ zu customId) für Referenzen benötigt, z.B. zwischen einem Asset und seinem Template.

Ist nur für die Aktion update relevant.

<id>

CustomID

Ein Identifier, der manuell gesetzt werden kann. Er wird (alternativ zu id) für Referenzen benötigt, z.B. zwischen einem Asset und seinem Template.

Um die customId eines Templates zu ändern, aktualisieren Sie das Template mit der Angabe von id (der einzige Anwendungsfall, der id erfordert)

ausschließlich char-Werte → keine Nummern-Werte → Kombination funktioniert (Id-33) → Am besten gleich benennen wie Template label → Ohne Label oder display wird für beides von CustomID belegt

<customId>Produkt</customId>

colorCode

Der verwendete XPATH, um den endgültigen HTML-Farbcode zur Anzeige im Frontend auszuwerten.

Der definierte XPATH kann verwendet werden, um die versionierten Attribute oder die Zeitreihendaten auf der Grundlage der im XPATH definierten Schlüsselwörter auszuwerten.

Die zulässigen "Schlüsselwörter" sind: “/asset/versionedAttributes”.

<colorCode>
    <xpath> ... </xpath>
</colorCode>

labels

Enthält sprachspezifische Bezeichnungen/labels des Templates.
Die Struktur ähnelt den Labels von Attributen.

<labels>
    <de>Produkt</de>
    <en>Product</en>
</labels>

versionedAttributes

Diese Attribute verwenden die Historisierung, sodass bei einer Aktualisierung die neuen Werte die aktuellen Werte nicht ersetzen, sondern der Datenbank hinzugefügt werden. Die letzte Version wird lediglich als veraltet gekennzeichnet, sodass sie in der Datenbank verbleibt.
Siehe auch Attributeigenschaften.
Alte Versionen können abgerufen werden, d.h. es ist möglich, in der Zeit zurückzugehen.
Für Attribute, die sich häufig ändern, sind das spezialisierte TSM-Modul und der Datentyp zu bevorzugen, um die Auswirkungen auf Speicherplatz, CPU-Anforderungen usw. zu verringern.

<versionedAttributes>
    <attribute> …  </attribute>
</versionedAttributes>

unversionedAttributes

Diese Attribute verwenden keine Historisierung, sodass bei einer Aktualisierung die neuen Werte die aktuellen Werte ersetzen.
Es ist nicht möglich, in der Zeit zurückzugehen. Daher können alte Versionen nicht abgerufen werden.

<unversionedAttributes>
<attribute>...</attribute>
</unversionedAttributes>

attribute

Felder der Assets/Stammdaten.
Sie können nicht alleine stehen und müssen entweder in unversionedAttributes oder versionedAttributes definiert werden.

<attribute>...</attribute>

children

Liste der Templates, die Kinder des aktuellen Templates sein können.
In den untergeordneten Templates muss das aktuelle Template als übergeordnetes Template definiert sein. Wenn kein Wert für maximumQuantity angegeben wird, wird der Standardwert 0 = unbounded verwendet.
Siehe auch Relationen zwischen Templates

<children>
    <template>
        <id>...<id>
    </template>
</children>

parents

Liste der Templates, die Eltern des aktuellen Templates sein können.
Ein Beispiel für einen Anwendungsfall ist ein Template für ein einzelnes Stromgeneratormodell, das nur in bestimmten Kraftwerkstypen enthalten sein kann.
Siehe auch Relationen zwischen Templates.

<parents>
    <template>
        <id>52</id>
    </template>
</parents>

actions

Für ein Template können Aktionen definiert werden, z.B. kann eine Anlage abgeschaltet oder eine Serviceaufgabe ausgelöst werden.

Beispiele

Beispielaufbau eines "create"-Templates für Produkte in der Organisation "Supermarkt"
<api>
    <organizationId>supermarkt</organizationId>
    <locale>de</locale>
    <requests>
        <request>
            <module>am</module>
            <context>template</context>
            <method>create</method>
            <parameters>
                <template>
                    <customId>Produkt</customId>
                    <versionedAttributes>
                        <attribute>
                            <key>Anfangsproduktnummer</key>
                            <type>number</type>
                            <required>true</required>
                            <unique>true</unique>
                        </attribute>
                        <attribute>
                            <key>Produkt</key>
                            <type>group</type>
                            <attributes>
                                <attribute>
                                    <key>Produktart</key>
                                    <type>string</type>
                                    <required>true</required>
                                    <enums>
                                        <enum>
                                            <key>1</key>
                                            <labels>
                                                <de>Lebensmittel</de>
                                            </labels>
                                        </enum>
                                        <enum>
                                            <key>2</key>
                                            <labels>
                                                <de>Süßwaren</de>
                                            </labels>
                                        </enum>
                                        <enum>
                                            <key>3</key>
                                            <labels>
                                                <de>Drogerieartikel</de>
                                            </labels>
                                        </enum>
                                        <enum>
                                            <key>4</key>
                                            <labels>
                                                <de>Getränke</de>
                                            </labels>
                                        </enum>
                                    </enums>
                                </attribute>
                                <attribute>
                                    <key>Herkunftsland</key>
                                    <type>string</type>
                                    <required>true</required>
                                </attribute>
                            </attributes>
                        </attribute>
                        <attribute>
                            <key>Produktname</key>
                            <type>string</type>
                            <required>true</required>
                            <unique>true</unique>
                        </attribute>

                        <attribute>
                            <key>Lagerort</key>
                            <type>group</type>
                            <attributes>
                                <attribute>
                                    <key>Lager</key>
                                    <required>true</required>
                                    <type>enum</type>
                                    <enums>
                                        <enum>
                                            <key>1</key>
                                            <labels>
                                                <de>Hochregallager</de>
                                            </labels>
                                        </enum>
                                        <enum>
                                            <key>2</key>
                                            <labels>
                                                <de>Kühlhaus</de>
                                            </labels>
                                        </enum>
                                    </enums>
                                </attribute>
                                <attribute>
                                    <key>Lagerort</key>
                                    <type>group</type>
                                    <required>true</required>
                                    <attributes>
                                        <attribute>
                                            <key>regal-nr</key>
                                            <labels>
                                                <de>Regal Nummer</de>
                                            </labels>
                                            <type>number</type>

                                        </attribute>
                                        <attribute>
                                            <key>regalbrett</key>
                                            <labels>
                                                <de>Regalbrett-Platz</de>
                                            </labels>
                                            <type>string</type>

                                        </attribute>
                                    </attributes>
                                </attribute>
                            </attributes>
                        </attribute>
                        <attribute>
                            <key>Herkunftsland</key>
                            <type>string</type>
                            <required>true</required>
                        </attribute>
                        <attribute>
                            <key>Kommentar</key>
                            <type>string</type>
                            <required>false</required>
                            <multiline>true</multiline>

                        </attribute>
                    </versionedAttributes>
                    <unversionedAttributes/>
                </template>
            </parameters>
        </request>
    </requests>
</api>
Beispielaufbau eines "create"-Templates für Filialen in der Organisation "Supermarkt"
<api>
    <organizationId>supermarkt</organizationId>
    <locale>de</locale>
    <requests>
        <request>
            <module>am</module>
            <context>template</context>
            <method>create</method>
            <parameters>
                <template>
                    <customId>Filiale</customId>
                    <descriptionAttribute>
                        <hidden>true</hidden>
                    </descriptionAttribute>
                    <versionedAttributes>
                        <attribute>
                            <key>Filialleitung</key>
                            <type>string</type>
                            <required>true</required>
                            <defaultValue>Max Mustermann</defaultValue>
                        </attribute>
                        <attribute>
                            <key>Adresse</key>
                            <type>group</type>
                            <collapsed>false</collapsed>
                            <attributes>
                                <attribute>
                                    <key>Straße</key>
                                    <type>string</type>
                                    <required>true</required>
                                    <defaultValue>Muster Straße</defaultValue>
                                    <minLength>5</minLength>
                                </attribute>
                                <attribute>
                                    <key>Hausnummer</key>
                                    <type>string</type>
                                    <required>true</required>
                                    <defaultValue>42</defaultValue>
                                </attribute>
                                <attribute>
                                    <key>plz</key>
                                    <type>string</type>
                                    <minLength>5</minLength>
                                    <maxLength>5</maxLength>

                                    <required>true</required>
                                    <defaultValue>12345</defaultValue>
                                </attribute>
                            </attributes>
                        </attribute>
                    </versionedAttributes>
                    <unversionedAttributes/>
                    <children>
                        <template>
                            <id>55</id>
                            <minimumQuantity>0</minimumQuantity>
                            <maximumQuantity>0</maximumQuantity>
                            <customId>Produkt</customId>
                            <displayName>Produkt</displayName>
                        </template>
                    </children>
                </template>
            </parameters>
        </request>
    </requests>
</api>

Attributeigenschaften

Die folgenden Attributeigenschaften können sowohl für Attribute mit Historie als auch Attribute ohne Historie verwendet werden.

Property Beschreibung Beispiel

key*

Primärschlüssel, der ein Attribut identifiziert.
Falls "labels" oder "displayName" nicht angegeben sind, werden diese Werte durch "key" belegt.

<key>nr</key>

labels

Titel oder Name des Attributs.
Falls labels oder displayName nicht angegeben werden, werden diese Werte durch key belegt.

<labels>
    <de>Drogerieartikel</de>
    <en>Drugstore items</en>
</labels>

enum

Vordefinierte Auswahl von Optionen

displayName

Angezeigter Name fürs Feld, wird ansonsten automatisch vom Label eingefügt.

<displayName>Anfangsproduktnummer</displayName>

displayDescriptions

descriptions

Beschreibung von Attributen

<descriptions>
    <de>Die ersten 5 Zahlen der Produktnummer</de>
</descriptions>

type

Datentyp des Attributs, siehe Datentypen eines Attributs

Multiline

Ermöglicht die Eingabe mehrerer Zeilen in einem Popup-Fenster

<multiline>true/false</multiline>

readOnly

Der Benutzer kann den Wert nicht manuell bearbeiten. Dies ist nur ein Hinweis für das Standard-Frontend und schränkt den Zugriff über die API nicht ein

<readOnly>true/false</readOnly>

required

Der Benutzer kann den Wert nicht manuell bearbeiten. Dies ist nur ein Hinweis für das Standard-Frontend und schränkt den Zugriff über die API nicht ein.

<required>true/false</required>

defaultValue

Dieser Wert wird verwendet, wenn kein Wert vorhanden ist (z.B. bei der Erstellung).
Wenn ein leerer Wert verwendet wurde (z.B. “ “, 0), dann wird nicht der defaultValue genutzt.

<defaultValue>Max Mustermann</defaultValue>

colorCode

Ein Attribut kann einen Farbcode haben.
Wenn dieser Farbcode angegeben ist, wird ein Symbol dieser Farbe direkt vor dem Attributschlüssel gezeichnet, um z.B. für Zustände verwendet zu werden.
Es können auch Felder eingefärbt werden.
Die Verwendung beschränkt sich ausschließlich auf die oberste Attribut-Ebene (also nicht in Listen, Gruppen oder Enums).

hiddenInUI

Wert wird nicht im Standard-Frontend angezeigt.

unique

Einzigartiger Wert

<unique>true</unique>

collapsed

Entscheidet, ob die Gruppe standardmäßig geöffnet oder geschlossen angezeigt wird.
"false" stellt die Gruppe bereits geöffnet dar.

<collapsed>true/false</collapsed>

minValue

Mindestwert für numbers

<minValue>3</minValue>

maxValue

Maximalwert für numbers

<maxValue>10</maxValue>

minLength

Mindestlänge für Strings

<minLength>0</minLength>`

maxLength

Maximale Länge für Strings

<maxLength>100</maxLength>

Mit * markierte Felder müssen definiert werden.

Beispiele

Beispiel für Attribut "enum"
<attribute>
    <required>true</required>
    <key>Produktart</key>
    <type>enum</type>
    <displayName>Produktart</displayName>
    <enums>
        <enum>
            <key>lebensmittel</key>
            <displayName>Lebensmittel</displayName>
            <labels>
                <de>Lebensmittel</de>
            </labels>
        </enum>
        <enum>
            <key>sueßwaren</key>
            <displayName>Süßwaren</displayName>
            <labels>
                <de>Süßwaren</de>
            </labels>
        </enum>
        <enum>
            <key>drogerieartikel</key>
            <displayName>Drogerieartikel</displayName>
            <labels>
                <de>Drogerieartikel</de>
                <en>Drugstore items</en>
            </labels>
        </enum>
        <enum>
            <key>getraenke</key>
            <displayName>Getränke</displayName>
            <labels>
                <de>Getränke</de>
            </labels>
        </enum>
    </enums>
</attribute>
Beispiel für Attribut "type"
<attribute>
    <multiline>true</multiline>
    <key>comment</key>
    <type>string</type>
    <displayName>Kommentar</displayName>
</attribute>
Beispiel für Attribut "colorCode"
<colorCode>
    <xpath>if (/asset/unversionedAttributes/attribute[key/text() = 'status']/value/text() = 'STATUS_OK') then '00ff00' else 'ff0000'</xpath>
</colorCode>

<unversionedAttributes>
<attribute>
    <key>status</key>
    <displayName>Status of Asset</displayName>
    <value>STATUS_OK</value>
</attribute>
<attribute>
    <key>meter_reading</key>
    <displayName>Meter Reading</displayName>
    <value>123</value>
</attribute>
</unversionedAttributes>
Beispiel für Gruppe von Attributen
<attribute>
    <required>true</required>
    <key>Stellplatz</key>
    <type>group</type>
    <displayName>Stellplatz</displayName>
    <attributes>
        <attribute>
            <labels>
                <de>Regal Nummer</de>
            </labels>
            <key>regal-nr</key>
            <type>number</type>
            <displayName>Regal Nummer</displayName>
        </attribute>
        <attribute>
            <labels>
                <de>Regalbrett-Platz</de>
            </labels>
            <key>regalbrett</key>
            <type>string</type>
            <displayName>Regalbrett-Platz</displayName>
        </attribute>
    </attributes>
</attribute>

Datentypen eines Attributs

Sie können den Typ eines versionierten und nicht versionierten Attributs in der Definition des Attributs festlegen.
Der Standardtyp ist "string".
Benutzerdefinierte Attribute sind immer vom Typ "string" mit max. 1024 Zeichen.

Ein Datentyp "basic" kann auch für Listen und Tabellenspalten verwendet werden.

Datentypen "complex" können nicht verschachtelt werden, z. B. für Listen oder Tabellenspalten. Sie können auch keine Gruppen enthalten.

Klasse Typ Beschreibung

basic

boolean

true/false

number

string

password

Einfaches Passwort (nicht geheim, wird nur nicht im Frontend angezeigt).

date

Keine Zeitzone erlaubt. Beispiel: 2014-05-30

time

Keine Zeitzone erlaubt. Beispiel: 23:59:59

dateTime

Keine Zeitzone erlaubt. Beispiel: 23:59:59

enum

Auswahl zwischen festgelegten Optionen.

dynamicEnum

complex

list

Kann Attribute vom Typ Klasse "basic" enthalten.

table

Kann Attribute vom Typ Klasse "basic" enthalten.

group

group

Kann Attribute beliebigen Typs enthalten (Basic, Complex und Group).

Relationen zwischen Templates

Bei der Verknüpfung zwischen Templates kommt es zu einer Eltern-Kind-Beziehung. Ist ein Template ein Kind eines anderen Templates, muss dieses im Eltern-Template unter “children” hinterlegt werden und entsprechend das Eltern-Template im Kind unter “parents”. Das jeweilige Template muss von der Beziehung wissen.
Sie können mehrere Kinder und Eltern hinterlegen.

Falls unter “maximumQuantity” kein Wert hinterlegt wurde, wird "0" gesetzt und als "unbegrenzt" interpretiert.

Sie können entweder die CustomID oder ID hinterlegen.

Beispiel Kind
Kind:
<children>
	<template>
	    <id>53</id>
        <minimumQuantity>0</minimumQuantity>
    <template>
</children>
image
Beispiel Eltern
<parents>
    <template>
        <customId>Filiale</customId>
        <maximumQuantity>1</maximumQuantity>
        <displayName>Heimat</displayName>
    </template>
</parents>

Für die Auswirkungen in der Oberflächenansicht siehe auch Relationen zwischen Objekten.

Template aktualisieren

Letzte Aktualisierung gilt

Falls Änderungen in der BPC-Oberfläche des Data Management Moduls vorgenommen werden, werden diese Änderungen im Modul sichtbar.
Falls jedoch automatisiert INUBIT-Workflows ablaufen, die die Stammdatenobjekte verändern, wird das "alte" Template aus dem Workflow eingespielt und eventuelle Änderungen aus dem BPC-Frontend gehen verloren.

Per API Call

Siehe xref:data_management:admin/api_calls.adoc

Es ist nicht möglich, Templates auf die gleiche Art und Weise wie Assets zu bearbeiten. Sollten Templates per API-Call verändert werden, muss erst einmal das gesamte Template angefragt und dann das gewünschte Element geändert werden.
Wird eine Änderung ausschließlich mit dem zu verändernden Element abgeschickt, so wird das gesamte Template überschrieben.

Per Template-Editor im BPC

Vorhandene Templates können in der BPC-Oberfläche angepasst werden.

  1. Im BPC-Administrationsbereich den Reiter "Data Management" öffnen.

  2. Die gewünschte Modulkomponente auswählen.

  3. Reiter "Organisation verwalten" wählen.

  4. Reiter "Vorlagen" wählen.

  5. Gewünschte Vorlage zur Bearbeitung aufrufen.

    update template bpc 01
  6. Im Template-Editor die gewünschten Anpassungen vornehmen.

  7. Aktualisieren wählen.

    update template bpc 02

Template löschen

Vor dem Löschen eines Templates müssen alle Stammdatenobjekte, die mit dem Template erstellt werden, gelöscht werden. Es dürfen also keine Abhängigkeiten mehr bestehen.

Falls Templates über die BPC-Oberfläche gelöscht werden, werden sie in der Datenbank getaggt und entsprechend nicht mehr in der Oberfläche angezeigt. Sie sind jedoch noch in der Datenbank hinterlegt.

  1. Im BPC-Administrationsbereich den Reiter "Data Management" öffnen.

  2. Die gewünschte Modulkomponente auswählen.

  3. Reiter "Organisation verwalten" wählen.

  4. Reiter "Vorlagen" wählen.

  5. Die gewünschte Vorlage löschen.

    delete template

Für das endgültige Löschen aus der Datenbank:

  1. Alle gelöschten Elemente des Templates endgültig löschen

    1. DELETE FROM TEM_LABELS WHERE TEMPLATEID = $ID;

    2. DELETE FROM TEM_CHILDREN WHERE TEMPLATEID = $ID;

    3. DELETE FROM TEM_PARENTS WHERE TEMPLATEID = $ID;

  2. DELETE FROM TEMPLATES WHERE ID = $ID;