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://primedocs.example.org/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

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://primedocs.example.org/ids/connect/token"
$connectSessionUrl = "https://primedocs.example.org/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;
}