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.

  1. 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.

  2. Business Edition delivers fully featured backup capabilities for small teams.

  3. 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.

SmartBackup Housekeeping Services

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:

Capability
Business
Enterprise

# 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

exact copy

exact copy

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

zip file + metadata

zip file + metadata

ShadowCopy

Type of

Incremental

Incremental

Included

Sheets, Attachments + matedata

Sheets, Attachments + metadata

Backup

Tip

Backup refers to the copying of a Smartsheet object from your Home/Workspace/Folder to a designated Workspace within Smartsheet called the Backup Vault so that it may be used to restore the original in the event of data loss or data corruption.

What can be backed up to the Vault?

  1. Sheets

  2. Dashboards

  3. 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.

Consideration
Business
Enterprise

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:

Feature
Business
Enterprise

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.

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.

The SmartBackup Administrator can optionally decide to add the SheetID to the backup copy name, therefore it becomes zz2.1234567890123456.name by turning on addsheetid. NOTE: The name will be truncated to fit into the Smartsheet max size of 50 characters.

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.

Parameter
Meaning
Example

-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

For Logging, a rotational Log file called Backup_logx.log will be created in the ..\data directory with timestamped entries. If you encounter an error, you can review this log file for error details.

Archive

Note

Archive is a “helper” function only. Designed to clean-up the vaults.

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.

Consideration
Business
Enterprise

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

Parameter
Meaning
Example

-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

Note

Due to changes with the Smartsheet API Export is being replaced by the new ShadowCopy function.

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:

Option
Description

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.

Consideration
Starter
Business
Enterprise

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.

Feature
Business
Enterprise

Data

✔️

✔️

Formulas

🔲

🔲

Formatting

🔲

🔲

Attachments

✔️

✔️

Cell-Links

🔲

🔲

Discussion / Comments

✔️

✔️

Shared Filters

Forms

🔲

🔲

Automation Rules

🔲

🔲

Shares

🔲 Supplied in Packing Notes files, which are .txt files included in each ZIP export. These require some detailed review when you want to use the data for restore operations. This feature is unique to SmartBackup and should be considered as a very high value feature - not available in any other solution. For example, this Packing Note data can be used to restore Formulas, Drop Down lists, Formatting, Rules, and Attachments for a User or for the organization.

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.

  1. XLSX file (containing all sheet data)

  2. 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)

  3. 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

Optional Parameters

The following optional parameters can be supplied when you invoke Export.

Parameter
Meaning
Example

-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.

Feature
ShadowCopy

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:

Business Requirement
Frequency
Interval
Runtime Parameter

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

Option
Description
Example

-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.

Feature
Business
Enterprise

Data

Formulas

🔲

🔲

Formatting

🔲

🔲

Attachments

Cell links

🔲

🔲

Comments

Shared Filters

Forms

🔲

🔲

Automation rules

Shares

🔲 Items marked with this box are supplied in "metadata" files which are .json files contained in compressed ZIP files. These metadata files require some detailed review when you want to use the data for restore operations. This feature is unique to SmartBackup and should be considered as a very high value feature - not available in any other solution. For example, this metadata can be used to restore Formulas, Drop Down lists, Formatting, Rules, and Attachments for a User or for the organization.

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.

Example ShadowCopy Output Folder

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.

Example folder with both Sheets and Attachments

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