Call
File extensions
Two file extensions are already associated with the primedocs client in Windows:
| File extension | Description |
|---|---|
| .pdcx | Contains Connect-compliant XML and will be executed by primedocs directly (without query). The file will be deleted after document creation unless otherwise defined in the XML. |
| .pdck | Same as .pdcx, but the k stands for keep. The connect file will not be deleted after processing. |
| .oocx | Legacy: same as .pdcx |
| .oock | Legacy: same as .pdck |
Client-side call via console
If unstructured XML is used for the call, primedocs must be called parameterized via the console:
...\primedocs.exe /connector "<path to xml file>" /interfaceType "<interface name in XML-Transformer>"
As the path to the xml file, you can specify either a file path or a URL.
If a URL is specified, it must first be allowed via the Connect Remote Policies in the Admin Dashboard. When a URL is provided, the keepConnect setting is ignored.
CAUTION
primedocs automatically deletes the connect file after processing. If the additional argument /keepConnector is passed, this behavior can be suppressed. If called via shell, then the file extension ".oock" must be used.
TemplatePicker
If no or no unique template has been defined in the XML for the call, then the TemplatePicker appears. This happens if
- no Template id and no Tag filter are set
- or the tag filter returns more than one result.
NOTE
An incorrect or non-existent template id will result in an error.
IMPORTANT
The TemplatePicker is executed asynchronously. It should only be used if there is only one entry in the batch.
Call by the Document Creation Server (DCS)
To create a document via the DCS, the Connect API must be addressed. This can be called with {ServerAddress}/connect/api/v1/connect. With {ServerAddress}/connect/ the general description of the API can be viewed. The API accepts a connect XML as body. The login to the server works via Basic Authentication with the format username:password as a base64 string. Username and password correspond to the entry basicAuth in the server-side OneOffixx.config.
CAUTION
Unstructured XML cannot be processed on the DCS. It is mandatory that a Connect XML is also sent. There is also no template picker for the DCS. A call via the DCS must therefore always contain all information regarding templates clearly in the Connect XML.
Result
Via Commands single documents (or in case of Batch processing the final result as a whole) can be converted or saved. In the case of the server call, if the execution is successful, the finished document is always returned as a response to the API call. In case of unsuccessful processing, the server will return a 400-Bad-Request or a 500-Internal-ServerError status code, depending on the severity of the error encountered. For security reasons, no details are supplied with this response in most cases. These must be viewed in the Connect API's server log (via the dashboard, or directly on the server's filesystem).
In the case of batch processing, it is mandatory that the Merge command is specified at the batch level. If this is not specified, the server will respond with status code 400-Bad-Request and an error message that the Merge command must be specified.
Example Call via DCS (with batch processing)
POST /{ServerFolder}/connect/api/v1/connect HTTP/1.1
Host: {ServerAddress}
Content-Type: text/xml
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
User-Agent: PostmanRuntime/7.15.0
Accept: */*
Cache-Control: no-cache
Postman-Token: 5c37ad5f-0ba0-464c-b0cc-33db5d46ce3d,05f57e43-dc8e-4a3e-a57c-a121f50a71f5
Host: {ServerAddress}
accept-encoding: gzip, deflate
content-length: 1004
Connection: keep-alive
cache-control: no-cache
<?xml version="1.0" encoding="utf-8"?>
<OneOffixxConnectBatch xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schema.oneoffixx.com/OneOffixxConnectBatch/1">
<Commands>
<Command Name="Merge">
<Parameters>
<Add key="PageNumberStart">10</Add>
</Parameters>
</Command>
<Command Name="ConvertToDocument" />
<Command Name="DefaultProcess">
<Parameters>
<Add key="Start">true</Add>
</Parameters>
</Command>
<OnCancel>
<Command Name="CreateConnectorResult" />
</OnCancel>
</Commands>
<Entries>
<OneOffixxConnect>
<Arguments>
<TemplateId>52945b6c-b65a-436d-8045-619e4e41af51</TemplateId>
</Arguments>
</OneOffixxConnect>
<OneOffixxConnect>
<Arguments>
<TemplateId>52945b6c-b65a-436d-8045-619e4e41af51</TemplateId>
</Arguments>
</OneOffixxConnect>
</Entries>
</OneOffixxConnectBatch>
Calling the primedocs Shell
.../primedocs.exe /CreateConnectorResult /interfaceType "ContosoInterface"
NOTE
The argument name is case-insensitive.
Possible arguments are:
| Argument | Type | Description |
|---|---|---|
| ActivateAddIn | string | Activates the specified (ProgID) primedocs addIn. |
| Clean | - | Exit primedocs and clear the cache |
| Connector | string | File path to connector XML |
| CreateConnectorResult | - | Creates an XML file with the result of the connector call. |
| CreateConnectorResultOnError | - | Creates an XML file with the result of the connector call when an error occurs. |
| DatasourceId | guid | ID of the data source to use |
| DLCID | int | Select the document language |
| ForceRestart | int | Force restart |
| Help | - | Show help. |
| Hidden | - | Starts primedocs without showing the shell. The application is started invisibly. The startup screen is shown at the first startup. |
| InterfaceType | string | Defines the format of the connector XML. |
| InterfaceVersion | string | Defines the version of the connector XML. |
| KeepConnector | - | The connector file will not be deleted automatically. |
| New | guid | Opens a document depending on a specified template. Parameters: Template id as GUID. |
| OutputUrl | string | Path for documents to be stored in SharePoint |
| ProfileId | guid | Preselected profile id |
| Show | - | Whether to show the client |
| Shutdown | - | Exit primedocs |
| Silent | - | Suppresses the startup screen. |
| Uri | string | Windows Protocol URI. Example: primedocs:hidden. |
| ValidateConnector | - | The connector file is validated before execution. |
| Argument | Parameter | Description | Windows command (WIN+ R) | HTML link | Shell |
|---|---|---|---|---|---|
| Clean | - | Exit primedocs and clear the cache | ✓ | ✓ | ✓ |
| Connector | string (Path to XML file) | File path on Connector XML | ✓ | X | ✓ |
| InterfaceType (Additional argument for Connector) | string (Name of the interface) | Defines the format of the connector XML. | |||
| KeepConnector (Additional argument for Connector) | - | The connector file is not automatically deleted. | |||
| InterfaceVersion (Additional argument for Connector) | string (Version number) | Defines the version of the Connector XML. | |||
| CreateConnectorResult (Additional argument for Connector) | - | Creates an XML file with the result of the connector call. | |||
| CreateConnectorResultOnError (Additional argument for Connector) | - | Creates an XML file with the result of the connector call when an error occurs. | |||
| Hidden | - | Starts primedocs without showing the shell. The application is not started visibly. The startup screen is shown at the first startup when primedocs is finished, when it is open the window is closed. | ✓ | ✓ | ✓ |
| New | guid GUID of the template | Opens a document depending on a specific template. Parameters: Template id as GUID. | ✓ | ✓ | ✓ |
| ProfileId (Additional argument for New) | guid GUID of the profile | Preselected profile id | |||
| DLCID (Additional argument for New) | int LCID number | Document language selection | |||
| Show | - | Whether to display the client | ✓ | X | ✓ |
| DatasourceId (Additional argument for Show) | guid GUID of the DataSource | Id of the data source to be used | |||
| Shutdown | - | Exit primedocs | ✓ | ✓ | ✓ |
| Silent | - | Suppresses the startup screen. | ✓ | ✓ | ✓ |
| Help | - | Displays the help. | X | X | ✓ |
| ActivateAddIn | string | Activates the specified (ProgID) primedocs add-in. | |||
| Uri | string | Windows Protocol URI. Example: primedocs:hidden. | |||
| ValidateConnector | - | The connector file is validated before execution. | |||
| ForceRestart | int | Force restart | |||
| OutputUrl | string | Path for documents to be stored in SharePoint |
Call via the protocol handler
When installing primedocs, a protocol handler is installed by default. The protocol handler allows primedocs to be called directly via a link in the browser.
<a href="primedocs:show">Show/Open primedocs client</a> <br />
<a href="primedocs:hidden">Hide primedocs client</a> <br />
<a href="primedocs:new=1d93046c-b3a2-4e96-ab5f-5b9b60afa86e">Open template with ID 1d93046c-b3a2-4e96-ab5f-5b9b60afa86e</a> <br />
<a href="primedocs:clean">Reset cache</a> <br />