Microsoft Flow - Core concepts used by the Document Converter

Muhimbi’s facilities for Microsoft Flow cover a wide range of functionality ranging from Document Conversion, Merging, Watermarking Encryption and Optical Character recognition (OCR). We have made sure that each Flow action follows the same pattern to make life as easy as possible for our users.

The fields in each action are largely self-describing. The facilities shared between most actions are described below.

Return / Output variables

Similar to other Flow actions, the output of each of our actions can be fed into subsequent actions. This allows for such operations as ‘take the output (a PDF file) generated by the Convert Document action and pass it into the SharePoint.CreateFile action to write the PDF to SharePoint’. Or attach a processed file to an email as per the following screenshot.

These Return variables are typically:

  • Processed file content: The most important field shared by almost all our Flow Actions as it contains the result of the operation. Depending on the Flow action, this contains typically a converted PDF file, a watermarked file, the results of a merge operations etc. This field can then be fed into other Muhimbi, or third, party Flow actions to do something with that file (e.g. email it as an attachment, write it to OneDrive, place it in a SharePoint document library etc)

  • Base file name: This utility variable just contains the base file name, without extension, of the input file. A simple, but very useful variable that is typically used to construct the name of the output file. For example, let’s take an input file named ‘Monthly Report.docx’. Once converted it is typically required to specify the file name when attaching it to an email / writing it to another service. By taking the returned Base file name (in this case ‘Monthly Report’) you can add a simple suffix such as ‘.pdf’ to generate the output file name. This may appear to be a trivial operation, but at the time of writing Microsoft Flow does not support a macro language to manipulate text.

  • Result code: This is typically used when the Fail On Error option (under Advanced options) is set to False. For details see the section about Error handling below.

  • Result details: Additional details that can be used in combination with the Result code. For more information see the Error handling section below.

Error handling

An important concept in programming, including designing workflows, is how to deal with errors. You have tested your workflow, all works well and executes without problem, but what happens when something goes wrong? The document that is being converted is corrupt, your subscription has expired, Flow has internal problems, many things can go wrong and WILL go wrong eventually.

Flow’s default behaviour is to abort the workflow when an error happens in any of the workflow actions. Depending on your point of view this may be desirable, but it means that when a problem happens in your mission critical workflow you cannot take corrective action or even send out an alert.

As we don’t like surprising our users, the default behaviour of our workflow actions fit in with Flow’s standard model. When a problem happens, a signal is sent to Flow that an error occurred resulting in the workflow being aborted. However, as our software is typically used in mission critical systems, we have also implemented a second ‘optional’ model for error handling.

Each of our workflow actions contains a Fail on error option in the ‘Advanced options’ area. By default, as you can see in the screenshot below, the workflow fails when an error occurs.

However, by setting this value to False, Flow will think our workflow action has succeeded, even if an error occurred. The person designing the workflow can insert a simple Flow condition after our workflow actions to check the Result code returned by our software.

The Result code will be set to one of the following values:

  • Success: The operation succeeded without error.

  • ProcessingError: An unexpected error has occurred. E.g. the input file is corrupt or there are connectivity problems.

  • SubscriptionNotFound: Your subscription was not found.

  • SubscriptionExpired: Your subscription was found, but has expired.

  • ActivationPending: Your subscription was found, but the activation link sent by email was not clicked.

  • TrialExpired: Your trial subscription has expired.

  • OperationSizeExceeded: The maximum operation size for your subscription level has been exceeded.

  • OperationsExceeded: The maximum number of operations for your subscription level has been exceeded.

  • InputFileTypeNotSupported: The specified input file type is either not supported by the Document Converter or not supported by your subscription level.

  • OutputFileTypeNotSupported: The specified output file type is either not supported by the Document Converter or not supported by your subscription level.

  • OperationNotSupported: The specified operation is not supported by your subscription level.

  • Accepted: (Not used by Flow, API only) The operation was accepted, and is running asynchronously.

  • AccessDenied: (Not used by Flow, API only) The specified credentials are incorrect.

Logging

When it comes to troubleshooting, especially when you are dealing with our friendly support desk, it is essential that we can differentiate between the various operations that you are executing. For this reason it is recommended to always enter the ‘source file name’ field with the actual, or at least a unique, file name.

This may appear obvious for Flow actions such as Convert Document, which require this field to be filled out. However, for other actions - specifically the various watermarking related actions - this field is optional and can be found under the Advanced options section.

Watermarking

All watermarking facilities follow a similar pattern as well. Some fields are obviously unique to each action, but most share the following:

  • Position: The location where the watermark will be positioned on the page.

  • Width: The width of the watermark in pts (1/72nd of an inch). For example 144 is 2 inches wide.

  • Height: The height of the watermark.

  • X Coordinate: The x-coordinate of the watermark. Only used when Position is set to Absolute.

  • Y Coordinate: The y-coordinate of the watermark. Only used when Position is set to Absolute.

  • Layer: Position the watermark in front of the page’s content, or behind it. This is particularly important when dealing with images or PowerPoint content which always cover any content positioned in the background (So set it to Foreground for those file types)

  • Rotation: Rotate the watermark, specify a value in degrees. Negative values are accepted.

  • Opacity: A value between 0 (completely transparent) and 100 (fully visible)

  • Watermark start page: The first page in the document the watermark applies to.

  • Watermark end page: The last page in the document the watermark applies to.

  • Watermark page interval: Which pages to apply the watermark on (1 = every page, 2 = every other page etc). This allows such functionality as having different watermarks on odd and even pages.

  • Watermark page orientation: The page orientation the watermark applies to. Please note that this does not change the orientation of the page, instead it allows different watermarks to be defined for landscape and portrait pages.

If you have any further questions regarding this topic, or any topic, then please contact our friendly support desk, we are here to help.