BIM Server Backup Scripting Tools

by GRAPHISOFT and Ed Brown · updated: 02.19.2012

/!\ 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 Files\Graphisoft\BIM Server\Server 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

{i} 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

{i} 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:

  • backupFolder.jpg

The projects are identified in project.txt. Here you can look up their user-friendly name:

  • projects.PNG

The library names can be found in libraries.txt

  • libraries.PNG

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.

Front page

Subtopics

teamwork-bimserverbackupscriptpc--cmdpromptrunasadministrator

BIM Server Template Backup scripts for the PC

Some programming experience required! Outline of the backup Program control starts (bkup_main.bat). The program first makes sure that the directories where data will go and the install directory are correct. It will NOT run the backup if these are wrong…

Schedule Mac Script to Run Unattended

On the Mac the two standard methods for scheduling programs to run unattended are installed with the operating system. The first option is to edit the /etc/crontab. The second option is to run the crontab utility. In both cases you need to be…

Backup script for the Mac

Some programming experience required! Outline of backup Test that directories are correctly specified. Prepare an area on the local disk for the backup Make the master module backup Backup non-master module project data into a folder numbered for the…
teamwork-bimserverbackupcompleterestore--restore

Restore the master module from backup

Command to restore the master module TeamworkServerRestoreTool Source_folder_created_by_backup Command is found at: On Mac: /Applications/Graphisoft/BIM Server/Server Modules/[master module version]/TeamworkServer On PC: \Program Files\Graphisoft\BIM…
teamwork-bimserverbackupselectiverestore--backupdirectory

Selective Restore From Backup

The backup data Suppose we have some data we would like to restore from a backup. Here is what the backup folder looks like: Selectively restore a project From the BIM Server Manager choose Create then “Import from file…” Navigate to your backup…

ArchiCAD 13 BIM Server Backup

Deprecated. In general, AC 13 modules should be retired. If you absolutely have to run the AC 13 module, consider backing up by hand via exporting from the client. See Backup via exporting project from the BIM Server . Description A complete backup of a…

Related content

Data safety with Teamwork projects

Why worry? It is a given that your company will suffer a data loss event. There are too many points of failure for this not to happen: Human failure point Somebody mistakenly “modified” or deleted the project or part of it, Somebody purposely modified…
teamwork-bimserverbackupselectiverestore--backupdirectory

Selective Restore From Backup

The backup data Suppose we have some data we would like to restore from a backup. Here is what the backup folder looks like: Selectively restore a project From the BIM Server Manager choose Create then “Import from file…” Navigate to your backup…
teamwork-bimserverbackupcompleterestore--restore

Restore the master module from backup

Command to restore the master module TeamworkServerRestoreTool Source_folder_created_by_backup Command is found at: On Mac: /Applications/Graphisoft/BIM Server/Server Modules/[master module version]/TeamworkServer On PC: \Program Files\Graphisoft\BIM…
teamwork-bimserverbackupscriptpc--cmdpromptrunasadministrator

BIM Server Template Backup scripts for the PC

Some programming experience required! Outline of the backup Program control starts (bkup_main.bat). The program first makes sure that the directories where data will go and the install directory are correct. It will NOT run the backup if these are wrong…

Backup script for the Mac

Some programming experience required! Outline of backup Test that directories are correctly specified. Prepare an area on the local disk for the backup Make the master module backup Backup non-master module project data into a folder numbered for the…