BIM Server Backup Scripting Tools
Some programming experience required!
Preliminaries (the fine print you should read)
An effective data safety strategy recognizes that Teamwork data is both distributed and central. This article addresses the central BIM Server database backup, but this is only a part of a full data safety strategy. For instance, this article will deal with how project data can be recovered from a data loss event by rolling back from a server side backup. One should be aware project data can also be recovered by re-sharing the distributed data -- the client’s local cache (see How to recover lost Teamwork projects for more information). Often the latter will set the team back less, since this cache data is usually more up to date. Also, a project is not just composed of data on the BIM Server. Distributed data in the form of external references of a project should be considered. A project is dependent on these arbitrary network locations and so it is important that both end user and IT professional work together to assure that this distributed data is also sufficiently safe.
For an overview of data safety in Teamwork see: Date safety with Teamwork projects
The command line tools for backing up data from the BIM Server were introduced in ARCHICAD 14. They can be found in the following directories:
- On Mac: /Applications/Graphisoft/BIM Server/Server Modules/[version number]/TeamworkServer
- On PC: Program FilesGraphisoftBIM ServerServer Modules[version number]TeamworkServer
Where the version number is 1500 for version 15, or 1600 for version 16. Later versions will be numbered in a similar fashion. For simplicity of documentation, only the version number/TeamworkServer relative path will precede a command that is being discussed.
These commands must be run with elevated “administrative” permissions. On the mac “sudo” is often used within the terminal prompt. On the PC the command prompt is launched with “run as administrator” elevated permissions.
These tools can only write or read from folders that the BIM Server itself has permission to write to. This means that by default the command line BIM Server tools will not be able to write to most network locations. The account used for the BIM Server services (in case of PC) or daemons (in case of Mac) must be modified to access other network locations.
Backups are version specific. You must use the same version's tools to restore the backups. This makes it imperative that you dump version data separately, to their own version specific folders, so that it is easier to restore using the correct tool.
The Master Module is the highest version number module on the BIM Server.
Complete Master Module backup and restore
Complete Master Module backup and restore will include the projects in the highest numbered version, along with all of the libraries, users, roles and custom properties found on the BIM Server. This backup will not include projects from lower numbered versions.
Backup the master module:
- [highest version number]/TeamworkServer/TeamworkServerBackupTool Target_folder_where_master_module_data_goes
Restore the master module:
- [highest version number]/TeamworkServer/TeamworkServerRestoreTool Source_folder_created_by_backup
There are two optional parameters that can be added to the TeamworkServerBackupTool: -include-manual-backups and -include-automatic-backups . Including one or both parameters in the command line will force the backup to also dump the data from the scheduled BIM Server backups. Since each project has 10 backups by default these parameters by default could increase the backup dump size by a factor of 10. Increasing the backup dump size will also increase the time it takes to complete a backup by a similar factor.
Non Master Module Project backup and restore
With these tools, only project data for the given module is backed up or restored. Other BIM Server data is not addressed. If you would like to restore only a specific project or specific projects from the group, then see the section below titled Backup Catalogue Files to determine which files should be moved into a special folder, which the restore shall use as a source folder.
Backup non master module projects:
- [version number]/TeamworkServer/TeamworkServerProjectStoreBackupTool Target_folder_where_the_projects_go
Restore non master module projects:
- [version number]/TeamworkServer/TeamworkServerProjectStoreRestoreTool Source_folder_created_by_backup
There are two optional parameters that can be added to the TeamworkServerProjectStoreBackupTool : -include-manual-backups and -include-automatic-backups . Including one or both parameters in the command line will force the backup to also dump the data from the scheduled BIM Server backups. Since each project has 10 backups by default these parameters by default could increase the backup dump size by a factor of 10. Increasing the backup dump size will also increase the time it takes to complete a backup by a similar factor.
Library Restore
Determine which libraries need to be restored and place them in a folder. Then run the below command. See Backup Catalogue Files to determine the user-friendly name of the library or libraries.
Restore a library or libraries
- [highest version number]/TeamworkServer/TeamworkServerAttachmentStoreRestoreTool Source_folder_of_libraries_to_be_restored
The Backup Catalogue Files
There are two catalogue files that provide a user-friendly name lookup:
- Projects.txt (project name lookup)
- Libraries.txt (library name lookup)
The name of a backup file consists of its data's identifying GUID instead of its user-friendly name. If your intent is to selectively restore a project or library, you will want to move the specific library or project backup to a separate folder, from where it can be restored.
Here is an example of how a typical backup folder looks:
The projects are identified in project.txt. Here you can look up their user-friendly name:
The library names can be found in libraries.txt
Restore Users, Roles or Custom Properties
The BIM Server Manager can be used to restore backups of users (Users.BIMusers), roles (Roles.BIMroles) and custom properties (UserProperties.BIMUserProperties). Also see, Selective restore from backup
Example backup scripts and tips on how to schedule them
Follow the links below to discussions of some template scripts I wrote. They are only provided as an example of how you might use the backup scripting tools. Feel free to copy them and modify them to your needs.
In both cases you will want to set these scripts up to run at off hours. Here are some pointers for how you can do it. Be aware that with the Mac there are a few methods for how this can be done; I only present a simple way.
Example steps to restore a single project, project categories, library, or master module
See
To restore multiple projects or libraries it is easier to move them into a separate folder and use the restore scripting tools described above.
Troubleshooting
In testing your scripts you may run into some problems. Look here for pointers.