We recently released the Muhimbi PDF Converter Xtension for Nintex Automation Cloud. You can download it here or learn more about available Muhimbi deployments for Nintex on our product page.
We have been a little bit in love with Nintex Workflow ever since we integrated it into the Muhimbi PDF Converter for SharePoint all the way back in the SharePoint 2007 era. Although we started simple with just a basic PDF Conversion workflow action, over the years we added Nintex Workflow support for all our Workflow Actions to make it possible to Convert, Merge, Watermark, Secure and OCR documents.
With more and more companies moving to Office 365, and specifically SharePoint online, the industry's focus is moving towards online services, resulting in such products as the Muhimbi PDF Converter for SharePoint Online and Nintex Workflow for Office 365. Although other workflow engines such as Microsoft Flow, Azure Logic Apps, and the built-in SharePoint Online Workflow Manager make it possible for 3rd parties such as Muhimbi to directly integrate their services, this is currently not possible in Nintex Workflow for Office 365.
We don't like ' not possible' and, as many of our shared customers frequently request Muhimbi / Nintex Workflow for Office 365 integration, we decided to see if perhaps we can implement a workaround to make the two products work together. The workaround that our customers have been using for years (Create a SharePoint Designer Workflow using our workflow actions and invoke that from Nintex Workflow for Office 365) works well, but it is just....well... unsatisfactory. In this post, we'll show how to integrate the functionality exposed by the Muhimbi PDF Converter for SharePoint Online directly into a Nintex Workflow by invoking our comprehensive REST API.
Background
When we first released the Muhimbi PDF Converter for SharePoint Online in early 2015, we were very much aware that - due to technical limitations in the SharePoint Online platform - it would not be possible to bring the full power of our existing on-premise (SP2007-SP2016) products to The Cloud. The first release focused on the most important elements (the PDF Conversion user interface and Workflow Actions for SharePoint Designer), but one of the key features of our on-premise products was missing, an API to allow integration with 3rd party solutions and software partners.
Although our customers are very happy with the comprehensive Web Services (SOAP) interface exposed by our on-premise products, it is less suitable for use by online subscription based services. Instead we decided to go for a brand-new, and much-simplified, REST based interface as that is how modern systems, especially Cloud based products, talk to each other.
This new REST based service was launched earlier this year as part of the Muhimbi PDF Converter Services product. A separate product that has no dependencies on SharePoint and can be used to integrate with such services as Microsoft Flow, Azure Logic Apps, C#, Java, PHP, JavaScript, Python Ruby and many other services including ... and here it comes .... Nintex Workflow for Office 365.
Although available as a stand-alone subscription, this new service is automatically included in each PDF Converter for SharePoint Online subscription at no additional charge.
Prerequisites
Before you begin, please make sure the following prerequisites are in place:
- Muhimbi PDF Converter for SharePoint Online installed and enabled in your workflow's site with a full, or trial, subscription.
- Muhimbi PDF Converter REST-based API for Server Platform full or trial subscription and associated API KEY. (Start trial)
- Nintex Workflow for Office 365 installed and enabled in your workflow's site.
- The appropriate privileges to deploy these Apps, and author workflows.
- Working Knowledge of Nintex Workflow for Office 365. This is not a masterclass in Nintex Workflow for Office 365 development.
Please note that this tutorial is for the SharePoint Online version of Nintex Workflow. For details about using our software in combination with the on-premise (2007-2016) versions of SharePoint, see this Knowledge Base article .
Building the workflow
Let's have some fun and build a workflow! It is strongly recommended to follow the tutorial below, but the workflow is available for download as well. Import it in Nintex Workflow for Office 365, SET THE API KEY, publish it and you are ready to go.
Navigate to a site collection and document library of your choice, one that matches the prerequisites listed above, and choose the option to create a new Nintex Workflow. In this example, we use the standard Shared Document library that is available on most site collections.
Create the following workflow variables as we need them later:
- JSON (Text): Contains the JSON, JavaScript Object Notation, the command that will be sent to the conversion service.
- API_KEY (Text): A unique ID that will be used to look up your Muhimbi subscription details.
- ResponseText (Text): The status message returned by the Conversion Service.
- ResponseCode (Integer): The status code returned by the Conversion Service.
As a first step (you should always do this) insert a Set Workflow Status action, edit it and set it to Started. This will show us that the workflow has actually triggered (it is always a guess in SharePoint Online), it will also give us something to click on to inspect the current status of the workflow.
Add a Build String action and set the Output to the JSON workflow variable. In the String field enter the following:
[
"sharepoint_file":
[
"site_url":"{Workflow Context:Current site URL}",
"source_file_url":"{Current Item:Server Relative URL}",
"destination_file_url":"{Current Item:Server Relative URL}.pdf"
],
"output_format":"PDF",
"fail_on_error":true
]
PAY ATTENTION TO:
- JSON Notation: You may be familiar with JSON notation, but please note that we have replaced the curly braces - { } - with square brackets [ ]. This is due to a bug in Nintex Workflow for Office 365. If you have concerns about using square brackets (as they are also used for Array types) feel free to replace them with anything else. In a follow-up step we will fix them.
- Copy & Paste: Be careful when copying this bit of JSON from the browser window. Always paste it in Notepad (and copy back) to strip out non-standard characters and formatting.
- References: The text displayed in red are Nintex Workflow references. You can't just copy and paste them and expect it to work, after pasting the entire fragment replace each Nintex reference using the Insert Reference facility (Currently on the right-hand side of the action's edit screen, see screenshot above).
- Output file name: In this basic example, we just add '.pdf' to the end of the output path and file name. This is not particularly pretty, but in order to keep things simple we are not including the Nintex Workflow actions to strip off the old extension and add the new one. You can use whatever you like here as long as it is a valid output path and file name.
As mentioned above, we have mangled the JSON by using square brackets, we need to replace them with curly braces again. To do so, insert a Replace Substring in String action and configure it as follows:
- Search String: Enter the opening square bracket [.
- Replace String: Enter the opening curly brace {.
- String: Insert a reference to the workflow variable named JSON.
- Output: Pick the JSON workflow variable to store the results in.
Click the Save button and copy the workflow action (using the action's ... menu), and paste it as the next action (click the little square on the workflow's timeline). Configure the newly pasted workflow action and replace the opening bracket with the closing bracket ']'. Do the same for the curly brace and replace '{' with '}'. Save the action, we now have valid JSON that we can send to the Conversion Service.
Before we can talk to the Conversion Service, we need to set the API_KEY. Insert a Set Workflow Variable action and configure it to set the API_KEY workflow variable to the API Key you received by email when signing up for the Muhimbi PDF Converter REST-based API for Server Platform. e.g.:
decafbad-baad-baad-baad-decafbaaaaad
Do not try to use this particular key, it will not work. Also, do not try to be clever and put curly braces around the key.
Save the action, we are almost done!
Insert the Web Request action and configure it as follows:
- URL: https://api.muhimbi.com/api/v1/operations/convert
- Method: POST
- Content type: application/json
- Add header: Click Add header, specify API_KEY as the Header name and insert a reference to the API_KEY workflow variable for the Header value.
- Body: Select the Content option, add a reference to the JSON workflow variable in the Data field.
- Store response content in: ResponseText.
- Store http status code in: ResponseCode.
Click the Save button.
Finally, insert another Set Workflow Status action and configure it with the text Completed. When we run the workflow, we can now easily see when it has completed.
Your workflow should look something like the following:
We are DONE, at least with the initial version. Publish the workflow, give it a sensible name, set the Start Options to a value of your choice.
Once published, open the document library the workflow is associated with, make sure a file of the supported type is present, and manually start the workflow. After a few seconds, the PDF file will show up next to the file the workflow was started on.
Troubleshooting
Although both Nintex Workflow for Office 365 and the Muhimbi PDF Converter are mature services, in workflows like this there are a lot of 'moving parts'. Custom generated JSON, customer specific API keys, paths to document libraries etc. The first time you create a workflow like this, something is bound to go wrong.
Some common issues and troubleshooting tips are provided below:
- Check prerequisites: Double check the prerequisites - listed at the beginning of this article - are in place.
- Log to History List: If it is not clear what is going wrong, log critical parts such as the JSON workflow variable (after the replace operation) as well as the ResponseText workflow variable (after the web request) using the Log To History List workflow action. You can see the contents of this list by clicking on the Workflow Status column for the List Item the workflow is running on.
- Send email: The amount of text that can be logged to the History List is limited (roughly 250 characters I believe), so for larger messages use the Send an Email action action to send an email, with debug content in the body, to yourself.
- Copy & Paste: Be very careful when copying the JSON fragment from this article into your workflow. Browsers tend to insert hidden characters that are not filtered out by the Nintex Workflow editor. When copying text from a browser, paste it into Notepad first to clean it. Then copy it from Notepad and paste it into your workflow.
- Nintex References: Make sure that the Nintex Workflow references in the JSON provided in this article are replaced by actual Nintex Workflow references. You can double check if the references are active by logging the JSON workflow variable to the History List. You should see the actual paths, not {Current Item:Server Relative URL}.
- Muhimbi Support: If, after double checking all prerequisites and going over all troubleshooting steps in this section, you are stuck, please contact our friendly support desk, we are here to help.
Fine tuning
Don't get me wrong, the workflow we created earlier is great, but I wouldn't use it for mission critical processes. There is no error handling whatsoever, and there is a possible recursion problem where the workflow will be triggered for PDF files it has created itself.
A version of the workflow that is more production ready can be found in the screenshot below. Full details are beyond the scope of this post, but you can download the full workflow here. Import it into Nintex Workflow for Office 365, SET THE API KEY, publish it and you are ready to go.
Other operations
This article shows how to invoke the Convert action on Muhimbi's REST interface. In addition to PDF Conversion, we expose additional end-points for Merge, Watermark, Secure, Split, OCR and even Copy Metadata operations. Full examples are beyond the scope of this article, but you can find examples in the SharePoint section of our GitHub repository.
Many of our customers already use the functionality described in this blog post in their mission critical SharePoint Online processes. What do you think, is this something that could work for your organisation? Feel free to leave a comment below or contact our support desk if you have any technical or commercial questions.
Labels: Articles, Nintex, Nintex for Office 365, pdf, PDF Converter, SharePoint Online, Workflow