Troubleshooting Content Issues in Bb Learn

ELC staff and student workers are assisting faculty with problems such as broken images and broken links in Bb Learn. If you wish, you can try to troubleshoot these problems using our tutorial, but please feel free to contact us for assistance.

Why it happens:

If you only want a solution, click on this link to skip ahead. This paragraph just gives you some background about how we got here. These problems we've been having with permissions, broken links to files, and broken images arise with courses that were migrated to Blackboard Learn from Vista, our old learning management system. While Vista was designed around creating content externally using an HTML editor (such as DreamWeaver), where files and folders are organized in a hierarchical structure and reference each other by name and location, Blackboard's internal content editing system keeps track of files using a database that assigns each document a permanent ID as it enters the system, and then the files are hidden from view. However, when Blackboard purchased WebCT, the makers of the Vista LMS, they wanted to give the Vista people a way to bring in their content with minimal effort, so they bought a third-party tool called Xythos, bolted it on the side of Blackboard and called it the "Content Collection." Documents created inside Blackboard using its internal editor (Blank Pages, Items, etc.) don't show up in the content collection, but files brought in from outside (HTML pages, images, PDFs, Word documents, PowerPoint presentations, Excel spreadsheets, etc.) reside in the content collection. Until a file in the content collection is given an x-id (x for xythos, one presumes) or permanent URL (Blackboard uses the terms interchangeably), which only happens when an internally created document points to it and it gets indexed by Blackboard's internal tracking database, Blackboard doesn't do a very good job of keeping track of those files. It's all fine at first but, when the course gets copied to a new semester, things start to break. Here's an example. In the Fall, 2013 version of English 101, section 2345, there's a course graphic called "banner1.jpg" and it's stored in a folder called "banner_graphics" inside a folder called "images." The path to the file would look something like this:


Students and the instructor can see the banner, and all's well. Then the course gets copied to the next semester, Spring, 2014, so the new path to the graphic looks like this:


If there's an HTML file in the content collection, its link to the banner graphic is absolute or fixed, rather than relative, so even though there's a copy of the image in the current course, the HTML page is looking for the graphic at its old location, back in the 1137 (Fall '13) section of the course. The file is still there but, because the students are enrolled in the current class but not the previous one, they are not permitted to see it. The instructor, however, is enrolled in both sections, so he/she can see the image just fine, and doesn't realize there's a problem. Why doesn't logging in as the "test-student" help? Like the instructor, the test student account is also enrolled in the past sections of the course, so you can't use the test student to see the problem.

Temporary Fix:

A quick fix is to grant students in the current course permission to view content in the past section. This can be done easily and quickly, but is not a good practice for several reasons:

  1. With the problem solved for now, it's easy to ignore the problem, but it will come back later. You will need to do this fix again each time the course is copied.
  2. Sooner or later, the originating course will get deleted and all future copies will be pointing at nothing. That's a mess that won't be easily fixable.

The band-aid solution. If you prefer a permanent solution, skip ahead. Steps to give students access:

  1. Identify the original course in which the content resides. For example, maybe it's 1137-2345, and your current course is 1141-1357.
  2. In your current course, go to the Course Management Control Panel on the lower left and select the first item in the content collection, with the section number 1141-1357.
  3. At the top of the gray banner, select the action link and choose Permissions from the menu.

  4. Set the permissions

    Set Permissions from the Action Link menu.

  5. In the dark gray button bar, choose "Select Specific Users by Place" and pick "Course" from the menu.

  6. by course

  7. You will be adding the users (students) in your current course section to the list of users permitted to see content in the original course section. You can only do this if you have access rights to the content in the original section. There are several steps:
    1. Choose Courses: Check the box next to the original course in the list, and then scroll down to Step 2.
    2. Select Roles: Check the box for All Course Users
    3. Set Permissions: Check the box for Read (read, but not write).
    4. Advanced Folder Options: Check the box to Overwrite (which causes these permissions to trickle down through sub-folders.)
    5. Hit the Submit button.

Permanent Fix:

Convert HTML Pages to Blackboard's Blank Pages

Build Content: Blank Page

One by one, replace your externally created HTML pages with native Blackboard content pages and re-link the images and files. It only takes a few minutes per page. How do I know if my pages were externally created HTML pages or internally created native Blackboard pages? Just look at the icons. An HTML page has a generic text icon like the one on the left. The native Blackboard page has an icon with an image inside it like the one on the right.

generic icon blank page icon

To convert an HTML page to a native Blackboard page, do this. In an HTML document, select all and copy the content. Then, choose Build Content/Blank Page, and paste the content from the HTML page into the Blank Page. The images will show up, but they will still be bad. To repair the images, one by one, click on an image and the add image Add Image button should turn dark gray. Click on the add image Add Image button, choose Browse Content Collection and re-locate the graphic in the current course's content collection. Select it by clicking on the radio button to its left, or preview it by clicking on its name. Click Submit, and the change is saved. Do this for each graphic. As the graphics are re-linked, they will each be assigned a permanent URL or x-id. From this point forward, you will have no more problems with these graphics. You can see if a graphic has an x-id assigned by taking note of the path. Images that lack an x-id will only have a URL. This one has both an image URL and an x-id, so it will continue to work after being copied without need of permissions fixes.


Repairing linked files is a very similar process. For any linked pdf PDFs, doc Word, xls Excel or ppt PowerPoint documents, click on the link. The link button link button should turn dark gray, and then, as above, click on the button, check to see if the link has an x-id and, if not, browse the content collection to locate and re-link the file, allowing Bb Learn to assign it an x-id.

There are several benefits of taking the time to make this change:

  1. You won't have to fix it again later. This fix is permanent.
  2. You never need to mess with the permissions. Every student in your course already has the correct privileges to view content in that course.
  3. Your students will be happier, and they won't have to bug you or the help desk!
  4. Files in the content collection that are linked by an x-id can be moved or renamed without breaking the link.
  5. You can reorganize your content collection so that things are easier to find, duplicates are eliminated, and files have intelligible names.
  6. Once your course is converted to Blank Pages and Items organized in Folders, it will be easier to correct errors and update course content.
The Content Collection

The Public File Storage Area
of the Content Collection

Can I find a file's permanent URL (x-id)? Yes, but only from the Content Collection. Choose theaction link Action Link of any document. Go the 360° View. Here you will find a file's x-id as well as a human readable "web folder" location, such as in this example:

Web Folder URL:

Permanent URL:

Organizing the Content Collection: One of the benefits of converting your course pages from HTML to Blackboard-native "blank pages" is that you can now more easily and safely organize the content collection. This was dangerous when the course was built in HTML because links relied on the path and filenames not changing. Now you can create folders and move similar items into them. For example, perhaps you could create an images folder and then, within that folder (especially if you have a lot of images) create subfolders by course module. You could make a separate folder for PDFs, etc. This will make finding your content later much easier. Feel free to rename your files, because Blackboard now uses the x-id to find them, and doesn't care what they are called or where you put them.

Tricky Stuff: Usually the methods described above work well. Occasionally, you may encounter something more complicated.

  1. Occasionally, there will be an image or file that is visible in your course, but you won't be able to find it in the content collection. If so, right-click on the image or file in your course, save it to the desktop of your computer, and then re-add it to the content collection in a sensible location. Then you should be able to browse the content collection and find it.
  2. If your course uses a graphic instead of a greek letter or other special character, you should remove the graphic and replace it with the appropriate symbol where practical. Generally, you can just copy and paste a symbol from another web page that uses it, such as this one, or this one, or this one. If you can't find the symbol you want on these pages, google the term "HTML entities" and you'll probably find it.
  3. Occasionally a file has an x-id, but the permanent location is outside the current course. Just because a file is associated with an x-id doesn't mean it's always correct, though if it lacks an x-id it is definitely a problem. If you look at the human readable URL, you can sometimes see that the link points to a previous section of the course. These links should be fixed, even if there was already an x-id.
  4. There is one significant missing feature in Blackboard. That's the ability to create direct links from one page to another in a non-linear fashion. At present, we have no solution to this problem. The best you can do is organize the course well, and give students written instructions about where to go to find something in the course.