ATLAS.ti 7 User Guide and Reference

Where Are My Primary Documents?

Document Management and Project

Backup

Even though a document has been assigned to the project, you have already

worked with it (coded, etc.), and it shows up in the list of primary documents,

it no longer can be accessed. What is going on?

When you assign/add documents to a ATLAS.ti project, the original documents do

not become a physical part of the project. The ATLAS.ti project (called Hermeneutic

Unit" or HU in version 7 and older) stores a copy of your document (ATLAS.ti 7,

ATLAS.ti 8, ATLAS.ti Mac) or a reference to the original document (ATLAS.ti 5.

ATLAS.ti 6).

Most importantly, you need to distinguish between external (=linked) documents,

and managed documents in ATLAS.ti 7 and ATLAS.ti 8. ATLAS.ti 5 and 6 used

linked documents exclusively. ATLAS.ti 8, ATLAS.ti 7, and ATLAS.ti Mac manage

your documents for you in so-called libraries, although they also let you use linked

documents if so desired (audio / video only in ATLAS.ti 8 and ATLAS.ti Mac).

Please determine which version of ATLAS.ti you have and read on in the

appropriate section below.

ATLAS.ti 8 Windows

When you use version 8, it is important for you to know that all project files are

managed by ATLAS.ti. The only exception is if you chose to link audio and video

files to your project, rather than to import them.

When you add documents to an ATLAS.ti project, ATLAS.ti copies these

documents and converts them into a format that can be read by both the Windows

and the Mac version. The converted files are stored in a library in a sub-folder of

your AppData\Roaming\ directory and are managed by ATLAS.ti. Thus, when

you save your project, there is no need to specify a location. All project files are

saved internally (exception: linked files; see below). The original files remain

untouched in their original location and can be treated in any way you prefer (i.e.

they can be renamed, moved, or even deleted without any negative effect on your

project).

WHERE ARE MY PRIMARY DOCUMENTS? - DOCUMENT MANAGEMENT AND PROJECT BACKUP 1

To transfer your project to a different computer, or for creating backup copies of

your project, you need to export your project and create a Project Bundle (FILE /

EXPORT). Project Bundle files can be shared via Dropbox, OneDrive, Google Drive, or

any other suitable way. To open a Project Bundle, select PROJECT / NEW / IMPORT

PROJECT BUNDLE.

We recommend that you include the ATLAS.ti AppData\Roaming\ folder into

your routine computer backup. The location is:

~\Users\[username]\AppData\Roaming\Scientific Software\

ATLASti.8

Never modify anything in this folder manually, as this will jeopardize the

integrity of your ATLAS.ti projects!

When You Have Lost Access to Linked Multimedia Files

If you linked your multimedia documents to your project, the linked files must

remain at the exact location where you linked them from. You should also not

rename the documents; otherwise, ATLAS.ti will not be able to locate them.

If you have lost access to a linked file, put the documents back into the folder that

you used when you linked them, or in case you modified the name, change the

name back to what it was at the time when you linked the file.

In the future, you will have the option to redirect ATLAS.ti to the location where

the files are located, or to the renamed file.

ATLAS.ti Mac

When you use ATLAS.ti for Mac, it is important for you to know that all project files

are managed by ATLAS.ti. The only exception is if you chose to link audio and video

files to your project, rather than to import them.

When you add documents to an ATLAS.ti project, ATLAS.ti copies these

documents and converts them into a format that can be read by both the Mac and

the Windows version. The converted files are stored in a library in the ATLAS.ti

folder under the Application Support directory and are managed by

ATLAS.ti. Thus, when you save your project, there is no need to specify a location.

All project files are saved internally (exception: linked files; see below). The original

files remain untouched in their original location and can be treated in any way you

prefer (i.e., they can be renamed, moved, or even deleted without any negative

effect on your project).

To transfer your project to a different computer, or for creating backup copies of

your project, you need to export your project and create a Project Bundle (Project /

Export Project). Project Bundle files can be shared via Dropbox, OneDrive, Google

Drive, or any other suitable way. To open a Project Bundle, select Project / Import

Project.

WHERE ARE MY PRIMARY DOCUMENTS? - DOCUMENT MANAGEMENT AND PROJECT BACKUP 2

We recommend that you include the ATLAS.ti folder in the Application Support

directory into your routine computer backup (e.g. via TIMEMACHINE). The location is:

~/Library/Application Support/ATLAS.ti.

Never modify anything in this folder manually, as this will jeopardize the

integrity of your ATLAS.ti projects.

When You Have Lost Access to Linked Multimedia Files

If you linked your multimedia documents to your project, the linked files need to

remain at the exact location where you linked them from. You should also not

rename the documents; otherwise, ATLAS.ti will not be able to locate them.

If you have lost access to a linked file, you can either redirect ATLAS.ti to its new

location, or you put the document back into the folder that you used when you

linked the file (or change the name back to what it used to be).

You can see the original location and name of the linked files in the Document

Manager in the column “Origin.” If you have moved a linked file to a different

location, right-click and select USE DIFFERENT FILE. Then redirect ATLAS.ti to the

new location of this file. Even if the menu entry reads “different file,” you need to

select the same audio or video file that you originally linked as otherwise all your

codings will no longer fit, or will no longer be available.

ATLAS.ti 7.5 Windows

If you lost access to one or more documents in your project, open the P-Docs

Manager to see which reference is stored for your primary documents - this

information is shown in the column “Location”.

Linked vs. Managed Documents

Linked documents are assigned to a project using the menu item Add Documents

/ Assign external documents. In this case the documents remain at their original

location. This location is shown in the P-Docs Manager in the column “Location”.

WHERE ARE MY PRIMARY DOCUMENTS? - DOCUMENT MANAGEMENT AND PROJECT BACKUP 3

Managed documents are added to a project using the menu items Add

Documents / Add Documents. In this case, the documents are copied to what is

called a “library.” The library essentially is a folder on your computer that is created

when you install ATLAS.ti.

On Windows Vista, Windows 7, 8 and 10 systems, the default locations of the

library is: C:\Users\USER NAME\AppData\Roaming\Scientific Software\ATLASti

Note that there is no need for you to access these folders directly, nor can you

add/assign files simply by dropping them into these folders. The above is mainly

for your information.

It is possible to create libraries at a location you determine. In order to do so, select

Project / Set Project Library. We advise to create them under the

appdata\roaming folder as well, but if you chose a different location, you should

know where the library is located :-). If not, you can access the library location in

the library manager: DOCUMENTS / DATA SOURCE MANAGEMENT / OPEN LIBRARY

MANAGER, then select EXTRAS / OPEN LIBRARY FOLDER.

Project Backup

Please always create a Copy Bundle file after each work session. Your project file

(Hermeneutic Unit) does NOT contain the documents. The only exception is if you

work with internal documents, e.g. when importing survey data.

To create a Copy Bundle file, select PROJECT / SAVE COPY BUNDLE.

Typical Problem Scenarios

Typically, there are four reasons why a document in ATLAS.ti 7.5 may no longer be

accessible from the library:

Issue 1: User name (Login name) has changed / You are logged in under a different

name.

Issue 2: Working on a different computer

Issue 3: Hard Disk Crash or Similar System Failure

Issue 4: Drive Letter of Library Path Has been Changed by IT Staff

Important: None of the above issues poses a serious problem if you have or can

find a Copy Bundle file of your project to fall back on. Even an older Copy Bundle

file could help (you can always exclude the HU file or rename it when unpacking

the bundle in order not to overwrite a more recent version). Therefore, make it

a habit to create regular backups of your projects as a Copy Bundle!

Issue 1: User name (Login name) has changed / You are

logged in under a different name.

cannot remember, create an accessibility report first:

WHERE ARE MY PRIMARY DOCUMENTS? - DOCUMENT MANAGEMENT AND PROJECT BACKUP 4

DOCUMENTS / DATA SOURCE MANAGEMENT / ACCESSIBILITY REPORT. Look for the

information <LocalManaged>. You will find the user name there.

After you have logged in with the expected name:

Open your ATLAS.ti project and create a Copy Bundle file: PROJECT / SAVE COPY

BUNDLE. The Copy Bundle file contains your project file (the HU) plus all necessary

documents from the library.

Store the Copy Bundle file on an external disk (e.g. USB stick / flash drive) or

temporarily in a Dropbox or other cloud storage device.

Close ATLAS.ti and log out.

For more information on how to create and unpack Copy Bundle files, take a

look at the following video tutorial.

Unpack the Copy Bundle file: Either double click on it, or open ATLAS.ti first:

PROJECT / UNPACK COPY BUNDLE. If you have stored it in the cloud, first download it

your desktop.

In the field HU Path, select a location for your HU file. If the box is red, click on the

file loader icon and select a location that exists given the current user name.

Click the UNBUNDLE button. During the unbundling process, all your primary

documents will be copied into the library and your HU file to the selected location.

Now you are up and running again and can also work under the second user name.

Remember to ALWAYS create a Copy Bundle file as backup of your entire

project!

Issue 2: Working on a different computer

If you have a Copy Bundle file of your project, just unpack this file on the new

computer and you are up and running again.

If you do not have a Copy Bundle file, you need to return to the computer that you

previously used and create a Copy Bundle file first:

WHERE ARE MY PRIMARY DOCUMENTS? - DOCUMENT MANAGEMENT AND PROJECT BACKUP 5

Open your ATLAS.ti project and create a Copy Bundle file: PROJECT / SAVE COPY

BUNDLE. The Copy Bundle file contains your project file (the HU) plus all necessary

documents from the library.

Store the Copy Bundle file on an external disk (e.g. USB stick / flash drive) or

temporarily in a Dropbox or other cloud storage device.

Close ATLAS.ti and log out.

For more information on how to create and unpack Copy Bundle files, take a

look at the following video tutorial.

Unpack the Copy Bundle file on the other computer:

Either double click on it or open ATLAS.ti first: PROJECT / UNPACK COPY BUNDLE. If you

have stored it in the cloud, first download it your desktop.

In the field HU Path, select a location for your HU file. If the box is red, click on the

file loader icon and select a location that exists given the current user name.

Click on the UNBUNDLE button. During the unbundling process, all of your primary

documents will be copied into the library and your HU file to the selected location.

Now you are up and running again and can also work under the second user name.

Remember to ALWAYS create a Copy Bundle files as back-up of your entire

project.

Issue 3: Hard Disk Crash or Similar System Failure

If you have a Copy Bundle file, proceed as described above for issues 1 and 2.

If you do

not

have a Copy Bundle file, you can restore the library using the

original documents. These are the documents you initially added to the HU. If you

have these original files available, ATLAS.ti can restore the documents for you (in

most cases).

WHERE ARE MY PRIMARY DOCUMENTS? - DOCUMENT MANAGEMENT AND PROJECT BACKUP 6

This functionality is available for non-editable formats (PDF, images, audio and

video data) and text documents that have not yet been edited within ATLAS.ti.

Move all documents into the same folder where the HU file resides.

Open your project in ATLAS.ti and then the P-Docs Manager.

Open each primary document from the Manager by double clicking on it. ATLAS.ti

will tell you that the managed document is missing but that a document was

found that can be used to restore it. Press OK to restore the document.

If your documents have been edited already, these data can be restored in most

cases, but your coded segments may be misaligned.

When you edit a document, ATLAS.ti stores the revisions. The latest revision might

be gone, but ATLAS.ti allows you to reset the document to the latest available

revision:

Right click on the document in the P-Doc Manager and select: DATA SOURCE

MANAGEMENT / RESET TO LATEST VALID REVISION.

If this procedure allows you to open the document, note that the codes may be

misaligned. You need to go through the document and manually adjust misaligned

quotations.

If both options do not work to rescue your documents, please contact the ATLAS.ti

help desk at [email protected]

Issue 4: Drive Letter of Library Path Has been Changed

by IT Staff

Sometimes drive letters are changed by IT staff. This can become an issue if your

library is stored on a server and you have not created a Copy Bundle file.

This problem can only be solved by changing some information in the ATLAS.ti

user.ini file. If you do not feel computer-literate enough to do this, please contact

the helpdesk.

To change the user.ini file:

Open the HU whose document you cannot access.

Select TOOLS / EXPLORER / USER SYSTEM FILES

Open the user.ini file in a text editor and search for the section “Managed Files”

Adjust the path references according to the changes: If only the drive letter

changed, you just have to change this one letter.

For My Library:

; A user defined directory where local managed files are stored

localManagedFolder =

WHERE ARE MY PRIMARY DOCUMENTS? - DOCUMENT MANAGEMENT AND PROJECT BACKUP 7

For all user-defined libraries:

; A user defined directory where public/shared managed files are stored

sharedManagedFolder =

Save the user.ini file. Save the HU. Close ATLAS.ti and reopen it.

After you have restored the documents in your HU, create a Copy Bundle file as

a backup!

If none of these remedies work, create a system report and an accessibility report

and send both files, along with a description of the problem, to the ATLAS.ti help

desk at [email protected]. To create these reports, select HELP / TECH

SUPPORT INFO (note: the system report is a single file with the extension ".AtlRep").

ATLAS.ti 6 Windows

If a Primary Document cannot be loaded, the ‘Usable’ column in the P-Docs

Manager displays “No” and nothing is displayed in the HU editor. Depending on the

kind of problem, the entries in the primary document manager are displayed in a

different color.

There are two possible reasons why a document cannot be displayed in ATLAS.ti 6:

(1) Document is not found: The document cannot be found where ATLAS.ti

expects it; the file was deleted, renamed, or moved. The entry for the primary

document is shown in gray.

(2) Document is not valid:

(a) The document was found, but it was edited with another application and not

with ATLAS.ti.

(b) The companion log file of an edited document was deleted, not copied, or is not

the correct version.

In both cases, the entry for the primary document is show in bright red.

Remedy for Issue 1: Document Not Found

Open the P-Docs Manager to see which reference is stored for the documents. This

information can be found in the column ORIGIN. If the documents are no longer

stored at this location, they cannot be loaded. You have three alternative options:

(1) Move the documents back to the original location as indicated in the column

ORIGIN in the P-Docs Manager using the Windows Explorer.

(2) Tell the HU about the new location of your documents. To do this select the

main menu option: DOCUMENTS / DATA SOURCE MANAGEMENT / CHANGE PATH (This

WHERE ARE MY PRIMARY DOCUMENTS? - DOCUMENT MANAGEMENT AND PROJECT BACKUP 8

option is not recommended as it is a bit cumbersome. You must change the path

for each document), or

(3) Create a different project set-up (recommended). This is the solution providing

the most flexibility in terms of future project handling, backup and transfer.

This is how it works:

Create a new folder.

Copy all documents and the HU into this folder. If documents have been edited,

remember to copy all LOG files as well.

Open ATLAS.ti and select the main menu option Documents / Data Source

Management / Optimize Paths. This will create the so called HUPATH for all

primary documents (see P-Docs Manager, column: Origin)

Remedy for Issue 2: Invalid Documents, or Problems

Related to Edited Files

A “not syncable” message indicates that there is a problem with editing. You have

either modified a file outside ATLAS.ti (e.g. in MS Word), or you have edited the

file in ATLAS.ti as you should but have misplaced, deleted, or modified the log file.

Create an accessibility report first to find out which of the two possibilities apply.

To do so, select DOCUMENTS / DATA SOURCE MANAGEMENT / ACCESSIBILITY REPORT from

the main menu.

Data Source Changes Detected

If data source changes have been detected, then you have modified the document

outside ATLAS.ti. This should never be done, but let’s assume this happened by

accident. This problem can be remedied, but you should be aware of its potential

consequences.

When you modify a document outside ATLAS.ti, your coding references stored in

the HU are not modified and therefore a mismatch between text and attached

codes can occur.

You can nonetheless force the program to load the document:

Open the P-Docs Manager and right click on the document.

Select the option Data Source Management / Reset last Access Information.

Read and OK all warning messages.

Now go through all coded segments for this document and modify misaligned

segments.

Synchronization failure: Expected Log File Not Found

In the accessibility report you find information about the name and the date when

the expected log file was created. For example, if you have edited a file with the

name interview.rtf, the name of the log file is interview.rtf.log.

WHERE ARE MY PRIMARY DOCUMENTS? - DOCUMENT MANAGEMENT AND PROJECT BACKUP 9

Search your computer for this file and copy it into the same folder as the original

source file. If you cannot find it, you may have an older Copy Bundle file from where

you can retrieve it.

If you deleted the log file and you cannot recover it from the Windows Recycle Bin

or from an ATLAS.ti Copy Bundle file, there is no solution but to disconnect the

primary document from the HU and to re-code it!

Source-Log Mismatch

This means a log file was found but it is not the correct version. In the accessibility

report you find information about the size and the time of saving of both the

currently available and the expected log file. For example:

Modified: 17.02.2013 20:41:33 (expected from log:

15.01.2012 11:17:39!!!)

Size: 232312 (expected from log: 231219!!!)

In the above example, you need to search for a file that was last save January 15

2012 at 11:17:39, and that has a file size of 231219 bytes. You get a precise indication

of file size if you right click on the file in the Windows Explorer and select the

option “properties.”

If you found the correct file, it needs to be copied into the same folder as the Word

(rtf) file.

We strongly recommend that you create a Copy Bundle file after each work

session (TOOLS / COPY BUNDLE / CREATE BUNDLE) and store different versions over

time. If you cannot rescue a needed log file, you can no longer load the

document and have to remove the document from your project, assign it anew

and code it again. If you have a Copy Bundle file, there is a good chance you will

be able to rescue the correct version of the log file and will not lose any work.

If you need additional help, create and send an accessibility report along with a

detailed description of the problem to our Support Team. To create the report, go

to DOCUMENTS / DATA SOURCE MANAGEMENT / ACCESSIBILITY REPORT. Contact our

Support Team at [email protected]. NOTE: Support for ATLAS.ti 6

ended in Dec. 2016. We cannot guarantee that we will be able to help with

rescuing projects from this discontinued program version.

WHERE ARE MY PRIMARY DOCUMENTS? - DOCUMENT MANAGEMENT AND PROJECT BACKUP 10