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://{instanz}/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
• Commands — but only the web-supported commands InvokeUrl, ShowDialog, and DownloadFile (in the OnSuccess/OnExit/OnError/OnCancel handler groups). Other command types (e.g. SaveFile, InvokeProcess) are rejected. See After document generation (Commands). The commands are applied when the session is executed.

Further endpoints

All endpoints live under .../api/v3/{datasourceId}/Connect/Session:

Method	Path	Purpose
POST	/	Creates a Connect Session from a submitted Connect and returns the sessionId.
POST	/Template/{templateName}	Creates a pre-initialized session from a named Connect Session Template.
GET	/{sessionId}/Navigation	Returns the session's navigation data for the web app (template selection via Id/tags).
GET	/{sessionId}/Input	Returns the session's input data (Forms/Data) for the web app.
POST	/{sessionId}/Execute	Executes the stored session in the context of the authenticated user (including ConnectedService authentication).
GET	/{sessionId}/Result/{executionId}	Returns the execution report (Report) stored during an execution.

Execution (/Execute)

The Execute endpoint runs a previously created session on the server. The response depends on the configured commands:

• Scenario A — if a DownloadFile command is configured, the generated document is returned as a file download (multiple DownloadFile commands produce a ZIP archive).
• Scenario B — if a command handles the content itself (e.g. InvokeUrl), the endpoint responds with 204 No Content.

In both cases an execution report is stored under the executionId and can be retrieved via GET .../{sessionId}/Result/{executionId}.

Connect Session Templates

Instead of submitting a full Connect on every call, you can define named, pre-initialised sessions via the Connect Session Templates document function and launch them directly by URL:

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

The URL's GET parameters are merged into the resulting Connect object (Forms.* → Forms, Data.* → Data) and are available to the template's initializers. Initializers can additionally enrich the session from HTTP, SQL, CSV, or Excel sources and finish it via OnSuccess/OnError commands (e.g. InvokeUrl, ShowDialog).

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