Helper - Benutzerbeiträge [de]

Sentry

2026-06-18T12:45:33Z

Silvan:

__NOTOC__
== Inhaltsverzeichnis ==
* [[#Überblick|Überblick]]
* [[#Installation|Installation]]
* [[#Quickstart|Quickstart]]
* [[#Events erfassen|Events erfassen]]
* [[#Eigene Exceptions standardisieren|Eigene Exceptions standardisieren]]
* [[#Tags, Extras und User-Kontext|Tags, Extras und User-Kontext]]
* [[#Stacktrace und Kontext|Stacktrace und Kontext]]
* [[#Interne Architektur|Interne Architektur]]
* [[#Demo Library|Demo Library]]
* [[#API Reference|API Reference]]
* [[#Troubleshooting|Troubleshooting]]

== Überblick ==

OSentry ist ein REST-API-Konnektor von Omnis Studio zu Sentry. Der Konnektor sendet Fehler, Messages, Logs und Laufzeitkontext aus Omnis-Anwendungen an Sentry, damit Probleme in produktiven Systemen sichtbar, gruppierbar und analysierbar werden.

Diese Dokumentation beschreibt die [[#Installation|Installation]], die Nutzung in bestehenden Omnis-Anwendungen, die Definition eigener standardisierter Exception-Typen, die interne Struktur und die [[#Demo Library|Demo-Library]].

=== Kernidee ===

OSentry besteht aus zwei produktiv relevanten Klassen:

* <code>OSentryHL</code>: High-Level-Adapter für die Anwendung. Diese Klasse sollte von normalem Applikationscode aufgerufen werden.
* <code>OSentry</code>: Low-Level-Adapter für DSN-Parsing, JSON-Erzeugung, [[#Stacktrace und Kontext|Stacktrace]]-Aufbereitung und HTTP-Kommunikation mit Sentry.

Die Anwendung arbeitet im Normalfall mit <code>OSentryHL</code>. Dadurch bleiben Sentry-spezifische Details zentral gekapselt und neue standardisierte Exception-Typen können als eigene Methoden in <code>OSentryHL</code> definiert werden.

=== Hauptfeatures ===

* Direkte Anbindung von Omnis Studio an Sentry über REST API und DSN
* Erfassen von Exceptions, Messages, Logs und SQL-Fehlern
* Unterstützung der Sentry-Level <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code> und <code>debug</code>
* Automatische Omnis-Kontextinformationen
* Omnis-[[#Stacktrace und Kontext|Stacktrace]] mit Klassen, Methoden, Zeilen und Variablen
* [[#Tags, Extras und User-Kontext|Tags]] für Filterung und Gruppierung
* [[#Tags, Extras und User-Kontext|Extras]] für zusätzliche Diagnoseinformationen
* Optionaler [[#Tags, Extras und User-Kontext|User-Kontext]]
* Proxy-Unterstützung
* Aktivieren und Deaktivieren der Sentry-Übertragung
* Lokales Speichern von Reports bei Übertragungsfehlern

=== Weiterführende Links ===

* [https://sentry.io/welcome/ Sentry Website]
* [https://sentry.io/signup/ Sentry Account erstellen]
* [https://develop.sentry.dev/self-hosted/ Sentry self-hosted]

== Installation ==

Diese Seite beschreibt, wie OSentry in eine bestehende Omnis-Anwendung integriert wird.

=== Voraussetzungen ===

* Omnis Studio Anwendung
* Sentry Account oder self-hosted Sentry Installation
* Ein Sentry-Projekt mit SDK-Typ <code>Other</code>
* Die DSN des Sentry-Projekts
* Netzwerkzugriff auf Sentry

Die exportierte [[#Demo Library|Demo-Library]] wurde mit Omnis <code>11.1</code> erstellt.

=== Sentry-Projekt erstellen ===

# In Sentry ein neues Projekt erstellen.
# Als SDK <code>Other</code> auswählen.
# Die DSN des Projekts kopieren.

Die DSN wird beim Initialisieren verwendet. <code>OSentry</code> zerlegt sie intern in Public Key, Host und Project ID.

[[Datei:Sentry-projects.png|900px|Sentry Projektübersicht]]

=== Klassen kopieren ===

Kopiere die folgenden Klassen in deine bestehende Omnis-Library:

* <code>OSentry</code>
* <code>OSentryHL</code>

Die Demo-spezifischen Klassen sind für die produktive Integration nicht erforderlich. Damit sind die übrigen Klassen der Demo-Library gemeint, zum Beispiel <code>FSY_Demo</code>, <code>ODummy</code>, <code>ODatabaseHandler</code> und <code>OSLSession</code>. Diese Klassen dienen nur dazu, die [[#Demo Library|Demo-Library]] mit Fenster, SQLite-Testdaten und Beispielaufrufen auszuführen.

=== Task Variable anlegen ===

Lege in deiner Startup Task eine Task Variable an:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' <code>tSentry</code> sollte als global erreichbarer Singleton der Anwendung verwendet werden. In Omnis ist dafür eine Task Variable sinnvoll, weil sie von Fenstern, Objektklassen und zentralen Error-Handlern aus konsistent erreichbar ist. Dadurch gibt es genau eine aktive Sentry-Konfiguration mit einer DSN, einem Status, optionalen Proxy-Daten und gemeinsamen Wrapper-Methoden in <code>OSentryHL</code>.</div>

Im [[#Demo Library|Demo-Projekt]] ist diese Variable in <code>Startup_Task</code> definiert.

=== Initialisierung im Startup Task ===

Initialisiere <code>tSentry</code> beim Start deiner Anwendung mit der DSN deines Sentry-Projekts:

<pre>
Do tSentry.$init('<DSN>')
</pre>

Die [[#Demo Library|Demo-Library]] ruft im Startup Task ebenfalls die Initialisierung auf. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()
</pre>

In einer produktiven Anwendung sollte die DSN explizit oder aus einer Konfiguration übergeben werden:

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Speichere die DSN in einer Datenbank, einer Konfigurationstabelle oder einem Config File. So kann sie pro Kunde, Umgebung oder Installation geändert werden, ohne die Library neu auszuliefern.</div>

=== Testcall ===

Nach der Initialisierung kann ein erstes Testevent gesendet werden:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Wenn alles korrekt eingerichtet ist, erscheint das Event im Sentry-Projekt.

=== Proxy konfigurieren ===

Falls die Anwendung in einem geschützten Netzwerk läuft, kann ein Proxy gesetzt werden. Die Methode befindet sich im Low-Level-Objekt <code>OSentry</code>.

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Die interne Implementierung setzt den Proxy vor dem HTTP-Request:

<pre>
#Configure proxy; needed when sending data out of secured networks
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Sentry aktivieren oder deaktivieren ===

OSentry kann zentral ein- oder ausgeschaltet werden.

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Deaktiviere Sentry in der Entwicklungs-Version standardmäßig oder verwende eine separate Entwicklungs-DSN. So landen lokale Tests, Debug-Fehler und absichtlich ausgelöste Exceptions nicht im produktiven Sentry-Projekt.</div>

<pre>
Do tSentry.$setStatus(1) ## aktiv
Do tSentry.$setStatus(0) ## inaktiv
</pre>

Im Low-Level-Objekt <code>OSentry</code> wird vor dem Senden geprüft:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

== Quickstart ==

Diese Seite zeigt die minimale Integration in eine bestehende Omnis-Anwendung.

=== Klassen übernehmen ===

Kopiere <code>OSentry</code> und <code>OSentryHL</code> in deine Library.

=== Task Variable erstellen ===

In der Startup Task:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

=== Sentry initialisieren ===

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<code>OSentryHL.$init</code> delegiert an das Low-Level-Objekt <code>OSentry</code>:

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

=== Message senden ===

<pre>
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
</pre>

Die [[#Demo Library|Demo-Library]] verwendet genau diesen Aufruf im Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception senden ===

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

=== In Sentry prüfen ===

In Sentry sollte anschließend ein neues Event sichtbar sein. Je nach Event-Typ enthält es:

* Message
* Level
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Tags, Extras und User-Kontext|User-Kontext]]
* [[#Stacktrace und Kontext|Stacktrace]]
* Omnis-Kontextinformationen

== Events erfassen ==

OSentryHL ist die empfohlene Einstiegsschicht für Applikationscode. Die Klasse bietet sprechende Methoden für typische Event-Arten und ruft intern <code>OSentry.$captureException</code> auf.

=== Message ===

Eine einfache Information wird mit <code>$captureMessage</code> gesendet:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

Verhalten:

* Level: <code>info</code>
* Kein [[#Stacktrace und Kontext|Stacktrace]]
* Kein [[#Tags, Extras und User-Kontext|User Interface]]
* Geeignet für einfache Statusmeldungen oder technische Hinweise

=== Log ===

Ein Log-Event wird mit <code>$captureLog</code> gesendet:

<pre>
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

Verhalten:

* Level: <code>warning</code>
* [[#Stacktrace und Kontext|Stacktrace]] aktiv
* Exception Interface in diesem Wrapper deaktiviert
* [[#Tags, Extras und User-Kontext|User Interface]] aktiv

=== Generische Exception ===

Eine generische Exception wird mit <code>$captureException</code> gesendet:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

Parameter:

{| class="wikitable"
! Parameter !! Bedeutung
|-
| <code>pErrorText</code> || Text, der in Sentry als Message sichtbar ist
|-
| <code>pErrorCode</code> || Fehlercode oder fachlicher Code
|-
| <code>pExcType</code> || Exception-Typ für Benennung und Gruppierung
|-
| <code>pLevel</code> || Sentry-Level
|}

Gültige Levels:

* <code>fatal</code>
* <code>error</code>
* <code>warning</code>
* <code>info</code>
* <code>debug</code>

=== SQL Exception ===

SQL-Fehler können mit <code>$captureSQLException</code> gemeldet werden.

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

Verhalten:

* Fügt die Datenbank als [[#Tags, Extras und User-Kontext|Tag]] hinzu
* Fügt SQL-Text als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Fügt native Datenbankfehlermeldung als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Sendet das Event als <code>SQL-Exception</code> mit Level <code>error</code>

=== Deprecated Call ===

Veraltete Codepfade können gezielt gemeldet werden:

<pre>
Do tSentry.$captureDeprecatedCall()
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

Dieser Wrapper eignet sich, um zu erkennen, ob alter Code in produktiven Systemen noch ausgeführt wird.

=== Frei konfigurierbares Event ===

Für Sonderfälle gibt es <code>$captureAnything</code>:

<pre>
Do tSentry.$captureAnything('Text',1001,'Custom Type','error',kTrue,kTrue,kTrue)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Diese Methode bietet maximale Flexibilität. Für wiederkehrende Exception-Typen sollte aber eine eigene Methode in <code>OSentryHL</code> angelegt werden. Siehe [[#Eigene Exceptions standardisieren|04 Eigene Exceptions standardisieren]].

== Eigene Exceptions standardisieren ==

Wenn ein Exception-Typ mehrfach in der Anwendung vorkommt, sollte er nicht überall manuell mit <code>$captureException</code> aufgebaut werden. Besser ist eine eigene Methode in <code>OSentryHL</code>.

Dadurch entsteht eine zentrale, wiederverwendbare Definition für:

* Exception-Typ
* Sentry-Level
* Fehlercode
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Stacktrace und Kontext|Stacktrace]]/[[#Tags, Extras und User-Kontext|User]]/Exception Interface

Die automatisch gesetzten [[#Tags, Extras und User-Kontext|Tags und Extras]] aus <code>OSentry.$generateJson</code> müssen in solchen Wrappern nicht erneut ergänzt werden. Eigene Exception-Methoden setzen nur zusätzliche Werte, die für diesen standardisierten Exception-Typ relevant sind.

=== Warum über OSentryHL? ===

<code>OSentryHL</code> ist die Abstraktionsschicht für Applikationscode. Sie kapselt die Details von <code>OSentry</code> und sorgt dafür, dass Aufrufe in der Anwendung kurz und konsistent bleiben.

Bestehende Beispiele aus <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

=== Empfohlenes Muster ===

Für jeden standardisierten Exception-Typ wird eine eigene Methode in <code>OSentryHL</code> erstellt.

Beispiel:

<pre>
# Captures a validation exception
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addExtra('Field',pField)
Do $cinst.$addExtra('Invalid Value',pValue)

Do iOSentry.$captureException(pErrorText,2001,'Validation-Exception','warning',1,1,1) Returns code

Quit method code
</pre>

Mögliche Parameter der neuen Methode:

{| class="wikitable"
! Parameter !! Beispiel !! Zweck
|-
| <code>pErrorText</code> || <code>'Invalid customer number'</code> || Sentry Message
|-
| <code>pModule</code> || <code>'Customer'</code> || Filterbarer Tag
|-
| <code>pField</code> || <code>'cu_number'</code> || Diagnoseinformation
|-
| <code>pValue</code> || <code>'ABC'</code> || Diagnoseinformation
|}

Der Applikationscode bleibt dadurch einfach:

<pre>
Do tSentry.$captureValidationException('Invalid customer number','Customer','cu_number',cu_number)
</pre>

=== Beispiel: Business Rule Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures a business rule violation
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do $cinst.$addExtra('Details',pDetails)

Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureBusinessRuleViolation('Invoice cannot be posted','Invoice','PostingAllowed','Invoice is missing customer')
</pre>

=== Beispiel: Integration Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures an integration exception
Do $cinst.$addTag('Integration',pSystem)
Do $cinst.$addTag('Endpoint',pEndpoint)
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)

Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureIntegrationException('External API request failed','ERP','/api/customer',jsonPayload,responseText)
</pre>

=== Namenskonventionen ===

Empfehlung für neue Methoden:

* Methodenname beginnt mit <code>$capture</code>
* Der fachliche Typ steht im Methodennamen
* Der Sentry Exception Type ist stabil und ändert sich nicht laufend
* [[#Tags, Extras und User-Kontext|Tags]] sind kurz und filterbar
* [[#Tags, Extras und User-Kontext|Extras]] dürfen länger sein und Diagnoseinformationen enthalten

Beispiele:

* <code>$captureValidationException</code>
* <code>$captureBusinessRuleViolation</code>
* <code>$captureIntegrationException</code>
* <code>$capturePermissionViolation</code>
* <code>$captureConfigurationError</code>

=== Error Codes ===

Verwende feste Fehlercodes für standardisierte Exception-Typen. Dadurch können Events in Sentry besser gefiltert und wiedererkannt werden.

Beispiel:

{| class="wikitable"
! Code !! Exception Type
|-
| <code>2001</code> || <code>Validation-Exception</code>
|-
| <code>3001</code> || <code>Business-Rule-Violation</code>
|-
| <code>4001</code> || <code>Integration-Exception</code>
|-
| <code>5001</code> || <code>Configuration-Error</code>
|}

=== Wann nicht standardisieren? ===

Nicht jeder Einzelfall braucht eine eigene Methode. Für einmalige technische Tests oder sehr spezielle Fälle reicht:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Sobald ein Exception-Typ aber mehrfach vorkommt oder fachlich relevant ist, sollte er als eigene Methode in <code>OSentryHL</code> definiert werden.

== Tags, Extras und User-Kontext ==

Tags, Extras und User-Kontext reichern Sentry-Events mit zusätzlichen Informationen an. Diese Informationen helfen beim Filtern, Gruppieren und Analysieren.

[[Datei:Sentry-tags.png|900px|Sentry Tags und User-Kontext]]

=== Tags ===

Tags sind kurze, filterbare Werte.

Beispiele:

* Datenbank
* Kunde
* Modul
* Umgebung
* Error Code
* Omnis-Version

Methode in <code>OSentryHL</code>:

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds a tag to the next request processed
Do iTagList.$add(pName,pValue)
Quit method
</pre>

Beispiel:

<pre>
Do tSentry.$addTag('Module','Invoice')
Do tSentry.$addTag('Customer','10001')
Do tSentry.$captureException('Invoice posting failed',3001,'Business-Rule-Violation','warning')
</pre>

=== Extras ===

Extras sind Detailinformationen, die nicht primär zum Filtern gedacht sind.

Beispiele:

* SQL-Text
* Native Datenbankfehlermeldung
* Payload
* Response Body
* interne IDs
* zusätzliche Debug-Informationen

Methode in <code>OSentryHL</code>:

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds extra information to the next request being processed
Do iExtraList.$add(pName,pValue)
Quit method
</pre>

Beispiel aus der SQL Exception:

<pre>
Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)
</pre>

=== Automatische Tags ===

Die folgenden Tags werden bei jedem Event automatisch von <code>OSentry.$generateJson</code> ergänzt. Sie müssen bei eigenen Exceptions nicht erneut gesetzt werden. Eigene Wrapper-Methoden in <code>OSentryHL</code> sollten nur zusätzliche, fachlich oder technisch relevante Tags hinzufügen.

<code>OSentry.$generateJson</code> fügt mehrere Tags automatisch hinzu:

<pre>
# Add static tags
Do iTagList.$add('Omnisversion',sys(1))
Calculate systemversionRow as systemversion()
Do iTagList.$add('Plattform',con(sys(8),pick(systemversionRow.server,'',' SRV')))
Do iTagList.$add('OS Version',con(systemversionRow.major,'.',systemversionRow.minor,'.',systemversionRow.build))
Do iTagList.$add('error_code',pErrorCode)
</pre>

Automatisch gesendete Tags:

{| class="wikitable"
! Tag !! Herkunft !! Zweck
|-
| <code>Omnisversion</code> || <code>sys(1)</code> || Zeigt, mit welcher Omnis-Version das Event erzeugt wurde
|-
| <code>Plattform</code> || <code>sys(8)</code> und Server-Flag aus <code>systemversion()</code> || Unterscheidet Plattform und Server Runtime
|-
| <code>OS Version</code> || <code>systemversionRow.major/minor/build</code> || Zeigt die Betriebssystemversion
|-
| <code>error_code</code> || Parameter <code>pErrorCode</code> || Verbindet das Event mit dem übergebenen Fehlercode
|}

Beispiel für eine eigene Exception: Der Wrapper muss nicht erneut <code>Omnisversion</code> oder <code>OS Version</code> setzen. Er ergänzt nur das, was für diesen Exception-Typ zusätzlich hilfreich ist.

<pre>
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code
</pre>

=== Automatische Extras ===

Auch die folgenden Extras werden bei jedem Event automatisch ergänzt. Bei eigenen Exceptions müssen nur zusätzliche Extras gesetzt werden, zum Beispiel ein SQL-Statement, ein Payload oder fachliche Zusatzdaten.

<code>OSentry.$generateJson</code> fügt offene Fenster, offene Reports und die aktuelle Printfile hinzu:

<pre>
# Static extra 1: All open windows
Do $root.$iwindows.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate windows as con(windows,', ',nameList.[i].1)
End For
Calculate windows as right(windows,len(windows)-2)
Do iExtraList.$add('Open Windows',windows)

# Static extra 2: All open reports
Do $root.$ireports.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate reports as con(reports,', ',nameList.[i].1)
End For
Calculate reports as right(reports,len(reports)-2)
Do iExtraList.$add('Open Reports',reports)
Do iExtraList.$add('Current Printfile',$root.$prefs.$printfile)
</pre>

Automatisch gesendete Extras:

{| class="wikitable"
! Extra !! Herkunft !! Zweck
|-
| <code>Open Windows</code> || <code>$root.$iwindows.$makelist($ref.$name)</code> || Zeigt, welche Fenster im Moment des Events offen waren
|-
| <code>Open Reports</code> || <code>$root.$ireports.$makelist($ref.$name)</code> || Zeigt, welche Reports im Moment des Events offen waren
|-
| <code>Current Printfile</code> || <code>$root.$prefs.$printfile</code> || Zeigt die aktuell gesetzte Printfile
|}

Beispiel für zusätzliche Extras in einem eigenen Wrapper:

<pre>
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)
Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code
</pre>

=== User-Kontext ===

Der User-Kontext ordnet ein Event einem betroffenen Benutzer zu. In Sentry erscheint dadurch ein eigener User-Bereich, und Events können nach Benutzer gefiltert oder gruppiert werden. Das ist besonders hilfreich, wenn ein Fehler nur bei einzelnen Kunden, Arbeitsplätzen oder Benutzerkonten auftritt.

<code>OSentry</code> unterstützt drei User-Felder:

{| class="wikitable"
! Feld !! Bedeutung
|-
| <code>id</code> || stabile interne Benutzer-ID oder Kundennummer
|-
| <code>username</code> || lesbarer Benutzername
|-
| <code>email</code> || E-Mail-Adresse, falls sie übertragen werden darf
|}

Der User-Kontext wird nur in das Event geschrieben, wenn das User Interface beim Capture-Aufruf aktiviert ist. Die Standardmethode <code>OSentry.$captureException</code> hat <code>pUserInterface</code> standardmäßig auf <code>kTrue</code>. Einzelne High-Level-Methoden können das bewusst deaktivieren, zum Beispiel <code>$captureMessage</code>.

<code>OSentry</code> kann User-Daten an das Event anhängen:

<pre>
#Sets userinformation for the next request being processed
Calculate iUserID as pID
Calculate iUserName as pName
Calculate iUserEmail as pEmail
Quit method
</pre>

Das User Interface wird so generiert:

<pre>
# Create user data row
Do UserdataRow.$define(id,email,username)

Calculate UserdataRow.id as iUserID
Calculate UserdataRow.email as iUserEmail
Calculate UserdataRow.username as iUserName

Do JSON.$addmember('','user','')
Do JSON.$setobject('user',UserdataRow)

Calculate jsonString as OJSON.$formatjson(JSON.$getjson())

Quit method jsonString
</pre>

Die aktuelle Demo-Methode in <code>OSentryHL</code> verwendet feste Testdaten. Quelle: <code>OSentryHL.$setUser</code>.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode angepasst und parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
Quit method
</pre>

Empfohlen ist, den User nach Login oder beim Wechsel des aktiven Benutzers zentral zu setzen. Bei anonymen oder sensiblen Installationen kann statt Name und E-Mail auch nur eine interne ID oder ein pseudonymisierter Wert verwendet werden.

=== Datenschutz ===

<div style="border-left:4px solid #72777d; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Datenschutz:''' Prüfe vor produktiver Nutzung, welche Daten an Sentry gesendet werden. Besonders kritisch sind personenbezogene Daten, SQL-Statements, Zugangsdaten, Tokens und interne Pfade.</div>

Besonders kritisch sind:

* personenbezogene Daten
* Kundendaten
* SQL-Statements mit Werten
* Zugangsdaten
* Tokens
* interne Pfade

Tags und Extras sollten so gestaltet werden, dass sie für die Fehleranalyse hilfreich sind, aber keine unnötigen sensiblen Daten übertragen.

== Stacktrace und Kontext ==

<code>OSentry</code> erzeugt einen Omnis-spezifischen Stacktrace und übergibt ihn an Sentry. Dadurch sieht man in Sentry nicht nur eine Fehlermeldung, sondern auch Klassen, Methoden, Zeilen und Variablenkontext. Ergänzende Informationen zu [[#Tags, Extras und User-Kontext|Tags, Extras und User-Kontext]] stehen auf der separaten Kontext-Seite.

[[Datei:Sentry-stack.png|900px|Sentry Stacktrace mit Omnis-Kontext]]

=== Stack lesen ===

<code>OSentry.$generateStacktraceInterface</code> verwendet <code>sys(192)</code>, um den aktuellen Omnis-Stack zu lesen:

<pre>
# Clean up the Stacklist (remove OSentry classes from the stack)
Do sys(192) Returns sys192List
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
If pos('OSentry',class.$name)>0|pos('OSentryHL',class.$name)>0
Do sys192List.[sys192List.$line].$selected.$assign(kTrue)
End If
End For
Do sys192List.$remove(kListDeleteSelected)
</pre>

Interne Frames von <code>OSentry</code> und <code>OSentryHL</code> werden entfernt, damit in Sentry die fachlich relevanten Stellen sichtbar bleiben.

=== SQL-Error Frames entfernen ===

Bestimmte interne SQL-Fehlerframes werden ebenfalls entfernt:

<pre>
# Remove some other classes which we do not want to display
If sys192List.1.method='$sqlerror'
Do sys192List.$remove(1)
Else If sys192List.1.method='$statementerror'
Do sys192List.$remove(1)
End If
</pre>

=== Frames erzeugen ===

Für jeden Stack-Eintrag werden Funktion, Zeilennummer und Kontextzeile erzeugt:

<pre>
#Loop through every item on the omnis stack
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
Calculate className as class.$name

# Create the content row
Do contentRow.$define(vars,function,pre_context,context_line,lineno,filename,post_context)
Calculate contentRow.lineno as sys192List.line
Calculate contentRow.filename as testFileName
Calculate contentRow.context_line as sys192List.linetext
If isclear(sys192List.object)
Calculate contentRow.function as con(className,'.',sys192List.method) ## If it's a class method
Else
Calculate contentRow.function as con(className,'.',sys192List.object,'.',sys192List.method) ## If it's a method of an object of a class (e.g. Headedlist)
End If
Do contentList.$add(contentRow)
End For
</pre>

=== Variablen aufnehmen ===

Pro Stackframe werden Instance Variablen und Parameter gesammelt:

<pre>
# Get all iVars
Do varList.$define(name,value)
Set reference class to sys192List.inst
Do $cinst.$getVars('ivars',class) Returns varList

# Get all params
Calculate paramList as sys192List.params
For paramList.$line from 1 to paramList.$linecount step 1
If not(paramList.value='(Not empty)')
Do varList.$add(paramList.name,paramList.value)
Else
Do varList.$add(paramList.name,'(Not empty)')
End If
End For
</pre>

=== Pre- und Post-Context ===

OSentry fügt Methodenzeilen vor und nach der aktuellen Zeile hinzu:

<pre>
# Pre Context (all method lines before the error occured)
Set reference method to sys192List.methoditem
Do precontextList.$define(line)
For i from 1 to sys192List.line-1 step 1
Do precontextList.$add(method.$methodlines.[i].$text)
End For

# Post Context (all method lines after the error occured
Do postcontextList.$define(line)
For i from sys192List.line+1 to method.$methodlines.$count step 1
Do postcontextList.$add(method.$methodlines.[i].$text)
End For
</pre>

=== Variablentypen ===

<code>OSentry.$getVars</code> unterstützt Basisvariablen, Rows und Lists.

Basisvariablen:

<pre>
If varType='char'|varType='boolean'|varType='integer'|varType='number'|varType='date'
Calculate varContent as pItemRef.$[pVarType].[varName]
Do varList.$add(varName,varContent)
</pre>

Rows:

<pre>
Else If varType='row'
Calculate varRow as pItemRef.$[pVarType].[varName]
If varRow.$colcount=0
Do varList.$add(varName,'(Empty)')
Else
For Z2 from 1 to varRow.$colcount step 1
Calculate varContent as con(varContent,varRow.$cols.[Z2].$name,': ',varRow.[Z2],', ')
End For
Do varList.$add(varName,varContent)
</pre>

Lists:

<pre>
Else If varType='list'
Calculate varListType as pItemRef.$[pVarType].[varName]
Calculate varContent as con('Colcount: ',varListType.$colcount,', ','Linecount: ',varListType.$linecount,', ','Current Line: ',varListType.$line)
If varListType.$linecount=0&varListType.$line=0&varListType.$colcount=0
Do varList.$add(varName,'(Empty)')
Calculate varContent as ''
Else
For Z3 from 1 to varListType.$colcount step 1
Calculate colName as varListType.$cols.[Z3].$name
Calculate varContent as con(varContent,' ',colName,': ',varListType.[colName])
End For
Do varList.$add(varName,varContent)
Calculate varContent as ''
End If
End If
</pre>

=== Hinweise ===

Stacktrace und Variablenkontext sind sehr hilfreich, können aber sensible Daten enthalten. Vor produktiver Nutzung sollte geprüft werden, ob bestimmte Variablen anonymisiert oder ausgeschlossen werden müssen.

== Interne Architektur ==

Diese Seite beschreibt die produktiv relevanten Klassen <code>OSentryHL</code> und <code>OSentry</code>.

=== Klassenübersicht ===

{| class="wikitable"
! Klasse !! Rolle
|-
| <code>OSentryHL</code> || High-Level-Adapter für Applikationscode
|-
| <code>OSentry</code> || Low-Level-Adapter für JSON, [[#Stacktrace und Kontext|Stacktrace]] und HTTP
|-
| <code>Startup_Task</code> || [[#Demo Library|Demo]]-Startup und Beispiel für Initialisierung
|-
| <code>FSY_Demo</code> || [[#Demo Library|Demo]]-Fenster
|-
| <code>ODummy</code> || [[#Demo Library|Demo]]-Code für [[#Stacktrace und Kontext|Stacktrace]]-Beispiel
|-
| <code>ODatabaseHandler</code> || [[#Demo Library|Demo]]-DB Initialisierung
|-
| <code>OSLSession</code> || SQLite Session für [[#Demo Library|Demo]]
|}

=== Empfohlener Aufrufweg ===

Applikationscode sollte <code>OSentryHL</code> verwenden:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

<code>OSentryHL</code> delegiert anschließend an <code>OSentry</code>:

<pre>
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code
</pre>

=== Ablauf eines Events ===

# Applikationscode ruft Methode in <code>OSentryHL</code> auf.
# <code>OSentryHL</code> fügt bei Bedarf [[#Tags, Extras und User-Kontext|Tags und Extras]] hinzu.
# <code>OSentryHL</code> ruft <code>iOSentry.$captureException(...)</code> auf.
# <code>OSentry</code> prüft, ob Sentry aktiv ist.
# <code>OSentry</code> erzeugt JSON.
# [[#Stacktrace und Kontext|Stacktrace]], Exception Interface und [[#Tags, Extras und User-Kontext|User Interface]] werden optional ergänzt.
# HTTP Header und Sentry Auth Header werden erstellt.
# JSON wird per HTTPS an Sentry gesendet.
# Bei Erfolg werden [[#Tags, Extras und User-Kontext|Tags und Extras]] geleert.
# Bei Fehler wird der JSON Report lokal gespeichert.

=== DSN Parsing ===

<code>OSentry.$init</code> zerlegt die DSN:

<pre>
# Parse the DSN into Public Key, Host and Project ID
If len(pDSN)>5
Calculate iDSN as pDSN
Calculate part1 as strtok('iDSN','@')
Calculate iProtocol as strtok('part1','/')
Calculate iProtocol as left(iProtocol,len(iProtocol)-1)
Do strtok('part1','/')
Calculate iPubKey as strtok('part1',':')

Calculate iHost as strtok('iDSN','/')
Calculate iProID as iDSN

#Save the values for the next startup
Calculate $cclass.$ivardefs.iPubKey.$objinitval as con('"',iPubKey,'"')
Calculate $cclass.$ivardefs.iHost.$objinitval as con('"',iHost,'"')
Calculate $cclass.$ivardefs.iProID.$objinitval as con('"',iProID,'"')
End If

Quit method
</pre>

=== JSON-Erzeugung ===

<code>OSentry.$generateJson</code> ist die zentrale Methode für den Payload. Sie setzt unter anderem:

* <code>event_id</code>
* <code>logger</code>
* <code>platform</code>
* <code>culprit</code>
* <code>timestamp</code>
* <code>sdk</code>
* <code>message</code>
* <code>level</code>
* <code>tags</code>
* <code>extra</code>
* optional <code>user</code>
* optional <code>exception</code>
* optional <code>stacktrace</code>

Auszug:

<pre>
# Add all required fields (those are required from the API)
Do JSON.$addmember('','event_id',$cinst.$generateUUID()) ## auto generated UUID 4
Do JSON.$addmember('','logger',logger)
Do JSON.$addmember('','platform',platform)
Do JSON.$addmember('','culprit',culprit)
#Do JSON.$addmember('','release',release)
Do JSON.$addmember('','timestamp',timestamp)
Do JSON.$addmember('','sdk','')
Do JSON.$addmember('','message',pErrorText)
Do JSON.$addmember('','level',pLevel)
Do JSON.$addmember('','tags','')
</pre>

=== HTTP-Kommunikation ===

<code>OSentry.$captureException</code> sendet den erzeugten JSON-Payload an Sentry:

<pre>
#Generate HTTP Auth header
Begin text block
Text:Sentry sentry_version=7,
Text:sentry_timestamp=[$cinst.$getUnixTimestamp()],
Text:sentry_key=[iPubKey],
Text:sentry_client=omnis/1.0
End text block
Get text block auth

#Generate header list
Calculate Host as 'sentry.io'
Calculate Url as con('/api/',iProID,'/store/')
Do HdrList.$define(wert,name)
Do HdrList.$add('User-Agent','omnis/1.0')
Do HdrList.$add('Content-Type','application/json')
Do HdrList.$add('Content-Length',binlength(json))
Do HdrList.$add('X-Sentry-Auth',auth)
</pre>

Anschließend wird der Request über <code>HTTPPost</code>, <code>HTTPSend</code> und <code>HTTPRead</code> ausgeführt.

=== Fehlerbehandlung beim Senden ===

Wenn der Socket nicht geöffnet werden kann:

<pre>
HTTPPost (Host,Url,,HdrList,443,kTrue,kTrue) Returns Socket
If Socket<0
#Error when opening connection -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Error ',Socket,' when performing HTTPPost'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -1
End If
</pre>

Wenn das Senden fehlschlägt:

<pre>
HTTPSend (Socket,json) Returns byteCount
If byteCount<0
# Error while sending data -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Erorr ',byteCount,' when performing HTTPSend'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -2
End If
</pre>

Wenn die Antwort nicht erfolgreich ist:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

=== Lokales Speichern ===

Bei Fehlern wird der JSON Report lokal im Omnis-Installationsordner gespeichert:

<pre>
#Writes the json and the http buffer to a file in the omnis installation folder
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
Do fOP.$writecharacter(kUniTypeUTF8,pJSON) Returns err
If not(isclear(pBuffer))
Do fOP.$writecharacter(kUniTypeUTF8,con(kCr,pBuffer),kTrue) Returns err
End If
Do fOP.$closefile()

Quit method
</pre>

=== Cleanup ===

Nach erfolgreichem Senden werden [[#Tags, Extras und User-Kontext|Tags und Extras]] gelöscht:

<pre>
#Clears all extras and tags => to be used after a sentry request has successfully been sent
Do iTagList.$clear()
Do iExtraList.$clear()
Quit method
</pre>

== Demo Library ==

Die Demo-Library zeigt, wie <code>OSentry</code> initialisiert wird und wie verschiedene [[#Events erfassen|Event-Typen]] aus einer Omnis-Oberfläche heraus an Sentry gesendet werden.

=== Bestandteile ===

{| class="wikitable"
! Klasse !! Zweck
|-
| <code>Startup_Task</code> || Initialisiert Sentry, SQLite und öffnet das Demo-Fenster
|-
| <code>FSY_Demo</code> || Demo-Fenster
|-
| <code>ODummy</code> || Erzeugt Demo-Stack für Exception
|-
| <code>ODatabaseHandler</code> || Erstellt SQLite-Demo-Datenbank
|-
| <code>OSLSession</code> || SQLite Session
|-
| <code>OSentry</code> || Low-Level-Sentry-Adapter
|-
| <code>OSentryHL</code> || High-Level-Sentry-Adapter
|}

=== Startup ===

<code>Startup_Task.$construct</code> initialisiert Sentry, baut eine SQLite Session auf und öffnet das Demo-Fenster. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()

#SQLite Session init
Do $objects.OSLSession.$newref() Returns tOSLSession
#Calculate tOSLSession.$opencreate as kTrue
Calculate workingDir as tODatabaseHandler.$getWorkingDir()
Do con(workingDir,'Sentry_Test.db') Returns dbLocation
Do tOSLSession.$logon(dbLocation,'','','slsession') Returns #F

#Open Test Window
Do $windows.FSY_Demo.$openonce('*')

Quit method
</pre>

=== Demo-Fenster ===

<code>FSY_Demo</code> enthält folgende Bereiche:

* DSN Configuration
* DB Status
* Actions

Wichtige Felder:

{| class="wikitable"
! Feld !! Datenanbindung
|-
| DSN || <code>iDSN</code>
|-
| Host || <code>tSentry.iOSentry.iHost</code>
|-
| Public Key || <code>tSentry.iOSentry.iPubKey</code>
|-
| Project ID || <code>tSentry.iOSentry.iProID</code>
|-
| DB Status || <code>iCurrentDBStatus</code>
|}

[[Datei:Demo-window.png|850px|Demo-Fenster der OSentry Library]]

=== DSN setzen ===

Die DSN wird im Feld <code>iDSN</code> erfasst. Der Button <code>Set DSN</code> ruft anschließend <code>tSentry.$init(iDSN)</code> auf. Nach dem Setzen werden Public Key, Host und Project ID aus der DSN gelesen und in den darunterliegenden Feldern angezeigt.

[[Datei:Demo-dsn.png|850px|DSN-Konfiguration im Demo-Fenster]]

Der Button <code>Set DSN</code> initialisiert Sentry mit der eingegebenen DSN. Quelle: <code>FSY_Demo.setDSN.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$init(iDSN)
Calculate $cclass.$ivardefs.iDSN.$objinitval as con(kSq,iDSN,kSq)

Do $cinst.$showmessage('DSN set and Sentry initialized!','Info')

Do $cinst.$redraw()
Quit method
</pre>

=== DB Status anzeigen ===

<code>FSY_Demo.$displayDBState</code> zeigt, ob die SQLite Session verbunden ist. Quelle: <code>FSY_Demo.$displayDBState</code>.

<pre>
Do tOSLSession.$state Returns dbState
If dbState='kSessionStateLoggedOff'
Calculate iCurrentDBStatus as 'Logged Off'
Else If dbState='kSessionStateLoggedOn'
Calculate iCurrentDBStatus as 'Logged On'
Else
Calculate iCurrentDBStatus as 'Unkown DB State'
End If

Do $cinst.$redraw()
Quit method
</pre>

=== Demo-Datenbank erstellen ===

Der Button <code>Create Database</code> ruft <code>ODatabaseHandler.$DBFirstInit</code> auf. Quelle: <code>FSY_Demo.createDB.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Setup the DB
Do tODatabaseHandler.$DBFirstInit() Returns err
If err=0
Do $cinst.$showmessage('DB successfully created!','Info')
Else
Do $cinst.$showmessage('Error while creating the DB. Make sure that the DB does not already exist.','Info')
End If

Do $cinst.$displayDBState()

Quit method
</pre>

Die Datenbank wird im Arbeitsverzeichnis der Library angelegt. Quelle: <code>ODatabaseHandler.$getWorkingDir</code>.

<pre>
Quit method con(FileOps.$parentdir($clib.$pathname),pathsep())
</pre>

Die Demo-DB enthält unter anderem:

* <code>dperson</code>
* <code>drelease</code>
* <code>dvcs</code>

=== Message auslösen ===

Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Log auslösen ===

Button <code>Trigger a log</code>. Quelle: <code>FSY_Demo.log.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception auslösen ===

Button <code>Trigger an exception</code> bereitet eine Row und eine List vor und ruft anschließend <code>ODummy.$dummyMethod</code> auf. Quelle: <code>FSY_Demo.exception.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do iDummyRow.$define(id,name)
Calculate iDummyRow.id as 22
Calculate iDummyRow.name as 'Tom'

Do iDummyList.$define(id,weekday)
Do iDummyList.$add(1,'Monday')
Do iDummyList.$add(2,'Tuesday')
Do iDummyList.$add(3,'Wednesday')
Do iDummyList.$add(4,'Thursday')
Do iDummyList.$add(5,'Friday')
Do iDummyList.$add(6,'Saturday')
Do iDummyList.$add(7,'Sunday')

Calculate iDummyList.$line as 5

Do iODummy.$dummyMethod('Important Value')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')

Quit method
</pre>

<code>ODummy.$dummyMethod</code> sendet die Exception. Quelle: <code>ODummy.$dummyMethod</code>.

<pre>
#In here is some logic
#This logic would produce an error
#We send all this information to Sentry

Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')

Quit method 0
</pre>

=== Deprecated Call auslösen ===

Button <code>Trigger a deprecated call</code>. Quelle: <code>FSY_Demo.deprecatedCall.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureDeprecatedCall()
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== SQL Exception Button ===

Der Button <code>Trigger an SQLException</code> ist im Export vorhanden, enthält aber noch keinen fertigen Demo-Code. Quelle: <code>FSY_Demo.sqlException.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Für die Dokumentation der SQL-Erfassung siehe [[#Events erfassen|03 Events erfassen]].

== API Reference ==

Diese Seite dokumentiert die produktiv relevanten Methoden von <code>OSentryHL</code> und <code>OSentry</code>.

=== OSentryHL ===

<code>OSentryHL</code> ist die empfohlene Klasse für Applikationscode.

'''<code>$init(pDSN)</code>'''

Initialisiert das interne <code>OSentry</code>-Objekt.

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

'''<code>$captureMessage(pMessage)</code>'''

Sendet eine einfache Info-Message.

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel)</code>'''

Sendet eine generische Exception.

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

'''<code>$captureAnything(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface)</code>'''

Sendet ein frei konfigurierbares Event.

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Hinweis: Der Parameter ist im Export als <code>pStacktraveInterface</code> geschrieben.

'''<code>$captureLog(pErrorText)</code>'''

Sendet ein Log-Event.

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

'''<code>$captureDeprecatedCall()</code>'''

Meldet die Ausführung eines veralteten Codepfads.

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

'''<code>$captureSQLException(pErrorText,pStat)</code>'''

Meldet einen SQL-Fehler mit SQL-Text und nativer Datenbankfehlermeldung.

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag für das nächste Event hinzu.

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra für das nächste Event hinzu.

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

'''<code>$setStatus(pStatus)</code>'''

Aktiviert oder deaktiviert Sentry.

<pre>
#Toggels Sentry on or off
Do iOSentry.$setStatus(pStatus)
Quit method
</pre>

'''<code>$setUser()</code>'''

Setzt im Export feste [[#Demo Library|Demo]]-Userdaten.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode parametrisiert werden.

=== OSentry ===

<code>OSentry</code> ist die Low-Level-Klasse für Payload-Erzeugung und Versand.

'''<code>$init(pDSN)</code>'''

Parst die DSN in Protokoll, Public Key, Host und Project ID.

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraceInterface,pUserInterface,pExceptionInterface)</code>'''

Erzeugt JSON, sendet es an Sentry und behandelt Fehlerfälle.

Parameter:

{| class="wikitable"
! Parameter !! Default !! Bedeutung
|-
| <code>pErrorText</code> || || Message
|-
| <code>pErrorCode</code> || || Fehlercode
|-
| <code>pExcType</code> || || Exception-Typ
|-
| <code>pLevel</code> || || <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code>, <code>debug</code>
|-
| <code>pStacktraceInterface</code> || <code>kTrue</code> || [[#Stacktrace und Kontext|Stacktrace]] senden
|-
| <code>pUserInterface</code> || <code>kTrue</code> || [[#Tags, Extras und User-Kontext|User-Kontext]] senden
|-
| <code>pExceptionInterface</code> || <code>kTrue</code> || Exception Interface senden
|}

'''<code>$generateJson(...)</code>'''

Erzeugt den Sentry JSON Payload als Binary.

'''<code>$generateStacktraceInterface(pCulprit)</code>'''

Erzeugt den Omnis-[[#Stacktrace und Kontext|Stacktrace]] inklusive Variablen und Kontextzeilen.

'''<code>$generateExceptionInterface(pType,pValue)</code>'''

Erzeugt das Sentry Exception Interface.

<pre>
# Generate Row to store in the JSON
Do exceptionRow.$define(type,value,stacktrace)
Calculate exceptionRow.type as pType
Calculate exceptionRow.value as pValue
Calculate exceptionRow.stacktrace as 'sentry.interfaces.stacktrace' ## Tells the exception interface that a stacktrace is passed aswell
</pre>

'''<code>$generateUserInterface()</code>'''

Erzeugt den [[#Tags, Extras und User-Kontext|User-Kontext]].

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag zur internen Tag-Liste hinzu.

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra zur internen Extra-Liste hinzu.

'''<code>$clearList()</code>'''

Leert [[#Tags, Extras und User-Kontext|Tags und Extras]] nach einem Request.

'''<code>$setUserData(pID,pName,pEmail)</code>'''

Setzt Userdaten für den nächsten Request.

'''<code>$setProxy(pProxyHost,pProxyPort)</code>'''

Setzt Proxy-Informationen.

'''<code>$setStatus(pStatus)</code>'''

Setzt den Sentry-Status.

<pre>
#Toggels Sentry Reports on or off
Calculate iStatus as pStatus
Quit method
</pre>

'''<code>$writeJSON(pJSON,pBuffer)</code>'''

Schreibt fehlgeschlagene Reports lokal in eine Datei.

'''<code>$getUnixTimestamp()</code>'''

Gibt den aktuellen UNIX Timestamp zurück.

'''<code>$generateUUID()</code>'''

Erzeugt eine UUID für die Sentry Event ID.

<pre>
#Genereates a UUID for the issue id
Quit method OW3.$makeuuid(kFalse)
</pre>

== Troubleshooting ==

=== Es erscheinen keine Events in Sentry ===

Prüfe zuerst, ob Sentry aktiv ist:

<pre>
Do tSentry.$setStatus(1)
</pre>

<code>OSentry.$captureException</code> beendet sich sofort, wenn der Status <code>0</code> oder leer ist:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

=== Die DSN ist falsch ===

Prüfe, ob die DSN korrekt aus Sentry kopiert wurde. <code>OSentry.$init</code> erwartet eine DSN, aus der Public Key, Host und Project ID gelesen werden können.

Nach dem Setzen der DSN sollten in der [[#Demo Library|Demo-Library]] folgende Felder gefüllt sein:

* Host
* Public Key
* Project ID

=== Netzwerk oder Proxy blockiert den Request ===

Wenn die Anwendung keinen direkten Zugriff auf Sentry hat, setze einen Proxy:

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Intern wird der Proxy vor dem HTTP Request gesetzt:

<pre>
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Report wird lokal gespeichert ===

Wenn <code>HTTPPost</code>, <code>HTTPSend</code> oder <code>HTTPRead</code> fehlschlägt, speichert OSentry den Report lokal:

<pre>
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
</pre>

Suche im Omnis-Installationsordner nach Dateien mit dem Namen:

<pre>
Sentryreport_<timestamp>.json
</pre>

=== Sentry antwortet nicht mit 200 OK ===

Wenn die HTTP-Antwort kein <code>200 OK</code> enthält, wird der JSON Report ebenfalls lokal gespeichert:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

Mögliche Ursachen:

* falsche Project ID
* falscher Public Key
* ungültige DSN
* JSON Payload wird von Sentry abgelehnt
* Netzwerk-Gateway verändert den Request

=== Tags oder Extras erscheinen beim falschen Event ===

[[#Tags, Extras und User-Kontext|Tags und Extras]] werden für den nächsten Request gesammelt. Nach erfolgreichem Request werden sie gelöscht:

<pre>
Do iTagList.$clear()
Do iExtraList.$clear()
</pre>

Wenn ein Request fehlschlägt, wird ebenfalls aufgeräumt:

<pre>
Do $cinst.$clearList()
</pre>

Prüfe trotzdem, ob in eigenen Wrapper-Methoden Tags und Extras direkt vor dem passenden Capture-Aufruf gesetzt werden.

=== User-Kontext zeigt Demo-Daten ===

<code>OSentryHL.$setUser</code> verwendet im Export feste Testdaten:

<pre>
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
</pre>

Für produktive Nutzung sollte die Methode parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
</pre>

=== SQL Exception Demo-Button funktioniert nicht ===

Der Button <code>Trigger an SQLException</code> ist im Export noch nicht implementiert:

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Die produktive Methode für SQL-Fehler ist aber vorhanden. Siehe auch [[#Events erfassen|Events erfassen]].

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

=== Zu viele Events ===

Sentry kann sehr schnell viele Events sammeln. Verwende für produktive Systeme:

* klare Wrapper-Methoden in <code>OSentryHL</code>
* sinnvolle Levels
* gezielte [[#Tags, Extras und User-Kontext|Tags]]
* keine Events in sehr häufigen Schleifen
* keine rein informativen Debug-Events ohne Nutzen

=== Sensible Daten ===

[[#Stacktrace und Kontext|Stacktrace]], Parameter, Instance Variablen, SQL-Text und [[#Tags, Extras und User-Kontext|Extras]] können sensible Daten enthalten. Prüfe vor produktiver Nutzung:

* Welche Variablen werden übertragen?
* Enthalten SQL-Statements personenbezogene Daten?
* Werden Tokens oder Passwörter in Extras geschrieben?
* Sollen bestimmte Werte maskiert werden?

Sentry

2026-06-12T14:08:18Z

Silvan: /* DSN setzen */

__TOC__

== Überblick ==

OSentry ist ein REST-API-Konnektor von Omnis Studio zu Sentry. Der Konnektor sendet Fehler, Messages, Logs und Laufzeitkontext aus Omnis-Anwendungen an Sentry, damit Probleme in produktiven Systemen sichtbar, gruppierbar und analysierbar werden.

Diese Dokumentation beschreibt die [[#Installation|Installation]], die Nutzung in bestehenden Omnis-Anwendungen, die Definition eigener standardisierter Exception-Typen, die interne Struktur und die [[#Demo Library|Demo-Library]].

=== Kernidee ===

OSentry besteht aus zwei produktiv relevanten Klassen:

* <code>OSentryHL</code>: High-Level-Adapter für die Anwendung. Diese Klasse sollte von normalem Applikationscode aufgerufen werden.
* <code>OSentry</code>: Low-Level-Adapter für DSN-Parsing, JSON-Erzeugung, [[#Stacktrace und Kontext|Stacktrace]]-Aufbereitung und HTTP-Kommunikation mit Sentry.

Die Anwendung arbeitet im Normalfall mit <code>OSentryHL</code>. Dadurch bleiben Sentry-spezifische Details zentral gekapselt und neue standardisierte Exception-Typen können als eigene Methoden in <code>OSentryHL</code> definiert werden.

=== Hauptfeatures ===

* Direkte Anbindung von Omnis Studio an Sentry über REST API und DSN
* Erfassen von Exceptions, Messages, Logs und SQL-Fehlern
* Unterstützung der Sentry-Level <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code> und <code>debug</code>
* Automatische Omnis-Kontextinformationen
* Omnis-[[#Stacktrace und Kontext|Stacktrace]] mit Klassen, Methoden, Zeilen und Variablen
* [[#Tags, Extras und User-Kontext|Tags]] für Filterung und Gruppierung
* [[#Tags, Extras und User-Kontext|Extras]] für zusätzliche Diagnoseinformationen
* Optionaler [[#Tags, Extras und User-Kontext|User-Kontext]]
* Proxy-Unterstützung
* Aktivieren und Deaktivieren der Sentry-Übertragung
* Lokales Speichern von Reports bei Übertragungsfehlern

=== Weiterführende Links ===

* [https://sentry.io/welcome/ Sentry Website]
* [https://sentry.io/signup/ Sentry Account erstellen]
* [https://develop.sentry.dev/self-hosted/ Sentry self-hosted]

== Installation ==

Diese Seite beschreibt, wie OSentry in eine bestehende Omnis-Anwendung integriert wird.

=== Voraussetzungen ===

* Omnis Studio Anwendung
* Sentry Account oder self-hosted Sentry Installation
* Ein Sentry-Projekt mit SDK-Typ <code>Other</code>
* Die DSN des Sentry-Projekts
* Netzwerkzugriff auf Sentry

Die exportierte [[#Demo Library|Demo-Library]] wurde mit Omnis <code>11.1</code> erstellt.

=== Sentry-Projekt erstellen ===

# In Sentry ein neues Projekt erstellen.
# Als SDK <code>Other</code> auswählen.
# Die DSN des Projekts kopieren.

Die DSN wird beim Initialisieren verwendet. <code>OSentry</code> zerlegt sie intern in Public Key, Host und Project ID.

[[Datei:Sentry-projects.png|900px|Sentry Projektübersicht]]

=== Klassen kopieren ===

Kopiere die folgenden Klassen in deine bestehende Omnis-Library:

* <code>OSentry</code>
* <code>OSentryHL</code>

Die Demo-spezifischen Klassen sind für die produktive Integration nicht erforderlich. Damit sind die übrigen Klassen der Demo-Library gemeint, zum Beispiel <code>FSY_Demo</code>, <code>ODummy</code>, <code>ODatabaseHandler</code> und <code>OSLSession</code>. Diese Klassen dienen nur dazu, die [[#Demo Library|Demo-Library]] mit Fenster, SQLite-Testdaten und Beispielaufrufen auszuführen.

=== Task Variable anlegen ===

Lege in deiner Startup Task eine Task Variable an:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' <code>tSentry</code> sollte als global erreichbarer Singleton der Anwendung verwendet werden. In Omnis ist dafür eine Task Variable sinnvoll, weil sie von Fenstern, Objektklassen und zentralen Error-Handlern aus konsistent erreichbar ist. Dadurch gibt es genau eine aktive Sentry-Konfiguration mit einer DSN, einem Status, optionalen Proxy-Daten und gemeinsamen Wrapper-Methoden in <code>OSentryHL</code>.</div>

Im [[#Demo Library|Demo-Projekt]] ist diese Variable in <code>Startup_Task</code> definiert.

=== Initialisierung im Startup Task ===

Initialisiere <code>tSentry</code> beim Start deiner Anwendung mit der DSN deines Sentry-Projekts:

<pre>
Do tSentry.$init('<DSN>')
</pre>

Die [[#Demo Library|Demo-Library]] ruft im Startup Task ebenfalls die Initialisierung auf. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()
</pre>

In einer produktiven Anwendung sollte die DSN explizit oder aus einer Konfiguration übergeben werden:

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Speichere die DSN in einer Datenbank, einer Konfigurationstabelle oder einem Config File. So kann sie pro Kunde, Umgebung oder Installation geändert werden, ohne die Library neu auszuliefern.</div>

=== Testcall ===

Nach der Initialisierung kann ein erstes Testevent gesendet werden:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Wenn alles korrekt eingerichtet ist, erscheint das Event im Sentry-Projekt.

=== Proxy konfigurieren ===

Falls die Anwendung in einem geschützten Netzwerk läuft, kann ein Proxy gesetzt werden. Die Methode befindet sich im Low-Level-Objekt <code>OSentry</code>.

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Die interne Implementierung setzt den Proxy vor dem HTTP-Request:

<pre>
#Configure proxy; needed when sending data out of secured networks
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Sentry aktivieren oder deaktivieren ===

OSentry kann zentral ein- oder ausgeschaltet werden.

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Deaktiviere Sentry in der Entwicklungs-Version standardmäßig oder verwende eine separate Entwicklungs-DSN. So landen lokale Tests, Debug-Fehler und absichtlich ausgelöste Exceptions nicht im produktiven Sentry-Projekt.</div>

<pre>
Do tSentry.$setStatus(1) ## aktiv
Do tSentry.$setStatus(0) ## inaktiv
</pre>

Im Low-Level-Objekt <code>OSentry</code> wird vor dem Senden geprüft:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

== Quickstart ==

Diese Seite zeigt die minimale Integration in eine bestehende Omnis-Anwendung.

=== Klassen übernehmen ===

Kopiere <code>OSentry</code> und <code>OSentryHL</code> in deine Library.

=== Task Variable erstellen ===

In der Startup Task:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

=== Sentry initialisieren ===

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<code>OSentryHL.$init</code> delegiert an das Low-Level-Objekt <code>OSentry</code>:

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

=== Message senden ===

<pre>
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
</pre>

Die [[#Demo Library|Demo-Library]] verwendet genau diesen Aufruf im Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception senden ===

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

=== In Sentry prüfen ===

In Sentry sollte anschließend ein neues Event sichtbar sein. Je nach Event-Typ enthält es:

* Message
* Level
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Tags, Extras und User-Kontext|User-Kontext]]
* [[#Stacktrace und Kontext|Stacktrace]]
* Omnis-Kontextinformationen

== Events erfassen ==

OSentryHL ist die empfohlene Einstiegsschicht für Applikationscode. Die Klasse bietet sprechende Methoden für typische Event-Arten und ruft intern <code>OSentry.$captureException</code> auf.

=== Message ===

Eine einfache Information wird mit <code>$captureMessage</code> gesendet:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

Verhalten:

* Level: <code>info</code>
* Kein [[#Stacktrace und Kontext|Stacktrace]]
* Kein [[#Tags, Extras und User-Kontext|User Interface]]
* Geeignet für einfache Statusmeldungen oder technische Hinweise

=== Log ===

Ein Log-Event wird mit <code>$captureLog</code> gesendet:

<pre>
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

Verhalten:

* Level: <code>warning</code>
* [[#Stacktrace und Kontext|Stacktrace]] aktiv
* Exception Interface in diesem Wrapper deaktiviert
* [[#Tags, Extras und User-Kontext|User Interface]] aktiv

=== Generische Exception ===

Eine generische Exception wird mit <code>$captureException</code> gesendet:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

Parameter:

{| class="wikitable"
! Parameter !! Bedeutung
|-
| <code>pErrorText</code> || Text, der in Sentry als Message sichtbar ist
|-
| <code>pErrorCode</code> || Fehlercode oder fachlicher Code
|-
| <code>pExcType</code> || Exception-Typ für Benennung und Gruppierung
|-
| <code>pLevel</code> || Sentry-Level
|}

Gültige Levels:

* <code>fatal</code>
* <code>error</code>
* <code>warning</code>
* <code>info</code>
* <code>debug</code>

=== SQL Exception ===

SQL-Fehler können mit <code>$captureSQLException</code> gemeldet werden.

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

Verhalten:

* Fügt die Datenbank als [[#Tags, Extras und User-Kontext|Tag]] hinzu
* Fügt SQL-Text als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Fügt native Datenbankfehlermeldung als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Sendet das Event als <code>SQL-Exception</code> mit Level <code>error</code>

=== Deprecated Call ===

Veraltete Codepfade können gezielt gemeldet werden:

<pre>
Do tSentry.$captureDeprecatedCall()
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

Dieser Wrapper eignet sich, um zu erkennen, ob alter Code in produktiven Systemen noch ausgeführt wird.

=== Frei konfigurierbares Event ===

Für Sonderfälle gibt es <code>$captureAnything</code>:

<pre>
Do tSentry.$captureAnything('Text',1001,'Custom Type','error',kTrue,kTrue,kTrue)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Diese Methode bietet maximale Flexibilität. Für wiederkehrende Exception-Typen sollte aber eine eigene Methode in <code>OSentryHL</code> angelegt werden. Siehe [[#Eigene Exceptions standardisieren|04 Eigene Exceptions standardisieren]].

== Eigene Exceptions standardisieren ==

Wenn ein Exception-Typ mehrfach in der Anwendung vorkommt, sollte er nicht überall manuell mit <code>$captureException</code> aufgebaut werden. Besser ist eine eigene Methode in <code>OSentryHL</code>.

Dadurch entsteht eine zentrale, wiederverwendbare Definition für:

* Exception-Typ
* Sentry-Level
* Fehlercode
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Stacktrace und Kontext|Stacktrace]]/[[#Tags, Extras und User-Kontext|User]]/Exception Interface

Die automatisch gesetzten [[#Tags, Extras und User-Kontext|Tags und Extras]] aus <code>OSentry.$generateJson</code> müssen in solchen Wrappern nicht erneut ergänzt werden. Eigene Exception-Methoden setzen nur zusätzliche Werte, die für diesen standardisierten Exception-Typ relevant sind.

=== Warum über OSentryHL? ===

<code>OSentryHL</code> ist die Abstraktionsschicht für Applikationscode. Sie kapselt die Details von <code>OSentry</code> und sorgt dafür, dass Aufrufe in der Anwendung kurz und konsistent bleiben.

Bestehende Beispiele aus <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

=== Empfohlenes Muster ===

Für jeden standardisierten Exception-Typ wird eine eigene Methode in <code>OSentryHL</code> erstellt.

Beispiel:

<pre>
# Captures a validation exception
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addExtra('Field',pField)
Do $cinst.$addExtra('Invalid Value',pValue)

Do iOSentry.$captureException(pErrorText,2001,'Validation-Exception','warning',1,1,1) Returns code

Quit method code
</pre>

Mögliche Parameter der neuen Methode:

{| class="wikitable"
! Parameter !! Beispiel !! Zweck
|-
| <code>pErrorText</code> || <code>'Invalid customer number'</code> || Sentry Message
|-
| <code>pModule</code> || <code>'Customer'</code> || Filterbarer Tag
|-
| <code>pField</code> || <code>'cu_number'</code> || Diagnoseinformation
|-
| <code>pValue</code> || <code>'ABC'</code> || Diagnoseinformation
|}

Der Applikationscode bleibt dadurch einfach:

<pre>
Do tSentry.$captureValidationException('Invalid customer number','Customer','cu_number',cu_number)
</pre>

=== Beispiel: Business Rule Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures a business rule violation
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do $cinst.$addExtra('Details',pDetails)

Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureBusinessRuleViolation('Invoice cannot be posted','Invoice','PostingAllowed','Invoice is missing customer')
</pre>

=== Beispiel: Integration Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures an integration exception
Do $cinst.$addTag('Integration',pSystem)
Do $cinst.$addTag('Endpoint',pEndpoint)
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)

Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureIntegrationException('External API request failed','ERP','/api/customer',jsonPayload,responseText)
</pre>

=== Namenskonventionen ===

Empfehlung für neue Methoden:

* Methodenname beginnt mit <code>$capture</code>
* Der fachliche Typ steht im Methodennamen
* Der Sentry Exception Type ist stabil und ändert sich nicht laufend
* [[#Tags, Extras und User-Kontext|Tags]] sind kurz und filterbar
* [[#Tags, Extras und User-Kontext|Extras]] dürfen länger sein und Diagnoseinformationen enthalten

Beispiele:

* <code>$captureValidationException</code>
* <code>$captureBusinessRuleViolation</code>
* <code>$captureIntegrationException</code>
* <code>$capturePermissionViolation</code>
* <code>$captureConfigurationError</code>

=== Error Codes ===

Verwende feste Fehlercodes für standardisierte Exception-Typen. Dadurch können Events in Sentry besser gefiltert und wiedererkannt werden.

Beispiel:

{| class="wikitable"
! Code !! Exception Type
|-
| <code>2001</code> || <code>Validation-Exception</code>
|-
| <code>3001</code> || <code>Business-Rule-Violation</code>
|-
| <code>4001</code> || <code>Integration-Exception</code>
|-
| <code>5001</code> || <code>Configuration-Error</code>
|}

=== Wann nicht standardisieren? ===

Nicht jeder Einzelfall braucht eine eigene Methode. Für einmalige technische Tests oder sehr spezielle Fälle reicht:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Sobald ein Exception-Typ aber mehrfach vorkommt oder fachlich relevant ist, sollte er als eigene Methode in <code>OSentryHL</code> definiert werden.

== Tags, Extras und User-Kontext ==

Tags, Extras und User-Kontext reichern Sentry-Events mit zusätzlichen Informationen an. Diese Informationen helfen beim Filtern, Gruppieren und Analysieren.

[[Datei:Sentry-tags.png|900px|Sentry Tags und User-Kontext]]

=== Tags ===

Tags sind kurze, filterbare Werte.

Beispiele:

* Datenbank
* Kunde
* Modul
* Umgebung
* Error Code
* Omnis-Version

Methode in <code>OSentryHL</code>:

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds a tag to the next request processed
Do iTagList.$add(pName,pValue)
Quit method
</pre>

Beispiel:

<pre>
Do tSentry.$addTag('Module','Invoice')
Do tSentry.$addTag('Customer','10001')
Do tSentry.$captureException('Invoice posting failed',3001,'Business-Rule-Violation','warning')
</pre>

=== Extras ===

Extras sind Detailinformationen, die nicht primär zum Filtern gedacht sind.

Beispiele:

* SQL-Text
* Native Datenbankfehlermeldung
* Payload
* Response Body
* interne IDs
* zusätzliche Debug-Informationen

Methode in <code>OSentryHL</code>:

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds extra information to the next request being processed
Do iExtraList.$add(pName,pValue)
Quit method
</pre>

Beispiel aus der SQL Exception:

<pre>
Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)
</pre>

=== Automatische Tags ===

Die folgenden Tags werden bei jedem Event automatisch von <code>OSentry.$generateJson</code> ergänzt. Sie müssen bei eigenen Exceptions nicht erneut gesetzt werden. Eigene Wrapper-Methoden in <code>OSentryHL</code> sollten nur zusätzliche, fachlich oder technisch relevante Tags hinzufügen.

<code>OSentry.$generateJson</code> fügt mehrere Tags automatisch hinzu:

<pre>
# Add static tags
Do iTagList.$add('Omnisversion',sys(1))
Calculate systemversionRow as systemversion()
Do iTagList.$add('Plattform',con(sys(8),pick(systemversionRow.server,'',' SRV')))
Do iTagList.$add('OS Version',con(systemversionRow.major,'.',systemversionRow.minor,'.',systemversionRow.build))
Do iTagList.$add('error_code',pErrorCode)
</pre>

Automatisch gesendete Tags:

{| class="wikitable"
! Tag !! Herkunft !! Zweck
|-
| <code>Omnisversion</code> || <code>sys(1)</code> || Zeigt, mit welcher Omnis-Version das Event erzeugt wurde
|-
| <code>Plattform</code> || <code>sys(8)</code> und Server-Flag aus <code>systemversion()</code> || Unterscheidet Plattform und Server Runtime
|-
| <code>OS Version</code> || <code>systemversionRow.major/minor/build</code> || Zeigt die Betriebssystemversion
|-
| <code>error_code</code> || Parameter <code>pErrorCode</code> || Verbindet das Event mit dem übergebenen Fehlercode
|}

Beispiel für eine eigene Exception: Der Wrapper muss nicht erneut <code>Omnisversion</code> oder <code>OS Version</code> setzen. Er ergänzt nur das, was für diesen Exception-Typ zusätzlich hilfreich ist.

<pre>
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code
</pre>

=== Automatische Extras ===

Auch die folgenden Extras werden bei jedem Event automatisch ergänzt. Bei eigenen Exceptions müssen nur zusätzliche Extras gesetzt werden, zum Beispiel ein SQL-Statement, ein Payload oder fachliche Zusatzdaten.

<code>OSentry.$generateJson</code> fügt offene Fenster, offene Reports und die aktuelle Printfile hinzu:

<pre>
# Static extra 1: All open windows
Do $root.$iwindows.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate windows as con(windows,', ',nameList.[i].1)
End For
Calculate windows as right(windows,len(windows)-2)
Do iExtraList.$add('Open Windows',windows)

# Static extra 2: All open reports
Do $root.$ireports.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate reports as con(reports,', ',nameList.[i].1)
End For
Calculate reports as right(reports,len(reports)-2)
Do iExtraList.$add('Open Reports',reports)
Do iExtraList.$add('Current Printfile',$root.$prefs.$printfile)
</pre>

Automatisch gesendete Extras:

{| class="wikitable"
! Extra !! Herkunft !! Zweck
|-
| <code>Open Windows</code> || <code>$root.$iwindows.$makelist($ref.$name)</code> || Zeigt, welche Fenster im Moment des Events offen waren
|-
| <code>Open Reports</code> || <code>$root.$ireports.$makelist($ref.$name)</code> || Zeigt, welche Reports im Moment des Events offen waren
|-
| <code>Current Printfile</code> || <code>$root.$prefs.$printfile</code> || Zeigt die aktuell gesetzte Printfile
|}

Beispiel für zusätzliche Extras in einem eigenen Wrapper:

<pre>
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)
Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code
</pre>

=== User-Kontext ===

Der User-Kontext ordnet ein Event einem betroffenen Benutzer zu. In Sentry erscheint dadurch ein eigener User-Bereich, und Events können nach Benutzer gefiltert oder gruppiert werden. Das ist besonders hilfreich, wenn ein Fehler nur bei einzelnen Kunden, Arbeitsplätzen oder Benutzerkonten auftritt.

<code>OSentry</code> unterstützt drei User-Felder:

{| class="wikitable"
! Feld !! Bedeutung
|-
| <code>id</code> || stabile interne Benutzer-ID oder Kundennummer
|-
| <code>username</code> || lesbarer Benutzername
|-
| <code>email</code> || E-Mail-Adresse, falls sie übertragen werden darf
|}

Der User-Kontext wird nur in das Event geschrieben, wenn das User Interface beim Capture-Aufruf aktiviert ist. Die Standardmethode <code>OSentry.$captureException</code> hat <code>pUserInterface</code> standardmäßig auf <code>kTrue</code>. Einzelne High-Level-Methoden können das bewusst deaktivieren, zum Beispiel <code>$captureMessage</code>.

<code>OSentry</code> kann User-Daten an das Event anhängen:

<pre>
#Sets userinformation for the next request being processed
Calculate iUserID as pID
Calculate iUserName as pName
Calculate iUserEmail as pEmail
Quit method
</pre>

Das User Interface wird so generiert:

<pre>
# Create user data row
Do UserdataRow.$define(id,email,username)

Calculate UserdataRow.id as iUserID
Calculate UserdataRow.email as iUserEmail
Calculate UserdataRow.username as iUserName

Do JSON.$addmember('','user','')
Do JSON.$setobject('user',UserdataRow)

Calculate jsonString as OJSON.$formatjson(JSON.$getjson())

Quit method jsonString
</pre>

Die aktuelle Demo-Methode in <code>OSentryHL</code> verwendet feste Testdaten. Quelle: <code>OSentryHL.$setUser</code>.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode angepasst und parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
Quit method
</pre>

Empfohlen ist, den User nach Login oder beim Wechsel des aktiven Benutzers zentral zu setzen. Bei anonymen oder sensiblen Installationen kann statt Name und E-Mail auch nur eine interne ID oder ein pseudonymisierter Wert verwendet werden.

=== Datenschutz ===

<div style="border-left:4px solid #72777d; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Datenschutz:''' Prüfe vor produktiver Nutzung, welche Daten an Sentry gesendet werden. Besonders kritisch sind personenbezogene Daten, SQL-Statements, Zugangsdaten, Tokens und interne Pfade.</div>

Besonders kritisch sind:

* personenbezogene Daten
* Kundendaten
* SQL-Statements mit Werten
* Zugangsdaten
* Tokens
* interne Pfade

Tags und Extras sollten so gestaltet werden, dass sie für die Fehleranalyse hilfreich sind, aber keine unnötigen sensiblen Daten übertragen.

== Stacktrace und Kontext ==

<code>OSentry</code> erzeugt einen Omnis-spezifischen Stacktrace und übergibt ihn an Sentry. Dadurch sieht man in Sentry nicht nur eine Fehlermeldung, sondern auch Klassen, Methoden, Zeilen und Variablenkontext. Ergänzende Informationen zu [[#Tags, Extras und User-Kontext|Tags, Extras und User-Kontext]] stehen auf der separaten Kontext-Seite.

[[Datei:Sentry-stack.png|900px|Sentry Stacktrace mit Omnis-Kontext]]

=== Stack lesen ===

<code>OSentry.$generateStacktraceInterface</code> verwendet <code>sys(192)</code>, um den aktuellen Omnis-Stack zu lesen:

<pre>
# Clean up the Stacklist (remove OSentry classes from the stack)
Do sys(192) Returns sys192List
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
If pos('OSentry',class.$name)>0|pos('OSentryHL',class.$name)>0
Do sys192List.[sys192List.$line].$selected.$assign(kTrue)
End If
End For
Do sys192List.$remove(kListDeleteSelected)
</pre>

Interne Frames von <code>OSentry</code> und <code>OSentryHL</code> werden entfernt, damit in Sentry die fachlich relevanten Stellen sichtbar bleiben.

=== SQL-Error Frames entfernen ===

Bestimmte interne SQL-Fehlerframes werden ebenfalls entfernt:

<pre>
# Remove some other classes which we do not want to display
If sys192List.1.method='$sqlerror'
Do sys192List.$remove(1)
Else If sys192List.1.method='$statementerror'
Do sys192List.$remove(1)
End If
</pre>

=== Frames erzeugen ===

Für jeden Stack-Eintrag werden Funktion, Zeilennummer und Kontextzeile erzeugt:

<pre>
#Loop through every item on the omnis stack
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
Calculate className as class.$name

# Create the content row
Do contentRow.$define(vars,function,pre_context,context_line,lineno,filename,post_context)
Calculate contentRow.lineno as sys192List.line
Calculate contentRow.filename as testFileName
Calculate contentRow.context_line as sys192List.linetext
If isclear(sys192List.object)
Calculate contentRow.function as con(className,'.',sys192List.method) ## If it's a class method
Else
Calculate contentRow.function as con(className,'.',sys192List.object,'.',sys192List.method) ## If it's a method of an object of a class (e.g. Headedlist)
End If
Do contentList.$add(contentRow)
End For
</pre>

=== Variablen aufnehmen ===

Pro Stackframe werden Instance Variablen und Parameter gesammelt:

<pre>
# Get all iVars
Do varList.$define(name,value)
Set reference class to sys192List.inst
Do $cinst.$getVars('ivars',class) Returns varList

# Get all params
Calculate paramList as sys192List.params
For paramList.$line from 1 to paramList.$linecount step 1
If not(paramList.value='(Not empty)')
Do varList.$add(paramList.name,paramList.value)
Else
Do varList.$add(paramList.name,'(Not empty)')
End If
End For
</pre>

=== Pre- und Post-Context ===

OSentry fügt Methodenzeilen vor und nach der aktuellen Zeile hinzu:

<pre>
# Pre Context (all method lines before the error occured)
Set reference method to sys192List.methoditem
Do precontextList.$define(line)
For i from 1 to sys192List.line-1 step 1
Do precontextList.$add(method.$methodlines.[i].$text)
End For

# Post Context (all method lines after the error occured
Do postcontextList.$define(line)
For i from sys192List.line+1 to method.$methodlines.$count step 1
Do postcontextList.$add(method.$methodlines.[i].$text)
End For
</pre>

=== Variablentypen ===

<code>OSentry.$getVars</code> unterstützt Basisvariablen, Rows und Lists.

Basisvariablen:

<pre>
If varType='char'|varType='boolean'|varType='integer'|varType='number'|varType='date'
Calculate varContent as pItemRef.$[pVarType].[varName]
Do varList.$add(varName,varContent)
</pre>

Rows:

<pre>
Else If varType='row'
Calculate varRow as pItemRef.$[pVarType].[varName]
If varRow.$colcount=0
Do varList.$add(varName,'(Empty)')
Else
For Z2 from 1 to varRow.$colcount step 1
Calculate varContent as con(varContent,varRow.$cols.[Z2].$name,': ',varRow.[Z2],', ')
End For
Do varList.$add(varName,varContent)
</pre>

Lists:

<pre>
Else If varType='list'
Calculate varListType as pItemRef.$[pVarType].[varName]
Calculate varContent as con('Colcount: ',varListType.$colcount,', ','Linecount: ',varListType.$linecount,', ','Current Line: ',varListType.$line)
If varListType.$linecount=0&varListType.$line=0&varListType.$colcount=0
Do varList.$add(varName,'(Empty)')
Calculate varContent as ''
Else
For Z3 from 1 to varListType.$colcount step 1
Calculate colName as varListType.$cols.[Z3].$name
Calculate varContent as con(varContent,' ',colName,': ',varListType.[colName])
End For
Do varList.$add(varName,varContent)
Calculate varContent as ''
End If
End If
</pre>

=== Hinweise ===

Stacktrace und Variablenkontext sind sehr hilfreich, können aber sensible Daten enthalten. Vor produktiver Nutzung sollte geprüft werden, ob bestimmte Variablen anonymisiert oder ausgeschlossen werden müssen.

== Interne Architektur ==

Diese Seite beschreibt die produktiv relevanten Klassen <code>OSentryHL</code> und <code>OSentry</code>.

=== Klassenübersicht ===

{| class="wikitable"
! Klasse !! Rolle
|-
| <code>OSentryHL</code> || High-Level-Adapter für Applikationscode
|-
| <code>OSentry</code> || Low-Level-Adapter für JSON, [[#Stacktrace und Kontext|Stacktrace]] und HTTP
|-
| <code>Startup_Task</code> || [[#Demo Library|Demo]]-Startup und Beispiel für Initialisierung
|-
| <code>FSY_Demo</code> || [[#Demo Library|Demo]]-Fenster
|-
| <code>ODummy</code> || [[#Demo Library|Demo]]-Code für [[#Stacktrace und Kontext|Stacktrace]]-Beispiel
|-
| <code>ODatabaseHandler</code> || [[#Demo Library|Demo]]-DB Initialisierung
|-
| <code>OSLSession</code> || SQLite Session für [[#Demo Library|Demo]]
|}

=== Empfohlener Aufrufweg ===

Applikationscode sollte <code>OSentryHL</code> verwenden:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

<code>OSentryHL</code> delegiert anschließend an <code>OSentry</code>:

<pre>
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code
</pre>

=== Ablauf eines Events ===

# Applikationscode ruft Methode in <code>OSentryHL</code> auf.
# <code>OSentryHL</code> fügt bei Bedarf [[#Tags, Extras und User-Kontext|Tags und Extras]] hinzu.
# <code>OSentryHL</code> ruft <code>iOSentry.$captureException(...)</code> auf.
# <code>OSentry</code> prüft, ob Sentry aktiv ist.
# <code>OSentry</code> erzeugt JSON.
# [[#Stacktrace und Kontext|Stacktrace]], Exception Interface und [[#Tags, Extras und User-Kontext|User Interface]] werden optional ergänzt.
# HTTP Header und Sentry Auth Header werden erstellt.
# JSON wird per HTTPS an Sentry gesendet.
# Bei Erfolg werden [[#Tags, Extras und User-Kontext|Tags und Extras]] geleert.
# Bei Fehler wird der JSON Report lokal gespeichert.

=== DSN Parsing ===

<code>OSentry.$init</code> zerlegt die DSN:

<pre>
# Parse the DSN into Public Key, Host and Project ID
If len(pDSN)>5
Calculate iDSN as pDSN
Calculate part1 as strtok('iDSN','@')
Calculate iProtocol as strtok('part1','/')
Calculate iProtocol as left(iProtocol,len(iProtocol)-1)
Do strtok('part1','/')
Calculate iPubKey as strtok('part1',':')

Calculate iHost as strtok('iDSN','/')
Calculate iProID as iDSN

#Save the values for the next startup
Calculate $cclass.$ivardefs.iPubKey.$objinitval as con('"',iPubKey,'"')
Calculate $cclass.$ivardefs.iHost.$objinitval as con('"',iHost,'"')
Calculate $cclass.$ivardefs.iProID.$objinitval as con('"',iProID,'"')
End If

Quit method
</pre>

=== JSON-Erzeugung ===

<code>OSentry.$generateJson</code> ist die zentrale Methode für den Payload. Sie setzt unter anderem:

* <code>event_id</code>
* <code>logger</code>
* <code>platform</code>
* <code>culprit</code>
* <code>timestamp</code>
* <code>sdk</code>
* <code>message</code>
* <code>level</code>
* <code>tags</code>
* <code>extra</code>
* optional <code>user</code>
* optional <code>exception</code>
* optional <code>stacktrace</code>

Auszug:

<pre>
# Add all required fields (those are required from the API)
Do JSON.$addmember('','event_id',$cinst.$generateUUID()) ## auto generated UUID 4
Do JSON.$addmember('','logger',logger)
Do JSON.$addmember('','platform',platform)
Do JSON.$addmember('','culprit',culprit)
#Do JSON.$addmember('','release',release)
Do JSON.$addmember('','timestamp',timestamp)
Do JSON.$addmember('','sdk','')
Do JSON.$addmember('','message',pErrorText)
Do JSON.$addmember('','level',pLevel)
Do JSON.$addmember('','tags','')
</pre>

=== HTTP-Kommunikation ===

<code>OSentry.$captureException</code> sendet den erzeugten JSON-Payload an Sentry:

<pre>
#Generate HTTP Auth header
Begin text block
Text:Sentry sentry_version=7,
Text:sentry_timestamp=[$cinst.$getUnixTimestamp()],
Text:sentry_key=[iPubKey],
Text:sentry_client=omnis/1.0
End text block
Get text block auth

#Generate header list
Calculate Host as 'sentry.io'
Calculate Url as con('/api/',iProID,'/store/')
Do HdrList.$define(wert,name)
Do HdrList.$add('User-Agent','omnis/1.0')
Do HdrList.$add('Content-Type','application/json')
Do HdrList.$add('Content-Length',binlength(json))
Do HdrList.$add('X-Sentry-Auth',auth)
</pre>

Anschließend wird der Request über <code>HTTPPost</code>, <code>HTTPSend</code> und <code>HTTPRead</code> ausgeführt.

=== Fehlerbehandlung beim Senden ===

Wenn der Socket nicht geöffnet werden kann:

<pre>
HTTPPost (Host,Url,,HdrList,443,kTrue,kTrue) Returns Socket
If Socket<0
#Error when opening connection -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Error ',Socket,' when performing HTTPPost'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -1
End If
</pre>

Wenn das Senden fehlschlägt:

<pre>
HTTPSend (Socket,json) Returns byteCount
If byteCount<0
# Error while sending data -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Erorr ',byteCount,' when performing HTTPSend'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -2
End If
</pre>

Wenn die Antwort nicht erfolgreich ist:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

=== Lokales Speichern ===

Bei Fehlern wird der JSON Report lokal im Omnis-Installationsordner gespeichert:

<pre>
#Writes the json and the http buffer to a file in the omnis installation folder
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
Do fOP.$writecharacter(kUniTypeUTF8,pJSON) Returns err
If not(isclear(pBuffer))
Do fOP.$writecharacter(kUniTypeUTF8,con(kCr,pBuffer),kTrue) Returns err
End If
Do fOP.$closefile()

Quit method
</pre>

=== Cleanup ===

Nach erfolgreichem Senden werden [[#Tags, Extras und User-Kontext|Tags und Extras]] gelöscht:

<pre>
#Clears all extras and tags => to be used after a sentry request has successfully been sent
Do iTagList.$clear()
Do iExtraList.$clear()
Quit method
</pre>

== Demo Library ==

Die Demo-Library zeigt, wie <code>OSentry</code> initialisiert wird und wie verschiedene [[#Events erfassen|Event-Typen]] aus einer Omnis-Oberfläche heraus an Sentry gesendet werden.

=== Bestandteile ===

{| class="wikitable"
! Klasse !! Zweck
|-
| <code>Startup_Task</code> || Initialisiert Sentry, SQLite und öffnet das Demo-Fenster
|-
| <code>FSY_Demo</code> || Demo-Fenster
|-
| <code>ODummy</code> || Erzeugt Demo-Stack für Exception
|-
| <code>ODatabaseHandler</code> || Erstellt SQLite-Demo-Datenbank
|-
| <code>OSLSession</code> || SQLite Session
|-
| <code>OSentry</code> || Low-Level-Sentry-Adapter
|-
| <code>OSentryHL</code> || High-Level-Sentry-Adapter
|}

=== Startup ===

<code>Startup_Task.$construct</code> initialisiert Sentry, baut eine SQLite Session auf und öffnet das Demo-Fenster. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()

#SQLite Session init
Do $objects.OSLSession.$newref() Returns tOSLSession
#Calculate tOSLSession.$opencreate as kTrue
Calculate workingDir as tODatabaseHandler.$getWorkingDir()
Do con(workingDir,'Sentry_Test.db') Returns dbLocation
Do tOSLSession.$logon(dbLocation,'','','slsession') Returns #F

#Open Test Window
Do $windows.FSY_Demo.$openonce('*')

Quit method
</pre>

=== Demo-Fenster ===

<code>FSY_Demo</code> enthält folgende Bereiche:

* DSN Configuration
* DB Status
* Actions

Wichtige Felder:

{| class="wikitable"
! Feld !! Datenanbindung
|-
| DSN || <code>iDSN</code>
|-
| Host || <code>tSentry.iOSentry.iHost</code>
|-
| Public Key || <code>tSentry.iOSentry.iPubKey</code>
|-
| Project ID || <code>tSentry.iOSentry.iProID</code>
|-
| DB Status || <code>iCurrentDBStatus</code>
|}

[[Datei:Demo-window.png|850px|Demo-Fenster der OSentry Library]]

=== DSN setzen ===

Die DSN wird im Feld <code>iDSN</code> erfasst. Der Button <code>Set DSN</code> ruft anschließend <code>tSentry.$init(iDSN)</code> auf. Nach dem Setzen werden Public Key, Host und Project ID aus der DSN gelesen und in den darunterliegenden Feldern angezeigt.

[[Datei:Demo-dsn.png|850px|DSN-Konfiguration im Demo-Fenster]]

Der Button <code>Set DSN</code> initialisiert Sentry mit der eingegebenen DSN. Quelle: <code>FSY_Demo.setDSN.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$init(iDSN)
Calculate $cclass.$ivardefs.iDSN.$objinitval as con(kSq,iDSN,kSq)

Do $cinst.$showmessage('DSN set and Sentry initialized!','Info')

Do $cinst.$redraw()
Quit method
</pre>

=== DB Status anzeigen ===

<code>FSY_Demo.$displayDBState</code> zeigt, ob die SQLite Session verbunden ist. Quelle: <code>FSY_Demo.$displayDBState</code>.

<pre>
Do tOSLSession.$state Returns dbState
If dbState='kSessionStateLoggedOff'
Calculate iCurrentDBStatus as 'Logged Off'
Else If dbState='kSessionStateLoggedOn'
Calculate iCurrentDBStatus as 'Logged On'
Else
Calculate iCurrentDBStatus as 'Unkown DB State'
End If

Do $cinst.$redraw()
Quit method
</pre>

=== Demo-Datenbank erstellen ===

Der Button <code>Create Database</code> ruft <code>ODatabaseHandler.$DBFirstInit</code> auf. Quelle: <code>FSY_Demo.createDB.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Setup the DB
Do tODatabaseHandler.$DBFirstInit() Returns err
If err=0
Do $cinst.$showmessage('DB successfully created!','Info')
Else
Do $cinst.$showmessage('Error while creating the DB. Make sure that the DB does not already exist.','Info')
End If

Do $cinst.$displayDBState()

Quit method
</pre>

Die Datenbank wird im Arbeitsverzeichnis der Library angelegt. Quelle: <code>ODatabaseHandler.$getWorkingDir</code>.

<pre>
Quit method con(FileOps.$parentdir($clib.$pathname),pathsep())
</pre>

Die Demo-DB enthält unter anderem:

* <code>dperson</code>
* <code>drelease</code>
* <code>dvcs</code>

=== Message auslösen ===

Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Log auslösen ===

Button <code>Trigger a log</code>. Quelle: <code>FSY_Demo.log.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception auslösen ===

Button <code>Trigger an exception</code> bereitet eine Row und eine List vor und ruft anschließend <code>ODummy.$dummyMethod</code> auf. Quelle: <code>FSY_Demo.exception.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do iDummyRow.$define(id,name)
Calculate iDummyRow.id as 22
Calculate iDummyRow.name as 'Tom'

Do iDummyList.$define(id,weekday)
Do iDummyList.$add(1,'Monday')
Do iDummyList.$add(2,'Tuesday')
Do iDummyList.$add(3,'Wednesday')
Do iDummyList.$add(4,'Thursday')
Do iDummyList.$add(5,'Friday')
Do iDummyList.$add(6,'Saturday')
Do iDummyList.$add(7,'Sunday')

Calculate iDummyList.$line as 5

Do iODummy.$dummyMethod('Important Value')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')

Quit method
</pre>

<code>ODummy.$dummyMethod</code> sendet die Exception. Quelle: <code>ODummy.$dummyMethod</code>.

<pre>
#In here is some logic
#This logic would produce an error
#We send all this information to Sentry

Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')

Quit method 0
</pre>

=== Deprecated Call auslösen ===

Button <code>Trigger a deprecated call</code>. Quelle: <code>FSY_Demo.deprecatedCall.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureDeprecatedCall()
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== SQL Exception Button ===

Der Button <code>Trigger an SQLException</code> ist im Export vorhanden, enthält aber noch keinen fertigen Demo-Code. Quelle: <code>FSY_Demo.sqlException.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Für die Dokumentation der SQL-Erfassung siehe [[#Events erfassen|03 Events erfassen]].

== API Reference ==

Diese Seite dokumentiert die produktiv relevanten Methoden von <code>OSentryHL</code> und <code>OSentry</code>.

=== OSentryHL ===

<code>OSentryHL</code> ist die empfohlene Klasse für Applikationscode.

'''<code>$init(pDSN)</code>'''

Initialisiert das interne <code>OSentry</code>-Objekt.

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

'''<code>$captureMessage(pMessage)</code>'''

Sendet eine einfache Info-Message.

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel)</code>'''

Sendet eine generische Exception.

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

'''<code>$captureAnything(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface)</code>'''

Sendet ein frei konfigurierbares Event.

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Hinweis: Der Parameter ist im Export als <code>pStacktraveInterface</code> geschrieben.

'''<code>$captureLog(pErrorText)</code>'''

Sendet ein Log-Event.

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

'''<code>$captureDeprecatedCall()</code>'''

Meldet die Ausführung eines veralteten Codepfads.

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

'''<code>$captureSQLException(pErrorText,pStat)</code>'''

Meldet einen SQL-Fehler mit SQL-Text und nativer Datenbankfehlermeldung.

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag für das nächste Event hinzu.

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra für das nächste Event hinzu.

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

'''<code>$setStatus(pStatus)</code>'''

Aktiviert oder deaktiviert Sentry.

<pre>
#Toggels Sentry on or off
Do iOSentry.$setStatus(pStatus)
Quit method
</pre>

'''<code>$setUser()</code>'''

Setzt im Export feste [[#Demo Library|Demo]]-Userdaten.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode parametrisiert werden.

=== OSentry ===

<code>OSentry</code> ist die Low-Level-Klasse für Payload-Erzeugung und Versand.

'''<code>$init(pDSN)</code>'''

Parst die DSN in Protokoll, Public Key, Host und Project ID.

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraceInterface,pUserInterface,pExceptionInterface)</code>'''

Erzeugt JSON, sendet es an Sentry und behandelt Fehlerfälle.

Parameter:

{| class="wikitable"
! Parameter !! Default !! Bedeutung
|-
| <code>pErrorText</code> || || Message
|-
| <code>pErrorCode</code> || || Fehlercode
|-
| <code>pExcType</code> || || Exception-Typ
|-
| <code>pLevel</code> || || <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code>, <code>debug</code>
|-
| <code>pStacktraceInterface</code> || <code>kTrue</code> || [[#Stacktrace und Kontext|Stacktrace]] senden
|-
| <code>pUserInterface</code> || <code>kTrue</code> || [[#Tags, Extras und User-Kontext|User-Kontext]] senden
|-
| <code>pExceptionInterface</code> || <code>kTrue</code> || Exception Interface senden
|}

'''<code>$generateJson(...)</code>'''

Erzeugt den Sentry JSON Payload als Binary.

'''<code>$generateStacktraceInterface(pCulprit)</code>'''

Erzeugt den Omnis-[[#Stacktrace und Kontext|Stacktrace]] inklusive Variablen und Kontextzeilen.

'''<code>$generateExceptionInterface(pType,pValue)</code>'''

Erzeugt das Sentry Exception Interface.

<pre>
# Generate Row to store in the JSON
Do exceptionRow.$define(type,value,stacktrace)
Calculate exceptionRow.type as pType
Calculate exceptionRow.value as pValue
Calculate exceptionRow.stacktrace as 'sentry.interfaces.stacktrace' ## Tells the exception interface that a stacktrace is passed aswell
</pre>

'''<code>$generateUserInterface()</code>'''

Erzeugt den [[#Tags, Extras und User-Kontext|User-Kontext]].

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag zur internen Tag-Liste hinzu.

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra zur internen Extra-Liste hinzu.

'''<code>$clearList()</code>'''

Leert [[#Tags, Extras und User-Kontext|Tags und Extras]] nach einem Request.

'''<code>$setUserData(pID,pName,pEmail)</code>'''

Setzt Userdaten für den nächsten Request.

'''<code>$setProxy(pProxyHost,pProxyPort)</code>'''

Setzt Proxy-Informationen.

'''<code>$setStatus(pStatus)</code>'''

Setzt den Sentry-Status.

<pre>
#Toggels Sentry Reports on or off
Calculate iStatus as pStatus
Quit method
</pre>

'''<code>$writeJSON(pJSON,pBuffer)</code>'''

Schreibt fehlgeschlagene Reports lokal in eine Datei.

'''<code>$getUnixTimestamp()</code>'''

Gibt den aktuellen UNIX Timestamp zurück.

'''<code>$generateUUID()</code>'''

Erzeugt eine UUID für die Sentry Event ID.

<pre>
#Genereates a UUID for the issue id
Quit method OW3.$makeuuid(kFalse)
</pre>

== Troubleshooting ==

=== Es erscheinen keine Events in Sentry ===

Prüfe zuerst, ob Sentry aktiv ist:

<pre>
Do tSentry.$setStatus(1)
</pre>

<code>OSentry.$captureException</code> beendet sich sofort, wenn der Status <code>0</code> oder leer ist:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

=== Die DSN ist falsch ===

Prüfe, ob die DSN korrekt aus Sentry kopiert wurde. <code>OSentry.$init</code> erwartet eine DSN, aus der Public Key, Host und Project ID gelesen werden können.

Nach dem Setzen der DSN sollten in der [[#Demo Library|Demo-Library]] folgende Felder gefüllt sein:

* Host
* Public Key
* Project ID

=== Netzwerk oder Proxy blockiert den Request ===

Wenn die Anwendung keinen direkten Zugriff auf Sentry hat, setze einen Proxy:

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Intern wird der Proxy vor dem HTTP Request gesetzt:

<pre>
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Report wird lokal gespeichert ===

Wenn <code>HTTPPost</code>, <code>HTTPSend</code> oder <code>HTTPRead</code> fehlschlägt, speichert OSentry den Report lokal:

<pre>
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
</pre>

Suche im Omnis-Installationsordner nach Dateien mit dem Namen:

<pre>
Sentryreport_<timestamp>.json
</pre>

=== Sentry antwortet nicht mit 200 OK ===

Wenn die HTTP-Antwort kein <code>200 OK</code> enthält, wird der JSON Report ebenfalls lokal gespeichert:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

Mögliche Ursachen:

* falsche Project ID
* falscher Public Key
* ungültige DSN
* JSON Payload wird von Sentry abgelehnt
* Netzwerk-Gateway verändert den Request

=== Tags oder Extras erscheinen beim falschen Event ===

[[#Tags, Extras und User-Kontext|Tags und Extras]] werden für den nächsten Request gesammelt. Nach erfolgreichem Request werden sie gelöscht:

<pre>
Do iTagList.$clear()
Do iExtraList.$clear()
</pre>

Wenn ein Request fehlschlägt, wird ebenfalls aufgeräumt:

<pre>
Do $cinst.$clearList()
</pre>

Prüfe trotzdem, ob in eigenen Wrapper-Methoden Tags und Extras direkt vor dem passenden Capture-Aufruf gesetzt werden.

=== User-Kontext zeigt Demo-Daten ===

<code>OSentryHL.$setUser</code> verwendet im Export feste Testdaten:

<pre>
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
</pre>

Für produktive Nutzung sollte die Methode parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
</pre>

=== SQL Exception Demo-Button funktioniert nicht ===

Der Button <code>Trigger an SQLException</code> ist im Export noch nicht implementiert:

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Die produktive Methode für SQL-Fehler ist aber vorhanden. Siehe auch [[#Events erfassen|Events erfassen]].

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

=== Zu viele Events ===

Sentry kann sehr schnell viele Events sammeln. Verwende für produktive Systeme:

* klare Wrapper-Methoden in <code>OSentryHL</code>
* sinnvolle Levels
* gezielte [[#Tags, Extras und User-Kontext|Tags]]
* keine Events in sehr häufigen Schleifen
* keine rein informativen Debug-Events ohne Nutzen

=== Sensible Daten ===

[[#Stacktrace und Kontext|Stacktrace]], Parameter, Instance Variablen, SQL-Text und [[#Tags, Extras und User-Kontext|Extras]] können sensible Daten enthalten. Prüfe vor produktiver Nutzung:

* Welche Variablen werden übertragen?
* Enthalten SQL-Statements personenbezogene Daten?
* Werden Tokens oder Passwörter in Extras geschrieben?
* Sollen bestimmte Werte maskiert werden?

Sentry

2026-06-12T14:07:58Z

Silvan: /* Demo-Fenster */

__TOC__

== Überblick ==

OSentry ist ein REST-API-Konnektor von Omnis Studio zu Sentry. Der Konnektor sendet Fehler, Messages, Logs und Laufzeitkontext aus Omnis-Anwendungen an Sentry, damit Probleme in produktiven Systemen sichtbar, gruppierbar und analysierbar werden.

Diese Dokumentation beschreibt die [[#Installation|Installation]], die Nutzung in bestehenden Omnis-Anwendungen, die Definition eigener standardisierter Exception-Typen, die interne Struktur und die [[#Demo Library|Demo-Library]].

=== Kernidee ===

OSentry besteht aus zwei produktiv relevanten Klassen:

* <code>OSentryHL</code>: High-Level-Adapter für die Anwendung. Diese Klasse sollte von normalem Applikationscode aufgerufen werden.
* <code>OSentry</code>: Low-Level-Adapter für DSN-Parsing, JSON-Erzeugung, [[#Stacktrace und Kontext|Stacktrace]]-Aufbereitung und HTTP-Kommunikation mit Sentry.

Die Anwendung arbeitet im Normalfall mit <code>OSentryHL</code>. Dadurch bleiben Sentry-spezifische Details zentral gekapselt und neue standardisierte Exception-Typen können als eigene Methoden in <code>OSentryHL</code> definiert werden.

=== Hauptfeatures ===

* Direkte Anbindung von Omnis Studio an Sentry über REST API und DSN
* Erfassen von Exceptions, Messages, Logs und SQL-Fehlern
* Unterstützung der Sentry-Level <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code> und <code>debug</code>
* Automatische Omnis-Kontextinformationen
* Omnis-[[#Stacktrace und Kontext|Stacktrace]] mit Klassen, Methoden, Zeilen und Variablen
* [[#Tags, Extras und User-Kontext|Tags]] für Filterung und Gruppierung
* [[#Tags, Extras und User-Kontext|Extras]] für zusätzliche Diagnoseinformationen
* Optionaler [[#Tags, Extras und User-Kontext|User-Kontext]]
* Proxy-Unterstützung
* Aktivieren und Deaktivieren der Sentry-Übertragung
* Lokales Speichern von Reports bei Übertragungsfehlern

=== Weiterführende Links ===

* [https://sentry.io/welcome/ Sentry Website]
* [https://sentry.io/signup/ Sentry Account erstellen]
* [https://develop.sentry.dev/self-hosted/ Sentry self-hosted]

== Installation ==

Diese Seite beschreibt, wie OSentry in eine bestehende Omnis-Anwendung integriert wird.

=== Voraussetzungen ===

* Omnis Studio Anwendung
* Sentry Account oder self-hosted Sentry Installation
* Ein Sentry-Projekt mit SDK-Typ <code>Other</code>
* Die DSN des Sentry-Projekts
* Netzwerkzugriff auf Sentry

Die exportierte [[#Demo Library|Demo-Library]] wurde mit Omnis <code>11.1</code> erstellt.

=== Sentry-Projekt erstellen ===

# In Sentry ein neues Projekt erstellen.
# Als SDK <code>Other</code> auswählen.
# Die DSN des Projekts kopieren.

Die DSN wird beim Initialisieren verwendet. <code>OSentry</code> zerlegt sie intern in Public Key, Host und Project ID.

[[Datei:Sentry-projects.png|900px|Sentry Projektübersicht]]

=== Klassen kopieren ===

Kopiere die folgenden Klassen in deine bestehende Omnis-Library:

* <code>OSentry</code>
* <code>OSentryHL</code>

Die Demo-spezifischen Klassen sind für die produktive Integration nicht erforderlich. Damit sind die übrigen Klassen der Demo-Library gemeint, zum Beispiel <code>FSY_Demo</code>, <code>ODummy</code>, <code>ODatabaseHandler</code> und <code>OSLSession</code>. Diese Klassen dienen nur dazu, die [[#Demo Library|Demo-Library]] mit Fenster, SQLite-Testdaten und Beispielaufrufen auszuführen.

=== Task Variable anlegen ===

Lege in deiner Startup Task eine Task Variable an:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' <code>tSentry</code> sollte als global erreichbarer Singleton der Anwendung verwendet werden. In Omnis ist dafür eine Task Variable sinnvoll, weil sie von Fenstern, Objektklassen und zentralen Error-Handlern aus konsistent erreichbar ist. Dadurch gibt es genau eine aktive Sentry-Konfiguration mit einer DSN, einem Status, optionalen Proxy-Daten und gemeinsamen Wrapper-Methoden in <code>OSentryHL</code>.</div>

Im [[#Demo Library|Demo-Projekt]] ist diese Variable in <code>Startup_Task</code> definiert.

=== Initialisierung im Startup Task ===

Initialisiere <code>tSentry</code> beim Start deiner Anwendung mit der DSN deines Sentry-Projekts:

<pre>
Do tSentry.$init('<DSN>')
</pre>

Die [[#Demo Library|Demo-Library]] ruft im Startup Task ebenfalls die Initialisierung auf. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()
</pre>

In einer produktiven Anwendung sollte die DSN explizit oder aus einer Konfiguration übergeben werden:

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Speichere die DSN in einer Datenbank, einer Konfigurationstabelle oder einem Config File. So kann sie pro Kunde, Umgebung oder Installation geändert werden, ohne die Library neu auszuliefern.</div>

=== Testcall ===

Nach der Initialisierung kann ein erstes Testevent gesendet werden:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Wenn alles korrekt eingerichtet ist, erscheint das Event im Sentry-Projekt.

=== Proxy konfigurieren ===

Falls die Anwendung in einem geschützten Netzwerk läuft, kann ein Proxy gesetzt werden. Die Methode befindet sich im Low-Level-Objekt <code>OSentry</code>.

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Die interne Implementierung setzt den Proxy vor dem HTTP-Request:

<pre>
#Configure proxy; needed when sending data out of secured networks
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Sentry aktivieren oder deaktivieren ===

OSentry kann zentral ein- oder ausgeschaltet werden.

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Deaktiviere Sentry in der Entwicklungs-Version standardmäßig oder verwende eine separate Entwicklungs-DSN. So landen lokale Tests, Debug-Fehler und absichtlich ausgelöste Exceptions nicht im produktiven Sentry-Projekt.</div>

<pre>
Do tSentry.$setStatus(1) ## aktiv
Do tSentry.$setStatus(0) ## inaktiv
</pre>

Im Low-Level-Objekt <code>OSentry</code> wird vor dem Senden geprüft:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

== Quickstart ==

Diese Seite zeigt die minimale Integration in eine bestehende Omnis-Anwendung.

=== Klassen übernehmen ===

Kopiere <code>OSentry</code> und <code>OSentryHL</code> in deine Library.

=== Task Variable erstellen ===

In der Startup Task:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

=== Sentry initialisieren ===

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<code>OSentryHL.$init</code> delegiert an das Low-Level-Objekt <code>OSentry</code>:

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

=== Message senden ===

<pre>
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
</pre>

Die [[#Demo Library|Demo-Library]] verwendet genau diesen Aufruf im Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception senden ===

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

=== In Sentry prüfen ===

In Sentry sollte anschließend ein neues Event sichtbar sein. Je nach Event-Typ enthält es:

* Message
* Level
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Tags, Extras und User-Kontext|User-Kontext]]
* [[#Stacktrace und Kontext|Stacktrace]]
* Omnis-Kontextinformationen

== Events erfassen ==

OSentryHL ist die empfohlene Einstiegsschicht für Applikationscode. Die Klasse bietet sprechende Methoden für typische Event-Arten und ruft intern <code>OSentry.$captureException</code> auf.

=== Message ===

Eine einfache Information wird mit <code>$captureMessage</code> gesendet:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

Verhalten:

* Level: <code>info</code>
* Kein [[#Stacktrace und Kontext|Stacktrace]]
* Kein [[#Tags, Extras und User-Kontext|User Interface]]
* Geeignet für einfache Statusmeldungen oder technische Hinweise

=== Log ===

Ein Log-Event wird mit <code>$captureLog</code> gesendet:

<pre>
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

Verhalten:

* Level: <code>warning</code>
* [[#Stacktrace und Kontext|Stacktrace]] aktiv
* Exception Interface in diesem Wrapper deaktiviert
* [[#Tags, Extras und User-Kontext|User Interface]] aktiv

=== Generische Exception ===

Eine generische Exception wird mit <code>$captureException</code> gesendet:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

Parameter:

{| class="wikitable"
! Parameter !! Bedeutung
|-
| <code>pErrorText</code> || Text, der in Sentry als Message sichtbar ist
|-
| <code>pErrorCode</code> || Fehlercode oder fachlicher Code
|-
| <code>pExcType</code> || Exception-Typ für Benennung und Gruppierung
|-
| <code>pLevel</code> || Sentry-Level
|}

Gültige Levels:

* <code>fatal</code>
* <code>error</code>
* <code>warning</code>
* <code>info</code>
* <code>debug</code>

=== SQL Exception ===

SQL-Fehler können mit <code>$captureSQLException</code> gemeldet werden.

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

Verhalten:

* Fügt die Datenbank als [[#Tags, Extras und User-Kontext|Tag]] hinzu
* Fügt SQL-Text als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Fügt native Datenbankfehlermeldung als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Sendet das Event als <code>SQL-Exception</code> mit Level <code>error</code>

=== Deprecated Call ===

Veraltete Codepfade können gezielt gemeldet werden:

<pre>
Do tSentry.$captureDeprecatedCall()
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

Dieser Wrapper eignet sich, um zu erkennen, ob alter Code in produktiven Systemen noch ausgeführt wird.

=== Frei konfigurierbares Event ===

Für Sonderfälle gibt es <code>$captureAnything</code>:

<pre>
Do tSentry.$captureAnything('Text',1001,'Custom Type','error',kTrue,kTrue,kTrue)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Diese Methode bietet maximale Flexibilität. Für wiederkehrende Exception-Typen sollte aber eine eigene Methode in <code>OSentryHL</code> angelegt werden. Siehe [[#Eigene Exceptions standardisieren|04 Eigene Exceptions standardisieren]].

== Eigene Exceptions standardisieren ==

Wenn ein Exception-Typ mehrfach in der Anwendung vorkommt, sollte er nicht überall manuell mit <code>$captureException</code> aufgebaut werden. Besser ist eine eigene Methode in <code>OSentryHL</code>.

Dadurch entsteht eine zentrale, wiederverwendbare Definition für:

* Exception-Typ
* Sentry-Level
* Fehlercode
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Stacktrace und Kontext|Stacktrace]]/[[#Tags, Extras und User-Kontext|User]]/Exception Interface

Die automatisch gesetzten [[#Tags, Extras und User-Kontext|Tags und Extras]] aus <code>OSentry.$generateJson</code> müssen in solchen Wrappern nicht erneut ergänzt werden. Eigene Exception-Methoden setzen nur zusätzliche Werte, die für diesen standardisierten Exception-Typ relevant sind.

=== Warum über OSentryHL? ===

<code>OSentryHL</code> ist die Abstraktionsschicht für Applikationscode. Sie kapselt die Details von <code>OSentry</code> und sorgt dafür, dass Aufrufe in der Anwendung kurz und konsistent bleiben.

Bestehende Beispiele aus <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

=== Empfohlenes Muster ===

Für jeden standardisierten Exception-Typ wird eine eigene Methode in <code>OSentryHL</code> erstellt.

Beispiel:

<pre>
# Captures a validation exception
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addExtra('Field',pField)
Do $cinst.$addExtra('Invalid Value',pValue)

Do iOSentry.$captureException(pErrorText,2001,'Validation-Exception','warning',1,1,1) Returns code

Quit method code
</pre>

Mögliche Parameter der neuen Methode:

{| class="wikitable"
! Parameter !! Beispiel !! Zweck
|-
| <code>pErrorText</code> || <code>'Invalid customer number'</code> || Sentry Message
|-
| <code>pModule</code> || <code>'Customer'</code> || Filterbarer Tag
|-
| <code>pField</code> || <code>'cu_number'</code> || Diagnoseinformation
|-
| <code>pValue</code> || <code>'ABC'</code> || Diagnoseinformation
|}

Der Applikationscode bleibt dadurch einfach:

<pre>
Do tSentry.$captureValidationException('Invalid customer number','Customer','cu_number',cu_number)
</pre>

=== Beispiel: Business Rule Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures a business rule violation
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do $cinst.$addExtra('Details',pDetails)

Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureBusinessRuleViolation('Invoice cannot be posted','Invoice','PostingAllowed','Invoice is missing customer')
</pre>

=== Beispiel: Integration Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures an integration exception
Do $cinst.$addTag('Integration',pSystem)
Do $cinst.$addTag('Endpoint',pEndpoint)
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)

Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureIntegrationException('External API request failed','ERP','/api/customer',jsonPayload,responseText)
</pre>

=== Namenskonventionen ===

Empfehlung für neue Methoden:

* Methodenname beginnt mit <code>$capture</code>
* Der fachliche Typ steht im Methodennamen
* Der Sentry Exception Type ist stabil und ändert sich nicht laufend
* [[#Tags, Extras und User-Kontext|Tags]] sind kurz und filterbar
* [[#Tags, Extras und User-Kontext|Extras]] dürfen länger sein und Diagnoseinformationen enthalten

Beispiele:

* <code>$captureValidationException</code>
* <code>$captureBusinessRuleViolation</code>
* <code>$captureIntegrationException</code>
* <code>$capturePermissionViolation</code>
* <code>$captureConfigurationError</code>

=== Error Codes ===

Verwende feste Fehlercodes für standardisierte Exception-Typen. Dadurch können Events in Sentry besser gefiltert und wiedererkannt werden.

Beispiel:

{| class="wikitable"
! Code !! Exception Type
|-
| <code>2001</code> || <code>Validation-Exception</code>
|-
| <code>3001</code> || <code>Business-Rule-Violation</code>
|-
| <code>4001</code> || <code>Integration-Exception</code>
|-
| <code>5001</code> || <code>Configuration-Error</code>
|}

=== Wann nicht standardisieren? ===

Nicht jeder Einzelfall braucht eine eigene Methode. Für einmalige technische Tests oder sehr spezielle Fälle reicht:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Sobald ein Exception-Typ aber mehrfach vorkommt oder fachlich relevant ist, sollte er als eigene Methode in <code>OSentryHL</code> definiert werden.

== Tags, Extras und User-Kontext ==

Tags, Extras und User-Kontext reichern Sentry-Events mit zusätzlichen Informationen an. Diese Informationen helfen beim Filtern, Gruppieren und Analysieren.

[[Datei:Sentry-tags.png|900px|Sentry Tags und User-Kontext]]

=== Tags ===

Tags sind kurze, filterbare Werte.

Beispiele:

* Datenbank
* Kunde
* Modul
* Umgebung
* Error Code
* Omnis-Version

Methode in <code>OSentryHL</code>:

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds a tag to the next request processed
Do iTagList.$add(pName,pValue)
Quit method
</pre>

Beispiel:

<pre>
Do tSentry.$addTag('Module','Invoice')
Do tSentry.$addTag('Customer','10001')
Do tSentry.$captureException('Invoice posting failed',3001,'Business-Rule-Violation','warning')
</pre>

=== Extras ===

Extras sind Detailinformationen, die nicht primär zum Filtern gedacht sind.

Beispiele:

* SQL-Text
* Native Datenbankfehlermeldung
* Payload
* Response Body
* interne IDs
* zusätzliche Debug-Informationen

Methode in <code>OSentryHL</code>:

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds extra information to the next request being processed
Do iExtraList.$add(pName,pValue)
Quit method
</pre>

Beispiel aus der SQL Exception:

<pre>
Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)
</pre>

=== Automatische Tags ===

Die folgenden Tags werden bei jedem Event automatisch von <code>OSentry.$generateJson</code> ergänzt. Sie müssen bei eigenen Exceptions nicht erneut gesetzt werden. Eigene Wrapper-Methoden in <code>OSentryHL</code> sollten nur zusätzliche, fachlich oder technisch relevante Tags hinzufügen.

<code>OSentry.$generateJson</code> fügt mehrere Tags automatisch hinzu:

<pre>
# Add static tags
Do iTagList.$add('Omnisversion',sys(1))
Calculate systemversionRow as systemversion()
Do iTagList.$add('Plattform',con(sys(8),pick(systemversionRow.server,'',' SRV')))
Do iTagList.$add('OS Version',con(systemversionRow.major,'.',systemversionRow.minor,'.',systemversionRow.build))
Do iTagList.$add('error_code',pErrorCode)
</pre>

Automatisch gesendete Tags:

{| class="wikitable"
! Tag !! Herkunft !! Zweck
|-
| <code>Omnisversion</code> || <code>sys(1)</code> || Zeigt, mit welcher Omnis-Version das Event erzeugt wurde
|-
| <code>Plattform</code> || <code>sys(8)</code> und Server-Flag aus <code>systemversion()</code> || Unterscheidet Plattform und Server Runtime
|-
| <code>OS Version</code> || <code>systemversionRow.major/minor/build</code> || Zeigt die Betriebssystemversion
|-
| <code>error_code</code> || Parameter <code>pErrorCode</code> || Verbindet das Event mit dem übergebenen Fehlercode
|}

Beispiel für eine eigene Exception: Der Wrapper muss nicht erneut <code>Omnisversion</code> oder <code>OS Version</code> setzen. Er ergänzt nur das, was für diesen Exception-Typ zusätzlich hilfreich ist.

<pre>
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code
</pre>

=== Automatische Extras ===

Auch die folgenden Extras werden bei jedem Event automatisch ergänzt. Bei eigenen Exceptions müssen nur zusätzliche Extras gesetzt werden, zum Beispiel ein SQL-Statement, ein Payload oder fachliche Zusatzdaten.

<code>OSentry.$generateJson</code> fügt offene Fenster, offene Reports und die aktuelle Printfile hinzu:

<pre>
# Static extra 1: All open windows
Do $root.$iwindows.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate windows as con(windows,', ',nameList.[i].1)
End For
Calculate windows as right(windows,len(windows)-2)
Do iExtraList.$add('Open Windows',windows)

# Static extra 2: All open reports
Do $root.$ireports.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate reports as con(reports,', ',nameList.[i].1)
End For
Calculate reports as right(reports,len(reports)-2)
Do iExtraList.$add('Open Reports',reports)
Do iExtraList.$add('Current Printfile',$root.$prefs.$printfile)
</pre>

Automatisch gesendete Extras:

{| class="wikitable"
! Extra !! Herkunft !! Zweck
|-
| <code>Open Windows</code> || <code>$root.$iwindows.$makelist($ref.$name)</code> || Zeigt, welche Fenster im Moment des Events offen waren
|-
| <code>Open Reports</code> || <code>$root.$ireports.$makelist($ref.$name)</code> || Zeigt, welche Reports im Moment des Events offen waren
|-
| <code>Current Printfile</code> || <code>$root.$prefs.$printfile</code> || Zeigt die aktuell gesetzte Printfile
|}

Beispiel für zusätzliche Extras in einem eigenen Wrapper:

<pre>
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)
Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code
</pre>

=== User-Kontext ===

Der User-Kontext ordnet ein Event einem betroffenen Benutzer zu. In Sentry erscheint dadurch ein eigener User-Bereich, und Events können nach Benutzer gefiltert oder gruppiert werden. Das ist besonders hilfreich, wenn ein Fehler nur bei einzelnen Kunden, Arbeitsplätzen oder Benutzerkonten auftritt.

<code>OSentry</code> unterstützt drei User-Felder:

{| class="wikitable"
! Feld !! Bedeutung
|-
| <code>id</code> || stabile interne Benutzer-ID oder Kundennummer
|-
| <code>username</code> || lesbarer Benutzername
|-
| <code>email</code> || E-Mail-Adresse, falls sie übertragen werden darf
|}

Der User-Kontext wird nur in das Event geschrieben, wenn das User Interface beim Capture-Aufruf aktiviert ist. Die Standardmethode <code>OSentry.$captureException</code> hat <code>pUserInterface</code> standardmäßig auf <code>kTrue</code>. Einzelne High-Level-Methoden können das bewusst deaktivieren, zum Beispiel <code>$captureMessage</code>.

<code>OSentry</code> kann User-Daten an das Event anhängen:

<pre>
#Sets userinformation for the next request being processed
Calculate iUserID as pID
Calculate iUserName as pName
Calculate iUserEmail as pEmail
Quit method
</pre>

Das User Interface wird so generiert:

<pre>
# Create user data row
Do UserdataRow.$define(id,email,username)

Calculate UserdataRow.id as iUserID
Calculate UserdataRow.email as iUserEmail
Calculate UserdataRow.username as iUserName

Do JSON.$addmember('','user','')
Do JSON.$setobject('user',UserdataRow)

Calculate jsonString as OJSON.$formatjson(JSON.$getjson())

Quit method jsonString
</pre>

Die aktuelle Demo-Methode in <code>OSentryHL</code> verwendet feste Testdaten. Quelle: <code>OSentryHL.$setUser</code>.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode angepasst und parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
Quit method
</pre>

Empfohlen ist, den User nach Login oder beim Wechsel des aktiven Benutzers zentral zu setzen. Bei anonymen oder sensiblen Installationen kann statt Name und E-Mail auch nur eine interne ID oder ein pseudonymisierter Wert verwendet werden.

=== Datenschutz ===

<div style="border-left:4px solid #72777d; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Datenschutz:''' Prüfe vor produktiver Nutzung, welche Daten an Sentry gesendet werden. Besonders kritisch sind personenbezogene Daten, SQL-Statements, Zugangsdaten, Tokens und interne Pfade.</div>

Besonders kritisch sind:

* personenbezogene Daten
* Kundendaten
* SQL-Statements mit Werten
* Zugangsdaten
* Tokens
* interne Pfade

Tags und Extras sollten so gestaltet werden, dass sie für die Fehleranalyse hilfreich sind, aber keine unnötigen sensiblen Daten übertragen.

== Stacktrace und Kontext ==

<code>OSentry</code> erzeugt einen Omnis-spezifischen Stacktrace und übergibt ihn an Sentry. Dadurch sieht man in Sentry nicht nur eine Fehlermeldung, sondern auch Klassen, Methoden, Zeilen und Variablenkontext. Ergänzende Informationen zu [[#Tags, Extras und User-Kontext|Tags, Extras und User-Kontext]] stehen auf der separaten Kontext-Seite.

[[Datei:Sentry-stack.png|900px|Sentry Stacktrace mit Omnis-Kontext]]

=== Stack lesen ===

<code>OSentry.$generateStacktraceInterface</code> verwendet <code>sys(192)</code>, um den aktuellen Omnis-Stack zu lesen:

<pre>
# Clean up the Stacklist (remove OSentry classes from the stack)
Do sys(192) Returns sys192List
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
If pos('OSentry',class.$name)>0|pos('OSentryHL',class.$name)>0
Do sys192List.[sys192List.$line].$selected.$assign(kTrue)
End If
End For
Do sys192List.$remove(kListDeleteSelected)
</pre>

Interne Frames von <code>OSentry</code> und <code>OSentryHL</code> werden entfernt, damit in Sentry die fachlich relevanten Stellen sichtbar bleiben.

=== SQL-Error Frames entfernen ===

Bestimmte interne SQL-Fehlerframes werden ebenfalls entfernt:

<pre>
# Remove some other classes which we do not want to display
If sys192List.1.method='$sqlerror'
Do sys192List.$remove(1)
Else If sys192List.1.method='$statementerror'
Do sys192List.$remove(1)
End If
</pre>

=== Frames erzeugen ===

Für jeden Stack-Eintrag werden Funktion, Zeilennummer und Kontextzeile erzeugt:

<pre>
#Loop through every item on the omnis stack
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
Calculate className as class.$name

# Create the content row
Do contentRow.$define(vars,function,pre_context,context_line,lineno,filename,post_context)
Calculate contentRow.lineno as sys192List.line
Calculate contentRow.filename as testFileName
Calculate contentRow.context_line as sys192List.linetext
If isclear(sys192List.object)
Calculate contentRow.function as con(className,'.',sys192List.method) ## If it's a class method
Else
Calculate contentRow.function as con(className,'.',sys192List.object,'.',sys192List.method) ## If it's a method of an object of a class (e.g. Headedlist)
End If
Do contentList.$add(contentRow)
End For
</pre>

=== Variablen aufnehmen ===

Pro Stackframe werden Instance Variablen und Parameter gesammelt:

<pre>
# Get all iVars
Do varList.$define(name,value)
Set reference class to sys192List.inst
Do $cinst.$getVars('ivars',class) Returns varList

# Get all params
Calculate paramList as sys192List.params
For paramList.$line from 1 to paramList.$linecount step 1
If not(paramList.value='(Not empty)')
Do varList.$add(paramList.name,paramList.value)
Else
Do varList.$add(paramList.name,'(Not empty)')
End If
End For
</pre>

=== Pre- und Post-Context ===

OSentry fügt Methodenzeilen vor und nach der aktuellen Zeile hinzu:

<pre>
# Pre Context (all method lines before the error occured)
Set reference method to sys192List.methoditem
Do precontextList.$define(line)
For i from 1 to sys192List.line-1 step 1
Do precontextList.$add(method.$methodlines.[i].$text)
End For

# Post Context (all method lines after the error occured
Do postcontextList.$define(line)
For i from sys192List.line+1 to method.$methodlines.$count step 1
Do postcontextList.$add(method.$methodlines.[i].$text)
End For
</pre>

=== Variablentypen ===

<code>OSentry.$getVars</code> unterstützt Basisvariablen, Rows und Lists.

Basisvariablen:

<pre>
If varType='char'|varType='boolean'|varType='integer'|varType='number'|varType='date'
Calculate varContent as pItemRef.$[pVarType].[varName]
Do varList.$add(varName,varContent)
</pre>

Rows:

<pre>
Else If varType='row'
Calculate varRow as pItemRef.$[pVarType].[varName]
If varRow.$colcount=0
Do varList.$add(varName,'(Empty)')
Else
For Z2 from 1 to varRow.$colcount step 1
Calculate varContent as con(varContent,varRow.$cols.[Z2].$name,': ',varRow.[Z2],', ')
End For
Do varList.$add(varName,varContent)
</pre>

Lists:

<pre>
Else If varType='list'
Calculate varListType as pItemRef.$[pVarType].[varName]
Calculate varContent as con('Colcount: ',varListType.$colcount,', ','Linecount: ',varListType.$linecount,', ','Current Line: ',varListType.$line)
If varListType.$linecount=0&varListType.$line=0&varListType.$colcount=0
Do varList.$add(varName,'(Empty)')
Calculate varContent as ''
Else
For Z3 from 1 to varListType.$colcount step 1
Calculate colName as varListType.$cols.[Z3].$name
Calculate varContent as con(varContent,' ',colName,': ',varListType.[colName])
End For
Do varList.$add(varName,varContent)
Calculate varContent as ''
End If
End If
</pre>

=== Hinweise ===

Stacktrace und Variablenkontext sind sehr hilfreich, können aber sensible Daten enthalten. Vor produktiver Nutzung sollte geprüft werden, ob bestimmte Variablen anonymisiert oder ausgeschlossen werden müssen.

== Interne Architektur ==

Diese Seite beschreibt die produktiv relevanten Klassen <code>OSentryHL</code> und <code>OSentry</code>.

=== Klassenübersicht ===

{| class="wikitable"
! Klasse !! Rolle
|-
| <code>OSentryHL</code> || High-Level-Adapter für Applikationscode
|-
| <code>OSentry</code> || Low-Level-Adapter für JSON, [[#Stacktrace und Kontext|Stacktrace]] und HTTP
|-
| <code>Startup_Task</code> || [[#Demo Library|Demo]]-Startup und Beispiel für Initialisierung
|-
| <code>FSY_Demo</code> || [[#Demo Library|Demo]]-Fenster
|-
| <code>ODummy</code> || [[#Demo Library|Demo]]-Code für [[#Stacktrace und Kontext|Stacktrace]]-Beispiel
|-
| <code>ODatabaseHandler</code> || [[#Demo Library|Demo]]-DB Initialisierung
|-
| <code>OSLSession</code> || SQLite Session für [[#Demo Library|Demo]]
|}

=== Empfohlener Aufrufweg ===

Applikationscode sollte <code>OSentryHL</code> verwenden:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

<code>OSentryHL</code> delegiert anschließend an <code>OSentry</code>:

<pre>
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code
</pre>

=== Ablauf eines Events ===

# Applikationscode ruft Methode in <code>OSentryHL</code> auf.
# <code>OSentryHL</code> fügt bei Bedarf [[#Tags, Extras und User-Kontext|Tags und Extras]] hinzu.
# <code>OSentryHL</code> ruft <code>iOSentry.$captureException(...)</code> auf.
# <code>OSentry</code> prüft, ob Sentry aktiv ist.
# <code>OSentry</code> erzeugt JSON.
# [[#Stacktrace und Kontext|Stacktrace]], Exception Interface und [[#Tags, Extras und User-Kontext|User Interface]] werden optional ergänzt.
# HTTP Header und Sentry Auth Header werden erstellt.
# JSON wird per HTTPS an Sentry gesendet.
# Bei Erfolg werden [[#Tags, Extras und User-Kontext|Tags und Extras]] geleert.
# Bei Fehler wird der JSON Report lokal gespeichert.

=== DSN Parsing ===

<code>OSentry.$init</code> zerlegt die DSN:

<pre>
# Parse the DSN into Public Key, Host and Project ID
If len(pDSN)>5
Calculate iDSN as pDSN
Calculate part1 as strtok('iDSN','@')
Calculate iProtocol as strtok('part1','/')
Calculate iProtocol as left(iProtocol,len(iProtocol)-1)
Do strtok('part1','/')
Calculate iPubKey as strtok('part1',':')

Calculate iHost as strtok('iDSN','/')
Calculate iProID as iDSN

#Save the values for the next startup
Calculate $cclass.$ivardefs.iPubKey.$objinitval as con('"',iPubKey,'"')
Calculate $cclass.$ivardefs.iHost.$objinitval as con('"',iHost,'"')
Calculate $cclass.$ivardefs.iProID.$objinitval as con('"',iProID,'"')
End If

Quit method
</pre>

=== JSON-Erzeugung ===

<code>OSentry.$generateJson</code> ist die zentrale Methode für den Payload. Sie setzt unter anderem:

* <code>event_id</code>
* <code>logger</code>
* <code>platform</code>
* <code>culprit</code>
* <code>timestamp</code>
* <code>sdk</code>
* <code>message</code>
* <code>level</code>
* <code>tags</code>
* <code>extra</code>
* optional <code>user</code>
* optional <code>exception</code>
* optional <code>stacktrace</code>

Auszug:

<pre>
# Add all required fields (those are required from the API)
Do JSON.$addmember('','event_id',$cinst.$generateUUID()) ## auto generated UUID 4
Do JSON.$addmember('','logger',logger)
Do JSON.$addmember('','platform',platform)
Do JSON.$addmember('','culprit',culprit)
#Do JSON.$addmember('','release',release)
Do JSON.$addmember('','timestamp',timestamp)
Do JSON.$addmember('','sdk','')
Do JSON.$addmember('','message',pErrorText)
Do JSON.$addmember('','level',pLevel)
Do JSON.$addmember('','tags','')
</pre>

=== HTTP-Kommunikation ===

<code>OSentry.$captureException</code> sendet den erzeugten JSON-Payload an Sentry:

<pre>
#Generate HTTP Auth header
Begin text block
Text:Sentry sentry_version=7,
Text:sentry_timestamp=[$cinst.$getUnixTimestamp()],
Text:sentry_key=[iPubKey],
Text:sentry_client=omnis/1.0
End text block
Get text block auth

#Generate header list
Calculate Host as 'sentry.io'
Calculate Url as con('/api/',iProID,'/store/')
Do HdrList.$define(wert,name)
Do HdrList.$add('User-Agent','omnis/1.0')
Do HdrList.$add('Content-Type','application/json')
Do HdrList.$add('Content-Length',binlength(json))
Do HdrList.$add('X-Sentry-Auth',auth)
</pre>

Anschließend wird der Request über <code>HTTPPost</code>, <code>HTTPSend</code> und <code>HTTPRead</code> ausgeführt.

=== Fehlerbehandlung beim Senden ===

Wenn der Socket nicht geöffnet werden kann:

<pre>
HTTPPost (Host,Url,,HdrList,443,kTrue,kTrue) Returns Socket
If Socket<0
#Error when opening connection -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Error ',Socket,' when performing HTTPPost'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -1
End If
</pre>

Wenn das Senden fehlschlägt:

<pre>
HTTPSend (Socket,json) Returns byteCount
If byteCount<0
# Error while sending data -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Erorr ',byteCount,' when performing HTTPSend'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -2
End If
</pre>

Wenn die Antwort nicht erfolgreich ist:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

=== Lokales Speichern ===

Bei Fehlern wird der JSON Report lokal im Omnis-Installationsordner gespeichert:

<pre>
#Writes the json and the http buffer to a file in the omnis installation folder
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
Do fOP.$writecharacter(kUniTypeUTF8,pJSON) Returns err
If not(isclear(pBuffer))
Do fOP.$writecharacter(kUniTypeUTF8,con(kCr,pBuffer),kTrue) Returns err
End If
Do fOP.$closefile()

Quit method
</pre>

=== Cleanup ===

Nach erfolgreichem Senden werden [[#Tags, Extras und User-Kontext|Tags und Extras]] gelöscht:

<pre>
#Clears all extras and tags => to be used after a sentry request has successfully been sent
Do iTagList.$clear()
Do iExtraList.$clear()
Quit method
</pre>

== Demo Library ==

Die Demo-Library zeigt, wie <code>OSentry</code> initialisiert wird und wie verschiedene [[#Events erfassen|Event-Typen]] aus einer Omnis-Oberfläche heraus an Sentry gesendet werden.

=== Bestandteile ===

{| class="wikitable"
! Klasse !! Zweck
|-
| <code>Startup_Task</code> || Initialisiert Sentry, SQLite und öffnet das Demo-Fenster
|-
| <code>FSY_Demo</code> || Demo-Fenster
|-
| <code>ODummy</code> || Erzeugt Demo-Stack für Exception
|-
| <code>ODatabaseHandler</code> || Erstellt SQLite-Demo-Datenbank
|-
| <code>OSLSession</code> || SQLite Session
|-
| <code>OSentry</code> || Low-Level-Sentry-Adapter
|-
| <code>OSentryHL</code> || High-Level-Sentry-Adapter
|}

=== Startup ===

<code>Startup_Task.$construct</code> initialisiert Sentry, baut eine SQLite Session auf und öffnet das Demo-Fenster. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()

#SQLite Session init
Do $objects.OSLSession.$newref() Returns tOSLSession
#Calculate tOSLSession.$opencreate as kTrue
Calculate workingDir as tODatabaseHandler.$getWorkingDir()
Do con(workingDir,'Sentry_Test.db') Returns dbLocation
Do tOSLSession.$logon(dbLocation,'','','slsession') Returns #F

#Open Test Window
Do $windows.FSY_Demo.$openonce('*')

Quit method
</pre>

=== Demo-Fenster ===

<code>FSY_Demo</code> enthält folgende Bereiche:

* DSN Configuration
* DB Status
* Actions

Wichtige Felder:

{| class="wikitable"
! Feld !! Datenanbindung
|-
| DSN || <code>iDSN</code>
|-
| Host || <code>tSentry.iOSentry.iHost</code>
|-
| Public Key || <code>tSentry.iOSentry.iPubKey</code>
|-
| Project ID || <code>tSentry.iOSentry.iProID</code>
|-
| DB Status || <code>iCurrentDBStatus</code>
|}

[[Datei:Demo-window.png|850px|Demo-Fenster der OSentry Library]]

=== DSN setzen ===

Die DSN wird im Feld <code>iDSN</code> erfasst. Der Button <code>Set DSN</code> ruft anschließend <code>tSentry.$init(iDSN)</code> auf. Nach dem Setzen werden Public Key, Host und Project ID aus der DSN gelesen und in den darunterliegenden Feldern angezeigt.

[[Datei:Demo-dsn.svg|850px|DSN-Konfiguration im Demo-Fenster]]

Der Button <code>Set DSN</code> initialisiert Sentry mit der eingegebenen DSN. Quelle: <code>FSY_Demo.setDSN.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$init(iDSN)
Calculate $cclass.$ivardefs.iDSN.$objinitval as con(kSq,iDSN,kSq)

Do $cinst.$showmessage('DSN set and Sentry initialized!','Info')

Do $cinst.$redraw()
Quit method
</pre>

=== DB Status anzeigen ===

<code>FSY_Demo.$displayDBState</code> zeigt, ob die SQLite Session verbunden ist. Quelle: <code>FSY_Demo.$displayDBState</code>.

<pre>
Do tOSLSession.$state Returns dbState
If dbState='kSessionStateLoggedOff'
Calculate iCurrentDBStatus as 'Logged Off'
Else If dbState='kSessionStateLoggedOn'
Calculate iCurrentDBStatus as 'Logged On'
Else
Calculate iCurrentDBStatus as 'Unkown DB State'
End If

Do $cinst.$redraw()
Quit method
</pre>

=== Demo-Datenbank erstellen ===

Der Button <code>Create Database</code> ruft <code>ODatabaseHandler.$DBFirstInit</code> auf. Quelle: <code>FSY_Demo.createDB.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Setup the DB
Do tODatabaseHandler.$DBFirstInit() Returns err
If err=0
Do $cinst.$showmessage('DB successfully created!','Info')
Else
Do $cinst.$showmessage('Error while creating the DB. Make sure that the DB does not already exist.','Info')
End If

Do $cinst.$displayDBState()

Quit method
</pre>

Die Datenbank wird im Arbeitsverzeichnis der Library angelegt. Quelle: <code>ODatabaseHandler.$getWorkingDir</code>.

<pre>
Quit method con(FileOps.$parentdir($clib.$pathname),pathsep())
</pre>

Die Demo-DB enthält unter anderem:

* <code>dperson</code>
* <code>drelease</code>
* <code>dvcs</code>

=== Message auslösen ===

Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Log auslösen ===

Button <code>Trigger a log</code>. Quelle: <code>FSY_Demo.log.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception auslösen ===

Button <code>Trigger an exception</code> bereitet eine Row und eine List vor und ruft anschließend <code>ODummy.$dummyMethod</code> auf. Quelle: <code>FSY_Demo.exception.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do iDummyRow.$define(id,name)
Calculate iDummyRow.id as 22
Calculate iDummyRow.name as 'Tom'

Do iDummyList.$define(id,weekday)
Do iDummyList.$add(1,'Monday')
Do iDummyList.$add(2,'Tuesday')
Do iDummyList.$add(3,'Wednesday')
Do iDummyList.$add(4,'Thursday')
Do iDummyList.$add(5,'Friday')
Do iDummyList.$add(6,'Saturday')
Do iDummyList.$add(7,'Sunday')

Calculate iDummyList.$line as 5

Do iODummy.$dummyMethod('Important Value')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')

Quit method
</pre>

<code>ODummy.$dummyMethod</code> sendet die Exception. Quelle: <code>ODummy.$dummyMethod</code>.

<pre>
#In here is some logic
#This logic would produce an error
#We send all this information to Sentry

Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')

Quit method 0
</pre>

=== Deprecated Call auslösen ===

Button <code>Trigger a deprecated call</code>. Quelle: <code>FSY_Demo.deprecatedCall.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureDeprecatedCall()
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== SQL Exception Button ===

Der Button <code>Trigger an SQLException</code> ist im Export vorhanden, enthält aber noch keinen fertigen Demo-Code. Quelle: <code>FSY_Demo.sqlException.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Für die Dokumentation der SQL-Erfassung siehe [[#Events erfassen|03 Events erfassen]].

== API Reference ==

Diese Seite dokumentiert die produktiv relevanten Methoden von <code>OSentryHL</code> und <code>OSentry</code>.

=== OSentryHL ===

<code>OSentryHL</code> ist die empfohlene Klasse für Applikationscode.

'''<code>$init(pDSN)</code>'''

Initialisiert das interne <code>OSentry</code>-Objekt.

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

'''<code>$captureMessage(pMessage)</code>'''

Sendet eine einfache Info-Message.

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel)</code>'''

Sendet eine generische Exception.

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

'''<code>$captureAnything(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface)</code>'''

Sendet ein frei konfigurierbares Event.

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Hinweis: Der Parameter ist im Export als <code>pStacktraveInterface</code> geschrieben.

'''<code>$captureLog(pErrorText)</code>'''

Sendet ein Log-Event.

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

'''<code>$captureDeprecatedCall()</code>'''

Meldet die Ausführung eines veralteten Codepfads.

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

'''<code>$captureSQLException(pErrorText,pStat)</code>'''

Meldet einen SQL-Fehler mit SQL-Text und nativer Datenbankfehlermeldung.

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag für das nächste Event hinzu.

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra für das nächste Event hinzu.

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

'''<code>$setStatus(pStatus)</code>'''

Aktiviert oder deaktiviert Sentry.

<pre>
#Toggels Sentry on or off
Do iOSentry.$setStatus(pStatus)
Quit method
</pre>

'''<code>$setUser()</code>'''

Setzt im Export feste [[#Demo Library|Demo]]-Userdaten.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode parametrisiert werden.

=== OSentry ===

<code>OSentry</code> ist die Low-Level-Klasse für Payload-Erzeugung und Versand.

'''<code>$init(pDSN)</code>'''

Parst die DSN in Protokoll, Public Key, Host und Project ID.

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraceInterface,pUserInterface,pExceptionInterface)</code>'''

Erzeugt JSON, sendet es an Sentry und behandelt Fehlerfälle.

Parameter:

{| class="wikitable"
! Parameter !! Default !! Bedeutung
|-
| <code>pErrorText</code> || || Message
|-
| <code>pErrorCode</code> || || Fehlercode
|-
| <code>pExcType</code> || || Exception-Typ
|-
| <code>pLevel</code> || || <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code>, <code>debug</code>
|-
| <code>pStacktraceInterface</code> || <code>kTrue</code> || [[#Stacktrace und Kontext|Stacktrace]] senden
|-
| <code>pUserInterface</code> || <code>kTrue</code> || [[#Tags, Extras und User-Kontext|User-Kontext]] senden
|-
| <code>pExceptionInterface</code> || <code>kTrue</code> || Exception Interface senden
|}

'''<code>$generateJson(...)</code>'''

Erzeugt den Sentry JSON Payload als Binary.

'''<code>$generateStacktraceInterface(pCulprit)</code>'''

Erzeugt den Omnis-[[#Stacktrace und Kontext|Stacktrace]] inklusive Variablen und Kontextzeilen.

'''<code>$generateExceptionInterface(pType,pValue)</code>'''

Erzeugt das Sentry Exception Interface.

<pre>
# Generate Row to store in the JSON
Do exceptionRow.$define(type,value,stacktrace)
Calculate exceptionRow.type as pType
Calculate exceptionRow.value as pValue
Calculate exceptionRow.stacktrace as 'sentry.interfaces.stacktrace' ## Tells the exception interface that a stacktrace is passed aswell
</pre>

'''<code>$generateUserInterface()</code>'''

Erzeugt den [[#Tags, Extras und User-Kontext|User-Kontext]].

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag zur internen Tag-Liste hinzu.

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra zur internen Extra-Liste hinzu.

'''<code>$clearList()</code>'''

Leert [[#Tags, Extras und User-Kontext|Tags und Extras]] nach einem Request.

'''<code>$setUserData(pID,pName,pEmail)</code>'''

Setzt Userdaten für den nächsten Request.

'''<code>$setProxy(pProxyHost,pProxyPort)</code>'''

Setzt Proxy-Informationen.

'''<code>$setStatus(pStatus)</code>'''

Setzt den Sentry-Status.

<pre>
#Toggels Sentry Reports on or off
Calculate iStatus as pStatus
Quit method
</pre>

'''<code>$writeJSON(pJSON,pBuffer)</code>'''

Schreibt fehlgeschlagene Reports lokal in eine Datei.

'''<code>$getUnixTimestamp()</code>'''

Gibt den aktuellen UNIX Timestamp zurück.

'''<code>$generateUUID()</code>'''

Erzeugt eine UUID für die Sentry Event ID.

<pre>
#Genereates a UUID for the issue id
Quit method OW3.$makeuuid(kFalse)
</pre>

== Troubleshooting ==

=== Es erscheinen keine Events in Sentry ===

Prüfe zuerst, ob Sentry aktiv ist:

<pre>
Do tSentry.$setStatus(1)
</pre>

<code>OSentry.$captureException</code> beendet sich sofort, wenn der Status <code>0</code> oder leer ist:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

=== Die DSN ist falsch ===

Prüfe, ob die DSN korrekt aus Sentry kopiert wurde. <code>OSentry.$init</code> erwartet eine DSN, aus der Public Key, Host und Project ID gelesen werden können.

Nach dem Setzen der DSN sollten in der [[#Demo Library|Demo-Library]] folgende Felder gefüllt sein:

* Host
* Public Key
* Project ID

=== Netzwerk oder Proxy blockiert den Request ===

Wenn die Anwendung keinen direkten Zugriff auf Sentry hat, setze einen Proxy:

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Intern wird der Proxy vor dem HTTP Request gesetzt:

<pre>
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Report wird lokal gespeichert ===

Wenn <code>HTTPPost</code>, <code>HTTPSend</code> oder <code>HTTPRead</code> fehlschlägt, speichert OSentry den Report lokal:

<pre>
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
</pre>

Suche im Omnis-Installationsordner nach Dateien mit dem Namen:

<pre>
Sentryreport_<timestamp>.json
</pre>

=== Sentry antwortet nicht mit 200 OK ===

Wenn die HTTP-Antwort kein <code>200 OK</code> enthält, wird der JSON Report ebenfalls lokal gespeichert:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

Mögliche Ursachen:

* falsche Project ID
* falscher Public Key
* ungültige DSN
* JSON Payload wird von Sentry abgelehnt
* Netzwerk-Gateway verändert den Request

=== Tags oder Extras erscheinen beim falschen Event ===

[[#Tags, Extras und User-Kontext|Tags und Extras]] werden für den nächsten Request gesammelt. Nach erfolgreichem Request werden sie gelöscht:

<pre>
Do iTagList.$clear()
Do iExtraList.$clear()
</pre>

Wenn ein Request fehlschlägt, wird ebenfalls aufgeräumt:

<pre>
Do $cinst.$clearList()
</pre>

Prüfe trotzdem, ob in eigenen Wrapper-Methoden Tags und Extras direkt vor dem passenden Capture-Aufruf gesetzt werden.

=== User-Kontext zeigt Demo-Daten ===

<code>OSentryHL.$setUser</code> verwendet im Export feste Testdaten:

<pre>
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
</pre>

Für produktive Nutzung sollte die Methode parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
</pre>

=== SQL Exception Demo-Button funktioniert nicht ===

Der Button <code>Trigger an SQLException</code> ist im Export noch nicht implementiert:

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Die produktive Methode für SQL-Fehler ist aber vorhanden. Siehe auch [[#Events erfassen|Events erfassen]].

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

=== Zu viele Events ===

Sentry kann sehr schnell viele Events sammeln. Verwende für produktive Systeme:

* klare Wrapper-Methoden in <code>OSentryHL</code>
* sinnvolle Levels
* gezielte [[#Tags, Extras und User-Kontext|Tags]]
* keine Events in sehr häufigen Schleifen
* keine rein informativen Debug-Events ohne Nutzen

=== Sensible Daten ===

[[#Stacktrace und Kontext|Stacktrace]], Parameter, Instance Variablen, SQL-Text und [[#Tags, Extras und User-Kontext|Extras]] können sensible Daten enthalten. Prüfe vor produktiver Nutzung:

* Welche Variablen werden übertragen?
* Enthalten SQL-Statements personenbezogene Daten?
* Werden Tokens oder Passwörter in Extras geschrieben?
* Sollen bestimmte Werte maskiert werden?

Sentry

2026-06-12T14:06:27Z

Silvan: /* Screenshots */

__TOC__

== Überblick ==

OSentry ist ein REST-API-Konnektor von Omnis Studio zu Sentry. Der Konnektor sendet Fehler, Messages, Logs und Laufzeitkontext aus Omnis-Anwendungen an Sentry, damit Probleme in produktiven Systemen sichtbar, gruppierbar und analysierbar werden.

Diese Dokumentation beschreibt die [[#Installation|Installation]], die Nutzung in bestehenden Omnis-Anwendungen, die Definition eigener standardisierter Exception-Typen, die interne Struktur und die [[#Demo Library|Demo-Library]].

=== Kernidee ===

OSentry besteht aus zwei produktiv relevanten Klassen:

* <code>OSentryHL</code>: High-Level-Adapter für die Anwendung. Diese Klasse sollte von normalem Applikationscode aufgerufen werden.
* <code>OSentry</code>: Low-Level-Adapter für DSN-Parsing, JSON-Erzeugung, [[#Stacktrace und Kontext|Stacktrace]]-Aufbereitung und HTTP-Kommunikation mit Sentry.

Die Anwendung arbeitet im Normalfall mit <code>OSentryHL</code>. Dadurch bleiben Sentry-spezifische Details zentral gekapselt und neue standardisierte Exception-Typen können als eigene Methoden in <code>OSentryHL</code> definiert werden.

=== Hauptfeatures ===

* Direkte Anbindung von Omnis Studio an Sentry über REST API und DSN
* Erfassen von Exceptions, Messages, Logs und SQL-Fehlern
* Unterstützung der Sentry-Level <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code> und <code>debug</code>
* Automatische Omnis-Kontextinformationen
* Omnis-[[#Stacktrace und Kontext|Stacktrace]] mit Klassen, Methoden, Zeilen und Variablen
* [[#Tags, Extras und User-Kontext|Tags]] für Filterung und Gruppierung
* [[#Tags, Extras und User-Kontext|Extras]] für zusätzliche Diagnoseinformationen
* Optionaler [[#Tags, Extras und User-Kontext|User-Kontext]]
* Proxy-Unterstützung
* Aktivieren und Deaktivieren der Sentry-Übertragung
* Lokales Speichern von Reports bei Übertragungsfehlern

=== Weiterführende Links ===

* [https://sentry.io/welcome/ Sentry Website]
* [https://sentry.io/signup/ Sentry Account erstellen]
* [https://develop.sentry.dev/self-hosted/ Sentry self-hosted]

== Installation ==

Diese Seite beschreibt, wie OSentry in eine bestehende Omnis-Anwendung integriert wird.

=== Voraussetzungen ===

* Omnis Studio Anwendung
* Sentry Account oder self-hosted Sentry Installation
* Ein Sentry-Projekt mit SDK-Typ <code>Other</code>
* Die DSN des Sentry-Projekts
* Netzwerkzugriff auf Sentry

Die exportierte [[#Demo Library|Demo-Library]] wurde mit Omnis <code>11.1</code> erstellt.

=== Sentry-Projekt erstellen ===

# In Sentry ein neues Projekt erstellen.
# Als SDK <code>Other</code> auswählen.
# Die DSN des Projekts kopieren.

Die DSN wird beim Initialisieren verwendet. <code>OSentry</code> zerlegt sie intern in Public Key, Host und Project ID.

[[Datei:Sentry-projects.png|900px|Sentry Projektübersicht]]

=== Klassen kopieren ===

Kopiere die folgenden Klassen in deine bestehende Omnis-Library:

* <code>OSentry</code>
* <code>OSentryHL</code>

Die Demo-spezifischen Klassen sind für die produktive Integration nicht erforderlich. Damit sind die übrigen Klassen der Demo-Library gemeint, zum Beispiel <code>FSY_Demo</code>, <code>ODummy</code>, <code>ODatabaseHandler</code> und <code>OSLSession</code>. Diese Klassen dienen nur dazu, die [[#Demo Library|Demo-Library]] mit Fenster, SQLite-Testdaten und Beispielaufrufen auszuführen.

=== Task Variable anlegen ===

Lege in deiner Startup Task eine Task Variable an:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' <code>tSentry</code> sollte als global erreichbarer Singleton der Anwendung verwendet werden. In Omnis ist dafür eine Task Variable sinnvoll, weil sie von Fenstern, Objektklassen und zentralen Error-Handlern aus konsistent erreichbar ist. Dadurch gibt es genau eine aktive Sentry-Konfiguration mit einer DSN, einem Status, optionalen Proxy-Daten und gemeinsamen Wrapper-Methoden in <code>OSentryHL</code>.</div>

Im [[#Demo Library|Demo-Projekt]] ist diese Variable in <code>Startup_Task</code> definiert.

=== Initialisierung im Startup Task ===

Initialisiere <code>tSentry</code> beim Start deiner Anwendung mit der DSN deines Sentry-Projekts:

<pre>
Do tSentry.$init('<DSN>')
</pre>

Die [[#Demo Library|Demo-Library]] ruft im Startup Task ebenfalls die Initialisierung auf. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()
</pre>

In einer produktiven Anwendung sollte die DSN explizit oder aus einer Konfiguration übergeben werden:

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Speichere die DSN in einer Datenbank, einer Konfigurationstabelle oder einem Config File. So kann sie pro Kunde, Umgebung oder Installation geändert werden, ohne die Library neu auszuliefern.</div>

=== Testcall ===

Nach der Initialisierung kann ein erstes Testevent gesendet werden:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Wenn alles korrekt eingerichtet ist, erscheint das Event im Sentry-Projekt.

=== Proxy konfigurieren ===

Falls die Anwendung in einem geschützten Netzwerk läuft, kann ein Proxy gesetzt werden. Die Methode befindet sich im Low-Level-Objekt <code>OSentry</code>.

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Die interne Implementierung setzt den Proxy vor dem HTTP-Request:

<pre>
#Configure proxy; needed when sending data out of secured networks
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Sentry aktivieren oder deaktivieren ===

OSentry kann zentral ein- oder ausgeschaltet werden.

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Deaktiviere Sentry in der Entwicklungs-Version standardmäßig oder verwende eine separate Entwicklungs-DSN. So landen lokale Tests, Debug-Fehler und absichtlich ausgelöste Exceptions nicht im produktiven Sentry-Projekt.</div>

<pre>
Do tSentry.$setStatus(1) ## aktiv
Do tSentry.$setStatus(0) ## inaktiv
</pre>

Im Low-Level-Objekt <code>OSentry</code> wird vor dem Senden geprüft:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

== Quickstart ==

Diese Seite zeigt die minimale Integration in eine bestehende Omnis-Anwendung.

=== Klassen übernehmen ===

Kopiere <code>OSentry</code> und <code>OSentryHL</code> in deine Library.

=== Task Variable erstellen ===

In der Startup Task:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

=== Sentry initialisieren ===

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<code>OSentryHL.$init</code> delegiert an das Low-Level-Objekt <code>OSentry</code>:

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

=== Message senden ===

<pre>
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
</pre>

Die [[#Demo Library|Demo-Library]] verwendet genau diesen Aufruf im Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception senden ===

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

=== In Sentry prüfen ===

In Sentry sollte anschließend ein neues Event sichtbar sein. Je nach Event-Typ enthält es:

* Message
* Level
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Tags, Extras und User-Kontext|User-Kontext]]
* [[#Stacktrace und Kontext|Stacktrace]]
* Omnis-Kontextinformationen

== Events erfassen ==

OSentryHL ist die empfohlene Einstiegsschicht für Applikationscode. Die Klasse bietet sprechende Methoden für typische Event-Arten und ruft intern <code>OSentry.$captureException</code> auf.

=== Message ===

Eine einfache Information wird mit <code>$captureMessage</code> gesendet:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

Verhalten:

* Level: <code>info</code>
* Kein [[#Stacktrace und Kontext|Stacktrace]]
* Kein [[#Tags, Extras und User-Kontext|User Interface]]
* Geeignet für einfache Statusmeldungen oder technische Hinweise

=== Log ===

Ein Log-Event wird mit <code>$captureLog</code> gesendet:

<pre>
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

Verhalten:

* Level: <code>warning</code>
* [[#Stacktrace und Kontext|Stacktrace]] aktiv
* Exception Interface in diesem Wrapper deaktiviert
* [[#Tags, Extras und User-Kontext|User Interface]] aktiv

=== Generische Exception ===

Eine generische Exception wird mit <code>$captureException</code> gesendet:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

Parameter:

{| class="wikitable"
! Parameter !! Bedeutung
|-
| <code>pErrorText</code> || Text, der in Sentry als Message sichtbar ist
|-
| <code>pErrorCode</code> || Fehlercode oder fachlicher Code
|-
| <code>pExcType</code> || Exception-Typ für Benennung und Gruppierung
|-
| <code>pLevel</code> || Sentry-Level
|}

Gültige Levels:

* <code>fatal</code>
* <code>error</code>
* <code>warning</code>
* <code>info</code>
* <code>debug</code>

=== SQL Exception ===

SQL-Fehler können mit <code>$captureSQLException</code> gemeldet werden.

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

Verhalten:

* Fügt die Datenbank als [[#Tags, Extras und User-Kontext|Tag]] hinzu
* Fügt SQL-Text als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Fügt native Datenbankfehlermeldung als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Sendet das Event als <code>SQL-Exception</code> mit Level <code>error</code>

=== Deprecated Call ===

Veraltete Codepfade können gezielt gemeldet werden:

<pre>
Do tSentry.$captureDeprecatedCall()
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

Dieser Wrapper eignet sich, um zu erkennen, ob alter Code in produktiven Systemen noch ausgeführt wird.

=== Frei konfigurierbares Event ===

Für Sonderfälle gibt es <code>$captureAnything</code>:

<pre>
Do tSentry.$captureAnything('Text',1001,'Custom Type','error',kTrue,kTrue,kTrue)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Diese Methode bietet maximale Flexibilität. Für wiederkehrende Exception-Typen sollte aber eine eigene Methode in <code>OSentryHL</code> angelegt werden. Siehe [[#Eigene Exceptions standardisieren|04 Eigene Exceptions standardisieren]].

== Eigene Exceptions standardisieren ==

Wenn ein Exception-Typ mehrfach in der Anwendung vorkommt, sollte er nicht überall manuell mit <code>$captureException</code> aufgebaut werden. Besser ist eine eigene Methode in <code>OSentryHL</code>.

Dadurch entsteht eine zentrale, wiederverwendbare Definition für:

* Exception-Typ
* Sentry-Level
* Fehlercode
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Stacktrace und Kontext|Stacktrace]]/[[#Tags, Extras und User-Kontext|User]]/Exception Interface

Die automatisch gesetzten [[#Tags, Extras und User-Kontext|Tags und Extras]] aus <code>OSentry.$generateJson</code> müssen in solchen Wrappern nicht erneut ergänzt werden. Eigene Exception-Methoden setzen nur zusätzliche Werte, die für diesen standardisierten Exception-Typ relevant sind.

=== Warum über OSentryHL? ===

<code>OSentryHL</code> ist die Abstraktionsschicht für Applikationscode. Sie kapselt die Details von <code>OSentry</code> und sorgt dafür, dass Aufrufe in der Anwendung kurz und konsistent bleiben.

Bestehende Beispiele aus <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

=== Empfohlenes Muster ===

Für jeden standardisierten Exception-Typ wird eine eigene Methode in <code>OSentryHL</code> erstellt.

Beispiel:

<pre>
# Captures a validation exception
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addExtra('Field',pField)
Do $cinst.$addExtra('Invalid Value',pValue)

Do iOSentry.$captureException(pErrorText,2001,'Validation-Exception','warning',1,1,1) Returns code

Quit method code
</pre>

Mögliche Parameter der neuen Methode:

{| class="wikitable"
! Parameter !! Beispiel !! Zweck
|-
| <code>pErrorText</code> || <code>'Invalid customer number'</code> || Sentry Message
|-
| <code>pModule</code> || <code>'Customer'</code> || Filterbarer Tag
|-
| <code>pField</code> || <code>'cu_number'</code> || Diagnoseinformation
|-
| <code>pValue</code> || <code>'ABC'</code> || Diagnoseinformation
|}

Der Applikationscode bleibt dadurch einfach:

<pre>
Do tSentry.$captureValidationException('Invalid customer number','Customer','cu_number',cu_number)
</pre>

=== Beispiel: Business Rule Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures a business rule violation
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do $cinst.$addExtra('Details',pDetails)

Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureBusinessRuleViolation('Invoice cannot be posted','Invoice','PostingAllowed','Invoice is missing customer')
</pre>

=== Beispiel: Integration Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures an integration exception
Do $cinst.$addTag('Integration',pSystem)
Do $cinst.$addTag('Endpoint',pEndpoint)
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)

Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureIntegrationException('External API request failed','ERP','/api/customer',jsonPayload,responseText)
</pre>

=== Namenskonventionen ===

Empfehlung für neue Methoden:

* Methodenname beginnt mit <code>$capture</code>
* Der fachliche Typ steht im Methodennamen
* Der Sentry Exception Type ist stabil und ändert sich nicht laufend
* [[#Tags, Extras und User-Kontext|Tags]] sind kurz und filterbar
* [[#Tags, Extras und User-Kontext|Extras]] dürfen länger sein und Diagnoseinformationen enthalten

Beispiele:

* <code>$captureValidationException</code>
* <code>$captureBusinessRuleViolation</code>
* <code>$captureIntegrationException</code>
* <code>$capturePermissionViolation</code>
* <code>$captureConfigurationError</code>

=== Error Codes ===

Verwende feste Fehlercodes für standardisierte Exception-Typen. Dadurch können Events in Sentry besser gefiltert und wiedererkannt werden.

Beispiel:

{| class="wikitable"
! Code !! Exception Type
|-
| <code>2001</code> || <code>Validation-Exception</code>
|-
| <code>3001</code> || <code>Business-Rule-Violation</code>
|-
| <code>4001</code> || <code>Integration-Exception</code>
|-
| <code>5001</code> || <code>Configuration-Error</code>
|}

=== Wann nicht standardisieren? ===

Nicht jeder Einzelfall braucht eine eigene Methode. Für einmalige technische Tests oder sehr spezielle Fälle reicht:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Sobald ein Exception-Typ aber mehrfach vorkommt oder fachlich relevant ist, sollte er als eigene Methode in <code>OSentryHL</code> definiert werden.

== Tags, Extras und User-Kontext ==

Tags, Extras und User-Kontext reichern Sentry-Events mit zusätzlichen Informationen an. Diese Informationen helfen beim Filtern, Gruppieren und Analysieren.

[[Datei:Sentry-tags.png|900px|Sentry Tags und User-Kontext]]

=== Tags ===

Tags sind kurze, filterbare Werte.

Beispiele:

* Datenbank
* Kunde
* Modul
* Umgebung
* Error Code
* Omnis-Version

Methode in <code>OSentryHL</code>:

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds a tag to the next request processed
Do iTagList.$add(pName,pValue)
Quit method
</pre>

Beispiel:

<pre>
Do tSentry.$addTag('Module','Invoice')
Do tSentry.$addTag('Customer','10001')
Do tSentry.$captureException('Invoice posting failed',3001,'Business-Rule-Violation','warning')
</pre>

=== Extras ===

Extras sind Detailinformationen, die nicht primär zum Filtern gedacht sind.

Beispiele:

* SQL-Text
* Native Datenbankfehlermeldung
* Payload
* Response Body
* interne IDs
* zusätzliche Debug-Informationen

Methode in <code>OSentryHL</code>:

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds extra information to the next request being processed
Do iExtraList.$add(pName,pValue)
Quit method
</pre>

Beispiel aus der SQL Exception:

<pre>
Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)
</pre>

=== Automatische Tags ===

Die folgenden Tags werden bei jedem Event automatisch von <code>OSentry.$generateJson</code> ergänzt. Sie müssen bei eigenen Exceptions nicht erneut gesetzt werden. Eigene Wrapper-Methoden in <code>OSentryHL</code> sollten nur zusätzliche, fachlich oder technisch relevante Tags hinzufügen.

<code>OSentry.$generateJson</code> fügt mehrere Tags automatisch hinzu:

<pre>
# Add static tags
Do iTagList.$add('Omnisversion',sys(1))
Calculate systemversionRow as systemversion()
Do iTagList.$add('Plattform',con(sys(8),pick(systemversionRow.server,'',' SRV')))
Do iTagList.$add('OS Version',con(systemversionRow.major,'.',systemversionRow.minor,'.',systemversionRow.build))
Do iTagList.$add('error_code',pErrorCode)
</pre>

Automatisch gesendete Tags:

{| class="wikitable"
! Tag !! Herkunft !! Zweck
|-
| <code>Omnisversion</code> || <code>sys(1)</code> || Zeigt, mit welcher Omnis-Version das Event erzeugt wurde
|-
| <code>Plattform</code> || <code>sys(8)</code> und Server-Flag aus <code>systemversion()</code> || Unterscheidet Plattform und Server Runtime
|-
| <code>OS Version</code> || <code>systemversionRow.major/minor/build</code> || Zeigt die Betriebssystemversion
|-
| <code>error_code</code> || Parameter <code>pErrorCode</code> || Verbindet das Event mit dem übergebenen Fehlercode
|}

Beispiel für eine eigene Exception: Der Wrapper muss nicht erneut <code>Omnisversion</code> oder <code>OS Version</code> setzen. Er ergänzt nur das, was für diesen Exception-Typ zusätzlich hilfreich ist.

<pre>
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code
</pre>

=== Automatische Extras ===

Auch die folgenden Extras werden bei jedem Event automatisch ergänzt. Bei eigenen Exceptions müssen nur zusätzliche Extras gesetzt werden, zum Beispiel ein SQL-Statement, ein Payload oder fachliche Zusatzdaten.

<code>OSentry.$generateJson</code> fügt offene Fenster, offene Reports und die aktuelle Printfile hinzu:

<pre>
# Static extra 1: All open windows
Do $root.$iwindows.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate windows as con(windows,', ',nameList.[i].1)
End For
Calculate windows as right(windows,len(windows)-2)
Do iExtraList.$add('Open Windows',windows)

# Static extra 2: All open reports
Do $root.$ireports.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate reports as con(reports,', ',nameList.[i].1)
End For
Calculate reports as right(reports,len(reports)-2)
Do iExtraList.$add('Open Reports',reports)
Do iExtraList.$add('Current Printfile',$root.$prefs.$printfile)
</pre>

Automatisch gesendete Extras:

{| class="wikitable"
! Extra !! Herkunft !! Zweck
|-
| <code>Open Windows</code> || <code>$root.$iwindows.$makelist($ref.$name)</code> || Zeigt, welche Fenster im Moment des Events offen waren
|-
| <code>Open Reports</code> || <code>$root.$ireports.$makelist($ref.$name)</code> || Zeigt, welche Reports im Moment des Events offen waren
|-
| <code>Current Printfile</code> || <code>$root.$prefs.$printfile</code> || Zeigt die aktuell gesetzte Printfile
|}

Beispiel für zusätzliche Extras in einem eigenen Wrapper:

<pre>
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)
Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code
</pre>

=== User-Kontext ===

Der User-Kontext ordnet ein Event einem betroffenen Benutzer zu. In Sentry erscheint dadurch ein eigener User-Bereich, und Events können nach Benutzer gefiltert oder gruppiert werden. Das ist besonders hilfreich, wenn ein Fehler nur bei einzelnen Kunden, Arbeitsplätzen oder Benutzerkonten auftritt.

<code>OSentry</code> unterstützt drei User-Felder:

{| class="wikitable"
! Feld !! Bedeutung
|-
| <code>id</code> || stabile interne Benutzer-ID oder Kundennummer
|-
| <code>username</code> || lesbarer Benutzername
|-
| <code>email</code> || E-Mail-Adresse, falls sie übertragen werden darf
|}

Der User-Kontext wird nur in das Event geschrieben, wenn das User Interface beim Capture-Aufruf aktiviert ist. Die Standardmethode <code>OSentry.$captureException</code> hat <code>pUserInterface</code> standardmäßig auf <code>kTrue</code>. Einzelne High-Level-Methoden können das bewusst deaktivieren, zum Beispiel <code>$captureMessage</code>.

<code>OSentry</code> kann User-Daten an das Event anhängen:

<pre>
#Sets userinformation for the next request being processed
Calculate iUserID as pID
Calculate iUserName as pName
Calculate iUserEmail as pEmail
Quit method
</pre>

Das User Interface wird so generiert:

<pre>
# Create user data row
Do UserdataRow.$define(id,email,username)

Calculate UserdataRow.id as iUserID
Calculate UserdataRow.email as iUserEmail
Calculate UserdataRow.username as iUserName

Do JSON.$addmember('','user','')
Do JSON.$setobject('user',UserdataRow)

Calculate jsonString as OJSON.$formatjson(JSON.$getjson())

Quit method jsonString
</pre>

Die aktuelle Demo-Methode in <code>OSentryHL</code> verwendet feste Testdaten. Quelle: <code>OSentryHL.$setUser</code>.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode angepasst und parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
Quit method
</pre>

Empfohlen ist, den User nach Login oder beim Wechsel des aktiven Benutzers zentral zu setzen. Bei anonymen oder sensiblen Installationen kann statt Name und E-Mail auch nur eine interne ID oder ein pseudonymisierter Wert verwendet werden.

=== Datenschutz ===

<div style="border-left:4px solid #72777d; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Datenschutz:''' Prüfe vor produktiver Nutzung, welche Daten an Sentry gesendet werden. Besonders kritisch sind personenbezogene Daten, SQL-Statements, Zugangsdaten, Tokens und interne Pfade.</div>

Besonders kritisch sind:

* personenbezogene Daten
* Kundendaten
* SQL-Statements mit Werten
* Zugangsdaten
* Tokens
* interne Pfade

Tags und Extras sollten so gestaltet werden, dass sie für die Fehleranalyse hilfreich sind, aber keine unnötigen sensiblen Daten übertragen.

== Stacktrace und Kontext ==

<code>OSentry</code> erzeugt einen Omnis-spezifischen Stacktrace und übergibt ihn an Sentry. Dadurch sieht man in Sentry nicht nur eine Fehlermeldung, sondern auch Klassen, Methoden, Zeilen und Variablenkontext. Ergänzende Informationen zu [[#Tags, Extras und User-Kontext|Tags, Extras und User-Kontext]] stehen auf der separaten Kontext-Seite.

[[Datei:Sentry-stack.png|900px|Sentry Stacktrace mit Omnis-Kontext]]

=== Stack lesen ===

<code>OSentry.$generateStacktraceInterface</code> verwendet <code>sys(192)</code>, um den aktuellen Omnis-Stack zu lesen:

<pre>
# Clean up the Stacklist (remove OSentry classes from the stack)
Do sys(192) Returns sys192List
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
If pos('OSentry',class.$name)>0|pos('OSentryHL',class.$name)>0
Do sys192List.[sys192List.$line].$selected.$assign(kTrue)
End If
End For
Do sys192List.$remove(kListDeleteSelected)
</pre>

Interne Frames von <code>OSentry</code> und <code>OSentryHL</code> werden entfernt, damit in Sentry die fachlich relevanten Stellen sichtbar bleiben.

=== SQL-Error Frames entfernen ===

Bestimmte interne SQL-Fehlerframes werden ebenfalls entfernt:

<pre>
# Remove some other classes which we do not want to display
If sys192List.1.method='$sqlerror'
Do sys192List.$remove(1)
Else If sys192List.1.method='$statementerror'
Do sys192List.$remove(1)
End If
</pre>

=== Frames erzeugen ===

Für jeden Stack-Eintrag werden Funktion, Zeilennummer und Kontextzeile erzeugt:

<pre>
#Loop through every item on the omnis stack
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
Calculate className as class.$name

# Create the content row
Do contentRow.$define(vars,function,pre_context,context_line,lineno,filename,post_context)
Calculate contentRow.lineno as sys192List.line
Calculate contentRow.filename as testFileName
Calculate contentRow.context_line as sys192List.linetext
If isclear(sys192List.object)
Calculate contentRow.function as con(className,'.',sys192List.method) ## If it's a class method
Else
Calculate contentRow.function as con(className,'.',sys192List.object,'.',sys192List.method) ## If it's a method of an object of a class (e.g. Headedlist)
End If
Do contentList.$add(contentRow)
End For
</pre>

=== Variablen aufnehmen ===

Pro Stackframe werden Instance Variablen und Parameter gesammelt:

<pre>
# Get all iVars
Do varList.$define(name,value)
Set reference class to sys192List.inst
Do $cinst.$getVars('ivars',class) Returns varList

# Get all params
Calculate paramList as sys192List.params
For paramList.$line from 1 to paramList.$linecount step 1
If not(paramList.value='(Not empty)')
Do varList.$add(paramList.name,paramList.value)
Else
Do varList.$add(paramList.name,'(Not empty)')
End If
End For
</pre>

=== Pre- und Post-Context ===

OSentry fügt Methodenzeilen vor und nach der aktuellen Zeile hinzu:

<pre>
# Pre Context (all method lines before the error occured)
Set reference method to sys192List.methoditem
Do precontextList.$define(line)
For i from 1 to sys192List.line-1 step 1
Do precontextList.$add(method.$methodlines.[i].$text)
End For

# Post Context (all method lines after the error occured
Do postcontextList.$define(line)
For i from sys192List.line+1 to method.$methodlines.$count step 1
Do postcontextList.$add(method.$methodlines.[i].$text)
End For
</pre>

=== Variablentypen ===

<code>OSentry.$getVars</code> unterstützt Basisvariablen, Rows und Lists.

Basisvariablen:

<pre>
If varType='char'|varType='boolean'|varType='integer'|varType='number'|varType='date'
Calculate varContent as pItemRef.$[pVarType].[varName]
Do varList.$add(varName,varContent)
</pre>

Rows:

<pre>
Else If varType='row'
Calculate varRow as pItemRef.$[pVarType].[varName]
If varRow.$colcount=0
Do varList.$add(varName,'(Empty)')
Else
For Z2 from 1 to varRow.$colcount step 1
Calculate varContent as con(varContent,varRow.$cols.[Z2].$name,': ',varRow.[Z2],', ')
End For
Do varList.$add(varName,varContent)
</pre>

Lists:

<pre>
Else If varType='list'
Calculate varListType as pItemRef.$[pVarType].[varName]
Calculate varContent as con('Colcount: ',varListType.$colcount,', ','Linecount: ',varListType.$linecount,', ','Current Line: ',varListType.$line)
If varListType.$linecount=0&varListType.$line=0&varListType.$colcount=0
Do varList.$add(varName,'(Empty)')
Calculate varContent as ''
Else
For Z3 from 1 to varListType.$colcount step 1
Calculate colName as varListType.$cols.[Z3].$name
Calculate varContent as con(varContent,' ',colName,': ',varListType.[colName])
End For
Do varList.$add(varName,varContent)
Calculate varContent as ''
End If
End If
</pre>

=== Hinweise ===

Stacktrace und Variablenkontext sind sehr hilfreich, können aber sensible Daten enthalten. Vor produktiver Nutzung sollte geprüft werden, ob bestimmte Variablen anonymisiert oder ausgeschlossen werden müssen.

== Interne Architektur ==

Diese Seite beschreibt die produktiv relevanten Klassen <code>OSentryHL</code> und <code>OSentry</code>.

=== Klassenübersicht ===

{| class="wikitable"
! Klasse !! Rolle
|-
| <code>OSentryHL</code> || High-Level-Adapter für Applikationscode
|-
| <code>OSentry</code> || Low-Level-Adapter für JSON, [[#Stacktrace und Kontext|Stacktrace]] und HTTP
|-
| <code>Startup_Task</code> || [[#Demo Library|Demo]]-Startup und Beispiel für Initialisierung
|-
| <code>FSY_Demo</code> || [[#Demo Library|Demo]]-Fenster
|-
| <code>ODummy</code> || [[#Demo Library|Demo]]-Code für [[#Stacktrace und Kontext|Stacktrace]]-Beispiel
|-
| <code>ODatabaseHandler</code> || [[#Demo Library|Demo]]-DB Initialisierung
|-
| <code>OSLSession</code> || SQLite Session für [[#Demo Library|Demo]]
|}

=== Empfohlener Aufrufweg ===

Applikationscode sollte <code>OSentryHL</code> verwenden:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

<code>OSentryHL</code> delegiert anschließend an <code>OSentry</code>:

<pre>
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code
</pre>

=== Ablauf eines Events ===

# Applikationscode ruft Methode in <code>OSentryHL</code> auf.
# <code>OSentryHL</code> fügt bei Bedarf [[#Tags, Extras und User-Kontext|Tags und Extras]] hinzu.
# <code>OSentryHL</code> ruft <code>iOSentry.$captureException(...)</code> auf.
# <code>OSentry</code> prüft, ob Sentry aktiv ist.
# <code>OSentry</code> erzeugt JSON.
# [[#Stacktrace und Kontext|Stacktrace]], Exception Interface und [[#Tags, Extras und User-Kontext|User Interface]] werden optional ergänzt.
# HTTP Header und Sentry Auth Header werden erstellt.
# JSON wird per HTTPS an Sentry gesendet.
# Bei Erfolg werden [[#Tags, Extras und User-Kontext|Tags und Extras]] geleert.
# Bei Fehler wird der JSON Report lokal gespeichert.

=== DSN Parsing ===

<code>OSentry.$init</code> zerlegt die DSN:

<pre>
# Parse the DSN into Public Key, Host and Project ID
If len(pDSN)>5
Calculate iDSN as pDSN
Calculate part1 as strtok('iDSN','@')
Calculate iProtocol as strtok('part1','/')
Calculate iProtocol as left(iProtocol,len(iProtocol)-1)
Do strtok('part1','/')
Calculate iPubKey as strtok('part1',':')

Calculate iHost as strtok('iDSN','/')
Calculate iProID as iDSN

#Save the values for the next startup
Calculate $cclass.$ivardefs.iPubKey.$objinitval as con('"',iPubKey,'"')
Calculate $cclass.$ivardefs.iHost.$objinitval as con('"',iHost,'"')
Calculate $cclass.$ivardefs.iProID.$objinitval as con('"',iProID,'"')
End If

Quit method
</pre>

=== JSON-Erzeugung ===

<code>OSentry.$generateJson</code> ist die zentrale Methode für den Payload. Sie setzt unter anderem:

* <code>event_id</code>
* <code>logger</code>
* <code>platform</code>
* <code>culprit</code>
* <code>timestamp</code>
* <code>sdk</code>
* <code>message</code>
* <code>level</code>
* <code>tags</code>
* <code>extra</code>
* optional <code>user</code>
* optional <code>exception</code>
* optional <code>stacktrace</code>

Auszug:

<pre>
# Add all required fields (those are required from the API)
Do JSON.$addmember('','event_id',$cinst.$generateUUID()) ## auto generated UUID 4
Do JSON.$addmember('','logger',logger)
Do JSON.$addmember('','platform',platform)
Do JSON.$addmember('','culprit',culprit)
#Do JSON.$addmember('','release',release)
Do JSON.$addmember('','timestamp',timestamp)
Do JSON.$addmember('','sdk','')
Do JSON.$addmember('','message',pErrorText)
Do JSON.$addmember('','level',pLevel)
Do JSON.$addmember('','tags','')
</pre>

=== HTTP-Kommunikation ===

<code>OSentry.$captureException</code> sendet den erzeugten JSON-Payload an Sentry:

<pre>
#Generate HTTP Auth header
Begin text block
Text:Sentry sentry_version=7,
Text:sentry_timestamp=[$cinst.$getUnixTimestamp()],
Text:sentry_key=[iPubKey],
Text:sentry_client=omnis/1.0
End text block
Get text block auth

#Generate header list
Calculate Host as 'sentry.io'
Calculate Url as con('/api/',iProID,'/store/')
Do HdrList.$define(wert,name)
Do HdrList.$add('User-Agent','omnis/1.0')
Do HdrList.$add('Content-Type','application/json')
Do HdrList.$add('Content-Length',binlength(json))
Do HdrList.$add('X-Sentry-Auth',auth)
</pre>

Anschließend wird der Request über <code>HTTPPost</code>, <code>HTTPSend</code> und <code>HTTPRead</code> ausgeführt.

=== Fehlerbehandlung beim Senden ===

Wenn der Socket nicht geöffnet werden kann:

<pre>
HTTPPost (Host,Url,,HdrList,443,kTrue,kTrue) Returns Socket
If Socket<0
#Error when opening connection -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Error ',Socket,' when performing HTTPPost'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -1
End If
</pre>

Wenn das Senden fehlschlägt:

<pre>
HTTPSend (Socket,json) Returns byteCount
If byteCount<0
# Error while sending data -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Erorr ',byteCount,' when performing HTTPSend'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -2
End If
</pre>

Wenn die Antwort nicht erfolgreich ist:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

=== Lokales Speichern ===

Bei Fehlern wird der JSON Report lokal im Omnis-Installationsordner gespeichert:

<pre>
#Writes the json and the http buffer to a file in the omnis installation folder
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
Do fOP.$writecharacter(kUniTypeUTF8,pJSON) Returns err
If not(isclear(pBuffer))
Do fOP.$writecharacter(kUniTypeUTF8,con(kCr,pBuffer),kTrue) Returns err
End If
Do fOP.$closefile()

Quit method
</pre>

=== Cleanup ===

Nach erfolgreichem Senden werden [[#Tags, Extras und User-Kontext|Tags und Extras]] gelöscht:

<pre>
#Clears all extras and tags => to be used after a sentry request has successfully been sent
Do iTagList.$clear()
Do iExtraList.$clear()
Quit method
</pre>

== Demo Library ==

Die Demo-Library zeigt, wie <code>OSentry</code> initialisiert wird und wie verschiedene [[#Events erfassen|Event-Typen]] aus einer Omnis-Oberfläche heraus an Sentry gesendet werden.

=== Bestandteile ===

{| class="wikitable"
! Klasse !! Zweck
|-
| <code>Startup_Task</code> || Initialisiert Sentry, SQLite und öffnet das Demo-Fenster
|-
| <code>FSY_Demo</code> || Demo-Fenster
|-
| <code>ODummy</code> || Erzeugt Demo-Stack für Exception
|-
| <code>ODatabaseHandler</code> || Erstellt SQLite-Demo-Datenbank
|-
| <code>OSLSession</code> || SQLite Session
|-
| <code>OSentry</code> || Low-Level-Sentry-Adapter
|-
| <code>OSentryHL</code> || High-Level-Sentry-Adapter
|}

=== Startup ===

<code>Startup_Task.$construct</code> initialisiert Sentry, baut eine SQLite Session auf und öffnet das Demo-Fenster. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()

#SQLite Session init
Do $objects.OSLSession.$newref() Returns tOSLSession
#Calculate tOSLSession.$opencreate as kTrue
Calculate workingDir as tODatabaseHandler.$getWorkingDir()
Do con(workingDir,'Sentry_Test.db') Returns dbLocation
Do tOSLSession.$logon(dbLocation,'','','slsession') Returns #F

#Open Test Window
Do $windows.FSY_Demo.$openonce('*')

Quit method
</pre>

=== Demo-Fenster ===

<code>FSY_Demo</code> enthält folgende Bereiche:

* DSN Configuration
* DB Status
* Actions

Wichtige Felder:

{| class="wikitable"
! Feld !! Datenanbindung
|-
| DSN || <code>iDSN</code>
|-
| Host || <code>tSentry.iOSentry.iHost</code>
|-
| Public Key || <code>tSentry.iOSentry.iPubKey</code>
|-
| Project ID || <code>tSentry.iOSentry.iProID</code>
|-
| DB Status || <code>iCurrentDBStatus</code>
|}

[[Datei:Demo-window.svg|850px|Demo-Fenster der OSentry Library]]

=== DSN setzen ===

Die DSN wird im Feld <code>iDSN</code> erfasst. Der Button <code>Set DSN</code> ruft anschließend <code>tSentry.$init(iDSN)</code> auf. Nach dem Setzen werden Public Key, Host und Project ID aus der DSN gelesen und in den darunterliegenden Feldern angezeigt.

[[Datei:Demo-dsn.svg|850px|DSN-Konfiguration im Demo-Fenster]]

Der Button <code>Set DSN</code> initialisiert Sentry mit der eingegebenen DSN. Quelle: <code>FSY_Demo.setDSN.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$init(iDSN)
Calculate $cclass.$ivardefs.iDSN.$objinitval as con(kSq,iDSN,kSq)

Do $cinst.$showmessage('DSN set and Sentry initialized!','Info')

Do $cinst.$redraw()
Quit method
</pre>

=== DB Status anzeigen ===

<code>FSY_Demo.$displayDBState</code> zeigt, ob die SQLite Session verbunden ist. Quelle: <code>FSY_Demo.$displayDBState</code>.

<pre>
Do tOSLSession.$state Returns dbState
If dbState='kSessionStateLoggedOff'
Calculate iCurrentDBStatus as 'Logged Off'
Else If dbState='kSessionStateLoggedOn'
Calculate iCurrentDBStatus as 'Logged On'
Else
Calculate iCurrentDBStatus as 'Unkown DB State'
End If

Do $cinst.$redraw()
Quit method
</pre>

=== Demo-Datenbank erstellen ===

Der Button <code>Create Database</code> ruft <code>ODatabaseHandler.$DBFirstInit</code> auf. Quelle: <code>FSY_Demo.createDB.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Setup the DB
Do tODatabaseHandler.$DBFirstInit() Returns err
If err=0
Do $cinst.$showmessage('DB successfully created!','Info')
Else
Do $cinst.$showmessage('Error while creating the DB. Make sure that the DB does not already exist.','Info')
End If

Do $cinst.$displayDBState()

Quit method
</pre>

Die Datenbank wird im Arbeitsverzeichnis der Library angelegt. Quelle: <code>ODatabaseHandler.$getWorkingDir</code>.

<pre>
Quit method con(FileOps.$parentdir($clib.$pathname),pathsep())
</pre>

Die Demo-DB enthält unter anderem:

* <code>dperson</code>
* <code>drelease</code>
* <code>dvcs</code>

=== Message auslösen ===

Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Log auslösen ===

Button <code>Trigger a log</code>. Quelle: <code>FSY_Demo.log.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception auslösen ===

Button <code>Trigger an exception</code> bereitet eine Row und eine List vor und ruft anschließend <code>ODummy.$dummyMethod</code> auf. Quelle: <code>FSY_Demo.exception.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do iDummyRow.$define(id,name)
Calculate iDummyRow.id as 22
Calculate iDummyRow.name as 'Tom'

Do iDummyList.$define(id,weekday)
Do iDummyList.$add(1,'Monday')
Do iDummyList.$add(2,'Tuesday')
Do iDummyList.$add(3,'Wednesday')
Do iDummyList.$add(4,'Thursday')
Do iDummyList.$add(5,'Friday')
Do iDummyList.$add(6,'Saturday')
Do iDummyList.$add(7,'Sunday')

Calculate iDummyList.$line as 5

Do iODummy.$dummyMethod('Important Value')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')

Quit method
</pre>

<code>ODummy.$dummyMethod</code> sendet die Exception. Quelle: <code>ODummy.$dummyMethod</code>.

<pre>
#In here is some logic
#This logic would produce an error
#We send all this information to Sentry

Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')

Quit method 0
</pre>

=== Deprecated Call auslösen ===

Button <code>Trigger a deprecated call</code>. Quelle: <code>FSY_Demo.deprecatedCall.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureDeprecatedCall()
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== SQL Exception Button ===

Der Button <code>Trigger an SQLException</code> ist im Export vorhanden, enthält aber noch keinen fertigen Demo-Code. Quelle: <code>FSY_Demo.sqlException.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Für die Dokumentation der SQL-Erfassung siehe [[#Events erfassen|03 Events erfassen]].

== API Reference ==

Diese Seite dokumentiert die produktiv relevanten Methoden von <code>OSentryHL</code> und <code>OSentry</code>.

=== OSentryHL ===

<code>OSentryHL</code> ist die empfohlene Klasse für Applikationscode.

'''<code>$init(pDSN)</code>'''

Initialisiert das interne <code>OSentry</code>-Objekt.

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

'''<code>$captureMessage(pMessage)</code>'''

Sendet eine einfache Info-Message.

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel)</code>'''

Sendet eine generische Exception.

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

'''<code>$captureAnything(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface)</code>'''

Sendet ein frei konfigurierbares Event.

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Hinweis: Der Parameter ist im Export als <code>pStacktraveInterface</code> geschrieben.

'''<code>$captureLog(pErrorText)</code>'''

Sendet ein Log-Event.

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

'''<code>$captureDeprecatedCall()</code>'''

Meldet die Ausführung eines veralteten Codepfads.

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

'''<code>$captureSQLException(pErrorText,pStat)</code>'''

Meldet einen SQL-Fehler mit SQL-Text und nativer Datenbankfehlermeldung.

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag für das nächste Event hinzu.

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra für das nächste Event hinzu.

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

'''<code>$setStatus(pStatus)</code>'''

Aktiviert oder deaktiviert Sentry.

<pre>
#Toggels Sentry on or off
Do iOSentry.$setStatus(pStatus)
Quit method
</pre>

'''<code>$setUser()</code>'''

Setzt im Export feste [[#Demo Library|Demo]]-Userdaten.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode parametrisiert werden.

=== OSentry ===

<code>OSentry</code> ist die Low-Level-Klasse für Payload-Erzeugung und Versand.

'''<code>$init(pDSN)</code>'''

Parst die DSN in Protokoll, Public Key, Host und Project ID.

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraceInterface,pUserInterface,pExceptionInterface)</code>'''

Erzeugt JSON, sendet es an Sentry und behandelt Fehlerfälle.

Parameter:

{| class="wikitable"
! Parameter !! Default !! Bedeutung
|-
| <code>pErrorText</code> || || Message
|-
| <code>pErrorCode</code> || || Fehlercode
|-
| <code>pExcType</code> || || Exception-Typ
|-
| <code>pLevel</code> || || <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code>, <code>debug</code>
|-
| <code>pStacktraceInterface</code> || <code>kTrue</code> || [[#Stacktrace und Kontext|Stacktrace]] senden
|-
| <code>pUserInterface</code> || <code>kTrue</code> || [[#Tags, Extras und User-Kontext|User-Kontext]] senden
|-
| <code>pExceptionInterface</code> || <code>kTrue</code> || Exception Interface senden
|}

'''<code>$generateJson(...)</code>'''

Erzeugt den Sentry JSON Payload als Binary.

'''<code>$generateStacktraceInterface(pCulprit)</code>'''

Erzeugt den Omnis-[[#Stacktrace und Kontext|Stacktrace]] inklusive Variablen und Kontextzeilen.

'''<code>$generateExceptionInterface(pType,pValue)</code>'''

Erzeugt das Sentry Exception Interface.

<pre>
# Generate Row to store in the JSON
Do exceptionRow.$define(type,value,stacktrace)
Calculate exceptionRow.type as pType
Calculate exceptionRow.value as pValue
Calculate exceptionRow.stacktrace as 'sentry.interfaces.stacktrace' ## Tells the exception interface that a stacktrace is passed aswell
</pre>

'''<code>$generateUserInterface()</code>'''

Erzeugt den [[#Tags, Extras und User-Kontext|User-Kontext]].

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag zur internen Tag-Liste hinzu.

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra zur internen Extra-Liste hinzu.

'''<code>$clearList()</code>'''

Leert [[#Tags, Extras und User-Kontext|Tags und Extras]] nach einem Request.

'''<code>$setUserData(pID,pName,pEmail)</code>'''

Setzt Userdaten für den nächsten Request.

'''<code>$setProxy(pProxyHost,pProxyPort)</code>'''

Setzt Proxy-Informationen.

'''<code>$setStatus(pStatus)</code>'''

Setzt den Sentry-Status.

<pre>
#Toggels Sentry Reports on or off
Calculate iStatus as pStatus
Quit method
</pre>

'''<code>$writeJSON(pJSON,pBuffer)</code>'''

Schreibt fehlgeschlagene Reports lokal in eine Datei.

'''<code>$getUnixTimestamp()</code>'''

Gibt den aktuellen UNIX Timestamp zurück.

'''<code>$generateUUID()</code>'''

Erzeugt eine UUID für die Sentry Event ID.

<pre>
#Genereates a UUID for the issue id
Quit method OW3.$makeuuid(kFalse)
</pre>

== Troubleshooting ==

=== Es erscheinen keine Events in Sentry ===

Prüfe zuerst, ob Sentry aktiv ist:

<pre>
Do tSentry.$setStatus(1)
</pre>

<code>OSentry.$captureException</code> beendet sich sofort, wenn der Status <code>0</code> oder leer ist:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

=== Die DSN ist falsch ===

Prüfe, ob die DSN korrekt aus Sentry kopiert wurde. <code>OSentry.$init</code> erwartet eine DSN, aus der Public Key, Host und Project ID gelesen werden können.

Nach dem Setzen der DSN sollten in der [[#Demo Library|Demo-Library]] folgende Felder gefüllt sein:

* Host
* Public Key
* Project ID

=== Netzwerk oder Proxy blockiert den Request ===

Wenn die Anwendung keinen direkten Zugriff auf Sentry hat, setze einen Proxy:

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Intern wird der Proxy vor dem HTTP Request gesetzt:

<pre>
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Report wird lokal gespeichert ===

Wenn <code>HTTPPost</code>, <code>HTTPSend</code> oder <code>HTTPRead</code> fehlschlägt, speichert OSentry den Report lokal:

<pre>
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
</pre>

Suche im Omnis-Installationsordner nach Dateien mit dem Namen:

<pre>
Sentryreport_<timestamp>.json
</pre>

=== Sentry antwortet nicht mit 200 OK ===

Wenn die HTTP-Antwort kein <code>200 OK</code> enthält, wird der JSON Report ebenfalls lokal gespeichert:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

Mögliche Ursachen:

* falsche Project ID
* falscher Public Key
* ungültige DSN
* JSON Payload wird von Sentry abgelehnt
* Netzwerk-Gateway verändert den Request

=== Tags oder Extras erscheinen beim falschen Event ===

[[#Tags, Extras und User-Kontext|Tags und Extras]] werden für den nächsten Request gesammelt. Nach erfolgreichem Request werden sie gelöscht:

<pre>
Do iTagList.$clear()
Do iExtraList.$clear()
</pre>

Wenn ein Request fehlschlägt, wird ebenfalls aufgeräumt:

<pre>
Do $cinst.$clearList()
</pre>

Prüfe trotzdem, ob in eigenen Wrapper-Methoden Tags und Extras direkt vor dem passenden Capture-Aufruf gesetzt werden.

=== User-Kontext zeigt Demo-Daten ===

<code>OSentryHL.$setUser</code> verwendet im Export feste Testdaten:

<pre>
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
</pre>

Für produktive Nutzung sollte die Methode parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
</pre>

=== SQL Exception Demo-Button funktioniert nicht ===

Der Button <code>Trigger an SQLException</code> ist im Export noch nicht implementiert:

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Die produktive Methode für SQL-Fehler ist aber vorhanden. Siehe auch [[#Events erfassen|Events erfassen]].

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

=== Zu viele Events ===

Sentry kann sehr schnell viele Events sammeln. Verwende für produktive Systeme:

* klare Wrapper-Methoden in <code>OSentryHL</code>
* sinnvolle Levels
* gezielte [[#Tags, Extras und User-Kontext|Tags]]
* keine Events in sehr häufigen Schleifen
* keine rein informativen Debug-Events ohne Nutzen

=== Sensible Daten ===

[[#Stacktrace und Kontext|Stacktrace]], Parameter, Instance Variablen, SQL-Text und [[#Tags, Extras und User-Kontext|Extras]] können sensible Daten enthalten. Prüfe vor produktiver Nutzung:

* Welche Variablen werden übertragen?
* Enthalten SQL-Statements personenbezogene Daten?
* Werden Tokens oder Passwörter in Extras geschrieben?
* Sollen bestimmte Werte maskiert werden?

Sentry

2026-06-12T14:06:00Z

Silvan: /* Inhalt */

__TOC__

== Überblick ==

OSentry ist ein REST-API-Konnektor von Omnis Studio zu Sentry. Der Konnektor sendet Fehler, Messages, Logs und Laufzeitkontext aus Omnis-Anwendungen an Sentry, damit Probleme in produktiven Systemen sichtbar, gruppierbar und analysierbar werden.

Diese Dokumentation beschreibt die [[#Installation|Installation]], die Nutzung in bestehenden Omnis-Anwendungen, die Definition eigener standardisierter Exception-Typen, die interne Struktur und die [[#Demo Library|Demo-Library]].

=== Kernidee ===

OSentry besteht aus zwei produktiv relevanten Klassen:

* <code>OSentryHL</code>: High-Level-Adapter für die Anwendung. Diese Klasse sollte von normalem Applikationscode aufgerufen werden.
* <code>OSentry</code>: Low-Level-Adapter für DSN-Parsing, JSON-Erzeugung, [[#Stacktrace und Kontext|Stacktrace]]-Aufbereitung und HTTP-Kommunikation mit Sentry.

Die Anwendung arbeitet im Normalfall mit <code>OSentryHL</code>. Dadurch bleiben Sentry-spezifische Details zentral gekapselt und neue standardisierte Exception-Typen können als eigene Methoden in <code>OSentryHL</code> definiert werden.

=== Hauptfeatures ===

* Direkte Anbindung von Omnis Studio an Sentry über REST API und DSN
* Erfassen von Exceptions, Messages, Logs und SQL-Fehlern
* Unterstützung der Sentry-Level <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code> und <code>debug</code>
* Automatische Omnis-Kontextinformationen
* Omnis-[[#Stacktrace und Kontext|Stacktrace]] mit Klassen, Methoden, Zeilen und Variablen
* [[#Tags, Extras und User-Kontext|Tags]] für Filterung und Gruppierung
* [[#Tags, Extras und User-Kontext|Extras]] für zusätzliche Diagnoseinformationen
* Optionaler [[#Tags, Extras und User-Kontext|User-Kontext]]
* Proxy-Unterstützung
* Aktivieren und Deaktivieren der Sentry-Übertragung
* Lokales Speichern von Reports bei Übertragungsfehlern

=== Weiterführende Links ===

* [https://sentry.io/welcome/ Sentry Website]
* [https://sentry.io/signup/ Sentry Account erstellen]
* [https://develop.sentry.dev/self-hosted/ Sentry self-hosted]

=== Screenshots ===

[[Datei:Sentry-issue.png|900px|Sentry Issue-Übersicht]]

== Installation ==

Diese Seite beschreibt, wie OSentry in eine bestehende Omnis-Anwendung integriert wird.

=== Voraussetzungen ===

* Omnis Studio Anwendung
* Sentry Account oder self-hosted Sentry Installation
* Ein Sentry-Projekt mit SDK-Typ <code>Other</code>
* Die DSN des Sentry-Projekts
* Netzwerkzugriff auf Sentry

Die exportierte [[#Demo Library|Demo-Library]] wurde mit Omnis <code>11.1</code> erstellt.

=== Sentry-Projekt erstellen ===

# In Sentry ein neues Projekt erstellen.
# Als SDK <code>Other</code> auswählen.
# Die DSN des Projekts kopieren.

Die DSN wird beim Initialisieren verwendet. <code>OSentry</code> zerlegt sie intern in Public Key, Host und Project ID.

[[Datei:Sentry-projects.png|900px|Sentry Projektübersicht]]

=== Klassen kopieren ===

Kopiere die folgenden Klassen in deine bestehende Omnis-Library:

* <code>OSentry</code>
* <code>OSentryHL</code>

Die Demo-spezifischen Klassen sind für die produktive Integration nicht erforderlich. Damit sind die übrigen Klassen der Demo-Library gemeint, zum Beispiel <code>FSY_Demo</code>, <code>ODummy</code>, <code>ODatabaseHandler</code> und <code>OSLSession</code>. Diese Klassen dienen nur dazu, die [[#Demo Library|Demo-Library]] mit Fenster, SQLite-Testdaten und Beispielaufrufen auszuführen.

=== Task Variable anlegen ===

Lege in deiner Startup Task eine Task Variable an:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' <code>tSentry</code> sollte als global erreichbarer Singleton der Anwendung verwendet werden. In Omnis ist dafür eine Task Variable sinnvoll, weil sie von Fenstern, Objektklassen und zentralen Error-Handlern aus konsistent erreichbar ist. Dadurch gibt es genau eine aktive Sentry-Konfiguration mit einer DSN, einem Status, optionalen Proxy-Daten und gemeinsamen Wrapper-Methoden in <code>OSentryHL</code>.</div>

Im [[#Demo Library|Demo-Projekt]] ist diese Variable in <code>Startup_Task</code> definiert.

=== Initialisierung im Startup Task ===

Initialisiere <code>tSentry</code> beim Start deiner Anwendung mit der DSN deines Sentry-Projekts:

<pre>
Do tSentry.$init('<DSN>')
</pre>

Die [[#Demo Library|Demo-Library]] ruft im Startup Task ebenfalls die Initialisierung auf. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()
</pre>

In einer produktiven Anwendung sollte die DSN explizit oder aus einer Konfiguration übergeben werden:

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Speichere die DSN in einer Datenbank, einer Konfigurationstabelle oder einem Config File. So kann sie pro Kunde, Umgebung oder Installation geändert werden, ohne die Library neu auszuliefern.</div>

=== Testcall ===

Nach der Initialisierung kann ein erstes Testevent gesendet werden:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Wenn alles korrekt eingerichtet ist, erscheint das Event im Sentry-Projekt.

=== Proxy konfigurieren ===

Falls die Anwendung in einem geschützten Netzwerk läuft, kann ein Proxy gesetzt werden. Die Methode befindet sich im Low-Level-Objekt <code>OSentry</code>.

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Die interne Implementierung setzt den Proxy vor dem HTTP-Request:

<pre>
#Configure proxy; needed when sending data out of secured networks
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Sentry aktivieren oder deaktivieren ===

OSentry kann zentral ein- oder ausgeschaltet werden.

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Deaktiviere Sentry in der Entwicklungs-Version standardmäßig oder verwende eine separate Entwicklungs-DSN. So landen lokale Tests, Debug-Fehler und absichtlich ausgelöste Exceptions nicht im produktiven Sentry-Projekt.</div>

<pre>
Do tSentry.$setStatus(1) ## aktiv
Do tSentry.$setStatus(0) ## inaktiv
</pre>

Im Low-Level-Objekt <code>OSentry</code> wird vor dem Senden geprüft:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

== Quickstart ==

Diese Seite zeigt die minimale Integration in eine bestehende Omnis-Anwendung.

=== Klassen übernehmen ===

Kopiere <code>OSentry</code> und <code>OSentryHL</code> in deine Library.

=== Task Variable erstellen ===

In der Startup Task:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

=== Sentry initialisieren ===

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<code>OSentryHL.$init</code> delegiert an das Low-Level-Objekt <code>OSentry</code>:

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

=== Message senden ===

<pre>
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
</pre>

Die [[#Demo Library|Demo-Library]] verwendet genau diesen Aufruf im Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception senden ===

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

=== In Sentry prüfen ===

In Sentry sollte anschließend ein neues Event sichtbar sein. Je nach Event-Typ enthält es:

* Message
* Level
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Tags, Extras und User-Kontext|User-Kontext]]
* [[#Stacktrace und Kontext|Stacktrace]]
* Omnis-Kontextinformationen

== Events erfassen ==

OSentryHL ist die empfohlene Einstiegsschicht für Applikationscode. Die Klasse bietet sprechende Methoden für typische Event-Arten und ruft intern <code>OSentry.$captureException</code> auf.

=== Message ===

Eine einfache Information wird mit <code>$captureMessage</code> gesendet:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

Verhalten:

* Level: <code>info</code>
* Kein [[#Stacktrace und Kontext|Stacktrace]]
* Kein [[#Tags, Extras und User-Kontext|User Interface]]
* Geeignet für einfache Statusmeldungen oder technische Hinweise

=== Log ===

Ein Log-Event wird mit <code>$captureLog</code> gesendet:

<pre>
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

Verhalten:

* Level: <code>warning</code>
* [[#Stacktrace und Kontext|Stacktrace]] aktiv
* Exception Interface in diesem Wrapper deaktiviert
* [[#Tags, Extras und User-Kontext|User Interface]] aktiv

=== Generische Exception ===

Eine generische Exception wird mit <code>$captureException</code> gesendet:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

Parameter:

{| class="wikitable"
! Parameter !! Bedeutung
|-
| <code>pErrorText</code> || Text, der in Sentry als Message sichtbar ist
|-
| <code>pErrorCode</code> || Fehlercode oder fachlicher Code
|-
| <code>pExcType</code> || Exception-Typ für Benennung und Gruppierung
|-
| <code>pLevel</code> || Sentry-Level
|}

Gültige Levels:

* <code>fatal</code>
* <code>error</code>
* <code>warning</code>
* <code>info</code>
* <code>debug</code>

=== SQL Exception ===

SQL-Fehler können mit <code>$captureSQLException</code> gemeldet werden.

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

Verhalten:

* Fügt die Datenbank als [[#Tags, Extras und User-Kontext|Tag]] hinzu
* Fügt SQL-Text als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Fügt native Datenbankfehlermeldung als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Sendet das Event als <code>SQL-Exception</code> mit Level <code>error</code>

=== Deprecated Call ===

Veraltete Codepfade können gezielt gemeldet werden:

<pre>
Do tSentry.$captureDeprecatedCall()
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

Dieser Wrapper eignet sich, um zu erkennen, ob alter Code in produktiven Systemen noch ausgeführt wird.

=== Frei konfigurierbares Event ===

Für Sonderfälle gibt es <code>$captureAnything</code>:

<pre>
Do tSentry.$captureAnything('Text',1001,'Custom Type','error',kTrue,kTrue,kTrue)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Diese Methode bietet maximale Flexibilität. Für wiederkehrende Exception-Typen sollte aber eine eigene Methode in <code>OSentryHL</code> angelegt werden. Siehe [[#Eigene Exceptions standardisieren|04 Eigene Exceptions standardisieren]].

== Eigene Exceptions standardisieren ==

Wenn ein Exception-Typ mehrfach in der Anwendung vorkommt, sollte er nicht überall manuell mit <code>$captureException</code> aufgebaut werden. Besser ist eine eigene Methode in <code>OSentryHL</code>.

Dadurch entsteht eine zentrale, wiederverwendbare Definition für:

* Exception-Typ
* Sentry-Level
* Fehlercode
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Stacktrace und Kontext|Stacktrace]]/[[#Tags, Extras und User-Kontext|User]]/Exception Interface

Die automatisch gesetzten [[#Tags, Extras und User-Kontext|Tags und Extras]] aus <code>OSentry.$generateJson</code> müssen in solchen Wrappern nicht erneut ergänzt werden. Eigene Exception-Methoden setzen nur zusätzliche Werte, die für diesen standardisierten Exception-Typ relevant sind.

=== Warum über OSentryHL? ===

<code>OSentryHL</code> ist die Abstraktionsschicht für Applikationscode. Sie kapselt die Details von <code>OSentry</code> und sorgt dafür, dass Aufrufe in der Anwendung kurz und konsistent bleiben.

Bestehende Beispiele aus <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

=== Empfohlenes Muster ===

Für jeden standardisierten Exception-Typ wird eine eigene Methode in <code>OSentryHL</code> erstellt.

Beispiel:

<pre>
# Captures a validation exception
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addExtra('Field',pField)
Do $cinst.$addExtra('Invalid Value',pValue)

Do iOSentry.$captureException(pErrorText,2001,'Validation-Exception','warning',1,1,1) Returns code

Quit method code
</pre>

Mögliche Parameter der neuen Methode:

{| class="wikitable"
! Parameter !! Beispiel !! Zweck
|-
| <code>pErrorText</code> || <code>'Invalid customer number'</code> || Sentry Message
|-
| <code>pModule</code> || <code>'Customer'</code> || Filterbarer Tag
|-
| <code>pField</code> || <code>'cu_number'</code> || Diagnoseinformation
|-
| <code>pValue</code> || <code>'ABC'</code> || Diagnoseinformation
|}

Der Applikationscode bleibt dadurch einfach:

<pre>
Do tSentry.$captureValidationException('Invalid customer number','Customer','cu_number',cu_number)
</pre>

=== Beispiel: Business Rule Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures a business rule violation
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do $cinst.$addExtra('Details',pDetails)

Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureBusinessRuleViolation('Invoice cannot be posted','Invoice','PostingAllowed','Invoice is missing customer')
</pre>

=== Beispiel: Integration Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures an integration exception
Do $cinst.$addTag('Integration',pSystem)
Do $cinst.$addTag('Endpoint',pEndpoint)
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)

Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureIntegrationException('External API request failed','ERP','/api/customer',jsonPayload,responseText)
</pre>

=== Namenskonventionen ===

Empfehlung für neue Methoden:

* Methodenname beginnt mit <code>$capture</code>
* Der fachliche Typ steht im Methodennamen
* Der Sentry Exception Type ist stabil und ändert sich nicht laufend
* [[#Tags, Extras und User-Kontext|Tags]] sind kurz und filterbar
* [[#Tags, Extras und User-Kontext|Extras]] dürfen länger sein und Diagnoseinformationen enthalten

Beispiele:

* <code>$captureValidationException</code>
* <code>$captureBusinessRuleViolation</code>
* <code>$captureIntegrationException</code>
* <code>$capturePermissionViolation</code>
* <code>$captureConfigurationError</code>

=== Error Codes ===

Verwende feste Fehlercodes für standardisierte Exception-Typen. Dadurch können Events in Sentry besser gefiltert und wiedererkannt werden.

Beispiel:

{| class="wikitable"
! Code !! Exception Type
|-
| <code>2001</code> || <code>Validation-Exception</code>
|-
| <code>3001</code> || <code>Business-Rule-Violation</code>
|-
| <code>4001</code> || <code>Integration-Exception</code>
|-
| <code>5001</code> || <code>Configuration-Error</code>
|}

=== Wann nicht standardisieren? ===

Nicht jeder Einzelfall braucht eine eigene Methode. Für einmalige technische Tests oder sehr spezielle Fälle reicht:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Sobald ein Exception-Typ aber mehrfach vorkommt oder fachlich relevant ist, sollte er als eigene Methode in <code>OSentryHL</code> definiert werden.

== Tags, Extras und User-Kontext ==

Tags, Extras und User-Kontext reichern Sentry-Events mit zusätzlichen Informationen an. Diese Informationen helfen beim Filtern, Gruppieren und Analysieren.

[[Datei:Sentry-tags.png|900px|Sentry Tags und User-Kontext]]

=== Tags ===

Tags sind kurze, filterbare Werte.

Beispiele:

* Datenbank
* Kunde
* Modul
* Umgebung
* Error Code
* Omnis-Version

Methode in <code>OSentryHL</code>:

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds a tag to the next request processed
Do iTagList.$add(pName,pValue)
Quit method
</pre>

Beispiel:

<pre>
Do tSentry.$addTag('Module','Invoice')
Do tSentry.$addTag('Customer','10001')
Do tSentry.$captureException('Invoice posting failed',3001,'Business-Rule-Violation','warning')
</pre>

=== Extras ===

Extras sind Detailinformationen, die nicht primär zum Filtern gedacht sind.

Beispiele:

* SQL-Text
* Native Datenbankfehlermeldung
* Payload
* Response Body
* interne IDs
* zusätzliche Debug-Informationen

Methode in <code>OSentryHL</code>:

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds extra information to the next request being processed
Do iExtraList.$add(pName,pValue)
Quit method
</pre>

Beispiel aus der SQL Exception:

<pre>
Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)
</pre>

=== Automatische Tags ===

Die folgenden Tags werden bei jedem Event automatisch von <code>OSentry.$generateJson</code> ergänzt. Sie müssen bei eigenen Exceptions nicht erneut gesetzt werden. Eigene Wrapper-Methoden in <code>OSentryHL</code> sollten nur zusätzliche, fachlich oder technisch relevante Tags hinzufügen.

<code>OSentry.$generateJson</code> fügt mehrere Tags automatisch hinzu:

<pre>
# Add static tags
Do iTagList.$add('Omnisversion',sys(1))
Calculate systemversionRow as systemversion()
Do iTagList.$add('Plattform',con(sys(8),pick(systemversionRow.server,'',' SRV')))
Do iTagList.$add('OS Version',con(systemversionRow.major,'.',systemversionRow.minor,'.',systemversionRow.build))
Do iTagList.$add('error_code',pErrorCode)
</pre>

Automatisch gesendete Tags:

{| class="wikitable"
! Tag !! Herkunft !! Zweck
|-
| <code>Omnisversion</code> || <code>sys(1)</code> || Zeigt, mit welcher Omnis-Version das Event erzeugt wurde
|-
| <code>Plattform</code> || <code>sys(8)</code> und Server-Flag aus <code>systemversion()</code> || Unterscheidet Plattform und Server Runtime
|-
| <code>OS Version</code> || <code>systemversionRow.major/minor/build</code> || Zeigt die Betriebssystemversion
|-
| <code>error_code</code> || Parameter <code>pErrorCode</code> || Verbindet das Event mit dem übergebenen Fehlercode
|}

Beispiel für eine eigene Exception: Der Wrapper muss nicht erneut <code>Omnisversion</code> oder <code>OS Version</code> setzen. Er ergänzt nur das, was für diesen Exception-Typ zusätzlich hilfreich ist.

<pre>
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code
</pre>

=== Automatische Extras ===

Auch die folgenden Extras werden bei jedem Event automatisch ergänzt. Bei eigenen Exceptions müssen nur zusätzliche Extras gesetzt werden, zum Beispiel ein SQL-Statement, ein Payload oder fachliche Zusatzdaten.

<code>OSentry.$generateJson</code> fügt offene Fenster, offene Reports und die aktuelle Printfile hinzu:

<pre>
# Static extra 1: All open windows
Do $root.$iwindows.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate windows as con(windows,', ',nameList.[i].1)
End For
Calculate windows as right(windows,len(windows)-2)
Do iExtraList.$add('Open Windows',windows)

# Static extra 2: All open reports
Do $root.$ireports.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate reports as con(reports,', ',nameList.[i].1)
End For
Calculate reports as right(reports,len(reports)-2)
Do iExtraList.$add('Open Reports',reports)
Do iExtraList.$add('Current Printfile',$root.$prefs.$printfile)
</pre>

Automatisch gesendete Extras:

{| class="wikitable"
! Extra !! Herkunft !! Zweck
|-
| <code>Open Windows</code> || <code>$root.$iwindows.$makelist($ref.$name)</code> || Zeigt, welche Fenster im Moment des Events offen waren
|-
| <code>Open Reports</code> || <code>$root.$ireports.$makelist($ref.$name)</code> || Zeigt, welche Reports im Moment des Events offen waren
|-
| <code>Current Printfile</code> || <code>$root.$prefs.$printfile</code> || Zeigt die aktuell gesetzte Printfile
|}

Beispiel für zusätzliche Extras in einem eigenen Wrapper:

<pre>
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)
Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code
</pre>

=== User-Kontext ===

Der User-Kontext ordnet ein Event einem betroffenen Benutzer zu. In Sentry erscheint dadurch ein eigener User-Bereich, und Events können nach Benutzer gefiltert oder gruppiert werden. Das ist besonders hilfreich, wenn ein Fehler nur bei einzelnen Kunden, Arbeitsplätzen oder Benutzerkonten auftritt.

<code>OSentry</code> unterstützt drei User-Felder:

{| class="wikitable"
! Feld !! Bedeutung
|-
| <code>id</code> || stabile interne Benutzer-ID oder Kundennummer
|-
| <code>username</code> || lesbarer Benutzername
|-
| <code>email</code> || E-Mail-Adresse, falls sie übertragen werden darf
|}

Der User-Kontext wird nur in das Event geschrieben, wenn das User Interface beim Capture-Aufruf aktiviert ist. Die Standardmethode <code>OSentry.$captureException</code> hat <code>pUserInterface</code> standardmäßig auf <code>kTrue</code>. Einzelne High-Level-Methoden können das bewusst deaktivieren, zum Beispiel <code>$captureMessage</code>.

<code>OSentry</code> kann User-Daten an das Event anhängen:

<pre>
#Sets userinformation for the next request being processed
Calculate iUserID as pID
Calculate iUserName as pName
Calculate iUserEmail as pEmail
Quit method
</pre>

Das User Interface wird so generiert:

<pre>
# Create user data row
Do UserdataRow.$define(id,email,username)

Calculate UserdataRow.id as iUserID
Calculate UserdataRow.email as iUserEmail
Calculate UserdataRow.username as iUserName

Do JSON.$addmember('','user','')
Do JSON.$setobject('user',UserdataRow)

Calculate jsonString as OJSON.$formatjson(JSON.$getjson())

Quit method jsonString
</pre>

Die aktuelle Demo-Methode in <code>OSentryHL</code> verwendet feste Testdaten. Quelle: <code>OSentryHL.$setUser</code>.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode angepasst und parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
Quit method
</pre>

Empfohlen ist, den User nach Login oder beim Wechsel des aktiven Benutzers zentral zu setzen. Bei anonymen oder sensiblen Installationen kann statt Name und E-Mail auch nur eine interne ID oder ein pseudonymisierter Wert verwendet werden.

=== Datenschutz ===

<div style="border-left:4px solid #72777d; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Datenschutz:''' Prüfe vor produktiver Nutzung, welche Daten an Sentry gesendet werden. Besonders kritisch sind personenbezogene Daten, SQL-Statements, Zugangsdaten, Tokens und interne Pfade.</div>

Besonders kritisch sind:

* personenbezogene Daten
* Kundendaten
* SQL-Statements mit Werten
* Zugangsdaten
* Tokens
* interne Pfade

Tags und Extras sollten so gestaltet werden, dass sie für die Fehleranalyse hilfreich sind, aber keine unnötigen sensiblen Daten übertragen.

== Stacktrace und Kontext ==

<code>OSentry</code> erzeugt einen Omnis-spezifischen Stacktrace und übergibt ihn an Sentry. Dadurch sieht man in Sentry nicht nur eine Fehlermeldung, sondern auch Klassen, Methoden, Zeilen und Variablenkontext. Ergänzende Informationen zu [[#Tags, Extras und User-Kontext|Tags, Extras und User-Kontext]] stehen auf der separaten Kontext-Seite.

[[Datei:Sentry-stack.png|900px|Sentry Stacktrace mit Omnis-Kontext]]

=== Stack lesen ===

<code>OSentry.$generateStacktraceInterface</code> verwendet <code>sys(192)</code>, um den aktuellen Omnis-Stack zu lesen:

<pre>
# Clean up the Stacklist (remove OSentry classes from the stack)
Do sys(192) Returns sys192List
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
If pos('OSentry',class.$name)>0|pos('OSentryHL',class.$name)>0
Do sys192List.[sys192List.$line].$selected.$assign(kTrue)
End If
End For
Do sys192List.$remove(kListDeleteSelected)
</pre>

Interne Frames von <code>OSentry</code> und <code>OSentryHL</code> werden entfernt, damit in Sentry die fachlich relevanten Stellen sichtbar bleiben.

=== SQL-Error Frames entfernen ===

Bestimmte interne SQL-Fehlerframes werden ebenfalls entfernt:

<pre>
# Remove some other classes which we do not want to display
If sys192List.1.method='$sqlerror'
Do sys192List.$remove(1)
Else If sys192List.1.method='$statementerror'
Do sys192List.$remove(1)
End If
</pre>

=== Frames erzeugen ===

Für jeden Stack-Eintrag werden Funktion, Zeilennummer und Kontextzeile erzeugt:

<pre>
#Loop through every item on the omnis stack
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
Calculate className as class.$name

# Create the content row
Do contentRow.$define(vars,function,pre_context,context_line,lineno,filename,post_context)
Calculate contentRow.lineno as sys192List.line
Calculate contentRow.filename as testFileName
Calculate contentRow.context_line as sys192List.linetext
If isclear(sys192List.object)
Calculate contentRow.function as con(className,'.',sys192List.method) ## If it's a class method
Else
Calculate contentRow.function as con(className,'.',sys192List.object,'.',sys192List.method) ## If it's a method of an object of a class (e.g. Headedlist)
End If
Do contentList.$add(contentRow)
End For
</pre>

=== Variablen aufnehmen ===

Pro Stackframe werden Instance Variablen und Parameter gesammelt:

<pre>
# Get all iVars
Do varList.$define(name,value)
Set reference class to sys192List.inst
Do $cinst.$getVars('ivars',class) Returns varList

# Get all params
Calculate paramList as sys192List.params
For paramList.$line from 1 to paramList.$linecount step 1
If not(paramList.value='(Not empty)')
Do varList.$add(paramList.name,paramList.value)
Else
Do varList.$add(paramList.name,'(Not empty)')
End If
End For
</pre>

=== Pre- und Post-Context ===

OSentry fügt Methodenzeilen vor und nach der aktuellen Zeile hinzu:

<pre>
# Pre Context (all method lines before the error occured)
Set reference method to sys192List.methoditem
Do precontextList.$define(line)
For i from 1 to sys192List.line-1 step 1
Do precontextList.$add(method.$methodlines.[i].$text)
End For

# Post Context (all method lines after the error occured
Do postcontextList.$define(line)
For i from sys192List.line+1 to method.$methodlines.$count step 1
Do postcontextList.$add(method.$methodlines.[i].$text)
End For
</pre>

=== Variablentypen ===

<code>OSentry.$getVars</code> unterstützt Basisvariablen, Rows und Lists.

Basisvariablen:

<pre>
If varType='char'|varType='boolean'|varType='integer'|varType='number'|varType='date'
Calculate varContent as pItemRef.$[pVarType].[varName]
Do varList.$add(varName,varContent)
</pre>

Rows:

<pre>
Else If varType='row'
Calculate varRow as pItemRef.$[pVarType].[varName]
If varRow.$colcount=0
Do varList.$add(varName,'(Empty)')
Else
For Z2 from 1 to varRow.$colcount step 1
Calculate varContent as con(varContent,varRow.$cols.[Z2].$name,': ',varRow.[Z2],', ')
End For
Do varList.$add(varName,varContent)
</pre>

Lists:

<pre>
Else If varType='list'
Calculate varListType as pItemRef.$[pVarType].[varName]
Calculate varContent as con('Colcount: ',varListType.$colcount,', ','Linecount: ',varListType.$linecount,', ','Current Line: ',varListType.$line)
If varListType.$linecount=0&varListType.$line=0&varListType.$colcount=0
Do varList.$add(varName,'(Empty)')
Calculate varContent as ''
Else
For Z3 from 1 to varListType.$colcount step 1
Calculate colName as varListType.$cols.[Z3].$name
Calculate varContent as con(varContent,' ',colName,': ',varListType.[colName])
End For
Do varList.$add(varName,varContent)
Calculate varContent as ''
End If
End If
</pre>

=== Hinweise ===

Stacktrace und Variablenkontext sind sehr hilfreich, können aber sensible Daten enthalten. Vor produktiver Nutzung sollte geprüft werden, ob bestimmte Variablen anonymisiert oder ausgeschlossen werden müssen.

== Interne Architektur ==

Diese Seite beschreibt die produktiv relevanten Klassen <code>OSentryHL</code> und <code>OSentry</code>.

=== Klassenübersicht ===

{| class="wikitable"
! Klasse !! Rolle
|-
| <code>OSentryHL</code> || High-Level-Adapter für Applikationscode
|-
| <code>OSentry</code> || Low-Level-Adapter für JSON, [[#Stacktrace und Kontext|Stacktrace]] und HTTP
|-
| <code>Startup_Task</code> || [[#Demo Library|Demo]]-Startup und Beispiel für Initialisierung
|-
| <code>FSY_Demo</code> || [[#Demo Library|Demo]]-Fenster
|-
| <code>ODummy</code> || [[#Demo Library|Demo]]-Code für [[#Stacktrace und Kontext|Stacktrace]]-Beispiel
|-
| <code>ODatabaseHandler</code> || [[#Demo Library|Demo]]-DB Initialisierung
|-
| <code>OSLSession</code> || SQLite Session für [[#Demo Library|Demo]]
|}

=== Empfohlener Aufrufweg ===

Applikationscode sollte <code>OSentryHL</code> verwenden:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

<code>OSentryHL</code> delegiert anschließend an <code>OSentry</code>:

<pre>
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code
</pre>

=== Ablauf eines Events ===

# Applikationscode ruft Methode in <code>OSentryHL</code> auf.
# <code>OSentryHL</code> fügt bei Bedarf [[#Tags, Extras und User-Kontext|Tags und Extras]] hinzu.
# <code>OSentryHL</code> ruft <code>iOSentry.$captureException(...)</code> auf.
# <code>OSentry</code> prüft, ob Sentry aktiv ist.
# <code>OSentry</code> erzeugt JSON.
# [[#Stacktrace und Kontext|Stacktrace]], Exception Interface und [[#Tags, Extras und User-Kontext|User Interface]] werden optional ergänzt.
# HTTP Header und Sentry Auth Header werden erstellt.
# JSON wird per HTTPS an Sentry gesendet.
# Bei Erfolg werden [[#Tags, Extras und User-Kontext|Tags und Extras]] geleert.
# Bei Fehler wird der JSON Report lokal gespeichert.

=== DSN Parsing ===

<code>OSentry.$init</code> zerlegt die DSN:

<pre>
# Parse the DSN into Public Key, Host and Project ID
If len(pDSN)>5
Calculate iDSN as pDSN
Calculate part1 as strtok('iDSN','@')
Calculate iProtocol as strtok('part1','/')
Calculate iProtocol as left(iProtocol,len(iProtocol)-1)
Do strtok('part1','/')
Calculate iPubKey as strtok('part1',':')

Calculate iHost as strtok('iDSN','/')
Calculate iProID as iDSN

#Save the values for the next startup
Calculate $cclass.$ivardefs.iPubKey.$objinitval as con('"',iPubKey,'"')
Calculate $cclass.$ivardefs.iHost.$objinitval as con('"',iHost,'"')
Calculate $cclass.$ivardefs.iProID.$objinitval as con('"',iProID,'"')
End If

Quit method
</pre>

=== JSON-Erzeugung ===

<code>OSentry.$generateJson</code> ist die zentrale Methode für den Payload. Sie setzt unter anderem:

* <code>event_id</code>
* <code>logger</code>
* <code>platform</code>
* <code>culprit</code>
* <code>timestamp</code>
* <code>sdk</code>
* <code>message</code>
* <code>level</code>
* <code>tags</code>
* <code>extra</code>
* optional <code>user</code>
* optional <code>exception</code>
* optional <code>stacktrace</code>

Auszug:

<pre>
# Add all required fields (those are required from the API)
Do JSON.$addmember('','event_id',$cinst.$generateUUID()) ## auto generated UUID 4
Do JSON.$addmember('','logger',logger)
Do JSON.$addmember('','platform',platform)
Do JSON.$addmember('','culprit',culprit)
#Do JSON.$addmember('','release',release)
Do JSON.$addmember('','timestamp',timestamp)
Do JSON.$addmember('','sdk','')
Do JSON.$addmember('','message',pErrorText)
Do JSON.$addmember('','level',pLevel)
Do JSON.$addmember('','tags','')
</pre>

=== HTTP-Kommunikation ===

<code>OSentry.$captureException</code> sendet den erzeugten JSON-Payload an Sentry:

<pre>
#Generate HTTP Auth header
Begin text block
Text:Sentry sentry_version=7,
Text:sentry_timestamp=[$cinst.$getUnixTimestamp()],
Text:sentry_key=[iPubKey],
Text:sentry_client=omnis/1.0
End text block
Get text block auth

#Generate header list
Calculate Host as 'sentry.io'
Calculate Url as con('/api/',iProID,'/store/')
Do HdrList.$define(wert,name)
Do HdrList.$add('User-Agent','omnis/1.0')
Do HdrList.$add('Content-Type','application/json')
Do HdrList.$add('Content-Length',binlength(json))
Do HdrList.$add('X-Sentry-Auth',auth)
</pre>

Anschließend wird der Request über <code>HTTPPost</code>, <code>HTTPSend</code> und <code>HTTPRead</code> ausgeführt.

=== Fehlerbehandlung beim Senden ===

Wenn der Socket nicht geöffnet werden kann:

<pre>
HTTPPost (Host,Url,,HdrList,443,kTrue,kTrue) Returns Socket
If Socket<0
#Error when opening connection -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Error ',Socket,' when performing HTTPPost'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -1
End If
</pre>

Wenn das Senden fehlschlägt:

<pre>
HTTPSend (Socket,json) Returns byteCount
If byteCount<0
# Error while sending data -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Erorr ',byteCount,' when performing HTTPSend'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -2
End If
</pre>

Wenn die Antwort nicht erfolgreich ist:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

=== Lokales Speichern ===

Bei Fehlern wird der JSON Report lokal im Omnis-Installationsordner gespeichert:

<pre>
#Writes the json and the http buffer to a file in the omnis installation folder
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
Do fOP.$writecharacter(kUniTypeUTF8,pJSON) Returns err
If not(isclear(pBuffer))
Do fOP.$writecharacter(kUniTypeUTF8,con(kCr,pBuffer),kTrue) Returns err
End If
Do fOP.$closefile()

Quit method
</pre>

=== Cleanup ===

Nach erfolgreichem Senden werden [[#Tags, Extras und User-Kontext|Tags und Extras]] gelöscht:

<pre>
#Clears all extras and tags => to be used after a sentry request has successfully been sent
Do iTagList.$clear()
Do iExtraList.$clear()
Quit method
</pre>

== Demo Library ==

Die Demo-Library zeigt, wie <code>OSentry</code> initialisiert wird und wie verschiedene [[#Events erfassen|Event-Typen]] aus einer Omnis-Oberfläche heraus an Sentry gesendet werden.

=== Bestandteile ===

{| class="wikitable"
! Klasse !! Zweck
|-
| <code>Startup_Task</code> || Initialisiert Sentry, SQLite und öffnet das Demo-Fenster
|-
| <code>FSY_Demo</code> || Demo-Fenster
|-
| <code>ODummy</code> || Erzeugt Demo-Stack für Exception
|-
| <code>ODatabaseHandler</code> || Erstellt SQLite-Demo-Datenbank
|-
| <code>OSLSession</code> || SQLite Session
|-
| <code>OSentry</code> || Low-Level-Sentry-Adapter
|-
| <code>OSentryHL</code> || High-Level-Sentry-Adapter
|}

=== Startup ===

<code>Startup_Task.$construct</code> initialisiert Sentry, baut eine SQLite Session auf und öffnet das Demo-Fenster. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()

#SQLite Session init
Do $objects.OSLSession.$newref() Returns tOSLSession
#Calculate tOSLSession.$opencreate as kTrue
Calculate workingDir as tODatabaseHandler.$getWorkingDir()
Do con(workingDir,'Sentry_Test.db') Returns dbLocation
Do tOSLSession.$logon(dbLocation,'','','slsession') Returns #F

#Open Test Window
Do $windows.FSY_Demo.$openonce('*')

Quit method
</pre>

=== Demo-Fenster ===

<code>FSY_Demo</code> enthält folgende Bereiche:

* DSN Configuration
* DB Status
* Actions

Wichtige Felder:

{| class="wikitable"
! Feld !! Datenanbindung
|-
| DSN || <code>iDSN</code>
|-
| Host || <code>tSentry.iOSentry.iHost</code>
|-
| Public Key || <code>tSentry.iOSentry.iPubKey</code>
|-
| Project ID || <code>tSentry.iOSentry.iProID</code>
|-
| DB Status || <code>iCurrentDBStatus</code>
|}

[[Datei:Demo-window.svg|850px|Demo-Fenster der OSentry Library]]

=== DSN setzen ===

Die DSN wird im Feld <code>iDSN</code> erfasst. Der Button <code>Set DSN</code> ruft anschließend <code>tSentry.$init(iDSN)</code> auf. Nach dem Setzen werden Public Key, Host und Project ID aus der DSN gelesen und in den darunterliegenden Feldern angezeigt.

[[Datei:Demo-dsn.svg|850px|DSN-Konfiguration im Demo-Fenster]]

Der Button <code>Set DSN</code> initialisiert Sentry mit der eingegebenen DSN. Quelle: <code>FSY_Demo.setDSN.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$init(iDSN)
Calculate $cclass.$ivardefs.iDSN.$objinitval as con(kSq,iDSN,kSq)

Do $cinst.$showmessage('DSN set and Sentry initialized!','Info')

Do $cinst.$redraw()
Quit method
</pre>

=== DB Status anzeigen ===

<code>FSY_Demo.$displayDBState</code> zeigt, ob die SQLite Session verbunden ist. Quelle: <code>FSY_Demo.$displayDBState</code>.

<pre>
Do tOSLSession.$state Returns dbState
If dbState='kSessionStateLoggedOff'
Calculate iCurrentDBStatus as 'Logged Off'
Else If dbState='kSessionStateLoggedOn'
Calculate iCurrentDBStatus as 'Logged On'
Else
Calculate iCurrentDBStatus as 'Unkown DB State'
End If

Do $cinst.$redraw()
Quit method
</pre>

=== Demo-Datenbank erstellen ===

Der Button <code>Create Database</code> ruft <code>ODatabaseHandler.$DBFirstInit</code> auf. Quelle: <code>FSY_Demo.createDB.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Setup the DB
Do tODatabaseHandler.$DBFirstInit() Returns err
If err=0
Do $cinst.$showmessage('DB successfully created!','Info')
Else
Do $cinst.$showmessage('Error while creating the DB. Make sure that the DB does not already exist.','Info')
End If

Do $cinst.$displayDBState()

Quit method
</pre>

Die Datenbank wird im Arbeitsverzeichnis der Library angelegt. Quelle: <code>ODatabaseHandler.$getWorkingDir</code>.

<pre>
Quit method con(FileOps.$parentdir($clib.$pathname),pathsep())
</pre>

Die Demo-DB enthält unter anderem:

* <code>dperson</code>
* <code>drelease</code>
* <code>dvcs</code>

=== Message auslösen ===

Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Log auslösen ===

Button <code>Trigger a log</code>. Quelle: <code>FSY_Demo.log.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception auslösen ===

Button <code>Trigger an exception</code> bereitet eine Row und eine List vor und ruft anschließend <code>ODummy.$dummyMethod</code> auf. Quelle: <code>FSY_Demo.exception.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do iDummyRow.$define(id,name)
Calculate iDummyRow.id as 22
Calculate iDummyRow.name as 'Tom'

Do iDummyList.$define(id,weekday)
Do iDummyList.$add(1,'Monday')
Do iDummyList.$add(2,'Tuesday')
Do iDummyList.$add(3,'Wednesday')
Do iDummyList.$add(4,'Thursday')
Do iDummyList.$add(5,'Friday')
Do iDummyList.$add(6,'Saturday')
Do iDummyList.$add(7,'Sunday')

Calculate iDummyList.$line as 5

Do iODummy.$dummyMethod('Important Value')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')

Quit method
</pre>

<code>ODummy.$dummyMethod</code> sendet die Exception. Quelle: <code>ODummy.$dummyMethod</code>.

<pre>
#In here is some logic
#This logic would produce an error
#We send all this information to Sentry

Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')

Quit method 0
</pre>

=== Deprecated Call auslösen ===

Button <code>Trigger a deprecated call</code>. Quelle: <code>FSY_Demo.deprecatedCall.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureDeprecatedCall()
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== SQL Exception Button ===

Der Button <code>Trigger an SQLException</code> ist im Export vorhanden, enthält aber noch keinen fertigen Demo-Code. Quelle: <code>FSY_Demo.sqlException.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Für die Dokumentation der SQL-Erfassung siehe [[#Events erfassen|03 Events erfassen]].

== API Reference ==

Diese Seite dokumentiert die produktiv relevanten Methoden von <code>OSentryHL</code> und <code>OSentry</code>.

=== OSentryHL ===

<code>OSentryHL</code> ist die empfohlene Klasse für Applikationscode.

'''<code>$init(pDSN)</code>'''

Initialisiert das interne <code>OSentry</code>-Objekt.

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

'''<code>$captureMessage(pMessage)</code>'''

Sendet eine einfache Info-Message.

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel)</code>'''

Sendet eine generische Exception.

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

'''<code>$captureAnything(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface)</code>'''

Sendet ein frei konfigurierbares Event.

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Hinweis: Der Parameter ist im Export als <code>pStacktraveInterface</code> geschrieben.

'''<code>$captureLog(pErrorText)</code>'''

Sendet ein Log-Event.

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

'''<code>$captureDeprecatedCall()</code>'''

Meldet die Ausführung eines veralteten Codepfads.

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

'''<code>$captureSQLException(pErrorText,pStat)</code>'''

Meldet einen SQL-Fehler mit SQL-Text und nativer Datenbankfehlermeldung.

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag für das nächste Event hinzu.

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra für das nächste Event hinzu.

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

'''<code>$setStatus(pStatus)</code>'''

Aktiviert oder deaktiviert Sentry.

<pre>
#Toggels Sentry on or off
Do iOSentry.$setStatus(pStatus)
Quit method
</pre>

'''<code>$setUser()</code>'''

Setzt im Export feste [[#Demo Library|Demo]]-Userdaten.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode parametrisiert werden.

=== OSentry ===

<code>OSentry</code> ist die Low-Level-Klasse für Payload-Erzeugung und Versand.

'''<code>$init(pDSN)</code>'''

Parst die DSN in Protokoll, Public Key, Host und Project ID.

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraceInterface,pUserInterface,pExceptionInterface)</code>'''

Erzeugt JSON, sendet es an Sentry und behandelt Fehlerfälle.

Parameter:

{| class="wikitable"
! Parameter !! Default !! Bedeutung
|-
| <code>pErrorText</code> || || Message
|-
| <code>pErrorCode</code> || || Fehlercode
|-
| <code>pExcType</code> || || Exception-Typ
|-
| <code>pLevel</code> || || <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code>, <code>debug</code>
|-
| <code>pStacktraceInterface</code> || <code>kTrue</code> || [[#Stacktrace und Kontext|Stacktrace]] senden
|-
| <code>pUserInterface</code> || <code>kTrue</code> || [[#Tags, Extras und User-Kontext|User-Kontext]] senden
|-
| <code>pExceptionInterface</code> || <code>kTrue</code> || Exception Interface senden
|}

'''<code>$generateJson(...)</code>'''

Erzeugt den Sentry JSON Payload als Binary.

'''<code>$generateStacktraceInterface(pCulprit)</code>'''

Erzeugt den Omnis-[[#Stacktrace und Kontext|Stacktrace]] inklusive Variablen und Kontextzeilen.

'''<code>$generateExceptionInterface(pType,pValue)</code>'''

Erzeugt das Sentry Exception Interface.

<pre>
# Generate Row to store in the JSON
Do exceptionRow.$define(type,value,stacktrace)
Calculate exceptionRow.type as pType
Calculate exceptionRow.value as pValue
Calculate exceptionRow.stacktrace as 'sentry.interfaces.stacktrace' ## Tells the exception interface that a stacktrace is passed aswell
</pre>

'''<code>$generateUserInterface()</code>'''

Erzeugt den [[#Tags, Extras und User-Kontext|User-Kontext]].

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag zur internen Tag-Liste hinzu.

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra zur internen Extra-Liste hinzu.

'''<code>$clearList()</code>'''

Leert [[#Tags, Extras und User-Kontext|Tags und Extras]] nach einem Request.

'''<code>$setUserData(pID,pName,pEmail)</code>'''

Setzt Userdaten für den nächsten Request.

'''<code>$setProxy(pProxyHost,pProxyPort)</code>'''

Setzt Proxy-Informationen.

'''<code>$setStatus(pStatus)</code>'''

Setzt den Sentry-Status.

<pre>
#Toggels Sentry Reports on or off
Calculate iStatus as pStatus
Quit method
</pre>

'''<code>$writeJSON(pJSON,pBuffer)</code>'''

Schreibt fehlgeschlagene Reports lokal in eine Datei.

'''<code>$getUnixTimestamp()</code>'''

Gibt den aktuellen UNIX Timestamp zurück.

'''<code>$generateUUID()</code>'''

Erzeugt eine UUID für die Sentry Event ID.

<pre>
#Genereates a UUID for the issue id
Quit method OW3.$makeuuid(kFalse)
</pre>

== Troubleshooting ==

=== Es erscheinen keine Events in Sentry ===

Prüfe zuerst, ob Sentry aktiv ist:

<pre>
Do tSentry.$setStatus(1)
</pre>

<code>OSentry.$captureException</code> beendet sich sofort, wenn der Status <code>0</code> oder leer ist:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

=== Die DSN ist falsch ===

Prüfe, ob die DSN korrekt aus Sentry kopiert wurde. <code>OSentry.$init</code> erwartet eine DSN, aus der Public Key, Host und Project ID gelesen werden können.

Nach dem Setzen der DSN sollten in der [[#Demo Library|Demo-Library]] folgende Felder gefüllt sein:

* Host
* Public Key
* Project ID

=== Netzwerk oder Proxy blockiert den Request ===

Wenn die Anwendung keinen direkten Zugriff auf Sentry hat, setze einen Proxy:

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Intern wird der Proxy vor dem HTTP Request gesetzt:

<pre>
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Report wird lokal gespeichert ===

Wenn <code>HTTPPost</code>, <code>HTTPSend</code> oder <code>HTTPRead</code> fehlschlägt, speichert OSentry den Report lokal:

<pre>
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
</pre>

Suche im Omnis-Installationsordner nach Dateien mit dem Namen:

<pre>
Sentryreport_<timestamp>.json
</pre>

=== Sentry antwortet nicht mit 200 OK ===

Wenn die HTTP-Antwort kein <code>200 OK</code> enthält, wird der JSON Report ebenfalls lokal gespeichert:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

Mögliche Ursachen:

* falsche Project ID
* falscher Public Key
* ungültige DSN
* JSON Payload wird von Sentry abgelehnt
* Netzwerk-Gateway verändert den Request

=== Tags oder Extras erscheinen beim falschen Event ===

[[#Tags, Extras und User-Kontext|Tags und Extras]] werden für den nächsten Request gesammelt. Nach erfolgreichem Request werden sie gelöscht:

<pre>
Do iTagList.$clear()
Do iExtraList.$clear()
</pre>

Wenn ein Request fehlschlägt, wird ebenfalls aufgeräumt:

<pre>
Do $cinst.$clearList()
</pre>

Prüfe trotzdem, ob in eigenen Wrapper-Methoden Tags und Extras direkt vor dem passenden Capture-Aufruf gesetzt werden.

=== User-Kontext zeigt Demo-Daten ===

<code>OSentryHL.$setUser</code> verwendet im Export feste Testdaten:

<pre>
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
</pre>

Für produktive Nutzung sollte die Methode parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
</pre>

=== SQL Exception Demo-Button funktioniert nicht ===

Der Button <code>Trigger an SQLException</code> ist im Export noch nicht implementiert:

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Die produktive Methode für SQL-Fehler ist aber vorhanden. Siehe auch [[#Events erfassen|Events erfassen]].

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

=== Zu viele Events ===

Sentry kann sehr schnell viele Events sammeln. Verwende für produktive Systeme:

* klare Wrapper-Methoden in <code>OSentryHL</code>
* sinnvolle Levels
* gezielte [[#Tags, Extras und User-Kontext|Tags]]
* keine Events in sehr häufigen Schleifen
* keine rein informativen Debug-Events ohne Nutzen

=== Sensible Daten ===

[[#Stacktrace und Kontext|Stacktrace]], Parameter, Instance Variablen, SQL-Text und [[#Tags, Extras und User-Kontext|Extras]] können sensible Daten enthalten. Prüfe vor produktiver Nutzung:

* Welche Variablen werden übertragen?
* Enthalten SQL-Statements personenbezogene Daten?
* Werden Tokens oder Passwörter in Extras geschrieben?
* Sollen bestimmte Werte maskiert werden?

Sentry

2026-06-12T14:05:39Z

Silvan:

__TOC__

== Überblick ==

OSentry ist ein REST-API-Konnektor von Omnis Studio zu Sentry. Der Konnektor sendet Fehler, Messages, Logs und Laufzeitkontext aus Omnis-Anwendungen an Sentry, damit Probleme in produktiven Systemen sichtbar, gruppierbar und analysierbar werden.

Diese Dokumentation beschreibt die [[#Installation|Installation]], die Nutzung in bestehenden Omnis-Anwendungen, die Definition eigener standardisierter Exception-Typen, die interne Struktur und die [[#Demo Library|Demo-Library]].

=== Inhalt ===

* [[#Installation|01 Installation]]
* [[#Quickstart|02 Quickstart]]
* [[#Events erfassen|03 Events erfassen]]
* [[#Eigene Exceptions standardisieren|04 Eigene Exceptions standardisieren]]
* [[#Tags, Extras und User-Kontext|05 Tags Extras und User]]
* [[#Stacktrace und Kontext|06 Stacktrace und Kontext]]
* [[#Interne Architektur|07 Interne Architektur]]
* [[#Demo Library|08 Demo Library]]
* [[#API Reference|09 API Reference]]
* [[#Troubleshooting|10 Troubleshooting]]

=== Kernidee ===

OSentry besteht aus zwei produktiv relevanten Klassen:

* <code>OSentryHL</code>: High-Level-Adapter für die Anwendung. Diese Klasse sollte von normalem Applikationscode aufgerufen werden.
* <code>OSentry</code>: Low-Level-Adapter für DSN-Parsing, JSON-Erzeugung, [[#Stacktrace und Kontext|Stacktrace]]-Aufbereitung und HTTP-Kommunikation mit Sentry.

Die Anwendung arbeitet im Normalfall mit <code>OSentryHL</code>. Dadurch bleiben Sentry-spezifische Details zentral gekapselt und neue standardisierte Exception-Typen können als eigene Methoden in <code>OSentryHL</code> definiert werden.

=== Hauptfeatures ===

* Direkte Anbindung von Omnis Studio an Sentry über REST API und DSN
* Erfassen von Exceptions, Messages, Logs und SQL-Fehlern
* Unterstützung der Sentry-Level <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code> und <code>debug</code>
* Automatische Omnis-Kontextinformationen
* Omnis-[[#Stacktrace und Kontext|Stacktrace]] mit Klassen, Methoden, Zeilen und Variablen
* [[#Tags, Extras und User-Kontext|Tags]] für Filterung und Gruppierung
* [[#Tags, Extras und User-Kontext|Extras]] für zusätzliche Diagnoseinformationen
* Optionaler [[#Tags, Extras und User-Kontext|User-Kontext]]
* Proxy-Unterstützung
* Aktivieren und Deaktivieren der Sentry-Übertragung
* Lokales Speichern von Reports bei Übertragungsfehlern

=== Weiterführende Links ===

* [https://sentry.io/welcome/ Sentry Website]
* [https://sentry.io/signup/ Sentry Account erstellen]
* [https://develop.sentry.dev/self-hosted/ Sentry self-hosted]

=== Screenshots ===

[[Datei:Sentry-issue.png|900px|Sentry Issue-Übersicht]]

== Installation ==

Diese Seite beschreibt, wie OSentry in eine bestehende Omnis-Anwendung integriert wird.

=== Voraussetzungen ===

* Omnis Studio Anwendung
* Sentry Account oder self-hosted Sentry Installation
* Ein Sentry-Projekt mit SDK-Typ <code>Other</code>
* Die DSN des Sentry-Projekts
* Netzwerkzugriff auf Sentry

Die exportierte [[#Demo Library|Demo-Library]] wurde mit Omnis <code>11.1</code> erstellt.

=== Sentry-Projekt erstellen ===

# In Sentry ein neues Projekt erstellen.
# Als SDK <code>Other</code> auswählen.
# Die DSN des Projekts kopieren.

Die DSN wird beim Initialisieren verwendet. <code>OSentry</code> zerlegt sie intern in Public Key, Host und Project ID.

[[Datei:Sentry-projects.png|900px|Sentry Projektübersicht]]

=== Klassen kopieren ===

Kopiere die folgenden Klassen in deine bestehende Omnis-Library:

* <code>OSentry</code>
* <code>OSentryHL</code>

Die Demo-spezifischen Klassen sind für die produktive Integration nicht erforderlich. Damit sind die übrigen Klassen der Demo-Library gemeint, zum Beispiel <code>FSY_Demo</code>, <code>ODummy</code>, <code>ODatabaseHandler</code> und <code>OSLSession</code>. Diese Klassen dienen nur dazu, die [[#Demo Library|Demo-Library]] mit Fenster, SQLite-Testdaten und Beispielaufrufen auszuführen.

=== Task Variable anlegen ===

Lege in deiner Startup Task eine Task Variable an:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' <code>tSentry</code> sollte als global erreichbarer Singleton der Anwendung verwendet werden. In Omnis ist dafür eine Task Variable sinnvoll, weil sie von Fenstern, Objektklassen und zentralen Error-Handlern aus konsistent erreichbar ist. Dadurch gibt es genau eine aktive Sentry-Konfiguration mit einer DSN, einem Status, optionalen Proxy-Daten und gemeinsamen Wrapper-Methoden in <code>OSentryHL</code>.</div>

Im [[#Demo Library|Demo-Projekt]] ist diese Variable in <code>Startup_Task</code> definiert.

=== Initialisierung im Startup Task ===

Initialisiere <code>tSentry</code> beim Start deiner Anwendung mit der DSN deines Sentry-Projekts:

<pre>
Do tSentry.$init('<DSN>')
</pre>

Die [[#Demo Library|Demo-Library]] ruft im Startup Task ebenfalls die Initialisierung auf. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()
</pre>

In einer produktiven Anwendung sollte die DSN explizit oder aus einer Konfiguration übergeben werden:

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Speichere die DSN in einer Datenbank, einer Konfigurationstabelle oder einem Config File. So kann sie pro Kunde, Umgebung oder Installation geändert werden, ohne die Library neu auszuliefern.</div>

=== Testcall ===

Nach der Initialisierung kann ein erstes Testevent gesendet werden:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Wenn alles korrekt eingerichtet ist, erscheint das Event im Sentry-Projekt.

=== Proxy konfigurieren ===

Falls die Anwendung in einem geschützten Netzwerk läuft, kann ein Proxy gesetzt werden. Die Methode befindet sich im Low-Level-Objekt <code>OSentry</code>.

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Die interne Implementierung setzt den Proxy vor dem HTTP-Request:

<pre>
#Configure proxy; needed when sending data out of secured networks
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Sentry aktivieren oder deaktivieren ===

OSentry kann zentral ein- oder ausgeschaltet werden.

<div style="border-left:4px solid #3366cc; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Empfehlung:''' Deaktiviere Sentry in der Entwicklungs-Version standardmäßig oder verwende eine separate Entwicklungs-DSN. So landen lokale Tests, Debug-Fehler und absichtlich ausgelöste Exceptions nicht im produktiven Sentry-Projekt.</div>

<pre>
Do tSentry.$setStatus(1) ## aktiv
Do tSentry.$setStatus(0) ## inaktiv
</pre>

Im Low-Level-Objekt <code>OSentry</code> wird vor dem Senden geprüft:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

== Quickstart ==

Diese Seite zeigt die minimale Integration in eine bestehende Omnis-Anwendung.

=== Klassen übernehmen ===

Kopiere <code>OSentry</code> und <code>OSentryHL</code> in deine Library.

=== Task Variable erstellen ===

In der Startup Task:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

=== Sentry initialisieren ===

<pre>
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</pre>

<code>OSentryHL.$init</code> delegiert an das Low-Level-Objekt <code>OSentry</code>:

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

=== Message senden ===

<pre>
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
</pre>

Die [[#Demo Library|Demo-Library]] verwendet genau diesen Aufruf im Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception senden ===

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

=== In Sentry prüfen ===

In Sentry sollte anschließend ein neues Event sichtbar sein. Je nach Event-Typ enthält es:

* Message
* Level
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Tags, Extras und User-Kontext|User-Kontext]]
* [[#Stacktrace und Kontext|Stacktrace]]
* Omnis-Kontextinformationen

== Events erfassen ==

OSentryHL ist die empfohlene Einstiegsschicht für Applikationscode. Die Klasse bietet sprechende Methoden für typische Event-Arten und ruft intern <code>OSentry.$captureException</code> auf.

=== Message ===

Eine einfache Information wird mit <code>$captureMessage</code> gesendet:

<pre>
Do tSentry.$captureMessage('Hello World!')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

Verhalten:

* Level: <code>info</code>
* Kein [[#Stacktrace und Kontext|Stacktrace]]
* Kein [[#Tags, Extras und User-Kontext|User Interface]]
* Geeignet für einfache Statusmeldungen oder technische Hinweise

=== Log ===

Ein Log-Event wird mit <code>$captureLog</code> gesendet:

<pre>
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

Verhalten:

* Level: <code>warning</code>
* [[#Stacktrace und Kontext|Stacktrace]] aktiv
* Exception Interface in diesem Wrapper deaktiviert
* [[#Tags, Extras und User-Kontext|User Interface]] aktiv

=== Generische Exception ===

Eine generische Exception wird mit <code>$captureException</code> gesendet:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

Parameter:

{| class="wikitable"
! Parameter !! Bedeutung
|-
| <code>pErrorText</code> || Text, der in Sentry als Message sichtbar ist
|-
| <code>pErrorCode</code> || Fehlercode oder fachlicher Code
|-
| <code>pExcType</code> || Exception-Typ für Benennung und Gruppierung
|-
| <code>pLevel</code> || Sentry-Level
|}

Gültige Levels:

* <code>fatal</code>
* <code>error</code>
* <code>warning</code>
* <code>info</code>
* <code>debug</code>

=== SQL Exception ===

SQL-Fehler können mit <code>$captureSQLException</code> gemeldet werden.

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

Verhalten:

* Fügt die Datenbank als [[#Tags, Extras und User-Kontext|Tag]] hinzu
* Fügt SQL-Text als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Fügt native Datenbankfehlermeldung als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Sendet das Event als <code>SQL-Exception</code> mit Level <code>error</code>

=== Deprecated Call ===

Veraltete Codepfade können gezielt gemeldet werden:

<pre>
Do tSentry.$captureDeprecatedCall()
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

Dieser Wrapper eignet sich, um zu erkennen, ob alter Code in produktiven Systemen noch ausgeführt wird.

=== Frei konfigurierbares Event ===

Für Sonderfälle gibt es <code>$captureAnything</code>:

<pre>
Do tSentry.$captureAnything('Text',1001,'Custom Type','error',kTrue,kTrue,kTrue)
</pre>

Implementierung in <code>OSentryHL</code>:

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Diese Methode bietet maximale Flexibilität. Für wiederkehrende Exception-Typen sollte aber eine eigene Methode in <code>OSentryHL</code> angelegt werden. Siehe [[#Eigene Exceptions standardisieren|04 Eigene Exceptions standardisieren]].

== Eigene Exceptions standardisieren ==

Wenn ein Exception-Typ mehrfach in der Anwendung vorkommt, sollte er nicht überall manuell mit <code>$captureException</code> aufgebaut werden. Besser ist eine eigene Methode in <code>OSentryHL</code>.

Dadurch entsteht eine zentrale, wiederverwendbare Definition für:

* Exception-Typ
* Sentry-Level
* Fehlercode
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Stacktrace und Kontext|Stacktrace]]/[[#Tags, Extras und User-Kontext|User]]/Exception Interface

Die automatisch gesetzten [[#Tags, Extras und User-Kontext|Tags und Extras]] aus <code>OSentry.$generateJson</code> müssen in solchen Wrappern nicht erneut ergänzt werden. Eigene Exception-Methoden setzen nur zusätzliche Werte, die für diesen standardisierten Exception-Typ relevant sind.

=== Warum über OSentryHL? ===

<code>OSentryHL</code> ist die Abstraktionsschicht für Applikationscode. Sie kapselt die Details von <code>OSentry</code> und sorgt dafür, dass Aufrufe in der Anwendung kurz und konsistent bleiben.

Bestehende Beispiele aus <code>OSentryHL</code>:

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

=== Empfohlenes Muster ===

Für jeden standardisierten Exception-Typ wird eine eigene Methode in <code>OSentryHL</code> erstellt.

Beispiel:

<pre>
# Captures a validation exception
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addExtra('Field',pField)
Do $cinst.$addExtra('Invalid Value',pValue)

Do iOSentry.$captureException(pErrorText,2001,'Validation-Exception','warning',1,1,1) Returns code

Quit method code
</pre>

Mögliche Parameter der neuen Methode:

{| class="wikitable"
! Parameter !! Beispiel !! Zweck
|-
| <code>pErrorText</code> || <code>'Invalid customer number'</code> || Sentry Message
|-
| <code>pModule</code> || <code>'Customer'</code> || Filterbarer Tag
|-
| <code>pField</code> || <code>'cu_number'</code> || Diagnoseinformation
|-
| <code>pValue</code> || <code>'ABC'</code> || Diagnoseinformation
|}

Der Applikationscode bleibt dadurch einfach:

<pre>
Do tSentry.$captureValidationException('Invalid customer number','Customer','cu_number',cu_number)
</pre>

=== Beispiel: Business Rule Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures a business rule violation
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do $cinst.$addExtra('Details',pDetails)

Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureBusinessRuleViolation('Invoice cannot be posted','Invoice','PostingAllowed','Invoice is missing customer')
</pre>

=== Beispiel: Integration Exception ===

Neue Methode in <code>OSentryHL</code>:

<pre>
# Captures an integration exception
Do $cinst.$addTag('Integration',pSystem)
Do $cinst.$addTag('Endpoint',pEndpoint)
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)

Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code

Quit method code
</pre>

Aufruf in der Anwendung:

<pre>
Do tSentry.$captureIntegrationException('External API request failed','ERP','/api/customer',jsonPayload,responseText)
</pre>

=== Namenskonventionen ===

Empfehlung für neue Methoden:

* Methodenname beginnt mit <code>$capture</code>
* Der fachliche Typ steht im Methodennamen
* Der Sentry Exception Type ist stabil und ändert sich nicht laufend
* [[#Tags, Extras und User-Kontext|Tags]] sind kurz und filterbar
* [[#Tags, Extras und User-Kontext|Extras]] dürfen länger sein und Diagnoseinformationen enthalten

Beispiele:

* <code>$captureValidationException</code>
* <code>$captureBusinessRuleViolation</code>
* <code>$captureIntegrationException</code>
* <code>$capturePermissionViolation</code>
* <code>$captureConfigurationError</code>

=== Error Codes ===

Verwende feste Fehlercodes für standardisierte Exception-Typen. Dadurch können Events in Sentry besser gefiltert und wiedererkannt werden.

Beispiel:

{| class="wikitable"
! Code !! Exception Type
|-
| <code>2001</code> || <code>Validation-Exception</code>
|-
| <code>3001</code> || <code>Business-Rule-Violation</code>
|-
| <code>4001</code> || <code>Integration-Exception</code>
|-
| <code>5001</code> || <code>Configuration-Error</code>
|}

=== Wann nicht standardisieren? ===

Nicht jeder Einzelfall braucht eine eigene Methode. Für einmalige technische Tests oder sehr spezielle Fälle reicht:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

Sobald ein Exception-Typ aber mehrfach vorkommt oder fachlich relevant ist, sollte er als eigene Methode in <code>OSentryHL</code> definiert werden.

== Tags, Extras und User-Kontext ==

Tags, Extras und User-Kontext reichern Sentry-Events mit zusätzlichen Informationen an. Diese Informationen helfen beim Filtern, Gruppieren und Analysieren.

[[Datei:Sentry-tags.png|900px|Sentry Tags und User-Kontext]]

=== Tags ===

Tags sind kurze, filterbare Werte.

Beispiele:

* Datenbank
* Kunde
* Modul
* Umgebung
* Error Code
* Omnis-Version

Methode in <code>OSentryHL</code>:

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds a tag to the next request processed
Do iTagList.$add(pName,pValue)
Quit method
</pre>

Beispiel:

<pre>
Do tSentry.$addTag('Module','Invoice')
Do tSentry.$addTag('Customer','10001')
Do tSentry.$captureException('Invoice posting failed',3001,'Business-Rule-Violation','warning')
</pre>

=== Extras ===

Extras sind Detailinformationen, die nicht primär zum Filtern gedacht sind.

Beispiele:

* SQL-Text
* Native Datenbankfehlermeldung
* Payload
* Response Body
* interne IDs
* zusätzliche Debug-Informationen

Methode in <code>OSentryHL</code>:

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

Methode in <code>OSentry</code>:

<pre>
#Adds extra information to the next request being processed
Do iExtraList.$add(pName,pValue)
Quit method
</pre>

Beispiel aus der SQL Exception:

<pre>
Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)
</pre>

=== Automatische Tags ===

Die folgenden Tags werden bei jedem Event automatisch von <code>OSentry.$generateJson</code> ergänzt. Sie müssen bei eigenen Exceptions nicht erneut gesetzt werden. Eigene Wrapper-Methoden in <code>OSentryHL</code> sollten nur zusätzliche, fachlich oder technisch relevante Tags hinzufügen.

<code>OSentry.$generateJson</code> fügt mehrere Tags automatisch hinzu:

<pre>
# Add static tags
Do iTagList.$add('Omnisversion',sys(1))
Calculate systemversionRow as systemversion()
Do iTagList.$add('Plattform',con(sys(8),pick(systemversionRow.server,'',' SRV')))
Do iTagList.$add('OS Version',con(systemversionRow.major,'.',systemversionRow.minor,'.',systemversionRow.build))
Do iTagList.$add('error_code',pErrorCode)
</pre>

Automatisch gesendete Tags:

{| class="wikitable"
! Tag !! Herkunft !! Zweck
|-
| <code>Omnisversion</code> || <code>sys(1)</code> || Zeigt, mit welcher Omnis-Version das Event erzeugt wurde
|-
| <code>Plattform</code> || <code>sys(8)</code> und Server-Flag aus <code>systemversion()</code> || Unterscheidet Plattform und Server Runtime
|-
| <code>OS Version</code> || <code>systemversionRow.major/minor/build</code> || Zeigt die Betriebssystemversion
|-
| <code>error_code</code> || Parameter <code>pErrorCode</code> || Verbindet das Event mit dem übergebenen Fehlercode
|}

Beispiel für eine eigene Exception: Der Wrapper muss nicht erneut <code>Omnisversion</code> oder <code>OS Version</code> setzen. Er ergänzt nur das, was für diesen Exception-Typ zusätzlich hilfreich ist.

<pre>
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code
</pre>

=== Automatische Extras ===

Auch die folgenden Extras werden bei jedem Event automatisch ergänzt. Bei eigenen Exceptions müssen nur zusätzliche Extras gesetzt werden, zum Beispiel ein SQL-Statement, ein Payload oder fachliche Zusatzdaten.

<code>OSentry.$generateJson</code> fügt offene Fenster, offene Reports und die aktuelle Printfile hinzu:

<pre>
# Static extra 1: All open windows
Do $root.$iwindows.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate windows as con(windows,', ',nameList.[i].1)
End For
Calculate windows as right(windows,len(windows)-2)
Do iExtraList.$add('Open Windows',windows)

# Static extra 2: All open reports
Do $root.$ireports.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate reports as con(reports,', ',nameList.[i].1)
End For
Calculate reports as right(reports,len(reports)-2)
Do iExtraList.$add('Open Reports',reports)
Do iExtraList.$add('Current Printfile',$root.$prefs.$printfile)
</pre>

Automatisch gesendete Extras:

{| class="wikitable"
! Extra !! Herkunft !! Zweck
|-
| <code>Open Windows</code> || <code>$root.$iwindows.$makelist($ref.$name)</code> || Zeigt, welche Fenster im Moment des Events offen waren
|-
| <code>Open Reports</code> || <code>$root.$ireports.$makelist($ref.$name)</code> || Zeigt, welche Reports im Moment des Events offen waren
|-
| <code>Current Printfile</code> || <code>$root.$prefs.$printfile</code> || Zeigt die aktuell gesetzte Printfile
|}

Beispiel für zusätzliche Extras in einem eigenen Wrapper:

<pre>
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)
Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code
</pre>

=== User-Kontext ===

Der User-Kontext ordnet ein Event einem betroffenen Benutzer zu. In Sentry erscheint dadurch ein eigener User-Bereich, und Events können nach Benutzer gefiltert oder gruppiert werden. Das ist besonders hilfreich, wenn ein Fehler nur bei einzelnen Kunden, Arbeitsplätzen oder Benutzerkonten auftritt.

<code>OSentry</code> unterstützt drei User-Felder:

{| class="wikitable"
! Feld !! Bedeutung
|-
| <code>id</code> || stabile interne Benutzer-ID oder Kundennummer
|-
| <code>username</code> || lesbarer Benutzername
|-
| <code>email</code> || E-Mail-Adresse, falls sie übertragen werden darf
|}

Der User-Kontext wird nur in das Event geschrieben, wenn das User Interface beim Capture-Aufruf aktiviert ist. Die Standardmethode <code>OSentry.$captureException</code> hat <code>pUserInterface</code> standardmäßig auf <code>kTrue</code>. Einzelne High-Level-Methoden können das bewusst deaktivieren, zum Beispiel <code>$captureMessage</code>.

<code>OSentry</code> kann User-Daten an das Event anhängen:

<pre>
#Sets userinformation for the next request being processed
Calculate iUserID as pID
Calculate iUserName as pName
Calculate iUserEmail as pEmail
Quit method
</pre>

Das User Interface wird so generiert:

<pre>
# Create user data row
Do UserdataRow.$define(id,email,username)

Calculate UserdataRow.id as iUserID
Calculate UserdataRow.email as iUserEmail
Calculate UserdataRow.username as iUserName

Do JSON.$addmember('','user','')
Do JSON.$setobject('user',UserdataRow)

Calculate jsonString as OJSON.$formatjson(JSON.$getjson())

Quit method jsonString
</pre>

Die aktuelle Demo-Methode in <code>OSentryHL</code> verwendet feste Testdaten. Quelle: <code>OSentryHL.$setUser</code>.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode angepasst und parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
Quit method
</pre>

Empfohlen ist, den User nach Login oder beim Wechsel des aktiven Benutzers zentral zu setzen. Bei anonymen oder sensiblen Installationen kann statt Name und E-Mail auch nur eine interne ID oder ein pseudonymisierter Wert verwendet werden.

=== Datenschutz ===

<div style="border-left:4px solid #72777d; padding:8px 12px; margin:12px 0; background:#f8f9fa;">'''Datenschutz:''' Prüfe vor produktiver Nutzung, welche Daten an Sentry gesendet werden. Besonders kritisch sind personenbezogene Daten, SQL-Statements, Zugangsdaten, Tokens und interne Pfade.</div>

Besonders kritisch sind:

* personenbezogene Daten
* Kundendaten
* SQL-Statements mit Werten
* Zugangsdaten
* Tokens
* interne Pfade

Tags und Extras sollten so gestaltet werden, dass sie für die Fehleranalyse hilfreich sind, aber keine unnötigen sensiblen Daten übertragen.

== Stacktrace und Kontext ==

<code>OSentry</code> erzeugt einen Omnis-spezifischen Stacktrace und übergibt ihn an Sentry. Dadurch sieht man in Sentry nicht nur eine Fehlermeldung, sondern auch Klassen, Methoden, Zeilen und Variablenkontext. Ergänzende Informationen zu [[#Tags, Extras und User-Kontext|Tags, Extras und User-Kontext]] stehen auf der separaten Kontext-Seite.

[[Datei:Sentry-stack.png|900px|Sentry Stacktrace mit Omnis-Kontext]]

=== Stack lesen ===

<code>OSentry.$generateStacktraceInterface</code> verwendet <code>sys(192)</code>, um den aktuellen Omnis-Stack zu lesen:

<pre>
# Clean up the Stacklist (remove OSentry classes from the stack)
Do sys(192) Returns sys192List
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
If pos('OSentry',class.$name)>0|pos('OSentryHL',class.$name)>0
Do sys192List.[sys192List.$line].$selected.$assign(kTrue)
End If
End For
Do sys192List.$remove(kListDeleteSelected)
</pre>

Interne Frames von <code>OSentry</code> und <code>OSentryHL</code> werden entfernt, damit in Sentry die fachlich relevanten Stellen sichtbar bleiben.

=== SQL-Error Frames entfernen ===

Bestimmte interne SQL-Fehlerframes werden ebenfalls entfernt:

<pre>
# Remove some other classes which we do not want to display
If sys192List.1.method='$sqlerror'
Do sys192List.$remove(1)
Else If sys192List.1.method='$statementerror'
Do sys192List.$remove(1)
End If
</pre>

=== Frames erzeugen ===

Für jeden Stack-Eintrag werden Funktion, Zeilennummer und Kontextzeile erzeugt:

<pre>
#Loop through every item on the omnis stack
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
Calculate className as class.$name

# Create the content row
Do contentRow.$define(vars,function,pre_context,context_line,lineno,filename,post_context)
Calculate contentRow.lineno as sys192List.line
Calculate contentRow.filename as testFileName
Calculate contentRow.context_line as sys192List.linetext
If isclear(sys192List.object)
Calculate contentRow.function as con(className,'.',sys192List.method) ## If it's a class method
Else
Calculate contentRow.function as con(className,'.',sys192List.object,'.',sys192List.method) ## If it's a method of an object of a class (e.g. Headedlist)
End If
Do contentList.$add(contentRow)
End For
</pre>

=== Variablen aufnehmen ===

Pro Stackframe werden Instance Variablen und Parameter gesammelt:

<pre>
# Get all iVars
Do varList.$define(name,value)
Set reference class to sys192List.inst
Do $cinst.$getVars('ivars',class) Returns varList

# Get all params
Calculate paramList as sys192List.params
For paramList.$line from 1 to paramList.$linecount step 1
If not(paramList.value='(Not empty)')
Do varList.$add(paramList.name,paramList.value)
Else
Do varList.$add(paramList.name,'(Not empty)')
End If
End For
</pre>

=== Pre- und Post-Context ===

OSentry fügt Methodenzeilen vor und nach der aktuellen Zeile hinzu:

<pre>
# Pre Context (all method lines before the error occured)
Set reference method to sys192List.methoditem
Do precontextList.$define(line)
For i from 1 to sys192List.line-1 step 1
Do precontextList.$add(method.$methodlines.[i].$text)
End For

# Post Context (all method lines after the error occured
Do postcontextList.$define(line)
For i from sys192List.line+1 to method.$methodlines.$count step 1
Do postcontextList.$add(method.$methodlines.[i].$text)
End For
</pre>

=== Variablentypen ===

<code>OSentry.$getVars</code> unterstützt Basisvariablen, Rows und Lists.

Basisvariablen:

<pre>
If varType='char'|varType='boolean'|varType='integer'|varType='number'|varType='date'
Calculate varContent as pItemRef.$[pVarType].[varName]
Do varList.$add(varName,varContent)
</pre>

Rows:

<pre>
Else If varType='row'
Calculate varRow as pItemRef.$[pVarType].[varName]
If varRow.$colcount=0
Do varList.$add(varName,'(Empty)')
Else
For Z2 from 1 to varRow.$colcount step 1
Calculate varContent as con(varContent,varRow.$cols.[Z2].$name,': ',varRow.[Z2],', ')
End For
Do varList.$add(varName,varContent)
</pre>

Lists:

<pre>
Else If varType='list'
Calculate varListType as pItemRef.$[pVarType].[varName]
Calculate varContent as con('Colcount: ',varListType.$colcount,', ','Linecount: ',varListType.$linecount,', ','Current Line: ',varListType.$line)
If varListType.$linecount=0&varListType.$line=0&varListType.$colcount=0
Do varList.$add(varName,'(Empty)')
Calculate varContent as ''
Else
For Z3 from 1 to varListType.$colcount step 1
Calculate colName as varListType.$cols.[Z3].$name
Calculate varContent as con(varContent,' ',colName,': ',varListType.[colName])
End For
Do varList.$add(varName,varContent)
Calculate varContent as ''
End If
End If
</pre>

=== Hinweise ===

Stacktrace und Variablenkontext sind sehr hilfreich, können aber sensible Daten enthalten. Vor produktiver Nutzung sollte geprüft werden, ob bestimmte Variablen anonymisiert oder ausgeschlossen werden müssen.

== Interne Architektur ==

Diese Seite beschreibt die produktiv relevanten Klassen <code>OSentryHL</code> und <code>OSentry</code>.

=== Klassenübersicht ===

{| class="wikitable"
! Klasse !! Rolle
|-
| <code>OSentryHL</code> || High-Level-Adapter für Applikationscode
|-
| <code>OSentry</code> || Low-Level-Adapter für JSON, [[#Stacktrace und Kontext|Stacktrace]] und HTTP
|-
| <code>Startup_Task</code> || [[#Demo Library|Demo]]-Startup und Beispiel für Initialisierung
|-
| <code>FSY_Demo</code> || [[#Demo Library|Demo]]-Fenster
|-
| <code>ODummy</code> || [[#Demo Library|Demo]]-Code für [[#Stacktrace und Kontext|Stacktrace]]-Beispiel
|-
| <code>ODatabaseHandler</code> || [[#Demo Library|Demo]]-DB Initialisierung
|-
| <code>OSLSession</code> || SQLite Session für [[#Demo Library|Demo]]
|}

=== Empfohlener Aufrufweg ===

Applikationscode sollte <code>OSentryHL</code> verwenden:

<pre>
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</pre>

<code>OSentryHL</code> delegiert anschließend an <code>OSentry</code>:

<pre>
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code
</pre>

=== Ablauf eines Events ===

# Applikationscode ruft Methode in <code>OSentryHL</code> auf.
# <code>OSentryHL</code> fügt bei Bedarf [[#Tags, Extras und User-Kontext|Tags und Extras]] hinzu.
# <code>OSentryHL</code> ruft <code>iOSentry.$captureException(...)</code> auf.
# <code>OSentry</code> prüft, ob Sentry aktiv ist.
# <code>OSentry</code> erzeugt JSON.
# [[#Stacktrace und Kontext|Stacktrace]], Exception Interface und [[#Tags, Extras und User-Kontext|User Interface]] werden optional ergänzt.
# HTTP Header und Sentry Auth Header werden erstellt.
# JSON wird per HTTPS an Sentry gesendet.
# Bei Erfolg werden [[#Tags, Extras und User-Kontext|Tags und Extras]] geleert.
# Bei Fehler wird der JSON Report lokal gespeichert.

=== DSN Parsing ===

<code>OSentry.$init</code> zerlegt die DSN:

<pre>
# Parse the DSN into Public Key, Host and Project ID
If len(pDSN)>5
Calculate iDSN as pDSN
Calculate part1 as strtok('iDSN','@')
Calculate iProtocol as strtok('part1','/')
Calculate iProtocol as left(iProtocol,len(iProtocol)-1)
Do strtok('part1','/')
Calculate iPubKey as strtok('part1',':')

Calculate iHost as strtok('iDSN','/')
Calculate iProID as iDSN

#Save the values for the next startup
Calculate $cclass.$ivardefs.iPubKey.$objinitval as con('"',iPubKey,'"')
Calculate $cclass.$ivardefs.iHost.$objinitval as con('"',iHost,'"')
Calculate $cclass.$ivardefs.iProID.$objinitval as con('"',iProID,'"')
End If

Quit method
</pre>

=== JSON-Erzeugung ===

<code>OSentry.$generateJson</code> ist die zentrale Methode für den Payload. Sie setzt unter anderem:

* <code>event_id</code>
* <code>logger</code>
* <code>platform</code>
* <code>culprit</code>
* <code>timestamp</code>
* <code>sdk</code>
* <code>message</code>
* <code>level</code>
* <code>tags</code>
* <code>extra</code>
* optional <code>user</code>
* optional <code>exception</code>
* optional <code>stacktrace</code>

Auszug:

<pre>
# Add all required fields (those are required from the API)
Do JSON.$addmember('','event_id',$cinst.$generateUUID()) ## auto generated UUID 4
Do JSON.$addmember('','logger',logger)
Do JSON.$addmember('','platform',platform)
Do JSON.$addmember('','culprit',culprit)
#Do JSON.$addmember('','release',release)
Do JSON.$addmember('','timestamp',timestamp)
Do JSON.$addmember('','sdk','')
Do JSON.$addmember('','message',pErrorText)
Do JSON.$addmember('','level',pLevel)
Do JSON.$addmember('','tags','')
</pre>

=== HTTP-Kommunikation ===

<code>OSentry.$captureException</code> sendet den erzeugten JSON-Payload an Sentry:

<pre>
#Generate HTTP Auth header
Begin text block
Text:Sentry sentry_version=7,
Text:sentry_timestamp=[$cinst.$getUnixTimestamp()],
Text:sentry_key=[iPubKey],
Text:sentry_client=omnis/1.0
End text block
Get text block auth

#Generate header list
Calculate Host as 'sentry.io'
Calculate Url as con('/api/',iProID,'/store/')
Do HdrList.$define(wert,name)
Do HdrList.$add('User-Agent','omnis/1.0')
Do HdrList.$add('Content-Type','application/json')
Do HdrList.$add('Content-Length',binlength(json))
Do HdrList.$add('X-Sentry-Auth',auth)
</pre>

Anschließend wird der Request über <code>HTTPPost</code>, <code>HTTPSend</code> und <code>HTTPRead</code> ausgeführt.

=== Fehlerbehandlung beim Senden ===

Wenn der Socket nicht geöffnet werden kann:

<pre>
HTTPPost (Host,Url,,HdrList,443,kTrue,kTrue) Returns Socket
If Socket<0
#Error when opening connection -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Error ',Socket,' when performing HTTPPost'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -1
End If
</pre>

Wenn das Senden fehlschlägt:

<pre>
HTTPSend (Socket,json) Returns byteCount
If byteCount<0
# Error while sending data -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Erorr ',byteCount,' when performing HTTPSend'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -2
End If
</pre>

Wenn die Antwort nicht erfolgreich ist:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

=== Lokales Speichern ===

Bei Fehlern wird der JSON Report lokal im Omnis-Installationsordner gespeichert:

<pre>
#Writes the json and the http buffer to a file in the omnis installation folder
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
Do fOP.$writecharacter(kUniTypeUTF8,pJSON) Returns err
If not(isclear(pBuffer))
Do fOP.$writecharacter(kUniTypeUTF8,con(kCr,pBuffer),kTrue) Returns err
End If
Do fOP.$closefile()

Quit method
</pre>

=== Cleanup ===

Nach erfolgreichem Senden werden [[#Tags, Extras und User-Kontext|Tags und Extras]] gelöscht:

<pre>
#Clears all extras and tags => to be used after a sentry request has successfully been sent
Do iTagList.$clear()
Do iExtraList.$clear()
Quit method
</pre>

== Demo Library ==

Die Demo-Library zeigt, wie <code>OSentry</code> initialisiert wird und wie verschiedene [[#Events erfassen|Event-Typen]] aus einer Omnis-Oberfläche heraus an Sentry gesendet werden.

=== Bestandteile ===

{| class="wikitable"
! Klasse !! Zweck
|-
| <code>Startup_Task</code> || Initialisiert Sentry, SQLite und öffnet das Demo-Fenster
|-
| <code>FSY_Demo</code> || Demo-Fenster
|-
| <code>ODummy</code> || Erzeugt Demo-Stack für Exception
|-
| <code>ODatabaseHandler</code> || Erstellt SQLite-Demo-Datenbank
|-
| <code>OSLSession</code> || SQLite Session
|-
| <code>OSentry</code> || Low-Level-Sentry-Adapter
|-
| <code>OSentryHL</code> || High-Level-Sentry-Adapter
|}

=== Startup ===

<code>Startup_Task.$construct</code> initialisiert Sentry, baut eine SQLite Session auf und öffnet das Demo-Fenster. Quelle: <code>Startup_Task.$construct</code>.

<pre>
#Init Sentry on lbs startup
Do tSentry.$init()

#SQLite Session init
Do $objects.OSLSession.$newref() Returns tOSLSession
#Calculate tOSLSession.$opencreate as kTrue
Calculate workingDir as tODatabaseHandler.$getWorkingDir()
Do con(workingDir,'Sentry_Test.db') Returns dbLocation
Do tOSLSession.$logon(dbLocation,'','','slsession') Returns #F

#Open Test Window
Do $windows.FSY_Demo.$openonce('*')

Quit method
</pre>

=== Demo-Fenster ===

<code>FSY_Demo</code> enthält folgende Bereiche:

* DSN Configuration
* DB Status
* Actions

Wichtige Felder:

{| class="wikitable"
! Feld !! Datenanbindung
|-
| DSN || <code>iDSN</code>
|-
| Host || <code>tSentry.iOSentry.iHost</code>
|-
| Public Key || <code>tSentry.iOSentry.iPubKey</code>
|-
| Project ID || <code>tSentry.iOSentry.iProID</code>
|-
| DB Status || <code>iCurrentDBStatus</code>
|}

[[Datei:Demo-window.svg|850px|Demo-Fenster der OSentry Library]]

=== DSN setzen ===

Die DSN wird im Feld <code>iDSN</code> erfasst. Der Button <code>Set DSN</code> ruft anschließend <code>tSentry.$init(iDSN)</code> auf. Nach dem Setzen werden Public Key, Host und Project ID aus der DSN gelesen und in den darunterliegenden Feldern angezeigt.

[[Datei:Demo-dsn.svg|850px|DSN-Konfiguration im Demo-Fenster]]

Der Button <code>Set DSN</code> initialisiert Sentry mit der eingegebenen DSN. Quelle: <code>FSY_Demo.setDSN.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$init(iDSN)
Calculate $cclass.$ivardefs.iDSN.$objinitval as con(kSq,iDSN,kSq)

Do $cinst.$showmessage('DSN set and Sentry initialized!','Info')

Do $cinst.$redraw()
Quit method
</pre>

=== DB Status anzeigen ===

<code>FSY_Demo.$displayDBState</code> zeigt, ob die SQLite Session verbunden ist. Quelle: <code>FSY_Demo.$displayDBState</code>.

<pre>
Do tOSLSession.$state Returns dbState
If dbState='kSessionStateLoggedOff'
Calculate iCurrentDBStatus as 'Logged Off'
Else If dbState='kSessionStateLoggedOn'
Calculate iCurrentDBStatus as 'Logged On'
Else
Calculate iCurrentDBStatus as 'Unkown DB State'
End If

Do $cinst.$redraw()
Quit method
</pre>

=== Demo-Datenbank erstellen ===

Der Button <code>Create Database</code> ruft <code>ODatabaseHandler.$DBFirstInit</code> auf. Quelle: <code>FSY_Demo.createDB.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Setup the DB
Do tODatabaseHandler.$DBFirstInit() Returns err
If err=0
Do $cinst.$showmessage('DB successfully created!','Info')
Else
Do $cinst.$showmessage('Error while creating the DB. Make sure that the DB does not already exist.','Info')
End If

Do $cinst.$displayDBState()

Quit method
</pre>

Die Datenbank wird im Arbeitsverzeichnis der Library angelegt. Quelle: <code>ODatabaseHandler.$getWorkingDir</code>.

<pre>
Quit method con(FileOps.$parentdir($clib.$pathname),pathsep())
</pre>

Die Demo-DB enthält unter anderem:

* <code>dperson</code>
* <code>drelease</code>
* <code>dvcs</code>

=== Message auslösen ===

Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Log auslösen ===

Button <code>Trigger a log</code>. Quelle: <code>FSY_Demo.log.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== Exception auslösen ===

Button <code>Trigger an exception</code> bereitet eine Row und eine List vor und ruft anschließend <code>ODummy.$dummyMethod</code> auf. Quelle: <code>FSY_Demo.exception.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do iDummyRow.$define(id,name)
Calculate iDummyRow.id as 22
Calculate iDummyRow.name as 'Tom'

Do iDummyList.$define(id,weekday)
Do iDummyList.$add(1,'Monday')
Do iDummyList.$add(2,'Tuesday')
Do iDummyList.$add(3,'Wednesday')
Do iDummyList.$add(4,'Thursday')
Do iDummyList.$add(5,'Friday')
Do iDummyList.$add(6,'Saturday')
Do iDummyList.$add(7,'Sunday')

Calculate iDummyList.$line as 5

Do iODummy.$dummyMethod('Important Value')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')

Quit method
</pre>

<code>ODummy.$dummyMethod</code> sendet die Exception. Quelle: <code>ODummy.$dummyMethod</code>.

<pre>
#In here is some logic
#This logic would produce an error
#We send all this information to Sentry

Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')

Quit method 0
</pre>

=== Deprecated Call auslösen ===

Button <code>Trigger a deprecated call</code>. Quelle: <code>FSY_Demo.deprecatedCall.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureDeprecatedCall()
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</pre>

=== SQL Exception Button ===

Der Button <code>Trigger an SQLException</code> ist im Export vorhanden, enthält aber noch keinen fertigen Demo-Code. Quelle: <code>FSY_Demo.sqlException.$event</code>.

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Für die Dokumentation der SQL-Erfassung siehe [[#Events erfassen|03 Events erfassen]].

== API Reference ==

Diese Seite dokumentiert die produktiv relevanten Methoden von <code>OSentryHL</code> und <code>OSentry</code>.

=== OSentryHL ===

<code>OSentryHL</code> ist die empfohlene Klasse für Applikationscode.

'''<code>$init(pDSN)</code>'''

Initialisiert das interne <code>OSentry</code>-Objekt.

<pre>
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</pre>

'''<code>$captureMessage(pMessage)</code>'''

Sendet eine einfache Info-Message.

<pre>
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</pre>

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel)</code>'''

Sendet eine generische Exception.

<pre>
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</pre>

'''<code>$captureAnything(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface)</code>'''

Sendet ein frei konfigurierbares Event.

<pre>
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</pre>

Hinweis: Der Parameter ist im Export als <code>pStacktraveInterface</code> geschrieben.

'''<code>$captureLog(pErrorText)</code>'''

Sendet ein Log-Event.

<pre>
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</pre>

'''<code>$captureDeprecatedCall()</code>'''

Meldet die Ausführung eines veralteten Codepfads.

<pre>
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</pre>

'''<code>$captureSQLException(pErrorText,pStat)</code>'''

Meldet einen SQL-Fehler mit SQL-Text und nativer Datenbankfehlermeldung.

<pre>
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</pre>

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag für das nächste Event hinzu.

<pre>
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</pre>

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra für das nächste Event hinzu.

<pre>
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</pre>

'''<code>$setStatus(pStatus)</code>'''

Aktiviert oder deaktiviert Sentry.

<pre>
#Toggels Sentry on or off
Do iOSentry.$setStatus(pStatus)
Quit method
</pre>

'''<code>$setUser()</code>'''

Setzt im Export feste [[#Demo Library|Demo]]-Userdaten.

<pre>
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</pre>

Für produktive Nutzung sollte diese Methode parametrisiert werden.

=== OSentry ===

<code>OSentry</code> ist die Low-Level-Klasse für Payload-Erzeugung und Versand.

'''<code>$init(pDSN)</code>'''

Parst die DSN in Protokoll, Public Key, Host und Project ID.

'''<code>$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraceInterface,pUserInterface,pExceptionInterface)</code>'''

Erzeugt JSON, sendet es an Sentry und behandelt Fehlerfälle.

Parameter:

{| class="wikitable"
! Parameter !! Default !! Bedeutung
|-
| <code>pErrorText</code> || || Message
|-
| <code>pErrorCode</code> || || Fehlercode
|-
| <code>pExcType</code> || || Exception-Typ
|-
| <code>pLevel</code> || || <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code>, <code>debug</code>
|-
| <code>pStacktraceInterface</code> || <code>kTrue</code> || [[#Stacktrace und Kontext|Stacktrace]] senden
|-
| <code>pUserInterface</code> || <code>kTrue</code> || [[#Tags, Extras und User-Kontext|User-Kontext]] senden
|-
| <code>pExceptionInterface</code> || <code>kTrue</code> || Exception Interface senden
|}

'''<code>$generateJson(...)</code>'''

Erzeugt den Sentry JSON Payload als Binary.

'''<code>$generateStacktraceInterface(pCulprit)</code>'''

Erzeugt den Omnis-[[#Stacktrace und Kontext|Stacktrace]] inklusive Variablen und Kontextzeilen.

'''<code>$generateExceptionInterface(pType,pValue)</code>'''

Erzeugt das Sentry Exception Interface.

<pre>
# Generate Row to store in the JSON
Do exceptionRow.$define(type,value,stacktrace)
Calculate exceptionRow.type as pType
Calculate exceptionRow.value as pValue
Calculate exceptionRow.stacktrace as 'sentry.interfaces.stacktrace' ## Tells the exception interface that a stacktrace is passed aswell
</pre>

'''<code>$generateUserInterface()</code>'''

Erzeugt den [[#Tags, Extras und User-Kontext|User-Kontext]].

'''<code>$addTag(pName,pValue)</code>'''

Fügt einen Tag zur internen Tag-Liste hinzu.

'''<code>$addExtra(pName,pValue)</code>'''

Fügt ein Extra zur internen Extra-Liste hinzu.

'''<code>$clearList()</code>'''

Leert [[#Tags, Extras und User-Kontext|Tags und Extras]] nach einem Request.

'''<code>$setUserData(pID,pName,pEmail)</code>'''

Setzt Userdaten für den nächsten Request.

'''<code>$setProxy(pProxyHost,pProxyPort)</code>'''

Setzt Proxy-Informationen.

'''<code>$setStatus(pStatus)</code>'''

Setzt den Sentry-Status.

<pre>
#Toggels Sentry Reports on or off
Calculate iStatus as pStatus
Quit method
</pre>

'''<code>$writeJSON(pJSON,pBuffer)</code>'''

Schreibt fehlgeschlagene Reports lokal in eine Datei.

'''<code>$getUnixTimestamp()</code>'''

Gibt den aktuellen UNIX Timestamp zurück.

'''<code>$generateUUID()</code>'''

Erzeugt eine UUID für die Sentry Event ID.

<pre>
#Genereates a UUID for the issue id
Quit method OW3.$makeuuid(kFalse)
</pre>

== Troubleshooting ==

=== Es erscheinen keine Events in Sentry ===

Prüfe zuerst, ob Sentry aktiv ist:

<pre>
Do tSentry.$setStatus(1)
</pre>

<code>OSentry.$captureException</code> beendet sich sofort, wenn der Status <code>0</code> oder leer ist:

<pre>
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</pre>

=== Die DSN ist falsch ===

Prüfe, ob die DSN korrekt aus Sentry kopiert wurde. <code>OSentry.$init</code> erwartet eine DSN, aus der Public Key, Host und Project ID gelesen werden können.

Nach dem Setzen der DSN sollten in der [[#Demo Library|Demo-Library]] folgende Felder gefüllt sein:

* Host
* Public Key
* Project ID

=== Netzwerk oder Proxy blockiert den Request ===

Wenn die Anwendung keinen direkten Zugriff auf Sentry hat, setze einen Proxy:

<pre>
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</pre>

Intern wird der Proxy vor dem HTTP Request gesetzt:

<pre>
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</pre>

=== Report wird lokal gespeichert ===

Wenn <code>HTTPPost</code>, <code>HTTPSend</code> oder <code>HTTPRead</code> fehlschlägt, speichert OSentry den Report lokal:

<pre>
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
</pre>

Suche im Omnis-Installationsordner nach Dateien mit dem Namen:

<pre>
Sentryreport_<timestamp>.json
</pre>

=== Sentry antwortet nicht mit 200 OK ===

Wenn die HTTP-Antwort kein <code>200 OK</code> enthält, wird der JSON Report ebenfalls lokal gespeichert:

<pre>
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</pre>

Mögliche Ursachen:

* falsche Project ID
* falscher Public Key
* ungültige DSN
* JSON Payload wird von Sentry abgelehnt
* Netzwerk-Gateway verändert den Request

=== Tags oder Extras erscheinen beim falschen Event ===

[[#Tags, Extras und User-Kontext|Tags und Extras]] werden für den nächsten Request gesammelt. Nach erfolgreichem Request werden sie gelöscht:

<pre>
Do iTagList.$clear()
Do iExtraList.$clear()
</pre>

Wenn ein Request fehlschlägt, wird ebenfalls aufgeräumt:

<pre>
Do $cinst.$clearList()
</pre>

Prüfe trotzdem, ob in eigenen Wrapper-Methoden Tags und Extras direkt vor dem passenden Capture-Aufruf gesetzt werden.

=== User-Kontext zeigt Demo-Daten ===

<code>OSentryHL.$setUser</code> verwendet im Export feste Testdaten:

<pre>
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
</pre>

Für produktive Nutzung sollte die Methode parametrisiert werden:

<pre>
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
</pre>

=== SQL Exception Demo-Button funktioniert nicht ===

Der Button <code>Trigger an SQLException</code> ist im Export noch nicht implementiert:

<pre>
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</pre>

Die produktive Methode für SQL-Fehler ist aber vorhanden. Siehe auch [[#Events erfassen|Events erfassen]].

<pre>
Do tSentry.$captureSQLException('SQL statement failed',stat)
</pre>

=== Zu viele Events ===

Sentry kann sehr schnell viele Events sammeln. Verwende für produktive Systeme:

* klare Wrapper-Methoden in <code>OSentryHL</code>
* sinnvolle Levels
* gezielte [[#Tags, Extras und User-Kontext|Tags]]
* keine Events in sehr häufigen Schleifen
* keine rein informativen Debug-Events ohne Nutzen

=== Sensible Daten ===

[[#Stacktrace und Kontext|Stacktrace]], Parameter, Instance Variablen, SQL-Text und [[#Tags, Extras und User-Kontext|Extras]] können sensible Daten enthalten. Prüfe vor produktiver Nutzung:

* Welche Variablen werden übertragen?
* Enthalten SQL-Statements personenbezogene Daten?
* Werden Tokens oder Passwörter in Extras geschrieben?
* Sollen bestimmte Werte maskiert werden?

Sentry

2026-06-12T13:59:28Z

Silvan: Die Seite wurde neu angelegt: „  __TOC__ == Überblick == OSentry ist ein REST-API-Konnektor von Omnis Studio zu Sentry. Der Konnektor sendet Fehler, Messages, Logs und Laufzeitkontext aus Omnis-Anwendungen an Sentry, damit Probleme in produktiven Systemen sichtbar, gruppierbar und analysierb…“

__TOC__

== Überblick ==

OSentry ist ein REST-API-Konnektor von Omnis Studio zu Sentry. Der Konnektor sendet Fehler, Messages, Logs und Laufzeitkontext aus Omnis-Anwendungen an Sentry, damit Probleme in produktiven Systemen sichtbar, gruppierbar und analysierbar werden.

Diese Dokumentation beschreibt die [[#Installation|Installation]], die Nutzung in bestehenden Omnis-Anwendungen, die Definition eigener standardisierter Exception-Typen, die interne Struktur und die [[#Demo Library|Demo-Library]].

=== Inhalt ===

* [[#Installation|01 Installation]]
* [[#Quickstart|02 Quickstart]]
* [[#Events erfassen|03 Events erfassen]]
* [[#Eigene Exceptions standardisieren|04 Eigene Exceptions standardisieren]]
* [[#Tags, Extras und User-Kontext|05 Tags Extras und User]]
* [[#Stacktrace und Kontext|06 Stacktrace und Kontext]]
* [[#Interne Architektur|07 Interne Architektur]]
* [[#Demo Library|08 Demo Library]]
* [[#API Reference|09 API Reference]]
* [[#Troubleshooting|10 Troubleshooting]]

=== Kernidee ===

OSentry besteht aus zwei produktiv relevanten Klassen:

* <code>OSentryHL</code>: High-Level-Adapter für die Anwendung. Diese Klasse sollte von normalem Applikationscode aufgerufen werden.
* <code>OSentry</code>: Low-Level-Adapter für DSN-Parsing, JSON-Erzeugung, [[#Stacktrace und Kontext|Stacktrace]]-Aufbereitung und HTTP-Kommunikation mit Sentry.

Die Anwendung arbeitet im Normalfall mit <code>OSentryHL</code>. Dadurch bleiben Sentry-spezifische Details zentral gekapselt und neue standardisierte Exception-Typen können als eigene Methoden in <code>OSentryHL</code> definiert werden.

=== Hauptfeatures ===

* Direkte Anbindung von Omnis Studio an Sentry über REST API und DSN
* Erfassen von Exceptions, Messages, Logs und SQL-Fehlern
* Unterstützung der Sentry-Level <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code> und <code>debug</code>
* Automatische Omnis-Kontextinformationen
* Omnis-[[#Stacktrace und Kontext|Stacktrace]] mit Klassen, Methoden, Zeilen und Variablen
* [[#Tags, Extras und User-Kontext|Tags]] für Filterung und Gruppierung
* [[#Tags, Extras und User-Kontext|Extras]] für zusätzliche Diagnoseinformationen
* Optionaler [[#Tags, Extras und User-Kontext|User-Kontext]]
* Proxy-Unterstützung
* Aktivieren und Deaktivieren der Sentry-Übertragung
* Lokales Speichern von Reports bei Übertragungsfehlern

=== Screenshots ===

[[Datei:sentry-issue.png|thumb|Sentry Issue-Übersicht]]

[[Datei:sentry-stack.png|thumb|Sentry Stacktrace mit Omnis-Kontext]]

[[Datei:sentry-tags.png|thumb|Sentry Tags und User-Kontext]]

== Installation ==

Diese Seite beschreibt, wie OSentry in eine bestehende Omnis-Anwendung integriert wird.

=== Voraussetzungen ===

* Omnis Studio Anwendung
* Sentry Account oder self-hosted Sentry Installation
* Ein Sentry-Projekt mit SDK-Typ <code>Other</code>
* Die DSN des Sentry-Projekts
* Netzwerkzugriff auf Sentry

Die exportierte [[#Demo Library|Demo-Library]] wurde mit Omnis <code>11.1</code> erstellt.

=== Sentry-Projekt erstellen ===

# In Sentry ein neues Projekt erstellen.
# Als SDK <code>Other</code> auswählen.
# Die DSN des Projekts kopieren.

Die DSN wird beim Initialisieren verwendet. <code>OSentry</code> zerlegt sie intern in Public Key, Host und Project ID.

=== Klassen kopieren ===

Kopiere die folgenden Klassen in deine bestehende Omnis-Library:

* <code>OSentry</code>
* <code>OSentryHL</code>

Die Demo-spezifischen Klassen sind für die produktive Integration nicht erforderlich. Damit sind die übrigen Klassen der Demo-Library gemeint, zum Beispiel <code>FSY_Demo</code>, <code>ODummy</code>, <code>ODatabaseHandler</code> und <code>OSLSession</code>. Diese Klassen dienen nur dazu, die [[#Demo Library|Demo-Library]] mit Fenster, SQLite-Testdaten und Beispielaufrufen auszuführen.

=== Task Variable anlegen ===

Lege in deiner Startup Task eine Task Variable an:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

<code>tSentry</code> sollte als global erreichbarer Singleton der Anwendung verwendet werden. In Omnis ist dafür eine Task Variable sinnvoll, weil sie von Fenstern, Objektklassen und zentralen Error-Handlern aus konsistent erreichbar ist. Dadurch gibt es genau eine aktive Sentry-Konfiguration mit einer DSN, einem Status, optionalen Proxy-Daten und gemeinsamen Wrapper-Methoden in <code>OSentryHL</code>.

Im [[#Demo Library|Demo-Projekt]] ist diese Variable in <code>Startup_Task</code> definiert.

=== Initialisierung im Startup Task ===

Initialisiere <code>tSentry</code> beim Start deiner Anwendung mit der DSN deines Sentry-Projekts:

<syntaxhighlight lang="text">
Do tSentry.$init('<DSN>')
</syntaxhighlight>

Die [[#Demo Library|Demo-Library]] ruft im Startup Task ebenfalls die Initialisierung auf. Quelle: <code>Startup_Task.$construct</code>.

<syntaxhighlight lang="text">
#Init Sentry on lbs startup
Do tSentry.$init()
</syntaxhighlight>

In einer produktiven Anwendung sollte die DSN explizit oder aus einer Konfiguration übergeben werden:

<syntaxhighlight lang="text">
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</syntaxhighlight>

Für produktive Systeme ist es sinnvoll, die DSN nicht fest im Code zu hinterlegen. Speichere sie besser in einer Datenbank, einer Konfigurationstabelle oder einem Config File. Dadurch kann die DSN pro Kunde, Umgebung oder Installation geändert werden, ohne die Library neu auszuliefern.

=== Testcall ===

Nach der Initialisierung kann ein erstes Testevent gesendet werden:

<syntaxhighlight lang="text">
Do tSentry.$captureMessage('Hello World!')
</syntaxhighlight>

Wenn alles korrekt eingerichtet ist, erscheint das Event im Sentry-Projekt.

=== Proxy konfigurieren ===

Falls die Anwendung in einem geschützten Netzwerk läuft, kann ein Proxy gesetzt werden. Die Methode befindet sich im Low-Level-Objekt <code>OSentry</code>.

<syntaxhighlight lang="text">
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</syntaxhighlight>

Die interne Implementierung setzt den Proxy vor dem HTTP-Request:

<syntaxhighlight lang="text">
#Configure proxy; needed when sending data out of secured networks
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</syntaxhighlight>

=== Sentry aktivieren oder deaktivieren ===

OSentry kann zentral ein- oder ausgeschaltet werden. Es ist empfohlen, Sentry in der Entwicklungs-Version standardmäßig zu deaktivieren oder eine separate Entwicklungs-DSN zu verwenden. So landen lokale Tests, Debug-Fehler und absichtlich ausgelöste Exceptions nicht im produktiven Sentry-Projekt.

<syntaxhighlight lang="text">
Do tSentry.$setStatus(1) ## aktiv
Do tSentry.$setStatus(0) ## inaktiv
</syntaxhighlight>

Im Low-Level-Objekt <code>OSentry</code> wird vor dem Senden geprüft:

<syntaxhighlight lang="text">
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</syntaxhighlight>

== Quickstart ==

Diese Seite zeigt die minimale Integration in eine bestehende Omnis-Anwendung.

=== 1. Klassen übernehmen ===

Kopiere <code>OSentry</code> und <code>OSentryHL</code> in deine Library.

=== 2. Task Variable erstellen ===

In der Startup Task:

{| class="wikitable"
! Name !! Typ
|-
| <code>tSentry</code> || <code>OSentryHL</code>
|}

=== 3. Sentry initialisieren ===

<syntaxhighlight lang="text">
Do tSentry.$init('https://PUBLIC_KEY@sentry.io/PROJECT_ID')
</syntaxhighlight>

<code>OSentryHL.$init</code> delegiert an das Low-Level-Objekt <code>OSentry</code>:

<syntaxhighlight lang="text">
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</syntaxhighlight>

=== 4. Message senden ===

<syntaxhighlight lang="text">
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
</syntaxhighlight>

Die [[#Demo Library|Demo-Library]] verwendet genau diesen Aufruf im Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<syntaxhighlight lang="text">
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</syntaxhighlight>

=== 5. Exception senden ===

<syntaxhighlight lang="text">
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</syntaxhighlight>

=== 6. In Sentry prüfen ===

In Sentry sollte anschließend ein neues Event sichtbar sein. Je nach Event-Typ enthält es:

* Message
* Level
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Tags, Extras und User-Kontext|User-Kontext]]
* [[#Stacktrace und Kontext|Stacktrace]]
* Omnis-Kontextinformationen

== Events erfassen ==

OSentryHL ist die empfohlene Einstiegsschicht für Applikationscode. Die Klasse bietet sprechende Methoden für typische Event-Arten und ruft intern <code>OSentry.$captureException</code> auf.

=== Message ===

Eine einfache Information wird mit <code>$captureMessage</code> gesendet:

<syntaxhighlight lang="text">
Do tSentry.$captureMessage('Hello World!')
</syntaxhighlight>

Implementierung in <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</syntaxhighlight>

Verhalten:

* Level: <code>info</code>
* Kein [[#Stacktrace und Kontext|Stacktrace]]
* Kein [[#Tags, Extras und User-Kontext|User Interface]]
* Geeignet für einfache Statusmeldungen oder technische Hinweise

=== Log ===

Ein Log-Event wird mit <code>$captureLog</code> gesendet:

<syntaxhighlight lang="text">
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
</syntaxhighlight>

Implementierung in <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</syntaxhighlight>

Verhalten:

* Level: <code>warning</code>
* [[#Stacktrace und Kontext|Stacktrace]] aktiv
* Exception Interface in diesem Wrapper deaktiviert
* [[#Tags, Extras und User-Kontext|User Interface]] aktiv

=== Generische Exception ===

Eine generische Exception wird mit <code>$captureException</code> gesendet:

<syntaxhighlight lang="text">
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</syntaxhighlight>

Implementierung in <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</syntaxhighlight>

Parameter:

{| class="wikitable"
! Parameter !! Bedeutung
|-
| <code>pErrorText</code> || Text, der in Sentry als Message sichtbar ist
|-
| <code>pErrorCode</code> || Fehlercode oder fachlicher Code
|-
| <code>pExcType</code> || Exception-Typ für Benennung und Gruppierung
|-
| <code>pLevel</code> || Sentry-Level
|}

Gültige Levels:

* <code>fatal</code>
* <code>error</code>
* <code>warning</code>
* <code>info</code>
* <code>debug</code>

=== SQL Exception ===

SQL-Fehler können mit <code>$captureSQLException</code> gemeldet werden.

<syntaxhighlight lang="text">
Do tSentry.$captureSQLException('SQL statement failed',stat)
</syntaxhighlight>

Implementierung in <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</syntaxhighlight>

Verhalten:

* Fügt die Datenbank als [[#Tags, Extras und User-Kontext|Tag]] hinzu
* Fügt SQL-Text als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Fügt native Datenbankfehlermeldung als [[#Tags, Extras und User-Kontext|Extra]] hinzu
* Sendet das Event als <code>SQL-Exception</code> mit Level <code>error</code>

=== Deprecated Call ===

Veraltete Codepfade können gezielt gemeldet werden:

<syntaxhighlight lang="text">
Do tSentry.$captureDeprecatedCall()
</syntaxhighlight>

Implementierung in <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</syntaxhighlight>

Dieser Wrapper eignet sich, um zu erkennen, ob alter Code in produktiven Systemen noch ausgeführt wird.

=== Frei konfigurierbares Event ===

Für Sonderfälle gibt es <code>$captureAnything</code>:

<syntaxhighlight lang="text">
Do tSentry.$captureAnything('Text',1001,'Custom Type','error',kTrue,kTrue,kTrue)
</syntaxhighlight>

Implementierung in <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</syntaxhighlight>

Diese Methode bietet maximale Flexibilität. Für wiederkehrende Exception-Typen sollte aber eine eigene Methode in <code>OSentryHL</code> angelegt werden. Siehe [[#Eigene Exceptions standardisieren|04 Eigene Exceptions standardisieren]].

== Eigene Exceptions standardisieren ==

Wenn ein Exception-Typ mehrfach in der Anwendung vorkommt, sollte er nicht überall manuell mit <code>$captureException</code> aufgebaut werden. Besser ist eine eigene Methode in <code>OSentryHL</code>.

Dadurch entsteht eine zentrale, wiederverwendbare Definition für:

* Exception-Typ
* Sentry-Level
* Fehlercode
* [[#Tags, Extras und User-Kontext|Tags]]
* [[#Tags, Extras und User-Kontext|Extras]]
* [[#Stacktrace und Kontext|Stacktrace]]/[[#Tags, Extras und User-Kontext|User]]/Exception Interface

Die automatisch gesetzten [[#Tags, Extras und User-Kontext|Tags und Extras]] aus <code>OSentry.$generateJson</code> müssen in solchen Wrappern nicht erneut ergänzt werden. Eigene Exception-Methoden setzen nur zusätzliche Werte, die für diesen standardisierten Exception-Typ relevant sind.

=== Warum über OSentryHL? ===

<code>OSentryHL</code> ist die Abstraktionsschicht für Applikationscode. Sie kapselt die Details von <code>OSentry</code> und sorgt dafür, dass Aufrufe in der Anwendung kurz und konsistent bleiben.

Bestehende Beispiele aus <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</syntaxhighlight>

<syntaxhighlight lang="text">
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</syntaxhighlight>

=== Empfohlenes Muster ===

Für jeden standardisierten Exception-Typ wird eine eigene Methode in <code>OSentryHL</code> erstellt.

Beispiel:

<syntaxhighlight lang="text">
# Captures a validation exception
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addExtra('Field',pField)
Do $cinst.$addExtra('Invalid Value',pValue)

Do iOSentry.$captureException(pErrorText,2001,'Validation-Exception','warning',1,1,1) Returns code

Quit method code
</syntaxhighlight>

Mögliche Parameter der neuen Methode:

{| class="wikitable"
! Parameter !! Beispiel !! Zweck
|-
| <code>pErrorText</code> || <code>'Invalid customer number'</code> || Sentry Message
|-
| <code>pModule</code> || <code>'Customer'</code> || Filterbarer Tag
|-
| <code>pField</code> || <code>'cu_number'</code> || Diagnoseinformation
|-
| <code>pValue</code> || <code>'ABC'</code> || Diagnoseinformation
|}

Der Applikationscode bleibt dadurch einfach:

<syntaxhighlight lang="text">
Do tSentry.$captureValidationException('Invalid customer number','Customer','cu_number',cu_number)
</syntaxhighlight>

=== Beispiel: Business Rule Exception ===

Neue Methode in <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Captures a business rule violation
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do $cinst.$addExtra('Details',pDetails)

Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code

Quit method code
</syntaxhighlight>

Aufruf in der Anwendung:

<syntaxhighlight lang="text">
Do tSentry.$captureBusinessRuleViolation('Invoice cannot be posted','Invoice','PostingAllowed','Invoice is missing customer')
</syntaxhighlight>

=== Beispiel: Integration Exception ===

Neue Methode in <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Captures an integration exception
Do $cinst.$addTag('Integration',pSystem)
Do $cinst.$addTag('Endpoint',pEndpoint)
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)

Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code

Quit method code
</syntaxhighlight>

Aufruf in der Anwendung:

<syntaxhighlight lang="text">
Do tSentry.$captureIntegrationException('External API request failed','ERP','/api/customer',jsonPayload,responseText)
</syntaxhighlight>

=== Namenskonventionen ===

Empfehlung für neue Methoden:

* Methodenname beginnt mit <code>$capture</code>
* Der fachliche Typ steht im Methodennamen
* Der Sentry Exception Type ist stabil und ändert sich nicht laufend
* [[#Tags, Extras und User-Kontext|Tags]] sind kurz und filterbar
* [[#Tags, Extras und User-Kontext|Extras]] dürfen länger sein und Diagnoseinformationen enthalten

Beispiele:

* <code>$captureValidationException</code>
* <code>$captureBusinessRuleViolation</code>
* <code>$captureIntegrationException</code>
* <code>$capturePermissionViolation</code>
* <code>$captureConfigurationError</code>

=== Error Codes ===

Verwende feste Fehlercodes für standardisierte Exception-Typen. Dadurch können Events in Sentry besser gefiltert und wiedererkannt werden.

Beispiel:

{| class="wikitable"
! Code !! Exception Type
|-
| <code>2001</code> || <code>Validation-Exception</code>
|-
| <code>3001</code> || <code>Business-Rule-Violation</code>
|-
| <code>4001</code> || <code>Integration-Exception</code>
|-
| <code>5001</code> || <code>Configuration-Error</code>
|}

=== Wann nicht standardisieren? ===

Nicht jeder Einzelfall braucht eine eigene Methode. Für einmalige technische Tests oder sehr spezielle Fälle reicht:

<syntaxhighlight lang="text">
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</syntaxhighlight>

Sobald ein Exception-Typ aber mehrfach vorkommt oder fachlich relevant ist, sollte er als eigene Methode in <code>OSentryHL</code> definiert werden.

== Tags, Extras und User-Kontext ==

Tags, Extras und User-Kontext reichern Sentry-Events mit zusätzlichen Informationen an. Diese Informationen helfen beim Filtern, Gruppieren und Analysieren.

=== Tags ===

Tags sind kurze, filterbare Werte.

Beispiele:

* Datenbank
* Kunde
* Modul
* Umgebung
* Error Code
* Omnis-Version

Methode in <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</syntaxhighlight>

Methode in <code>OSentry</code>:

<syntaxhighlight lang="text">
#Adds a tag to the next request processed
Do iTagList.$add(pName,pValue)
Quit method
</syntaxhighlight>

Beispiel:

<syntaxhighlight lang="text">
Do tSentry.$addTag('Module','Invoice')
Do tSentry.$addTag('Customer','10001')
Do tSentry.$captureException('Invoice posting failed',3001,'Business-Rule-Violation','warning')
</syntaxhighlight>

=== Extras ===

Extras sind Detailinformationen, die nicht primär zum Filtern gedacht sind.

Beispiele:

* SQL-Text
* Native Datenbankfehlermeldung
* Payload
* Response Body
* interne IDs
* zusätzliche Debug-Informationen

Methode in <code>OSentryHL</code>:

<syntaxhighlight lang="text">
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</syntaxhighlight>

Methode in <code>OSentry</code>:

<syntaxhighlight lang="text">
#Adds extra information to the next request being processed
Do iExtraList.$add(pName,pValue)
Quit method
</syntaxhighlight>

Beispiel aus der SQL Exception:

<syntaxhighlight lang="text">
Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)
</syntaxhighlight>

=== Automatische Tags ===

Die folgenden Tags werden bei jedem Event automatisch von <code>OSentry.$generateJson</code> ergänzt. Sie müssen bei eigenen Exceptions nicht erneut gesetzt werden. Eigene Wrapper-Methoden in <code>OSentryHL</code> sollten nur zusätzliche, fachlich oder technisch relevante Tags hinzufügen.

<code>OSentry.$generateJson</code> fügt mehrere Tags automatisch hinzu:

<syntaxhighlight lang="text">
# Add static tags
Do iTagList.$add('Omnisversion',sys(1))
Calculate systemversionRow as systemversion()
Do iTagList.$add('Plattform',con(sys(8),pick(systemversionRow.server,'',' SRV')))
Do iTagList.$add('OS Version',con(systemversionRow.major,'.',systemversionRow.minor,'.',systemversionRow.build))
Do iTagList.$add('error_code',pErrorCode)
</syntaxhighlight>

Automatisch gesendete Tags:

{| class="wikitable"
! Tag !! Herkunft !! Zweck
|-
| <code>Omnisversion</code> || <code>sys(1)</code> || Zeigt, mit welcher Omnis-Version das Event erzeugt wurde
|-
| <code>Plattform</code> || <code>sys(8)</code> und Server-Flag aus <code>systemversion()</code> || Unterscheidet Plattform und Server Runtime
|-
| <code>OS Version</code> || <code>systemversionRow.major/minor/build</code> || Zeigt die Betriebssystemversion
|-
| <code>error_code</code> || Parameter <code>pErrorCode</code> || Verbindet das Event mit dem übergebenen Fehlercode
|}

Beispiel für eine eigene Exception: Der Wrapper muss nicht erneut <code>Omnisversion</code> oder <code>OS Version</code> setzen. Er ergänzt nur das, was für diesen Exception-Typ zusätzlich hilfreich ist.

<syntaxhighlight lang="text">
Do $cinst.$addTag('Module',pModule)
Do $cinst.$addTag('Business Rule',pRuleName)
Do iOSentry.$captureException(pErrorText,3001,'Business-Rule-Violation','warning',1,1,1) Returns code
</syntaxhighlight>

=== Automatische Extras ===

Auch die folgenden Extras werden bei jedem Event automatisch ergänzt. Bei eigenen Exceptions müssen nur zusätzliche Extras gesetzt werden, zum Beispiel ein SQL-Statement, ein Payload oder fachliche Zusatzdaten.

<code>OSentry.$generateJson</code> fügt offene Fenster, offene Reports und die aktuelle Printfile hinzu:

<syntaxhighlight lang="text">
# Static extra 1: All open windows
Do $root.$iwindows.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate windows as con(windows,', ',nameList.[i].1)
End For
Calculate windows as right(windows,len(windows)-2)
Do iExtraList.$add('Open Windows',windows)

# Static extra 2: All open reports
Do $root.$ireports.$makelist($ref.$name) Returns nameList
For i from 1 to nameList.$linecount step 1
Calculate reports as con(reports,', ',nameList.[i].1)
End For
Calculate reports as right(reports,len(reports)-2)
Do iExtraList.$add('Open Reports',reports)
Do iExtraList.$add('Current Printfile',$root.$prefs.$printfile)
</syntaxhighlight>

Automatisch gesendete Extras:

{| class="wikitable"
! Extra !! Herkunft !! Zweck
|-
| <code>Open Windows</code> || <code>$root.$iwindows.$makelist($ref.$name)</code> || Zeigt, welche Fenster im Moment des Events offen waren
|-
| <code>Open Reports</code> || <code>$root.$ireports.$makelist($ref.$name)</code> || Zeigt, welche Reports im Moment des Events offen waren
|-
| <code>Current Printfile</code> || <code>$root.$prefs.$printfile</code> || Zeigt die aktuell gesetzte Printfile
|}

Beispiel für zusätzliche Extras in einem eigenen Wrapper:

<syntaxhighlight lang="text">
Do $cinst.$addExtra('Payload',pPayload)
Do $cinst.$addExtra('Response',pResponse)
Do iOSentry.$captureException(pErrorText,4001,'Integration-Exception','error',1,1,1) Returns code
</syntaxhighlight>

=== User-Kontext ===

Der User-Kontext ordnet ein Event einem betroffenen Benutzer zu. In Sentry erscheint dadurch ein eigener User-Bereich, und Events können nach Benutzer gefiltert oder gruppiert werden. Das ist besonders hilfreich, wenn ein Fehler nur bei einzelnen Kunden, Arbeitsplätzen oder Benutzerkonten auftritt.

<code>OSentry</code> unterstützt drei User-Felder:

{| class="wikitable"
! Feld !! Bedeutung
|-
| <code>id</code> || stabile interne Benutzer-ID oder Kundennummer
|-
| <code>username</code> || lesbarer Benutzername
|-
| <code>email</code> || E-Mail-Adresse, falls sie übertragen werden darf
|}

Der User-Kontext wird nur in das Event geschrieben, wenn das User Interface beim Capture-Aufruf aktiviert ist. Die Standardmethode <code>OSentry.$captureException</code> hat <code>pUserInterface</code> standardmäßig auf <code>kTrue</code>. Einzelne High-Level-Methoden können das bewusst deaktivieren, zum Beispiel <code>$captureMessage</code>.

<code>OSentry</code> kann User-Daten an das Event anhängen:

<syntaxhighlight lang="text">
#Sets userinformation for the next request being processed
Calculate iUserID as pID
Calculate iUserName as pName
Calculate iUserEmail as pEmail
Quit method
</syntaxhighlight>

Das User Interface wird so generiert:

<syntaxhighlight lang="text">
# Create user data row
Do UserdataRow.$define(id,email,username)

Calculate UserdataRow.id as iUserID
Calculate UserdataRow.email as iUserEmail
Calculate UserdataRow.username as iUserName

Do JSON.$addmember('','user','')
Do JSON.$setobject('user',UserdataRow)

Calculate jsonString as OJSON.$formatjson(JSON.$getjson())

Quit method jsonString
</syntaxhighlight>

Die aktuelle Demo-Methode in <code>OSentryHL</code> verwendet feste Testdaten. Quelle: <code>OSentryHL.$setUser</code>.

<syntaxhighlight lang="text">
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</syntaxhighlight>

Für produktive Nutzung sollte diese Methode angepasst und parametrisiert werden:

<syntaxhighlight lang="text">
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
Quit method
</syntaxhighlight>

Empfohlen ist, den User nach Login oder beim Wechsel des aktiven Benutzers zentral zu setzen. Bei anonymen oder sensiblen Installationen kann statt Name und E-Mail auch nur eine interne ID oder ein pseudonymisierter Wert verwendet werden.

=== Datenschutz ===

Prüfe vor produktiver Nutzung, welche Daten an Sentry gesendet werden. Besonders kritisch sind:

* personenbezogene Daten
* Kundendaten
* SQL-Statements mit Werten
* Zugangsdaten
* Tokens
* interne Pfade

Tags und Extras sollten so gestaltet werden, dass sie für die Fehleranalyse hilfreich sind, aber keine unnötigen sensiblen Daten übertragen.

== Stacktrace und Kontext ==

<code>OSentry</code> erzeugt einen Omnis-spezifischen Stacktrace und übergibt ihn an Sentry. Dadurch sieht man in Sentry nicht nur eine Fehlermeldung, sondern auch Klassen, Methoden, Zeilen und Variablenkontext. Ergänzende Informationen zu [[#Tags, Extras und User-Kontext|Tags, Extras und User-Kontext]] stehen auf der separaten Kontext-Seite.

[[Datei:sentry-stack.png|thumb|Sentry Stacktrace mit Omnis-Kontext]]

=== Stack lesen ===

<code>OSentry.$generateStacktraceInterface</code> verwendet <code>sys(192)</code>, um den aktuellen Omnis-Stack zu lesen:

<syntaxhighlight lang="text">
# Clean up the Stacklist (remove OSentry classes from the stack)
Do sys(192) Returns sys192List
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
If pos('OSentry',class.$name)>0|pos('OSentryHL',class.$name)>0
Do sys192List.[sys192List.$line].$selected.$assign(kTrue)
End If
End For
Do sys192List.$remove(kListDeleteSelected)
</syntaxhighlight>

Interne Frames von <code>OSentry</code> und <code>OSentryHL</code> werden entfernt, damit in Sentry die fachlich relevanten Stellen sichtbar bleiben.

=== SQL-Error Frames entfernen ===

Bestimmte interne SQL-Fehlerframes werden ebenfalls entfernt:

<syntaxhighlight lang="text">
# Remove some other classes which we do not want to display
If sys192List.1.method='$sqlerror'
Do sys192List.$remove(1)
Else If sys192List.1.method='$statementerror'
Do sys192List.$remove(1)
End If
</syntaxhighlight>

=== Frames erzeugen ===

Für jeden Stack-Eintrag werden Funktion, Zeilennummer und Kontextzeile erzeugt:

<syntaxhighlight lang="text">
#Loop through every item on the omnis stack
For sys192List.$line from 1 to sys192List.$linecount step 1
Set reference class to sys192List.classitem
Calculate className as class.$name

# Create the content row
Do contentRow.$define(vars,function,pre_context,context_line,lineno,filename,post_context)
Calculate contentRow.lineno as sys192List.line
Calculate contentRow.filename as testFileName
Calculate contentRow.context_line as sys192List.linetext
If isclear(sys192List.object)
Calculate contentRow.function as con(className,'.',sys192List.method) ## If it's a class method
Else
Calculate contentRow.function as con(className,'.',sys192List.object,'.',sys192List.method) ## If it's a method of an object of a class (e.g. Headedlist)
End If
Do contentList.$add(contentRow)
End For
</syntaxhighlight>

=== Variablen aufnehmen ===

Pro Stackframe werden Instance Variablen und Parameter gesammelt:

<syntaxhighlight lang="text">
# Get all iVars
Do varList.$define(name,value)
Set reference class to sys192List.inst
Do $cinst.$getVars('ivars',class) Returns varList

# Get all params
Calculate paramList as sys192List.params
For paramList.$line from 1 to paramList.$linecount step 1
If not(paramList.value='(Not empty)')
Do varList.$add(paramList.name,paramList.value)
Else
Do varList.$add(paramList.name,'(Not empty)')
End If
End For
</syntaxhighlight>

=== Pre- und Post-Context ===

OSentry fügt Methodenzeilen vor und nach der aktuellen Zeile hinzu:

<syntaxhighlight lang="text">
# Pre Context (all method lines before the error occured)
Set reference method to sys192List.methoditem
Do precontextList.$define(line)
For i from 1 to sys192List.line-1 step 1
Do precontextList.$add(method.$methodlines.[i].$text)
End For

# Post Context (all method lines after the error occured
Do postcontextList.$define(line)
For i from sys192List.line+1 to method.$methodlines.$count step 1
Do postcontextList.$add(method.$methodlines.[i].$text)
End For
</syntaxhighlight>

=== Variablentypen ===

<code>OSentry.$getVars</code> unterstützt Basisvariablen, Rows und Lists.

Basisvariablen:

<syntaxhighlight lang="text">
If varType='char'|varType='boolean'|varType='integer'|varType='number'|varType='date'
Calculate varContent as pItemRef.$[pVarType].[varName]
Do varList.$add(varName,varContent)
</syntaxhighlight>

Rows:

<syntaxhighlight lang="text">
Else If varType='row'
Calculate varRow as pItemRef.$[pVarType].[varName]
If varRow.$colcount=0
Do varList.$add(varName,'(Empty)')
Else
For Z2 from 1 to varRow.$colcount step 1
Calculate varContent as con(varContent,varRow.$cols.[Z2].$name,': ',varRow.[Z2],', ')
End For
Do varList.$add(varName,varContent)
</syntaxhighlight>

Lists:

<syntaxhighlight lang="text">
Else If varType='list'
Calculate varListType as pItemRef.$[pVarType].[varName]
Calculate varContent as con('Colcount: ',varListType.$colcount,', ','Linecount: ',varListType.$linecount,', ','Current Line: ',varListType.$line)
If varListType.$linecount=0&varListType.$line=0&varListType.$colcount=0
Do varList.$add(varName,'(Empty)')
Calculate varContent as ''
Else
For Z3 from 1 to varListType.$colcount step 1
Calculate colName as varListType.$cols.[Z3].$name
Calculate varContent as con(varContent,' ',colName,': ',varListType.[colName])
End For
Do varList.$add(varName,varContent)
Calculate varContent as ''
End If
End If
</syntaxhighlight>

=== Hinweise ===

Stacktrace und Variablenkontext sind sehr hilfreich, können aber sensible Daten enthalten. Vor produktiver Nutzung sollte geprüft werden, ob bestimmte Variablen anonymisiert oder ausgeschlossen werden müssen.

== Interne Architektur ==

Diese Seite beschreibt die produktiv relevanten Klassen <code>OSentryHL</code> und <code>OSentry</code>.

=== Klassenübersicht ===

{| class="wikitable"
! Klasse !! Rolle
|-
| <code>OSentryHL</code> || High-Level-Adapter für Applikationscode
|-
| <code>OSentry</code> || Low-Level-Adapter für JSON, [[#Stacktrace und Kontext|Stacktrace]] und HTTP
|-
| <code>Startup_Task</code> || [[#Demo Library|Demo]]-Startup und Beispiel für Initialisierung
|-
| <code>FSY_Demo</code> || [[#Demo Library|Demo]]-Fenster
|-
| <code>ODummy</code> || [[#Demo Library|Demo]]-Code für [[#Stacktrace und Kontext|Stacktrace]]-Beispiel
|-
| <code>ODatabaseHandler</code> || [[#Demo Library|Demo]]-DB Initialisierung
|-
| <code>OSLSession</code> || SQLite Session für [[#Demo Library|Demo]]
|}

=== Empfohlener Aufrufweg ===

Applikationscode sollte <code>OSentryHL</code> verwenden:

<syntaxhighlight lang="text">
Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')
</syntaxhighlight>

<code>OSentryHL</code> delegiert anschließend an <code>OSentry</code>:

<syntaxhighlight lang="text">
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code
</syntaxhighlight>

=== Ablauf eines Events ===

# Applikationscode ruft Methode in <code>OSentryHL</code> auf.
# <code>OSentryHL</code> fügt bei Bedarf [[#Tags, Extras und User-Kontext|Tags und Extras]] hinzu.
# <code>OSentryHL</code> ruft <code>iOSentry.$captureException(...)</code> auf.
# <code>OSentry</code> prüft, ob Sentry aktiv ist.
# <code>OSentry</code> erzeugt JSON.
# [[#Stacktrace und Kontext|Stacktrace]], Exception Interface und [[#Tags, Extras und User-Kontext|User Interface]] werden optional ergänzt.
# HTTP Header und Sentry Auth Header werden erstellt.
# JSON wird per HTTPS an Sentry gesendet.
# Bei Erfolg werden [[#Tags, Extras und User-Kontext|Tags und Extras]] geleert.
# Bei Fehler wird der JSON Report lokal gespeichert.

=== DSN Parsing ===

<code>OSentry.$init</code> zerlegt die DSN:

<syntaxhighlight lang="text">
# Parse the DSN into Public Key, Host and Project ID
If len(pDSN)>5
Calculate iDSN as pDSN
Calculate part1 as strtok('iDSN','@')
Calculate iProtocol as strtok('part1','/')
Calculate iProtocol as left(iProtocol,len(iProtocol)-1)
Do strtok('part1','/')
Calculate iPubKey as strtok('part1',':')

Calculate iHost as strtok('iDSN','/')
Calculate iProID as iDSN

#Save the values for the next startup
Calculate $cclass.$ivardefs.iPubKey.$objinitval as con('"',iPubKey,'"')
Calculate $cclass.$ivardefs.iHost.$objinitval as con('"',iHost,'"')
Calculate $cclass.$ivardefs.iProID.$objinitval as con('"',iProID,'"')
End If

Quit method
</syntaxhighlight>

=== JSON-Erzeugung ===

<code>OSentry.$generateJson</code> ist die zentrale Methode für den Payload. Sie setzt unter anderem:

* <code>event_id</code>
* <code>logger</code>
* <code>platform</code>
* <code>culprit</code>
* <code>timestamp</code>
* <code>sdk</code>
* <code>message</code>
* <code>level</code>
* <code>tags</code>
* <code>extra</code>
* optional <code>user</code>
* optional <code>exception</code>
* optional <code>stacktrace</code>

Auszug:

<syntaxhighlight lang="text">
# Add all required fields (those are required from the API)
Do JSON.$addmember('','event_id',$cinst.$generateUUID()) ## auto generated UUID 4
Do JSON.$addmember('','logger',logger)
Do JSON.$addmember('','platform',platform)
Do JSON.$addmember('','culprit',culprit)
#Do JSON.$addmember('','release',release)
Do JSON.$addmember('','timestamp',timestamp)
Do JSON.$addmember('','sdk','')
Do JSON.$addmember('','message',pErrorText)
Do JSON.$addmember('','level',pLevel)
Do JSON.$addmember('','tags','')
</syntaxhighlight>

=== HTTP-Kommunikation ===

<code>OSentry.$captureException</code> sendet den erzeugten JSON-Payload an Sentry:

<syntaxhighlight lang="text">
#Generate HTTP Auth header
Begin text block
Text:Sentry sentry_version=7,
Text:sentry_timestamp=[$cinst.$getUnixTimestamp()],
Text:sentry_key=[iPubKey],
Text:sentry_client=omnis/1.0
End text block
Get text block auth

#Generate header list
Calculate Host as 'sentry.io'
Calculate Url as con('/api/',iProID,'/store/')
Do HdrList.$define(wert,name)
Do HdrList.$add('User-Agent','omnis/1.0')
Do HdrList.$add('Content-Type','application/json')
Do HdrList.$add('Content-Length',binlength(json))
Do HdrList.$add('X-Sentry-Auth',auth)
</syntaxhighlight>

Anschließend wird der Request über <code>HTTPPost</code>, <code>HTTPSend</code> und <code>HTTPRead</code> ausgeführt.

=== Fehlerbehandlung beim Senden ===

Wenn der Socket nicht geöffnet werden kann:

<syntaxhighlight lang="text">
HTTPPost (Host,Url,,HdrList,443,kTrue,kTrue) Returns Socket
If Socket<0
#Error when opening connection -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Error ',Socket,' when performing HTTPPost'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -1
End If
</syntaxhighlight>

Wenn das Senden fehlschlägt:

<syntaxhighlight lang="text">
HTTPSend (Socket,json) Returns byteCount
If byteCount<0
# Error while sending data -> save json as a file
Do $cinst.$writeJSON(iJSON,con('Erorr ',byteCount,' when performing HTTPSend'))
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -2
End If
</syntaxhighlight>

Wenn die Antwort nicht erfolgreich ist:

<syntaxhighlight lang="text">
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</syntaxhighlight>

=== Lokales Speichern ===

Bei Fehlern wird der JSON Report lokal im Omnis-Installationsordner gespeichert:

<syntaxhighlight lang="text">
#Writes the json and the http buffer to a file in the omnis installation folder
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
Do fOP.$writecharacter(kUniTypeUTF8,pJSON) Returns err
If not(isclear(pBuffer))
Do fOP.$writecharacter(kUniTypeUTF8,con(kCr,pBuffer),kTrue) Returns err
End If
Do fOP.$closefile()

Quit method
</syntaxhighlight>

=== Cleanup ===

Nach erfolgreichem Senden werden [[#Tags, Extras und User-Kontext|Tags und Extras]] gelöscht:

<syntaxhighlight lang="text">
#Clears all extras and tags => to be used after a sentry request has successfully been sent
Do iTagList.$clear()
Do iExtraList.$clear()
Quit method
</syntaxhighlight>

== Demo Library ==

Die Demo-Library zeigt, wie <code>OSentry</code> initialisiert wird und wie verschiedene [[#Events erfassen|Event-Typen]] aus einer Omnis-Oberfläche heraus an Sentry gesendet werden.

=== Bestandteile ===

{| class="wikitable"
! Klasse !! Zweck
|-
| <code>Startup_Task</code> || Initialisiert Sentry, SQLite und öffnet das Demo-Fenster
|-
| <code>FSY_Demo</code> || Demo-Fenster
|-
| <code>ODummy</code> || Erzeugt Demo-Stack für Exception
|-
| <code>ODatabaseHandler</code> || Erstellt SQLite-Demo-Datenbank
|-
| <code>OSLSession</code> || SQLite Session
|-
| <code>OSentry</code> || Low-Level-Sentry-Adapter
|-
| <code>OSentryHL</code> || High-Level-Sentry-Adapter
|}

=== Startup ===

<code>Startup_Task.$construct</code> initialisiert Sentry, baut eine SQLite Session auf und öffnet das Demo-Fenster. Quelle: <code>Startup_Task.$construct</code>.

<syntaxhighlight lang="text">
#Init Sentry on lbs startup
Do tSentry.$init()

#SQLite Session init
Do $objects.OSLSession.$newref() Returns tOSLSession
#Calculate tOSLSession.$opencreate as kTrue
Calculate workingDir as tODatabaseHandler.$getWorkingDir()
Do con(workingDir,'Sentry_Test.db') Returns dbLocation
Do tOSLSession.$logon(dbLocation,'','','slsession') Returns #F

#Open Test Window
Do $windows.FSY_Demo.$openonce('*')

Quit method
</syntaxhighlight>

=== Demo-Fenster ===

<code>FSY_Demo</code> enthält folgende Bereiche:

* DSN Configuration
* DB Status
* Actions

Wichtige Felder:

{| class="wikitable"
! Feld !! Datenanbindung
|-
| DSN || <code>iDSN</code>
|-
| Host || <code>tSentry.iOSentry.iHost</code>
|-
| Public Key || <code>tSentry.iOSentry.iPubKey</code>
|-
| Project ID || <code>tSentry.iOSentry.iProID</code>
|-
| DB Status || <code>iCurrentDBStatus</code>
|}

[[Datei:demo-window.svg|thumb|Demo-Fenster der OSentry Library]]

=== DSN setzen ===

Die DSN wird im Feld <code>iDSN</code> erfasst. Der Button <code>Set DSN</code> ruft anschließend <code>tSentry.$init(iDSN)</code> auf. Nach dem Setzen werden Public Key, Host und Project ID aus der DSN gelesen und in den darunterliegenden Feldern angezeigt.

[[Datei:demo-dsn.svg|thumb|DSN-Konfiguration im Demo-Fenster]]

Der Button <code>Set DSN</code> initialisiert Sentry mit der eingegebenen DSN. Quelle: <code>FSY_Demo.setDSN.$event</code>.

<syntaxhighlight lang="text">
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$init(iDSN)
Calculate $cclass.$ivardefs.iDSN.$objinitval as con(kSq,iDSN,kSq)

Do $cinst.$showmessage('DSN set and Sentry initialized!','Info')

Do $cinst.$redraw()
Quit method
</syntaxhighlight>

=== DB Status anzeigen ===

<code>FSY_Demo.$displayDBState</code> zeigt, ob die SQLite Session verbunden ist. Quelle: <code>FSY_Demo.$displayDBState</code>.

<syntaxhighlight lang="text">
Do tOSLSession.$state Returns dbState
If dbState='kSessionStateLoggedOff'
Calculate iCurrentDBStatus as 'Logged Off'
Else If dbState='kSessionStateLoggedOn'
Calculate iCurrentDBStatus as 'Logged On'
Else
Calculate iCurrentDBStatus as 'Unkown DB State'
End If

Do $cinst.$redraw()
Quit method
</syntaxhighlight>

=== Demo-Datenbank erstellen ===

Der Button <code>Create Database</code> ruft <code>ODatabaseHandler.$DBFirstInit</code> auf. Quelle: <code>FSY_Demo.createDB.$event</code>.

<syntaxhighlight lang="text">
On evClick ## Event Parameters - pRow( Itemreference )
#Setup the DB
Do tODatabaseHandler.$DBFirstInit() Returns err
If err=0
Do $cinst.$showmessage('DB successfully created!','Info')
Else
Do $cinst.$showmessage('Error while creating the DB. Make sure that the DB does not already exist.','Info')
End If

Do $cinst.$displayDBState()

Quit method
</syntaxhighlight>

Die Datenbank wird im Arbeitsverzeichnis der Library angelegt. Quelle: <code>ODatabaseHandler.$getWorkingDir</code>.

<syntaxhighlight lang="text">
Quit method con(FileOps.$parentdir($clib.$pathname),pathsep())
</syntaxhighlight>

Die Demo-DB enthält unter anderem:

* <code>dperson</code>
* <code>drelease</code>
* <code>dvcs</code>

=== Message auslösen ===

Button <code>Trigger a message</code>. Quelle: <code>FSY_Demo.message.$event</code>.

<syntaxhighlight lang="text">
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureMessage('Hello Euromnis! This is a test message...')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</syntaxhighlight>

=== Log auslösen ===

Button <code>Trigger a log</code>. Quelle: <code>FSY_Demo.log.$event</code>.

<syntaxhighlight lang="text">
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureLog('Uh oh this is a Log because something went wrong')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</syntaxhighlight>

=== Exception auslösen ===

Button <code>Trigger an exception</code> bereitet eine Row und eine List vor und ruft anschließend <code>ODummy.$dummyMethod</code> auf. Quelle: <code>FSY_Demo.exception.$event</code>.

<syntaxhighlight lang="text">
On evClick ## Event Parameters - pRow( Itemreference )
Do iDummyRow.$define(id,name)
Calculate iDummyRow.id as 22
Calculate iDummyRow.name as 'Tom'

Do iDummyList.$define(id,weekday)
Do iDummyList.$add(1,'Monday')
Do iDummyList.$add(2,'Tuesday')
Do iDummyList.$add(3,'Wednesday')
Do iDummyList.$add(4,'Thursday')
Do iDummyList.$add(5,'Friday')
Do iDummyList.$add(6,'Saturday')
Do iDummyList.$add(7,'Sunday')

Calculate iDummyList.$line as 5

Do iODummy.$dummyMethod('Important Value')
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')

Quit method
</syntaxhighlight>

<code>ODummy.$dummyMethod</code> sendet die Exception. Quelle: <code>ODummy.$dummyMethod</code>.

<syntaxhighlight lang="text">
#In here is some logic
#This logic would produce an error
#We send all this information to Sentry

Do tSentry.$captureException('A generic Exception occured',1234,'Generic Exception','error')

Quit method 0
</syntaxhighlight>

=== Deprecated Call auslösen ===

Button <code>Trigger a deprecated call</code>. Quelle: <code>FSY_Demo.deprecatedCall.$event</code>.

<syntaxhighlight lang="text">
On evClick ## Event Parameters - pRow( Itemreference )
Do tSentry.$captureDeprecatedCall()
Do $cinst.$showmessage('Sentry Event successfully triggered!','Info')
Quit method
</syntaxhighlight>

=== SQL Exception Button ===

Der Button <code>Trigger an SQLException</code> ist im Export vorhanden, enthält aber noch keinen fertigen Demo-Code. Quelle: <code>FSY_Demo.sqlException.$event</code>.

<syntaxhighlight lang="text">
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</syntaxhighlight>

Für die Dokumentation der SQL-Erfassung siehe [[#Events erfassen|03 Events erfassen]].

== API Reference ==

Diese Seite dokumentiert die produktiv relevanten Methoden von <code>OSentryHL</code> und <code>OSentry</code>.

=== OSentryHL ===

<code>OSentryHL</code> ist die empfohlene Klasse für Applikationscode.

==== <code>$init(pDSN)</code> ====

Initialisiert das interne <code>OSentry</code>-Objekt.

<syntaxhighlight lang="text">
#Init of the main sentry object
Do iOSentry.$init(pDSN)
Quit method
</syntaxhighlight>

==== <code>$captureMessage(pMessage)</code> ====

Sendet eine einfache Info-Message.

<syntaxhighlight lang="text">
# Captures an Info Message
Do iOSentry.$captureException(pMessage,3,,'info',kFalse,,kFalse) Returns code
Quit method
</syntaxhighlight>

==== <code>$captureException(pErrorText,pErrorCode,pExcType,pLevel)</code> ====

Sendet eine generische Exception.

<syntaxhighlight lang="text">
# Method to capture a generic Exception
#Add any custom tags / extras
Do $cinst.$addTag('Custom Test Tag','Euromnis')

Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel) Returns code

Quit method
</syntaxhighlight>

==== <code>$captureAnything(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface)</code> ====

Sendet ein frei konfigurierbares Event.

<syntaxhighlight lang="text">
# Capture a generic Sentry Report (max configurability)
Do iOSentry.$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraveInterface,pExceptionInterface,pUserInterface) Returns code

Quit method
</syntaxhighlight>

Hinweis: Der Parameter ist im Export als <code>pStacktraveInterface</code> geschrieben.

==== <code>$captureLog(pErrorText)</code> ====

Sendet ein Log-Event.

<syntaxhighlight lang="text">
# Captures a Log Sentry Report
Do iOSentry.$captureException(pErrorText,1,'Log','warning',1,0,1) Returns code

Quit method
</syntaxhighlight>

==== <code>$captureDeprecatedCall()</code> ====

Meldet die Ausführung eines veralteten Codepfads.

<syntaxhighlight lang="text">
# Report a deprecated call of a piece of code to sentry
Do iOSentry.$captureException('Deprecated Call',3,'Deprecated Call','warning',1,1,1) Returns code

Quit method
</syntaxhighlight>

==== <code>$captureSQLException(pErrorText,pStat)</code> ====

Meldet einen SQL-Fehler mit SQL-Text und nativer Datenbankfehlermeldung.

<syntaxhighlight lang="text">
# Method to capture an SQL Exception
Do $cinst.$addTag('Database',tOSLSession.$hostname)

Do $cinst.$addExtra('SQL-Text',pStat.$sqltext)
Do $cinst.$addExtra('SQL-Error',pStat.$nativeerrortext)

Do iOSentry.$captureException(pErrorText,1,'SQL-Exception','error')
Quit method
</syntaxhighlight>

==== <code>$addTag(pName,pValue)</code> ====

Fügt einen Tag für das nächste Event hinzu.

<syntaxhighlight lang="text">
# Add a Tag to the next Sentry Report
Do iOSentry.$addTag(pName,pValue)
Quit method
</syntaxhighlight>

==== <code>$addExtra(pName,pValue)</code> ====

Fügt ein Extra für das nächste Event hinzu.

<syntaxhighlight lang="text">
# Add an Extra to the next Sentry Report
Do iOSentry.$addExtra(pName,pValue)
Quit method
</syntaxhighlight>

==== <code>$setStatus(pStatus)</code> ====

Aktiviert oder deaktiviert Sentry.

<syntaxhighlight lang="text">
#Toggels Sentry on or off
Do iOSentry.$setStatus(pStatus)
Quit method
</syntaxhighlight>

==== <code>$setUser()</code> ====

Setzt im Export feste [[#Demo Library|Demo]]-Userdaten.

<syntaxhighlight lang="text">
# Set the User which should be linked to the Sentry Issue
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
Quit method
</syntaxhighlight>

Für produktive Nutzung sollte diese Methode parametrisiert werden.

=== OSentry ===

<code>OSentry</code> ist die Low-Level-Klasse für Payload-Erzeugung und Versand.

==== <code>$init(pDSN)</code> ====

Parst die DSN in Protokoll, Public Key, Host und Project ID.

==== <code>$captureException(pErrorText,pErrorCode,pExcType,pLevel,pStacktraceInterface,pUserInterface,pExceptionInterface)</code> ====

Erzeugt JSON, sendet es an Sentry und behandelt Fehlerfälle.

Parameter:

{| class="wikitable"
! Parameter !! Default !! Bedeutung
|-
| <code>pErrorText</code> || || Message
|-
| <code>pErrorCode</code> || || Fehlercode
|-
| <code>pExcType</code> || || Exception-Typ
|-
| <code>pLevel</code> || || <code>fatal</code>, <code>error</code>, <code>warning</code>, <code>info</code>, <code>debug</code>
|-
| <code>pStacktraceInterface</code> || <code>kTrue</code> || [[#Stacktrace und Kontext|Stacktrace]] senden
|-
| <code>pUserInterface</code> || <code>kTrue</code> || [[#Tags, Extras und User-Kontext|User-Kontext]] senden
|-
| <code>pExceptionInterface</code> || <code>kTrue</code> || Exception Interface senden
|}

==== <code>$generateJson(...)</code> ====

Erzeugt den Sentry JSON Payload als Binary.

==== <code>$generateStacktraceInterface(pCulprit)</code> ====

Erzeugt den Omnis-[[#Stacktrace und Kontext|Stacktrace]] inklusive Variablen und Kontextzeilen.

==== <code>$generateExceptionInterface(pType,pValue)</code> ====

Erzeugt das Sentry Exception Interface.

<syntaxhighlight lang="text">
# Generate Row to store in the JSON
Do exceptionRow.$define(type,value,stacktrace)
Calculate exceptionRow.type as pType
Calculate exceptionRow.value as pValue
Calculate exceptionRow.stacktrace as 'sentry.interfaces.stacktrace' ## Tells the exception interface that a stacktrace is passed aswell
</syntaxhighlight>

==== <code>$generateUserInterface()</code> ====

Erzeugt den [[#Tags, Extras und User-Kontext|User-Kontext]].

==== <code>$addTag(pName,pValue)</code> ====

Fügt einen Tag zur internen Tag-Liste hinzu.

==== <code>$addExtra(pName,pValue)</code> ====

Fügt ein Extra zur internen Extra-Liste hinzu.

==== <code>$clearList()</code> ====

Leert [[#Tags, Extras und User-Kontext|Tags und Extras]] nach einem Request.

==== <code>$setUserData(pID,pName,pEmail)</code> ====

Setzt Userdaten für den nächsten Request.

==== <code>$setProxy(pProxyHost,pProxyPort)</code> ====

Setzt Proxy-Informationen.

==== <code>$setStatus(pStatus)</code> ====

Setzt den Sentry-Status.

<syntaxhighlight lang="text">
#Toggels Sentry Reports on or off
Calculate iStatus as pStatus
Quit method
</syntaxhighlight>

==== <code>$writeJSON(pJSON,pBuffer)</code> ====

Schreibt fehlgeschlagene Reports lokal in eine Datei.

==== <code>$getUnixTimestamp()</code> ====

Gibt den aktuellen UNIX Timestamp zurück.

==== <code>$generateUUID()</code> ====

Erzeugt eine UUID für die Sentry Event ID.

<syntaxhighlight lang="text">
#Genereates a UUID for the issue id
Quit method OW3.$makeuuid(kFalse)
</syntaxhighlight>

== Troubleshooting ==

=== Es erscheinen keine Events in Sentry ===

Prüfe zuerst, ob Sentry aktiv ist:

<syntaxhighlight lang="text">
Do tSentry.$setStatus(1)
</syntaxhighlight>

<code>OSentry.$captureException</code> beendet sich sofort, wenn der Status <code>0</code> oder leer ist:

<syntaxhighlight lang="text">
#Check if Sentry is enabled
If iStatus=0|isclear(iStatus)
Quit method 0
End If
</syntaxhighlight>

=== Die DSN ist falsch ===

Prüfe, ob die DSN korrekt aus Sentry kopiert wurde. <code>OSentry.$init</code> erwartet eine DSN, aus der Public Key, Host und Project ID gelesen werden können.

Nach dem Setzen der DSN sollten in der [[#Demo Library|Demo-Library]] folgende Felder gefüllt sein:

* Host
* Public Key
* Project ID

=== Netzwerk oder Proxy blockiert den Request ===

Wenn die Anwendung keinen direkten Zugriff auf Sentry hat, setze einen Proxy:

<syntaxhighlight lang="text">
Do tSentry.iOSentry.$setProxy('proxy.example.local','8080')
</syntaxhighlight>

Intern wird der Proxy vor dem HTTP Request gesetzt:

<syntaxhighlight lang="text">
If not(isclear(iProxyHost))&not(isclear(iProxyPort))
HTTPSetProxyServer (iProxyHost,iProxyPort)
End If
</syntaxhighlight>

=== Report wird lokal gespeichert ===

Wenn <code>HTTPPost</code>, <code>HTTPSend</code> oder <code>HTTPRead</code> fehlschlägt, speichert OSentry den Report lokal:

<syntaxhighlight lang="text">
Calculate path as sys(115)
Calculate filename as con('Sentryreport_',$cinst.$getUnixTimestamp(),'.json')
Do fOP.$createfile(con(path,filename)) Returns err
</syntaxhighlight>

Suche im Omnis-Installationsordner nach Dateien mit dem Namen:

<syntaxhighlight lang="text">
Sentryreport_<timestamp>.json
</syntaxhighlight>

=== Sentry antwortet nicht mit 200 OK ===

Wenn die HTTP-Antwort kein <code>200 OK</code> enthält, wird der JSON Report ebenfalls lokal gespeichert:

<syntaxhighlight lang="text">
HTTPRead (Socket,Buffer) Returns byteCount
If byteCount<0|not(pos('200 OK',Buffer))
# JSON may be corrupted or contains errors -> save json and the buffer as a file
Do $cinst.$writeJSON(iJSON,Buffer)
Do $cinst.$clearList()
HTTPClose (Socket)
Quit method -3
End If
</syntaxhighlight>

Mögliche Ursachen:

* falsche Project ID
* falscher Public Key
* ungültige DSN
* JSON Payload wird von Sentry abgelehnt
* Netzwerk-Gateway verändert den Request

=== Tags oder Extras erscheinen beim falschen Event ===

[[#Tags, Extras und User-Kontext|Tags und Extras]] werden für den nächsten Request gesammelt. Nach erfolgreichem Request werden sie gelöscht:

<syntaxhighlight lang="text">
Do iTagList.$clear()
Do iExtraList.$clear()
</syntaxhighlight>

Wenn ein Request fehlschlägt, wird ebenfalls aufgeräumt:

<syntaxhighlight lang="text">
Do $cinst.$clearList()
</syntaxhighlight>

Prüfe trotzdem, ob in eigenen Wrapper-Methoden Tags und Extras direkt vor dem passenden Capture-Aufruf gesetzt werden.

=== User-Kontext zeigt Demo-Daten ===

<code>OSentryHL.$setUser</code> verwendet im Export feste Testdaten:

<syntaxhighlight lang="text">
Do iOSentry.$setUserData(23,'Euromnis Test User','euromnis@test.com')
</syntaxhighlight>

Für produktive Nutzung sollte die Methode parametrisiert werden:

<syntaxhighlight lang="text">
Do iOSentry.$setUserData(pUserID,pUserName,pUserEmail)
</syntaxhighlight>

=== SQL Exception Demo-Button funktioniert nicht ===

Der Button <code>Trigger an SQLException</code> ist im Export noch nicht implementiert:

<syntaxhighlight lang="text">
On evClick ## Event Parameters - pRow( Itemreference )
#Code need's to be written
</syntaxhighlight>

Die produktive Methode für SQL-Fehler ist aber vorhanden. Siehe auch [[#Events erfassen|Events erfassen]].

<syntaxhighlight lang="text">
Do tSentry.$captureSQLException('SQL statement failed',stat)
</syntaxhighlight>

=== Zu viele Events ===

Sentry kann sehr schnell viele Events sammeln. Verwende für produktive Systeme:

* klare Wrapper-Methoden in <code>OSentryHL</code>
* sinnvolle Levels
* gezielte [[#Tags, Extras und User-Kontext|Tags]]
* keine Events in sehr häufigen Schleifen
* keine rein informativen Debug-Events ohne Nutzen

=== Sensible Daten ===

[[#Stacktrace und Kontext|Stacktrace]], Parameter, Instance Variablen, SQL-Text und [[#Tags, Extras und User-Kontext|Extras]] können sensible Daten enthalten. Prüfe vor produktiver Nutzung:

* Welche Variablen werden übertragen?
* Enthalten SQL-Statements personenbezogene Daten?
* Werden Tokens oder Passwörter in Extras geschrieben?
* Sollen bestimmte Werte maskiert werden?

Datei:Demo-window.png

2026-06-12T13:58:35Z

Silvan:

Datei:Demo-dsn.png

2026-06-12T13:58:21Z

Silvan:

Datei:Sentry-tags.png

2026-06-12T13:55:30Z

Silvan:

Datei:Sentry-stack.png

2026-06-12T13:55:20Z

Silvan:

Datei:Sentry-projects.png

2026-06-12T13:55:10Z

Silvan:

Datei:Sentry-issue.png

2026-06-12T13:54:58Z

Silvan:

Entausschiessen

2026-01-28T10:33:14Z

Silvan: /* Anwendungsbeispiel */

;Mantiseinträge:
3583
;Systemtyp:
79

== Beschreibung ==
Dieser Serverjob führt einen '''Entausschiessen-Algorithmus''' aus.
Er wird eingesetzt, wenn z. B. '''Broschüren oder geheftete Dokumente''' (Bostitch/Klammer entfernt) geöffnet und anschliessend über einen '''Durchlaufscanner''' digitalisiert werden.

Ein Durchlaufscanner erfasst jeweils eine '''aufgeklappte Doppelseite'''.
'''Jede gescannte Seite wird dabei in zwei einzelne Bilddateien aufgetrennt.'''

Dabei entsteht eine Bildreihenfolge, die nicht der logischen Seitenreihenfolge des Dokuments entspricht:

* Bei der '''ersten gescannten Seite''' ist
** das '''erste Bild''' die '''letzte Seite''' der Broschüre
** das '''zweite Bild''' die '''erste Seite''' der Broschüre
* Bei den '''folgenden Scans''' alterniert die Reihenfolge der aufgetrennten Bilder (aussen nach innen)

Der Serverjob bringt diese aufgetrennten Bilder automatisch in die korrekte Reihenfolge.

== Funktionsweise ==
Ausgehend von einer Liste mit ''N'' Bilddateien (Einzelseiten), welche aus dem Auftrennen der gescannten Doppelseiten entstehen, ordnet der Algorithmus die Seiten nach dem Prinzip '''aussen nach innen''' neu an.

Die resultierende Reihenfolge folgt diesem Muster:

* letztes Dokumentblatt
* erstes Dokumentblatt
* zweites Dokumentblatt
* zweitletztes Dokumentblatt
* usw.

Nach der Neuordnung werden die Dateien fortlaufend neu nummeriert:

<code>0001.tif … 000N.tif</code>

== Mathematische Beschreibung ==
Es sei ''N'' die Anzahl der '''aufgetrennten Einzelseiten''' (nicht der gescannten Doppelseiten).

Die Eingabe für den Algorithmus ist eine Liste von ''N'' Bildern, welche durch das Auftrennen der gescannten Doppelseiten entstehen.
Diese Liste entspricht einer Reihenfolge von außen nach innen.

Für eine Zielposition <code>k</code> mit

<code>1 ≤ k ≤ N</code>

berechnet der Algorithmus, welche physische Seite an dieser Position stehen soll.

Die Zuordnung erfolgt über die Funktion <code>f(k)</code>:

<pre>
f(k) =
N - ⌊(k-1)/2⌋ falls k ≡ 1 (mod 4)
1 + ⌊(k-2)/2⌋ falls k ≡ 2 (mod 4)
1 + ⌊(k-3)/2⌋ falls k ≡ 3 (mod 4)
N - ⌊(k-4)/2⌋ falls k ≡ 0 (mod 4)
</pre>

=== Beispielrechnung ===
Gegeben sei ein Dokument mit <code>N = 8</code> Einzelseiten und die Zielposition <code>k = 5</code>.

Zuerst wird die Modulo-Klasse bestimmt:

<code>5 mod 4 = 1</code>

Damit gilt der erste Fall der Definition:

<pre>
f(5) = 8 − ⌊(5−1)/2⌋
= 8 − ⌊2⌋
= 6
</pre>

Das bedeutet:
'''Die Zielposition 0005 enthält die physische Seite 6.'''

== Anwendungsbeispiel ==
Eine Broschüre mit 8 physischen Seiten wird geöffnet (Bostitch entfernt) und über einen Durchlaufscanner digitalisiert.

Der Scanner erfasst aufgeklappte Doppelseiten.
Jede gescannte Seite wird anschließend in zwei Bilder aufgetrennt.

{| class="wikitable"
! Gescannte Seite !! Bild 1 !! Bild 2
|-
| Scan 1 || Seite 8 || Seite 1
|-
| Scan 2 || Seite 2 || Seite 7
|-
| Scan 3 || Seite 6 || Seite 3
|-
| Scan 4 || Seite 4 || Seite 5
|}

Daraus ergibt sich folgende Bildliste (Eingabe für den Serverjob):

<code>(8, 1, 2, 7, 6, 3, 4, 5)</code>

=== Bezug zur mathematischen Beschreibung ===
Für die Zielposition <code>k = 5</code> ergibt die mathematische Funktion:

<code>f(5) = 6</code>

Der fünfte Eintrag der Bildliste ist ebenfalls '''Seite 6''':

{| class="wikitable"
! Zielposition !! Physische Seite
|-
| 0005 || 6
|}

[[Kategorie:Workflowschritt]]

Entausschiessen

2026-01-28T10:33:02Z

Silvan: /* Mathematische Beschreibung */

Entausschiessen

2026-01-28T10:31:49Z

Silvan:

;Mantiseinträge:
3583
;Systemtyp:
79

== Beschreibung ==
Dieser Serverjob führt einen '''Entausschiessen-Algorithmus''' aus.
Er wird eingesetzt, wenn z. B. '''Broschüren oder geheftete Dokumente''' (Bostitch/Klammer entfernt) geöffnet und anschliessend über einen '''Durchlaufscanner''' digitalisiert werden.

Ein Durchlaufscanner erfasst jeweils eine '''aufgeklappte Doppelseite'''.
'''Jede gescannte Seite wird dabei in zwei einzelne Bilddateien aufgetrennt.'''

Dabei entsteht eine Bildreihenfolge, die nicht der logischen Seitenreihenfolge des Dokuments entspricht:

* Bei der '''ersten gescannten Seite''' ist
** das '''erste Bild''' die '''letzte Seite''' der Broschüre
** das '''zweite Bild''' die '''erste Seite''' der Broschüre
* Bei den '''folgenden Scans''' alterniert die Reihenfolge der aufgetrennten Bilder (aussen nach innen)

Der Serverjob bringt diese aufgetrennten Bilder automatisch in die korrekte Reihenfolge.

== Funktionsweise ==
Ausgehend von einer Liste mit ''N'' Bilddateien (Einzelseiten), welche aus dem Auftrennen der gescannten Doppelseiten entstehen, ordnet der Algorithmus die Seiten nach dem Prinzip '''aussen nach innen''' neu an.

Die resultierende Reihenfolge folgt diesem Muster:

* letztes Dokumentblatt
* erstes Dokumentblatt
* zweites Dokumentblatt
* zweitletztes Dokumentblatt
* usw.

Nach der Neuordnung werden die Dateien fortlaufend neu nummeriert:

<code>0001.tif … 000N.tif</code>

== Mathematische Beschreibung ==
Es sei ''N'' die Anzahl der '''aufgetrennten Einzelseiten''' (nicht der gescannten Doppelseiten).

Die Eingabe für den Algorithmus ist eine Liste von ''N'' Bildern, welche durch das Auftrennen der gescannten Doppelseiten entstehen.
Diese Liste entspricht einer Reihenfolge von außen nach innen.

Für eine Zielposition <code>k</code> mit

<code>1 ≤ k ≤ N</code>

berechnet der Algorithmus, welche physische Seite an dieser Position stehen soll.

Die Zuordnung erfolgt über die Funktion <code>f(k)</code>:

<pre>
f(k) =
N - ⌊(k-1)/2⌋ falls k ≡ 1 (mod 4)
1 + ⌊(k-2)/2⌋ falls k ≡ 2 (mod 4)
1 + ⌊(k-3)/2⌋ falls k ≡ 3 (mod 4)
N - ⌊(k-4)/2⌋ falls k ≡ 0 (mod 4)
</pre>

=== Beispielrechnung ===
Gegeben sei ein Dokument mit <code>N = 8</code> Einzelseiten und die Zielposition <code>k = 5</code>.

Zuerst wird die Modulo-Klasse bestimmt:

<code>5 mod 4 = 1</code>

Damit gilt der erste Fall der Definition:

<pre>
f(5) = 8 − ⌊(5−1)/2⌋
= 8 − ⌊2⌋
= 6
</pre>

Das bedeutet:
'''Die Zielposition 0005 enthält die physische Seite 6.'''

---

== Anwendungsbeispiel ==
Eine Broschüre mit 8 physischen Seiten wird geöffnet (Bostitch entfernt) und über einen Durchlaufscanner digitalisiert.

Der Scanner erfasst aufgeklappte Doppelseiten.
Jede gescannte Seite wird anschließend in zwei Bilder aufgetrennt.

{| class="wikitable"
! Gescannte Seite !! Bild 1 !! Bild 2
|-
| Scan 1 || Seite 8 || Seite 1
|-
| Scan 2 || Seite 2 || Seite 7
|-
| Scan 3 || Seite 6 || Seite 3
|-
| Scan 4 || Seite 4 || Seite 5
|}

Daraus ergibt sich folgende Bildliste (Eingabe für den Serverjob):

<code>(8, 1, 2, 7, 6, 3, 4, 5)</code>

=== Bezug zur mathematischen Beschreibung ===
Für die Zielposition <code>k = 5</code> ergibt die mathematische Funktion:

<code>f(5) = 6</code>

Der fünfte Eintrag der Bildliste ist ebenfalls '''Seite 6''':

{| class="wikitable"
! Zielposition !! Physische Seite
|-
| 0005 || 6
|}

Damit ist gezeigt, dass die mathematische Beschreibung exakt der tatsächlichen Scan- und Auftrennreihenfolge entspricht.

[[Kategorie:Workflowschritt]]

Entausschiessen

2026-01-28T10:20:17Z

Silvan: 3583: Neuer Wikieintrag

;Mantiseinträge:
3583
;Systemtyp:
79

== Beschreibung ==
Dieser Serverjob führt einen '''Entausschiessen-Algorithmus''' aus.
Er wird eingesetzt, wenn z. B. '''Broschüren oder geheftete Dokumente''' (Bostitch/Klammer entfernt) geöffnet und anschliessend über einen '''Durchlaufscanner''' digitalisiert werden.

Ein Durchlaufscanner erfasst jeweils eine '''aufgeklappte Doppelseite'''.
'''Jede gescannte Seite wird dabei in zwei einzelne Bilddateien aufgetrennt.'''

Dabei entsteht eine Bildreihenfolge, die nicht der logischen Seitenreihenfolge des Dokuments entspricht:

* Bei der '''ersten gescannten Seite''' ist
** das '''erste Bild''' die '''letzte Seite''' der Broschüre
** das '''zweite Bild''' die '''erste Seite''' der Broschüre
* Bei den '''folgenden Scans''' alterniert die Reihenfolge der aufgetrennten Bilder (aussen nach innen)

Der Serverjob bringt diese aufgetrennten Bilder automatisch in die korrekte Reihenfolge.

== Funktionsweise ==
Ausgehend von einer Liste mit ''N'' Bilddateien (Einzelseiten), welche aus dem Auftrennen der gescannten Doppelseiten entstehen, ordnet der Algorithmus die Seiten nach dem Prinzip '''aussen nach innen''' neu an.

Die resultierende Reihenfolge folgt diesem Muster:

* letztes Dokumentblatt
* erstes Dokumentblatt
* zweites Dokumentblatt
* zweitletztes Dokumentblatt
* usw.

Nach der Neuordnung werden die Dateien fortlaufend neu nummeriert:

<code>0001.tif … 000N.tif</code>

== Mathematische Beschreibung ==
Gegeben sei eine Folge von ''N'' Einzelseiten in logischer Reihenfolge:

<code>S = (1, 2, 3, …, N)</code>

Durch das Scannen und Auftrennen der Doppelseiten entsteht eine Eingabereihenfolge, die von aussen nach innen verläuft.

Der Entausschiessen-Algorithmus erzeugt daraus eine Zielreihenfolge:

<code>T = (1, 2, 3, …, N)</code>

indem die Seiten abwechselnd vom Anfang und vom Ende der Dokumentstruktur entnommen werden.

Formal wird für jede Zielposition <code>k</code> mit <code>1 ≤ k ≤ N</code> die zugehörige Eingabeseite <code>f(k)</code> wie folgt bestimmt:

<pre>
f(k) =
N - ⌊(k-1)/2⌋ falls k ≡ 1 (mod 4)
1 + ⌊(k-2)/2⌋ falls k ≡ 2 (mod 4)
1 + ⌊(k-3)/2⌋ falls k ≡ 3 (mod 4)
N - ⌊(k-4)/2⌋ falls k ≡ 0 (mod 4)
</pre>

Diese Abbildung stellt sicher, dass die Seiten paarweise von aussen nach innen korrekt angeordnet werden.

== Anwendungsbeispiel ==
Eine Broschüre mit 8 physischen Seiten wird geöffnet (Bostitch entfernt) und über einen Durchlaufscanner digitalisiert.

=== Scan-Ergebnis ===
Der Scanner erfasst aufgeklappte Doppelseiten, welche anschliessend in zwei Bilder aufgetrennt werden:

{| class="wikitable"
! Gescannte Seite !! Bild 1 !! Bild 2
|-
| Scan 1 || Seite 8 || Seite 1
|-
| Scan 2 || Seite 2 || Seite 7
|-
| Scan 3 || Seite 6 || Seite 3
|-
| Scan 4 || Seite 4 || Seite 5
|}

Die daraus resultierende Bildliste (Eingabe für den Serverjob) lautet:

<code>(8, 1, 2, 7, 6, 3, 4, 5)</code>

[[Kategorie:Workflowschritt]]

Produktionsaufträge

2026-01-07T10:20:50Z

Silvan: 3576: Wiki aktualisiert

;Fenstername:
'''FHK_Maske1'''

== Kopfdaten eines Produktionsaufträge ==

[[File:Kopfdaten.png|1000px|thumb|none|Tab 1 - Kopfdaten]]

=== Taste Duplizieren ===

Ermöglicht das duplizieren eines Auftrages und seiner Elemente.

*Ein duplizierter Auftrag behält den Namen seiner Vorlage mit dem Suffix " - (Kopie)" und erhält den Auftragsstatus "offen".
*Duplizierte Produktionsschritte erhalten alle den HZ Status "gestoppt".

Die zu duplizerenden Elemente des Auftrages müssen dazu entsprechend ausgewählt werden.

[[File:dupliAuswahl.png]]

Da es in einem Auftrag zu den Produktionsschritten Einstellungen geben kann, welche Auftragsspezifisch sind (Speicherpfade, Auslieferpfade, Dokumentenpfade, Internet Adressen, Benutzernamen und Kennwörter, usw.),
muss bei der Auswahl "Absolute Referenzen" duplizieren besonders darauf geachtet werden, keine falschen Angaben zu übernehmen. Alle Konfigurationen sollten anschliessend entsprechend sorgfältig überprüft werden.

Zu den Feldern für "Absolute Referenzen" gehören:

HZ_OUTPUTPFAD
HZ_INPUTPFAD
HZ_USERNAME
HZ_ZIELERSATZPFAD
HZ_METATEXTFILE
HZ_METADATENINPUTFILE
HZ_POOLPFAD
HZ_HOST

== Produktionsschritte ==

Erstellung und Basiskonfiguration der verfügbaren Arbeitsschritte.

Herkömmliche Tasten auf der rechte Seite wie '''Liste''' (Übersicht aller Produktionsaufträge/HK), '''Leistungen''' (ausgeführte Arbeiten eines Arbeitnehmers/AN innerhalb eines Produktionsauftrages/HK), '''Begleitlieferschein''',

'''Produktionsauftragsübersicht''' (Report aller Einzelheiten zu einem Produktionsauftrag/HK), '''Produktionsschritte ordnen''' (Planung des Arbeitsablaufes).

[[File:Produktionsschritte.png|1000px|thumb|none|Tab 2 - Produktionsschritte]]

====Generell====

*Serverjob: Auswahl eines Client- oder Serverseitigen Arbeitsschrittes. (Client = manuelle Verarbeitung im Helper, Server = automatische Verarbeitung durch HLI Server)
*Bezeichnung: Wörtliche Bezeichnung des Schrittes entsprechend der Workflowplanung
*Unterordner: Speicherpfad für Daten im Hauptspeicherpfad des Auftrages
*Alternative Quellen: Alternative Quellen werden berücksichtig, wenn die Objekte am Originalpfad nicht mehr vorhanden sind. Dabei können beliebig viele Zeilen konfiguriert werden. Es wird aber der erste existierende Pfad verwendet.

Format: <zuErsetzendenTeilDesOriginalPfad>*<AlternativerPfad>

Beispiel: Die benötigte Datei ist unter dem Originalpfad "O:\11_Helper\Produktion\Bodenforschung\Rename\011.tif" nicht mehr vorhanden. Über alternative Dateipfade soll unter "C:\Deleatur\Rename\011.tif" oder "E:\Deleatur\Rename\011.tif" nach den fehlenden Dateien gesucht werden.

O:\11_Helper\Produktion\Bodenforschung\*C:\Deleatur\
O:\11_Helper\Produktion\Bodenforschung\*E:\Deleatur\

====Zertifikate====

====Daten====

Grundsätzlich nur für Clientarbeitsschritte zu konfigurieren!

*Daten auf Server Speichern: Verhalten für verarbeitete Daten. Wenn die Daten (Dateien!) am Schritt nicht verändert werden, müssen diese in der Regel auch nicht nochmals gespeichert werden.
*Daten vom Server holen: Lädt die Dateien in den lokalen Arbeitsordner der ausführenden Arbeitsstation. (Dateien des letzten Arbeitsschrittes gelten damit als Basis für diesen Arbeitsschritt)
*Metadaten erfassen:
*Fehlermarkierung erlaubt: Ermöglich das markieren eines Objektes bei der manuellen Verarbeitung, wenn nach dem Abschliessen des Objektes eine Unsicherheit über die korrekte Verarbeitung besteht. Objekte können somit aufgefangen werden und fliessen nicht automatisch zum nächsten Arbeitsschritt weiter.
*Beenden nicht erlaubt: Erzwingt die abschliessende Bearbeitung eines bereits angefangenen Objektes an einem Arbeitsschritt. Ein Objekt kann somit nicht pausiert werden und muss vollständig bearbeitet werden.
*Zuweiseverhalten beim Beenden:
Zuweisung aufheben = Ein beendetes Objekt bleibt nicht derjenige Person, welche es bearbeitet hat, zugewiesen. Es fliesst zurück in den Objektpool des Arbeitsschrittes und muss/kann danach neu zugewiesen werden.
Zuweisung beibehalten = Ein beendetes Objekt bleibt der Person zugewiesen welche es bearbeitet hat.

====Sonstiges====

*Benötigter Machinentyp: Erlaubt eine Einschränkung der für den Arbeitsschritt in frage kommenden Arbeitsstationen
*Untersystemtyp: Essentielles Feld für die indivuelle Konfiguration des verwendeten Arbeitsfensters. Ermöglicht die Auswahl von Auftrags- oder Arbeitschrittbezogenen Modulen im Arbeitsfenster.
*Arbeitsschritt für Unterobjekte:
*Serverjob Version: Ermöglicht die Auswahl von versionsabhängigen Verarbeitungsalgorythmen oder von unterschiedlichen drittanbieter Komponenten in den automatisierten Serverarbeitsschritten.

===Schalter Produktionsschritte Ordnen===

Öffnet das Fenster über welches der Workflow des Projektes sowie die Detailkonfiguration der einzelnen erstellen Arbeitsschritte verwaltet werden kann.

[[File:KoordinationArbeitsschritte.png|1000px|none|]]

'''Löschen einer Verbindung'''<br>
Um eine Verbindung mit einem Arbeitsschritt zu löschen, klicken Sie mit Ctrl + Klick auf den jeweiligen Startbutton.

'''Mehrere Arbeitsschritte selektieren / deselektieren'''<br>
Um mehrere Arbeitsschritte zu selektieren nutzen Sie Shift + Klick. Um einen bestimmten Schritt zu deselektieren können Sie Shift + Rechtsklick verwenden.

==Objekttypen==

Ermöglicht die Konfiguration der Typen und von zugehörigen Attributen (Metadaten) für die zur verarbeitung vorgesehenen Objekte.

[[File:Objekttypen.png|1000px|thumb|none|Tab 3 - Objekttypen]]

'''Objekttypen/DY''' sowie '''Attributen/AT''' dienen der genaueren Beschreibung eines Objektes.

Beispiel:
*'''Objekttyp''': Bilder
*'''Attribute''': Format, Erstellungsdatum

Der Benutzer hat die Möglichkeit seine zuvor erstellten '''Vorlagen''' im Fenster Vorlagen Objekttypen/FDY_ModSpot per Knopfdruck am unteren linken Ende der Objekttypenliste/DY einzufügen. Nähere Informationen dazu in einem anderen Kapitel.

Es ist möglich für jeden Objekttyp "Interessante" Formate, Umfänge oder Kategorieren zu definieren. Mehr Informationen dazu finden Sie unter [[Formate definieren]]

===Attributswerte (Schalter - Werte Anzeigen)===

Ermöglicht eine rasche Übersicht und die Bearbeitung von bereits verarbeiteten Objekte und ihren zugehörigen Attributswerten.

[[File:Attributwerte.png|1000px|thumb|none|]]

==Einlagerung==

[[File:Tab4.jpg|1000px|thumb|none|Tab 4 - Einlagerung]]

==Anleitung==

[[File:Anleitung.png|1000px|thumb|none|Tab 5 - Anleitung]]

Ermöglicht das erstellen einer Arbeitsanleitung zu einem Produktionsschritt

==Diverses - Automatisches zuweisen von Objekten==

Ermöglicht das automatische Zuweisen von Objekten zu Angestellten. Eine Einschränkung auf einen bestimmten Objekttyp (Siehe Objekttypen) ist dabei möglich.

Je Arbeitschritt ist für jeden Angestellten ein Eintrag zu erstellen mit der Anzahl an Objekten welche maximal immer zugewiesen werden sollen.

Angestellte werden über den Suchkürzel ausgewählt.

[[File:Diveres.png|1000px|thumb|none|Tab 6 - Diverses]]

==Diverses - Vier Augen Prinzip==

Dies ist eine Qualitätssicherungsfunktion.

Sie ermöglicht das Sperren von Arbeitsschritten, bzw. unterbindet das öffnen von Objekten an diesen Schritten, in Abhängigkeit von bereits zuvor ausgeführten Arbeitschritten der gleichen Person am gleichen Objekt.

Damit kann gewährleistet werden, dass in einem Arbeitsprozess ein Objekt nicht an zwei unterschiedlichen Arbeitsschritten von einer einzigen Person bearbeitet werden kann.

Bsp.: Eine Person welche einen kontrollieren Schritt ausführt, darf an diesem Schritt keine Objekte kontrollieren, welche zuvor von ihr selbst an einem oder mehreren anderen Schritten erzeugt oder bearbeitet wurden.

Über das Dropdownmenü den gewünschten Arbeitsschritt wählen, bei welchem der Bearbeitungsverlauf von Objekten betrachtet werden soll. z.B.: 6 - Kontrolle

[[Datei:4ap_kontrolle.png]]

In der Checkboxliste darunter nun diejenigen Schritte auswählen, welche als Ausschlusskriterium gelten. z.B.: 4 - Scannen der Kleinbild-Dias..

[[Datei:4ap_checklist.png]]

Versucht nun eine Person, welche am Schritt 4 ein Dia gescannt hat, das zugehörige Objekte am Schritt 6 zu kontrollieren, erscheint eine Fehlermeldung und das öffnen des Objektes zur bearbeitung wird abgebrochen.

==Word==

[[File:word.png|1000px|thumb|none|Tab 7 - Word]]

[[Kategorie:Workflow]]

Filetest

2025-11-07T09:35:26Z

Silvan: 3554: Wiki für den neuen Filtest erstellt

;Mantiseinträge:
1526

1822
;Systemtyp:
18

==Beschreibung==
Besteht aus einem Serverjob OJOHZDOFiletest. Überprüft die Files auf ihre Richtigkeit. Das Ergebnis (0/1) kann in einem Attribut gespeichert werden. Falls ein Test fehlschlägt geht das Objekt zu zum roten Ausgang und im Fehlertext steht, welche Bedingung(en) nicht erfüllt wurde(n).

'''Grundsätzlich sind hier keine Formeln für die Werte möglich, mit Ausnahme:''' ''FileAnzahl''

===Konfiguration FileAnzahl===
Bei diesem Test werden die '''Dateien und Ordner''' im auf oberster Ebene im Objektordner gezählt. Die Dateien in (Unter-)Ordnern zählen nicht. Der Ordner 'Hilfsobjekte' zählt auch.

'''Zugriff auf Metadaten des Objektes, bzw. das einsetzen von Formel sind für diesen Test erlaubt.''' ''Das Metadatum ist wie üblich in eckigen Klammern zu nennen: [MetadatumMitAnzahl]''

===Konfiguration FileTyp===
Bei diesem Test wird jedes File im Objektordner mit konfigurierten Filetyp verglichen. Ordner werden (natürlich) nicht verglichen. Files in Unterordnern werden nur getestet, wenn 'Rekursiv' angekreuzt ist.

===Konfiguration BildformatXY===
Bei diesem Test können beide Seiten des Bildformats (X und Y) berücksichtigt werden.
*Operator Codes können sein (>, *>, >>, *>>) Bzw. die Varianten für kleiner (<) und gleich (=)
*>,= wenn eine Seite grösser/gleich als ihr entsprechender Maximalwert (xi > xs) | (yi > ys)
*>>,== wenn beide Seiten grösser / gleich wie der entsprechende Maximalwert (xi > xs) & (yi > ys)
* *>, *= wenn mindestens eine beliebige Seite grösser / gleich ist wie ein beliebiger Maximalwert
* *>>, *== wenn je beide Seiten grösser / gleich wie ein beliebiger Maximalwert sind (Bildausrichtung gleich oder gedreht)
Der Vergleichswert wird geschrieben: 2000x3000

===Konfiguration Farbraum===
Bei diesem Test wird der Farbraum aus dem File gelesen. Typische Werte sind 'Gray' oder 'sRGB'. Bitte achten Sie auf Grosskleinschreibung.

=== Konfiguration Positions SW Histogramm ===
Bei diesem Test wird ein Histogramm in einem PDF / Bild generiert basierend auf einer bestimmten Position sowie einem Grössenbereich.
Grundsätzlich wird immer von links oben aus gerechnet.<br>

1. Parameter = Seite - zB 4 (Wird nur bei PDF's verwendet)<br>
2. Parameter = Position X - zB 250 oder -150 (Bei Bildern in Pixel, bei PDF's in mm / Negative Zahlen werden von Rechts statt Links aus gerechnet)<br>
3. Parameter = Position Y - zB 300 oder - 200 (Bei Bildern in Pixel, bei PDF's in mm / Negative Zahlen werden von Unten statt Oben aus gerechnet)<br>
4. Parameter = Breite - zB 500 oder 25 % (Entweder Prozentangabe oder bei Bildern in Pixel, bei PDF's in mm)<br>
5. Parameter = Höhe - zB 200 oder 15 % (Entweder Prozentangabe oder bei Bildern in Pixel, bei PDF's in mm)<br>
6. Parameter = Helligkeitsgrenzwert - zB 150 (Werte von 0 - 255, wobei 0=Schwarz / 255 = Weiss)<br>
7. Parameter = Prozent - zB 35% (Wie viel Prozent der Pixel müssen über oder unter der angegeben Helligkeit sein)<br>
<br>
Hier ein komplettes Beispiel: "1,100,-150,140,5%,200,30%"<br>
*Es wird Seite 1 gemessen (falls es um ein PDF geht)
*Es wird der folgende Bildausschnitt genommen: Annahme das Bild ist 1000x500px gross
** Linke obere Ecke: 100/350 px. (350=500-150)
** Grösse des Ausschnitts: 140x25 px. (25=5% von 500)
** Rechte untere Ecke: 240/375 px.
*Es wird folgende Formel evaluiert:
(Pixelheller (als Grauwert 200) / TotaleAnzahlPixel) > oder < Prozent (30%).
Es werden also immer die helleren Pixel als der Helligkeitsgrenzwert gezählt und durch die totale Anzahl Pixel geteilt. Das Ergebnis wird mit dem Prozentsatz verglichen.
Falls ein Wert nicht angegeben werden soll muss das Komma dennoch da stehen. Beispiel ohne die Angabe der Seite: ",100,-150,140,5%,200,30%".<br>
==== Beispiele Bildausschnitt====
* Das ganze Bild (Seite 1) soll gemessen werden: "1,1,1,100%,100%..."
* Links oben in der Ecke soll ein Quadrat von 100px gemessen werden: "1,1,1,100,100..."
==== Beispiele Helligkeit====
* Es darf fast keine (fast) schwarzen Pixel haben: > "...20, 98%" -> mehr als 98% der Pixel sollen heller sein als fast schwarz (Grauwert 20)
* Es soll fast ganz weiss sein: > "...240, 99%" -> 99% der Pixel sollen heller als der Grauwert 240 sein (fast weiss)

=== Konfiguration Ist Extrem ===
Bei diesem Test wird jedes DO geprüft ob es nach der konfigurierten Weise extrem ist.

1. Parameter = Sortierfeld - Dieser Wert wird aufs "Extrem sein" geprüft. Muss ein AT-Name sein<br>
2. Parameter = Selektionsfeld - Es werden nur DOs berücksichtig die den gleichen Wert im Selektionsfeld haben wie das DO welches gerade angeschaut wird. Muss ein AT-Name sein. Falls leer wird DO_DO_SEQ automatisch verwendet.<br>
3. Parameter = Menge - Ab wann wird ein DO als Extrem beachtet? zB. 10<br>
<br>
Hier ein komplettes Beispiel: "seitenanzahl,pdfname,10"<br>
Ist das DO in den Top 10 mit den Seitenzahlen verglichen mit allen DOs welche denselben PDF Namen haben?

===Konfiguration Pixeltiefe pro Kanal===
Bei diesem Test wird die Anzahl Pixel pro Kanal aus dem File gelesen. Typische Werte sind 8 oder 16.

===Konfiguration ICC Profile===
Bei diesem Test wird aus dem File die Zeile icc:description gefiltert und der Text danach herausgelesen. Ein typischer Wert ist 'Adobe RGB (1998)'.

Sie können das Feld bei einem Bild auch auslesen:
identify -verbose "Pfad zum Bild"
Suchen Sie nach der Zeile 'icc:description'

===Dateigrösse===

Bei diesem Test wird eine Dateigrösse in Bytes geprüft.

Operator Codes können sein (>,<).

===SeitenAnzahl===

Bei diese Test wird die Anzahl Seiten in einem PDF oder TIFF Dokument geprüft.

Operator Codes können sein (>,<,=,<>).

===Anzahl Barcodes in Ordner===

Bei diesem Test wir die Anzahl Barcodes eines bestimmten Typs mit einem bestimmten Wert im gesamten Ordner getestet.

Operator Codes können sein (>,<,=,<>,<=, >=).

Wertkonfiguration: Anzahl Barcodes,Barcodewert,Barcodetyp

Beispiel: 2,ABC1234,Code 39

===Konfiguration Pixeltiefe pro Kanal===
Bei diesem Test wird die Anzahl Pixel pro Kanal aus dem File gelesen. Typische Werte sind 8 oder 16.

==Allgemeine Metadaten von Bildformaten==

Für die unten folgenden Konfigurationen kann für die gesuchten Werte auf diese Auflistungen von TAG Namen zurückgegriffen werden:

[https://www.exiftool.org/TagNames/ TAG Übersicht]

[https://www.exiftool.org/TagNames/EXIF.html EXIF Tags]

[https://www.exiftool.org/TagNames/IPTC.html IPTC Tags]

[https://www.exiftool.org/TagNames/XMP.html XMP Tags]

'''Suche nach leeren Tags'''

Falls nach leeren, bzw. fehlenden Werten gesucht werden soll, dann ist der Wertebereicht nach dem Komma leer zu lassen.

Bsp.: Kein Änderungsdatum vorhanden

[[Datei:Metadatum Datum leer.png]]

===Konfiguration Metadatum Text===

Bei diesem Test wird ein TAG mit Textinhalt verglichen.

Operator Codes können sein (=, <>)

Bsp.: Gesucht wird der Hersteller des Aufnahmegerätes. Der entsprechende TAG heisst 'Make'. Der gesuchte Wert soll auf 'Canon' lauten.

[[Datei:Metadatum Text.png]]

===Konfiguration Metadatum Zahl===

Bei diesem Test wird ein TAG mit Zahleninhalt verglichen.

Operator Codes können sein (=, <>, >, >=, <, <=)

Bsp.: Gesucht wird nach der X Auflösung des Bildes. Der entsprechende TAG heisst 'XResolution'. Der gesuchte Wert soll grösser oder gleich 3500 sein.

[[Datei:Metadatum Zahl.png]]

===Konfiguration Metadatum Datum===

Bei diesem Test wird ein TAG mit Datumsinhalt verglichen.

Operator Codes können sein (=, <>, >, >=, <, <=)

Bsp.: Gesucht wird dem Änderungsdatum. Der entsprechende TAG heisst 'DateModify'. Der gesuchte Wert soll nach dem 23.03.2021 08:05:14 liegen.

[[Datei:Metadatum Datum.png]]

==Dateien auch in den Unterordnern prüfen==

Soll auch in Unterordner geprüft werden, ist folgende Checkbox zu aktivieren:

[[File:filetest_rekursiv.png]]

Der Filetest beim Abschliessen eines clientseitigen Arbeitsschrittes ist nicht rekursiv.

== Dateinamen auf Regex überprüfen ==
Sie können den Dateinamen mithilfe eines Regex überprüfen lassen.
Wählen Sie dazu die Kondition "Dateiname" und den Operator "entspricht Regex", dann '''muss jedes File''' im Objektordner dem Regex entsprechen.
Wenn Sie "entspricht nicht Regex" wählen, dann '''darf kein File''' dem Regex entsprechen.

Tool um Regex zu schreiben: https://regex101.com

[[Datei:Filetest regexmatching.png|500px]]

==Barcodes finden==

Ermittelt, ob die Seiten einen Barcode besitzen. Ein bestimmer Suchwert für den Inhalt des Barcodes kann ebenfalls als Einschränkung mitgegeben werden.

Kann alle Seiten, oder nur die geraden, oder nur die ungeraden prüfen. Wenn wir hier von Seiten sprechen, dann sind damit einzelne Dateien gemeint, welche in der Regel eine einzelne Seite darstellen. Die Reihenfolge der nach Namen sortierten Dateien im Dateisystem legt dabei die Seitenzahl fest. Die erste Datei - Sortiernummer 1 - entspricht demnach einer ungeraden Seite. Datei achte Datei - Sortiernummer 8 - einer geraden Seite.

Unterstüzte Dateitypen - alle gängigen Bildformate.

'''Attribut:''' SeiteHatBarcodes

'''Operator Code:''' ( = )

'''Wert:''' A/U/G/[Zahl]''','''Barcodeinhalt,Barcodetyp

*A = alle Seiten (es muss auf allen Seiten einen Barcode haben)
*U = ungerade Seiten (es darf nur auf ungeraden Seiten barcodes haben. Es muss aber nicht auf allen ungeraden Seiten Barcodes haben)
*G = gerade Seiten (es darf nur auf geraden Seiten barcodes haben. Es muss aber nicht auf allen geraden Seiten Barcodes haben)
*[Zahl] = zB. 5 => Hat es auf der 5. Seite einen Barcode?

'''Bsp.:'''

1) Suche auf ungeraden Seiten nach einem Barcode: '''Wert = 1'''

2) Suche auf geraden Seiten (2) nach einem Barcode mit dem Wert 0783A-123: '''Wert = 2,0783A-123'''

'''Merke:''' Die Suche nach einem Wert funktioniert aktuell nur für den ersten gefundenen Barcode! Wenn es mehrere Barcodes auf der Seite gibt, wird jeweils der erste Ausgewertet.

Falls eine Zahl angegeben wird, kann der Barcodetyp definiert werden. In der anderen Fällen ist der Parameter nicht implementiert. Ebenfalls kann der Wert ein Regex sein, sofern eine Zahl definiert ist.

==Unsichtbare Dateien==
File test prüft auch unsichtbare/geschützte Systemdateien wie Thumps.db. Dies ist Absicht, damit verhindert werden kann, dass diese Dateien weiter im Workflow gehen. Damit Sie die unsichtbaren/geschützen Systemdateien sehen (und ggf. löschen) können, müssen Sie sie in Windows sichtbar machen:
* Für geschützte Systemdateien: Deselektieren Sie 'Ordneroptionen: Ansicht: Erweiterte Einstellungen: Geschützte Systemdateien ausblenden'
* Für unsichtbare Dateien: Im Befehlsband: 'Ansicht', 'unsichtbare Dateien'

==Essentielle Felder==
AR_FILETEST, HZ_FILETEST ''Code kTab Attribut kTab Operator kTab Wert(e) kCR''

HZ_TESTERGEBNIS

HZ_FILEVERHALTEN

==Pane im Produktionsauftrag (FHK_Maske)==

[[File:0.jpg]]

[[Kategorie:Workflowschritt]]

Generische Produktionsauftragsauswertung

2025-10-29T09:15:28Z

Silvan: 3491: Doku für Blatt 8

;Mantiseinträge:
3155

==Beschreibung==
Die generische Produktionsauftragsauswertung ist eine Excelauswertung mit vielen Informationen über verarbeitete Stückzahlen, Arbeitsstunden, Angestellte und weiteres. Diese Auswertung kann für jeden Produktionsauftrag in einer beliebigen Zeitspanne generiert werden. Navigieren Sie dazu in die Produktionsauftragsmaske, wählen Sie einen Produktionsauftrag aus und klicken Sie auf den Button "Auswertung generieren". Dabei können Sie aus 2 verschiedenen Modi auswählen. Modus 1 wertet alle Objekte in einem Datumsbereich aus, wobei Modus 2 alle Objekte einer Tranche auswertet.

==Arbeitsblätter==
Die Arbeitsblätter der Vorlage sind nicht fix definiert. Folgende anpassen können in der Vorlage getätigt werden:
- Namen der Blätter kann angepasst werden
- Platzhalten können beliebig verschoben werden (es kann auch mehrmals den gleichen Platzhalter im Dokument haben)
- Blätter können gelöscht werden
- Die Reihenfolge der Arbeitsblätter kann verändert werden

Sie dürfen beliebig viele Datums oder Tranchennamen Platzhalter einfügen. Beachten Sie, dass wenn die Auswertung im Datums Modus ausgeführt wird der Tranchenname Platzhalter durch eine Fehlermeldung ersetzt wird und umgekehrt.<br>
$DATUM$ wir ersetzt durch "Auswertung vom 21.05.2023 bis 18.09.2023"<br>
$TRANCHENAME$ wird ersetzt durch "Auswertung der Tranche 'Tranche XY'"

==Checkliste für reibungslosen Ablauf==
* Für Blatt 3 müssen passende Umfänge, Kategorien und Formate definiert sein. Mehr dazu [[Formate definieren|hier]]
* Für Blatt 5 sollten alle Angestellten welche an diesem Auftrag arbeiten einen aktiven Vertrag haben

==Blatt 1 - Objektanzahlen==
Auf diesem Blatt werden die Anzahl Objekte, aufgeschlüsselt nach Objekttyp, welche in der Periode am jeweiligen Arbeitsschritt verarbeitet wurden, aufgelistet. Dabei werden Objekte welche mehrmals am gleichen Arbeitsschritt verarbeitet wurden nicht mitgezählt. Jedes Objekt wird also pro Arbeitsschritt nur einmal gezählt.

==Blatt 2 - Objekt / Seitenanzahlen==
Dieses Blatt dient als weitere Aufschlüsselung der Zahlen auf dem Blatt 1. Folgende Informationen befinden sich auf Blatt 2: Arbeitsschritt, Maschine, Anzahl Objekte Einmalig, Anzahl Objekte Durchlauf, Anzahl Objekte Doppelt, Anzahl Seiten Einmalig, Anzahl Seiten Durchlauf, Anzahl Seiten Doppelt. Grundsätzlich wenden alle Arbeitsschritte welche keine manuellen Leistungen haben auf diesem Blatt ignoriert. Alle anderen Arbeitsschritte welche mindestens ein verarbeitetes Objekt in der Periode aufweisen, werden aufgelistet.

===Informationen zu den Seitenanzahlen===
Die Anzahl der Seiten von Objekten wird aus einer materialisierten Sicht gelesen. Diese wird nur einmal täglich aktualisiert. Falls Sie also ganz genaue Zahlen wünschen, setzen Sie das Ende der Periode auf gestern. Es wird die Anzahl verrechenbarer Seiten angezeigt; Diese Anzahl stimmt nicht mit den Seitenzahlen aus den Leistungen überein. Wenn eine Seite 3 mal gescannt wird, weil die ersten 2 Versuche ungenügend waren, erhalten wir nur 1 verrechenbare Seite jedoch wird in der Leistung 3 Seiten abgespeichert. Die Seitenanzahlen werden beim Arbeitsschritt [[Files messen|Files Messen]] gemessen. Alle Objekte welche noch nicht gemessen wurden, zeigen sich nicht in den Kennzahlen der Seiten.

===Beschreibungen der Kennzahlen===
'''Maschine'''<br>
An welcher Maschine dieser Arbeitsschritt stattfindet. Achtung: Wenn der Maschinentyp des Arbeitsschritts verändert wird, erscheint es rückwirkend so als ob alle Objekte an der neuen Maschine verarbeitet wurden.
<br>
'''Anzahl Objekte Einmalig'''<br>
Die Anzahl Objekte welche in der Periode einmalig verarbeitet wurden. Falls ein Objekt mehrmals am gleichen Schritt verarbeitet wurde wird dies hier nicht gezählt.
<br>
'''Anzahl Objekte Durchlauf'''<br>
Die Anzahl Objekte welche in der Periode allgemein an diesem Arbeitsschritt verarbeitet wurden. Dabei werden alle Duplikate gezählt.
<br>
'''Anzahl Objekte Doppelt'''<br>
Dies ist die Zahl der einmalig verarbeiten Objekte welche vor der Periode bereits einmal an diesem Schritt verarbeitet wurden. Dabei werden keine Duplikate gezählt; d. H. wenn das Objekt X vor der Periode schon 8 mal an diesem Schritt war, zählt dies jedoch nur als 1 doppeltes Objekt.
<br>
'''Anzahl Seiten Einmalig'''<br>
Anzahl Seiten welche an diesem Arbeitsschritt verarbeitet wurden. Falls ein Objekt mehrmals am gleichen Schritt verarbeitet wird, werden die Seiten hier nicht doppelt gezählt.
<br>
'''Anzahl Seiten Durchlauf'''<br>
Anzahl Seiten welche in der Periode an diesem Arbeitsschritt verarbeitet wurden. Dabei werden alle Duplikate gezählt. Achtung: Die Auswertung weiss nicht wie viele Seiten wirklich doppelt verarbeitet wurden. Sie multipliziert die Anzahl Seiten des Objektes mit der Anzahl der Durchläufe. Beispiel: Ein Objekt mit 50 Seiten wird 3 mal am Arbeitsschritt XY verarbeitet. Anzahl Seiten Einmalig = 50, Anzahl Seiten Durchlauf = 150. Auch wenn der Angestellte beim 3. Durchlauf nur 15 Seiten bearbeitet hat.
<br>
'''Anzahl Seiten Doppelt'''<br>
Anzahl Seiten welche vor der aktuellen Periode bereits verarbeitet wurden. Dabei werden keine Duplikate gezählt.

==Blatt 3 - Formate / Umfänge / Kategorien==
Auf diesem Blatt werden die Anzahl verarbeite Objekte basierend auf den Konfigurierten Formaten, Umfängen und Kategorien, aufgeschlüsselt nach Objekttyp, gelistet. Dabei wird jedes Objekt nur einmal gezählt und alle Duplikate von mehrfacher Verarbeitung ignoriert. Achtung: Auf diesem Blatt sind die Totalanzahlen dargestellt und nicht die verarbeiteten Objekte in der Periode!

==Blatt 4 - Leistungen (h)==
Auf diesen Arbeitsblatt werden die Anzahl Stunden aus den Leistungen pro Arbeitsschritt und Objekttyp aufgelistet.

==Blatt 5 - Leistungen Angestellte==
Auf diesen Arbeitsblatt werden die Leistungen der Angestellten genauer aufgeschlüsselt. Folgende Kennzahlen befinden sich auf diesem Blatt: Arbeitsschritt, Objekttyp, Angestellter, Vertragsart, Stunden Total, Anzahl Objekte, Ø Zeit Objekt (h), Anzahl Seiten gemessen, Ø Zeit pro Seite gemessen (h), Geschätzte Dauer pro Objekt (h), Kalkulatorische Kosten. Werte welche undefiniert sind werden mit N/A angegeben. Achten Sie darauf das alle Angestellte einen gültigen laufenden Vertrag haben. Ansonsten können einige Zahlen nicht berechnet werden.
<br>
'''Stunden Total (h)'''<br>
Anzahl Stunden welche der Angestellte an diesem Arbeitsschritt in der Periode gearbeitet hat.
<br>
'''Anzahl Objekte'''<br>
Die Anzahl der Objekte welche der Angestellte an diesem Arbeitsschritt in der Periode verarbeitet hat.
<br>
'''Ø Zeit Objekt (h)'''<br>
Die durchschnittliche Verarbeitungszeit für ein Objekt
<br>
'''Anzahl Seiten gemessen'''<br>
Die Anzahl der gemessenen Seiten aller Objekte welcher der Angestellte verarbeitet hat. Die Messung der Seiten erfolgt beim [[Files messen|Files Messen]]; Falls ein File in mehrere Typen konvertiert wird erscheinen die in dieser Auswertung obwohl der Angestellte nur 1 Seite gescannt hat. Beispiel: Der Angestellte scannt eine Seite (.tif). Danach wird daraus ein PDF, ein JPG und ein PNG generiert und am Schluss wird das Objekt gemessen. Es erscheinen dann 4 Seiten in der Auswertung, obwohl der Angestellte nur eine Seite gescannt hat.
<br>
'''Ø Zeit pro Seite gemessen (h)'''<br>
Die durchschnittliche Verarbeitungszeit pro Seite. Diese Zahl berechnet sich mit Stunden Total / Anzahl Seiten gemessen d.h. sollte der Angestellte 60 Seiten gescannt haben und davon 30 doppelt, merken wir das nicht. Ø Zeit pro Seite gemessen (h) kann in machen Fällen grösser sein als Ø Zeit Objekt (h). Dies geschieht wenn Objekte noch nicht gemessen wurden und deswegen 0 Seiten haben.
<br>
'''Geschätzte Dauer pro Objekt (h)'''<br>
Die geschätzte Dauer pro Objekt aus der Auftragsplanung.
<br>
'''Kalkulatorische Kosten'''<br>
Die kalkulatorischen Kosten der betriebenen Arbeit des Angestellten in der Periode. Der Stundensatz ist in der Vertragsart definiert.

==Blatt 6 - Maschinenstunden==
Auf diesem Arbeitsblatt wird die Anzahl der gearbeiteten Stunden pro Angestellter und Maschine aufgelistet.

==Blatt 8 - Generisch zur Verrechnung==
Auf diesem Blatt lassen sich Metadaten und Leistungen von DOs anzeigen. Wichtig: Es werden nur DOs beachtet welche zur Verrechnung bereitstehen. Das bedeutet die DOs müssen am Arbeitsschritt "Letzter Arbeitsschritt" (DY_HZ_SEQ2) verarbeitet worden sein. Dieser lässt sich in der Produktionauftragsmaske unter Objekttypen konfigurieren. Auch im Tranchenmodus werden nur DOs welche zu verrechnen sind aufgelistet.

===Platzhalter===
Um das Blatt als diesen Typ zu definieren muss irgendwo $ATGENERISCH$ stehen. Dieser Platzhalter wird in der fertigen Auswertung dann gelöscht. Folgende Platzhalter können auf diesem Blatt verwendet werden:

====$START('[Objekttyp]')$====
Dieser Platzhalter markiert den Start der Auswertung. Das heisst 1 Zeile unter diesem Platzhalter startet die Liste der DO-Informationen. Damit wird ebenfalls definiert, welcher Objekttyp in der Auswertung angezeigt werden soll.

Beispiel: $START('Buch')$

====$DOMetawert('[MetadatumName]')$====
Dieser Platzhalter zeigt einen Wert eines beliebigen Metadatums des DO an.

Beispiel: $DOMetawert('Hausnummer')$ -> wird dann zu zB. 58A

====$DOLSstd(row('Arbeitsvertragstyp'))$====
Dieser Platzhalter zeigt den Wert aller gearbeiteter Stunden dieses DO von einer oder mehreren Arbeitsvertragsarten.

Beispiel: $DOLSstd(row('MOR'))$ -> wird dann zu zB. 1.456

Es können auch mehere Vertragsarten summiert werden.

Beispiel: $DOLSstd(row('MOR','MMR','ZIVI'))

====Weitere Platzhalter====
$DOSEQ$ -> Sequenzschlüssel des DO

$DOSIGNATUR$-> Signatur des DO

Normaler Arbeitsschritt

2025-10-13T09:46:15Z

Silvan: 3537: HZ_HASTYP zu HZ_FILEVERHALTEN geändert

;Mantiseinträge:
2237
;Systemtyp:
0

==Beschreibung==
Dieser Arbeitsschritt wird zB fürs Digitalisieren oder andere manuelle Tätigkeiten an Files verwendet. Er legt die Daten des vorherigen Arbeitschrittes eines Objektes in C:\Work\Input und erwartet die Daten nach der manuellen Bearbeitung in C:\Work\Output.
===Digitalisieren===
Digitalisieren Sie alles in C:\Work\Output.
===Manuelle Bearbeitung von Files===

===Leistungen===
Beim Starten des Schrittes wird Name und Änderungsdatum der Files im Ordner C:\Work\Output in einer Liste gespeichert. Am Beenden wird die Liste mit dem dann aktuellen Inhalt verglichen. Es können folgenden Leistungen vorkommen:
;Datei, Create: Eine Datei mit diesem Namen existierte beim Start noch nicht.
;Datei, Update: Eine Datei mit diesem Namen existierte beim Start schon, hat am Ende aber ein anderes Änderungsdatum.
;Datei, Delete: Eine Datei mit diesem Namen existierte beim Start, fehlt aber am Ende.
;Sonderobjekte: Ein Sonderobjekt wurde erstellt.

=Konfiguration=

* Generell

* File Test, Die Filetests sind hier nicht rekursiv. Es werden nur die Files auf der obersten Ebene im Arbeitsordner kontrolliert. Die Filetests können bei "Feierabend" ausgestellt werden.

* Metadaten

* Ausgänge: Ermöglicht das Einrichten zusätzlicher Ausgänge für nachfolgende Arbeitsschritte

* Ausgang für hier erstellte Sonderobjekte: Sonderobjekte im Fenster Typ0 (nicht Typ0abc), die an diesem Schritt erstellt werden, nehmen nicht einen der im Workflow konfigurierten Ausgänge. Sie werden zu dem Schritt geleitet, den Sie im Fenster Produktionsauftrage im Register Produktionsschritte (unten rechts) eingeben können: '''Arbeitschritt für Sonderobjekte'''.

* Serien Nr. Scanner: Schreibt die Seriennummer eines Scanners in die Bilddatei. Ermöglicht die zwingende Angabe der Seriennummer eines verwendeten Eingabegerätes / Scanners beim starten des Arbeitsfensters.

==Einstellungsfenster==

[[File:FHZ_STyp000_1.png]]

===Serien Nr. Scanner===

Verlangt die Eingabe des Namens eines EXIF Feldes. '''Wenn dieses Feld hier gefüllt wurde, dann muss bei dem Arbeitsschritt beim starten zwingend eine Seriennummer angegeben werden.'''
Ohne die Eingabe einer gültigen Seriennummer wird das Arbeitsfenster nicht laufen.

Das EXIF Standard Feld für die Seriennummer lautet: '''SerialNumber'''

Die Seriennummern der Scanner werden beim beenden der Arbeit automatisch in alle Bilddateien geschrieben, bei welchen nicht bereits eine Seriennummer in dem angegebenen EXIF Feld enthalten ist.

'''Validierung der Geräteseriennummern'''

Es werden nur Seriennummer akzeptiert, welche entweder:

*in der Liste unterhalb erfasst wurden (Die Seriennummern sind Zeilenweise (Zeilenumbruch) zu trennen!)
*in den Anlagen erfasst, mit einer Maschine verknüpft, einem Maschinentyp zugeordnet und dieser Maschinentyp beim Arbeitsschritt unter "benötigter Maschinentyp" konfiguriert wurde.

[[File:FHZ_STyp000_snc.png]]

==Digitalisierungssoftware==

Ermöglicht die Angabe einer für den Job zum Einsatz kommenden Digitalisierungsoftware und ggf. von spezifischen Software Voreinstellungen.

Die Auswahl der benötigten Software über das Dropdown Menu lädt die dazugehörenden Einstellungsmöglichkeiten.

'''Die Checkbox "Bearbeitung ohne Digitalsierungssoftware erlauben" erlaubt den Start des Arbeitsfensters auch für den Fall, dass auf dem Arbeitsplatz PC die konfigurierte Software nicht verfügbar ist.'''

===Software: Tocosa===

=====Jobkonfiguration über job.ini=====

Wird der Pfad zu einer zuvor in Tocosa vorbereiteten Job.ini Konfigurationsdatei angegeben, dann öffnet sich die Tocosa Applikation beim starten eines Auftragsobjektes mit den entsprechenden Job Einstellungen.

Die job.ini Datei kann im gewählten Ablageordner von solchen ini Dateien beliebig benannt werden, z.B. '''meinScanJobNr15.ini'''.

Der Dateipfad bei der Einstellung "Pfad zur Jobkonfig." muss immer vollständig, inklusive Dateiname, angegeben werden. E.g. '''O:\ordner\unterordner\job.ini''' oder '''O:\ordner\unterordner\meinScanJobNr15.ini'''

====Tocosa Grundeinstellungen über Tocosa7.ini====

Unabhängig von den Job Einstellungen, können die Grundeinstellungen von Tocosa, welche in der Datei Tocosa7.ini gespeichert sind, geändert werden.

Diese Datei findet sich unter C:\ProgramData\Business Graphics\Tocosa\Tocosa7.ini und sie wird mit den hier gemachten Einstellungen aktualisiert. Sollte dieser Pfad sich in einer zukünftigen Tocosa Version ändern, dann muss der Helper von der Profile dafür angepasst werden.

In der Tocosa7.ini finden sich Konfigurationsblöcke, deren Namen mit eckigen Klammern umfasst sind. Darunter finden sich die Schlüssel mit ihren Werten.

[Settings]
LanguageFile=C:\Program Files\Tocosa\Language7.lan
ShowOnScreenKeyboard=1
WriteProtocol=0
ThumbWidthOffset=196

Um einen Wert zu überschreiben, muss eine entsprechende Zeile dafür in das Textfeld eingegeben werden.

Die Formatierung für eine Zeile ist: <br>
'''Konfigurationsblock''':''Schlüssel''=Wert

Settings:WriteProtocol=1
Settings:ThumbWidthOffset=250

''Konfigurationsbeispiel in der Einstellungsmaske''

[[Datei: Digitalisierungssoftware.png]]

==Essentielle Felder==
HZ_TESTERGEBNISS Metadaten- Tagname um Entscheidung zu speichern.

HZ_DY_SEQ Sonder- und Kinderobjekte: Typen, welche bei der Einstellung zugelassen sind. Zu den hier angegebenen Attributstypen können Sonder- oder Kinderobjekte erstellt werden. Wenn leer, keine Sonderobjekterstellung möglich.

HZ_METAWERTFELD Sonder- und Kinderobjekte: Formel zur Berechnung der Signatur für Kindesobjekte. Leer lassen, wenn der Name / die Signatur manuell eingegeben werden muss.

HZ_XMPSCHEMANAME Name des EXIF Feldes der Bilddatei, in welche die Seriennummer des Eingabegerätes / Scanners geschrieben werden soll

HZ_BARCODEWERT Valide Seriennummern von Eingabegeräten, welche beim start des Arbeitsfenster eingegeben werden müssen und über diese Einträge hier validiert werden.

HZ_FORMEL Hält den Checkboxstatus der anzuzeigenden Metadaten durch speichern der zugehörigen AT_SEQ (YES:2454, NO:2455, ...)

HZ_FILEVERHALTEN Sollen Filetests bei Feierabend ausgeführt werden?

=Zugehörige Eingabemasken / Fenstertypen=

Aktuell sind vier Fenstermasken / Untersystemtyp für einen Digitalisierungsarbeitschritt konfigurierbar.

;FDO_SHZTyp0 - Standardfenster mit Eingabe von Metadaten und Sonderobjekterzeugung zum Bearbeiteten Hauptobjekt

[[File:FDO_SHZTyp0.png]]

;FDO_SHZTyp0a - Wie Typ0, jedoch zusätzlich mit Dateierzeugung zu den Sonderobjekten

[[File:FDO_SHZTyp0a.png]]

;FDO_SHZTyp0b - Wie Typ0a, jedoch zusätzlich mit Datei- und Unterordnererzeugung zu den Sonderobjekten

[[File:FDO_SHZTyp0b.png]]

;FDO_SHZTyp0c - Zur Erstellung von Kindsobjekten mit Metadaten und Dateien. Das Hauptobjekt (Vater) kann nicht bearbeitet werden.

'''HZ Konfiguration: Die Daten dürfen nicht auf dem Server gespeichert werden! '''

Zeigt die Metadaten des Hauptobjektes im oberen Teil an. Diese können nicht verändert werden.

Wenn für Kindesobjekte der Typ angegeben wurde, wird "Unterobjekte erzeugen" angezeigt. Die verfügbaren Typen finden sich im Dropdown Menu "Typ".

Befinden sich zum Zeitpunkt der Erstellung eines Kindobjektes Dateien im Ordner c:\work\output, dann werden diese dem Kindobjekt zugeordnet und auf den Server kopiert.

Alle Kinder des Hauptobjektes werden in der untersten Liste angezeigt.

Die Signatur des Kindobjektes kann im Einstellungsfenster vorgegeben werden. Das Eingabefeld wird dann zu einem Anzeigefeld und kann nicht mehr überschrieben werden.

Sie können die üblichen [[Omnisgrundlagen|Omnis-Funktionen]] benutzen. Das Feld kennt die Variable 'Zähler', welche ein automatisches hochzählen ermöglich.

Auf die Signatur des Vaterobjektes kann nicht zugegriffen werden. Der Name für die Signatur muss hier festgelegt werden.

con('MeineSignatur',[Zähler])

[[File:FDO_SHZTyp0c.png]]

[[Kategorie:Workflowschritt]]

Normaler Arbeitsschritt

2025-09-29T07:43:44Z

Silvan: 3537: Keine Filtests bei Feierabend ausführen

;Mantiseinträge:
2237
;Systemtyp:
0

==Beschreibung==
Dieser Arbeitsschritt wird zB fürs Digitalisieren oder andere manuelle Tätigkeiten an Files verwendet. Er legt die Daten des vorherigen Arbeitschrittes eines Objektes in C:\Work\Input und erwartet die Daten nach der manuellen Bearbeitung in C:\Work\Output.
===Digitalisieren===
Digitalisieren Sie alles in C:\Work\Output.
===Manuelle Bearbeitung von Files===

===Leistungen===
Beim Starten des Schrittes wird Name und Änderungsdatum der Files im Ordner C:\Work\Output in einer Liste gespeichert. Am Beenden wird die Liste mit dem dann aktuellen Inhalt verglichen. Es können folgenden Leistungen vorkommen:
;Datei, Create: Eine Datei mit diesem Namen existierte beim Start noch nicht.
;Datei, Update: Eine Datei mit diesem Namen existierte beim Start schon, hat am Ende aber ein anderes Änderungsdatum.
;Datei, Delete: Eine Datei mit diesem Namen existierte beim Start, fehlt aber am Ende.
;Sonderobjekte: Ein Sonderobjekt wurde erstellt.

=Konfiguration=

* Generell

* File Test, Die Filetests sind hier nicht rekursiv. Es werden nur die Files auf der obersten Ebene im Arbeitsordner kontrolliert. Die Filetests können bei "Feierabend" ausgestellt werden.

* Metadaten

* Ausgänge: Ermöglicht das Einrichten zusätzlicher Ausgänge für nachfolgende Arbeitsschritte

* Ausgang für hier erstellte Sonderobjekte: Sonderobjekte im Fenster Typ0 (nicht Typ0abc), die an diesem Schritt erstellt werden, nehmen nicht einen der im Workflow konfigurierten Ausgänge. Sie werden zu dem Schritt geleitet, den Sie im Fenster Produktionsauftrage im Register Produktionsschritte (unten rechts) eingeben können: '''Arbeitschritt für Sonderobjekte'''.

* Serien Nr. Scanner: Schreibt die Seriennummer eines Scanners in die Bilddatei. Ermöglicht die zwingende Angabe der Seriennummer eines verwendeten Eingabegerätes / Scanners beim starten des Arbeitsfensters.

==Einstellungsfenster==

[[File:FHZ_STyp000_1.png]]

===Serien Nr. Scanner===

Verlangt die Eingabe des Namens eines EXIF Feldes. '''Wenn dieses Feld hier gefüllt wurde, dann muss bei dem Arbeitsschritt beim starten zwingend eine Seriennummer angegeben werden.'''
Ohne die Eingabe einer gültigen Seriennummer wird das Arbeitsfenster nicht laufen.

Das EXIF Standard Feld für die Seriennummer lautet: '''SerialNumber'''

Die Seriennummern der Scanner werden beim beenden der Arbeit automatisch in alle Bilddateien geschrieben, bei welchen nicht bereits eine Seriennummer in dem angegebenen EXIF Feld enthalten ist.

'''Validierung der Geräteseriennummern'''

Es werden nur Seriennummer akzeptiert, welche entweder:

*in der Liste unterhalb erfasst wurden (Die Seriennummern sind Zeilenweise (Zeilenumbruch) zu trennen!)
*in den Anlagen erfasst, mit einer Maschine verknüpft, einem Maschinentyp zugeordnet und dieser Maschinentyp beim Arbeitsschritt unter "benötigter Maschinentyp" konfiguriert wurde.

[[File:FHZ_STyp000_snc.png]]

==Digitalisierungssoftware==

Ermöglicht die Angabe einer für den Job zum Einsatz kommenden Digitalisierungsoftware und ggf. von spezifischen Software Voreinstellungen.

Die Auswahl der benötigten Software über das Dropdown Menu lädt die dazugehörenden Einstellungsmöglichkeiten.

'''Die Checkbox "Bearbeitung ohne Digitalsierungssoftware erlauben" erlaubt den Start des Arbeitsfensters auch für den Fall, dass auf dem Arbeitsplatz PC die konfigurierte Software nicht verfügbar ist.'''

===Software: Tocosa===

=====Jobkonfiguration über job.ini=====

Wird der Pfad zu einer zuvor in Tocosa vorbereiteten Job.ini Konfigurationsdatei angegeben, dann öffnet sich die Tocosa Applikation beim starten eines Auftragsobjektes mit den entsprechenden Job Einstellungen.

Die job.ini Datei kann im gewählten Ablageordner von solchen ini Dateien beliebig benannt werden, z.B. '''meinScanJobNr15.ini'''.

Der Dateipfad bei der Einstellung "Pfad zur Jobkonfig." muss immer vollständig, inklusive Dateiname, angegeben werden. E.g. '''O:\ordner\unterordner\job.ini''' oder '''O:\ordner\unterordner\meinScanJobNr15.ini'''

====Tocosa Grundeinstellungen über Tocosa7.ini====

Unabhängig von den Job Einstellungen, können die Grundeinstellungen von Tocosa, welche in der Datei Tocosa7.ini gespeichert sind, geändert werden.

Diese Datei findet sich unter C:\ProgramData\Business Graphics\Tocosa\Tocosa7.ini und sie wird mit den hier gemachten Einstellungen aktualisiert. Sollte dieser Pfad sich in einer zukünftigen Tocosa Version ändern, dann muss der Helper von der Profile dafür angepasst werden.

In der Tocosa7.ini finden sich Konfigurationsblöcke, deren Namen mit eckigen Klammern umfasst sind. Darunter finden sich die Schlüssel mit ihren Werten.

[Settings]
LanguageFile=C:\Program Files\Tocosa\Language7.lan
ShowOnScreenKeyboard=1
WriteProtocol=0
ThumbWidthOffset=196

Um einen Wert zu überschreiben, muss eine entsprechende Zeile dafür in das Textfeld eingegeben werden.

Die Formatierung für eine Zeile ist: <br>
'''Konfigurationsblock''':''Schlüssel''=Wert

Settings:WriteProtocol=1
Settings:ThumbWidthOffset=250

''Konfigurationsbeispiel in der Einstellungsmaske''

[[Datei: Digitalisierungssoftware.png]]

==Essentielle Felder==
HZ_TESTERGEBNISS Metadaten- Tagname um Entscheidung zu speichern.

HZ_DY_SEQ Sonder- und Kinderobjekte: Typen, welche bei der Einstellung zugelassen sind. Zu den hier angegebenen Attributstypen können Sonder- oder Kinderobjekte erstellt werden. Wenn leer, keine Sonderobjekterstellung möglich.

HZ_METAWERTFELD Sonder- und Kinderobjekte: Formel zur Berechnung der Signatur für Kindesobjekte. Leer lassen, wenn der Name / die Signatur manuell eingegeben werden muss.

HZ_XMPSCHEMANAME Name des EXIF Feldes der Bilddatei, in welche die Seriennummer des Eingabegerätes / Scanners geschrieben werden soll

HZ_BARCODEWERT Valide Seriennummern von Eingabegeräten, welche beim start des Arbeitsfenster eingegeben werden müssen und über diese Einträge hier validiert werden.

HZ_FORMEL Hält den Checkboxstatus der anzuzeigenden Metadaten durch speichern der zugehörigen AT_SEQ (YES:2454, NO:2455, ...)

HZ_HASHTYP Sollen Filetests bei Feierabend ausgeführt werden?

=Zugehörige Eingabemasken / Fenstertypen=

Aktuell sind vier Fenstermasken / Untersystemtyp für einen Digitalisierungsarbeitschritt konfigurierbar.

;FDO_SHZTyp0 - Standardfenster mit Eingabe von Metadaten und Sonderobjekterzeugung zum Bearbeiteten Hauptobjekt

[[File:FDO_SHZTyp0.png]]

;FDO_SHZTyp0a - Wie Typ0, jedoch zusätzlich mit Dateierzeugung zu den Sonderobjekten

[[File:FDO_SHZTyp0a.png]]

;FDO_SHZTyp0b - Wie Typ0a, jedoch zusätzlich mit Datei- und Unterordnererzeugung zu den Sonderobjekten

[[File:FDO_SHZTyp0b.png]]

;FDO_SHZTyp0c - Zur Erstellung von Kindsobjekten mit Metadaten und Dateien. Das Hauptobjekt (Vater) kann nicht bearbeitet werden.

'''HZ Konfiguration: Die Daten dürfen nicht auf dem Server gespeichert werden! '''

Zeigt die Metadaten des Hauptobjektes im oberen Teil an. Diese können nicht verändert werden.

Wenn für Kindesobjekte der Typ angegeben wurde, wird "Unterobjekte erzeugen" angezeigt. Die verfügbaren Typen finden sich im Dropdown Menu "Typ".

Befinden sich zum Zeitpunkt der Erstellung eines Kindobjektes Dateien im Ordner c:\work\output, dann werden diese dem Kindobjekt zugeordnet und auf den Server kopiert.

Alle Kinder des Hauptobjektes werden in der untersten Liste angezeigt.

Die Signatur des Kindobjektes kann im Einstellungsfenster vorgegeben werden. Das Eingabefeld wird dann zu einem Anzeigefeld und kann nicht mehr überschrieben werden.

Sie können die üblichen [[Omnisgrundlagen|Omnis-Funktionen]] benutzen. Das Feld kennt die Variable 'Zähler', welche ein automatisches hochzählen ermöglich.

Auf die Signatur des Vaterobjektes kann nicht zugegriffen werden. Der Name für die Signatur muss hier festgelegt werden.

con('MeineSignatur',[Zähler])

[[File:FDO_SHZTyp0c.png]]

[[Kategorie:Workflowschritt]]

Filehandling

2025-08-20T08:43:05Z

Silvan: 3522: Wiki aktualisisert

;Mantiseinträge:
2377
;Systemtyp:
59

==Beschreibung==
Dieser Arbeitsschritt kann verschiedene Aktionen wie zB. Files bewegen, Ordner erstellen etc. im DO Ordner vornehmen.

Mögliche Befehle:
* Erstelle Ordner
* Lösche Ordner
* Kopiere Dateien von XX nach XX
* Bewege Dateien von XX nach XX
* Lösche Datei(en) nach Name
* Lösche Datei(en) nach Position
* Kopiere Dateien des Vaters von XX nach XX
* Kopiere Dateien des Grossvaters von XX nach XX
* Lösche alle Dateien mit einem Barcode des Typs XX mit einem Wert YY
<br>
Befehle können 2 Varianten von Errorhandling vorweisen:
<br>
'''zwingend erfolgreich [!]:''' Jeder Fehler wirft ein DO Fehler. Auch wenn zB. konfiguriert ist, dass ein File test.txt von A nach B kopiert werden soll und das File jedoch nicht gefunden wurde.
<br>
'''nicht zwingend erfolgreich:''' Ziemlich schwaches Errorhandling. Nur schwere Fehler verursachen einene DO Fehler. Sollte zB. benutzt werden "falls" ein File von A nach B kopiert werden soll, sofern es existiert.

==Essentielle Felder==
HZ_FORMEL ''Konfiguration welche Befehle ausgeführt werden sollen''

HZ_DATENHOLEN ''0 = Daten bleiben beim letzten Datenschritt. Somit wird die letzte vorhandene Version Ihrer Daten bearbeitet (!), 1 = Daten werden vor dem Ausführen der Befehle an den aktuellen Schritt kopiert. Somit werden die Befehle auf einer Kopie der Daten durchgeführt (Normalfall), 2 = Es wird ein neuer, leerer DO Ordner erstellt''

==Erlaubte Werte für die Konfiguration:==
Beim Auswählen von Files kann entweder genau 1 File via Name angegeben werden, oder es können "*" im Dateinamen eingebunden werden um mehrere Files anzusprechen.

;Beispiel:

Alle TIF's in einem Ordner: "*.tif"
Alle Dateien welche mit "a" starten: "a*.*"
Alle Dateien welche mit "a" starten, mit "e" enden und vom Typ txt sind: "a*e.txt"

==Verhalten Daten holen:==

''Aktion am letzten Datenschritt ausführen:''<br>
Die Aktionen werden im Ordner des letzten Datenschrittes des DO Objektes ausgeführt. Die Daten an diesem Schritt werden damit z.B. unwiederruflich gelöscht.
Vermeidet das unnötige duplizieren der Daten an einen neuen Schritt, wenn zum bsp. die Ordnerstruktur geändert werden soll.

''Daten an diesen Schritt kopieren und Aktionen ausführen:''<br>
Kopiert und dupliziert damit alle Daten des letzten Datenschrittes des DO an den aktuellen Datenschritt dieses Arbeitsschrittes.

''Neuen DO Ordner erstellen:''<br>
Erstellt einen Ordner für das Do Objekt am Datenschritt dieses Arbeitsschrittes. Wird zwingend benötigt, für die kopieren Schritte der Daten des Vaters oder des Grossvaters, wenn für das DO Objekt selbst keine Daten aus einem früheren Arbeitsschritt exisitieren oder diese nicht mit den Daten der Ahnen zusammengeführt werden sollen!

===Version 0===
Hier werden die Parameter, wie der Dateiname/Ordnername nicht evaluiert. Sie können keine Metadaten verwenden.
===Version 1===
Hier können Sie Metadaten verwenden in den Parametern. Die Parameter müssen korrekte Formeln sein und einfache Zeichenfolgen sind in Anführungszeichen einzugeben.

z.B.:
con([^DOSignatur],'_komprimiert')
'*.tif'
Sie können die üblichen Platzhalter verwenden. Somit ist es möglich in jedem DO einen anderen Unterordner zu erstellen.

==Befehle:==

===Erstelle Ordner===

===Lösche Ordner===

===Kopiere Dateien von XX nach XX===

===Bewege Dateien von XX nach XX===

===Lösche Datei(en) nach Name===

===Lösche Datei(en) nach Position===

Dateien können anhand ihrer Sortierposition inerhalb des Dateisystems gelöscht werden. Die zu löschenden Positionen werden hier als Kommagetrennte Zahlenfolge eingegeben.

Die verwendung der Literale "U" und "G" ermöglichen das löschen aller '''G'''eraden oder aller '''U'''ngeraden Positionen. Die Literale dürfen jedoch nicht beide gleichzeitig verwendet werden, um damit z.B. alle Dateien zu löschen.

Es sind positive und negative Zahlen als Positionswerte möglich.

Negative Werte zählen von der letzten Datei ausgehend rückwarts. '''Wobei -1 = letzte Datei, -2 = vorletzte Datei.'''

Positive Werte zählen von der ersten Datei ausgehend vorwärts.

''Die Reihenfolge der Positionseingabe'' '''ist nicht relevant.'''

Bsp.:

Lösche die Dateien nummer drei, fünfzehn sowie die drittletzte -> '3,15,-3' (ist gleich wie '15,-3,3')

Lösche alle geraden, die nummern 7, 17 und die letzte -> 'G,7,17,-1' (ist gleich wie '-1,7,17,G')

Lösche alle ungeraden -> 'U'

Das Verhalten bei angewählter Option 'zwingend erforderlich' verlangt, dass alle genannten Dateipositionen vorhanden sein müssen!:

* Sollen gerade Dateien (G) gelöscht werden, und es gibt bloss eine einzige Datei, erzeugt dies einen DO Fehler.
* Soll die Datei -15 gelöscht werden, und es gibt bloss 14 Dateien, erzeugt dies einen DO Fehler.

===Kopiere Dateien des Vaters von XX nach XX===

===Kopiere Dateien des Grossvaters von XX nach XX===

===Erstelle Kindsordner===

Erstellt im aktuellen Ordner des Objektes Unterordner mit den Namen der Signaturen seiner Kindesobjekte.

Bsp.: Das Objekt hat fünf Kindobjekte mit den Signaturen A1, A2, A3, A4, A5.
Wenn das Objekt den Befehl durchlaufen hat, befinden sich im aktuellen Ordner des Objektes, nebst bereits vorhandenen Ordnern oder Dateien, fünf neue Ordner mit den Namen A1, A2, A3, A4, A5.

===Lösche alle Dateien mit einem Barcode des Typs XX mit einem Wert YY===
Dieser Befehlt löscht alle Bilder welche einen Barcode besitzen. Sie können den Typ des Barcodes wählen sowie der Barcodewert. Beachten Sie, dass bei der Serverjob Version 1 die Formel evaluiert wird. Somit können Sie die üblichen Platzhalter und Funktionen verwenden.

===Lösche alle Dateien und folgende mit einem Barcode des Typs XX mit einem Wert YY===
Dieser Befehl such den 1. Barcode mit dem Typd un Wert und löscht diesen und alle darauf folgenden Files. Sie können den Typ des Barcodes wählen sowie der Barcodewert. Beachten Sie, dass bei der Serverjob Version 1 die Formel evaluiert wird. Somit können Sie die üblichen Platzhalter und Funktionen verwenden.

==Pane im Produktionsauftrag (FHK_Maske)==

[[File:Filehandling.png|500px]]

[[Kategorie:Workflowschritt]]

Filehandling

2025-07-24T08:33:38Z

Silvan: 3522: Wiki aktualisiert

;Mantiseinträge:
2377
;Systemtyp:
59

==Beschreibung==
Dieser Arbeitsschritt kann verschiedene Aktionen wie zB. Files bewegen, Ordner erstellen etc. im DO Ordner vornehmen.

Mögliche Befehle:
* Erstelle Ordner
* Lösche Ordner
* Kopiere Dateien von XX nach XX
* Bewege Dateien von XX nach XX
* Lösche Datei(en) nach Name
* Lösche Datei(en) nach Position
* Kopiere Dateien des Vaters von XX nach XX
* Kopiere Dateien des Grossvaters von XX nach XX
* Lösche alle Dateien mit einem Barcode des Typs XX mit einem Wert YY
<br>
Befehle können 2 Varianten von Errorhandling vorweisen:
<br>
'''zwingend erfolgreich [!]:''' Jeder Fehler wirft ein DO Fehler. Auch wenn zB. konfiguriert ist, dass ein File test.txt von A nach B kopiert werden soll und das File jedoch nicht gefunden wurde.
<br>
'''nicht zwingend erfolgreich:''' Ziemlich schwaches Errorhandling. Nur schwere Fehler verursachen einene DO Fehler. Sollte zB. benutzt werden "falls" ein File von A nach B kopiert werden soll, sofern es existiert.

==Essentielle Felder==
HZ_FORMEL ''Konfiguration welche Befehle ausgeführt werden sollen''

HZ_DATENHOLEN ''0 = Daten bleiben beim letzten Datenschritt. Somit wird die letzte vorhandene Version Ihrer Daten bearbeitet (!), 1 = Daten werden vor dem Ausführen der Befehle an den aktuellen Schritt kopiert. Somit werden die Befehle auf einer Kopie der Daten durchgeführt (Normalfall), 2 = Es wird ein neuer, leerer DO Ordner erstellt''

==Erlaubte Werte für die Konfiguration:==
Beim Auswählen von Files kann entweder genau 1 File via Name angegeben werden, oder es können "*" im Dateinamen eingebunden werden um mehrere Files anzusprechen.

;Beispiel:

Alle TIF's in einem Ordner: "*.tif"
Alle Dateien welche mit "a" starten: "a*.*"
Alle Dateien welche mit "a" starten, mit "e" enden und vom Typ txt sind: "a*e.txt"

==Verhalten Daten holen:==

''Aktion am letzten Datenschritt ausführen:''<br>
Die Aktionen werden im Ordner des letzten Datenschrittes des DO Objektes ausgeführt. Die Daten an diesem Schritt werden damit z.B. unwiederruflich gelöscht.
Vermeidet das unnötige duplizieren der Daten an einen neuen Schritt, wenn zum bsp. die Ordnerstruktur geändert werden soll.

''Daten an diesen Schritt kopieren und Aktionen ausführen:''<br>
Kopiert und dupliziert damit alle Daten des letzten Datenschrittes des DO an den aktuellen Datenschritt dieses Arbeitsschrittes.

''Neuen DO Ordner erstellen:''<br>
Erstellt einen Ordner für das Do Objekt am Datenschritt dieses Arbeitsschrittes. Wird zwingend benötigt, für die kopieren Schritte der Daten des Vaters oder des Grossvaters, wenn für das DO Objekt selbst keine Daten aus einem früheren Arbeitsschritt exisitieren oder diese nicht mit den Daten der Ahnen zusammengeführt werden sollen!

===Version 0===
Hier werden die Parameter, wie der Dateiname/Ordnername nicht evaluiert. Sie können keine Metadaten verwenden.
===Version 1===
Hier können Sie Metadaten verwenden in den Parametern. Die Parameter müssen korrekte Formeln sein und einfache Zeichenfolgen sind in Anführungszeichen einzugeben.

z.B.:
con([^DOSignatur],'_komprimiert')
'*.tif'
Sie können die üblichen Platzhalter verwenden. Somit ist es möglich in jedem DO einen anderen Unterordner zu erstellen.

==Befehle:==

===Erstelle Ordner===

===Lösche Ordner===

===Kopiere Dateien von XX nach XX===

===Bewege Dateien von XX nach XX===

===Lösche Datei(en) nach Name===

===Lösche Datei(en) nach Position===

Dateien können anhand ihrer Sortierposition inerhalb des Dateisystems gelöscht werden. Die zu löschenden Positionen werden hier als Kommagetrennte Zahlenfolge eingegeben.

Die verwendung der Literale "U" und "G" ermöglichen das löschen aller '''G'''eraden oder aller '''U'''ngeraden Positionen. Die Literale dürfen jedoch nicht beide gleichzeitig verwendet werden, um damit z.B. alle Dateien zu löschen.

Es sind positive und negative Zahlen als Positionswerte möglich.

Negative Werte zählen von der letzten Datei ausgehend rückwarts. '''Wobei -1 = letzte Datei, -2 = vorletzte Datei.'''

Positive Werte zählen von der ersten Datei ausgehend vorwärts.

''Die Reihenfolge der Positionseingabe'' '''ist nicht relevant.'''

Bsp.:

Lösche die Dateien nummer drei, fünfzehn sowie die drittletzte -> '3,15,-3' (ist gleich wie '15,-3,3')

Lösche alle geraden, die nummern 7, 17 und die letzte -> 'G,7,17,-1' (ist gleich wie '-1,7,17,G')

Lösche alle ungeraden -> 'U'

Das Verhalten bei angewählter Option 'zwingend erforderlich' verlangt, dass alle genannten Dateipositionen vorhanden sein müssen!:

* Sollen gerade Dateien (G) gelöscht werden, und es gibt bloss eine einzige Datei, erzeugt dies einen DO Fehler.
* Soll die Datei -15 gelöscht werden, und es gibt bloss 14 Dateien, erzeugt dies einen DO Fehler.

===Kopiere Dateien des Vaters von XX nach XX===

===Kopiere Dateien des Grossvaters von XX nach XX===

===Erstelle Kindsordner===

Erstellt im aktuellen Ordner des Objektes Unterordner mit den Namen der Signaturen seiner Kindesobjekte.

Bsp.: Das Objekt hat fünf Kindobjekte mit den Signaturen A1, A2, A3, A4, A5.
Wenn das Objekt den Befehl durchlaufen hat, befinden sich im aktuellen Ordner des Objektes, nebst bereits vorhandenen Ordnern oder Dateien, fünf neue Ordner mit den Namen A1, A2, A3, A4, A5.

===Lösche alle Dateien mit einem Barcode des Typs XX mit einem Wert YY===
Dieser Befehlt löscht alle Bilder welche einen Barcode besitzen. Sie können den Typ des Barcodes wählen sowie der Barcodewert. Beachten Sie, dass bei der Serverjob Version 1 die Formel evaluiert wird. Somit können Sie die üblichen Platzhalter und Funktionen verwenden.

==Pane im Produktionsauftrag (FHK_Maske)==

[[File:Filehandling.png|500px]]

[[Kategorie:Workflowschritt]]

Generische Vorerfassung

2025-07-23T09:23:56Z

Silvan: 3519: Wiki erstellt

;Mantiseinträge:
3519
;Systemtyp:
76

==Beschreibung==
Mit diesem Arbeitsschritt kann eine generische Vorerfassung von Objekten konfiguriert werden. Dazu gibt es ein Modul namens "Generische Vorerfassung".

==Konfiguration==

[[Datei:Generische Vorerfassung.png|400px]]

===Punkt 1===
Wählen Sie hier alle Objekttypen aus, die Sie konfigurieren möchten. Sie können über “+” und “−” Objekttypen hinzufügen oder entfernen. Die Reihenfolge kann ebenfalls angepasst werden. Dies wirkt sich auf das Dropdown-Menü im “Generische Vorerfassungsfenster” aus.

===Punkt 2===
Hier können Sie die Signatur der neu erfassten Objekte definieren. Verwenden Sie dazu alle [https://helper.ch/wiki/index.php?title=Verfügbare_Funktionen verfügbaren Funktionen]. Falls der Benutzer die Signatur selbst wählen soll, geben Sie “*” als Wert ein.

===Punkt 3===
Aktivieren Sie diese Checkbox, wenn der Benutzer Objekte dieses Typs vorerfassen darf.

===Punkt 4===
Wählen Sie alle Attribute aus, die dem Benutzer im “Generische Vorerfassungsfenster” angezeigt werden sollen. Auch hier können Sie die Reihenfolge der Attribute festlegen.

===Punkt 5===
Wählen Sie das Objektblatt, das gedruckt werden soll. Alternativ können Sie die Option deaktivieren, sodass kein Objektblatt gedruckt wird.

===Punkt 6===
Wählen Sie den Lieferschein, der gedruckt werden soll. Auch hier können Sie die Option deaktivieren, sodass kein Lieferschein gedruckt wird.

==Fenster==

[[Datei:Generische Vorerfassung Fenster.png|900px]]
===Punkt 1 - Produktionsauftrag wählen===
Zuerst muss der Benutzer den gewünschten Produktionsauftrag auswählen. Es stehen ihm alle Arbeitsschritte zur Verfügung, die zu Produktionsaufträgen seines Kunden gehören. Der Produktionsauftrag muss also mit dem gleichen Kunden (HK_KU_SEQ) verknüpft sein, dem auch der Benutzer zugeordnet ist (US_KU_SEQ). Ist dem Benutzer kein Kunde zugewiesen, wird er als interner Mitarbeiter betrachtet und ihm werden alle Arbeitsschritte des Systemtyps 76 angezeigt.

Ein Wechsel zwischen Arbeitsschritten ist während der Vorerfassung möglich.

===Punkt 2 - Treelist===
In der Hauptliste dieses Fensters werden alle Objekte des Produktionsauftrags angezeigt. Befinden sich die Objekte nicht mehr in diesem Arbeitsschritt, kann der Benutzer ihre Daten nicht mehr bearbeiten. Dies wird durch ein Schlosssymbol signalisiert. Für jedes Objekt werden die Signatur und die vorkonfigurierten Attribute in der festgelegten Reihenfolge angezeigt. Alle Werte sind direkt in der Liste editierbar – mit Ausnahme der Signatur, sofern keine freie Benutzereingabe (”*”) konfiguriert wurde.

===Punkt 3 - Aktionen===
Der Benutzer kann mit diesen Buttons Objekte erstellen, löschen oder duplizieren. Im Objekttyp-Dropdown werden nur jene Objekttypen angezeigt, die für die Vorerfassung freigegeben sind. Auch das Duplizieren von Objekten anderer Typen ist nicht möglich. Falls konfiguriert, kann der Benutzer außerdem einen Lieferschein und ein Objektblatt drucken.

===Punkt 4 - Statistiken===
Hier wird die Gesamtzahl aller Objekte der aktuellen Tranche angezeigt. Zudem gibt es eine Übersicht über die Anzahl der verschiedenen Objekttypen.

==Essentielle Felder==
HZ_FORMEL ''Hier wird die gesamte Konfiguration gespeichert''
HZ_STRINGTRENNER ''Speichert welches Objektblatt gedruckt werden soll''
HZ_FELDTRENNER ''Speichert welcher Lieferschein gedruckt werden soll''

[[Kategorie:Workflowschritt]]

Datei:Generische Vorerfassung Fenster.png

2025-07-23T09:07:30Z

Silvan:

Fenster "Generische Vorerfassung"

Datei:Generische Vorerfassung.png

2025-07-23T08:55:26Z

Silvan:

Konfigurationsfenster der Generischen Vorerfassung

Formate definieren

2025-07-04T07:24:02Z

Silvan: 3517: Wiki um nach Fläche Erweitert

;Fenstername:
'''FDY_FormateDefinieren'''

== Grund Idee ==
In diesem Fenster können Sie interessante Formate, Umfänge und Kategorien definieren, welche Sie messen möchten und somit in Auswertungen im Blick haben. Einige Beispiele: "Wie viele der Bücher sind dick (> 50 Seiten)", "Wie viele Seiten meines Ordners sind gross (> A3)?", "Wie viele Bücher kann ich als teuer verrechnen? (> 50 Seiten und mindestens 15 grosse Seiten)

== Konfiguration ==
In den folgenden Abschnitten werden Sie durch die Konfiguration geführt. Um das Fenster zu öffnen navigieren Sie zu Hauptmaske >> Produktionsaufträge >> Objekttypen >> Formate definieren. <br> Es ist möglich Formate, Umfänge und Kategorien für Bilder sowie für PDFs (auch gemischt) zu definieren.

=== Allgemeine Hinweise ===
Alle Grenzen welche Sie angeben sind '''inklusive'''. Geben Sie also Acht, dass Sie in der nächsten Konfigurationszeile den "Bis" Wert immer um 1 erhöhen und diesen als Startwert verwenden. <br> Wichtig ist auch, dass keine Löcher oder Überschneidungen konfiguriert werden, da dies zu falschen Zahlen führen kann.

=== Formate ===
[[Datei:Formate v2.png|500px]]
<br><br>
In diesem Tab können Sie Formate für einzelne Seiten definieren. Alle Höhen und Breiten Werte sind in Millimeter. Falls Sie Bilddateien in Ihrem Projekt messen nutzen Sie den [https://pixelcalculator.com/de Pixelrechner] um von px und dpi auf mm zu schliessen. In das definierte Attribut wird die Anzahl Seiten des DO gespeichert. Somit würde nach dem Messen zum Beispiel "20" im Attribut "AnzahlMini" stehen. Die Option "Ausrichtung egal" definiert, ob die Seite automatisch ins Hochformat gedreht werden soll bevor die Messungen ausgeführt werden. Falls Sie "nach Fläche" wählen, wird die Fläche der Datei für den Abgleich verwendet. Dies ist vor allem Sinnvoll, wenn spezielle Dateiformate in diesem Projekt vorkommen können. Sie müssen immer das ganze Spektrum von 0 - 999999 mm in Ihrer Konfiguration abdecken damit alle Seiten sicherlich zu einem Format gehören.

=== Umfänge ===
[[Datei:Umfänge.png|500px|rahmenlos]]<br><br>
In diesem Tab können Sie Umfänge für DO-Objekte definieren. In das Attribut wird der Name des Umfanges geschrieben. Also steht zum Beispiel im Attribut "Umfang" am Ende "mittel" sofern das Objekt zwischen 21 - 40 Seiten hat. Sie müssen immer das ganze Spektrum von 0 - 99999 Seiten in Ihrer Konfiguration abdecken damit alle Objekte sicherlich zu einem Umfang gehören.

=== Kategorien ===
[[Datei:Kategorien.png|500px|rahmenlos]]<br><br>
In diesem Tab können Sie Kategorien für DO-Objekte definieren. In das Attribut wird immer der Name der '''letzten''' passenden Konfiguration geschrieben. In der Formel können Sie '''alle''' Attribute des Objektes verwenden, auch diese welche in der Konfiguration der Formate und Umfänge stehen!

Datei:Formate v2.png

2025-07-04T07:21:56Z

Silvan:

Das Fenster um Formate zu definieren

Verfügbare Funktionen

2025-06-12T10:35:15Z

Silvan: 3499: Doku für 2 neue Funktionen

Die hier gelisteten Funktionen lassen sich bei allen Workflowschritten anwenden, welche einen Link zu dieser Seite besitzen.

==Funktionen==

'''Beachte:''' Die Metadatumsfelder sind hier unbedingt als String ('Metadatum') zu übergeben und nicht wie andersweitig in eckigen Klammern.

===§getQuittungsFeld===

Holt den Wert aus einem Quittungsfeld. Das Objekt muss dazu eine Quittung besitzen. Es wird immer auf die letzte erstellte Quittung zurückgegriffen. Aktuell werden Quittungsdetail im JSON Format unterstützt.

Die Funktion erwartet einen gültigen Pfad zu einem JSON Member, oder anderst gesagt den Schlüssel zu einem Attribut in dem JSON. (JSON Pfade der Quittung finden: Siehe [[Warten auf Rückmeldung]])

§getQuittungsFeld('pfad.zu.dem.gewünschten.feld')

===§istInWortliste===

Ermittelt ob ein Metadatum in einer Wortliste vorkommt; wobei 1 = kommt vor, 0 = kommt nicht vor.

Die Wortliste ist als [https://helper.ch/wiki/index.php?title=Konfiguration Konfigurationsdatensatz] zu erstellen. Der Name der erstellen Wortliste wird als Parameter zum finden der Liste benötigt.

§istInWortliste(Metadatumsname,Wortlistenname,Suchtyp,Zeilenumbruchtyp)

;Metadatumsname: Wert des Metadatums, zB 'Eugen' oder [Vorname]
;Wortlistenname: Name der Wortliste, also des Konfigurationsdatensatzes.
;Suchtyp: 0=Es wird genau nach dem Wert gesucht (Standard), 1=Findet auch 'Hans', wenn in der Wortliste 'Eugen Hans' oder 'Hans-Peter' steht
;Zeilenumbruchtyp: Welcher Zeilenumbruch wird in der Wortliste verwendet: 0=Zeilenumbruch ist 'CR' (Standard), 1=Zeilenumbruch ist 'CRLF'

Bsp.: Es wurde eine Liste mit Vornamen in der Konfiguration erstellt. Diese Liste lautet auf den Namen "Vornamenkonfiguration". Ein Metadatum "Vorname" wurde erstellt, dort wurden zuvor Vornamen gespeichert.

§istInWortliste('Vorname','Vornamenkonfiguration')

===§getConfidenceOfWordInRegionXML===

Gibt die vom OCR ermittelte Konfidenz zu einem gefundenen Begriff zurück und schreibt den Wert in ein Metadatum. Erlaubt optional die Angabe eines Einschräkungsbereiches, in welchem der gesuchte Begriff vorkommen muss.

Der Bereich ist als Row(left,top,width,height) anzugeben: §getConfidenceOfWordInRegionXML('Suchwort',row(left,top,width,height))

Bsp.:
§getConfidenceOfWordInRegionXML('London',row(57,154,75,25))

0 = Begriff nicht gefunden
0.1 - 100 = Konfidenz des gefundenen Begriffes

===§istMin und §istMax===

Vergleicht von DO Objekten die Attributswerte des angegebenen Attributs miteinander, und ermittelt ob das DO den grössten oder den kleinsten Wert der verglichenen Objekte besitzt. Alle DO Typen, welchen den gleichen Attributsnamen besitzen, werden für den Vergleich herbeigezogen.<br>
Die Hierarchiestufe der Objekte kann, ausgehend vom Objekt eingeschränkt werden.<br>

Pflicht: Metadatumsname, Hierarchieebene<br>
Optional: Metadatumsname2 (Ohne Metadatumsname2 werden allein die gefundenen Metadaten aus Metadatumsname verglichen, mit werden nur diejenigen Objekte welche den gleichen Wert in Metadatumsname2 haben verglichen).<br>

§istMax(Metadatumsname,Hierachieebene,Metadatumsname2)
§istMax(Metadatumsname,../-2/-1/0/1/2/..,Metadatumsname2)
§istMin(Metadatumsname,../-2/-1/0/1/2/..,Metadatumsname2)

Bsp.:
'''§istMax('AnzahlDok',1,'Büronummer')''' Gibt 1 zurück, wenn das Objekt den grössten Wert im Attribut 'AnzahlDok' hat, innerhalb der eigenen Tranche und der gleichen Büronummer.

'''Parameter'''

Metadatumsname: Der Name des Metadatums

Hierachieebene: (Einschränkung)
* 0 = Alle DO des Auftrages (=keine Einschränkung)
* 1 = Alle DO mit dem selben Vorfahren auf Ebene 1 (typischerweise alle Objekte einer Tranche, inklusive der Tranche)
* 2 = Alle DO mit dem selben Vorfahren auf Ebene 2
* 3 = Alle DO mit dem selben Vorfahren auf Ebene 3
* etc.
* -1 = Alle auf der gleichen Ebene wie das DO Objekt, inklusive des Vorfahren
* -2 = Alle 2 Ebenen höher als das DO Objekt

Metadatumsname2: Schränkt die betrachteten Dos ein. Es werden nur die DO angesehen, die den gleichen Wert im Attribut '''Metadatumsname2''' haben.

===§sortierung===

Gibt die Sortierreihenfolge des Objektes zurück. Analog zu verwenden wie $min/$max.

§sortierung(Metadatumsname,../-2/-1/0/1/2/.., Metadatumsname2,0/1)

Bsp:
§sortierung('Büronummer',-1,'Metadatumsname2',0)

'''Parameter'''

Metadatumsname: Der Name des Metadatums

Hierachieebene: (Einschränkung)
* 0 = Alle DO des Auftrages (=keine Einschränkung)
* 1 = Alle DO mit dem selben Vorfahren auf Ebene 1 (typischerweise alle Objekte einer Tranche, inklusive der Tranche)
* 2 = Alle DO mit dem selben Vorfahren auf Ebene 2
* 3 = Alle DO mit dem selben Vorfahren auf Ebene 3
* etc.
* -1 = Alle auf der gleichen Ebene wie das DO Objekt, inklusive des Vorfahren
* -2 = Alle 2 Ebenen höher als das DO Objekt

Metadatumsname2: Schränkt die betrachteten Dos ein. Es werden nur die DO angesehen, die den gleichen Wert im Attribut '''Metadatumsname2''' haben.

Sortierreihenfolge: 0 = Aufwärts, 1 = Abwärts

===§istEindeutig===

Prüft ob für ein DO Objekt ein bestimmtes Metadatum im Vergleich zu weiteren DOs eindeutig ist. Vergleiche sind mit DOs auf wählbarer Hierarchieebene sowie mit gleichem oder abweichendem DO Typ möglich.

§istEindeutig(Metadatumsname, 0/1/2, 0/1/2[,DO Typen])
§istEindeutig(Metadatumsname, Hierarchieebene, Typ-Einschränkung[,'Typ1,Typ2,..'])

'''Parameter'''
Metadatumsname: Der Name des Metadatums
Bereich: 0 = Ganzer Auftrag, alle DO dieses Auftrages, 1 = Alle DO auf Ebene 1, 2 = Alle DO auf Ebene 2
Typ-Einschränkung: 0 = Alle Typen mit dem gleichen Metadatumsname, 1 = Gleicher Typ wie das Vergleichsobjekt, 2 = Alle im zwingend folgenden Parameter angegebenen Typen

'''Anwendung'''
§istEindeutig('Verlag',0,0) Alle DO des Auftrages, welche bei einem beliebiegen DO Typ und dem Attribut 'Verlag' das selbe Metadatum besitzen
§istEindeutig('Verlag',1,1) Alle DO auf Ebene 1, welche zum gleichen Typ und dem Attribut 'Verlag' das selbe Metadatum besitzen
§istEindeutig('Verlag',2,0) Alle DO auf Ebene 2, welche bei einem beliebiegen Typ und dem Attribut 'Verlag' das selbe Metadatum besitzen
§istEindeutig('Verlag',2,1) Alle DO auf Ebene 2, welche zum gleichen Typ und dem Attribut 'Verlag' das selbe Metadatum besitzen
§istEindeutig('Verlag',2,2,'Buch, Magazin, Zeitung') Alle DO auf Ebene 2, welche zu den angegebenen Typen 'Buch, Magazin, Zeitung' und dem Attribut 'Verlag' das selbe Metadatum besitzen

Fehleingabe vermeiden:
§istEindeutig('Verlag',2,2) Es wird eine Typeinschränkung (Parameter drei = 2) verlangt, ohne nachfolgende die gesuchten Typen zu nennen.

===§KindNr===

Diese Methode gibt zurück, das wievielte Kind das Objekt ist.

§KindNr()

Bsp:
Das Objekt hat 5 Geschwister und ist als viertes erstellt worden. Somit gibt die Methode §KindNr 4 zurück.

===§sortierungSignatur===

Diese Methode gibt zurück, die Position des Objektes von allen Objekten mit der gleichen Signatur.

§sortierungSignatur()

Bsp:
Gegeben:
Objekt 1 mit Signatur 'A'
Objekt 2 mit Signatur 'B'
Objekt 3 mit Sigantur 'A'
Objekt 4 mit Signatur 'A'
Objekt 5 mit Signatur 'C'

Wird zurückgegeben:
Objekt 1 -> 1 (weil es das erste Objekt ist mit Signatur 'A')
Objekt 2 -> 1 (weil es das erste Objekt ist mit Signatur 'B')
Objekt 3 -> 2 (weil es das zweite Objekt ist mit Signatur 'A')
Objekt 4 -> 3 (weil es das dritte Objekt ist mit Signatur 'A')
Objekt 5 -> 1 (weil es das erste Objekt ist mit Signatur 'C')

===§minX===

Bevor diese Methode ausgeführt werden kann, muss der Schritt [[Files messen]] gemacht werden.
Diese Methode gibt die kleinstmögliche Breite des Objektes nachdem die [[Files messen|Files gemessen]] wurden an, grösser oder gleich dem Parameter.
Es werden alle Files ausgewertet ausser PDFs.
Die Methode erwartet eine Zahl als Pixel-Wert.

§minX(minimumPixel)

Bsp:
Objekt mit folgenden Files: auto.jpg (Breite: 100), baum.jpg (Breite:200), clown.jpg (Breite:110)
Methode §minX(105) gibt 110 zurück
Methode §minX(110) gibt 110 zurück
Methode §minX(150) gibt 200 zurück

===§minY===

Bevor diese Methode ausgeführt werden kann, muss der Schritt [[Files messen]] gemacht werden.
Diese Methode gibt die kleinstmögliche Höhe des Objektes nachdem die [[Files messen|Files gemessen]] wurden an, grösser oder gleich dem Parameter.
Es werden alle Files ausgewertet ausser PDFs.
Die Methode erwartet eine Zahl als Pixel-Wert.

§minY(minimumPixel)

Bsp:
Objekt mit folgenden Files: auto.jpg (Höhe: 100), baum.jpg (Höhe:200), clown.jpg (Höhe:110)
Methode §minY(105) gibt 110 zurück
Methode §minY(110) gibt 110 zurück
Methode §minY(150) gibt 200 zurück

===§OCRTextRegion===

Führt OCR auf einer bestimmen Seitennummer (einzelne Bild Datei!) in einer bestimmten Region aus, und gibt als Resultat den gefundenen Text zurück. Dieser Text lässt sich dann z.B. in ein Metadatum übertragen.

Die Seitennummer wird über die Sortierreihenfolge der Dateinamen im Dateisystem bestimmt. Es werden TIFF, JPG und PNG als Dateiformate unterstützt.

Die wählbare Region, welche eine rechteckige Selektion ist, wird über die Koordinaten X1,X2,Y1,Y2 in Pixel definiert. Wobei X1=linker Rand, X2=rechter Rand, Y1=oberer Rand, Y2=unterer Rand.

'''Wenn für die Koordinaten negative Werte eingesetzt werden, so werden die Positionen relativ zur Bildgrösse und ausgehend vom rechten oder unteren Bildrand berechnet!'''

§OCRTextRegion(Seite,X1,X2,Y1,Y2)

Bsp: Seite Nummer 5 (entspricht Datei Nummer 5). Bilddimensionen: 2663 Breite x 3603 Höhe

§OCRTextRegion(5,359,709,631,690) -> entspricht einem Auswahlrechteck mit Abstand Links=359, Abstand oben=631, Breite=350, Höhe=59

§OCRTextRegion(5,-2304,709,-2972,690) -> entspricht genau dem gleichen Auswahlrechteck mit Abstand Links=359, Abstand oben=631, Breite=350, Höhe=59 ''' weil das Bild die gleiche Dimension besitzt!'''

§OCRTextRegion(5,-2304,-1954,-2972,-2913) -> entspricht genau dem gleichen Auswahlrechteck mit Abstand Links=359, Abstand oben=631, Breite=350, Höhe=59 '''weil das Bild die gleiche Dimension besitzt!'''

===§FileAnzahl===

Diese Methode gibt dir Anzahl Dateien am aktuellen Datenschritt des Objektes zurück. Dabei werden alle Dateien auch in allen Unterordnern gezählt. Unsichtbare Dateien sowie die Ordner selbst zählen nicht.

§FileAnzahl()

===§Hausnummer===
Diese Methode formatiert einen Hausnummer.
§Hausnummer(Wert)

Beispiele:
12 -> 012
123 -> 123
12a -> 012a
2a -> 002a

===§KinderSummeAT===
Gibt die Summe der Werte des Attributs aller Kinder zurück, nicht rekursiv, also nur der direkten Kinder.
§KinderSummeAT('Attribut')

===§KinderWertAT===
Gibt den Wert des Attributs des ersten Kindes zurück. Idealerweise hat es nur ein Kind. Sonst wir das erste genommen.
§KinderWertAT('Attribut')

===§isJSONValid===
Prüft ob ein Attribut ein valides JSON ist. Gibt Wahr (true) oder Falsch (false) zurück.
§isJSONValid('JSON')

===§StrasseAusschreiben===
Diese Methode prüft ob ein Strassennamen (mit oder ohne Hausnummer) schön formatiert ist. Dabei wird jeder Anfangsbuchstabe in einen Grossbuchstaben geändert. "str" und "str." werden zu "strasse" ausgeschrieben.

§StrasseAusschreiben('Strasse')

====Beispiele====
Teststr 58A => Teststrasse 58A
zUr lindENstr. => Zur Lindenstrasse
Hofweg 68 => Hofweg 68

==Weitere Beispiele==
§OCRMatchCount('Bericht')>0 ==> Falls das Wort Bericht mindestens 1 Mal gefunden wurde ist der Ausdruck wahr<br>
§OCRMatchCount('[0-9][0-9][.]')=0 ==> Falls KEINE 2 stellige Zahl mit einem Punkt gefunden wird ist der Ausdruck wahr<br>
§OCRMatchCount('[BelegName]')>2 ==> Falls der Wert des Attributes BelegName mehr als 2 mal gefunden wird ist der Ausdruck wahr<br>
§OCRMatchCount('[BelegName]',1)>0 ==> Falls der Wert des Attributes BelegName mindestens einmal im OCR der Kindern gefunden wurde.<br>

Objekt Umwandlung/Verdoppelung

2025-05-07T07:27:16Z

Silvan: 3503: Wiki ergänzt

;Mantiseinträge:
1824, 2662
;Systemtyp:
21

==Beschreibung==
Besteht aus einem Serverjob OJOHZDOVerdoppeln.

Erzeugt eine Kopie (Duplikat) eines DO Objektes, optional mit
* den zugehörigen Dateien
* den zugehörigen Metadaten

Das erzeugte Duplikat geht zum Herstellungsschritt HZ_HZ_SEQ2. Das Original zu HZ_HZ_SEQ. Folgende Fehler werden beim Duplikat gelöscht: Fehlertext, FTPUPLOADFiles, Änderungsdatum. Das Erfassungsdatum wird auf heute gestellt.

Umgangssprachlicher Name: Objekte duplizieren.

Es ist möglich die Daten vom aktuellen Datenschritt oder einem spezifischen Datenschritt zu duplizieren. Falls Sie einen spezifischen Datenschritt angeben und bei einem DO keine Daten gefunden werden gibt es einen Fehler.

==Objekt Erstellen bei Bildgrössenveränderung==
In diesem Modus wird das Haupt DO so oft dupliziert wie es Bildgrössenveränderungen (+- 1cm in Höhe und Breite zum vorherigen File) gibt. zB A4, A4, A3, A3, A4 gibt 2 neues DOs mit den Files A3, A3 und A4. Die Dateien werden in das duplizierte DO verschoben.

Wenn die Checkbox "Einzelnes Objekt erstellen wenn Bild grösser ist als Grenzwert" markiert wird, werden alle Dateien welche grösser sind zu einem Single Page Objekt. zB aus A4, A4, A3, A3, A4 werden 3 neue DOs A3 und A3 und A4.

Beachten Sie beim Grenzmass, dass nicht alle Scans gleich gross sind und geben Sie entsprechende Marge. Das DO muss natürlich vorher durch einen Filemessen Schritt laufen.

==Essentielle Felder==

HZ_FILEVERHALTEN: 0=Duplikat erhält keine Files, 1=Duplikat erhält Kopien der Files
HZ_METADATENERFASSEN: 0=Duplikat erhält keine Metadaten, 1=Duplikat erhält Metadaten
HZ_DELEATUR: HZ_SEQ des Datenschrittes von welchem die Daten dupliziert werden sollen
Aktuell nicht mehr verwendet - HZ_KINDERVERDOPPELN 0=nein 1=eine Ebene 2=zwei Ebenen etc
HZ_EXPORTFILETYP: Neues Objekt erstellen bei Bildgrössenveränderung
HZ_HASHTYP: Einzelnes Objekt (Single Page) erstellen wenn Bild grösser ist als Grenzmass
HZ_RANDOBENHINZU: Breite des Grenzmass
HZ_RANDLINKSHINZU: Höhe des Grenzmass

DO_DO_SEQ2 Verknüpfung zum Originalobjekt vor der Verdoppelung

[[Kategorie:Workflowschritt]]

Metadaten mit Anzeige des Files

2025-04-03T07:26:23Z

Silvan: 3461: Superusermode ergänzt

;Mantiseinträge:
1980
;Systemtyp:
31

==Beschreibung==
Einer der Arbeitsschritte (FDO_SHZTyp31), welcher im Fenster FDO_Auswahl1 ausgeführt wird.

In diesem Arbeitsschritt werden Metadaten zu den jeweiligen Objekt erfasst.

Es gibt vier verschiedene Fenster:
* Eines ist generell
* Eines ist angepasst an Zeitungsartikel (b)
* Eines ist angepasst an den Murdockcode (a)
* Eines ist angepasst an die Denkmalpflege (c)
* Eines ist angepasst an für die Anzeige von Geschwister und Vater (d)
* Eines ist angepasst an das Projekt Badischer Bahnhof (e)
* Eines ist angepasst für OCR (f)
* Eines ist angepasst an die Einwohnerkarten (g)
* Eines ist angepasst an die Azure-Validierung (h)

Es können X beliebige Ausgänge für den User aus den Metadatierungsfenstern definiert werden.

===Leistungen===
Alle Metadaten werden vor dem Starten des Schrittes mit denen am Ende verglichen. Es können folgenden Leistungen vorkommen:
;Felder, Create: Wie viele Metadaten wurden neu erfasst.
;Felder, Update: Wie viele Metadaten wurden aktualisiert.
;Felder, Delete: Wie viele Metadaten wurden gelöscht.

==Essentielle Felder==
;Daten vom Server holen: Muss angekreuzt sein, sonst werden die Bilder des Objektes nicht angezeigt.
;Nächster Arbeitsschritt im normalen Fall: Nummer des Arbeitsschrittes, an den Objekte gehen, wenn alles ok ist. (HZ_HZ_SEQ1)

==Pane im Produktionsauftrag (FHK_Maske)==

[[File:FHZ STyp31.png|600px]]

[[Kategorie:Workflowschritt]]

==Spezifische Konfiguration Denkmalpflege==
* Untersystemtyp = FDO_Auswahl1:FDO_SHZTyp31c:FAA_SMaske31c:DENKINF
* Daten nicht vom Server holen (Werden ja nicht bearbeitet)
* Metadatenerfassen = Ja

===Attribute für den Objekttyp "Bild"===
Diese Attribute müssen zwingend genau so erfasst werden:<br>
bezeichnung, plz, ort, strasse, hausnummer, hausnummerzusatz, parzelle, objekttyp, <br>
baujahr, rrbnr, objid, bildtyp, code, beschreibung, sujet, jahr, ersteller, bemerkungen

===Sonnstiges===
Der AT an welchem alle AOs hängen, welche vom Excel importiert wurden, hängt an keinem HK. Es ist ein Standalone AT und für die Zukunft wiederverwendbar.

==Spezifisches Fenster für Azure-Validierung (h)==
In diesem Fenster lassen sich Metadaten, welcher vorher mit Azure ausgelesen wurden, kontrollieren und korrigieren.

===Serverjob Konfiguration===
* Konfigurieren Sie, welche Metadaten angezeigt werden. Sie können definieren, wie viele Zeilen das Eingabefeld im Fenster haben soll.
* Stellen Sie sicher, dass das Metadatum, in welchem das JSON gespeichert ist, ausgeblendet ist.
* Geben Sie den Namen des Metadatum an, in welchem sich das Azure JSON befindet.

===Arbeitsfenster===
* In diesem Fenster kann der Angestellte die Metadatenwerte prüfen
* Vor dem Abschluss des Objektes, muss er alle Seiten angeschaut haben, sofern Sie das Konfiguriert haben
* Der Cursor springt automatisch in das erste Feld mit einer roten Confidence
* Mit Tab springt der Cursor direkt ins nächste rote Feld
* Es werden grüne oder orange Rahmen um den Begriff auf der PDF-Anzeige gezeichnet

=== Super User Mode ===
* Sie können in den Produktionsaufträgen unter Diverses für bestimmte Angestellte den "Superusermode" einschalten
* Dadurch wird unter jedem Eingabefeld ein Text in der Form FKG XX/XX, FKNG XX/XX, OCR XX/XX angezeigt
* FKG zeigt die Feldkonfidenz gefunden an
* FKNG zeigt die Feldkonfidenz nicht gefunden an
* OCR zeigt die Konfidenz des ausgelesenen Textes an

[[Datei:FDOSHZTyp31h(2).png|800px]]

Datei:FDOSHZTyp31h(2).png

2025-04-03T07:22:55Z

Silvan:

Azure Kontrollfenster

Filetest

2025-03-13T10:03:31Z

Silvan: 3459: Wiki erweitert

;Mantiseinträge:
1526

1822
;Systemtyp:
18

==Beschreibung==
Besteht aus einem Serverjob OJOHZDOFiletest. Überprüft die Files auf ihre Richtigkeit. Das Ergebnis (0/1) kann in einem Attribut gespeichert werden. Falls ein Test fehlschlägt geht das Objekt zu zum roten Ausgang und im Fehlertext steht, welche Bedingung(en) nicht erfüllt wurde(n).

'''Grundsätzlich sind hier keine Formeln für die Werte möglich, mit Ausnahme:''' ''FileAnzahl''

===Konfiguration FileAnzahl===
Bei diesem Test werden die '''Dateien und Ordner''' im auf oberster Ebene im Objektordner gezählt. Die Dateien in (Unter-)Ordnern zählen nicht. Der Ordner 'Hilfsobjekte' zählt auch.

'''Zugriff auf Metadaten des Objektes, bzw. das einsetzen von Formel sind für diesen Test erlaubt.''' ''Das Metadatum ist wie üblich in eckigen Klammern zu nennen: [MetadatumMitAnzahl]''

===Konfiguration FileTyp===
Bei diesem Test wird jedes File im Objektordner mit konfigurierten Filetyp verglichen. Ordner werden (natürlich) nicht verglichen. Files in Unterordnern werden nur getestet, wenn 'Rekursiv' angekreuzt ist.

===Konfiguration BildformatXY===
Bei diesem Test können beide Seiten des Bildformats (X und Y) berücksichtigt werden.
*Operator Codes können sein (>, *>, >>, *>>) Bzw. die Varianten für kleiner (<) und gleich (=)
*>,= wenn eine Seite grösser/gleich als ihr entsprechender Maximalwert (xi > xs) | (yi > ys)
*>>,== wenn beide Seiten grösser / gleich wie der entsprechende Maximalwert (xi > xs) & (yi > ys)
* *>, *= wenn mindestens eine beliebige Seite grösser / gleich ist wie ein beliebiger Maximalwert
* *>>, *== wenn je beide Seiten grösser / gleich wie ein beliebiger Maximalwert sind (Bildausrichtung gleich oder gedreht)
Der Vergleichswert wird geschrieben: 2000x3000

===Konfiguration Farbraum===
Bei diesem Test wird der Farbraum aus dem File gelesen. Typische Werte sind 'Gray' oder 'sRGB'. Bitte achten Sie auf Grosskleinschreibung.

=== Konfiguration Positions SW Histogramm ===
Bei diesem Test wird ein Histogramm in einem PDF / Bild generiert basierend auf einer bestimmten Position sowie einem Grössenbereich.
Grundsätzlich wird immer von links oben aus gerechnet.<br>

1. Parameter = Seite - zB 4 (Wird nur bei PDF's verwendet)<br>
2. Parameter = Position X - zB 250 oder -150 (Bei Bildern in Pixel, bei PDF's in mm / Negative Zahlen werden von Rechts statt Links aus gerechnet)<br>
3. Parameter = Position Y - zB 300 oder - 200 (Bei Bildern in Pixel, bei PDF's in mm / Negative Zahlen werden von Unten statt Oben aus gerechnet)<br>
4. Parameter = Breite - zB 500 oder 25 % (Entweder Prozentangabe oder bei Bildern in Pixel, bei PDF's in mm)<br>
5. Parameter = Höhe - zB 200 oder 15 % (Entweder Prozentangabe oder bei Bildern in Pixel, bei PDF's in mm)<br>
6. Parameter = Helligkeitsgrenzwert - zB 150 (Werte von 0 - 255, wobei 0=Schwarz / 255 = Weiss)<br>
7. Parameter = Prozent - zB 35% (Wie viel Prozent der Pixel müssen über oder unter der angegeben Helligkeit sein)<br>
<br>
Hier ein komplettes Beispiel: "1,100,-150,140,5%,200,30%"<br>
*Es wird Seite 1 gemessen (falls es um ein PDF geht)
*Es wird der folgende Bildausschnitt genommen: Annahme das Bild ist 1000x500px gross
** Linke obere Ecke: 100/350 px. (350=500-150)
** Grösse des Ausschnitts: 140x25 px. (25=5% von 500)
** Rechte untere Ecke: 240/375 px.
*Es wird folgende Formel evaluiert:
(Pixelheller (als Grauwert 200) / TotaleAnzahlPixel) > oder < Prozent (30%).
Es werden also immer die helleren Pixel als der Helligkeitsgrenzwert gezählt und durch die totale Anzahl Pixel geteilt. Das Ergebnis wird mit dem Prozentsatz verglichen.
Falls ein Wert nicht angegeben werden soll muss das Komma dennoch da stehen. Beispiel ohne die Angabe der Seite: ",100,-150,140,5%,200,30%".<br>
==== Beispiele Bildausschnitt====
* Das ganze Bild (Seite 1) soll gemessen werden: "1,1,1,100%,100%..."
* Links oben in der Ecke soll ein Quadrat von 100px gemessen werden: "1,1,1,100,100..."
==== Beispiele Helligkeit====
* Es darf fast keine (fast) schwarzen Pixel haben: > "...20, 98%" -> mehr als 98% der Pixel sollen heller sein als fast schwarz (Grauwert 20)
* Es soll fast ganz weiss sein: > "...240, 99%" -> 99% der Pixel sollen heller als der Grauwert 240 sein (fast weiss)

=== Konfiguration Ist Extrem ===
Bei diesem Test wird jedes DO geprüft ob es nach der konfigurierten Weise extrem ist.

1. Parameter = Sortierfeld - Dieser Wert wird aufs "Extrem sein" geprüft. Muss ein AT-Name sein<br>
2. Parameter = Selektionsfeld - Es werden nur DOs berücksichtig die den gleichen Wert im Selektionsfeld haben wie das DO welches gerade angeschaut wird. Muss ein AT-Name sein. Falls leer wird DO_DO_SEQ automatisch verwendet.<br>
3. Parameter = Menge - Ab wann wird ein DO als Extrem beachtet? zB. 10<br>
<br>
Hier ein komplettes Beispiel: "seitenanzahl,pdfname,10"<br>
Ist das DO in den Top 10 mit den Seitenzahlen verglichen mit allen DOs welche denselben PDF Namen haben?

===Konfiguration Pixeltiefe pro Kanal===
Bei diesem Test wird die Anzahl Pixel pro Kanal aus dem File gelesen. Typische Werte sind 8 oder 16.

===Konfiguration ICC Profile===
Bei diesem Test wird aus dem File die Zeile icc:description gefiltert und der Text danach herausgelesen. Ein typischer Wert ist 'Adobe RGB (1998)'.

Sie können das Feld bei einem Bild auch auslesen:
identify -verbose "Pfad zum Bild"
Suchen Sie nach der Zeile 'icc:description'

===Dateigrösse===

Bei diesem Test wird eine Dateigrösse in Bytes geprüft.

Operator Codes können sein (>,<).

===SeitenAnzahl===

Bei diese Test wird die Anzahl Seiten in einem PDF oder TIFF Dokument geprüft.

Operator Codes können sein (>,<,=,<>).

==Allgemeine Metadaten von Bildformaten==

Für die unten folgenden Konfigurationen kann für die gesuchten Werte auf diese Auflistungen von TAG Namen zurückgegriffen werden:

[https://www.exiftool.org/TagNames/ TAG Übersicht]

[https://www.exiftool.org/TagNames/EXIF.html EXIF Tags]

[https://www.exiftool.org/TagNames/IPTC.html IPTC Tags]

[https://www.exiftool.org/TagNames/XMP.html XMP Tags]

'''Suche nach leeren Tags'''

Falls nach leeren, bzw. fehlenden Werten gesucht werden soll, dann ist der Wertebereicht nach dem Komma leer zu lassen.

Bsp.: Kein Änderungsdatum vorhanden

[[Datei:Metadatum Datum leer.png]]

===Konfiguration Metadatum Text===

Bei diesem Test wird ein TAG mit Textinhalt verglichen.

Operator Codes können sein (=, <>)

Bsp.: Gesucht wird der Hersteller des Aufnahmegerätes. Der entsprechende TAG heisst 'Make'. Der gesuchte Wert soll auf 'Canon' lauten.

[[Datei:Metadatum Text.png]]

===Konfiguration Metadatum Zahl===

Bei diesem Test wird ein TAG mit Zahleninhalt verglichen.

Operator Codes können sein (=, <>, >, >=, <, <=)

Bsp.: Gesucht wird nach der X Auflösung des Bildes. Der entsprechende TAG heisst 'XResolution'. Der gesuchte Wert soll grösser oder gleich 3500 sein.

[[Datei:Metadatum Zahl.png]]

===Konfiguration Metadatum Datum===

Bei diesem Test wird ein TAG mit Datumsinhalt verglichen.

Operator Codes können sein (=, <>, >, >=, <, <=)

Bsp.: Gesucht wird dem Änderungsdatum. Der entsprechende TAG heisst 'DateModify'. Der gesuchte Wert soll nach dem 23.03.2021 08:05:14 liegen.

[[Datei:Metadatum Datum.png]]

==Dateien auch in den Unterordnern prüfen==

Soll auch in Unterordner geprüft werden, ist folgende Checkbox zu aktivieren:

[[File:filetest_rekursiv.png]]

Der Filetest beim Abschliessen eines clientseitigen Arbeitsschrittes ist nicht rekursiv.

== Dateinamen auf Regex überprüfen ==
Sie können den Dateinamen mithilfe eines Regex überprüfen lassen.
Wählen Sie dazu die Kondition "Dateiname" und den Operator "entspricht Regex", dann '''muss jedes File''' im Objektordner dem Regex entsprechen.
Wenn Sie "entspricht nicht Regex" wählen, dann '''darf kein File''' dem Regex entsprechen.

Tool um Regex zu schreiben: https://regex101.com

[[Datei:Filetest regexmatching.png|500px]]

==Barcodes finden==

Ermittelt, ob die Seiten einen Barcode besitzen. Ein bestimmer Suchwert für den Inhalt des Barcodes kann ebenfalls als Einschränkung mitgegeben werden.

Kann alle Seiten, oder nur die geraden, oder nur die ungeraden prüfen. Wenn wir hier von Seiten sprechen, dann sind damit einzelne Dateien gemeint, welche in der Regel eine einzelne Seite darstellen. Die Reihenfolge der nach Namen sortierten Dateien im Dateisystem legt dabei die Seitenzahl fest. Die erste Datei - Sortiernummer 1 - entspricht demnach einer ungeraden Seite. Datei achte Datei - Sortiernummer 8 - einer geraden Seite.

Unterstüzte Dateitypen - alle gängigen Bildformate.

'''Attribut:''' SeiteHatBarcodes

'''Operator Code:''' ( = )

'''Wert:''' A/U/G/[Zahl]''','''Barcodeinhalt,Barcodetyp

A = alle Seiten, U = ungerade Seiten, G = gerade Seiten, [Zahl] = zB. 5 => Hat es auf der 5. Seite einen Barcode?

'''Bsp.:'''

1) Suche auf ungeraden Seiten nach einem Barcode: '''Wert = 1'''

2) Suche auf geraden Seiten (2) nach einem Barcode mit dem Wert 0783A-123: '''Wert = 2,0783A-123'''

'''Merke:''' Die Suche nach einem Wert funktioniert aktuell nur für den ersten gefundenen Barcode! Wenn es mehrere Barcodes auf der Seite gibt, wird jeweils der erste Ausgewertet.

Falls eine Zahl angegeben wird, kann der Barcodetyp definiert werden. In der anderen Fällen ist der Parameter nicht implementiert. Ebenfalls kann der Wert ein Regex sein, sofern eine Zahl definiert ist.

==Essentielle Felder==
AR_FILETEST, HZ_FILETEST ''Code kTab Attribut kTab Operator kTab Wert(e) kCR''

HZ_TESTERGEBNIS

HZ_FILEVERHALTEN

==Pane im Produktionsauftrag (FHK_Maske)==

[[File:0.jpg]]

[[Kategorie:Workflowschritt]]

CheckIn

2025-03-05T14:15:45Z

Silvan: 3487: Text um Bruder erstellen erweitert

;Mantiseinträge:
1809
;Systemtyp:
13

==Beschreibung==

Arbeitsschritt der Wareneingangskontrolle.

Arbeitnehmer checkt die Objekte (z.B Boxen) hier in den Workflow ein und erfasst ggf. defekte an den Objekten.

An diesem Schritt können grundsätzlich keine Objekte erstellt werden. Die Objekte müssen zuerst erstellt worden sein und erscheinen dann in der Auswahlliste.

Es besteht die Möglichkeit, das duplizieren von Objekten zu erlauben (HZ Konfiguration), so dass bei unerwartetem Wareneingang oder bei Fehlern in der Vorerfassung, ein am Eingang tatsächlich vorhandenes Objekt gleich in den Workflow eingegliedert werden kann.

Es besteht die Möglichkeit, neue Brüder im CheckIn Fenster zu erstellen. Dazu klicken Sie die Checkbox "Neue Objekte erstellen erlaub" an und wählen einen Objekttyp für diese neuen Objekte aus. Es wird ein neuer Button im Fenster sichtbar der auf der selben Ebene wie das ausgewählte Objekt ein neues anlegt. Die Signatur muss vom Benutzter eingegeben werden.

*Metadaten werden nicht dupliziert! Diese müssen von Hand eingegeben werden. Die Bearbeitung von Metadaten muss ebenfalls zuerst über eine Konfiguration ermöglicht werden.
*Tranchen, bzw. Objekte auf der ersten Ebene können nicht dupliziert werden.
*Die Signatur wird 1-1 übernommen. Wird der Schalter duplizieren jedoch mit gedrückter SHIFT Taste aufgerufen, dann kann der Signatur ein zusätzlicher Text nach freier Eingabe angehängt werden.

Über den Schalter 'Fehlend markieren' kann ein Objekt als nicht geliefert / vorhanden markiert werden. Das Objekt wird dabei zum zweiten Ausgang verschoben und der Status auf 'fehlt' gesetzt. Das Objekt kann nun nicht mehr eingechekct werden! <br> '''Ein erneutes drücken des Schalters setzt die Markierung wieder zurück'''

Status:

'neu' Objekte welche eingecheckt werden müssen
'früher eingecheckt' Objekte welche bereits eingecheckt wurden.
'fehlt' Objekte welche nicht vorhanden sind oder nicht geliefert werden.

==Ausgänge==

Der Schritt besitzt zwei Ausgänge.

Eingecheckt - Normalfall nach erfolgtem einbuchen
Objekt fehlt - Objekt wurde als fehlend markiert

==Maske FDO_CheckIn==

[[Datei:FDO CheckIn.png | 800px]]

==Essentielle Felder==
Felder zur Datenbankverbindung wie im Systemtyp 8 SFTP-Upload.

HZ_BEZEICHNUNG ''URL für Postgres DB''
HZ_USERNAME ''Benutzername"
HZ_PASSWORD ''Password"

HZ_HASHTYP ''Duplizieren erlauben''
HZ_KINDERVERDOPPELN ''Bruder erstellen erlauben''
HZ_DY_SEQ1 ''Welcher Objekttyp hat der neue Bruder''

==Pane im Produktionsauftrag (FHK_Maske)==

[[Datei:FHZ STyp013.png | 400px]]

[[Kategorie:Workflowschritt]]

CheckIn

2025-03-05T14:13:37Z

Silvan: 3487: Maske aktualisiert

;Mantiseinträge:
1809
;Systemtyp:
13

==Beschreibung==

Arbeitsschritt der Wareneingangskontrolle.

Arbeitnehmer checkt die Objekte (z.B Boxen) hier in den Workflow ein und erfasst ggf. defekte an den Objekten.

An diesem Schritt können grundsätzlich keine Objekte erstellt werden. Die Objekte müssen zuerst erstellt worden sein und erscheinen dann in der Auswahlliste.

Es besteht die Möglichkeit, das duplizieren von Objekten zu erlauben (HZ Konfiguration), so dass bei unerwartetem Wareneingang oder bei Fehlern in der Vorerfassung, ein am Eingang tatsächlich vorhandenes Objekt gleich in den Workflow eingegliedert werden kann.

*Metadaten werden nicht dupliziert! Diese müssen von Hand eingegeben werden. Die Bearbeitung von Metadaten muss ebenfalls zuerst über eine Konfiguration ermöglicht werden.
*Tranchen, bzw. Objekte auf der ersten Ebene können nicht dupliziert werden.
*Die Signatur wird 1-1 übernommen. Wird der Schalter duplizieren jedoch mit gedrückter SHIFT Taste aufgerufen, dann kann der Signatur ein zusätzlicher Text nach freier Eingabe angehängt werden.

Über den Schalter 'Fehlend markieren' kann ein Objekt als nicht geliefert / vorhanden markiert werden. Das Objekt wird dabei zum zweiten Ausgang verschoben und der Status auf 'fehlt' gesetzt. Das Objekt kann nun nicht mehr eingechekct werden! <br> '''Ein erneutes drücken des Schalters setzt die Markierung wieder zurück'''

Status:

'neu' Objekte welche eingecheckt werden müssen
'früher eingecheckt' Objekte welche bereits eingecheckt wurden.
'fehlt' Objekte welche nicht vorhanden sind oder nicht geliefert werden.

==Ausgänge==

Der Schritt besitzt zwei Ausgänge.

Eingecheckt - Normalfall nach erfolgtem einbuchen
Objekt fehlt - Objekt wurde als fehlend markiert

==Maske FDO_CheckIn==

[[Datei:FDO CheckIn.png | 800px]]

==Essentielle Felder==
Felder zur Datenbankverbindung wie im Systemtyp 8 SFTP-Upload.

HZ_BEZEICHNUNG ''URL für Postgres DB''
HZ_USERNAME ''Benutzername"
HZ_PASSWORD ''Password"

HZ_HASHTYP ''Duplizieren erlauben''
HZ_KINDERVERDOPPELN ''Bruder erstellen erlauben''
HZ_DY_SEQ1 ''Welcher Objekttyp hat der neue Bruder''

==Pane im Produktionsauftrag (FHK_Maske)==

[[Datei:FHZ STyp013.png | 400px]]

[[Kategorie:Workflowschritt]]

Datei:FDO CheckIn.png

2025-03-05T14:13:12Z

Silvan:

CheckIn Fenster

CheckIn

2025-03-05T14:11:37Z

Silvan: 3487: Essentielle Felder aktualisiert

;Mantiseinträge:
1809
;Systemtyp:
13

==Beschreibung==

Arbeitsschritt der Wareneingangskontrolle.

Arbeitnehmer checkt die Objekte (z.B Boxen) hier in den Workflow ein und erfasst ggf. defekte an den Objekten.

An diesem Schritt können grundsätzlich keine Objekte erstellt werden. Die Objekte müssen zuerst erstellt worden sein und erscheinen dann in der Auswahlliste.

Es besteht die Möglichkeit, das duplizieren von Objekten zu erlauben (HZ Konfiguration), so dass bei unerwartetem Wareneingang oder bei Fehlern in der Vorerfassung, ein am Eingang tatsächlich vorhandenes Objekt gleich in den Workflow eingegliedert werden kann.

*Metadaten werden nicht dupliziert! Diese müssen von Hand eingegeben werden. Die Bearbeitung von Metadaten muss ebenfalls zuerst über eine Konfiguration ermöglicht werden.
*Tranchen, bzw. Objekte auf der ersten Ebene können nicht dupliziert werden.
*Die Signatur wird 1-1 übernommen. Wird der Schalter duplizieren jedoch mit gedrückter SHIFT Taste aufgerufen, dann kann der Signatur ein zusätzlicher Text nach freier Eingabe angehängt werden.

Über den Schalter 'Fehlend markieren' kann ein Objekt als nicht geliefert / vorhanden markiert werden. Das Objekt wird dabei zum zweiten Ausgang verschoben und der Status auf 'fehlt' gesetzt. Das Objekt kann nun nicht mehr eingechekct werden! <br> '''Ein erneutes drücken des Schalters setzt die Markierung wieder zurück'''

Status:

'neu' Objekte welche eingecheckt werden müssen
'früher eingecheckt' Objekte welche bereits eingecheckt wurden.
'fehlt' Objekte welche nicht vorhanden sind oder nicht geliefert werden.

==Ausgänge==

Der Schritt besitzt zwei Ausgänge.

Eingecheckt - Normalfall nach erfolgtem einbuchen
Objekt fehlt - Objekt wurde als fehlend markiert

==Maske FDO_CheckIn==

[[File:FDO_Checkin.png]]

==Essentielle Felder==
Felder zur Datenbankverbindung wie im Systemtyp 8 SFTP-Upload.

HZ_BEZEICHNUNG ''URL für Postgres DB''
HZ_USERNAME ''Benutzername"
HZ_PASSWORD ''Password"

HZ_HASHTYP ''Duplizieren erlauben''
HZ_KINDERVERDOPPELN ''Bruder erstellen erlauben''
HZ_DY_SEQ1 ''Welcher Objekttyp hat der neue Bruder''

==Pane im Produktionsauftrag (FHK_Maske)==

[[Datei:FHZ STyp013.png | 400px]]

[[Kategorie:Workflowschritt]]

CheckIn

2025-03-05T14:10:10Z

Silvan: 3487: Wiki aktualisiert

;Mantiseinträge:
1809
;Systemtyp:
13

==Beschreibung==

Arbeitsschritt der Wareneingangskontrolle.

Arbeitnehmer checkt die Objekte (z.B Boxen) hier in den Workflow ein und erfasst ggf. defekte an den Objekten.

An diesem Schritt können grundsätzlich keine Objekte erstellt werden. Die Objekte müssen zuerst erstellt worden sein und erscheinen dann in der Auswahlliste.

Es besteht die Möglichkeit, das duplizieren von Objekten zu erlauben (HZ Konfiguration), so dass bei unerwartetem Wareneingang oder bei Fehlern in der Vorerfassung, ein am Eingang tatsächlich vorhandenes Objekt gleich in den Workflow eingegliedert werden kann.

*Metadaten werden nicht dupliziert! Diese müssen von Hand eingegeben werden. Die Bearbeitung von Metadaten muss ebenfalls zuerst über eine Konfiguration ermöglicht werden.
*Tranchen, bzw. Objekte auf der ersten Ebene können nicht dupliziert werden.
*Die Signatur wird 1-1 übernommen. Wird der Schalter duplizieren jedoch mit gedrückter SHIFT Taste aufgerufen, dann kann der Signatur ein zusätzlicher Text nach freier Eingabe angehängt werden.

Über den Schalter 'Fehlend markieren' kann ein Objekt als nicht geliefert / vorhanden markiert werden. Das Objekt wird dabei zum zweiten Ausgang verschoben und der Status auf 'fehlt' gesetzt. Das Objekt kann nun nicht mehr eingechekct werden! <br> '''Ein erneutes drücken des Schalters setzt die Markierung wieder zurück'''

Status:

'neu' Objekte welche eingecheckt werden müssen
'früher eingecheckt' Objekte welche bereits eingecheckt wurden.
'fehlt' Objekte welche nicht vorhanden sind oder nicht geliefert werden.

==Ausgänge==

Der Schritt besitzt zwei Ausgänge.

Eingecheckt - Normalfall nach erfolgtem einbuchen
Objekt fehlt - Objekt wurde als fehlend markiert

==Maske FDO_CheckIn==

[[File:FDO_Checkin.png]]

==Essentielle Felder==
Felder zur Datenbankverbindung wie im Systemtyp 8 SFTP-Upload.

HZ_BEZEICHNUNG ''URL für Postgres DB''
HZ_USERNAME ''Benutzername"
HZ_PASSWORD ''Password"

HZ_HASHTYP ''Duplizieren erlauben''

==Pane im Produktionsauftrag (FHK_Maske)==

[[Datei:FHZ STyp013.png | 400px]]

[[Kategorie:Workflowschritt]]

Datei:FHZ STyp013.png

2025-03-05T14:09:28Z

Silvan:

Konfiguration CheckIn

Objekthierarchie ändern

2025-03-05T14:02:43Z

Silvan: /* Konfigurationsfenster im Produktionsauftrag */

;Mantiseinträge:
2237, 3371
;Systemtyp:
44

==Beschreibung==

Weist einem Objekt einen neuen Ahnen zu. Der neue Ahne muss dazu zwingend ein Geschwister des Objektes sein.

;Es gibt dafür vier Varianten:

''1. Älteres Geschwister, welches von einem anderen Objekt-Typ sein muss, finden.''

Für diesen Fall gibt es nur einen Ausgang.

Unter den älteren Geschwistern der DOs wird das nächst älteste gesucht, das einen anderen Typ (DO_DY_SEQ) hat. Also das mit der grössten DO_SEQ davon.

Es werden folglich nur Objekte berücksichtigt, welche bereits vor dem aktuellen Objekt entstanden sind (eine kleine DO_SEQ besitzen, als das Objekt selbst).

Wenn es dieses gibt, dann soll das aktuelle DO zu einem Kind des gefundenen DOs werden.

'''Falls es kein Geschwister gibt bleibt alles wie es ist. Das DO geht auf jeden Fall zum nächsten Schritt.'''

''2. Geschwister über dessen DOSignatur finden. Die Name für die zu suchenden DOSignatur wird aus einem Metadatum des Objektes geholt.''

Dieser Fall besitzt zwei Ausgänge.

Es muss ein Metadatum angegeben werden, in welchem die zu suchende DOSignatur hinterlegt wurde.

Es muss hier genau ein Geschwister vorhanden sein, sonst geht das Objekt zum zweiten Ausgang

'''Nur wenn ein Geschwister gefunden wurde, geht das DO zum nächsten Schritt. Wird kein geschwister gefunden geht das Obhjekt zum Ausgang 2.'''

E.g.: Kein Geschwister mit gesuchter DOSignatur -> DO Fehler. Zwei Geschwister mit gesuchter DOSignatur -> DO Fehler.

Merke: Der DO Typ ist hier nicht relevant. Genausowenig wie die Enstehungsfolge (logisches Alter) der Objekte.

''3. Objekt wird zum Kind seines Grossvaters''

In diesem Fall wird das Kind um eine Ebene nach oben geschoben. Das heisst es wird zum Kind seines Grossvaters oder zum Bruder seines Vaters.

Gibt es kein Grossvater, so landet das Objekt einfach auf der obersten Ebene.

''4. Objekt wird zum Kind eines bestimmen Objektes''

In diesem Fall wird das Objekt zu einem Kind eines spezifisch definierten Vaters. Dazu geben Sie eine Objektnummer im Konfigurationsfenster an. 0 ist auch ein gültiger Wert; Dadurch landet das Objekt auf der obersten Ebene der Projekthierarchie.

Sollte es den konfigurierten, neuen Vater nicht geben, stoppt der Arbeitsschritt mit einem Fehler.

==Essentielle Felder==
HZ_FILEVERHALTEN - Die auszuführende Variante (Checkbox Auswahl 0/1)
HZ_FILENAME - Das Metadatum welches die gesuchte DOSignatur hält
HZ_BARCODEFILEWEG - Objektnummer des neuen Vaters

==Konfigurationsfenster im Produktionsauftrag==

Fall 1: Nur ein Ausgang

[[Datei:FHZ STyp044.png | 500px]]

Fall 2: Zwei Ausgänge

[[Datei:FHZ STyp044 2.png | 500px]]

[[Kategorie:Workflowschritt]]

Datei:FHZ STyp044 2.png

2025-03-05T14:02:21Z

Silvan:

Konfiguration für HZ 44

Datei:FHZ STyp044.png

2025-03-05T14:00:55Z

Silvan:

Konfigurationsfenster für HZ 44

Objekthierarchie ändern

2025-03-05T13:58:37Z

Silvan: /* Beschreibung */

;Mantiseinträge:
2237, 3371
;Systemtyp:
44

==Beschreibung==

Weist einem Objekt einen neuen Ahnen zu. Der neue Ahne muss dazu zwingend ein Geschwister des Objektes sein.

;Es gibt dafür vier Varianten:

''1. Älteres Geschwister, welches von einem anderen Objekt-Typ sein muss, finden.''

Für diesen Fall gibt es nur einen Ausgang.

Unter den älteren Geschwistern der DOs wird das nächst älteste gesucht, das einen anderen Typ (DO_DY_SEQ) hat. Also das mit der grössten DO_SEQ davon.

Es werden folglich nur Objekte berücksichtigt, welche bereits vor dem aktuellen Objekt entstanden sind (eine kleine DO_SEQ besitzen, als das Objekt selbst).

Wenn es dieses gibt, dann soll das aktuelle DO zu einem Kind des gefundenen DOs werden.

'''Falls es kein Geschwister gibt bleibt alles wie es ist. Das DO geht auf jeden Fall zum nächsten Schritt.'''

''2. Geschwister über dessen DOSignatur finden. Die Name für die zu suchenden DOSignatur wird aus einem Metadatum des Objektes geholt.''

Dieser Fall besitzt zwei Ausgänge.

Es muss ein Metadatum angegeben werden, in welchem die zu suchende DOSignatur hinterlegt wurde.

Es muss hier genau ein Geschwister vorhanden sein, sonst geht das Objekt zum zweiten Ausgang

'''Nur wenn ein Geschwister gefunden wurde, geht das DO zum nächsten Schritt. Wird kein geschwister gefunden geht das Obhjekt zum Ausgang 2.'''

E.g.: Kein Geschwister mit gesuchter DOSignatur -> DO Fehler. Zwei Geschwister mit gesuchter DOSignatur -> DO Fehler.

Merke: Der DO Typ ist hier nicht relevant. Genausowenig wie die Enstehungsfolge (logisches Alter) der Objekte.

''3. Objekt wird zum Kind seines Grossvaters''

In diesem Fall wird das Kind um eine Ebene nach oben geschoben. Das heisst es wird zum Kind seines Grossvaters oder zum Bruder seines Vaters.

Gibt es kein Grossvater, so landet das Objekt einfach auf der obersten Ebene.

''4. Objekt wird zum Kind eines bestimmen Objektes''

In diesem Fall wird das Objekt zu einem Kind eines spezifisch definierten Vaters. Dazu geben Sie eine Objektnummer im Konfigurationsfenster an. 0 ist auch ein gültiger Wert; Dadurch landet das Objekt auf der obersten Ebene der Projekthierarchie.

Sollte es den konfigurierten, neuen Vater nicht geben, stoppt der Arbeitsschritt mit einem Fehler.

==Essentielle Felder==
HZ_FILEVERHALTEN - Die auszuführende Variante (Checkbox Auswahl 0/1)
HZ_FILENAME - Das Metadatum welches die gesuchte DOSignatur hält
HZ_BARCODEFILEWEG - Objektnummer des neuen Vaters

==Konfigurationsfenster im Produktionsauftrag==

Fall 1: Nur ein Ausgang

[[File:Objekthierarchie1.png]]

Fall 2: Zwei Ausgänge

[[File:Objekthierarchie.png]]

[[Kategorie:Workflowschritt]]

Objekthierarchie ändern

2025-03-05T13:53:46Z

Silvan: 3488: Wiki aktualisiert

;Mantiseinträge:
2237, 3371
;Systemtyp:
44

==Beschreibung==

Weist einem Objekt einen neuen Ahnen zu. Der neue Ahne muss dazu zwingend ein Geschwister des Objektes sein.

;Es gibt dafür zwei Varianten:

''1. Älteres Geschwister, welches von einem anderen Objekt-Typ sein muss, finden.''

Für diesen Fall gibt es nur einen Ausgang.

Unter den älteren Geschwistern der DOs wird das nächst älteste gesucht, das einen anderen Typ (DO_DY_SEQ) hat. Also das mit der grössten DO_SEQ davon.

Es werden folglich nur Objekte berücksichtigt, welche bereits vor dem aktuellen Objekt entstanden sind (eine kleine DO_SEQ besitzen, als das Objekt selbst).

Wenn es dieses gibt, dann soll das aktuelle DO zu einem Kind des gefundenen DOs werden.

'''Falls es kein Geschwister gibt bleibt alles wie es ist. Das DO geht auf jeden Fall zum nächsten Schritt.'''

''2. Geschwister über dessen DOSignatur finden. Die Name für die zu suchenden DOSignatur wird aus einem Metadatum des Objektes geholt.''

Dieser Fall besitzt zwei Ausgänge.

Es muss ein Metadatum angegeben werden, in welchem die zu suchende DOSignatur hinterlegt wurde.

Es muss hier genau ein Geschwister vorhanden sein, sonst geht das Objekt zum zweiten Ausgang

'''Nur wenn ein Geschwister gefunden wurde, geht das DO zum nächsten Schritt. Wird kein geschwister gefunden geht das Obhjekt zum Ausgang 2.'''

E.g.: Kein Geschwister mit gesuchter DOSignatur -> DO Fehler. Zwei Geschwister mit gesuchter DOSignatur -> DO Fehler.

Merke: Der DO Typ ist hier nicht relevant. Genausowenig wie die Enstehungsfolge (logisches Alter) der Objekte.

==Essentielle Felder==
HZ_FILEVERHALTEN - Die auszuführende Variante (Checkbox Auswahl 0/1)
HZ_FILENAME - Das Metadatum welches die gesuchte DOSignatur hält
HZ_BARCODEFILEWEG - Objektnummer des neuen Vaters

==Konfigurationsfenster im Produktionsauftrag==

Fall 1: Nur ein Ausgang

[[File:Objekthierarchie1.png]]

Fall 2: Zwei Ausgänge

[[File:Objekthierarchie.png]]

[[Kategorie:Workflowschritt]]

Effizienzfaktor Angestellte

2025-02-18T08:41:39Z

Silvan: 3113

=== Fensternamen ===
FAN_Einstell
FAN_Maske1
FAN_ACLSQuotientSpot
FAN_ACLSUbersicht

== Effizienzfaktor ==
Um Vorhersagen über das Fertigstellungsdatum eines Arbeitsschrittes machen zu können, ist es wichtig zu wissen wie viel Arbeit die einzelnen Angestellten an einem bestimmten Tag verrichten. Der Effizienzfaktor soll den Unterschied zwischen den erfassten Leistungen (LS) und den angegebenen Arbeitszeiten im BSB definieren. Ein Effizienzfaktor von 60 % bedeutet, dass 60 % der Zeit welcher der Angestellte im BSB verbringt auch im Helper als Leistung erfasst ist. Das bedeutet wenn der Angestellte XY 8 Stunden im BSB stempelt rechnen wir mit nur 60 % (also 4.8 h) in welchen er wirklich an Objekten arbeitet.

== Globaler Effizienzfaktor ==
===Ort===
Einstellungen -> Personal -> Standardwert für das Verhältnis von Helper Leistungen...

===Beschreibung===
Hier kann ein Globaler Effizienzfaktor (in Prozent) konfiguriert werden. Dieser wird von allen Angestellten verwendet, welche keinen eigenen Effizienzfaktor besitzen.<br>
Beispiel: 75.00 % = 75 % aller Arbeitszeit im BSB ist auch im Helper als Leistung erfasst.

[[Datei:FAN Einstell.png|900px]]

== Effizienzfaktor Angestellter ==
===Ort===
Angestellte -> Menu Angestellte -> Leistung vs. Arbeitszeit Verhältnis

===Beschreibung===
In diesem Fenster können Sie für jeden Angestellten einen eigenen Effizienzfaktor definieren. Mit dem Button "Relevante Angestellte für Produktionsplanung" laden Sie alle Daten der Angestellten, welche die Checkbox "für Termine / Produktion buchbar" markiert haben. Diese Checkbox finden Sie unter Hauptmaske -> Angestellte -> Diverses.

[[Datei:FAN ACLSQuotientSpot.png|900px]]

1: Wählen Sie welche Daten geladen werden sollen (Kann einen Moment dauern)<br>
2: Definieren Sie die 2 Zeiträume. Standardmässig ist Zeitraum 1 immer der letzte Monat und Zeitraum 2 die letzten 3 Monate<br>
3: In dieser Liste sehen Sie alle Angestellte und ihre jeweiligen Effizienzfaktoren in den definierten Zeiträumen. Die letzte Spalte zeigt den aktuellen Faktor oder den Globalen Faktor (Blau).<br>
4: Klicken Sie auf einen Angestellten und Sie können einen neuen Faktor setzten. Mit dem "Archiv"-Button können Sie einen gesetzten Faktor wieder auf den Globalen zurücksetzten.<br>
5: Siehe nächsten Abschnitt<br>

== Aufschlüsselung der Effizienzfaktoren ==
Sie möchten wissen wie der Faktor des Angestellten zustande kommt? Wählen Sie den Angestellten aus und klicken Sie auf den "Info"-Button. In diesem Fenster sehen Sie alle Leistungen sowie alle Arbeitszeiten des Angestellten im ausgewählten Zeitraum.

[[Datei:FAN ACLSUbersicht.png|900px]]

Produktionsauftrag Fortschrittsauswertung

2025-02-03T13:19:18Z

Silvan: /* Ort */

Mithilfe dieses Fensters können Sie sich eine Produktionsauftragsfortschrittsauswertung generieren.

== Ort ==

Um dieses Fenster zu öffnen navigieren sie nach
Hauptmaske -> Produktionsaufträge -> Fortschrittsbericht erstellen

== Konfiguration ==
Es ist wichtig alle Konfiguration abzuschliessen, bevor Sie sich auf die Zahlen der Auswertung verlassen!

=== Produktionsauftrag Stammdaten ===

* Setzten Sie einen Endtermin für den Auftrag
* Verknüpfen Sie einen Kunden mit dem Auftrag
* Wählen Sie eine Ansprechperson für den Auftrag
* Geben Sie die geschätzte Gesamtanzahl der Objekte aller Objekttypen an

=== Aufträge ===
Verknüpfen Sie alle Aufträge mit dem Produktionsauftrag. Navigieren Sie dazu nach Hauptmaske -> Aufträge -> Kopfdaten und füllen Sie das Feld "Prod. Auftrag" aus. Drücken Sie die "Insert" Taste für ein einfaches Auswählen des Produktionauftrags.

Produktionsauftrag Fortschrittsauswertung

2025-02-03T13:16:36Z

Silvan: /* Produktionsauftrag Stammdaten */

Mithilfe dieses Fensters können Sie sich eine Produktionsauftragsfortschrittsauswertung generieren.

== Ort ==

Um dieses Fenster zu öffnen navigieren sie nach
Hauptmaske -> Produktionsaufträge -> Fortschrittsauswertung

== Konfiguration ==
Es ist wichtig alle Konfiguration abzuschliessen, bevor Sie sich auf die Zahlen der Auswertung verlassen!

=== Produktionsauftrag Stammdaten ===

* Setzten Sie einen Endtermin für den Auftrag
* Verknüpfen Sie einen Kunden mit dem Auftrag
* Wählen Sie eine Ansprechperson für den Auftrag
* Geben Sie die geschätzte Gesamtanzahl der Objekte aller Objekttypen an

=== Aufträge ===
Verknüpfen Sie alle Aufträge mit dem Produktionsauftrag. Navigieren Sie dazu nach Hauptmaske -> Aufträge -> Kopfdaten und füllen Sie das Feld "Prod. Auftrag" aus. Drücken Sie die "Insert" Taste für ein einfaches Auswählen des Produktionauftrags.

Produktionsauftrag Fortschrittsauswertung

2025-02-03T12:46:51Z

Silvan: 3113: Neue Wikiseite

Mithilfe dieses Fensters können Sie sich eine Produktionsauftragsfortschrittsauswertung generieren.

== Ort ==

Um dieses Fenster zu öffnen navigieren sie nach
Hauptmaske -> Produktionsaufträge -> Fortschrittsauswertung

== Konfiguration ==
Es ist wichtig alle Konfiguration abzuschliessen, bevor Sie sich auf die Zahlen der Auswertung verlassen!

=== Produktionsauftrag Stammdaten ===

* Setzten Sie einen Endtermin für den Auftrag
* Verknüpfen Sie einen Kunden mit dem Auftrag
* Wählen Sie eine Ansprechperson für den Auftrag

=== Aufträge ===
Verknüpfen Sie alle Aufträge mit dem Produktionsauftrag. Navigieren Sie dazu nach Hauptmaske -> Aufträge -> Kopfdaten und füllen Sie das Feld "Prod. Auftrag" aus. Drücken Sie die "Insert" Taste für ein einfaches Auswählen des Produktionauftrags.

Cockpit

2025-02-03T12:29:28Z

Silvan: /* Daten Anzeigen */

Das Cockpit dient zur Planung von Produktionsaufträgen sowie dem Managen von Ressourcen. Es besteht aus mehreren Modulen:

=== Konfiguration ===
* [[Ressourcenzuweisung]]
* [[Effizienzfaktor Angestellte]]
* [[Planung von Produktionsaufträgen]]

=== Daten Anzeigen ===
* [[Planungsübersicht]]
* [[Produktionsauftrag Fortschrittsauswertung]]

Es ist wichtig in allen oben aufgeführten Modulen jegliche Zahlen zu konfigurieren. Falls Zahlen fehlen, kann es zu falschen Berechnungen kommen!