You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: DOCS/example-app.md
+5-5Lines changed: 5 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# Example app
1
+
# Example App
2
2
3
3
<h2>Table of contents</h2>
4
4
@@ -8,17 +8,17 @@
8
8
9
9
## Introduction
10
10
11
-
The example app is used to test the DocmosisCloud module. Therefor it can be used by you to see how you can implement the module in your own app.
11
+
The example app can be used to understand the DocmosisCloud module. It may assist you with ideas of how to implement the module in your own app.
12
12
13
-
## Where to find the app
13
+
## Where to find the Example App
14
14
15
15
Download the [latest version as zip file](https://github.com/Docmosis/mendix-integration/archive/main.zip) or use git to clone it from the [GitHub repository](https://github.com/Docmosis/mendix-integration).
16
16
17
-
If you want to run the app then open it in Mendix Studio Pro and in the profile update the two DocmosisCloud module constants with your access key and end point. Or start the app and enter the access key on the home page in the appropriate field.
17
+
To run the app, open it in Mendix Studio Pro and in the profile update the two DocmosisCloud module constants with your Docmosis Cloud access key and endpoint. Or start the app and enter the access key on the home page in the appropriate field.
18
18
19
19
> ATTENTION: This example app exposes the API access key visually. So when you want to hide it then remove the field(s) from the app's home page.
Copy file name to clipboardExpand all lines: DOCS/module.md
+34-30Lines changed: 34 additions & 30 deletions
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# The module
2
2
3
-
<h2>Table of contents</h2>
3
+
## Table of contents
4
4
5
5
-[Requirements](#requirements)
6
6
-[Terminology and process](#terminology-and-process)
@@ -15,29 +15,33 @@
15
15
16
16
The module can be imported in an app on [Mendix Studio Pro 8.12.5 or later](https://marketplace.mendix.com/link/studiopro/). That makes it compatible with Mendix 9 and in [version 8.12.5](https://docs.mendix.com/releasenotes/studio-pro/8.12#8125) a major security fix was implemented.
17
17
18
-
And it depends on Marketplace module [CommunityCommons](https://appstore.home.mendix.com/link/app/170/Mendix/Community-Commons-Function-Library).
The module is a wrapper around the Docmosis web services. This are the actions in your microflow:
22
+
## Terminology and Process
23
23
24
-
1.**Prepare the request:** This results in an pre-populated object where you can make additional adjustments. See the [Docmosis Cloud DWS3 Web Services Guide](https://resources.docmosis.com/content/documentation/cloud-dws3-web-services-guide) for details and examples.
25
-
2.**Execute the request:** The data is transformed to a proper web service request and send to Docmosis. The response is interpreted and in case of an error details of the error are stored in the response.
26
-
3.**Interpret the response:** In case of a successful execution the response contains the requested data. See the [Docmosis Cloud DWS3 Web Services Guide](https://resources.docmosis.com/content/documentation/cloud-dws3-web-services-guide) for details and examples. In case of an error you will find error details, see [paragraph Generic response object attributes](#generic-response-object-attributes).
24
+
The module is a wrapper around the calls to the Docmosis Cloud API. These are the actions in your microflow:
27
25
28
-
> In case of errors or other unforeseen events the module does not log errors or show messages to the user. It is up to your app to decide what to do.
26
+
1.**Prepare the request:** Create a pre-populated object where you can make additional adjustments.
27
+
2.**Execute the request:** The data is transformed to a web service request and sent to Docmosis. The response is interpreted and in case of an error details of the error are stored in the response.
28
+
3.**Process the response:** Extract the document and handle errors. In case of an error you will find error details, see [paragraph Generic response object attributes](#generic-response-object-attributes).
29
29
30
-
## Create a template
30
+
The main API endpoint used for generating documents is `/render`. For full details of the Docmosis Cloud API, refer to the [Docmosis Cloud DWS3 Web Services Guide](https://resources.docmosis.com/content/documentation/cloud-dws3-web-services-guide) for details and examples.
31
31
32
-
Before you can actually render documents you have to create a template. See the [Docmosis resources website](https://resources.docmosis.com) and in particular the [DWS3 Template Guide](https://resources.docmosis.com/content/documentation/cloud-dws3-template-guide) how to create a template.
32
+
> In case of errors or other unforeseen events this module does not log errors or show messages to the user. It is up to your app to decide what to do.
33
+
34
+
## Create a Template
35
+
36
+
Before you can render documents you will need to create a Docmosis template. Your Docmosis Cloud Account will contain some example templates. You can also refer to the [Docmosis Resources Website](https://resources.docmosis.com) for more examples and in particular the [DWS3 Template Guide](https://resources.docmosis.com/content/documentation/cloud-dws3-template-guide) for detailed templating information.
33
37
34
38
Use Docmosis Cloud Console to upload the template.
35
39
36
-
## Generate the data structure in your app
40
+
## Generate The Data Structure In Your App
37
41
38
-
In your app you have to collect all required data and structure it in such a way that it is compatible with the template you created. The module offers a function that supports you in generating a non-persistent data structure.
42
+
In your app you have to collect all required data and structure it in such a way that it is compatible with the template you created. The module includes a utility that supports you in generating a non-persistent example data structure based on your template.
39
43
40
-
In case you want to create the structure manually then you can skip the remainder of this paragraph. Otherwise continue reading and the [example app](example-app.md) shows how you can use it yourself.
44
+
If you want to create the structure manually then you can skip the remainder of this paragraph. Otherwise continue reading to see how the example data utility works. The [example app](example-app.md) shows it in operation.
@@ -48,27 +52,27 @@ First initialize the request using microflow `GetSampleDataRequest_Initialize`:
48
52
49
53
It returns an object of type `GetSampleDataRequest`. By default the data structure with sample data is returned as JSON, but if you prefer XML then change attribute `GetSampleDataRequest.Format` after initialization of the request object.
50
54
51
-
Next call microflow `CWS_GetSampleData` to lookup the structure and return it. A `GetSampleDataResponse` object is returned which contains the requested structure information in attribute `GetSampleDataResponse.TemplateSampleData`.
55
+
Next call the microflow `CWS_GetSampleData` to lookup the structure and return it. A `GetSampleDataResponse` object is returned which contains the requested structure information in attribute `GetSampleDataResponse.TemplateSampleData`.
52
56
53
-
Now you have a JSON or XML string that you can use in your app model to 1) create a [JSON Structure](https://docs.mendix.com/refguide/json-structures) or [XML Schema](https://docs.mendix.com/refguide/xml-schemas) document, 2) create an [export mapping](https://docs.mendix.com/refguide/export-mappings) and 3) [generate entities and associations](https://docs.mendix.com/refguide/map-automatically) that match the export mapping. Eventually tweak and tune the entities and associations, for example the naming of the entities.
57
+
Now you have a JSON or XML string that you can use in your app model to 1) create a [JSON Structure](https://docs.mendix.com/refguide/json-structures) or [XML Schema](https://docs.mendix.com/refguide/xml-schemas), 2) create an [export mapping](https://docs.mendix.com/refguide/export-mappings) and 3) [generate entities and associations](https://docs.mendix.com/refguide/map-automatically) that match the export mapping. Lastly, you may need to tweak the entities and associations, for example the naming of the entities.
54
58
55
-
All you have to do is copy/transform your app's data to this new data structure and use that in the [render process](#render-the-document).
59
+
You can then copy/transform your app's data to this new data structure and use that in the [render process](#render-the-document).
56
60
57
-
## Render the document
61
+
## Render The Document
58
62
59
-
Assuming you have a template and data then you can render the document.
63
+
Once you have a template and a matching data structure then you can render the document.
60
64
61
65
First initialize the request using microflow `RenderRequest_Initialize`:
62
66
63
67
-**TemplateName**: path and name of the template to use, for example *samples/InvoiceTemplate.docx*
64
-
-**OutputName**: name of the rendered document where the file extension tells Docmosis what type of document to generate, for example *invoice-21I000388.pdf*
68
+
-**OutputName**: name of the rendered document, for example *invoice-21I000388.pdf*. Docmosis will use the file extension to determine the format of document to generate, in this case *pdf*,
65
69
- common parameters are [documented here](#common-request-initialization-parameters)
It returns an object of type `RenderRequest` and when needed the attribute values can be adjusted. In [Docmosis Cloud DWS3 Web Services Guide chapter 2.4](https://resources.docmosis.com/content/documentation/cloud-dws3-web-services-guide) you will find a detailed explanation of all attributes.
73
+
It returns an object of type `RenderRequest` and when needed the attribute values can be adjusted. In [Docmosis Cloud DWS3 Web Services Guide](https://resources.docmosis.com/content/documentation/cloud-dws3-web-services-guide) chapter 2.4 you will find a detailed explanation of all attributes.
70
74
71
-
It is extremely flexible and powerful, so to help you get started quickly here are some common use cases:
75
+
It is extremely flexible and powerful. To help you get started quickly here are some common use cases:
72
76
73
77
- (Default behavior) Render the document and return it to your app
74
78
-`StoreTo=stream` - return the rendered document to the app
@@ -89,27 +93,27 @@ It is extremely flexible and powerful, so to help you get started quickly here a
89
93
> Attribute `StreamResultInResponse` is enforced to `true` for module implementation reasons. Changing it yourself will not change the behavior.
90
94
> Attribute `Data` will be populated with your data. Any data you put in here will be overwritten. See the next paragraph for details.
91
95
92
-
The next step is equally or maybe even more important: the data to be merged with the template. Your app has to generate a JSON string that matches the template. So typically that is a flow that involves data retrieval, creating one or more non-persistent objects and export it to JSON; see also paragraph [Generate the data structure in your app](#generate-the-data-structure-in-your-app). As that is completely specific to your app exact details cannot be given here. The [example app](DOCS/example-app.md) can be used as inspiration if you are new to this.
96
+
The next step is equally or maybe even more important: the data to be merged with the template. Your app has to generate a JSON string that matches the template. Typically that is a flow that involves data retrieval, creating one or more non-persistent objects and export it to JSON; see also paragraph [Generate the data structure in your app](#generate-the-data-structure-in-your-app). As that is completely specific to your app exact details cannot be given here. The [example app](DOCS/example-app.md) can be used as a guide.
93
97
94
98
When the `RenderRequest` object is set as required and a string with JSON data is available then call microflow `CWS_Render` to render the document.
95
99
96
-
The `RenderResponse` object returned contains the rendered document in [Base64](https://en.wikipedia.org/wiki/Base64) format in attribute `RenderResponse.Base64File`. You can use microflow `FileDocument_Base64Decode` to decode it to a [specialized `System.FileDocument`](https://docs.mendix.com/howto/data-models/working-with-images-and-files#4-file-documents) object, or process it otherwise that fits your need. And see also [Generic response object attributes](#generic-response-object-attributes) for an explanation of the other attributes and what to do in case of an error.
100
+
The `RenderResponse` object returned contains the rendered document in Base64 format in the attribute `RenderResponse.Base64File`. You can use microflow `FileDocument_Base64Decode` to decode it to a [specialized `System.FileDocument`](https://docs.mendix.com/howto/data-models/working-with-images-and-files#4-file-documents) object, or process it as meets your needs. Also see [Generic response object attributes](#generic-response-object-attributes) for an explanation of the other attributes and what to do in the case of an error.
97
101
98
-
> The document is returned as [Base64](https://en.wikipedia.org/wiki/Base64), which is different from default Docmosis behavior. This is an explicit characteristic of the module to be able to return a consistent type of response.
102
+
> The document is returned as [Base64](https://en.wikipedia.org/wiki/Base64) (enforced by `StreamResultInResponse` mentioned above), which is different from default Docmosis behavior. This is an explicit characteristic of this module to be able to return a consistent type of response.
99
103
100
104
## Common request initialization parameters
101
105
102
106
Most, if not all, request initialization microflows have these parameters in common:
103
107
104
-
-`APIAccessKey`: your Docmosis access key, see Docmosis Cloud Console for the access key
108
+
-`APIAccessKey`: your Docmosis access key, see the Docmosis Cloud Console[Accounts Page](https://console.dws3.docmosis.com/console/index.html#account) for the access key
105
109
- When empty then the value of constant `@DocmosisCloud.APIAccessKey` is used
106
-
-`APIEndPoint`: the Docmosis Cloud API endpoint, see Docmosis Cloud Console for the available endpoints
110
+
-`APIEndPoint`: the Docmosis Cloud API endpoint, see the Accounts Page for the available endpoints. Your templates will be uploaded and exist in one specific geo region, so you must use the matching endpoint when generating documents.
107
111
- When empty then the value of constant `@DocmosisCloud.APIEndpoint` is used
108
112
109
-
Why would you specify another access key or endpoint than stored in the constants? Here are two use cases that cannot be implemented if the module relied on the constants:
113
+
Usually the access key or endpoint stored in the constants will be sufficient, however here are examples where you may choose to override the constants:
110
114
111
-
1. your multi-tenant app allow tenants to specify their own keys and end points to be used
112
-
2. the access key is stored in a centralized configuration vault, for example [HashiCorp Vault](https://www.vaultproject.io), and the key is retrieved on runtime and not set on deployment
115
+
1. your multi-tenant app allows tenants to specify their own keys and endpoints to be used
116
+
2. the access key is stored in a centralized configuration vault, for example [HashiCorp Vault](https://www.vaultproject.io), and the key is retrieved at runtime and not set on deployment
113
117
114
118
## Generic request object attributes
115
119
@@ -128,7 +132,7 @@ Every response has these attributes:
[Docmosis Cloud](https://www.docmosis.com/products/cloud.html)is an online service to generate documents from your data. It works like mail merge, where you combine a document template and data to automatically generate documents. With Docmosis you create the document template using Microsoft Word or LibreOffice and the data is your app's data.
5
+
This module simplifies generating documents from your Mendix app by using the [Docmosis Cloud](https://www.docmosis.com/products/cloud.html) document generation service.
6
6
7
-
Output formats can be PDF, Doc, DocX, ODT, HTML and RTF; one at time or multiple at once.
7
+
You will need [a Docmosis Cloud Account](https://www.docmosis.com/products/cloud/try.html) to use this module.
8
8
9
-
[Docmosis Tornado](https://www.docmosis.com/products/tornado.html) is an on premise deployment of the same product. So this documentation applies to Docmosis Tornado too.
9
+
## Processing Locations
10
+
You have complete control over where your templates are stored and where processing occurs. Choose from [processing locations in the USA, EU and Asia/Pacific regions](https://www.docmosis.com/products/cloud/processing-locations.html) to ensure low latency and geo-bound processing.
10
11
11
-
> Any reference to Docmosis is short for Docmosis Cloud, Docmosis Tornado or the company Docmosis.
12
+
## Security and Reliability
13
+
We understand that Security and Reliability are essential. Below is a summary of our [Cloud Security Measures](https://www.docmosis.com/products/cloud/security-measures.html):
14
+
- Load balanced, high-performance, redundant, geographically distributed and monitored 24/7.
15
+
- Over 99.99% uptime consistently for over 7 years.
16
+
- All communication with the Docmosis Cloud is SSL encrypted and templates and other uploaded content are stored encrypted at rest.
17
+
18
+
We generate a test document every 60 seconds… view the live [Status Page](https://www.docmosis.com/status) and [Historical Uptime Statistics](https://www.docmosis.com/monitoring).
12
19
13
20
## The module
14
21
15
-
This Mendix module simplifies generating documents from your app using Docmosis. It is a wrapper around the Docmosis web services. All you need is a Docmosis access key and a good understanding of your reporting needs and the data in your app. The module handles all web service complexity so you don't have to be an expert on that and you can focus on generating documents.
22
+
This Mendix module simplifies generating documents from your app using Docmosis. It is a wrapper around the Docmosis Cloud service.
23
+
The module handles all web service complexity so you don't have to be an expert on that and you can focus on generating documents.
16
24
17
25
In the [GitHub repository](https://github.com/Docmosis/mendix-integration) you will find a project with some showcases and feel free to copy it to your own project or use it as inspiration. The author of the module uses it to test the module.
18
26
@@ -24,6 +32,6 @@ In the [GitHub repository](https://github.com/Docmosis/mendix-integration) you w
24
32
25
33
## Support
26
34
27
-
The module is published with an [Apache v2 open source license](https://www.apache.org/licenses/LICENSE-2.0). Support is not covered by your Docmosis contract but provided per best effort.
35
+
The module is published with an [Apache v2 open source license](https://www.apache.org/licenses/LICENSE-2.0). We will do our best to support your use and integration of this module.
28
36
29
-
Any questions, issues and requests for additional functionality can be posted to the [GitHub issue tracker](https://github.com/Docmosis/mendix-integration/issues) or can be send by [mail to Docmosis Support](mailto:support@docmosis.com).
37
+
Any questions, issues and requests for additional functionality can be posted to the [GitHub issue tracker](https://github.com/Docmosis/mendix-integration/issues) or can be [emailed to Docmosis Support](mailto:support@docmosis.com).
0 commit comments