Connected Services

Ein Connected Service ist ein konfigurierter externer Dienst, gegen den sich primedocs im Namen des Benutzers authentifiziert (z.B. via OAuth-Login). Statt Zugangsdaten in einzelnen Konfigurationen zu hinterlegen, referenzieren die Funktionen einen Connected Service über dessen ConnectedServiceKey. Die Anmeldung erfolgt einmal pro Benutzer und Dienst und wird anschliessend wiederverwendet.

Connected Services werden durch den Datasource-Administrator verwaltet (Name, Schlüssel, Endpunkte). Jeder Dienst hat einen eindeutigen Key, einen Anzeigenamen und einen benutzerbezogenen Anmeldestatus.

Konfiguration im DataSource-Admin

Connected Services werden im DataSource-Admin unter Settings → Connected Services verwaltet. Pro Dienst werden folgende Angaben gepflegt:

Feld	Beschreibung
Name	Anzeigename des Dienstes.
Key	Eindeutiger Schlüssel, über den Funktionen den Dienst referenzieren (ConnectedServiceKey).
Description	Optionale Beschreibung.
Active	Aktiviert bzw. deaktiviert den Dienst.
Configuration	XML-Konfiguration des Dienstes (z.B. <OAuth authorizeUri="…" …>).

Funktionsweise (OAuth 2.0)

Connected Services nutzen den OAuth-2.0-Authorization-Code-Flow:

1. Eine Funktion (z.B. HttpDataProvider oder ein InvokeUrl-Command) referenziert einen Connected Service über ConnectedServiceKey.
2. Ist der Benutzer für diesen Dienst noch nicht angemeldet, leitet primedocs Web ihn zum Autorisierungsendpunkt des externen Dienstes weiter.
3. Nach erfolgreicher Anmeldung ruft der Dienst die Rücksprungadresse von primedocs auf, primedocs tauscht den Code gegen ein Access-Token und legt es pro Benutzer und Dienst serverseitig ab.
4. Bei späteren Aufrufen wird das gespeicherte Token automatisch wiederverwendet (bzw. erneuert).

Registrierung beim externen Dienst

Bei der Registrierung der primedocs-Anwendung im externen Dienst (z.B. als App-Registrierung) muss folgende Rücksprung-/Redirect-URI hinterlegt werden:

https://{instanz}/app/web/connectedservices/connectedservice-oauthcallback

Der OAuth-state transportiert dabei intern die Zuordnungsinformationen, damit primedocs den Rücksprung dem richtigen Kontext zuordnen kann:

Feld	Bedeutung
LoginId	Identifiziert den angemeldeten Benutzer/Login.
ConnectedServiceId	Der betroffene Connected Service.
DataSourceId	Die Datasource (Mandant).

Die Connected Services selbst (Name, Key, Endpunkte, Client-ID/Secret) werden im Dashboard durch den Datasource-Administrator konfiguriert.

«Login erforderlich»

Greift eine Funktion auf einen Connected Service zu, für den der Benutzer noch nicht angemeldet ist, zeigt primedocs Web einen Anmelde-Banner an. Erst nach erfolgreicher Anmeldung wird die Aktion (z.B. Dokumentgenerierung oder Datenabruf) ausgeführt.

Verwendung

Ein Connected Service wird über das Attribut ConnectedServiceKey referenziert. Folgende Stellen unterstützen Connected Services:

Einsatzort	Beschreibung
InvokeUrl-Command	Authentifiziert die mehrstufigen HTTP-Aufrufe nach der Dokumentgenerierung.
HttpDataProvider	Authentifiziert den Datenabruf aus einer HTTP-/REST-API.
Connect Session / Connect Session Templates	Authentifiziert Initializer und InvokeUrl-Commands einer Session — die Ausführung (/Execute) erfolgt im Kontext des angemeldeten Benutzers.

<HttpDataProvider DisplayName="CRM" ConnectedServiceKey="Crm.OAuth">
  ...
</HttpDataProvider>

Zugriffstoken verwenden

Innerhalb einer Konfiguration, die einen Connected Service referenziert, kann das Access-Token über den Platzhalter {__ConnectedService.AccessToken__} eingesetzt werden — typischerweise im Authorization-Header. primedocs ersetzt den Platzhalter zur Laufzeit durch das gültige Token des angemeldeten Benutzers:

<HttpDataProvider DisplayName="CRM" ConnectedServiceKey="Crm.OAuth">
  <Configuration>
    <Step>
      <Request Method="Get">
        <Url>https://crm.example.com/api/contacts</Url>
        <Header Name="Authorization" Value="Bearer {__ConnectedService.AccessToken__}" />
      </Request>
    </Step>
  </Configuration>
</HttpDataProvider>

System-reservierte Dienste

Bestimmte Dienste sind vom System reserviert und tragen das Präfix _System. (in der Oberfläche mit einem «System»-Badge gekennzeichnet). Aktuell:

Key	Zweck
_System.MIP	Microsoft Information Protection — Abruf der Vertraulichkeitsbezeichnungen.
_System.MIP.Protection	MIP-Rechteschutz (Rights Management); Voraussetzung für EnableProtection der Dokumentfunktion MIP.