Druckaufträge und lokale Druck-Agenten steuern

Zweck und Einsatzbereich

Mit einem lokalen Druck-Agenten sollen Aktendeckel und Dokumente aus einer Ocean-Akte ohne den Druckdialog des Browsers auf einen benannten Büro-Drucker gesendet werden. Der Agent ist ein eigenständiges Windows-Skript auf einem Rechner im Büronetz. Er ist weder Bestandteil der NeuraPort-Desktop-App noch ein im Browser installierter Druckertreiber.

Für den normalen Arbeitsplatz stehen zwei getrennte Wege bereit:

Im Browser drucken lädt die Datei in den Browser und verwendet dessen Druckdialog. Dafür ist kein Agent erforderlich.
An Drucker senden legt einen Auftrag für einen vorher eingerichteten Büro-Agenten an. Erst der lokale Agent lädt die Datei und übergibt sie an die Drucksoftware.

Der direkte Agent-Druck ist im geprüften Stand noch nicht als produktionsbereit belegt: Die Serverfreigabe verlangt neben dem Agent-Token eine gültige angemeldete Benutzersitzung, der ausgelieferte Windows-Agent kann diese zusätzliche Anmeldung jedoch nicht konfigurieren. Mit seiner dokumentierten Standardkonfiguration erhält er deshalb Nicht authentifiziert. Verwenden Sie bis zur Korrektur den Browser-Druck und nehmen Sie den Agenten nicht ohne einen freigegebenen Integrationstest in den laufenden Betrieb.

Voraussetzungen und Berechtigungen

Für den Browser-Druck benötigen Sie Zugriff auf die gespeicherte Akte und das betreffende Dokument. Für einen Agent-Auftrag verlangt der Server zusätzlich Dokumente lesen und mindestens ein in der aktuellen Organisationseinheit schreibend nutzbares Produktmodul. Die Elternakte wird vor dem Auftrag auf Mandant und Organisationseinheit geprüft.

Aufgabe	Berechtigung und aktuelle Oberflächengrenze
Agenten anlegen, auflisten und löschen	Serverseitig ADMIN oder MANAGER; die Einstellungsseite wird im Hauptfrontend nur ADMIN angezeigt.
Agenten und Drucker im Aktenarbeitsplatz auswählen	Die Agentenliste ist ebenfalls auf ADMIN und MANAGER begrenzt. Andere Dokumentbenutzer sehen den Agent-Direktdruck nicht zuverlässig oder erhalten die allgemeine Meldung, dass der Agent nicht verfügbar ist.
Aktendeckel oder Aktendokument als Auftrag einstellen	Dokumente lesen, Zugriff auf die Elternakte und schreibender Lizenzstatus für mindestens ein aktives Modul. Individuelle Rollen können abweichen.
Auftragsliste lesen	Dokumente lesen; normale Benutzer sehen nur Aufträge aus ihrer aktuellen oder zusätzlich zugewiesenen Organisationseinheit, ADMIN und MANAGER alle Einheiten ihres Mandanten. Im aktuellen Hauptfrontend gibt es dafür keine Ansicht.
Aufträge abholen und Status melden	Aktiver Agent-Token und derzeit zusätzlich eine gültige Benutzeranmeldung mit passender Modullizenz. Diese zweite Voraussetzung wird vom ausgelieferten Agenten nicht erfüllt.

Ein Agent gehört zum gesamten Mandanten, nicht zu einer einzelnen Organisationseinheit. Er kann daher alle an ihn gerichteten Aufträge dieses Mandanten abholen, auch wenn deren Akten aus verschiedenen Einheiten stammen. Benutzer dürfen einen Auftrag nur aus einer für sie autorisierten Elternakte erzeugen. Eine bekannte Akten-, Dokument-, Agent- oder Auftragsnummer hebt diese Prüfung nicht auf. Plattformadministratoren besitzen in diesem Ablauf keinen normalen Mandantenkontext.

Für den lokalen Betrieb sind nach dem mitgelieferten Installationsmodell ein Windows-Rechner, Python ab Version 3.10, die Pakete requests und pywin32, SumatraPDF sowie ein erreichbarer, unter Windows eingerichteter Drucker vorgesehen. Der Rechner benötigt ausgehenden HTTPS-Zugriff auf die NeuraPort-Domain; ein eingehender Port im Büronetz ist nicht vorgesehen. Ob Python, SumatraPDF und der vorgeschlagene Windows-Dienst in Ihrer verwalteten Arbeitsplatzumgebung zulässig sind, muss die eigene IT vorab freigeben.

Schritt-für-Schritt-Anleitung

Agent als Organisationadmin vorbereiten

Melden Sie sich mit der Standardrolle ADMIN an und öffnen Sie Einstellungen → Druck-Agenten.
Tragen Sie einen eindeutigen Namen ein, zum Beispiel den Standort und den verwalteten Rechner, und wählen Sie Agent anlegen.
Sichern Sie den angezeigten Agent-Token sofort im freigegebenen Geheimnisspeicher. Er wird nur dieses eine Mal angezeigt.
Installieren Sie den bereitgestellten Windows-Agenten ausschließlich auf einem administrativ verwalteten Rechner. Hinterlegen Sie NeuraPort-URL, Agent-Token und den Pfad zu SumatraPDF in der geschützten Dienstkonfiguration.
Starten Sie den Agenten. Er soll seine Windows-Drucker melden und anschließend in Einstellungen → Druck-Agenten als online erscheinen.
Prüfen Sie die gemeldeten Druckernamen. Verwenden Sie einen eigenen Testdrucker und ausschließlich ein synthetisches Testdokument.
Brechen Sie die Inbetriebnahme ab, wenn das Agentprotokoll Nicht authentifiziert meldet. Der geprüfte Standardagent unterstützt die dafür zusätzlich verlangte Benutzeranmeldung nicht; ein Agent-Token allein genügt derzeit nicht.

Geben Sie den Agent-Token niemals weiter und nehmen Sie ihn nicht ungeschützt in Backups, Supportpakete oder Nachrichten auf. Bei Verlust oder Verdacht auf Offenlegung löschen Sie den Agenten in NeuraPort und stellen einen neuen Zugang aus.

Aktendeckel an einen Büro-Drucker senden

Öffnen Sie über Arbeitsbereich → Ocean Export → Akten oder Arbeitsbereich → Ocean Import → Import-Akten eine gespeicherte und für Sie berechtigte Akte.
Wechseln Sie zu Dokumente und suchen Sie den Bereich Aktendeckel drucken.
Wählen Sie A3 (faltbar) oder A4.
Kontrollieren Sie vor einem Direktdruck in den Einstellungen, dass der vorgesehene Agent tatsächlich online ist. Die Aktenmaske kann auch einen inzwischen nicht mehr verbundenen Agenten anbieten.
Wählen Sie unter An Drucker senden zuerst den Agenten, dann einen gemeldeten Drucker und anschließend Senden.
Die Meldung An „…“ gesendet bestätigt nur, dass der Auftrag in die Warteschlange aufgenommen wurde. Sie bestätigt weder den Ausdruck noch eine physisch ausgegebene Seite.
Verwenden Sie Im Browser drucken, wenn kein Agent wählbar ist oder der Integrationstest noch aussteht. Mit PDF öffnen können Sie den Aktendeckel vorab kontrollieren.

Ein Aktendokument senden

Öffnen Sie in derselben Akte die Dokumentenliste.
Prüfen Sie das Dokument vor dem Druck über PDF ansehen oder Herunterladen.
Wählen Sie am Dokument An Büro-Drucker senden.
Geben Sie im eingeblendeten Auswahldialog die Nummer eines Agenten ein und bestätigen Sie den vorgeschlagenen oder einen anderen gemeldeten Drucker.
Warten Sie auf An … gesendet. Auch diese Meldung bestätigt nur das Einstellen des Auftrags.

Der Windows-Agent ist technisch auf stillen PDF-Druck mit SumatraPDF ausgelegt. Die Schaltfläche wird derzeit jedoch auch für DOCX-, Tabellen- und Bilddateien angeboten, und der Server kennzeichnet jeden Abruf als PDF. Senden Sie über diesen Weg bis zur Korrektur ausschließlich geprüfte PDF-Dateien. Für andere Formate verwenden Sie Download und die dafür vorgesehene lokale Anwendung.

Agent überwachen, widerrufen und einen Fehler behandeln

Öffnen Sie als ADMIN Einstellungen → Druck-Agenten.
Prüfen Sie online/offline, Zuletzt gesehen und die gemeldeten Drucker. online bedeutet in der Oberfläche lediglich, dass innerhalb der letzten zwei Minuten ein Heartbeat einging.
Prüfen Sie bei Fehlern zusätzlich die Konsole beziehungsweise das freigegebene Dienstprotokoll des Windows-Rechners. Auftragsstatus und Fehlermeldung sind im Hauptfrontend derzeit nicht sichtbar.
Ein Auftrag im Zustand FETCHED, dessen Agent danach ausfällt, wird nicht automatisch erneut angeboten. Nach Ursachenklärung muss ein neuer Auftrag angelegt werden.
Löschen Sie einen Agenten nur nach Bestätigung, dass keine benötigten Aufträge mehr daran hängen. Das Löschen widerruft seinen Zugang und entfernt zugleich die zugehörigen Auftragsdatensätze.

Feldreferenz

Feld	Pflicht	Bedeutung	Validierung
Agentenname	Ja	Verständliche Bezeichnung des lokalen Agenten	2 bis 255 Zeichen; keine technische Eindeutigkeit des Namens belegt.
Agent-Token	Ja, lokal	Einmalig angezeigtes Geheimnis zur Identifikation des Agenten	Sofort sicher hinterlegen, niemals weitergeben und bei Verlust oder möglicher Offenlegung durch einen neuen Agentenzugang ersetzen.
NeuraPort-URL	Ja, lokal	Basisadresse, zu der der Agent ausgehend verbindet	Muss eine erreichbare freigegebene HTTPS-Adresse sein; der Agent entfernt einen abschließenden Schrägstrich.
Sumatra-Pfad	Ja für stillen Druck	Lokaler Pfad zur PDF-Druckanwendung	Muss auf eine vorhandene ausführbare Datei zeigen; andernfalls wird der Auftrag als Fehler behandelt.
Abfrageintervall	Lokal optional	Pause zwischen zwei Agentdurchläufen	Standard 5 Sekunden; die lokale Konfiguration prüft keinen sicheren Mindest- oder Höchstwert.
Druckerliste	Durch Heartbeat	Vom Windows-Rechner gemeldete lokale und verbundene Drucker	Keine belegte Anzahl- oder Zeichenlängenprüfung je Eintrag; veraltete Namen bleiben bis zum nächsten erfolgreichen Heartbeat sichtbar.
Zuletzt gesehen	Systemseitig	Zeitpunkt des letzten erfolgreichen Heartbeats	Die Oberfläche wertet weniger als 120 Sekunden als online; Client- und Serveruhr können die Anzeige beeinflussen.
Agent	Ja beim Auftrag	Empfänger des Druckauftrags	Muss zum selben Mandanten gehören; die Auswahl ist im Hauptfrontend nur für ADMIN und MANAGER abrufbar.
Drucker	Ja beim Auftrag	Exakter Windows-Druckername, an den der Agent übergibt	Höchstens 255 Zeichen; der Server prüft nicht, ob der Name aktuell vom gewählten Agenten gemeldet wurde.
Dokumentart	Ja	Aktendeckel oder Aktendokument	Andere Werte werden abgewiesen; Aktendeckel benötigen eine Akte, Aktendokumente ein autorisiertes Dokument.
Akte und Dokument	Je nach Dokumentart	Elternbezug des zu druckenden Inhalts	Mandant und Organisationseinheit werden über die Elternakte geprüft; bei beiden Angaben müssen Dokument und Akte zusammengehören.
Format	Für Aktendeckel in der Oberfläche	A3 quer beziehungsweise A4 hoch	Die Oberfläche bietet A3 und A4. Ein anderer technisch übermittelter Wert wird nicht abgewiesen, sondern wie A3 behandelt.
Kopien	Technisch optional	Anzahl der Druckdurchläufe	1 bis 50; das Hauptfrontend bietet dafür derzeit kein Feld und verwendet daher 1.
Fehlertext	Bei FAILED optional	Vom lokalen Agenten gemeldete Ursache	Keine belegte serverseitige Längenbegrenzung; kann lokale technische Details enthalten und gehört nicht in Supportexporte ohne Prüfung.

Status und mögliche Übergänge

Objekt	Ausgang	Ereignis	Ergebnis
Agent	Neu angelegt	Noch kein erfolgreicher Heartbeat	offline, keine Drucker gemeldet
Agent	offline	Heartbeat erreicht den Server	Druckerliste und Zuletzt gesehen werden aktualisiert; für etwa zwei Minuten zeigt die Oberfläche online
Agent	online	Mehr als zwei Minuten kein Heartbeat	Oberfläche zeigt offline; der Agent bleibt technisch aktiv und weiterhin auswählbar
Agent	aktiv	Löschen bestätigt	Agentenzugang wird ungültig; zugehörige Aufträge werden ebenfalls gelöscht
Druckauftrag	Noch nicht vorhanden	Senden wird akzeptiert	PENDING
Druckauftrag	PENDING	Agent fragt offene Aufträge ab	FETCHED, noch bevor Dateiabruf und Druck erfolgreich sind
Druckauftrag	FETCHED	Lokale Drucksoftware beendet den Aufruf ohne Fehler	PRINTED
Druckauftrag	FETCHED	Download, Datei, Drucker, SumatraPDF oder lokaler Aufruf schlägt fehl	FAILED mit optionalem Fehlertext

Es gibt keine belegten Übergänge für Abbrechen, manuelles Wiederholen, Zurückstellen oder automatisches Wiederaufnehmen. PRINTED bedeutet nur, dass der lokale Druckprozess ohne gemeldeten Programmfehler endete; Papierstand, Toner, Warteschlange und tatsächliche physische Ausgabe werden nicht bestätigt. Der Server verhindert außerdem nicht zuverlässig, dass ein Agent einen bereits endgültigen Status erneut überschreibt.

Was im Hintergrund passiert

Der lokale Agent stellt ausschließlich ausgehende Verbindungen her. In jedem Durchlauf meldet er zuerst die aktuell unter Windows gefundenen Drucker, holt danach bis zu 20 wartende Aufträge, lädt jeden Inhalt in eine temporäre Datei und ruft SumatraPDF für den gewählten Drucker pro Kopie auf. Anschließend meldet er PRINTED oder FAILED. TLS-Zertifikate werden über die verwendete HTTPS-Bibliothek regulär geprüft; eine zusätzliche Inhaltsignatur oder Prüfsumme des Druckdokuments ist nicht belegt.

Ein Agent erhält nur die ihm zugeordneten Aufträge, gehört aber keiner einzelnen Organisationseinheit an. Seine Aufträge können daher aus allen Einheiten des Mandanten stammen. Betreiben Sie den Agenten nur auf einem geschützten Rechner und behandeln Sie dort verarbeitete Dokumente wie andere vertrauliche Akteninhalte.

Ein Auftrag enthält Referenzen auf Akte oder Dokument, aber keine unveränderliche Kopie des Druckinhalts. Der Aktendeckel wird erst beim Abruf aus dem dann aktuellen Aktenstand erzeugt. Bei einem Aktendokument wird ebenfalls die zu diesem Zeitpunkt aktuelle gespeicherte Datei gelesen. Änderungen oder Löschungen zwischen Senden und Abruf können daher zu anderem Inhalt oder einem Fehler führen.

Zwei gleichzeitig laufende Instanzen desselben Agenten können denselben Auftrag erhalten und doppelt drucken. Nach der frühen Umstellung auf FETCHED existiert kein automatischer Rückweg zu PENDING. Betreiben Sie deshalb nie zwei Prozesse mit demselben Agentenzugang und werten Sie die aktuelle Warteschlange nicht als verlässliches Wiederholungs- oder Archivsystem.

Das Backend kann Auftragsstatus und Fehler speichern und nach Organisationseinheit filtern. Obwohl die Browseranbindung eine Auftragsliste vorsieht, wird sie in keiner geprüften Hauptansicht dargestellt. Es gibt somit derzeit keine zentrale Benutzeroberfläche für Druckhistorie, Bestätigung, Fehler, Wiederholung oder Audit. Auch die allgemeine NeuraPort-Desktop-/Citrix-Anwendung startet den Windows-Druck-Agenten nicht automatisch.

Typische Fehler und Lösungen

Meldung oder Beobachtung	Ursache	Lösung
Nicht authentifiziert im Agentprotokoll	Der Server verlangt zusätzlich zum Agent-Token eine gültige Benutzeranmeldung; der ausgelieferte Agent sendet sie nicht.	Agent-Direktdruck nicht produktiv verwenden. Browser-Druck nutzen und die Protokollanmeldung vor einem neuen Integrationstest korrigieren lassen.
Ungueltiger Agent-Token	Zugangsdaten falsch, Agent gelöscht oder falsche Umgebung/Domain verwendet	Eingabe und Zielumgebung prüfen. Geheimnis nicht offenlegen; bei Verlust Agent löschen und neu anlegen.
Agent bleibt offline	Kein erfolgreicher Heartbeat, falsche URL, Netzwerk-/Zertifikatsproblem, abgelaufene Zusatzanmeldung oder Prozess nicht gestartet	Lokales Dienstprotokoll, HTTPS-Erreichbarkeit, Systemzeit und freigegebene Konfiguration prüfen; keine Zertifikatsprüfung abschalten.
In der Akte erscheint kein Bereich An Drucker senden	Benutzer darf Agenten nicht auflisten, kein Agent wurde gemeldet oder die Liste konnte nicht geladen werden	Mit ADMIN oder MANAGER prüfen, Agentstatus kontrollieren und bis dahin Im Browser drucken verwenden.
Druck-Agent ist nicht verfügbar	Dokumentenansicht konnte Agenten/Drucker nicht laden oder die Auswahl wurde ungültig	Agent in den Einstellungen auf online und gemeldete Drucker prüfen; Rolle und Lizenzstatus kontrollieren.
Senden an Agent fehlgeschlagen	Akte/Dokument nicht autorisiert, Modullizenz nur lesbar, Agent fremd oder gelöscht oder Server nicht erreichbar	Aktuelle OE, Dokumentrecht, Lizenz und Agentstatus prüfen; Auftrag nicht durch Ändern einer ID umgehen.
Erfolgsmeldung, aber kein Ausdruck	Meldung bestätigt nur PENDING; Agent kann offline sein oder später scheitern	Agent- und Windows-Protokoll sowie Druckerwarteschlange prüfen. Da die Fehleransicht fehlt, bei Unsicherheit Browser-Druck mit Sichtkontrolle verwenden.
Auftrag bleibt nach Agentstart unbearbeitet	Ein früherer Abruf hat ihn bereits auf FETCHED gesetzt; automatische Rückstellung fehlt	Ursache im Agentprotokoll klären und danach einen neuen Auftrag anlegen; Doppeldruck vorher ausschließen.
Dokumentdruck endet bei DOCX, XLSX oder Bild mit Fehler	Der Agent übergibt jeden Inhalt als PDF an SumatraPDF	Nur echte, vorab geprüfte PDFs direkt senden; anderes Format herunterladen und in der passenden Anwendung drucken.
Falsches oder veraltetes Dokument wird gedruckt	Inhalt wird erst beim Abruf aus dem aktuellen Akten-/Dokumentstand ermittelt	Auftrag erst nach finaler Inhaltskontrolle senden und während des Drucks keine Version wechseln.
Dasselbe Dokument wird zweimal gedruckt	Zwei Agentinstanzen verwenden denselben Zugang und bearbeiten den Auftrag gleichzeitig	Je Agentenzugang genau einen Prozess betreiben; zweiten Prozess stoppen und Zugang bei unklarer Verteilung neu ausstellen.
PRINTED, aber am Drucker fehlt Papierausgabe	Status bestätigt nur den erfolgreichen lokalen Programmaufruf	Windows-Druckerwarteschlange, Papier, Toner und Gerät prüfen; erforderlichenfalls kontrollierten Browser-Druck erstellen.
Gewünschter Drucker fehlt oder alter Drucker bleibt sichtbar	Heartbeats melden die aktuelle Windows-Liste; ohne erfolgreichen neuen Heartbeat bleibt die letzte Liste bestehen	Drucker unter dem Dienstkonto installieren/entfernen, Agent neu starten und Zuletzt gesehen kontrollieren.
Nach Löschen des Agenten fehlt auch die Auftragshistorie	Agent und zugehörige Aufträge werden gemeinsam gelöscht	Vor Löschen fachlich prüfen; die Warteschlange nicht als Aufbewahrungs- oder Auditnachweis verwenden.