Access Keys:
Skip to content (Access Key - 0)

With Release 9.1, Blackboard included the ability for Building Blocks to define schema elements in the .war file that would get automatically installed and managed in the Learn database schema. However, that feature was limited to Building Blocks that were signed and distributed by Blackboard.

As of 9.1 Service Pack 1 (R9.1SP1), that "sign-gating" restriction has been lifted. Building Blocks authored by independent developers can define and install schema elements via special configuration files referenced from their manifest. In some ways, this was in recognition of the fact that Building Blocks frequently created custom schema objects directly. By enabling it as a feature allows system admins to get more visibility into the process, and ensure some level of consistency.

It should be noted that this is not on by default - Administrators must enable this functionality from the Building Blocks management section of the admin panel. The allowed schema actions are specified from the "Global Settings" screen, including:

  • Prevent any Building Block from creating custom database objects
  • Prompt each time a Building Block wants to create custom database objects
  • Allow any Building Block to create custom database objects

Also note that these options are not enforced for Blackboard-authored, signed Building Blocks - that would disrupt the operation of some key features, such as the Wiki, that are delivered via Building Blocks. The first option is the default - no schema may be installed. The second option prompts the administrator - previewing the tables/objects that would be created. The third option simply processes the objects, without prompting the admin. That option is only recommended for development, in order to facilitate rapid iteration. In practice, we expect most administrators to choose "prompt", and then only after attempting to install a Building Block and seeing the error message.

With great power comes great responsibility - there are a few things to keep in mind when designing the schema using this mechanism:

  • Database objects must be prefixed with the vendor-id in the B2 manifest (the B2 installer will complain if the prefixes do not match).
  • Minimize your dependency on Blackboard objects
  • If you do need to link to a Blackboard database object, ensure that the relationship does not interfere with standard Blackboard processing - you must specify an on-delete action (cascade or setnull)
  • The Blackboard schema is not an officially supported integration API, and will change from release to release.
  • Test test test - if you do reference a core entity, such as a course or user, make sure you can still delete that entity

Getting Started

The schema is defined primarily via a file called schema.xml, which is part of a directory structure that also defines various SQL scripts - procedures, functions, views, etc. One or more schema definition directories are referenced via the schema-dirs element in the manifest, as follows:

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

The dir-name attribute is evaluated first against the webapp root, then against WEB-INF. The schema.xml should be in that directory; all other scripts are in sub-directories. The database attribute indicates which schema the objects should be created in. By default, the objects are created in the transactional schema - so if you are creating tables to support the day-to-day features of your Building Block, you would not need to define this value. Tables and other objects can also be created in the reporting schema by using the value "stats". As of R9.1SP1, there are no other supported values.

See Schema Definitions for more information on the structure of schema.xml, the containing directory structure, and the supporting scripts.

Comments (3)

 

  1. 20 Jul 2010

    Thomas True says:

    Bob, This is wonderful news.   We've just arrived at 9.0 so I imagine ...

    Bob, This is wonderful news.   We've just arrived at 9.0 so I imagine things will be refined somewhat before I have the opportunity to work with this.  I do have a concern, though, about the security of things like grades.  A couple of directions to go in:

    1. Move some tables to another data base owner and then use grants on views or java security on the acquisition of the right JDBC connection.
    2. When a Building Block requests schema creation ability, construct a database user especially for that Building Block and add it to the connection pool.  The building block can then either use JNDI, or perhaps, Blackboard classes to get a connection.  Access to usual BB objects could be provided by grants, managed directly or indirectly by the sys admin.  Another real advantage would be the ability of a DBA to define a separate table space, etc, for the Building Block.

    I'm partial to the second option--I think it is simpler and can be applied in small steps.   I have also worked under similar constraints with our own Building Blocks, but without management and control you are supplying. 

    Tom True

  2. 09 Mar 2011

    Patricia Goldweic says:

    Very glad to see Blackboard moving in this direction. I agree with Thomas True's...

    Very glad to see Blackboard moving in this direction. I agree with Thomas True's concern, and would also like to see the second option he proposes. A separate database user that has write access to the new schema/tables but only (possibly partial) read access to the rest of the Bb database would be more secure. Building blocks should be able to use either JNDI (perhaps via the Java persistence framework) or the Blackboard database access classes to access the new -building block specific- database objects.

    -Patricia

  3. 10 Oct 2012

    Bruce Phillips says:

    The above document needs to clarify exactly what the directory structure needs t...

    The above document needs to clarify exactly what the directory structure needs to be.  This is what worked for me.

       In WEB-INF create a directory named schema.  In that schema directory create a directory that matches the value you give for the dir-name attribute of the schema-dir node (e.g. table_definitions).  In that sub-directory (e.g. table_definitions) place the schema.xml file that defines the table(s) and their columns.

       For example:

         WEB-INF

            table_definitions

                schema.xml

    The schema-dirs node in bb-manifest would be

        <schema-dirs>

            <schema-dir dir-name="table_definitions" />

       </schema-dirs>
Adaptavist Theme Builder (4.1.3) Powered by Atlassian Confluence 3.3, the Enterprise Wiki