Qualitem Document Fixer – Getting Started Guide

Overview

The Qualitem Office Document Fixer is a command line utility that can be used to scan and fix Microsoft Office documents in your SharePoint Online site for issues such as broken quick parts or invalid managed metadata. It is capable of scanning an entire site collection, a single web, a list or specific files by specifying a query value. Any errors found will be fixed and a new copy of the document will be saved to the library. The utility has a number of options for saving fixed documents such as creating copies in the same location with different filenames (by either adding a prefix or a suffix), saving the output in a different location or updating the file in-place (while preserving the version history).

Getting Started

  1. Extract the files from the Qualitem.QuickPartFixer.Cli.zip file to your PC.
  2. Open a command prompt at that location.
  3. Run the command Qualitem.QuickPartFixer.Cli.exe, you should see a screen as below:

 

 

  1. Type in the URL of your SharePoint site – this can be a site collection URL or the URL of a subsite / web within a site collection. For example https://mycompany.sharepoint.com or https://mycompany.sharepoint.com/sites/my-site-collection/my-subsite

 

  1. You will be redirected sign in with your Microsoft account.

 

  1. The application will perform a license check and show you details of how many conversions are remaining on your license. Note that a “conversion” is only deducted from your license when a document is fixed. If there are 20 documents in your library and only 2 require fixing then only 2 conversions will be deducted from your allocation.

 

If you run the application in report mode to perform a scan (see below for details) then no conversions will be deducted from your allocation.

 

  1. After logging in you can specify the scan mode:

 

  • S – scans your entire site collection (or a subsite), including all sub sites (recursively).
  • W – scans all document libraries in a single web (does not scan recursively).
  • L – scans all documents in a single list.

Note that if you want to scan a single file, you will need to launch the app specifying the –filter option (see below for a detailed description of all available command line switches).

  1. If you specified “L” to scan a list, you will be prompted to enter the title of the list (note: this is case sensitive).

 

  1. Next you will be asked if you want to create copies of documents or do an in-place upgrade:

 

  • Create copies – this mode will leave your original files unmodified and will save any fixed documents as copies with either different file names or in a different location (a different library or a folder within the same library).
  • In-place upgrade – this mode will overwrite the latest version of any file that requires fixing. This is irreversible. The result is that after fixing, a new version is not created – the version history is unmodified, as is the last modified date and the last modified user.

 

IMPORTANT: when fixing a document, the application must directly modify the XML within the file. There is a small element of risk that fixing a file may cause issues with the file.

 

It is recommended that you always use the “create copies” mode to do some initial test runs as this will save the fixed documents to a different location, leaving the originals unmodified. You can then review these files before deciding if you want to do an in-place upgrade. The in-place upgrade is irreversible as the latest version of the document is overwritten with the fixed file.

 

  1. If you select to make copies of the file (as is recommended) then you can select whether you want to put the files in the same library (with either a prefix or suffix added to the file name) or whether you want to put them in a different location.

 

  1. The fixer will run. After the fixer has finished you will see a CSV file in the output directory. The file name includes the date as a timestamp, for example Report_2020-01-01-133000.csv. Details of any fixed documents will be listed in the report.

 

  1. You can run the application in report mode using the -r switch afterwards to check the fixed files. You could also run the “Qualitem Office Document Scanner”. As mentioned above, it is recommended that you manually inspect / open a number of the fixed files to ensure the results are as expected.

 

Command Line Switches

The utility can be run with a number of command line switches / parameters. When using command line switches, if any required values are not specified, the user will be prompted for those values. For example, you could specify the site URL as a switch but would then be prompted for credentials. A list of command line switches is shown below. Note that short name parameters need to be prefixed with a single dash, full name parameters need to be prefixed with a double dash.

 

Short Name

Full Name

Description

s

site

Absolute URL of site collection or subsite – e.g. https://company.sharepoint.com/sites/test-site

m

mode

Scan mode: s for site, w for web, l for list or r for report.

l

list

Title of library (note: this is case sensitive).

f

filter

File name filter. Note that currently dashes are not supported as part of the file name. You can use a JSON file to input file names to work around this (see below).

u

user

Login user name.

p

password

Login password.

j

reportfile

Name of file containing JSON report data.

n

filenaming

Output file naming style – prefix (p), suffix (s) or unchanged (u).

d

destination

Server-relative URL of destination library / folder – e.g. /sites/test-site/documents/folder.

x

filenamepattern

Prefix or suffix value – e.g. a value of “__fixed” when used in suffix mode would result in files with name such as “document1__fixed.docx”.

o

overwrite

In-place update mode. WARNING this will overwrite the latest versions of existing files and is irreversible (see the warning in the red box above). To enable this you must specify a value of “true” for the parameter.

r

report

Report mode checks files but does not modify them. When running in report mode, no deductions are made to the quota associated with your license.

c

checklicense

License check mode – returns information on the quota / allocation for your license.

 

Usage Examples

 

  1. Run report mode to generate a report for a single library

 

Qualitem.QuickPartFixer.Cli.exe -s https://company.sharepoint.com -m l -l “Documents” –destination “/shared documents/fixed” -r

 

  1. Run report mode to generate a report for a single library (credentials specified):

 

Qualitem.QuickPartFixer.Cli.exe -s https://company.sharepoint.com -u user@company.onmicrosoft.com -p passwordhere -m l -l “Documents” –destination “/shared documents/fixed” -r

 

  1. Fix documents in a single library with results put in a separate folder:

 

Qualitem.QuickPartFixer.Cli.exe -s https://company.sharepoint.com -m l -l “Documents” –destination “/shared documents/fixed”

 

  1. Fix all documents in a web / subsite with results put in a document library with the sever-relative URL “/fixed documents”:

Qualitem.QuickPartFixer.Cli.exe -s https://company.sharepoint.com -m w –destination “/fixed documents”

 

  1. Fix documents in a library, suffix result file names with the term “_fixed”:

 

Qualitem.QuickPartFixer.Cli.exe -s https://company.sharepoint.com -m l -l “Documents” –filenaming s –filenamepattern “__fixed”

 

 

  1. Fix documents in place, existing latest version will be overwritten with the fixed file:

Qualitem.QuickPartFixer.Cli.exe -s https://company.sharepoint.com -m l -l “Documents” –overwrite true

 

  1. Specify a file name filter to fix a single file with the name “Expense_Report_June_2020.docx”:

 

Qualitem.QuickPartFixer.Cli.exe -s https://company.sharepoint.com -m l -l “Documents” –destination “/shared documents/fixed” -r –filter “Expense_Report_June_2020.docx”

 

  1. Perform a license check to see your remaining quota / allocation:

 

Qualitem.QuickPartFixer.Cli.exe -s https://company.sharepoint.com -u user@company.onmicrosoft.com -p passwordhere -m –checklicense

 

JSON File Format

The Qualitem Document Fixer can accept a JSON file as input to specify the list of files it should process. An example of the file format is shown below:

[

  {

    “ServerRelativeUrl”: “/shared documents/my-file.docx”,

    “Status”: 1,

  },

  {

    “ServerRelativeUrl”: “/moredocuments/another-file.docx “,

    “Status”: 1,

  }

]

 

 

The file can be processed using the reportfile switch (note that two dashes are needed before the “reportfile” switch):

Qualitem.QuickPartFixer.Cli.exe -s “https://company.sharepoint.com ” -m r –reportfile “my-report.json”

Categories