Developer's Guide to DocsNG Document Generation
Welcome to the DocsNG Developer's Guide! This guide will walk you through the process of generating documents using DocsNG's API. Follow these steps to seamlessly integrate document generation into your application.
Step 1: Define Data Models
Before diving into document generation, define the data models that your documents will be based on. Identify the fields, relationships, and structure necessary for your specific use case. Refer to the End User Guide for a comprehensive explanation on creating data models.
Step 2: Create Templates using MS Word
Design your document templates using Microsoft Word. Incorporate placeholders or tags that correspond to the data fields from your defined models. These placeholders will be dynamically replaced with actual data during the document generation process. Refer to the End User Guide for a comprehensive explanation on creating data models.
Step 3: Generate Documents using Restful API
The document generation process in DocsNG using the Restful API closely resembles document generation through the GUI. The key differences are:
- When using the Restful API, there's no requirement to have pre-entered data in the DocsNG database.
- It is not possible to send pfx file for advanced signing process. For advanced signing password protected pfx file must be already stored in the profile of the user.
The full API documentation can be found under API documentation.
Check out our public Postman collection, which is available for running against our demo environment
The postman collection contains a set of predefined API requests and associated tests that can be executed using Postman. It allows you to interact with our demo environment's RESTful API and observe how the API functions. This can be useful for testing, learning, or understanding the document generation capabilities of DocsNG.
Here's a concise overview of the Restful API for document generation process:
-
Step 1: Sign in to your DocsNG account through the API using the following endpoint: [HTTP Post] [URL of DocsNG]/api/Account/Login
- Parameters:
- Username: Your DocsNG account username
- Password: Your DocsNG account password
- Upon successful authentication, the API will provide a Bearer Token.
- Parameters:
-
Step 2: Send your data [HTTP Post] [URL of DocsNG]/api/Document/GenerateDocumentFromJson endpoint to generate a document
- Parameters (querystring):
- culture (string): Localisation override for the output document. Examples: en-US, nl-NL, de-DE
- templateId (integer): the Id of the template from DocsNG. Examples: 1,2,3,4, etc.
- outputType (integer): 1 for docx output, 2 for PDF output
- encryptPwd (string): password for the PDF encryption
- pfxPwd (string): password of the certificate in pfx file format stored in the profile of the user to be used for advanced signing
- Parameters (header)
- Accept-Language (string): Language choice (default en) for API resonse messages. Possible values are: en, en, es, de, nl, tr, fr, it, pt
-
Request body
-
JSON array: In the RESTful API of DocsNG, the data to be used for document generation needs to be sent in the request body in the form of a JSON array. This JSON array should contain all the necessary information for generating documents, including data structure and relationships.
Here's a breakdown of how this works:
- JSON Array: The main array is used to organize the data for generating multiple documents. Each element in this array represents one document to be generated.
- JSON Object for Each Document: Within the main JSON array, each element is a JSON object that encapsulates all the data required for a specific document. This JSON object should include not only the document's content but also its data structure and data and structure of other models that the model has relationship to.
- Data Structure: The JSON object for each document must define its data structure, which includes specifying the type and format of data fields. This ensures that the document generation process understands how to interpret and display the data correctly.
- Relationships: If the document relies on data from other entities, these relationships should also be included in the JSON object. This helps the document generation process access and incorporate related data when creating the document.
By providing all the necessary data, including data structure and relationships, in the JSON objects within the JSON array, the RESTful API can effectively generate documents with the desired content and connections to related data entities. This approach ensures that the documents accurately reflect the data's structure and dependencies, making it a powerful feature for creating complex and interconnected documents through the API.
-
-
Response body is the id of the generated document
Blow is the explanation of the structure
Blow is an example JSON array for invoice generation that we used in the examples of the DocsNG[ //Main JSON Array: Each individual JSON object within the array corresponds to a distinct document generation task. { "Id": 201, // Custom User-Defined Identifier for Document Generation Process "ModelId": 3, // Data Model ID in DocsNG "Name": "Invoice", // Data Model Name in DocsNG "Fields": [ //Array of model fields and their corresponding data. { "Name": "Number", // Name of the field in the data model "Value": "INVFromAPI1", // Value of the field "Type": "String", // Data type of the field. Possible values String, DateTime, Currency, Double, Boolean "IsRequired": "Y" // choice if the field is mendatory. Possible values: Y = Yes, N = No } ], "Relations": [ //Array of data of data models that main model has relation to, in nested structure { "Id": 1, "ModelId": 1, "Name": "Customer", "Fields": [ { "Name": "Name", "Value": "Customer From API", "Type": "String", "IsRequired": "Y" } ], "Relations": [] } ] } ][ { "Id": 201, "ModelId": 3, "Name": "Invoice", "Fields": [ { "Name": "Number", "Value": "INVFromAPI1", "Type": "String", "IsRequired": "Y" }, { "Name": "Date", "Value": "2023-10-06T09:00:00.594Z", "Type": "DateTime", "IsRequired": "Y" }, { "Name": "DueDate", "Value": "2023-10-31T09:00:00.594Z", "Type": "DateTime", "IsRequired": "Y" }, { "Name": "Reference", "Value": "Test", "Type": "String", "IsRequired": "Y" }, { "Name": "CustomerVATNr", "Value": "TestVat", "Type": "String", "IsRequired": "Y" }, { "Name": "UntaxedAmount", "Value": "100", "Type": "Currency", "IsRequired": "Y" }, { "Name": "TaxAmount", "Value": "21", "Type": "Currency", "IsRequired": "Y" }, { "Name": "Total", "Value": "121", "Type": "Currency", "IsRequired": "Y" } ], "Relations": [ { "Id": 1, "ModelId": 1, "Name": "Customer", "Fields": [ { "Name": "Name", "Value": "Customer From API", "Type": "String", "IsRequired": "Y" }, { "Name": "Address", "Value": "Test Street 33", "Type": "String", "IsRequired": "Y" }, { "Name": "Postcode", "Value": "2023AA", "Type": "String", "IsRequired": "Y" }, { "Name": "City", "Value": "Rotterdam", "Type": "String", "IsRequired": "Y" }, { "Name": "Country", "Value": "Netherlands", "Type": "String", "IsRequired": "Y" } ], "Relations": [] }, { "Id": 100, "ModelId": 2, "Name": "InvoiceItems", "Fields": [ { "Name": "Description", "Value": "Pizza 1 From API", "Type": "String", "IsRequired": "Y" }, { "Name": "Quantity", "Value": "2", "Type": "Double", "IsRequired": "Y" }, { "Name": "UnitPrice", "Value": "20", "Type": "Currency", "IsRequired": "Y" }, { "Name": "Taxes", "Value": "BTW 21%", "Type": "String", "IsRequired": "Y" }, { "Name": "Amount", "Value": "40", "Type": "Currency", "IsRequired": "Y" } ], "Relations": [] }, { "Id": 101, "ModelId": 2, "Name": "InvoiceItems", "Fields": [ { "Name": "Description", "Value": "Pizza 2 From API", "Type": "String", "IsRequired": "Y" }, { "Name": "Quantity", "Value": "1", "Type": "Double", "IsRequired": "Y" }, { "Name": "UnitPrice", "Value": "10", "Type": "Currency", "IsRequired": "Y" }, { "Name": "Taxes", "Value": "BTW 21%", "Type": "String", "IsRequired": "Y" }, { "Name": "Amount", "Value": "10", "Type": "Currency", "IsRequired": "Y" } ], "Relations": [] }, { "Id": 102, "ModelId": 2, "Name": "InvoiceItems", "Fields": [ { "Name": "Description", "Value": "Pizza 3 From API", "Type": "String", "IsRequired": "Y" }, { "Name": "Quantity", "Value": "5", "Type": "Double", "IsRequired": "Y" }, { "Name": "UnitPrice", "Value": "10", "Type": "Currency", "IsRequired": "Y" }, { "Name": "Taxes", "Value": "BTW 21%", "Type": "String", "IsRequired": "Y" }, { "Name": "Amount", "Value": "50", "Type": "Currency", "IsRequired": "Y" } ], "Relations": [] }, { "Id": 103, "ModelId": 2, "Name": "InvoiceItems", "Fields": [ { "Name": "Description", "Value": "Free Pizza 4 From API", "Type": "String", "IsRequired": "Y" }, { "Name": "Quantity", "Value": "1", "Type": "Double", "IsRequired": "Y" }, { "Name": "UnitPrice", "Value": "0", "Type": "Currency", "IsRequired": "Y" }, { "Name": "Taxes", "Value": "BTW 21%", "Type": "String", "IsRequired": "Y" }, { "Name": "Amount", "Value": "0", "Type": "Currency", "IsRequired": "Y" } ], "Relations": [] }, { "Id": 104, "ModelId": 2, "Name": "InvoiceItems", "Fields": [ { "Name": "Description", "Value": "Free Pizza 5 From API", "Type": "String", "IsRequired": "Y" }, { "Name": "Quantity", "Value": "1", "Type": "Double", "IsRequired": "Y" }, { "Name": "UnitPrice", "Value": "0", "Type": "Currency", "IsRequired": "Y" }, { "Name": "Taxes", "Value": "BTW 21%", "Type": "String", "IsRequired": "Y" }, { "Name": "Amount", "Value": "0", "Type": "Currency", "IsRequired": "Y" } ], "Relations": [] } ] } ] - Parameters (querystring):
-
Step 3: Download the generated document [HTTP Get] [URL of DocsNG]/api/Document/DownloadDocument
- Parameters:
- id (integer): The unique identifier of the generated document, which is returned as a response from the Generate API call.
- jwtToken (string): jwtToken of the user
- response: the binay of the generated document will be returned as response to the request
- Parameters:
Conclusion
Congratulations! You've successfully integrated DocsNG document generation into your application. Refer to this guide as you develop and refine your document generation workflow. If you have any questions or need further assistance, consult the DocsNG API documentation or reach out to our support team.
Happy coding!