5️⃣Reference Guide
This section is intended to be used as a general reference and specification reference. If you are new to SmartBackup, you will need to review the full documentation.
Editions
Since its first release, SmartBackup has been positioned as one of the leading backup solutions for Smartsheet. There are different editions of the product, depending on your needs, with differing capabilities as outlined further in this Reference Guide.
SmartBackup is offered in two Editions, to accommodate the unique feature and price requirements of teams and organizations.
Free 30-Day Trial of the full Enteprise Edition is available for organizations to experience the solution in their own live environments to determine if it meets your needs.
Business Edition delivers fully featured backup capabilities for small teams.
Enterprise Edition is ideal for company-wide deployments, with centralized control, larger scale requirements, and enterprise flexibility.
Business Edition
You can purchase this directly from the AcuWorkflow web site. This version is packed with features and should cater for most of the situations you encounter as a small team of up to 5 Users.
Enterprise Edition
Please contact AcuWorkflow by submitting this SmartBackup Enterprise Query form for more info.
SmartBackup Platform
The SmartBackup Platform primarily consists of the following components, which can be run independently or in concert with each other.
Backup Function
Makes exact copies, preserving formats, links, rules, and attachments, a feature not available from standard Smartsheet backups.
Archive Function (to be integrated into the Backup function in a future release)
The only purpose of Archive is to remove old backup copies from the vault, to manage the number of backup copies. Archive can be thought of as a “helper” function that will be integrated into the Backup function in future releases. In the latest release it now includes multi-processing and sophisticated error handling to improve both performance and reliability. It no longer saves older copies from the vault outside of Smartsheet.
If you are running the Backup function on a regular basis, then you MUST also run Archive regularly, to ensure that older backup copies are removed from the vaults.
Export Function (replaced by the new ShadowCopy function)
Export is designed for creating snapshot versions of sheets, or to create external copies of the data for disaster recovery, or business continuity purposes. Due to changes with the Smartsheet API Export is being replaced by the new ShadowCopy function.
ShadowCopy (New)
The new replacement for Export. It is faster and more reliable, creates snapshot copies of sheets that meet the criteria and saves them to the designated drive outside of Smartsheet. It is ideal for creating snapshot copies of your Smartsheet data, or to create external copies of the data for restoring, auditing, eDiscovery, disaster recovery planning, or business continuity purposes.
Note that the ShadowCopy saved files use the same path as defined in the Export settings. This can be a local drive, or it can be a UNC mapped drive.
RefreshMembers (New)
The purpose of the new RefreshMembers function is to refresh the contents of the Member list in SmartBackup. Because it is now a free-standing application, it can be invoked manually or automatically and independently from the SmartBackup Console. This means that it can be run from a command line, or via RunBook batch files, or via Windows Task Scheduler.
When Refreshmembers runs, it will fetch the latest list of Smartsheet users, and it will also check to see if a backup vault exists for each user. If a vault does not exist, it will try to create a vault for that user.
Note that depending on the customer’s IT environment, the results may be inconclusive, if for example, a new user is defined in Smartsheet, but the user has not yet logged in to Smartsheet. For this reason it is best to test the Refreshmembers function in your environment before adding it to your production schedule.
To run the Refreshmembers function, simply call the function by name, with no additional parameters. For example: refreshmembers.exe
DRP Reporting (New)
This new function has been added to the SmartBackup suite to assist SmartBackup administrators with overall DRP and BCP planning. It is designed to save key organizational information in a snapshot format and certain intervals.
This information includes data like a list of Users, list of Groups, etc. at a specific point in time.
When combined with SmartBackup Backup copies and ShadowCopy copies saved outside of Smartsheet, this DRP Report data will prove to be an invaluable resource for restoring data and services, and for auditing purposes.
The output from the DRP Reporting function will be stored in a subfolder of the path defined in the Export settings. For example: <exportpath> \DRPReporting\YYYY_MM_DD\HH_MM.
In future releases these DRP Reports will contain more fields including a list of Workspaces, etc.
To run the DRP Reporting function, simply call the function by name, with no additional parameters. For example: drpreporting.exe
Housekeeping Services (New)
The new Housekeeping services function allows some tasks to be scheduled internally, and is aimed at simplifying the management of SmartBackup operations. While the initial pre-defined scheduling choices are fairly limited, customers can still schedule all functions to run using RunBooks and Windows Task Scheduler.
Housekeeping Services offers basic scheduling of some housekeeping tasks such as Member Refresh, ShadowCopy and DRP Reporting. It uses common-sense intervals and scheduling instructions for simpler operations.
Scheduling is persistent, so if SmartBackup is running, it will remember the scheduled tasks across re-boots. A message will be displayed in the server windows if scheduled tasks were missed due to the SmartBackup Console not being active.
The three buttons on the right shows a) see the next run time, b) schedule a new task or c) delete a task.
The Default settings are defined in the config.yml file as part of setup installation and all schedules will be disabled by default.
The three switches on the left can be used to pause/resume a future scheduled task.
There is an additional “Hourly housekeeping task” that runs automatically to help prevent session timeouts the SmartBackup Console. This hourly task invokes a simple batch file that can optionally be edited to include other relevant housekeeping tasks in then future.
Note: To list all the running services at any time when the SmartBackup Console is running, is to open a new browser window and go to http://localhost:5000/api/v1/services. This will show a list of currently scheduled tasks.
Summary
Table with latest stable release features are shown. Terms and conditions apply. Use Limits and Restrictions:
# of Lic Users
2-5
Varies
Instances
Single
Single or Multiple
Access to Smartsheet data
sysAdmin Token
sysAdmin Token
User Provisioning
Manual & Automatic
Automatic
Backup Vault Provisioning
Automatic
Automatic
User defined queues for all Functions
Yes
Yes
Backup
Type of
Incremental (recommended)
Incremental (Recommended)
Included
Sheets, Dashboards, Reports
Sheets, Dashboards, Reports
# of Sheets
250 each
Unlimited
# of Attachments per sheet
10 per sheet
Unlimited, Admin can set soft limits
# of Dashboards per User
100 (most recent)
Unlimited
Archive
Note: Archive is a “helper” function only. Designed to clean-up the vaults.
n/a
n/a
Export
Note: Export is being sunset. Use ShadowCopy instead.
Type of
Incremental, Specific
Incremental, Specific
Included
Sheets, Reports
Sheets, Reports
ShadowCopy
Type of
Incremental
Incremental
Included
Sheets, Attachments + matedata
Sheets, Attachments + metadata
Backup
What can be backed up to the Vault?
Sheets
Dashboards
Folders (Reports)
Due to Smartsheet API limitations, backup of all Smartsheet objects in a consistent way is not possible.
Sheets and Dashboards are handled in the same way and can be backed up incrementally. Reports are not 'copy-able' nor do they contain a last-changed date and therefore can only be backed up via a folder arrangement. In this way Reports or anything else included in designated folders can be earmarked for backup. This is done using the Smartbackup "Specific" option.
Which sheets are backed up to the Vault?
SmartBackup will automatically determine which Sheets or Dashboards to backup in INCREMENTAL mode. INCREMENTAL is based on the last modification date for every sheet or dashboard each user owns. By default a backup run will include all sheets and dashboards modified in the last 5 days. This Incremental period can be adjusted based on your needs. Refer to the Administrator Guide for details.
In SPECIFIC mode you need to tell SmartBackup which sheets, dashboards or folders to include in the Backup run.
How many sheets will be backed up during a backup run?
The scope of sheets changed within the 5 day period (or other period chosen) will determine the actual number of sheets backed-up.
Scope
All Owned Sheets will be considered for each User
All Owned Sheets will be considered for each User in the Account
Backup
Will backup all sheets meeting the set criteria for each User (Up to a soft limit of 250 Sheets per User)
Will backup all sheets meeting the set criteria for each User in the Account
To exclude certain sheets from being backed-up each User can rename those Sheets starting with zz2. For example, if you have a sheet called “Campaign Plan”, then simply rename that sheet to “zz2.Campaign Plan”, and then it will no longer be included in future backups.
What is included for every backed up sheet?
All sheets backed up will be an exact copy of the original including the following:
Data
✔️
✔️
Formulas
✔️
✔️
Formatting
✔️
✔️
Attachments**
✔️
✔️
Cell-Links**
✔️
✔️
Discussion / Comments
✔️
✔️
Shared Filters
✔️
✔️
Forms
✔️
✔️
Automation Rules**
✔️
✔️
Shares**
✔️
✔️
** The SmartBackup Administrator can turn these options ON or OFF by editing the config.yml file. NOTE: Cell history is not backed-up.
NOTE: If Smartsheet Legacy Resource Management is enabled in a source Sheet, resource allocations in all backup copies of that Sheet will be included in the Legacy Resource Management reports. This will result in invalid resource utilization data. Instead, if you need a robust resource management solution then consider using Resource Management by Smartsheet.
What format is the backup sheet?
The backup sheet is the same format as the original Sheet, and it is saved in the User's Smartsheet environment.
For every Backup run, a folder named zz2.YYYY_MM_DD_HHMM_userid will be created within the designated Backup Vault (Smartsheet Workspace) and all the sheets and dashboards meeting the backup criteria for a particular User will be saved within that User's "Vault" workspace.
Sheets and Dashboards in the Vault will be prefixed with an id of zz2. followed by the original name. The reason for renaming this way is so that they can be recognized as backup copies and to help with identifying the backup copies when searching for Sheets and Dashboards. This also allows SmartBackup to identify the backup copies so that it does not create backups of the backup copies.
Optional Parameters
The following optional parameters can be supplied when you invoke Backup.
These optional parameters may be combined together.
For example: backup.exe -d=3 -i=incremental -q=FinDept will find all sheets and dashboards that have changed in the last 3 days and where the User is assigned to a Queue called "FinDept" and will create backup copies of those assets and save them to the User's vault workspace.
-d or --days
Backup all Sheets and Dashboards that have changed within the last days period.
backup.exe -d=60
-i or --include
Followed by any of these keywords: all outline specific incremental.
The default if no optional parameter supplied is -i=specific
backup.exe -i=incremental
all
Backup everything in each User's Smartsheet account. NOTE: Use this with caution, as it can result in a very large data transfer, with associated timeout errors, and it will result in creating a complete copy of your entire Smartsheet deployment. Contact AcuWorkflow if you have a need to perform this type of extensive backup operation.
backup.exe -i=all
specific
backup specific named sheets, reports or folders. Specify the items via Settings.
backup.exe -i=specific
incremental
backup sheets and dashboards based on last changed date. Must be used in combination with the -d parameter.
backup.exe -i=incremental -d=5
-q or --queue
queue name. When supplied only members with same queue name can be processed separately and/or in parallel.
backup.exe -q=FinDept
-l or --log
Optionally set logging level = debug, info, warning.
backup.exe -l=warning
Archive
Which sheets are removed from the Vault?
SmartBackup will automatically determine which sheets to remove. It is based on the last backup date for every sheet in the Vault. By default, an archive run will remove all sheets that were backed-up more than 5 days ago. This period can be adjusted based on your needs.
How many sheets will be archived during a archive run?
The scope of sheets changed within the 5 day period (or period chosen) will determine the actual number of sheets archived.
Scope
All Vaulted (backed up) Sheets will be considered for each User
All Vaulted (backed up) Sheets will be considered for Account
Archive
Will archive all sheets meeting set criteria for each User
Will archive all sheets meeting set criteria for Account
What is included for every archive sheet?
Note that from R10 onwards, the Archive function will not longer save copies of the old backup files outside of Smartsheet. The only purpose of the Archive function is to manage the number of backup copies in each vault.
Optional Parameters
The following optional parameters can be supplied when you invoke Archive
-a or --archive
Archive all Sheets successfully backed up to the Vault so many days or more ago.
archive.exe -a=60
-q or --queue
queue name. When supplied only members with same queue name can be processed separately and/or in parallel.
archive.exe -q=FinDept
These optional parameters may be combined together.
For example: archive.exe -a=60 -q=FinDept will find all folders and sheets in the Vault workspace that are older than 60 days and where the User is assigned to a Queue called "FinDept" and will create external Excel-format archive copies of those sheets and save them to the Archive location on the server as defined in the SmartBackup Console.
Export
Which Sheets are Exported from Smartsheet?
SmartBackup will automatically determine which sheets to export or you can manually specify which sheets to include in each Export run. The options are:
specific
This option requires you to specify the id of the Sheet or Report to export. Using this method you may export individual Sheets or Reports.
all (not recommended)
This option will automatically Export all Sheets except Backup Vault contents. In the latter case the folder structures will be exported.
incremental (this is the recommended option)
This option will export only sheets that were modified within the last x days. The number of days must be indicated with the -d=x option.
outline
This option will only export the Workspace and folder structures for each User.
How many sheets will be exported during an Export run?
The scope of sheets changed within the 5 day period (or period chosen) will determine the actual number of sheets exported, when using the incremental option.
Scope
All Sheets will be considered for the User
All Sheets will be considered for each User
All Sheets will be considered for each User in the Account
Export
Restricted to 3 Sheets with 3 attachments each
Unlimited Sheets, no more than 10 attachments each
Unlimited Sheets, unlimited attachments, but Administrator can set soft limits
What is included for every Export sheet?
All sheets exported are different to the original format in Smartsheet. This is mainly due to the fact that each sheet is re-instantiated outside the Smartsheet environment as an Excel file. Therefore some Smartsheet features cannot be exported, in part due to Excel incompatibilities and what is available in the Smartsheet API.
Note that these exported copies are more comprehensive than the archive copies, and because of the unique "packing note" files that accompany each exported copy, offer the richest possible externally saved backup copies available on the market today.
Data
✔️
✔️
Formulas
🔲
🔲
Formatting
🔲
🔲
Attachments
✔️
✔️
Cell-Links
🔲
🔲
Discussion / Comments
✔️
✔️
Shared Filters
Forms
🔲
🔲
Automation Rules
🔲
🔲
Shares
What format is the Export sheet?
The export sheet is an Excel XLSX file contained within a zipped file structure. It will contain multiple folders depending on what is present. For example images and pdf attachments.
XLSX file (containing all sheet data)
Packing Notes, json based files
Sheet_Packingnote (always)
Rule_Packingnote (if rules was present in sheet)
Attachments_Packingnote (if attachments were present in the sheet)
Attachments sub folder
Attachments (if attachments were present in the sheet)
A Summary file SUMMARY.xlsx will also be created in the root folder of every user run, containing a list of exported files for the run.
Where are Exports located?
All exports will reside under the path name specified in Export Settings Path. or every Export run a hierarchical folder structure starting with Username then YYYY_MM_DD then RecoveryPointHH_MM will be created.
In the event that a duplicate sheet name is detected in the same export folder, it will be renamed as originalname_HHMM_SS_TTTTTT.zip
If a duplicate Workspace name or any duplicate Folder names within same child-folder are detected, a warning will be displayed and export operations will stop for the User being processed. The reason is that file systems do not allow duplicate folder tree arrangements since it acts as a path.
Optional Parameters
The following optional parameters can be supplied when you invoke Export.
-d or --days
Export all Sheets changed within the last days period.
export.exe -d=60
-i or --include
Followed by any of these keywords: all outline specific incremental
The default if no optional parameter supplied is -i=specific
export.exe -i=incremental
all
export everything in the User space and maintain the tree folder hierarchy. Ideal for a DRP recovery point. NOTE: Use this with caution, as it can result in a very large data transfer, with associated timeout errors. Contact AcuWorkflow if you have a need to perform this type of extensive export operation.
export.exe -i=all
outline
export only the Tree folder hierarchy.
export.exe -i=outline
specific
export specific named sheets or reports.
export.exe -i=specific
incremental
export sheets based on last changed date. Must be used in combination with the -d parameter.
export.exe -i=incremental -d=5
-q or --queue
queue name. When supplied only members with same queue name can be processed separately and/or in parallel.
export.exe -q=FinDept
-l or --log
Turn logging on with level = debug, info, warning
export.exe -l=warning
These optional parameters may be combined together.
For example: export.exe -d=3 -i=incremental -q=FinDept will find all sheets that have changed in the last 3 days and where the User is assigned to a Queue called "FinDept" and will create Export copies of those assets and save them to the Export location on the server as defined in the SmartBackup Console.
ShadowCopy
ShadowCopy refers to the copying of a Smartsheet asset(sheet, dashboard, report or attachment) from Smartsheet to a designated local drive. It is ideal for creating regular copies of your data for history, DRP and governance purposes.
The major differences between Backup and ShadowCopy are that Backup duplicates the Sheet within Smartsheet whereas ShadowCopy makes a copy of the Sheet and saves it to external files store outside of Smartsheet. Therefore, the first is an exact copy preserving all information, whereas the latter may lose some Smartsheet-specific details.
Export Incremental
Only operates in Incremental mode.
Sheet and Attachment Names
Names are not used, instead files are named using the corresponding Smartsheet ID numbers. This avoids any issues with duplicate file names and non-western character sets. An index manifest is also exported, to assist with locating sheets.
File types
Sheets, attachments, and packing notes are saved as file mime-type. An attachment manifest provides attachment to sheet mapping.
Logging
Not yet implemented.
File Save Location
Uses the same location as defined in the Export settings.
ShadowCopy Runtime Considerations:
Very High-Risk, very volatile environment
Intra Day
Every 4 hrs Every 6 hrs Every 8 hrs
n/a
High-risk, volatile environment
Daily
Every 24 hrs
n/a
Moderate risk, stable environment
Weekly (Recommended)
Every 5-7 days
-d=5
Low risk, very stable environment
Monthly
Every 20-30 days
-d=14
ShadowCopy Runtime Parameters
-s or --sheets
Process Sheets. It must be specified in order to “shadowcopy” sheets.
shadowcopy.exe -s
-a or --attachments
Process Attachments. It must be specified in order to “shadowcopy” attachments.
shadowcopy.exe -d=5 -s
-n or --name
Give the Job a name.
shadowcopy.exe -n=Thor
-q=x or –queue=x
Queue name. When supplied only members with the same queue name can be processed separately and/or in parallel.
shadowcopy.exe -q=xtremegroup
What is included in every ShadowCopy exported Sheet?
All sheets exported via ShadowCopy are different to the original format in Smartsheet. This is mainly due to the fact that each sheet is re-instantiated outside the Smartsheet environment as an Excel file. Therefore some Smartsheet features cannot be exported, in part due to Excel incompatibilities and the functionality available in the Smartsheet API.
Note that these ShadowCopy exported copies are more comprehensive than the regular Smartsheet export copies, and because of the unique "metadata" files that accompany each exported copy, this offers the richest possible externally saved backup copies available on the market today.
Data
✔
✔
Formulas
🔲
🔲
Formatting
🔲
🔲
Attachments
✔
✔
Cell links
🔲
🔲
Comments
✔
✔
Shared Filters
Forms
🔲
🔲
Automation rules
Shares
What format is the ShadowCopy exported Sheet?
Note that the files that are saved by ShadowCopy are slightly different to the files that are saved by the SmartBackup Export function, to improve overall thorughput and to make it easier to locate files when needed.
In the case of ShadowCopy, all exported Sheets and Attachments, together with their associated metadata files are saved together in a single "flat" folder. These are accompanied by several "manifest" files. These manifest files provide additional information such as the Sheet names, Attachment names, associated Workspace names, etc. to enable asset mapping.
Let's take a look at each of these files:
Sheet Manifest files:
At the top of each ShadowCopy output folder you will find the manifest files, which have a naming convention beginning with "!~!". In the example above there is are two manifest files named !~!listsheets, because the ShadowCopy run was configured to save only Sheets. One file is saved in CVS format and the other is in saved .json format. Both files contain teh same informaiton. These contain lists of the Sheets that were exported, together with important metadata such as the source Sheet name, Sheet ID, Accesslevel, Permalink, Created date, and Modified date.
If the ShadowCopy run was configured to also export Attachments, then the folder would contain an additional manifest file called !~!ATTMIndex. That metadata file will contain attachment related data such as Attachment Name, Attachment ID, Sheet ID, Type, Partent Type, Username, etc. This informaiton can be used to figure out the Attachment-to-Sheet mapping and how the attachment was attached to the Sheet.
Note that the naming convention for attachments is "[Sheet ID] - [Attachment ID]", which allows sorting of the folder to group all attachments together with the associated sheet.
This metadata can be used to locate Sheets and Attachments, and then to help with restoring Sheets, Attachments, and Sheet data when needed. Note that SmartBackup is the only backup solution on the market today that saves this type of metdata.
Sheet files:
Next, in the examples above you will notice that there are two files for each Sheet that was exported. One file is in CSV format and contains the Sheet data in a similar format to what can be exported directly from Smartsheet, and the second file contains all the available metadata for that Sheet.
Note as well, that instead of using the Sheet name as the filename in the folder, ShadowCopy uses the unique Sheet ID of the source sheet. The reasons for doing this are to avoid duplicate file name issues when saving files to disk, and to make it easier to find a Sheet by using it's original Sheet ID rather than the name, because Smartsheet allows duplicate sheet names. Another reason for using the Sheet ID is to avoid trying to save files with names that use "non-western" character sets - which also cause issues when trying to save to disk.
Attachment files
As with the sheets and to circumvent the same issues, Attachments are saved using the unique Sheet ID combined with the unique Attachment ID, and the attachment files are saved in their native format, such as PowerPoint, Word, JPG, PDF, etc.
Where are the ShadowCopy exported files located?
All ShadowCopy exports will reside under the same path name specified in Export Settings Path and every ShadowCopy run will create a hierarchical folder structure starting with Username then YYYY _MM_DD then a timestamp value of HH_MM.
Last updated