Since we have released LiveDocx MailMerge API 1.1 many people have suggested interesting new features. We ourselves had some ideas, what to implement in future versions of the web service. This blog post is meant to summarize some of those feature requests and ideas to help you figure out what's coming up in the next LiveDocx version.

Save documents as HTML

TX Text Control 15, the technology LiveDocx is based on, supports embedding images in HTML. Thus, it is possible to introduce HTML as output format into LiveDocx. Whether as quick preview, as platform independent exchange format or for use in web apps, there's a wide variety of possible applications. As usual, you just feed your template and data into the API and it returns a single file, that contains everything, to you. Please note, that only recent browsers display embedded images correctly. If unsure, refer to respective browser's documentation.

Create multiple documents in one run

The new version will accept multiple lines of merge data. The resulting documents will be appended to one another, so that they become a single (possibly long) document. This is quite useful for scenarios such as label printing, creating vouchers or certificates, for instance. But we are pretty sure you, our users, will come up with some ideas how to put this to even better use.

Reduced file sizes

Documents containing images can become quite big. Version 1.2 of the LiveDocx MailMerge API addresses this problem, resulting in significantly reduced file sizes. By the time of this writing, the internal handling and management of image files, especially the compression settings, are thoroughly revised.

The benefits of this are obvious:
smaller documents → faster downloads → overall improved user experience

List of all available fonts

Since templates should ideally contain only fonts, which are installed on the server, and the free LiveDocx server only comes equipped with the Windows standard fonts, it's often desirable to have a list of the available fonts. If a template contains fonts, which are not installed on the server, the fonts a replaced by similar ones. In some rare cases, i.e. when using too exotic fonts, this automatic process does not work, and the generated documents lack some parts. LiveDocx MailMerge API 1.2 will provide a list of the available fonts, to enable its users to check with the server, before creating faulty documents.

Now that we have a couple of new and shiny templates, what do we do it them? Let's assume we want to create a telephone bill. We want to email it to the customer directly after creation, but—for legal reasons—the customer also receives a hard copy, printed on company letter paper. This means, the document generated for emailing and the one generated for printing differ in that the latter must not have a header, since that's already pre-printed on the company letter paper. Using IncludeText fields this is easy to accomplish.

Let's get ourselves equipped!

Besides a couple of templates, all we need is a little bit of application logic. In case you haven't created any templates of your own yet, you can use these:

template.docx (8.25 kb)

sub_template.docx (16.32 kb)

There are three different ways to toggle the inclusion/exclusion of sub-templates, when using IncludeText fields with LiveDocx. Let's take a look at 'em!

Using SetIgnoreSubTemplates()

The default for LiveDocx is to include sub-templates. I.e. when there's an IncludeText field in your template pointing to an existent sub-template, the sub-template is inserted at the corresponding position into the template holding the reference during the merge process.

To experience this yourself using the above templates, make sure to put the sub-template file into your server-side user directory as 'sub_template.docx' before you start merging. If you don't want to spend time on generating merge data, simply set it to null, i.e. SetFieldValues(null), and create the document. The resulting document contains a headline and an image coming from the sub-template.

If you need to exclude the sub-template, say for printing on company letter paper, there is just one more line of code for you to type. A call to SetIgnoreSubTemplates() using true as argument does the trick, i.e. SetIgnoreSubTemplates(true).

That was simple, wasn't it?

Using an empty sub-template

Obviously, another way to prevent anything from being inserted into the main template, is to replace the sub-template with an empty document. Please note, that the empty sub-template must not be a completely empty file but a valid doc, docx, rtf or txd file without contents. Big difference!

Deleting the sub-template

Also, if you do not upload the sub-template to the LiveDocx server or delete it before merging, the resulting document won't contain the contents of the sub-template—obviously. This is to prevent the merge process from crashing, in case you forget to put the sub-template in place, but can be used to toggle off the sub-template, too.

Playtime

For the impatient, here's a .NET project to try the things described above right away:

IncludeTextSample.zip (41.34 kb)

The above archive contains a VS.NET project. All you need to do is, double-click the .csproj file to fire up Visual Studio. Then, simply run the project, enter your LiveDocx credentials in the text fields and hit one of the buttons entitled 'Don't include' or 'Include'. After a few seconds the resulting document should open automatically. Feel free to play around with the source code to explore the possibilties LiveDocx offers to you.

A new feature in LiveDocx MailMerge API 1.1 is merging IncludeText fields. With IncludeText fields you can insert sub-templates into your main template during the merge process. This comes in handy, e.g. when you want to replace whole parts of your resulting document with something else under certain conditions. Another common application is to leave the document header blank, when printing onto pre-printed letter paper, but to include the document header, when sending the document by email. In this short article I'll show, how to build templates that enable you to use this new LiveDocx feature.

Prerequisites

To get started, you need at least two templates. The first one is your main template, which contains the IncludeText field(s), and the second one is the sub-template. Sub-templates may contain everything normal templates may contain, i.e. formatted text, fields (including IncludeText fields) and merge blocks. Building circular references with IncludeText fields won't work, of course. So, be sure to check your references, before merging.

The sub-template(s) have to be located in your template directory on the LiveDocx server. UploadTemplate() is your friend.

Creating Templates

All that's left to do now is to insert an IncludeText field into the main template. You can do this using MS Word or the TX Template Designer (LiveDocx Edition), which will be available here for download shortly. Instead of setting the field value to an absolute path like MS Word suggests, just insert the filename of the desired sub-template without leading path but including the file extension.

Please note, that MS Word will display an error message (something about the document name being invalid—depending on your system language). That's ok. MS Word expects an absolute path as argument to the IncludeText field, but LiveDocx will know, how to handle the document correctly.

That's it. There's nothing more to it. Now, you are good to go.

The next article on IncludeText fields will explain, how to merge or ignore sub-templates under certain conditions.

Now that there are two versions of the mail merge service released for quite a while, it is about time to explain the thoughts behind the version numbers.

A new minor version number, i.e. the number behind the dot like 1.1 following 1.0, indicates small improvements have been made. This is the case, when e.g. new features are added to the service, which hardly affect the interface and it remains completely backward compatible. The new features get added to the API documentation, the rest of the documentation remains unchanged and valid, of course.

Major additions to and/or changes in the interface on the other hand result in a change of the major version number, i.e. the number in front of the dot. For instance changing some or all of the method signatures, rendering the exiting client libraries like phpLiveDocx incompatible, would result in something like LiveDocx MailMerge 2.0. Also, the documentation would reflect this change by introducing a new section named after the new major version number.

For better orientation regarding minor versions, every entry in the API documentation has a field called "Introduced: <ver. no.>". The field informs the reader about when a particular method has been introduced into the service.

After a thorough server update and slight reconfiguration this morning we are proud to announce that version 1.1 of the LiveDocx MailMerge API is now available. This version is based on the recently released TX Text Control 15.0.

New Merge Field Types

LiveDocx MailMerge API 1.1 implements some new merge field types. Thus, this version now features following field types:

• MERGEFIELD
• DATE
• PAGE
• IF
• INCLUDETEXT

Additionally, to pay our respects to the beta status of our site and service, we have added

• NUMPAGES

to the list above, which is automatically merged at the end of the merging process with the total number of pages of the resulting document.

Reduced PDF file size

Many people will be pleased to learn that the size of generated PDF documents is dramatically smaller compared to those generated with version 1.0. In LiveDocx, PDF files are produced using the TX Text Control server component. Due to a PDF export filter in an early beta stage, the overly big PDF files came about.

SSL is mandatory

SSL is not optional but mandatory in LiveDocx MailMerge API 1.1. Regardless of the intended use of the service, SSL encryption always ensures maximum security and the integrity of the transmitted data.

New Service URL

The URL to use the new version is https://api.livedocx.com/1.1/mailmerge.asmx?WSDL, which can also be found in the footer of the LiveDocx website. Of course, the LiveDocx MailMerge API 1.0 will still be available. Also, SSL in version 1.0 remains optional.

Lastly, we want to apologize for any inconvenience the server update may have caused.

Have fun with the new version!

Due to some necessary maintenance work, the LiveDocx service and website will probably not be accessible on Tuesday, May 26, 2009 between 9:00 and 10:00 GMT. In advance, we appologize for any inconvenience.

We received loads of requests regarding the SSL encrypted version of LiveDocx. Finally, the API (api.livedocx.com) is now accessible using HTTPS:

https://api.livedocx.com/1.0/mailmerge.asmx

To enable SSL encryption in your existing projects, you simply need to switch to this new API. All traffic between your application and the LiveDocx service is encrypted. Of course, it is always recommended to use SSL for all sensitive data.

The non-SSL version is accessible as well and won't be deactivated as long as there are users for it. 

After long weeks of working on our core product TX Text Control, we are gathering new ideas and strategies for the future development of LiveDocx.

The next version of LiveDocx is going to support 3 new merge fields: IF, DATE and INCLUDETEXT.

The IF field can be used to compare a specific field value with an expression in order to insert a "true text" or a "false text". This is very nice for hiding information based on a specific field value. The Date field is quite self-explanatory: It inserts the current date. It is possible to specify the format of the date like this:

The format "dddd, MMMM d" would insert:

Saturday, November 26

The format "h:mm am/pm, dddd, MMMM d" would insert:

10:00 AM, Saturday, November 26

The INCLUDETEXT field can be used to insert the text and graphics contained in the named document. The format of the document will be recognized based on the file extension and can be uploaded to the LiveDocx server like all other normal templates.

The core product TX Text Control will be extended with loads of new features that will be part of LiveDocx as well. A very nice feature is PDF import. This enables LiveDocx users to convert PDF files into editable MS Word documents including images, fonts and text positions. We are thinking about creating specific web services for such tasks. The current LiveDocx service is MailMerge which can be recognized based on the namespace: api.livedocx.com/1.0/mailmerge.asmx

We are thinking about services for converting documents or assembling documents from text boilerplates.

Additionally, a LiveDocx trial version is planned to test LiveDocx on your own IIS server. It is planned to provide LiveDocx including a management tool for the management of databases, user accounts and templates.

I am very interested in your ideas for LiveDocx future developments. Feel free to post them in our forum:

http://www.theimagingsourceforums.com/forumdisplay.php?f=23

I just published my LiveDocx overview PowerPoint slides. A LiveDocx partner requested them and I thought to share these slides with the community. Feel free to use the slides when you need to present the LiveDocx idea to your colleagues or management.

LiveDocx.pptx (279.29 kb)

I would be glad to get your feedback on them.

After a month in beta stage, we got a phenomenal feedback from our users. We decided to open the LiveDocx service for free:

LiveDocx Service can be used completely free of charge.

There is no catch: The free version of the LiveDocx Service is identical to the version, which has been online since January 2009, with one exception: All methods which are related to sharing documents have been deactivated.

It is allowed to use LiveDocx in in-house projects and small-business end-user applications. It is not allowed to encapsulate LiveDocx in another web service or product that offers a similar functionality. If you plan to publish a product based on LiveDocx, you should get your own LiveDocx server to offer such functionality. We call that LiveDocx Appliance, which I would recommend, if you intend to generate many thousand documents per month.

Feel free to address your questions directly to me, if you need more help:

http://www.livedocx.com/pub/contact.aspx