Über die Connect API können Drittsysteme serverseitig die Dokumentgenerierung von primedocs über die primedocs Connect 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 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"
$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"
            ]
        }
    ]
}