Using Multiple Item Bank Sources in the Items API – Learnosity Product & Developer Help

This article outlines how to initialise the Items API with Items from multiple content sources – either different Item banks and/or different Item bank pools.

Overview

The Items API by default will source Items from the requesting client's default Item bank, or, Item bank pool if specified in the request.

However, if the requesting client wishes to combine Items from multiple Item bank sources, they can do so by setting the source information at an Item level granularity.

Typically, an individual Item is represented by its Item reference string – the rest of the Item information is implied in the request, i.e. the requesting clients default Item bank, the Item bank pool supplied in the request, and a unique Item id derived from the fact that the Item reference is unique per Item bank.

When specifying an Item source however, more information is required – i.e. an Item bank reference (known as an organisation_id), and subsequently an additional unique id (since Item reference uniqueness is no longer implied).

Items request examples

Common Items API usage – default Item bank

Here the client (Organisation A) is retrieving content from the default Item bank attached to their consumer credentials.

Advanced Items API usage #1 – alternate Item bank

Here the client (Organisation A) is retrieving content from an alternate Item bank that they have been given access to, Organisation B.

Advanced Items API usage #2 – multiple Item banks

Here the client (Organisation A) is retrieving content from multiple Item banks that they have been given access to.

Advanced Items API usage #3 – multiple Item banks/pools

Here the client (Organisation A) is retrieving content from multiple Item banks as well as pools.

To achieve the advanced usage as shown above, a support request needs to be made to Learnosity to enable a single consumer to have access to multiple Item banks that they may have.

Sample Code

/*
|---------------------------------------------------------
| Common Items API usage
|---------------------------------------------------------
|
| array of item reference strings
|
*/

"items": [
    "ccore_video_260_classification",
    "ccore_parcc_tecr_grade3"
]


/*
|---------------------------------------------------------
| Advanced Items API usage #1 – alternate Item bank
|---------------------------------------------------------
|
| Specifying an alternate `organisation_id` at the root
| of the configuration object
|
*/

{
    "organisation_id": 9356,
    "activity_id": "itemsassessdemo",
    "name": "Items API demo - assess activity",
    "items": [
        "ccore_video_260_classification",
        "ccore_parcc_tecr_grade3"
    ]
}


/*
|---------------------------------------------------------
| Advanced Items API usage #2 – multiple Item banks
|---------------------------------------------------------
|
| Specify an array of item source objects in
| the `items` array
|
| Note that we can re-use the `reference` as the `id`
| if it remains unique within the request
|
*/

"items": [
    {
        // No `organisation_id` specified, so the default will be used
        "id": "ccore_video_260_classification",
        "reference": "ccore_video_260_classification"
    },
    {
        // An `organisation_id` is specified, so it will become the source
        "organisation_id": 1,
        "id": "ccore_parcc_tecr_grade3",
        "reference": "ccore_parcc_tecr_grade3"
    }
]


/*
|---------------------------------------------------------
| Advanced Items API usage #3 – multiple Item banks/pools
|---------------------------------------------------------
|
| Specify an array of item source objects in the `items`
| array that includes an `item_pool_id`
|
| Note that we can re-use the `reference` as the `id`
| if it remains unique within the request
|
*/

"items": [
    {
        // No `organisation_id` specified, so the default will be used
        "id": "ccore_video_260_classification",
        "reference": "ccore_video_260_classification"
    },
    {
        // An `organisation_id` and `item_pool_id` are specified,
        // so they will become the source
        "organisation_id": 1,
        "item_pool_id": "january_snapshot",
        "reference": "ccore_parcc_tecr_grade3",
        "id": "ccore_parcc_tecr_grade3"
    }
],

Item source object requirements (for advanced usage)

For Item level granularity of Item sources, the following information is required per Item.

Important: Once one Item is defined with explicit source attributes, all Items must be defined with an explicit source.

Attribute	Required	Description
id	Required	A request client supplied unique id for an item - must be unique across all Items. Note: in most cases, `reference`and `id` can be the same. `id` is required to avoid conflicts in Item uniqueness only.
reference	Required	Item reference
organisation_id	Optional - only required when explicitly defining an Item from a source that is different to the Activity source	The unique identifier for the Item bank Note: if an item_pool_id is supplied at the Activity level of the request, it can be nullified at the Item level by supplying an organisation_id
item_pool_id	Optional - only used when requesting from an Item bank pool	Used to request Items from an Item bank pool. Important: make sure the correct organisation_id for this pool is supplied, either at the Activity level of the request, or explicitly at the Item level of the request.

Example

An example of the configuration required can be found below.

The requested Items in the example take the following form:

(Note that Item 1 and Item 2 do not supply an organisation_id or an item_pool_id because they are already supplied at the Activity level of the request).
(Note that Item 3 and Item 5 do supply an organisation_id, because they are coming from the Item bank with organisation_id 1 but NOT an Item bank pool).

"organisation_id": 1,
"item_pool_id": "MIBKIBKP_ITEM_POOL_1",
"items": [
   {
        "reference": "MIBKIBKP_Item_1",
        "id": "item_1"
    },
   {
        "reference": "MIBKIBKP_Item_2",
        "id": "item_2"
    },
   {
        "reference": "MIBKIBKP_Item_3",
        "organisation_id": 1,
        "id": "item_3"
    },
   {
        "reference": "MIBKIBKP_Item_4",
        "organisation_id": 1,
        "id": "item_4",
        "item_pool_id": "MIBKIBKP_ITEM_POOL_2"
    },
   {
        "reference": "MIBKIBKP_Item_5",
        "organisation_id": 1,
        "id": "item_5"
    }
],
"config": {
    "navigation": {
        "show_intro": true,
        "intro_item": {
            "reference": "MIBKIBKP_INTRO",
            "organisation_id": 1,
            "item_pool_id": "MIBKIBKP_INTRO_OUTRO",
            "id": "intro"
        },
        "show_outro": true,
        "outro_item": {
            "reference": "MIBKIBKP_OUTRO",
            "organisation_id": 1,
            "item_pool_id": "MIBKIBKP_INTRO_OUTRO",
            "id": "outro"
        }
    }
}