Using Item Pools to Create Content Snapshots

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

Item pools are a snapshot of specified Item bank data that is useful for keeping live, assessment-ready content consistent and immutable for a long period of time, while simultaneously letting content authors continue to update the original content.

The difference between an Item bank and an Item pool is that Item pool 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, assessment-ready content consistent and immutable for a long period of time, while simultaneously letting content authors continue to update the original content.

Note: Only published content can be added to an Item pool (or you can provide a flag to set unpublished content to published when copying into the pool - but either way, pools only contain published Items/Activities). As such, if an Item is in a workflow state, this will be removed.

Note: As pools are snapshots of data from a single Item bank, they can not be created with Activities which have Items from multiple Item banks. If a pool request is made which would result in including Activities that contain Items from Item banks, the pool creation will fail (and the job will indicate which Items are not from the same bank).

 

The reference documentation for creating Item pools 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 Item pool 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 Item pool (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 Item pool 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) - whether the pool itself is 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 preserve/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 Item pool content

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

  • activity_references (array) - this is an array of Activity references. The Item pool 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 Item pool 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, Item pool 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 Item pool, this is required.
  • name (string) - the Tag name; for obtaining content for an Item pool, this is not required.

When using Tags to get Item pool 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 Item pool 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 so: (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 Item pool 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 Item pool request

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

{
    "pools": [
            {
                "reference": "example_itempool_reference",
                "name": "Learnosity Item pool 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"
                        }
                    ]
                }
            }
        ]
}

Item pools 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 Item pool content will result in a response from the Learnosity Jobs Service.

The immediate successful response from an Item pool 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 Item pool 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 through 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. Depending on the size of the pool, it may remain in this state for a very little amount of time, or a long time.
  • Completed - the task is complete. An Item pool 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 occurred during processing. Relevant information will be available in the job results. Job may be picked up again later, depending on the error.

Beyond checking on this job status and processing results, once a job is completed, it no longer needs to be checked on for Item pool 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 Item pool 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 Item pool is ready to use.

 

Item pools 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 Item pool.

 

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 Item pool, e.g. namedescription (and so on) can be retrieved with a simple [GET] request to the itembank/pools endpoint.
Item pools can be retrieved by the following:

  • references (array) - an array of explicit Item pool references.
  • status (array) - an array of status strings (published or unpublished).

 

Example of an Item pool [GET] request

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

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

Item pools are a snapshot of Item bank data from a point in time, and as such, updating an existing Item pool is done in following ways:

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

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

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

Was this article helpful?

Did you arrive here by accident? If so, learn more about Learnosity.