/
Connect API

Connect API

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

Resultat

Das Resultat ist abhängig vom Vorlagentyp. In allen Fällen wird eine Datei erstellt.

Bei Word-, Excel- und PowerPoint-Vorlagen ist es eine entsprechende Datei.

Outlook

Bei allen Outlook-Vorlagen wird standmässig HTML samt eine Liste von verlinkten Bildern im json-Format zurückgegeben:

{ "Body":"<html><head></head><body><p>Hello World</p>\r\n<p><b>My Firstname</b> My LastName</p>\r\n<img src=\"cid:profile-org-logo-1312016b.png\"></body></html>", "AttachmentImages":[ { "Name":"profile-org-logo-1312016b.png", "Base64Data":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAadEVYdFNvZnR3YXJlAFBhaW50Lk5FVCB2My41LjEwMPRyoQAAAA1JREFUGFdj+P//PwMACPwC/ohfBuAAAAAASUVORK5CYII=" } ] }

  • Body: Beinhaltet den HTML Content der Signatur bzw. der E-Mail-Vorlage. Werden in der Vorlage auf Bilddaten des Profils zugegriffen (z.B. über <img src="{{Profile.Org.Logo}}" />) wird das Bild über ein cid-Link ausgetauscht und in der AttachmentImages hinterlegt.
    Hinweis: Werden externe Bilder verlinkt oder Bilder werden direkt via base64 in der Vorlage/Signatur hinterlegt, wird kein cid-Link hinzugefügt. Dies geschieht nur über die primedocs Bilder.

  • AttachmentImages: Beinhaltet alle cid-Bilder.

<primedocsConnect> <Template Id="e76712a7-d7ab-4112-9240-e688522e5f75" /> <Author> <Profile Id="dfc92748-fbf2-4861-bfac-683fec6139fe" /> </Author> <!-- This can be omitted, because this is the default: --> <Outlook ContentType="Html" /> </primedocsConnect>

PlainText

Über die Connect API können auch PlainText Signaturen bzw. E-Mail Vorlagen definiert werden. Hierfür muss das Connect mit dem Outlook-Element konfiguriert werden:

<primedocsConnect> <Template Id="e76712a7-d7ab-4112-9240-e688522e5f75" /> <Author> <Profile Id="dfc92748-fbf2-4861-bfac-683fec6139fe" /> </Author> <Outlook ContentType="PlainText" /> </primedocsConnect>

Zurückgegeben wird in diesem Fall ein solches json:

{ "PlainTextContent":"My Firstname My Lastname" }

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/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" $connectUrl = "https://customerserver.local/webapi/api/v3/$datasourceId/connect/file" $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" /> <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 { $filePath = "C:\temp\test.docx" $response = Invoke-RestMethod -Uri $connectUrl -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