bb-manifest.xml Reference

Written By Shane Argo

This is a reference for the bb-manifest.xml file. For more information, you can also refer to the blackboard documentation.

General Settings

name

<name value="Tag Showcase"/>

The human readable name of your Building block. This will be displayed on the Manage building blocks page, so don't make it too long.

handle

<handle value="tag-showcase"/>

The internal system identifier for your building block. The combination of "handle" and "vendor Id" must be unique in your blackboard installation.

description

<description value="Description of Building Block"/>

A Human readable description of your Building block.

version

<version value="1.0"/>

The version of your building block. You can assign whatever number you want to this.

requires

bbversion

<requires>
    <bbversion value="9.1"/>
</requires>

The version of blackboard that your building block requires. The building block will not install on versions of blackboard lower than this.

plugin-versions

<requires>
    <bbversion value="9.1.201404"/>
    <plugin-versions>
        <plugin-version min="1.3" handle="goal" vendor="bb"/>
    </plugin-versions>
</requires>

Gain access to JARs exposed by the 'WEB-INF/libext' directory of building blocks by specificying the handle, vendor and minimum version of the building block.

Vendor Section

<vendor>
    <id value="atd"/>
    <name value="All the Ducks Pty Ltd"/>
    <url value="http://www.alltheducks.com/" />
    <description value="All the Ducks, Education Technology" />
</vendor>
  • id the internal system ID of your institution. the
    combination of vendor ID and building block handle must be unique in
  your blackboard installation. **Max length, 4 chars.**
  • name the human readable name of your institution
  • url the url of your institutions web site
  • description a human readable description of your institution. This is often set to the same value as the name.

Application Definitions

<application-defs>
    <application handle="bb-tag-showcase" type="shared"
        use-ssl="false" name="Tag Showcase Application" can-allow-guest="false">
        <description lang="en_US">An example showcasing the bbNG tags</description>
        <links>
            <link>
                <type value="course_tool" />
                <handle value="landing_page" />
                <name value="bbNG Tag Showcase" />
                <url value="index.jsp" />
                <description value="Examples of how to use the bbNG tags" />
            </link>
        </links>
    </application>
</application-defs>

Application definitions are the container for any links that you wish to create in the blackboard interface.

<application handle="bb-tag-showcase"
        name="Tag Showcase Application"
        can-allow-guest="false"
        use-ssl="false"
        type="shared"
        is-course-tool="true"
        is-group-tool="true"
        is-org-tool="true"
        is-sys-tool="true">
  • handle attribute the internal handle for your application
  • name attribute a human readable name for the application
  • use-ssl attribute Whether this application needs to use SSL or not
  • can-allow-guest attribute whether users in the "guest" role can use this tool

Application Type: The application type can be specified one of two ways. Either in the "type" attribute or by setting the individual "is-xxx-tool" boolean values. If the "type" attribute is set, the boolean values will be ignored.

Link Visibility: If a link type doesn't match the application type, then it won't be displayed in Blackboard. E.g. If you add a "course_tool" link to an application that has type="system" or is-course-tool="false", then your link will not be displayed in Blackboard.

  • type attribute Can be one of shared, course, course_only, or system
  • is-course-tool attribute is this a course tool
  • is-group-tool attribute is this a group tool
  • is-org-tool attribute is this an organisation tool
  • is-sys-tool attribute is this a system tool
<link>
    <type value="course_tool" />
    <name value="bbNG Tag Showcase" />
    <url value="index.jsp" />
    <description value="Examples of how to use the bbNG tags" />
    <handle value="landing_page" />
    <entitlement-uid value="myinst.myb2.mystuff.MODIFY" />
</link>

Links will appear in the Blackboard UI. In the example above. A link with the text "bbNG Tag Showcase" will appear in the Course control panel menu, under the "Course Tools" heading.

  • type Determines where in the Blackboard UI the link will appear.
    See the Link Types reference below for details of the
  various link types
  • name The text for the link
  • url the URL of the link. Relative to the root of the web app.
  • description A human readable description of the link.
  • handle An optional value that is used in the construction of a
    nav_handle which is put in the NAVIGATION_ITEMS table.
  • entitlement-uid The entitlement to use to restrict visibility of this link. Template variables such as @X@course.course_id@X@ may be used to pass values through application links as well as in various course content items.

For more information on using links in Navigation Items, see the Navigation Items Reference.

This is a reference for the link types that appear in the application-defs section of the bb-manifest file.

  • course_tool - A Course Control Panel link. only visible to users who can see the course control panel.
  • system_tool - A link in the system admin page.
  • cs_system_tool
  • user_tool - A link in the "Tools" module on the front page of Blackboard.
  • tool - Shows up in the student Tools area of a course
  • communication - Shows up in the student Tools area of a course
  • group_tool - Displays a link in the Group tools list for groups.
  • cs_action
  • cs_tool
  • cs_modify_file
  • cs_modify_folder
  • cs_manage_portfolio
  • cs_my_portfolios
  • user_list_context_menu - A link in the context menu in the results of a user search. Use the target_user.pk_string template
  • variable to pass the user's PK to your script. (e.g. mycoolpage.jsp?user_pk=@X@target_user.pk_string@X@)
  • course_list_context_menu - A link in the context menu for a course on the course list page. This is the page that appears
  • when you search for a course from the System Admin panel.
  • user_in_course_context_menu - Same as user_list_context_menu, but applies to search results inside a course.
  • gradebook_extension - A link in the "Manage" menu on the gradebook page.
  • admin_console
  • admin_console_child
  • vtbe_mashup_sys
  • vtbe_mashup_course
  • vtbe_mashup_priv_sys
  • vtbe_mashup_priv_course
  • nav_handle_param -Indicates this link should appear in the navigation structure at the location specified in the navhandle element. See the Navigation Items Reference for examples.

Module Definitions

Modules are used in the Blackboard Community System, and are the equivalent of Portlets. The module-defs element can contain three other elements, <module-type>;, <module>;, and <rss-channel>;

<module-defs>
    <module-type ext-ref="smpl-module" title="Sample Plug-in Module Type" uicreatable="true">
        <jsp-dir>module</jsp-dir>
        <jsp>
            <view>view.jsp</view>
            <admin>admin.jsp</admin>
        </jsp>
    </module-type>
</module-defs>

content-handler/Content Types

<content-handlers>
    <content-handler>
        <name value="content-handler.handle"/>
        <handle value="resource/x-smpl-type1"/>
        <http-actions>
            <create value="ch1/create.jsp"/>
            <modify value="ch1/modify.jsp"/>
            <remove value="ch1/remove.jsp"/>
        <!-- <view value="do/archive"/>
         <cpview value="do/folderView"/>
         <create value="do/editArchive"/>
         <modify value="do/editArchive"/>
         <remove value="do/deleteArchive"/>
         <can-copy value="false"/> -->
        </http-actions>
        <icons>
            <toolbar value="/images/add_ch1.gif"/>
            <listitem value="/images/icon.gif"/>
        </icons>
        <types>
            <type>
                <action-type value="newPage">
            </type>
        </types>
    </content-handler>
</content-handlers>

Content Handler type

The types defined for a content handler determine which menus the new Content type will appear in. The locations are as follows.

  • none - No menu item
  • build - Tools menu
  • plan - Tools menu
  • evaluate - Assessments menu
  • collaborate - Tools menu
  • mashup - Build Content - mashups menu
  • more - Tools menu. You'd expect this to go in the Tools > more tools menu, but it doesn't.
  • createItem - first block of items in the Build Content menu
  • createMedia - second block of items in the Build Content menu
  • createOther - third block of items in the Build Content menu
  • newPage - Build Content - New Page
  • textbook - Partner Content menu
  • image - No menu item.
  • video - No menu item.
  • audio - No menu item.
  • file - No menu item.

Reports

<reports>
    <report-package file-name="reports.zip" />
</reports>

The file referenced in "report-package" is relative to /WEB-INF/reports/. For example, the path of the file in the example above would be: /WEB-INF/reports/reports.zip. The report-package contains one or more BIRT reports. For more information, look at the sample BIRT report building block, or refer to the BIRT website.

schema-dirs/Database Extensions

<schema-dirs>
  <schema-dir dir-name="test"/>
  <schema-dir dir-name="statstest" database="stats"/>
</schema-dirs>

The schema-dirs element allows your building block to create new database objects, including tables, triggers, sequences, etc.

Extensions

For third party Building Block developers, the primary use of Extensions is to define RenderingHooks. Internally Blackboard has other uses for Extensions, but these are undocumented and unsupported.

<extension-defs>
    <definition namespace="blackboard.platform">
        <extension id="my-extension"
              point="blackboard.platform.renderingHook"
              class="au.edu.swinburne.bb.studentview.hooks.TeacherViewRenderingHook"
              singleton="true" />
    </definition>
    <extension id="MyAnnouncementHandler"
            point="blackboard.platform.announcementEventHandler"
            class="nl.rug.blackboard.AnnouncementHandler"
            singleton="true" />
    </definition>
</extension-defs>

For SP14 or greater, you must include the following permission in bb-manifest.

<permission type="java.lang.RuntimePermission" name="injectRenderingHook" />

When using Extensions, you must also add the following element to you bb-manifest.xml file <webapp-type value="javaext">, as in the following example.

<handle value="studentview"/>
<description value="View your course as a student"/>
<webapp-type value="javaext" /> <!-- <<< HERE -->
<version value="0.1"/>
<requires>
    <bbversion value="9.0.0"/>
</requires>

The class referred to in the class attribute of the extension element must implement the appropriate extension interface. in the example above, these are

  • blackboard.servlet.renderinghook.RenderingHook
  • and, blackboard.persist.announcement.impl.AnnouncementEventHandler

entitlements

You can create custom entitlements for your building blocks by using statements like below.

  • template is the existing entitlement which your new entitlement will be based on. Anyone with the existing entitlement will also receive the new entitlement.

  • label is either a plain text string, or a language pack key. In the example below, it's a language pack key.

  • uid is a unique identifier for your entitlement. The last element in the UID should be one of CREATE, EXECUTE, MODIFY, DELETE, MOVE, REMOVE, VIEW, COPY

<entitlements>
    <entitlement uid="myinst.myentitlement.course.MODIFY"
        label="myinst.myentitlement.course.label"
        type="Course"
        template="course.control_panel.VIEW" />
    <entitlement uid="myinst.myentitlement.admin.MODIFY"
        label="myinst.myentitlement.admin.label"
        type="System"
        template="system.administration.VIEW" />
</entitlements>

For more information on using entitlements, see the Entitlements Reference.

permissions

This section of the manifest file lists the Java Security Manager permissions that your Building Block needs in order to run properly. If you don't have a required permission, Tomcat will throw an exception when you try to use that particular class and method. These permissions are displayed to an administrator when they install your Building Block so that they have some idea of what it might do to their system.

<permissions>
    <permission type="attribute" name="user.personalinfo" actions="get" />
    <permission type="attribute" name="user.authinfo" actions="get" />
    <permission type="attribute" name="user.cardnumber" actions="get" />
    <permission type="attribute" name="Group" actions="get" />
    <permission type="attribute" name="GroupMembership" actions="get" />
    <permission type="persist" name="Content" actions="create,modify,delete" />
    <permission type="persist" name="ContentHandler" actions="create,modify,delete" />
</permissions>
Shane Argo
Previous

Blackboard Building Block Entitlements Reference
Next

Using curl to access the Blackboard REST API