cmi-webapi-forms

Diese Komponente ist zurzeit für verschiedene Aufgaben vorgesehen. Es werden Formulardaten von Anthrazit und JaxForms entgegengenommen und daraus Geschäfte oder Posteingänge im CMI generiert. Zudem gibt es für die PhZh separate Funktionen für die Erstellung von Posteingängen. Neu sind im CmiController auch generische Endpunkte definiert für die Kommunikation mit dem CMI Server Service. In Zukunft sollten nur noch diese verwendet werden.

Inhaltsverzeichnis

• Allgemeine Informationen
• Technische Informationen
• Installation & Konfiguration
• Troubleshooting / Mögliche Fehlerquellen

Allgemeines

• Status: Freigegeben
• Fachliche Ansprechperson: Martina Brajkovic
• Technische Ansprechperson: Milan Bursac, Benjamin Schäublin, Micha Aepli, Abdu Almaz
• Nur für speziellen Kunden: PhZh, Anthrazit und JaxForms sind Kundenprojekte / CmiController kann für alle Kunden verwendet werden.

Strategische Einordnung

Zurzeit sind verschiedene Controller als Kundenprojekt implementiert: * AnthrazitController * JaxFormsController * PhZhController * BurgergemeindeController

Diese sollten nach Möglichkeit nicht mehr verwendet werden. Neu soll der CmiController für die Kommunikation mit dem CMI Server Service genutzt werden.

Technisches

webapi.forms ist ein Windows-Service der einen Webservice mit diversen Endpunkten startet.

Eigenschaften

Die Komponente erfüllt folgende Eigenschaften:

• Stateless: Als stateless REST Service implementiert (wurde nicht getestet)
• Skalierbar/Multiinstanzfähig: Ja (wurde nicht getestet)
• Mehrmandantenfähig: nein, es kann nur ein CMI Server Service hinterlegt werden
• Proxyfähig: Ja, kann im appsettings.json definiert werden

Abhängigkeiten

AnthrazitController

Service	Version	Anbindung	Protokoll	Standardports	Verfügbarkeit	Fehlertoleranzklasse
Anthrazit Formular	?	on request	HTTP/S	?	muss	Absturz
CMI Server Service	?	on request	HTTP/S	10003,10004	muss	Reconnect

JaxFormsController

Service	Version	Anbindung	Protokoll	Standardports	Verfügbarkeit	Fehlertoleranzklasse
Jax Forms Formular	?	on request	HTTP/S	?	muss	Absturz
CMI Server Service	?	on request	HTTP/S	10003,10004	muss	Reconnect

CmiController

Service	Version	Anbindung	Protokoll	Standardports	Verfügbarkeit	Fehlertoleranzklasse
CMI Server Service	19.8	on request	HTTP/S	10003,10004	muss	Reconnect

Fehlertoleranz

Wenn der CMI Server Service nicht erreichbar ist, können die Requests nicht erfolgreich abgesetzt werden. Die API gibt dann einen Error zurück.

Wenn im JaxForms oder Anthrazit ein Request abgesetzt wird, muss das CMI Forms API erreichbar sein.

Technologie Stack

Folgende Technologien werden eingesetzt: * ASP.NET Core 6.0

Installation

Informationen zur Installation der Komponente.

Systemvoraussetzungen

Das Kapitel zeigt, welche Komponenten auf dem System installiert sein müssen.

Betrieb via IIS: * ASP.NET Core 6.0 Runtime * IIS Feature Rewrite Module

Betrieb als Windows Service: Keine

Installationsanleitung

Vollständige Anleitung zur Installation der Komponente inklusive benötigter Services.

Entwicklerhinweise

Für Neuentwicklungen nur noch den CmiController verwenden.

Konfigurationsmöglichkeiten

Folgende Konfigurationen sind möglich und können in der Konfigurationsdatei appsettings.json gesetzt werden.

ApiConfiguration

"ApiConfiguration": {
    "UseClientTokens": false,
    "IpWhitelist": "::1;127.0.0.1",
    "WriteDownJson": false,
    "PathToJsonFolder": "C:\\Forms\\Json",
    "CorsAllowedOrigins": "http://localhost:4200;http://localhost:5000"
}

• UseClientTokens: Wenn true wird erwartet, dass jeder Request bereits ein Bearer Token vom STS enthält. Dieses Token wird dann mittels cmi-common-webapi-core validiert.

• IpWhitelist: Die IP's werden Semikolon separiert aufgelistet. Mit einem * werden alle IP's akzeptiert.

• WriteDownJson: Gibt an, ob die eingegangenen Formulare in Text-Dateien abgespeichert werden oder nicht.

• PathToJsonFolder: Pfad zum Ordner, unter welchem die eingegangenen Formulare abgespeichert werden.

• CorsAllowedOrigins: Die Origins werden Semikolon separiert aufgelistet. Mit einem * werden alle Origins akzeptiert.

ServerService

"ServerService": {
    "StsBaseUrl": "",
    "ClientSecret": 123,
    "AcrValues": "tenant:cmi_ag_local",
    "PrivateUrl": "http://localhost:10003",
    "User": "admin",
    "Password": "123",
    "CheckInComment": "First Check-In",
    "DocumentVersion": "Zwischenversion"
}

• StsBaseUrl (ehemals StsTokenEndpoint): Basis URL des Security Token Service (STS).

• ClientSecret: Client-Secret für die impersonierte Authentifizierung (Wird bei den STS-Konfiguration gesetzt)

• AcrValues: Name des Tenants. Dem Mandanten-Namen muss tenant: vorangestellt werden

• PrivateUrl: URL zum CMI Server Service. Die URL muss auf dem Owin-Privateport gerichtet sein

• User: Name des technischen CMI Benutzers

• Password: Passwort des technischen CMI Benutzers

• CheckInComment: CheckIn-Kommentar für die erstellten Dokumente

• DocumentVersion: Dokument-Version für die erstellten Dokumente. (Mögliche Werte: Unbekannt, Zwischenversion, Hauptversion, Schlussversion)

Serilog

Serilog bietet eine Diagnoseprotokollierung der Applikation für Dateien. Weiterführende Informationen finden Sie unter GitHub-Serilog.

"Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Debug",
        "System": "Debug"
      }
    },
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "C:\\temp\\logs\\forms\\forms-log.log",
          "rollingInterval": "Day"
        }
      },
      { 
        "Name": "Console" 
      }
    ]
}

• MinimulLevel: Minimum der Protokollereignisebenen. (Mögliche Werte: Verbose, Debug, Information, Warning, Error, Fatal)

• Path: Der Pfad zum Logging File

JaxForms

"JaxForms": {
    "ApiUrl": "https://cmi.jaxforms.com/formservice/services/rest",
    "token": "4c72b3c4-cb86-4a57-a9e4-83277cea27d0"
}

• ApiUrl: URL der JaxForms-API

• token: Token eines JaxForms-Benutzers (Wird für die API benötigt)

Proxy

"Proxy": {
    "UseProxy": false,
    "ProxyUrl": "http://localhost:808",
    "BypassOnLocal": false,
    "BypassList": [
    ]
} 

• UseProxy: true wenn ein Proxy verwendet werden soll

• ProxyUrl: URL des Proxy Servers

• BypassOnLocal: true wenn alle lokalen Requests nich über den Proxy laufen sollen

• BypassList: Array Liste mit allen Hosts die nicht über den Proxy laufen sollen

Troubleshooting