Welcome to AP_ItemSampler Docs¶
Application Overview¶
The Sample Items Website is a Microsoft ASP.NET Core MVC web application that displays sample test question items.
License¶
Mozilla Public License Version 2.0
Installation¶
- Clone the project
- Don’t forget to initialize the project submodules (instructions)
- Install the latest version of Microsoft .NET Core for your operating system (link)
- Install the latest TypeScript compiler (link)
- Download the latest sample item content package (TODO: Link?)
- Place this in the location specified in src/Web/appsettings.json
(
ContentRootDirectory
)
- Place this in the location specified in src/Web/appsettings.json
(
Project Architecture¶
The Sample Items Website project is composed of three layers: Web, Core, and Dal.
Web is the startup project and contains controllers, views, style, and other web dependencies. See the Dependencies section for more information.
Core provides business logic to Web via repositories. It also houses the business logic for the diagnosticAPI and model translations.
Dal provides data to the Core layer. All data is supplied by a
“content package” which is a set of XML files that represent test
question items. This XML is parsed into the immutable ItemDigest
and
ItemCard
models, which are used throughout the application.
Other XML data is used, such as
AccessibilityAccommodationConfigurations
, ClaimConfigurations
,
and InteractionTypeConfigurations
. These configure information such
as order and labels for accessibility and interaction types.
Test is the test project for Sample Items Website. It contains unit tests and integration tests for each of the three aforementioned layers.
Project Setup¶
General Steps¶
- Clone the project
- Don’t forget to initialize the project submodules (instructions)
- Install the latest version of Microsoft .NET Core for your operating system (link)
- Install the latest TypeScript compiler (link)
- Download the latest sample item content package
- Place this in the location specified in src/Web/appsettings.json
(
ContentRootDirectory
)
- Place this in the location specified in src/Web/appsettings.json
(
Running¶
Using Visual Studio 2015¶
- Open the project in Visual Studio 2015
- Click the run button
Using Command Line¶
- Set environment variable
ASPNETCORE_ENVIRONMENT
toDevelopment
- in Windows:
setx ASPNETCORE_ENVIRONMENT "Development"
, then close and reopen the command prompt
- in Windows:
cd SampleItemsWebsite\SmarterBalanced.SampleItems
dotnet restore
cd src\SmarterBalanced.SampleItems.Web
dotnet run
- Navigate to
http://localhost:<port>
in your browser to view the running site
Application Settings and Configurations¶
Within the SmarterBalanced.SampleItems.Web
project, configurations
are set in the file appsettings.json
. This file contains all of the
configurations and settings that are used throughout the application.
Within appsettings.json
, the SettingsConfig
object contains
configurations necessary to start the application, as well as runtime
configuration settings.
Note: Following is a description of important configurations within this object:
ContentItemDirectory
: Location of the Items directory within the
content package. Dependent on deployment environment setting
(development, staging, production).
ContentRootDirectory
: Location of the content package. Dependent on
deployment environment setting (development, staging, production).
AwsS3Bucket
: AWS S3 bucket that contains the content package.
Required for the diagnostic status feature.
AwsRegion
: AWS region. Required for the diagnostic status feature.
ItemViewerServiceURL
: Base URL for itemviewerservice, which renders
the test question items. URL is used to display an iframe of each item.
AwsClusterName
: Name of AWS cluster. Required for the diagnostic
status feature.
StatusUrl
: Diagnostic status URL for local diagnostic status.
Required for the diagnostic status feature.
AccommodationsXMLPath
: Location of the accessibility configurations
XML document.
InteractionTypesXMLPath
: Location of the interaction types
configuration XML document.
ClaimsXMLPath
: Location of the claims configuration XML document.
Additionally, the RubricPlaceHolderText
object contains strings that
are filtered out of item
Build¶
Sampleitems Website requires content before running.
There is a two-step process using docker. The base app without content needs to be created as a docker image called code. Then we combine the code image with the content package using another dockerfile.
Before starting build¶
Locate the dockerfile.stage and dockerfile.prod files from github repo, navigate to deployScripts
Using a previous docker code image¶
To build a docker image for sample items website code base (without content) see Building from scratch
Docker¶
- Navigate to directory containing dockerfiles
- Get docker code repo for stage/prod, run
docker pull reponame:{tag}
- Example stage: run
docker pull xxx.dkr.ecr.us-west-2.amazonaws.com/sampleitemscode:stage
- Example producation: run
docker pull xxx.dkr.ecr.us-west-2.amazonaws.com/sampleitemscode:prod
- Example stage: run
- Docker tag code, run
docker tag reponame:{tag} sampleitemscode:{tag}
- Example stage: run
docker tag xxx.dkr.ecr.us-west-2.amazonaws.com/sampleitemscode:stage sampleitemscode:stage
- Example production: run
docker tag xxx.dkr.ecr.us-west-2.amazonaws.com/sampleitemscode:prod sampleitemscode:prod
- Example stage: run
- place content within deployScripts directory
- Content needs to be unzipped
- content directory root level needs Items directory
- Docker build, run
docker build -t sampleitemsapp:{tag} -f Dockerfile.{tag} .
- Example stage: run
docker build -t sampleitemsapp:stage -f Dockerfile.stage .
- Example production: run
docker build -t sampleitemsapp:prod -f Dockerfile.prod .
- Example stage: run
- Docker Run app , run
docker run -it -p 8012:80 sampleitemsapp:{tag}
- Example stage: run
docker run -it -p 8012:80 sampleitemsapp:stage
- Example production: run
docker run -it -p 8012:80 sampleitemsapp:prod
- Example stage: run
- Go to localhost:8012
- point to docker
Building from scratch¶
Dependencies¶
- See Project Dependencies
- Install Nodejs and npm
Dotnet build and Publish¶
cd SampleItemsWebsite\SmarterBalanced.SampleItems
dotnet restore
cd src\SmarterBalanced.SampleItems.Web
npm install
grunt all
dotnet publish -o ../../publish
cd ../../publish
Docker build¶
- Go to the publish directory containing the dockerfile
- Build app, run
docker build -t sampleitemscode:{tag}
- Example stage: run
docker build -t sampleitemscode:stage
- Example producation: run
docker build -t sampleitemscode:prod
- Example stage: run
Deploy Sample Items app¶
- see Publish Docker
Dependencies¶
NPM¶
NPM is required to install Grunt, Grunt packages, Less, and TypeScript.
See package.json
in the Web project for configurations.
Bower¶
Bower is required to add Bootstrap, JQuery, and React. See
bower.json
in the Web project for configurations.
Grunt¶
Grunt is used to perform tasks with Visual Studio events as well as with build events. Grunt:
- Compiles TypeScript files into JavaScript on save and build
- Compiles Less CSS into CSS on save and build
- Minifies CSS on build
- Removes temp files
For Grunt configurations, see Gruntfile.js
in the Web project.
External Dependencies¶
Docker¶
Docker is used to simplify and unify the build and runtime environment for the application.
See Dockerfile
in the Web project for Docker configurations. The
Web project also contains a .dockerignore
.
TravisCI¶
TravisCI is used to verify the state of the application every time a developer pushes to a branch in the GitHub repository. It first installs project dependencies, pulls and builds the project, and then runs tests.
After the previous steps succeed, Travis builds a Docker image with the application and pushes it to AWS.
On the dev, stage, and master branches, Travis triggers a build process in AWS that combines the content package, hosted in an S3 bucket, with the application Docker image and performs a rolling update to the running versions of these branches.
See the travis.yml
file in the root directory project for
configurations.
Content package¶
The content for the site is provided by a content package supplied by the Smarter Balanced Assessment Consortium. It consists of XML files that describe the test question items (the “content package”).
Currently, content packages can be accessed at ftp://ftps.smarterbalanced.org/~sbacpublic/Public/PracticeAndTrainingTests/.
Docker¶
Publish Docker to AWS¶
- Go to Amazon ECS
- Select Repositories
- Select a repository or create
- Select push Commands
- Follow the push Commands or follow:
- Go to the root directory containing Dockerfile
- Run
aws ecr get-login --region us-west-2
- Run the docker login command
- Run
docker build -t {repo-name}:{latest/dev/stage/prod} .
- Run
docker tag {repo-name}:{latest/dev/stage/prod} {amazon-repo}:{latest/dev/stage/prod}
- Run
docker push {amazon-repo}:{latest/dev/stage/prod}
Publish Docker to DockerHub¶
- Go to the root directory containing Dockerfile
- Run
docker login
- Run
docker build -t {repo-name}:{latest/dev/stage/prod} .
- Run
docker push {repo-name}:{latest/dev/stage/prod}
Docker Commands¶
To update a docker image, please follow publish to Aws or DockerHub
Accessibility Resources¶
- See ISAAP docs
Terms¶
- Accessibility Family: Default accessibility Resources available to the item based on the item’s grade and subject
- Accessibility Resource: The group of accessibility options.
- Example: Dictionary, Calculator
- Accessibility Option: Accessibility feature code. An ISAAP code to enable/disable accessibility.
- Example: Calculator has Off and On options
- ISAAP: A unique code for accessibility. Each code has a
TDS
prefix.- See docs
AP_ItemViewerService¶
Usage¶
Please see github repo AP_ItemViewerService
Dictionary and Thesaurus¶
This is an external api for merriam-webster and depends on a running instance of TDS_Dictionary. AP_ItemSampler does not have any overrides or connection settings for this instance.
AP_ItemSampler usage¶
Client (Web)¶
Item Page and About Test Items use the AP_ItemViewerService as an iframe. Item Sampler passes a list of items, need to be related, with isaap codes. These codes are generated within the accessibility modal using the local item’s accessibility options. Items and Item’s family accessibility can be loaded from the Item Sampler’s api.
TODO: add API link
DAL¶
Accessibility is loaded from xml sources from a git submodule Github. Item Sampler loads them as is then applies business logic to create a complete list of accessibility resources for each family.
XML¶
Provides a global list of all accessibility resources, options, groups, and families. Families are a list of rules to apply to the global list for the subject and grade range.
Accessibility Resource Groups¶
This is the label for the group. Labels are loaded from the AppSettings.json and matched on the xml group key.
Merged Accessibility Family¶
This contains a list of accessibility resources for a range of grades and a subject. This contains the default options supported for a subject (ELA) and a grade range (3-5). Accessibility resource families from the xml contain rules to enable and disable options but not the options themselves. To simplify this process, merged accessibility families were created to execute the rules on the global list and contain the final result.
Item Accessibility¶
Local item accessibility is calculated from the accessibility family resource, based on subject and grade, and the item metadata attributes.
Item’s that can have different accessibility than the family:
- Metadata attribute AllowCalculator
- Item types
- Performance Task
- Thesaurus and Dictionary
- Braille (based on the ftp server resources)
- Metadata attachements (ASL)
- Claim
Calculator¶
Metadata can enable and disable calculator based on AllowCalculator
. Calculator only shows Off and On for all math items. On refers to the item’s specific calculator option based on grade.
Thesaurus¶
Can be disabled if calculator is not allowed/available and if the item type is not WER.
Braille¶
Can be enabled if the ftp server has a listing for the item
American Sign Language¶
Can be enabled if the item’s contents has a ASL video attachment
Global Notes¶
Can be enabled if item is a performance task
Options¶
Universal Tools¶
Digital Notepad¶
Displays a notepad in the item’s hamburger menu. This will open a dialog for a user to enter text and save.
English Glossary¶
Provides glossary definition for an item’s word list. This will show a dashed top and bottom border for words that have a glossary definition.
Highlighter¶
Allows highlighting the item and/or passage’s text. To highlight, select text and right click or use the hamburger menu then select highlight text. To remove, select highlighted text and from the menu, select remove highlight.
English Dictionary¶
Provides a dialog to search the merriam-webster api for definitions. When enabled, a toolbar icon will display with text Dictionary.
Expandable Passages¶
Allows the passage to expand over the item. To enable, an icon will appear to the left of the hamburger menu for the passage, select the expand icon.
Global Notes¶
Provides a dialog to enter global notes for the user’s session. When enabled, a toolbar icon will display.
Strikethrough¶
Allows strike-through text for the item and/or passage’s text. To enable, select text and right click or use the hamburger menu and then select strikethrough. To remove, select the striked-through text and from the menu select remove strikethrough. (TODO: Verify name in menu.)
Thesaurus¶
Provides a dialog to search the merriam-webster api thesaurus. When enabled, a toolbar icon will display with text Dictionary. Dictionary enabled accessibility option is required for thesaurus.
Zoom¶
Increases/decreases text size for both passage and item. This should always be enabled. Two toolbar icons will appear.
Designated Supports¶
Color Choices¶
Changes the background color and text color for the item and passage.
Masking¶
Creates a overlay on top of the item and/or passage. A toolbar icon will display with text Masking. To enable, select the masking icon. To dismiss, select the x icon in the upper right of the masked overlay.
Translations (Glossaries)¶
Provides glossary definition for an item’s word list. This will show a dashed top and bottom border for words that have a glossary definition for the selected language.
Translations (Stacked)¶
Provides translated item and passage text.
Accommodations¶
American Sign Language¶
Displays a dialog with an ASL video to describe item and passage. To enable, select the option from the hamburger menu.
Braille Type¶
Provides braille files for the item and/or passage to be printed. Above the item viewer, a new link will be displayed.
Streamlined Interface¶
Changes the layout of the item and passage. When enabled, the passage will be above the item.
Rubric and Rationale¶
Content Package¶
Applies to item-{bankKey}-itemKey.xml files within the content directory that are items. There are two types of “scoring” information. Rubric and Rationale list. Rationale list seems to be multiple choice explanations of the correct/incorrect answer. Rubric list has two parts, samples and rubrics. Rationale list also has rationale and option lists. There can be many sets based on the language.
Other Scoring Attributes¶
MachineRubric
: Specifies the machine rubric qrx file for automated scoring.itm_att_Answer Key
Rubric List¶
Rubric contains rubric entries and sample entries. Rubric entries are listed for each possible point value. There is usually many sample lists within a rubric list even though most sample lists contains one entry. Sample are example responses to get a certain point value. Rubrics are the requirements to achieve a specific point value.
content
>rubriclist
>rubric
- Score Point - entries point value
- Name - specifies rubric name with point
- Val - html of response
content
>rubriclist
>samplelist
>sample
- Purpose
- Name - specifies sample name with point value
- Annotation * not mapped
- Sample Content - html of explanation
Rationale List¶
Multiple choice and rationale for each possible answer. Note: Not mapped Explanation of Correct Answer and rationaloptlist
- Not Mapped -
content
>rationaleoptlist
>rationale
- Name - each option value (a,b, …)
- Val - html of choice option (usually blank)
content
>optionlist
>option
- Name - each option value (a,b, …)
- Val - html of choice option
- Feedback - html explanation of chosen answer
Item Sampler Translation¶
ItemDigest
is made up of two files, ItemContents
and ItemMetadata
. Item Digest is the merged result of the two files in the content package. ItemContents
has ItemXmlFieldRepresentation
of the Item. This has the list of Content
which holds all Rubric and Rationale List. SampleItem
is the final version of the translated content package.
ItemDigest
- ItemContents
and ItemMetadata
¶
rubriclist
from content is mapped toRubricList
rubric
from content is mapped toRubricEntry
samplelist
is mapped toRubricSample
optionlist
>option
is mapped toSmarterAppOption
SampleItem
from ItemDigest
¶
ItemDigest
is translated to SampleItemScore
. Please see code documentation for more information.
SampleItemScore
combines rubric and rationale for easier consumption in the API. It also filters out placeholder text and identifies correct/incorrect options.