Home
The OneTooX REST Push archiving solution allows a customer to have the documents and metadata of a OneTooX job delivered to their own systems. This can be used as a secondary channel after delivery to another channel such as Digital Post, remote print or e-Boks, or as a primary channel with no other delivery taking place.
To use the OneTooX REST Push archiving solution a customer must implement a REST service that the OneTooX system can push the job data to. The job data comes in a fixed format that the REST service must support. The input format and the response format are described below and they are also available live in the Test Service (see below) through the Swagger UI exposed by the service.
The OneTooX REST Push client can deliver data in two formats, JSON and XML. Which format is used, depends on a setting the OneTooX administration that is configured by the otx support team on behalf of the customer. It can easily be changed if requested. Your service must support the format that is configured in the otx administration. The format is declared in the HTTP header Content-Type with either the value application/json or application/xml.
See the assets of the releases for specifications of the API and related data models. The are both an HTML version and a formal OpenAPI specification.
The request consists of a single ArchiveMessage object that is sent to the service as a POST request. The URL can be decided by the customer, but it cannot contain dynamic values.
If the ArchiveMessage is handled by the service with success it can return a receipt to the OneTooX client in plain text. This receipt will then be stored in OneTooX.
In case the ArchiveMessage cannot be handled because of some error in the message itself, the client should return an HTTP 4xx status code (client error) and an error message that follows the RFC Problem Details for HTTP APIs. When the OneTooX client receives such an error it will not retry delivery as it is seen as an unrecoverable error. If, on the other hand, an intermittent error occurs due to failures in the service environment (such as network connectivity problems or database errors unrelated to the specific ArchiveMessage), a HTTP 5xx server error should be returned. This will instruct the client to try again after some period of time.
Example of a client error description:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "|807c8c1-4e61f5fe0d0814cd.",
"errors": {
"$.jobId": [
"'0x0A' is invalid within a JSON string. The string should be correctly escaped. Path: $.jobId | LineNumber: 1 | BytePositionInLine: 14."
]
}
}
The client may experience an intermittent error even though the service has received and handled the ArchiveMessage correctly. In these cases the client will retry the delivery and the service should not reject the ArchiveMessage, but reply to the client in the same way that it would when receiving the ArchiveMessage for the first time. In other words, the service should be idempotent.
The OneTooX REST client supports authentication through HTTP Basic Authentication. The username and password used by the client are configured in the OneTooX administration.
The documentation includes a test service with sample code that implements the API defined above. The test service is built with .NET Core 3.1 and the source code can be found at https://github.com/OneTooX/RestArchive. Binaries for Windows, Linux and MacOS are available as well. The test service can be used as the basis for developing an archive service and for comparison with a customer solution.
To demonstrate error responses the test service makes some (non-real world) validation. It also stores the main document on disk as well as saving metadata in both JSON and XML formats.
The test service implements HTTP Basic Authentication with a default username/password of test/test. The list of users is defined in UserService.cs.
The model representing the ArchiveMessage is included as a separate nuget package that is available at nuget.org. The source code can be found at https://github.com/OneTooX/RestArchiveModels.
The test service supports both JSON and XML serialization.
The test service is based on .NET Core 3.1, which can be downloaded from https://dotnet.microsoft.com/download/dotnet-core/3.1.
Get the test service code by cloning the source project. Build the project in Visual Studio and run the service with the Kestrel web server, which runs on port 5500 in the default setup:
The test service can be downloaded as an executable that only requires installation of .NET Core. The executable is available for Windows x64, Linux x64 and macOS 10.14 Mojave in the release section.
Start the test service by invoking the executable. By default the service runs on the address http://localhost:5000. This can be changed by using this command:
<executable name> --urls="http://<host>:<port>"
E.g. on Windows:
OneTooXRestArchiveTest.exe --urls="http://localhost:6000"
The test service exposes its API through Swagger at these addresses:
JSON: <base URL>/swagger/v1.0/swagger.json
UI: <base URL>/swagger
The first address returns a JSON description of the API in the OpenAPI format, which is a standard for describing RESTful APIs. The Swagger UI gives a more human readable form of the API and also adds example values in both JSON and XML format for request parameters.
Your service should of course be tested against a OneTooX test environment ahead of deployment into production. Before these tests there are a number of options for testing your service.
The Swagger UI has a simple interface for testing the API. Because the interface is rather minimalistic and does not have options for storing input data, it is mostly suitable for basic checks and validation.
Both Postman and Insomnia have features for testing REST APIs. They both offer a number of convenient features for creating and storing web requests and viewing responses. Below are examples of input that are applicable to the test service.
| Setting | Property | Value |
|---|---|---|
| Address | Source project default Executable default |
http://localhost:5500/api/v1.0/Archive/ http://localhost:5000/api/v1.0/Archive/ |
| Method | POST | |
| Basic authentication | username password |
test test |
| Header | Content-Type | application/json application/xml |
{
"JobId": 7300445,
"ParentJobId": 0,
"CreateTime": "2020-02-07T16:32:13.1285827+01:00",
"CustomerId": "0147",
"Division": "N-Byggeafdeling",
"UserId": "FIFTYTWO\\HGJ",
"MainDocument": {
"ContentType": "application/pdf",
"DocumentData": "JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgNTk1IDg0Ml0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDcxID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDEwMCA3MDAgVGQKICAgIChURVNUIC0gU0tBTCBJS0tFIFNFTkRFUykgVGoKICBFVAplbmRzdHJlYW0KZW5kb2JqCgp4cmVmCjAgNQowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMTggMDAwMDAgbiAKMDAwMDAwMDA3NyAwMDAwMCBuIAowMDAwMDAwMTc4IDAwMDAwIG4gCjAwMDAwMDA0NTcgMDAwMDAgbiAKdHJhaWxlcgogIDw8ICAvUm9vdCAxIDAgUgogICAgICAvU2l6ZSA1CiAgPj4Kc3RhcnR4cmVmCjU4MQolJUVPRgo=",
"Title": "Nyhedsbrev"
},
"Addendums": null,
"FixedAddendumName": null,
"ArchiveCaseId": "",
"ArchiveCategory": "Category X1",
"ArchiveDescription": "",
"Status": 0,
"Channel": 8,
"ChannelResolution": 0,
"ClientAddress": "fb80::6db4:5f9f:2a51:a65a%24",
"ClientInfo": "Print client: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.2; WOW64; Trident/7.0; .NET4.0C; .NET4.0E; .NET CLR 2.0.50727; .NET CLR 3.0.30729; .NET CLR 3.5.30729)",
"ClientVersion": "4.1.0.5000",
"IsColorPrint": true,
"Receiver": "1234560000",
"ReceiverType": 1,
"AttentionInfo": {
"PNummer": null,
"Email": null,
"PersonNavn": null,
"EnhedsNavn": null,
"PrimaerKlasse": null,
"SekundaerKlasse": null
},
"CustomerText": null,
"DigitalDestinationCountry": "DK",
"DigitalPostReceipt": null,
"DocumentType": "ArkivRestPush",
"DigitalPostResponse": null,
"DigitalPostResponseSubject": null,
"MaterialId": null,
"Title": "Nyhedsbrev",
"IsArchived": true,
"IsDuplex": false,
"MailPriority": 1,
"TotalNumberOfPages": 3,
"TotalNumberOfSheets": 3,
"TotalSize": 159933,
"OutputSystem": "MF",
"PostalDestinationCountry": "DK",
"SendingSystem": "Print"
}
<?xml version="1.0"?>
<ArchiveMessage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<JobId>7300445</JobId>
<ParentJobId>0</ParentJobId>
<CreateTime>2020-02-07T16:32:13.1285827+01:00</CreateTime>
<CustomerId>0147</CustomerId>
<Division>N-Byggeafdeling</Division>
<UserId>FIFTYTWO\HGJ</UserId>
<MainDocument>
<ContentType>application/pdf</ContentType>
<Title>Nyhedsbrev</Title>
<DocumentData>JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgNTk1IDg0Ml0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDcxID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDEwMCA3MDAgVGQKICAgIChURVNUIC0gU0tBTCBJS0tFIFNFTkRFUykgVGoKICBFVAplbmRzdHJlYW0KZW5kb2JqCgp4cmVmCjAgNQowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMTggMDAwMDAgbiAKMDAwMDAwMDA3NyAwMDAwMCBuIAowMDAwMDAwMTc4IDAwMDAwIG4gCjAwMDAwMDA0NTcgMDAwMDAgbiAKdHJhaWxlcgogIDw8ICAvUm9vdCAxIDAgUgogICAgICAvU2l6ZSA1CiAgPj4Kc3RhcnR4cmVmCjU4MQolJUVPRgo=</DocumentData>
</MainDocument>
<ArchiveCaseId />
<ArchiveCategory>Category X1</ArchiveCategory>
<ArchiveDescription />
<Status>Waiting</Status>
<Channel>Archive</Channel>
<ChannelResolution>Accepted</ChannelResolution>
<ClientAddress>fb80::6db4:5f9f:2a51:a65a%24</ClientAddress>
<ClientInfo>Print client: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.2; WOW64; Trident/7.0; .NET4.0C; .NET4.0E; .NET CLR 2.0.50727; .NET CLR 3.0.30729; .NET CLR 3.5.30729)</ClientInfo>
<ClientVersion>4.1.0.5000</ClientVersion>
<IsColorPrint>true</IsColorPrint>
<Receiver>1234560000</Receiver>
<ReceiverType>Person</ReceiverType>
<AttentionInfo />
<DigitalDestinationCountry>DK</DigitalDestinationCountry>
<DocumentType>ArkivRestPush</DocumentType>
<Title>Nyhedsbrev</Title>
<IsArchived>true</IsArchived>
<IsDuplex>false</IsDuplex>
<MailPriority>A</MailPriority>
<TotalNumberOfPages>3</TotalNumberOfPages>
<TotalNumberOfSheets>3</TotalNumberOfSheets>
<TotalSize>159933</TotalSize>
<OutputSystem>MF</OutputSystem>
<PostalDestinationCountry>DK</PostalDestinationCountry>
<SendingSystem>Print</SendingSystem>
</SendingSystem>