Connect Session API

---

Über die Connect Session API können Drittsysteme eine Connect Session in der primedocs Web App initialisieren, in dem der Schnittstelle ein primedocs Connect geliefert wird.

Ablauf

1. Das Drittsystem ruft die Connect/Session Endpunkt mit dem primedocs Connect im Body auf
2. Falls das Connect valid ist und nur unterstützte Inhalte beinhaltet, wird eine Connect Session ID returniert. Die Connect Session ist jeweils für eine Stunde gültig und wird danach automatisch bereinigt. Ein Aufruf der Connect Session erneuert die Gültigkeit.
3. Mit dieser Connect Session ID kann die primedocs Web App mit dem Parameter connect?sessionId gestartet werden:

https://{instanz}/app/web/connect?sessionId=76288508-c861-4af7-a151-46ed946e5d1f 

Optional kann die datasourceId als weiterer GET-Parameter übergeben werden, damit eine spezifische Datasource neben der Default-Datasource verwendet wird. 4. Die Web App lädt die Connect Session und navigiert - falls im initialen Connect vorhanden zu der Vorlage via ID oder Tags.

Unterstützte Inhalte

Folgende Inhalte aus der primedocs Connect Struktur werden aktuell für die Connect Session unterstützt:

• Template Id
• Template TagFilter
• DocumentLanguage
• Forms
• Data
• Commands — jedoch nur die web-fähigen Commands InvokeUrl, ShowDialog, DownloadFile und BrowserParentPostMessage (in den Handler-Gruppen OnSuccess/OnExit/OnError/OnCancel). Andere Command-Typen (z.B. SaveFile, InvokeProcess) werden abgelehnt. Siehe Nach der Dokumentgenerierung (Commands). Die Commands werden bei der Ausführung der Session angewendet.

Weitere Endpunkte

Alle Endpunkte liegen unter .../api/v3/{datasourceId}/Connect/Session:

Methode	Pfad	Zweck
POST	/	Erstellt eine Connect Session aus einem übermittelten Connect und gibt die sessionId zurück.
POST	/Template/{templateName}	Erstellt eine vorinitialisierte Session aus einem benannten Connect Session Template. Gibt ebenfalls die sessionId zurück.
GET	/{sessionId}/Navigation	Liefert die Navigationsdaten der Session für die Web App (Vorlagenauswahl via Id/Tags).
GET	/{sessionId}/Input	Liefert die Eingabedaten (Forms/Data) der Session für die Web App.
POST	/{sessionId}/Execute	Führt die gespeicherte Session im Kontext des angemeldeten Benutzers aus (inkl. ConnectedService-Authentifizierung).
GET	/{sessionId}/Result/{executionId}	Liefert den bei einer Ausführung gespeicherten Ausführungsbericht (ConnectResultReport).

Die Antwort der beiden POST-Endpunkte zum Erstellen einer Session ist ein ConnectSessionResult:

{
  "sessionId": "76288508-c861-4af7-a151-46ed946e5d1f",
  "datasourceId": "b78c3707-d7c7-4fc7-b97f-87d70f63c1ac",
  "webAppLink": "web/connect?datasourceId=b78c3707-d7c7-4fc7-b97f-87d70f63c1ac&sessionId=76288508-c861-4af7-a151-46ed946e5d1f"
}

hinweis

Herkunft der executionId

Die executionId wird vom Aufrufer erzeugt (eine GUID) und beim Aufruf von /{sessionId}/Execute mitgegeben. Unter derselben executionId wird der Ausführungsbericht gespeichert und kann anschliessend über /{sessionId}/Result/{executionId} abgerufen werden.

Ausführung (/Execute)

Der Execute-Endpunkt führt eine zuvor erstellte Session serverseitig aus. Die Antwort hängt von den konfigurierten Commands ab:

• Szenario A — ist ein DownloadFile-Command konfiguriert, wird das generierte Dokument als Datei-Download zurückgegeben (mehrere DownloadFile ergeben ein ZIP-Archiv).
• Szenario B — verarbeitet ein Command den Inhalt selbst (z.B. InvokeUrl), antwortet der Endpunkt mit 204 No Content.

In beiden Fällen wird ein Ausführungsbericht unter der executionId gespeichert und kann anschliessend über GET .../{sessionId}/Result/{executionId} abgerufen werden.

Connect Session Templates

Statt bei jedem Aufruf ein vollständiges Connect zu übermitteln, lassen sich benannte, vorinitialisierte Sessions über die Dokumentfunktion Connect Session Templates definieren und direkt per URL starten:

https://{instanz}/app/web/session/template/{Name}?Forms.Subject=...&Data.InvoiceNumber=...

Die GET-Parameter der Aufruf-URL werden in das resultierende Connect-Objekt überführt (Forms.* → Forms, Data.* → Data) und stehen den Initializern der Vorlage zur Verfügung. Die Initializer können die Session zusätzlich aus HTTP-, SQL-, CSV- oder Excel-Quellen anreichern und über OnSuccess/OnError-Commands (z.B. InvokeUrl, ShowDialog) abschliessen.

Authentifizierung und Aufruf

Um die Connect APIs aufzurufen, muss in der primedocs.config ein entsprechender Client registriert sein, siehe hierfür primedocs.config.

Nach der Registrierung kann damit ein AccessToken vom IdS angefordert werden. Mit dem AccessToken kann dann gegen den Connect/Session Endpunkt der WebApi der eigentliche Aufruf abgesetzt werden.

Dieses PowerShell-Beispiel zeigt den Bezug des AccessTokens und den Aufruf des Endpunktes:

# Configuration
$datasourceId = "b78c3707-d7c7-4fc7-b97f-87d70f63c1ac"
$tokenUrl = "https://{instanz}/ids/connect/token"
$connectSessionUrl = "https://{instanz}/webapi/api/v3/$datasourceId/connect/session"

$clientID = "CustomApiClient"
$clientSecret = "CustomClient_Secret_123"
$scope = "pd_ConnectWebApi"

$tokenRequestHeaders = @{
    "Content-Type" = "application/x-www-form-urlencoded"
}

$tokenRequestBody = @{
    client_id     = $clientID
    client_secret = $clientSecret
    grant_type    = "client_credentials"
    scope         = $scope
}

# Request the access token

try {
    $tokenResponse = Invoke-RestMethod -Uri $tokenUrl -Method POST -Headers $tokenRequestHeaders -Body $tokenRequestBody
}
catch {
    Write-Error "Error making the request: $_"
    exit 1;
}

if (-not $tokenResponse.access_token) {
    Write-Error "Failed to obtain an access token!"
    exit 1
}

# Access token information
Write-Host "Access Token: $($tokenResponse.access_token)"
$accessToken = $tokenResponse.access_token

# Prepare headers for request
$apiRequestHeaders = @{
    "Authorization" = "Bearer $accessToken"
    "Content-Type" = "application/xml; charset=utf-8"
}

$xmlBody = @"
<primedocsConnect>
  <Template Id="30b55516-80b5-41d7-801b-b31d6da376ac" />
  <DocumentLanguage Code="es-es" />
  <Forms>
    <Value Key="Subject">From Sample Script</Value>
    <Value Key="Notes">Sample Note</Value>
  </Forms>
  <Data>
    <Value Key="InvoiceNumber">1234</Value>
  </Data>
</primedocsConnect>
"@


Write-Host "Invoke Connect session..."
try {
    $response = Invoke-RestMethod -Uri $connectSessionUrl -Method POST -Headers $apiRequestHeaders -Body $xmlBody

    Write-Host "Connect session id: $($response.sessionId)"
}
catch {
    Write-Error "Error making the request: $_"
    exit 1;
}

Fehlerbehandlung

Die HTTP-Statuscodes und das Fehler-Response-Format sind einheitlich unter API → Fehlerbehandlung beschrieben. Ein POST / bzw. POST /Template/{templateName} mit ungültigem oder nicht unterstütztem Connect wird mit 400 Bad Request abgelehnt; eine nicht gefundene oder abgelaufene Session ergibt 404 Not Found.