<commit_before>#Open Assessments

This project provides a starting point for building a Canvas LTI or OAuth application. 

##Usage

###QTI
Most qti in active use seems to be the qti 1.2 lite variant. Full qti comes packaged in a zip file.

####oEmbed
See the API Documentation for the documentation on oEmbed.

####edX Support
Open Assessments supports the drag and drop and multiple choice question types from edX. 
For more information on the edX xml structure see http://edx-open-learning-xml.readthedocs.org/en/latest/index.html

####Assessment by Url
Assessments can be loaded directly from a remote url - the assessment need not be loaded into http://www.openassessments.com. 
Just specify a src_url. CORS must be enabled on the server specified by src_url. Example:

http://www.openassessments.com/assessments/load?confidence_levels=true&eid=atest&src_url=https%253A%252F%252Fdl.dropboxusercontent.com%252Fu%252F7594429%252FedXCourse%252Fsequential%252F97cc2d1812204294b5fcbb91a1157368.xml

####Stats
For assessments loaded into http://www.openassessments.com you simply need to browse to the assessment and click on the bar graph. 
Stats are available on the site, as json and as csv. Loading stats for an assessment that was loaded via a src_url is a bit trickier.
You'll want to specify an 'eid' (external identifier). In theory you can query later on based on src_url but that makes things hard to control and a 
bit unpredictable. Here's an example using our MIT edX course:

http://www.openassessments.com/assessments/load?confidence_levels=true&eid=atest&src_url=https%253A%252F%252Fdl.dropboxusercontent.com%252Fu%252F7594429%252FedXCourse%252Fsequential%252F97cc2d1812204294b5fcbb91a1157368.xml

For that assessment, the eid specified was 'atest'. View the stats by asking for them by eid. Note that the /0? is important in the url as it tells the system
that you want to find the stats by eid rather than by id:

html:
http://www.openassessments.com/assessment_results/0?eid=atest

csv:
http://www.openassessments.com/assessment_results/0.csv?eid=atest

json:
http://www.openassessments.com/assessment_results/0.json?eid=atest

We recommend using a GUID for the eid to prevent conflicts with other assessments.


##Development

To test your Canvas application with Canvas you will need to provide a public SSL url. The simpliest way to do this is to
use ngrok which can be downloaded from https://ngrok.com/.

###Foreman
Foreman makes it simple to startup all the services required to run the application in development mode. To start the application using foreman simply run:

  `foreman start -f Procfile.dev`

  * Make sure you have the latest version of Foreman installed.

####Environment
Foreman will automatically find and read a .env file. Rename `.env.example` to `.env` and
configure it to your liking.

###Without Foreman
If you need to run services individually or just don't like Foreman you can run each service seperately:

  `rails server`

  `cd client && nodemon webpack.hot.js`

  `ngrok_webpack: ngrok --subdomain cs_assets --log stdout 8080`

  `ngrok_rails: ngrok --subdomain canvasstarterapp --log stdout 3000`


### Modify application name
Change the name of the application to a name that you prefer. Open application.rb and change CanvasStarterApp to the 
name you choose. Do a global search and replace for canvas_starter_app and change it to the name you choose. Do a global
search and replace for canvasstarterapp.

### Secrets file
Rename config/secrets.example.yml to config.secrets.yml. Open the file and change each entry to values that are 
relevant for your application. You will need to request a Canvas ID and Secret from Instructure. You will also
need to setup a default account and provide that account's "code" for the "application_code" entry in
secrets.yml. See the [seeds](Seeds) section below for information on setting up the default account.

config/secrets.yml will be used to hold values that should be kept safe and which should not be commited to your repository.

`cd config`

`mv secrets.example.yml secrets.yml`

###Single Page Application Support
Most LTI applications need to be single page applications in order to avoid a bug that prevents cookies from being written in some
browsers. The Canvas Starter App uses React. During development run the (React Hot Loader)[https://github.com/gaearon/react-hot-loader]

####Webpack Integration

  `npm install -g webpack`

  `cd client && webpack`

####Install Javascript Libraries
To get started run:

  `npm install`

(npm-shrinkwrap)[https://github.com/uber/npm-shrinkwrap] is used to lock specific versions.
npm-shrinkwrap.json is included in the project. To verify your package.json & node_modules tree are in sync run:
  
  `npm-shrinkwrap`

To find outdated modules run:
  
  `npm outdated`

Packages must be updated manually. For example:

  `npm update lodash`

After updating be sure to run shrinkwrap again:

  `npm-shrinkwrap`

###ngrok

Install [https://ngrok.com/](ngrok)

__Create a local tunnel__

`ngrok --subdomain openassessments 3000`

(`openassessments` can be any subdomain). Only use letters or numbers in the name. 
Special characters like '_' will result in errors.

Once you have created the tunnel you will access your application using the ngrok url:

`https://openassessments.ngrok.com`

###Seeds

Open db/seeds.rb and configuration a default account for development and production. Here's a summary
of the values and their purpose:
-  code         Uniquely identifies the account. This is used for the subdomain when running applications on 
                a single domain. Create a default account in the seeds.rb file and then open up `config/secrets`.yml
                and be sure to provide the code from the default account for the `application_code`. Only use letters
                and numbers in the code. Special characters will result in errors.
-  domain       Custom domain name
-  name         Name the account anything you'd like
-  lti_key      A unique key for the LTI application you are building. This will be provided to Canvas
-  lti_secret   The shared secret for your LTI application. This will be provided to Canvas and will be
                used to sign the LTI request. Generate this value using `rake secret`. Alternatively if you 
                leave this field empty an LTI secret will be automatically generated for the account.
-  canvas_uri   The URI of the Canvas institution to be associated with a specific account.

Once you've setup your seeds file run it to setup database defaults:

`rake db:seed`

###Request a Canvas Developer Key

Go to the [https://docs.google.com/forms/d/1C5vOpWHAAl-cltj2944-NM0w16AiCvKQFJae3euwwM8/viewform](Canvas Developer Key Request Form)
Most of the fields will be specific to your organization. The Oauth2 Redirect URI and Icon URL will be as follows below. Be
sure to replace `openassessments.ngrok.com` with your domain. You will need an ID and secret for development and for production. The
development URI will use ngrok while the production URI will use your domain.

__Oauth2 Redirect URI:__
https://openassessments.ngrok.com/auth/canvas/callback

__Icon URL:__
https://openassessments.ngrok.com/oauth_icon.png 

Once your request is approved you will receive a Canvas ID and Secret.
and then add the ID and Secret into the file using these fields:
canvas_id: 
canvas_secret: 

##Deployment

###Heroku

Make sure you have signed up for a heroku account [Heroku](http://www.heroku.com). Then follow the instructions provided by 
Heroku to create your application.<commit_msg>Add deployment and bootstrap instructions to read me<commit_after>#Open Assessments

This project provides a starting point for building a Canvas LTI or OAuth application.

##Usage

###QTI
Most qti in active use seems to be the qti 1.2 lite variant. Full qti comes packaged in a zip file.

####oEmbed
See the API Documentation for the documentation on oEmbed.

####edX Support
Open Assessments supports the drag and drop and multiple choice question types from edX.
For more information on the edX xml structure see http://edx-open-learning-xml.readthedocs.org/en/latest/index.html

####Assessment by Url
Assessments can be loaded directly from a remote url - the assessment need not be loaded into http://www.openassessments.com.
Just specify a src_url. CORS must be enabled on the server specified by src_url. Example:

http://www.openassessments.com/assessments/load?confidence_levels=true&eid=atest&src_url=https%253A%252F%252Fdl.dropboxusercontent.com%252Fu%252F7594429%252FedXCourse%252Fsequential%252F97cc2d1812204294b5fcbb91a1157368.xml

####Stats
For assessments loaded into http://www.openassessments.com you simply need to browse to the assessment and click on the bar graph.
Stats are available on the site, as json and as csv. Loading stats for an assessment that was loaded via a src_url is a bit trickier.
You'll want to specify an 'eid' (external identifier). In theory you can query later on based on src_url but that makes things hard to control and a
bit unpredictable. Here's an example using our MIT edX course:

http://www.openassessments.com/assessments/load?confidence_levels=true&eid=atest&src_url=https%253A%252F%252Fdl.dropboxusercontent.com%252Fu%252F7594429%252FedXCourse%252Fsequential%252F97cc2d1812204294b5fcbb91a1157368.xml

For that assessment, the eid specified was 'atest'. View the stats by asking for them by eid. Note that the /0? is important in the url as it tells the system
that you want to find the stats by eid rather than by id:

html:
http://www.openassessments.com/assessment_results/0?eid=atest

csv:
http://www.openassessments.com/assessment_results/0.csv?eid=atest

json:
http://www.openassessments.com/assessment_results/0.json?eid=atest

We recommend using a GUID for the eid to prevent conflicts with other assessments.


##Development

To test your Canvas application with Canvas you will need to provide a public SSL url. The simpliest way to do this is to
use ngrok which can be downloaded from https://ngrok.com/.

###Foreman
Foreman makes it simple to startup all the services required to run the application in development mode. To start the application using foreman simply run:

  `foreman start -f Procfile.dev`

  * Make sure you have the latest version of Foreman installed.

####Environment
Foreman will automatically find and read a .env file. Rename `.env.example` to `.env` and
configure it to your liking.

###Without Foreman
If you need to run services individually or just don't like Foreman you can run each service seperately:

  `rails server`

  `cd client && nodemon webpack.hot.js`

  `ngrok_webpack: ngrok --subdomain cs_assets --log stdout 8080`

  `ngrok_rails: ngrok --subdomain canvasstarterapp --log stdout 3000`


### Modify application name
Change the name of the application to a name that you prefer. Open application.rb and change CanvasStarterApp to the
name you choose. Do a global search and replace for canvas_starter_app and change it to the name you choose. Do a global
search and replace for canvasstarterapp.

### Secrets file
Run:
`bin/bootstrap`

or manually set up secrets: Rename config/secrets.example.yml to config.secrets.yml. Open the file and change each entry to values that are
relevant for your application. You will need to request a Canvas ID and Secret from Instructure. You will also
need to setup a default account and provide that account's "code" for the "application_code" entry in
secrets.yml. See the [seeds](Seeds) section below for information on setting up the default account.

config/secrets.yml will be used to hold values that should be kept safe and which should not be commited to your repository.

`cd config`

`mv secrets.example.yml secrets.yml`

###Single Page Application Support
Most LTI applications need to be single page applications in order to avoid a bug that prevents cookies from being written in some
browsers. The Canvas Starter App uses React. During development run the (React Hot Loader)[https://github.com/gaearon/react-hot-loader]

####Webpack Integration

  `npm install -g webpack`

  `cd client && webpack`

####Install Javascript Libraries
To get started run:

  `npm install`

(npm-shrinkwrap)[https://github.com/uber/npm-shrinkwrap] is used to lock specific versions.
npm-shrinkwrap.json is included in the project. To verify your package.json & node_modules tree are in sync run:

  `npm-shrinkwrap`

To find outdated modules run:

  `npm outdated`

Packages must be updated manually. For example:

  `npm update lodash`

After updating be sure to run shrinkwrap again:

  `npm-shrinkwrap`

###ngrok

Install [https://ngrok.com/](ngrok)

__Create a local tunnel__

`ngrok --subdomain openassessments 3000`

(`openassessments` can be any subdomain). Only use letters or numbers in the name.
Special characters like '_' will result in errors.

Once you have created the tunnel you will access your application using the ngrok url:

`https://openassessments.ngrok.com`

###Seeds

Open db/seeds.rb and configuration a default account for development and production. Here's a summary
of the values and their purpose:
-  code         Uniquely identifies the account. This is used for the subdomain when running applications on
                a single domain. Create a default account in the seeds.rb file and then open up `config/secrets`.yml
                and be sure to provide the code from the default account for the `application_code`. Only use letters
                and numbers in the code. Special characters will result in errors.
-  domain       Custom domain name
-  name         Name the account anything you'd like
-  lti_key      A unique key for the LTI application you are building. This will be provided to Canvas
-  lti_secret   The shared secret for your LTI application. This will be provided to Canvas and will be
                used to sign the LTI request. Generate this value using `rake secret`. Alternatively if you
                leave this field empty an LTI secret will be automatically generated for the account.
-  canvas_uri   The URI of the Canvas institution to be associated with a specific account.

Once you've setup your seeds file run it to setup database defaults:

`rake db:seed`

###Request a Canvas Developer Key

Go to the [https://docs.google.com/forms/d/1C5vOpWHAAl-cltj2944-NM0w16AiCvKQFJae3euwwM8/viewform](Canvas Developer Key Request Form)
Most of the fields will be specific to your organization. The Oauth2 Redirect URI and Icon URL will be as follows below. Be
sure to replace `openassessments.ngrok.com` with your domain. You will need an ID and secret for development and for production. The
development URI will use ngrok while the production URI will use your domain.

__Oauth2 Redirect URI:__
https://openassessments.ngrok.com/auth/canvas/callback

__Icon URL:__
https://openassessments.ngrok.com/oauth_icon.png

Once your request is approved you will receive a Canvas ID and Secret.
and then add the ID and Secret into the file using these fields:
canvas_id:
canvas_secret:

##Deployment

###Elasticbeanstalk
Ensure that
`bin/bootstrap`
was run initially to setup the correct symlinks

Run
`bin/deploy`
to deploy

###Heroku

Make sure you have signed up for a heroku account [Heroku](http://www.heroku.com). Then follow the instructions provided by
Heroku to create your application.
{'fraction_non_alphanumeric': 0.06155044799376704, 'fraction_numerical': 0.01804960394753928, 'mean_word_length': 4.24089826471589, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 16, 'lorem ipsum': 0, 'www.': 16, 'xml': 8}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6996892', 'n_tokens_mistral': 4615, 'n_tokens_neox': 4290, 'n_words': 2027}