Connect API

Owned by Robert Mühsig
Last updated: May 23, 2024
49 min read

Über die Connect API können Drittsysteme serverseitig die Dokumentgenerierung von primedocs über die Schnittstelle nutzen.

Als Resultat wird das generierte Dokument dem Aufrufer zurückgegeben.

Authentizierung und Aufruf

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

Nach der Registrierung kann damit ein AccessToken vom IdS angefordert werden. Mit dem AccessToken kann dann gegen den Connect/File 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://customerserver.local/ids/connect/token" $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" } $xmlBody = @" <primedocsConnect> <Template Id="30b55516-80b5-41d7-801b-b31d6da376ac" /> <Author><Profile Id="191d8f76-16e5-43fb-a6df-03b234b9d32a" /></Author> <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..." try { $apiUrl = "https://localhost:5001/api/v3/$($datasourceId)/Connect/File" $filePath = "C:\temp\test.docx" $response = Invoke-RestMethod -Uri $apiUrl -Method POST -Headers $apiRequestHeaders -Body $xmlBody -OutFile $filePath Write-Host "Connect result file saved at: $($filePath)" } catch { Write-Error "Error making the request: $_" exit 1; }

Swagger / Open API

Die aktuelle Connect API Open API sieht in der Version 4.0.20171 folgendermassen aus. Sie können diese Beschreibung z.B. über den Swagger Editor visualisieren.

{ "openapi": "3.0.1", "info": { "title": "primedocs WebApi", "version": "v3" }, "servers": [ { "url": "/webapi" } ], "paths": { "/api/v3/{datasourceId}/Connect/File": { "post": { "tags": [ "Connect" ], "parameters": [ { "name": "proposedFileName", "in": "query", "schema": { "type": "string" } }, { "name": "datasourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" } } } } }, "components": { "schemas": { "AdminGroupInfoV3": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "primarySid": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AdminOrganizationUnitDetailInfoV3": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "parentId": { "type": "string", "format": "uuid", "nullable": true } }, "additionalProperties": false }, "AdminOrganizationUnitEditV3": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "organizationUnitParentId": { "type": "string", "format": "uuid", "nullable": true }, "fieldChanges": { "type": "array", "items": { "$ref": "#/components/schemas/FieldEdit" }, "nullable": true } }, "additionalProperties": false }, "AdminOrganizationUnitInfoV3": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AdminProfileDetailInfoV3": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "organizationUnitId": { "type": "string", "format": "uuid", "nullable": true }, "organizationUnitTitle": { "type": "string", "nullable": true }, "profileShares": { "type": "array", "items": { "$ref": "#/components/schemas/AdminProfileShareV3" }, "nullable": true } }, "additionalProperties": false }, "AdminProfileInfoV3": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "organizationUnitId": { "type": "string", "format": "uuid", "nullable": true }, "organizationUnitTitle": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AdminProfileShareEditV3": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "nullable": true }, "groupId": { "type": "string", "format": "uuid", "nullable": true }, "appUserGroupId": { "type": "string", "format": "uuid", "nullable": true }, "profilePermissionLevel": { "type": "integer", "format": "int32" }, "signaturePermissionLevel": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "AdminProfileShareV3": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid", "nullable": true }, "groupId": { "type": "string", "format": "uuid", "nullable": true }, "appUserGroupId": { "type": "string", "format": "uuid", "nullable": true }, "profilePermissionLevel": { "type": "integer", "format": "int32" }, "signaturePermissionLevel": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "AdminProfileUpdateEditV3": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "organizationUnitId": { "type": "string", "format": "uuid" }, "fieldChanges": { "type": "array", "items": { "$ref": "#/components/schemas/FieldEdit" }, "nullable": true } }, "additionalProperties": false }, "AdminUserDetailInfoV3": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "primarySid": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/AdminProfileInfoV3" }, "nullable": true } }, "additionalProperties": false }, "AdminUserInfoV3": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "primarySID": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AdminUserUpdateEditV3": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "fieldChanges": { "type": "array", "items": { "$ref": "#/components/schemas/FieldEdit" }, "nullable": true } }, "additionalProperties": false }, "EmailMessageTypeV3": { "enum": [ 0, 1, 2 ], "type": "integer", "format": "int32" }, "FieldEdit": { "type": "object", "properties": { "field": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "imageAsBase64": { "type": "string", "nullable": true }, "lcid": { "type": "integer", "format": "int32" }, "purge": { "type": "boolean" } }, "additionalProperties": false }, "FlatFieldInfoV2": { "type": "object", "properties": { "field": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "inheritance": { "type": "string", "nullable": true }, "isImage": { "type": "boolean" }, "lcid": { "type": "integer", "format": "int32" }, "profileId": { "type": "string", "format": "uuid", "nullable": true }, "_links": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/LinkV2" }, "nullable": true, "readOnly": true } }, "additionalProperties": false }, "LinkV2": { "type": "object", "properties": { "href": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "id": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PagedResponse`1<AdminGroupInfo[]v3>": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminGroupInfoV3" }, "nullable": true }, "pagingDetails": { "$ref": "#/components/schemas/PagingDetails" } }, "additionalProperties": false }, "PagedResponse`1<AdminOrganizationUnitInfo[]v3>": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminOrganizationUnitInfoV3" }, "nullable": true }, "pagingDetails": { "$ref": "#/components/schemas/PagingDetails" } }, "additionalProperties": false }, "PagedResponse`1<AdminUserInfo[]v3>": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUserInfoV3" }, "nullable": true }, "pagingDetails": { "$ref": "#/components/schemas/PagingDetails" } }, "additionalProperties": false }, "PagedResponse`1<SharedProfileInfo[]v2>": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SharedProfileInfoV2" }, "nullable": true }, "pagingDetails": { "$ref": "#/components/schemas/PagingDetails" } }, "additionalProperties": false }, "PagingDetails": { "type": "object", "properties": { "pageSize": { "type": "integer", "format": "int32" }, "page": { "type": "integer", "format": "int32" }, "totalPages": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "SearchInputFieldsResponseModel": { "type": "object", "properties": { "dataProviderDisplayName": { "type": "string", "nullable": true }, "searchParametersConfigurationXmlSerialized": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SharedProfileInfoV2": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "hasProfileImage": { "type": "boolean" }, "_links": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/LinkV2" }, "nullable": true, "readOnly": true }, "organizationUnitId": { "type": "string", "format": "uuid" }, "organizationUnit": { "type": "string", "nullable": true }, "isDefault": { "type": "boolean" }, "organizationUnitPath": { "type": "string", "nullable": true }, "localizedFlatFields": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FlatFieldInfoV2" } }, "nullable": true }, "isForeignProfile": { "type": "boolean" }, "isPinned": { "type": "boolean" }, "organizationUnitThemes": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "SignatureContentV3": { "type": "object", "properties": { "content": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SignatureV3": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://{tenantinstance}/ids/connect/authorize", "scopes": { "oo_WebApi": "Web API" } } } } } }, "security": [ { "oauth2": [ "oo_WebApi" ] } ] }

PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland