Posted at: 1:06 PM on 07 September 2015 by Muhimbi
It is no secret that the real power of the Muhimbi PDF Converter for SharePoint comes from the ability to automate processes using workflows, it takes the human error factor out of the equation. Automatically convert, watermark and secure a file and write it to the Record Center when it changes? No problem, all fully automatic, nice, easy, repeatable, just what you need.
Then Microsoft introduced SharePoint 2013, which – in addition to the legacy workflow engine that we already support – comes with the optional Workflow Manager. You know… because things were just not complicated enough. This Workflow Manager only works on some SharePoint editions (not on SharePoint Foundation), must be deployed manually and uses a completely different architecture, who is going to use that? Well, it turns out that some people actually use it and – as we hate to say ‘no’ to our customers – we went back to the drawing board and hammered out support for Workflow Manager Workflows.
Support for Workflow Manager workflows is part of the upcoming 8.0 release. Want early access? Please contact us.
So, how does this work? Well pretty much the way you expect it to. When deploying the Muhimbi PDF Converter for SharePoint on SharePoint 2013, Central Admin’s Farm Solutions screen will show that a new Solution named ‘muhimbi.pdfconverter.workflow manager.sp2013.wsp’ has been deployed automatically. On systems that do not have the Workflow Manager installed this Solution is ignored, but those lucky enough to be running the Workflow Manager will see a range of new Workflow Activities in SharePoint Designer when selecting ‘SharePoint 2013 workflow’ as the Platform Type when creating a new workflow.
Workflows using the SharePoint 2013 Workflow Platform Type now show the same range of PDF related workflow actions that are present for workflows using the SharePoint 2010 Workflow type. The only difference is that the legacy Convert to PDF workflow action is no longer present as this has been replaced by the more flexible Convert Document action.
Building a workflow is a matter of selecting the appropriate action and filling in the blanks. All actions are self-describing and do pretty much what you expect them to do. Links to the documentation for the SharePoint 2010 equivalents can be found below:
Secure PDF: Encrypt a file and restrict the ability to print or copy content.
Split PDF: Split a single, larger, file into multiple small ones.
It is possible to ‘chain’ multiple operations together by capturing the List Item ID of the output of one operation and use that to lookup an item, by its ID, in a follow up action. This way you can convert a document to PDF and then watermark or secure the generated PDF, all in a single workflow.
Most workflow actions require input or output files to be specified. For details about specifying file names and paths see this Knowledge Base Article.
SharePoint 2013 Workflow Manager workflows allow more complex scenarios than SharePoint 2010 workflows. For example it is possible to iterate over multiple files and convert them to individual PDFs, or build a list of file paths to feed into our Merge Documents into PDF action.
Anyone who has ever looked at product packaging is familiar with basic barcodes, those black and white vertical stripes that have made such a positive impact on cash registers. (I am old enough to remember pre-barcode days, oh the horror). Although first introduced in in 1997, QR Codes - a variation on the traditional barcode - have become really popular in the last few years as they allow much more data to be stored, with a very high level of error correction.
A popular use for QR codes is to embed them in documents. They can store all kind of information (almost 3KB at the time of writing) including meta-data such as a Document ID, last update time, author, anything really. However, to create these codes and add them to your documents, that is tricky, especially in SharePoint, what to do….. what to do!
Support for QR codes is part of the upcoming 8.0 release, if you would like early access then please contact us.
Have a look at the examples below. The various facilities are largely self-describing so there is no need to go into too much detail. For more information and examples related to watermarking in general, see the Watermarking hub in our Knowledge Base.
Regardless of the method used to apply the QR watermark, you always need to specify the following information:
Content: The content to embed in the QR code. This will need to match the specified input mode.
Input mode: Specify the appropriate mode for your content: - Binary: Any value including text, URLs etc. - AlphaNumeric: Numbers, (Upper case) characters and SPACE, $, %, *, +, -, ., /, : - Numeric: Numbers only
Error correction level: Select the appropriate level for your needs: Low, Medium, Quartile, High
When using Nintex Workflow there is only a single Watermark PDF workflow action. In the action’s configuration screen select QR Code as the Watermark Type and fill in the blanks. For details about adding watermarks using Nintex Workflow see this blog post.
Muhimbi’s real-time watermarking facilities
The PDF Converter for SharePoint comes with this cool facility to add a watermark the moment a PDF is opened. If the information embedded in the QR Code is user-specific or time sensitive (e.g. the name of the user who opened the PDF, or the current date / time) then you may want to consider using this facility instead of a workflow. QR codes can be added using our XML based watermarking syntax.
Adding a QR code using K2 blackpearl is easy as well. For details about how to integrate the Muhimbi PDF Converter with K2, as well as some examples, see this article.
Muhimbi’s Web Services based API
QR codes can also be added using our flexible web services based API, regardless of platform (C#, Java, PHP, Ruby etc). The associated class and enumerations can be found below. For an example of how to create watermarks from code see this blog post.
One of the industries that specify such requirements is the U.S. Food and Drug Administration (FDA). In their specifications for Providing Regulatory Submissions in Electronic Format — Certain Human Pharmaceutical Product Applications and Related Submissions Using the eCTD Specifications they list the following requirements.
Do not activate security settings or password protection: Although we support a range of PDF Security, Restriction and encryption facilities. The FDA’s recommendation is to not apply any security to the generated documents.
Fully embed all non-standard fonts:Embedding or stripping of embedded fonts is fully supported by our software. Even better, just use PDF/A output which automatically takes care of most requirements.
Avoid image-based PDF files whenever possible: Image based content can be hard to read on screen and – even worse – is not searchable. As a result people cannot copy its contents or find it using whatever search engine they happen to use. When dealing with image based content such as scans and faxes, use our Optical Character Recognition (OCR) abilities to automatically recognise all text and include it in the PDF file.
Optimize the PDF for fast web view: Many PDF files are accessed via the internet. To prevent long downloads, PDF files can be Linearized / Optimised for fast web view. This reduces the loading time of the initial pages considerably.
Table of contents (TOC): The ability to merge multiple files is probably the second most used feature provided by our software. However, the result of a merge operation may result in a document that is hundreds of pages long, which can make navigation a bit difficult. Our software automatically adds PDF bookmarks to ease navigation, but even better can automatically generate a full featured Table Of Contents.
Initial View Settings: Making sure that the PDF is displayed in the most optimal manner when the document is opened removes the effort from the end user and reduces the need for training. Naturally we fully support this.
We like to throw in a wildcard every once in a while, functionality that no-one has asked for, but we think our customers will really like. This tends to work out very well, for example the time we decided to provide a lot of flexibility around copying of SharePoint meta-data. Another one of those crazy wild-cards was support for the conversion of InfoPath forms to PDF, XLS, HTML and DOC. InfoPath is pretty obscure, right? Microsoft has even retired it, who needs a converter, who even cares? EVERYONE! A surprising number of people want to convert and archive InfoPath files, and for great reasons as well.
Over the years we have added many popular facilities to the InfoPath converter including the ability to convert InfoPath attachments and the ability to dynamically control which InfoPath view to use for PDF conversion. There was only one problem though, as Microsoft stopped caring about InfoPath, they slowly but surely crippled its PDF output abilities. It all started with the introduction of Internet Explorer 9 and was made worse with the introduction of Windows Server 2012 and InfoPath 2013. Out of the box, and completely unrelated to our software, InfoPath doesn’t even include content of checkboxes in a PDF, and that is just one of the smaller problems.
Our support desk is always happy to assist those customers who, for reasons beyond their control, cannot downgrade Internet Explorer or switch Windows versions. More often than not this resulted in solutions that worked well enough, but…. ughhh… horrible hacks, loads of support hours wasted, non-intuitive solutions, this has to stop…. and, as of today, it has!
The new InfoPath converter is part of the upcoming 8.0 release, if you would like early access then please contact us.
The last 2 options are particular important for forms that have been designed with SharePoint’s Forms Services in mind. Although those forms are created in InfoPath as well, and can be converted using our software just fine, these forms typically don’t specify a page size or orientation. The new PDF Converter automatically picks up these settings when they ARE defined in the form, but when the information is missing it will try to substitute it. These settings can be overridden globally or at the individual conversion level.
Before (left) and after (right). Click to zoom in and look at those horrible borders and image quality in detail.
Although the default values suffice for most situations, the following entries can be controlled via the conversion service’s configuration file. For details about how to edit this file see this article..
InfoPathConverterFullFidelity.UseNativePrintEngine: This setting controls which InfoPath converter is used, the legacy one (false) or the new high-fidelity one (true). This setting is automatically populated with the option selected during installation.
InfoPathConverterFullFidelity.DefaultPaperSize: The output paper size to use for InfoPath views without a specified printer / paper size. This does not change the paper size for views where that information IS specified. Leave this setting empty to take the value from the default printer or specify a named format such as 'A4' or 'Letter' (Full list of accepted paper sizes). PLEASE NOTE THAT THIS VALUE IS CASE SENSITIVE.
InfoPathConverterFullFidelity.ForcePaperSize: Force the paper size, regardless of the printer / paper size being present in the definition of the InfoPath view.
InfoPathConverterFullFidelity.DefaultPageOrientation: The Page orientation for InfoPath views that don't explicitly specify a printer / paper size. Either 'Portrait' or 'Landscape'. Leave empty to let InfoPath decide.
InfoPathConverterFullFidelity.ForcePageOrientation: Force the page orientation regardless of the printer / paper size being present in the definition of the InfoPath view
The easiest way to enable the new InfoPath converter is to do so during the setup process, for details see this blog post.
In order to use the new InfoPath converter on 64 bit systems, please install the 64 bit version of Office / InfoPath. 32 bit Windows versions work fine with the 32 bit version of Office / InfoPath.
If you are still on Windows Server 2003 then we don’t judge you, but you will need to contact our support desk to request assistance with the deployment of the new InfoPath converter as after 12 years… well… things have moved on a bit.
Any questions or feedback? Leave a comment below or contact us, we love talking to our customers.
At the time of writing our range of Server Side PDF Conversion and Automation based products, including the Muhimbi PDF Converter for SharePoint and the Muhimbi PDF Converter Services (for Java, .NET, PHP, Ruby) have been in the market for over 7 years. Although our setup experience has always been fine, it has never been excellent. Being excellent is something we strive for so we have dug through our historical support desk tickets to determine the worst pain points and address them as part of the new installation ‘experience’.
Carrying out a full deployment still requires some work and preparation – the entire product is a bit ‘enterprisey’ - getting the proper Windows account in place, granting privileges and installing some prerequisites, these steps are explained in detail in Chapter 2 of our comprehensive Administration Guide. Do yourself, and our support desk, a monumental favour and read that chapter, including references to all Appendices, in full. You will save yourself a lot of time and frustration.
The new installer is part of the upcoming version 8.0, if you would like early access then please contact us.
Let’s walk through a typical deployment and highlight some of the decision points. The screenshots and process below is based on the PDF Converter for SharePoint. Being less complex, the PDF Converter Services setup process is largely the same, it just lacks some of the SharePoint specific screens (and that installer uses a yellow background colour so it is immediately clear which product you are installing).
Naturally the first step is to download the free trial version. Once downloaded run setup.exe, resulting in the following screen. This screen allows for the Administration Guide to be opened in your PDF Reader, open it and start reading at chapter 2. We know you don’t want to read manuals, but it will save you time later.
Click Next to continue, read the boring but essential license agreement and accept the terms to continue. You can even print it and use it as wallpaper, everyone is a winner.
The following screen only applies to the PDF Converter for SharePoint and provides the following three options. Please read our blog post about typical deployment scenarios to learn more about how highly scalable products like the Muhimbi PDF Converter are typically deployed. When executing the installer on a machine that is not part of a SharePoint farm then the SharePoint related options will be disabled.
Install the Conversion Service on this system and the SharePoint front-end on the entire farm: This is the recommended option for most installations providing the installer is being executed on a single server SharePoint farm or on one of the App servers. This option deploys the conversion service (a Windows service that does all the heavy processing work) on the current server and pushes the SharePoint ‘WSP’ file out to all SharePoint servers.
Install only the Conversion Service on this computer: Use this option to install only the conversion service on the current system, and skip the deployment of the SharePoint WSP files. This is a good option when installing the conversion service on a system that is not part of a SharePoint farm, or if you are not yet ready to deploy the SharePoint front-end software.
Install the SharePoint front-end on the entire farm: This option must be executed on only one of the SharePoint servers. It automatically pushes the SharePoint WSP to all servers in the farm. When selecting this option you will be asked to specify the name of the server that will host (or already hosts) the conversion service. Doing so will automatically update the location of the conversion service in our Central Administration screen.
If the conversion service is being deployed as part of the current installation then use the following screen to specify the path to deploy it to. It is recommended to accept the default path, or just change the drive letter. It will work fine in other locations, but it may make troubleshooting more difficult.
Providing the conversion service is being deployed as part of the current installation process, you will be asked to specify the name of the Windows account the conversion service will run under. This may be a local machine account (in that case leave the domain name empty) or a domain account (please enter the domain in the separate field). This account must be a member of the local Administrators group and does not require any other special settings. Unless specified otherwise, the account will be granted ‘Log on as a Service’ rights automatically.
Now, this is where it (finally) gets interesting. As mentioned previously, there are some prerequisites you must get in place, as described in Chapter 2 of the Administration Guide. The installer will check that all these prerequisites are indeed in place and highlight any problem areas with a red X. If any warnings are displayed then you may continue with the installation process and address, or ignore, them after the installation completes. However, for the best experience you should close the installer, address any issues, restart the installer and check that the problems have been resolved.
Depending on your exact needs, and providing you are deploying the conversion service, you may want to change the following settings in the next screen:
Open TCP Port 41734 on the Windows Firewall: In a multi-server farm it is essential that the front end servers can communicate with the conversion server. The installer can open the correct port automatically, but please take into account that this only works for a basic Windows Firewall installation. When deploying the software in an environment with a different firewall or when the firewall is automatically configured and locked down, you may need to open this port manually.
Disable the Loopback Check: In certain cases a security feature in Windows makes it difficult to connect to a server by machine name, this is known as the Loopback Check. Providing this option is enabled (the default option in Windows) you can use the installer to disable this check. If this option is already disabled (perhaps by an administrator or another process) then you will not be able to change it using the Muhimbi installer. This prevents interoperability problems with other software. If you wish to change this setting by hand then see this blog post.
Download and install Ghostscript: Some functionality provided by the Muhimbi PDF Converter leverages a technology known as Ghostscript. If you expect to carry out conversions to PDF/A, conversions between different PDF versions or use the recently introduced high fidelity InfoPath converter then you should select this option. The installer will download and install Ghostscript automatically, but if the server you are deploying the conversion service on does not have internet connectivity, which is quite common in data centres, then you have the option to download and install Ghostscript manually. Providing it is installed in the default path (on any of the system’s drives) the PDF Converter will automatically detect it.
Our range of PDF Converters provide support for some less than common file formats including Microsoft InfoPath. (Microsoft has discontinued support so start archiving to PDF). Microsoft has slowly crippled InfoPath PDF support over the past few years so if you are running a Windows version newer than Windows Server 2008R2 or an Internet Explorer version newer than version 9, you will find that InfoPath PDF output does not work very well. On those systems, as well as other systems, it is highly recommend to enable our new converter. The only reason to use the ‘Legacy Converter’ is if you already use the Muhimbi PDF Converter in your environment to convert InfoPath to PDF and everything is working well. If it ain’t broke, don’t try to fix it.
Please note that the new InfoPath converter requires Ghostscript to be installed on the system running the conversion service (see the previous screen). In order to use the new InfoPath converter on 64 bit systems, please install the 64 bit version of Office / InfoPath. 32 bit Windows versions work fine with the 32 bit version of Office / InfoPath.
If you already have a license key then specify its location in the following screen. To install the trial version there is no need to specify a license file. If you have a license for the PDF Converter Professional add-on license then please copy that license file to the path the conversion service is being deployed to. Once the conversion service has been deployed you will find a handy shortcut to this folder in the Windows Start Menu.
That is it, the installer will now deploy the selected components and configure the local system in line with the specified settings. This may take a couple of minutes.
If all went well you will see the following screen. Congratulations, you have done it, woohooooo!
Providing you are installing the SharePoint front-end as part of the current installation process, our Central Administration screen will be opened automatically. Use this screen to configure the system further or execute a validation test to check that everything is indeed working as expected. If you encounter any problems with the validation process then please see this Knowledge Base article.
We recommend using Central Admin’s Solution Management screen to verify that the SharePoint WSP files were deployed without errors or warnings. The following WSP files are typically deployed.
muhimbi.pdfconverter.*.wsp: This WSP contains the main PDF Converter facilities.
muhimbi.licensing.*.wsp: The Muhimbi License Manager.
muhimbi.pdfconverter.workflowmanager.*.wsp: Deployed on SharePoint 2013 (and newer) systems only. This WSP file contains the workflow actions for the new ‘Workflow Manager’ based workflows.
Once it has been confirmed that everything is installed correctly, you may want to enable or disable various SharePoint Features related to the Muhimbi PDF Converter. A full list of all SharePoint Features can be found in the SharePoint Administration Guide, but some of the key ones are:
Muhimbi PDF Converter: Enable the main PDF Converter user interface and activate the workflow activities for SharePoint Designer and SharePoint 2010 workflows. This Feature is enabled by default.
Muhimbi PDF Converter – Automatic PDF Processing User Interface: Enable the user interface for the real-time watermarking and security facility. Please enable Muhimbi PDF Converter – Automated PDF Processor before enabling this Feature.
Muhimbi PDF Converter – Automated PDF Processor: Enable the module that controls real-time processing.
If you currently have a version of the Muhimbi PDF Converter installed, a version older than 8.0, then please uninstall that version manually before installing version 8.0. Before starting the uninstallation process have a look at the Upgrading section in the Administration Guide to make sure you don’t lose any changes that may have been made by manually adjusting various files.
Uninstall SharePoint Front-End: Manually retract and remove the WSP files from Central Administration or run the uninstall.cmd scripts that ship alongside the version of the PDF Converter that is currently installed. Please make sure that both the PDF Converter and License Manager WSPs are uninstalled.
Uninstall Conversion Service: Use Windows’ Add or Remove Programs facility to uninstall the conversion service.
Wow, what a title for a blog post ‘Automatically padding documents for merging double sided documents’, what does that even mean? Well, let me try and explain.
One of the more popular features in our range of server side PDF Conversion products is the ability to merge multiple documents (e.g. a couple of MS-Word, PowerPoint, Excel and Image files) into a single PDF. Works great! However, up until now we did a straight merge, each document was merged directly after the previous one. Although most of the time that is the desired behaviour, some merged documents are really intended for printing, more specifically, double-sided printing. When printing double sided you typically want each new document to start on the right-hand (or Odd) page.
As of version 8.0 (Out soon, contact us if you require early access) we make it possible to automatically inject blank pages for situations like the one described above.
This behaviour can be controlled in a number of ways.
<!-- Control merge behaviour. Leave empty to use the setting specified in the web service call.
* Next - When merging, start each document on the next page.
* Odd - When merging, start each document on an odd page.
* Even - When merging, start each document on the next even page. –><addkey="Merging.ForceDocumentStartPage"value=""/>
Request by request basis
If you do not wish to apply this new behaviour to all merge operations then it is possible to control it on a request-by-request basis by passing a value into MergeSettings.DocumentStartPage as part of a web service call.
Posted at: 12:16 PM on 04 June 2015 by David Radford
Yes, you heard that right! The popular Muhimbi PDF Converter for SharePoint is now available for SharePoint Online and Office 365. What does this mean for you? Well, if you’re using SharePoint Online / Office 365 or are looking to move to it, you can now access the Converter’s functionality from any SharePoint Online Site Collection, available directly from the SharePoint App Store!
SharePoint Online is an increasingly popular way for companies, large and small, to leverage the advantages of SharePoint, without the server and maintenance overhead of on-premise installations. It also makes it easy to grow when usage increases, just like the Muhimbi PDF Converter for SharePoint Online. Our new subscription model allows you to easily add features and capacity as your environment and needs grow, without the need to carry out complex software deployments on your own servers. From large to small- we convert them all!
To start, you can find an overview of the available features and various subscription tiers in the brochure attached to this Knowledge Base Article.
We’ve worked hard to provide our SharePoint Online customers the same experience our on-site customers have come to expect. This means, baring some minor limitations due to the SharePoint Online model, you’ll get the same full featured, robust application we’ve long provided for SharePoint on-premise.
With many more features, including our popular real-time (‘on open’) watermarking facility, and support for Nintex Workflow for Office 365 to come.
Handy ribbon menu convert icon for the User Interface? Right here and in the dropdown context menu:
Convert and merge multiple file types from the User Interface including meta-data? At your service from the same button:
Create custom SharePoint Online workflows using our workflow actions? Well, of course!:
The Muhimbi PDF Converter for SharePoint Online supports all our standard file formats. Yes, including InfoPath- and not just standard InfoPath forms, but the browser enabled ones your users have been filling out in SharePoint Online! The Converter for SharePoint Online also uses our brand new InfoPath conversion engine, which eliminates many of the formatting issues that have begun to crop-up when using the latest Windows Server and Internet Explorer versions.
This all sounds great! How can I get the Converter for our SharePoint Online environment? It’s easy! Just go to the SharePoint App store, select the Muhimbi App and click the green “Add” button. Once that’s done, just attempt a conversion from the User Interface, enter your e-mail address when prompted and begin you fully featured free trial. If you want to create SharePoint Designer based workflows, just follow the simple instructions in this link (or watch the how-to video) in order to deploy our workflow activities.
The Muhimbi PDF Converter for SharePoint Online is a new product, built on our time tested on-premise platform, and like our on-premise version, is very actively developed. Please check back here for new features and functionality or subscribe to our newsletter to keep up-to-date as we continue to improve this newest member of our Muhimbi PDF Converter line of products.
As always, our support desk is happy to hear from you if you have any questions or need some help with getting things to work the way you want. Please feel free to contact us at: firstname.lastname@example.org or browse our comprehensive knowledge base.
Although our developers have been working hard on the SharePoint Online version of the Muhimbi PDF Converter, that doesn’t mean we have forgotten about the on-premise version, after all it is used on thousands of servers.
Today we are announcing the release of version 7.3, which - in addition to having a fancy new Table Of Content Generator - also includes a number of bug fixes and major performance improvements when merging large files.
A quick introduction for those not familiar with the product: The Muhimbi PDF Converter Services is an ‘on premises’ server based SDK that allows software developers to convert typical Office files to PDF format using a robust, scalable but friendly Web Services interface from Java, .NET, Ruby & PHP based solutions. It supports a large number of file types including MS-Office and ODF file formats as well as HTML, MSG (email), EML, AutoCAD and Image based files and is used by some of the largest organisations in the world for mission critical document conversions. In addition to converting documents the product ships with a sophisticated watermarking engine, PDF Splitting and Merging facilities, an OCR facility and the ability to secure PDF files. A separate SharePoint specific version is available as well.
Automatically Generated Table Of Contents
In addition to the changes listed above, some of the main changes and additions in the new version are as follows:
EML to PDF - Accessing content stream of non-leaf entities is not supported.
EML to PDF - Attachments present in an attached EML file show as attachments of the main file
System.ArgumentOutOfRangeException when merging AnyDWG PDF Files.
NullReferenceException while merging
NullRefException when merging certain PDF files
Object reference not set to an instance of an object when merging certain files
Merge Operations reset the security settings
Error in 'PdfLoadedPageCollection.GetPage' while merging certain files
Loading some existing PDF files is slow (e.g. for merge operations)
Although our developers have been working hard on the SharePoint Online version of the Muhimbi PDF Converter for SharePoint, that doesn’t mean we have forgotten about the on-premise version, after all it is used on thousands of SharePoint 2007, 2010 and 2013 servers.
Today we are announcing the release of version 7.3, which - in addition to support for K2 blackpearl workflows and a fancy Table Of Content Generator - also includes a number of bug fixes and major performance improvements when merging large files.
For those not familiar with the product, the PDF Converter for SharePoint is a lightweight solution that allows end-users to merge, split, watermark, secure, OCR and convert common document types - including InfoPath, AutoCAD, MSG (email) MS-Office, HTML and images - to PDF as well as other formats from within SharePoint using a friendly user interface, workflows or a web service call without the need to install any client side software or Adobe Acrobat. It integrates at a deep level with SharePoint and leverages facilities such as the Audit log, Nintex Workflow, K2 blackpearl, localisation, security and tracing. It runs on SharePoint 2007, 2010 & 2013 and is available in English, German, Dutch, French, Traditional Chinese and Japanese. For detailed information check out the product page.
Use K2 SmartObjects to Convert, Merge, Watermark and OCR files.
In addition to the changes listed above, some of the main changes and additions in the new version are as follows:
EML to PDF - Accessing content stream of non-leaf entities is not supported.
EML to PDF - Attachments present in an attached EML file show as attachments of the main file
K2 blackpearl comes with a number of different workflow editors. The majority of K2 workflow designers will be most familiar with K2 Studio, but Visual Studio as well as web based workflow editors are also available. This post describes how to create a basic workflow to convert documents to PDF (as well as other formats) using a basic K2 Designer workflow. Similar tutorials are available for K2 Studio, Nintex Workflow as well as SharePoint Designer.
A note on licensing the Muhimbi PDF Converter for SharePoint when used in combination with K2 blackpearl. Muhimbi’s licensing model is very simple, if a server runs Muhimbi Software in any way shape or form, then it requires a server license. Even though the PDF Conversion engine may be installed on a non-K2 server, all K2 Servers run our SmartObjects and therefore require a license. For details, in plain English, about how Muhimbi’s software is licensed, see this Knowledge Base Article.
A version of this blog post can also be found in the User Guide, Chapter 5.3.
Before creating the workflow, please make sure Muhimbi’s K2 Integration facilities have been deployed as described in the Administration Guide, Appendix – Deploying K2 Integration facilities. Basic knowledge of creating workflows in K2 Designer, and having the privileges to do so, is assumed.
This tutorial was written for SharePoint 2010. Muhimbi’s PDF Converter for SharePoint integrates equally well with SharePoint 2007 & 2013, but the actual steps for creating K2 workflows differ in each SharePoint version, particularly in SharePoint 2013. Please refer to K2’s tutorials and documentation for your particular environment.
The Muhimbi PDF Converter for SharePoint is exposed in K2 as a series of SmartObjects. By default SmartObjects are not available for use in the K2 Designer, an administrator must add them. The steps to do so are as follows:
In the relevant Site Collection open K2 Site Settings. If this option is not available then please make sure the relevant K2 Designer SharePoint Features have been enabled at the Site Collections and Site Level.
Under K2 Designer for SharePoint Management select Configure SmartObject Access.
If Muhimbi Document Converter for SharePoint is not already present in the list, click Add new item.
In the Add SmartObject Window open the Muhimbi Folder and tick the box next to Muhimbi Document Converter for SharePoint.
Under Advanced, select the option to Automatically create all methods and click Finish to complete the operation.
Creating the workflow
In this tutorial we will create a basic workflow to convert files to PDF and associate the workflow with a Document Library. This workflow is similar to the one we built using K2 Studio, but as K2 Designer works slightly differently we have to jump though some additional hoops.
Create a new Document Library named Tutorial2 in a site collection of your choice.
In the Tutorial2 Library, select the Library ribbon tab and click K2 Workflow.
In the Welcome dialog, assuming it is displayed by default, select the Create a new workflow option.
Name the workflow Tutorial2, accept the default settings and, as this tutorial does not need any of the other Wizard screens, click Finish.
In order for a SmartObject to be able to convert a document a number of parameters are needed. In K2 Studio these parameters (EventDetails.ListItemRelativeURL and EventDetails.SiteURL) are available from the Context Browser, but in K2 Designer we have to manually create them. The steps are as follows:
In K2 Designer select File / Configure Workflow Settings / Data Fields.
Click the Add button and specify SiteURL as the name.
Although we could use a complex regular expression to determine this value at run time, let’s keep it simple and specify the URL to the site collection as the Default Value. In our case http://portal.denallix.com/ (including the trailing slash!).
Click OK and add another Data Field named ListItemRelativeURL.
Accept the default settings, click OK and OK again to close the Data Fields dialog.
Hover the mouse over the Start line in the designer, a button will appear, click it and confirm the question to add a new step.
Select the Workflow Steps tab in the ribbon and drag the Set Data Fields activity onto the newly created step.
We already know the SiteURL, but we need to calculate the value of the ListItemRelativeURL by taking Document Context.Document URL and removing the SiteURL from the beginning. This is not difficult, just a bit fiddly.
In the Context Browser open Inline Functions / Text and drag the Mid(Text,Start) on top of ListItemRelativeURL.
In the Editor that is opened drag and drop Document Context / Document URL onto the Text field.
Drag and drop Inline Functions / Text / Length onto the Start field.
In the Editor that is opened drag and drop Data Fields / Site URL onto the Text field.
Click OK in the various Edit windows and verify that the Set Data Fields Wizard looks as follows.
Click Finish to continue.
With the required data fields in place, select the SmartObjects tab and drag the Convert Document smart object onto the empty workflow container and fill out the fields:
Source URL: The URL of the document to convert. The syntax is as per this post, please make sure that the web application name (http://yourwebapp) IS NOT included in the URL. In this tutorial we use the previously calculated data field by dragging Context Browser / Data Fields / ListItemRelativeURL onto the SourceURL field.
SharePoint Site URL: Similar to K2’s other SharePoint SmartObjects and Wizards, you will need to specify the URL of the site collection the workflow is acting on. The steps are identical to specifying the Source Url, just select SiteURL from Data Fields.
Destination URL: The optional path and file name of where the converted file will be written to. When left empty the converted file will be saved in the same folder as the source file using the same file name, just with the extension of the specified file type. This field uses the same format and rules as the Source URL field. In this tutorial we’ll leave this field empty. For details on what locations documents can be converted to and how to specify paths, please see here.
File Type: Theextension of the file type we are converting to. In this case assign the PDF value.
Include Meta-Data: In this example we want to copy all meta-data available on the source document to the converted document. Please accept the default Yes value
Optional Parameters: The Muhimbi PDF Converter is a very powerful product that allows many different settings to be specified. It is not feasible to make all of these settings available via individual field mappings, which is why we have developed a special XML syntax to populate these parameters. For this tutorial leave this field empty, you can find more details in this blog post. Please keep in mind that K2 Designer does not provide support for entering line breaks in SmartObject mappings so we recommend creating this XML in a regular code editor (or Notepad) and copy it from there into the Optional Parameters field.
Click Next followed by Finish, this tutorial does not use the return properties.
From the File option in the ribbon select the Deploy option. Click Next (twice) followed by Finish.
Testing the Workflow
Verify the workflow is working correctly by uploading an MS-Word file (or Excel, MSG, TIFF, PowerPoint or any of the many other formats we support) into the Tutorial2 Document Library and manually starting the workflow on the file. To manually start a workflow, in SharePoint open the context menu for the relevant file and select the ‘Workflows’ option.
If all has been configured well, and the workflow has been created correctly then - within a few seconds - a PDF copy of the source file should appear in the Tutorial2 library.
If the workflow does not work correctly then either use the Process Overview report in K2 Workspace to drill down into the workflow, or - and this is what we like to do - insert a Send E-mail step between the Set Data Fields and Convert Document steps, and populate the email with the content of the various data fields. By sending the email to Context Browser / Workflow Context / Originator E-mail it is easy to verify that the workflow is actually running and get an overview of what is going on without having to dive into the K2 Workspace Reports.
For more details on how to create SharePoint Workflows using K2 blackpearl see the K2 Website. A fully installed Virtual Machine (Excluding the Muhimbi PDF Converter for SharePoint) is available as well.