DOC-2352: On-premises Import from Word and Export to Word documenta…

…tion. (#3187)

* DOC-2352: On-premises Import from Word and Export to Word documentation.

* Apply suggestions from code review

Updated content to reflect correct image names and also added login prerequisite details

* Update import-from-word-and-export-to-word-overview-on-premises.adoc - content alignment

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-logs-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-overview-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-overview-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-requirements-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-installation-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-logs-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-installation-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-logs-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-api-usage-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-api-usage-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-autorization-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-autorization-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-overview-on-premises.adoc

* Update modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-overview-on-premises.adoc

---------

Co-authored-by: shirqa <[email protected]>

antora.yml

@@ -17,6 +17,7 @@ asciidoc:
     jquery_url: https://cdn.jsdelivr.net/npm/@tinymce/tinymce-jquery@2/dist/tinymce-jquery.min.js
     default_meta_keywords: tinymce, documentation, docs, plugins, customizable skins, configuration, examples, html, php, java, javascript, image editor, inline editor, distraction-free editor, classic editor, wysiwyg
     # product docker variables
+    dockerimageimportfromwordexporttoword: registry.containers.tiny.cloud/docx-converter-tiny
     dockerimageexporttopdf: registry.containers.tiny.cloud/pdf-converter-tiny
     dockerimageexporttopdfwindows: registry.containers.tiny.cloud/pdf-converter-windows-tiny
     # document converter placeholder variables

modules/ROOT/nav.adoc

@@ -137,8 +137,7 @@
 ***** xref:individual-hyperlinking-container.adoc[Hyperlinking service]
 ***** xref:individual-spelling-container.adoc[Spelling service]
 ***** xref:individual-export-to-pdf-on-premises.adoc[Export to PDF]
-***** xref:individual-export-to-word-on-premises.adoc[Export to Word]
-***** xref:individual-import-from-word-on-premises.adoc[Import from Word]
+***** xref:individual-import-from-word-and-export-to-word-on-premises.adoc[Import from Word and Export to Word]
 *** Configure the server-side components
 **** xref:configure-required-services.adoc[Required configuration]
 **** xref:configure-common-settings-services.adoc[Optional common settings]

modules/ROOT/pages/individual-import-from-word-and-export-to-word-on-premises.adoc

@@ -0,0 +1,19 @@
+= Deploy the {productname} {pluginname} service server-side component using Docker (individually licensed)
+:navtitle: Import from Word and Export to Word
+:description: Setting up Import from Word and Export to Word using Docker.
+:keywords: server-side, docker, import-from-word, export-to-word, on-premises
+:pluginname: Import from Word and Export to Word
+
+include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-overview-on-premises.adoc[]
+
+include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-requirements-on-premises.adoc[]
+
+include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-installation-on-premises.adoc[]
+
+include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-autorization-on-premises.adoc[]
+
+include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-api-usage-on-premises.adoc[]
+
+include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-ssl-communication-on-premises.adoc[]
+
+include::partial$individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-logs-on-premises.adoc[]

modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-api-usage-on-premises.adoc

@@ -0,0 +1,15 @@
+[[api-usage]]
+== API usage
+
+{pluginname} On-Premises consists of two services:
+
+* xref:exportword.adoc[Export to Word] provides conversion from an HTML document to a `.docx` file via Restful API.
+* xref:importword.adoc[Import from Word] allows importing `.docx` file and converting it into a styled HTML document with comments and suggestions attached.
+
+The API is available on `+http://localhost:[port]+` (by default the port is 8080).
+
+[NOTE]
+The REST API documentation is available at `+http://localhost:[port]/docs+`.
+Alternatively you can check specification in our public resources for link:https://importdocx.converter.tiny.cloud/docs#section/Import-from-Word[Import from Word^] and the link:https://exportdocx.converter.tiny.cloud/docs#section/Export-to-Word[Export to Word^] plugins.
+
+If you have the authorization for the API enabled, you should provide an authorization token. More instructions you can find in the authorization section.

modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-autorization-on-premises.adoc

@@ -0,0 +1,69 @@
+[[authorization]]
+== Authorization
+
+To enable authorization, set the `SECRET_KEY` environment variable during the xref:individual-import-from-word-and-export-to-word-on-premises.adoc#installation[installation].
+
+If the `SECRET_KEY` variable is set, then all requests must have a header with a JWT (JSON Web Token) signed with this key. The token should be passed as a value of the `Authorization` header for each request sent to the {pluginname} REST API.
+
+[NOTE]
+If the `SECRET_KEY` is not setup during the installation, then {pluginname} On-Premises will not require any headers with tokens when sending requests to the {pluginname} REST API. However, this it is not recommend to skip the authorization when running {pluginname} On-Premises in a public network.
+
+=== Generating the token
+
+{companyname} recommends using the libraries listed on link:http://jwt.io/[jwt.io] to generate the token. The token is considered valid, when:
+
+* it is signed with the same `SECRET_KEY` as passed to the {pluginname} On-Premises instance,
+* it was created within the last 24 hours,
+* it is not issued in the future (e.i. the `iat` timestamp cannot be newer than the current time),
+* it has not expired yet.
+
+Tokens for the {pluginname} On-Premises do not require any additional claims such as the environment ID (which is specific for Collaboration Server On-Premises), the token can be created with an empty payload.
+
+If the specific use case involves sending requests from a backend server, then JWT tokens can be generated locally, as shown in the below request example.
+
+In the case of editor plugins or other frontend usages, a token endpoint should be created, that returns a valid JWT token for authorized users.
+
+=== Using editor plugins
+
+The are are two plugins available for {productname}: the xref:importword.adoc[Import from Word] and the xref:exportword.adoc[Export to Word] plugins. The plugins will automatically request the token from the given `tokenUrl` variable and will set the `Authorization` header when making an export request. Refer to the respective guides for details on adding the {pluginname} features to your WYSIWYG editor!
+
+=== Request example with an Authorization header
+
+The following example presents a request that generates a valid JWT token and sets it as an `Authorization` header:
+
+[source, js]
+----
+const fs = require( 'fs' );
+const jwt = require( 'jsonwebtoken' );
+const axios = require( 'axios' );
+
+const SECRET_KEY = 'secret';
+
+const token = jwt.sign( {}, SECRET_KEY, { algorithm: 'HS256' } );
+
+const data = {
+   html: "<p>I am a teapot</p>",
+   css: "p { color: red; }",
+};
+
+const config = {
+   headers: {
+      Authorization: token
+   },
+   responseType: 'arraybuffer',
+};
+
+axios.post( 'http://localhost:8080/v1/convert', data, config )
+   .then( response => {
+      fs.writeFileSync('./file.docx', response.data, 'binary');
+   } ).catch( error => {
+      console.log( error );
+   } );
+----
+
+`SECRET_KEY`: This is the key what has been passed to the {pluginname} On-Premises instance.
+
+Please refer to the link:https://importdocx.converter.tiny.cloud/docs#section/Import-from-Word[Import from Word^] and the link:https://exportdocx.converter.tiny.cloud/docs#section/Export-to-Word[Export to Word^] REST API documentation to start using the service.
+
+[NOTE]
+If API clients like Postman or Insomnia are used, then set the JWT token as an `Authorization` header in the `Headers` tab. Do not use the built-in token authorization as this will generate invalid header with a `Bearer` prefix added to the token.

modules/ROOT/partials/individually-licensed-components/import-from-word-and-export-to-word/import-from-word-and-export-to-word-installation-on-premises.adoc

@@ -0,0 +1,89 @@
+[[installation]]
+== Installation
+
+[NOTE]
+A valid license key is needed in order to install {pluginname} On-Premises.
+link:https://www.tiny.cloud/contact/[Contact us] for a trial license key.
+
+=== Supported technologies
+
+The application is provided as a docker image by default.
+
+It can be run with any Open Container runtime tool e.g. link:https://kubernetes.io/[Kubernetes], link:https://www.redhat.com/en/technologies/cloud-computing/openshift[OpenShift], link:https://podman.io/[Podman], link:https://docs.docker.com/[Docker] and many others.
+
+Refer to the xref:individual-import-from-word-and-export-to-word-on-premises.adoc#requirements[Requirements guide] for more information about the hardware and software requirements to run the {pluginname} On-Premises.
+
+=== Setting up the application using a Docker container
+
+. The username and password credentials supplied by Tiny are utilized for logging into the Docker registry and retrieving the Docker image.
+. Containerize the application using `docker` or `docker-compose`.
+. Use a demo page to verify if the application works properly.
+
+==== Containerize example using docker
+
+Login to Docker registry:
+
+[source, sh, subs="attributes+"]
+----
+docker login -u [username] -p [password] registry.containers.tiny.cloud
+----
+
+Launch the Docker container:
+
+[source, sh, subs="attributes+"]
+----
+docker run --init -p 8080:8080 -e LICENSE_KEY=[your_license_key] {dockerimageimportfromwordexporttoword}:[version]
+----
+
+If using authorization provide the SECRET_KEY:
+
+[source, sh, subs="attributes+"]
+----
+docker run --init -p 8080:8080 -e LICENSE_KEY=[your_license_key] -e SECRET_KEY=[your_secret_key] {dockerimageimportfromwordexporttoword}:[version]
+----
+
+Read more about using authorization in the xref:individual-import-from-word-and-export-to-word-on-premises.adoc#authorization[authorization] section.
+
+==== Containerize example using docker-compose
+
+. Create the docker-compose.yml file:
++
+[source, yml, subs="attributes+"]
+----
+version: "3.8"
+services:
+  doc-converter:
+    image: {dockerimageimportfromwordexporttoword}:[version]
+    ports:
+      - "8080:8080"
+    restart: always
+    init: true
+    environment:
+      LICENSE_KEY: "licensekey"
+      # Secret Key is optional
+      SECRET_KEY: "secret_key"
+----
++
+For details on `SECRET_KEY` usage check the xref:individual-import-from-word-and-export-to-word-on-premises.adoc#authorization[authorization] section.
++
+. Run:
+
+[source, bash]
+----
+docker-compose up
+----
+
+[NOTE]
+====
+* Without a correct `LICENSE_KEY` the application will not start.
+** If the license is invalid, a wrong license key error will display in the logs and the application will not run.
+* It is advisable to override the `SECRET_KEY` variable using a unique and hard to guess string for security reasons.
+====
+
+=== Next steps
+
+Use the link:http://localhost:8080/v1/convert[http://localhost:8080/v1/convert] endpoint to export DOCX files. Check out the xref:individual-import-from-word-and-export-to-word-on-premises.adoc#authorization[authorization] section to learn more about tokens and token endpoints.
+
+Use the demo page available on link:http://localhost:8080/demo[http://localhost:8080/demo] to generate an example DOCX file.
+
+Refer to the {pluginname} REST API documentation on link:http://localhost:8080/docs[http://localhost:8080/docs] for more details.