Connect Session API

---

Third-party systems can initialise a connect session in the primedocs web app via the Connect Session API by providing a primedocs Connect to the interface.

Process

1. The third-party system calls the Connect/Session endpoint with the primedocs Connect in the body.
2. If the connect payload is valid and contains only supported content, a connect session ID is returned. The connect session is valid for one hour and is then automatically cleaned up. Any call to the connect session renews its validity.
3. With this connect session ID, the primedocs web app can be started with the parameter connect?sessionId:

https://primedocs.example.org/app/web/connect?sessionId=76288508-c861-4af7-a151-46ed946e5d1f 

Optionally, datasourceId can be passed as an additional GET-parameter so that a specific database is used alongside the default database. 4. The web app loads the connect session and navigates—if present in the initial connect—to the template via ID or tags.

Supported content

The following elements from primedocs Connect Structure are currently supported for the connect session:

• Template Id
• Template TagFilter
• DocumentLanguage
• Forms
• Data

Authentication and invocation

To call the Connect APIs, a client of this kind must be registered in primedocs.config; see primedocs.config for details.

After registration, an access token can be requested from the IdS. With the access token, the actual request can then be made to the Connect/Session endpoint of the WebApi.

This PowerShell example shows how to obtain the access token and call the endpoint:

# 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 -OutFile $filePath 
    
    Write-Host "Connect session id: $($response.sessionId)"
}
catch {
    Write-Error "Error making the request: $_"
    exit 1;
}