The Muhimbi PDF Converter for SharePoint has grown over the last few years from a relatively modest SharePoint GUI application to a sophisticated framework that can be used from Nintex, SharePoint Designer, K2, Workflow Manager, SharePoint Online and Visual Studio workflows to carry out all kind of PDF processing, including conversion, merging, OCR, securing, watermarking, splitting and merging.
Regardless of the operation that is carried out, input and / or output file names, including paths, need to be specified. Although we have tried to make this as intuitive as possible, and we continue to make improvements, according to our statistics the most common support call we receive is related to how to specify these paths. We hope to clarify the situation in this post.
Please note that the details described below are the same for both SharePoint on-premise and SharePoint Online. However, SharePoint Online is limited to paths in the current Site Collection (unless you are happy to use a workaround). Due to strict security boundaries it is not possible to write files to a different site collection. Unlike its on-premise equivalent, the Online version supports fully qualified paths that include the hostname (e.g. http://somedomain/somesite/somedoclib) to make life easier when creating reusable workflows. For details see this blog post.
Targeting the same directory / using the same file name as the source file
If you wish to read from or write to the same location as the source file that is being processed, e.g. you are using a SharePoint Designer workflow to automatically convert files to PDF, then leave the path empty. This works for all situations with the exception of HTML to PDF Conversions and the Merge Method in K2 as these are is not necessarily associated with a source file (they can convert URLs as well).
If you wish to use the same name for the target file as the source file then there is no need to specify a file name, the system will generate the name for you. When converting files to PDF the files’ extension will automatically be updated to ‘PDF’, however when the source file is a PDF (e.g. when applying PDF Security) then omitting the file name and path will overwrite the source file. This may be the desired behaviour, but keep it in mind.
Targeting a (sub) folder in the current Document Library
If you wish to specify a (sub) folder in the same Document Library as the source file then you must specify the Document Library name as well as the path to the folder. Just specifying the folder name will not work. For example to convert a file to the ‘ Archives/PDFs’ folder in the Shared Documents library, specify:
Shared Documents/Archives/PDFs/
Make sure you use a trailing slash when specifying an output folder without an explicit file name. Please do not start the path with a slash in this particular case.
Targeting a different Document Library
To specify a location in a different Document Library in the current Site, specify the name of the Document Library followed by any folders. E.g. if your workflow activity is operating on a file in the Shared Documents library, but you want to write the generated file to the PDF folder in the Archive Document Library then specify the following as the path:
Archive/PDF/
Make sure you use a trailing slash when specifying an output folder without an explicit file name. Please do not start the path with a slash in this particular case.
Targeting a Sub Site
SharePoint Site Collections can contain multiple Sub Sites. To write a file to a location in a Sub Site specify the name of that Sub Site followed by the name of the Document Library followed by any folder names. For example if the current workflow is acting on a file in the root web of a Site Collection and you wish to write it to the PDFs folder in the Paid Document Library in the Invoices Sub Site specify the following path:
Invoices/Paid/PDFs/
Make sure you use a trailing slash when specifying an output folder without an explicit file name. Please do not start the path with a slash in this particular case.
To target a Sub Site ‘next’ to the current site, use an absolute path. For details see Targeting a different Site Collection below. Please note that ‘traditional’ relative path notation such as ‘../../’ is not supported.
Targeting a different Site Collection
Due to strict security restrictions, it is not possible to target a different site collection directly in SharePoint Online, A workaround can be found here.
In order to read from or write to a file in a different site collection you have to use an absolute path starting with ‘/’. For example if a PDF Conversion workflow is running in the Accounting Site collection and the generated PDF file should be written to the Archiving site collection in the PDFs folder in the Accounting Document Library, use the following path
/Archiving/Accounting/PDFs/
If all your Site Collections live under ‘/sites/’ then this will need to be reflected in the path, e.g.
/sites/Archiving/Accounting/PDFs/
Please do not start absolute paths with http://YourWebApplication/, always start absolute paths with a slash. (Except when using reusable workflows in SharePoint Online, see the ‘hints and tips’ section at the end of this post.)
Targeting historical files
As of version 6.0 it is possible to specify specific versions in a file’s history for Merge and Watermark (elements) operations. The syntax is similar to what is described above, for example:
Specify a document in the same document library:
_vti_history/1536/Automatic Merging/End Page.docx
Specify a document in a different document library:
_vti_history/1024/Shared Documents/Subfolder/End Page.docx
Specify a document in a sub-site of the current web:
SubSite/AnotherSubSite/_vti_history/1024/Shared Documents/Empty.pdf
Specify a document in a different site collection or in a sub web next to the current web:
/sites/PDFTest/_vti_history/512/Shared Documents/introduction.pdf
Targeting a different Web Application
As there are clear security boundaries between SharePoint Web Applications it is not possible to exchange files between them. If this is required then you will need to use a third party Workflow Activity, use Nintex Workflow or write a little bit of custom code..
Targeting host named site collections
Although the PDF Converter fully supports output to sub-sites, libraries and folders using the syntax described above, it is not possible to specify a location in a host named site collection from a different site collection. If this is required then you will need to use a third party Workflow Activity or write a little bit of custom code.
Using a List Item Attachment as the source
A popular use for the PDF Converter is to create a PDF for a list item including all attachments. Targeting list item attachments is easy, just right-click an attachment and copy the source URL to determine the structure of the path. It typically looks something like the following. In this example ‘10’ is the ID of the list item.
/sites/SomeSite/Lists/Tasks/Attachments/10/Test.docx
It is not possible to directly write a converted file to a list item attachment. You will need to output the file to a Document Library and then attach that file using a technology of your choice. (Nintex Workflow, Trigger etc)
Creating dynamic paths / file names
All of Muhimbi’s SharePoint Designer and Nintex Workflow activities allow lookup variables to be used in order to generate dynamic paths. For example, in order to make a workflow generic, the name of a source or target File / Library / Folder can be determined at run-time.
For Nintex Workflow use the ‘Insert Reference’ button
In SharePoint Designer use the ‘Add Lookup’ button
Some final, generic, hints and tips:
- Never start a path with http://YourWebApplication/. Start absolute paths with a ‘/’. (The only place where hostnames are allowed is in SharePoint Online reusable workflows)
- Some activities support templates in the output file name, e.g. to automatically generate file names when splitting PDFs.
- Although you can use forward (/) as well as back (\) slashes, make it a habit to use forward slashes as SharePoint Designer 2010 workflows do not always deal well with back slashes.
- No matter where you read from or write to, your user must have access to the location that is being specified.
Labels: Articles, PDF Converter, Workflow
