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 Datenbank neben der Default-Datenbank 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 und DownloadFile (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.
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 (Report).

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 solch ein 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;
}