Submit a request
Submit a request

Using Item Pools to Create Content Snapshots

This article explains how to create, get and append item bank pools via Data API.

Item bank pools, or Itempools are a snapshot of specified Item bank data that can used in the same way that conventional Item bank data is used.

The difference is that Itempool content does not update along with its corresponding Item bank content - it is a clone of that data from the time it was saved.
This is useful for keeping live, test-ready content consistent and immutable for a long period of time, while simultaneously letting content authors continue to update the original content.

The quick reference for creating itempools can be found here.

The request object must contain the attribute pools, which is an array of pool objects.

Each individual pool object requires:

  • reference (string) - this is a unique identifier of an itempool for a particular item bank - this is also known as an item_pool_id in other use cases
  • name (string) - the name of the pool, not necessarily unique
  • content (array) - this is an array describing the content to be taken from an item bank, and cloned into the itempool (this content will be outlined in further detail below)
// The Data API request endpoint for this example is itembank/pools
// The request type is POST

{
    // The minimum required attributes to create a new pool/s
    "pools": [
        {
            "reference": "example_itempool_reference",
            "name": "Learnosity Itempool Example",
            "content": [
                // ... content examples in detail below ...
            ]
        }
        // ... other pool objects ...
    ]
}

Pool objects may also contain:

  • description (string) - further information to describe the pool (default: none)
  • status (string) - published or unpublished (default: published)
  • overwrite (boolean) - whether to overwrite the pool of the given reference/item_pool_id with new content. This is useful to preserv/re-use the reference (default: false)
  • ignore_empty_additional_tags (boolean) - this relates to an advanced content case, and will be outlined in further detail below (default: false)
// The Data API request endpoint for this example is itembank/pools
// The request type is POST

{
    "pools": [
        {
            // ... required pool attributes ...
            "description": "An example pool to demonstrate the required and optional pool attributes.",
            "status": "unpublished",
            "overwrite": true,
            "ignore_empty_additional_tags": true
        }
    ]
}

Defining Itempool Content

In simple cases, itempool content can be defined explicitly by reference. This can be done with:

  • activity_references (array) - this is an array of activity references. The itempool service will find ALL content associated with the defined activities, including items, tags, questions etc.
  • item_references (array) - this is an array of item references. The itempool service will find ALL content associated with the defined items, including tags, questions etc.
// The Data API request endpoint for this example is itembank/pools
// The request type is POST

{
    // This example assumes all other necessary content has been defined
    "pools": [
        {
            // ... other pool attributes ...
            "content": {
                "item_references": ["item_001", "item_002", "item_003", "item_004", "item_005"],
                "activity_references": ["activity_001", "activity_002", "activity_003", "activity_004", "activity_005"]
            }
        }
    ]
}

In more complex cases, itempool content can be defined by tags, and tag combinations. There are three ways to use tags for content:

  • tags (array) - find all activities and items with the given tags
  • activity_tags (array) - find only activities with the given tags (will still add any relevant activity content, including items related to the activity)
  • item_tags (array) - find only items with the given tags (will add any relevant content)

Each of the tag attributes are arrays of tag objects. There are two types of tag object; conventional tags, and tag combinations.

Conventional Tags

Conventional tags should be familiar, as they are used all throughout Learnosity's APIs. They contain:

  • type (string) - the tag type; for obtaining content for an Itempool, this is required
  • name (string) - the tag name; for obtaining content for an Itempool, this is not required

When using tags to get itempool content, any combination of the given tags will be used to get the content.

Note Defining a tag object with only a tag type, and not a tag name is the same as supplying ALL tag names. 
I.e. If a tag type foo has tag names bar and baz, then both foo: bar and foo: baz will be used for content.

// The Data API request endpoint for this example is itembank/pools
// The request type is POST

{
    // This example assumes all other necessary content has been defined
    "pools": [
        {
            // ... other pool attributes ...
            "content": {
                // This example will create an itempool using ANY combination of the following tags
                // foo: * , bar: baz, qux: quux
                "tags": [
                    {
                        "type": "foo"
                    },
                    {
                        "type": "bar",
                        "name": "baz"
                    },
                    {
                        "type": "qux",
                        "name": "quux"
                    }
                ]
            }
        }
    ]
}

Tag Combinations

Tag combinations are more complex tag objects in that a single tag object can contain multiple tags. A tag combination is a very specific tag definition to get content explicitly.

A tag combination contains two arrays:

  • required_tags (array) - contains conventional tags, and content must have all defined tags to be included. When using tag combinations, required_tags is required
  • additional_tags (array) - contains conventional tags, and content must have at least one of the defined tags to be included. When using tag combinations, additional_tags is optional

Essentially a tag combination works like: (required AND required AND required) AND (additional OR additional OR additional)

Important if additional_tags returns no content, then the tag combination will return nothing, even if all required_tags are satisfied. 
The flag ignore_empty_additional_tags (above) can be used to make additional_tags completely optional - in such cases, it is easier to not set the additional_tags array, and rely solely on required_tags.

// The Data API request endpoint for this example is itembank/pools
// The request type is POST

{
    // This example assumes all other necessary content has been defined
    "pools": [
        {
            // ... other pool attributes ...
            "content": {
                // This example will create an itempool using ANY combination of the following tags
                // [(bar: baz AND qux: quux) and (foo: *)] OR [(corge: grault) AND (garply: *)] OR [foo: bar]
                "tags": [
                    {
                        "required_tags": [
                            {
                                "type": "bar",
                                "name": "baz"
                            },
                            {
                                "type": "qux",
                                "name": "quux"
                            }
                        ],
                        "additional_tags": [
                            {
                                "type": "foo"
                            }
                        ]
                    },
                    {
                        "required_tags": [
                            {
                                "type": "corge",
                                "name": "grault"
                            }
                        ],
                        "additional_tags": [
                            {
                                "type": "garply"
                            }
                        ]
                    },
                    {
                        "type": "foo",
                        "name": "bar"
                    }
                ]
            }
        }
    ]
}

Full example of a complex itempool request

// The Data API request endpoint for this example is itembank/pools
// The request type is POST

{
    "pools": [
            {
                "reference": "example_itempool_reference",
                "name": "Learnosity Itempool Example",
                "description": "An example pool to demonstrate the required and optional pool attributes.",
                "status": "published",
                "overwrite": true,
                "ignore_empty_additional_tags": true
                "content": {
                    "activity_tags": [
                        {
                            "required_tags": [
                                {
                                    "type": "bar",
                                    "name": "baz"
                                },
                                {
                                    "type": "qux",
                                    "name": "quux"
                                }
                            ],
                            "additional_tags": [
                                {
                                    "type": "foo"
                                }
                            ]
                        }
                    ],
                    "item_tags": [
                        {
                            "required_tags": [
                                {
                                    "type": "corge",
                                    "name": "grault"
                                }
                            ],
                            "additional_tags": [
                                {
                                    "type": "garply"
                                }
                            ]
                        },
                        {
                            "type": "foo",
                            "name": "bar"
                        }
                    ]
                }
            }
        ]
}

Itempools are not an immediately created snapshot. They are created via an asynchronous job due to potentially large and complex migration requests. This means that any creation or updating of Itempool content will result in a response from the Learnosity Jobs Service.

The immediate successful response from an Itempool request may look something like the following:

// The Data API request endpoint for this example response is itembank/pools
{
    "meta": {
        "status": true,
        "timestamp": 1442011150
    },
    "data": [
        {
            "pool_reference": "example_itempool_reference",
            "job_reference": "2c16732f-81a6-4e1c-bd09-0c01f9faf3da"
        }
    ]
}

In this response, we see our returned pool_reference (item_pool_id), which has been confirmed valid and unique, as well as a job_reference

The job_reference is required to track the progress of the Itempool request as it is processed by the jobs service.

The Jobs Service

The jobs service is a queue based service that processes large tasks in a timely manner.
All tasks go three phases when being processed by the jobs service:

  • Queued - a new request has been made and is waiting to be processed. This is an indication that a request has passed initial validation.
  • Running - the task is being processed. Itempool related jobs are processed very quickly, so this phase may not be observed.
  • Completed - the task is complete. An Itempool job that is completed means the pool has been created, however, relevant extra information can sometimes be found in the job results.
  • Halted - the alternate third phase of a job. An error has occured during processing. Relevant information will be available in the job results.

Beyond checking on this job status and processing results, once a job is completed, it no longer needs to be checked on for Itempool related information.

The Data API endpoint for checking on a job is /jobs. The quick reference for creating a request to the jobs endpoint can be found here.

If an explicit job reference is available (such as in the case of an Itempool request), then a request would look like the following:

// The endpoint for this request is /jobs
{
    // A job request by reference requires references to be an array of strings
    "references": [
        "2c16732f-81a6-4e1c-bd09-0c01f9faf3da"
    ]
}

A response to the above request:

// This is an example response
// The endpoint for this request was /jobs
{
    "meta": {
        "status": true,
        "timestamp": 1442794928,
        "records": 1
    },
    "data": [
        {
            "organisation_id": 1,
            "reference": "2c16732f-81a6-4e1c-bd09-0c01f9faf3da",
            "type": "itempool",
            "status": "completed",
            "data": "{"content":{"tags":[{"type":"MIBKIBMP"}],"status":1,"name":"Example item pool","description":null,"reference":"example_itempool_reference","ignore_empty_additional_tags":false}}",
            "results": "[]",
            "dt_created": "2015-09-21 00:21:25",
            "dt_completed": "2015-09-21 00:21:27"
        }
    ]
}

completed status is the indication that the job is complete and the Itempool is ready to use.

Itempools can be used anywhere that item bank content is used, the only difference is that an item_pool_id is provided along with the request.
Important an item_pool_id in requests is the same as the reference used to create the Itempool.

Example of a [GET] Items request using an item_pool_id

{
    "references": [
        "itemRef1",
        "itemRef2",
    ],
    "tags": [
        {
            "type": "foo",
            "name": "bar"
        }
    ],
    "item_pool_id": "example_itempool_reference",
    "limit": 5
}

The additional information used to create an itempool, e.g. namedescription etc. can be retrieved with a simple [GET] request to the itembank/pools endpoint.
Itempools can be retrieved by:

  • references (array) - an array of explicit Itempool references
  • status (array) - an array of status strings (published or unpublished

Example of an Itempool [GET] request

// The Data API request endpoint for this example is 'itembank/pools'
// The request type is GET

{
    "references": ["example_itempool_reference"],
    "status": ["published"]
}

Itempools are a snapshot of item bank data from a point in time, and as such, updating an existing Itempool is done in following ways:

  • Completely overwriting the data with new content (often used to preserve the Itempool reference with no regard for the content)
    Note see Creating Itempools above.
  • Appending the Itempool with additional content, but not altering what already exists by default. Add new Itempool objects in JSON request and set "overwrite" flag to false.
  • Updating the existing Itempool objects with the new state of these objects. Add Itempool objects you want to update in JSON request and set "overwrite" flag to true.

Many of the examples used above in the Creating Itempools section similarly apply to updating pools, with nuanced definitions of flags being found in the update pools documentation.

The endpoint for Itempool update requests is itembank/pools, and the request type is PUT.

Was this article helpful?
0 out of 1 found this helpful