What is CAPI?

CAPI 101
Slide Deck

CAPI 101

What is CAPI?

Read more about CAPI

Read/Write Properties of CAPI

Read more about CAPI Read/Write Properties

Types of CAPI

Read more about CAPI Types

Operators

Number Operators

Boolean Operators

String Operators

Array Operators

Enum Operators
 Math Expression Operators

Point Array Operators

Other CAPI Features

Firing Check Events

Data Storage

Configuring CAPI

What is CAPI?
CAPI is what allows for the control of a simulation or input widget inside
the authoring tool. CAPI gives the ability to set up a simulation or input
widget for student viewing and inspect how the student interacts with
them.
CAPI stands for Control Application Programming Interface (API) and is
the mechanism used by simulations and other widgets (multiple choice,
input boxes, Annotate, etc.) to connect with the platform.

• the way authors control and inspect stage elements.

• a communication framework

• a set of properties

Read more about CAPI

CAPI allows for the control of a simulation or input widget inside the
authoring tool. It gives the ability to set up a simulation or input
widget for student viewing and inspect how the student interacts with
them. Well designed CAPI increases the flexibility of a simulation,
making it possible to use it in several contexts or to target different
learning objectives. With CAPI, lesson authors can use simulations
and input widgets to create very rich experiences through
configuration that are personalized to each student’s actions through
inspection.

CAPI stands for Control Application Programming Interface (API) and

is the mechanism used by simulations and other widgets (multiple
choice, input boxes, Annotate, etc.) to connect with the platform.
When writing trap state and initial setup conditions, authors are
targeting properties exposed through CAPI. When a screen loads in
 the viewer, simulations and widgets are also loaded and they can tell
the platform when they are ready to receive values. The platform then
sends any values it has to the simulation or widget for processing.

CAPI started as a simple set of properties with change notification,

but has grown as simulations have become more complex. These
additional features will also be covered here.

Read/Write Properties of CAPI

From the perspective of the authoring tool, CAPI can be considered:

• Read only

• Write only

• Read/write

Read more about CAPI Read/Write Properties

A read-only CAPI property is one that is only expected to be read
from the authoring tool. The simulation does not expect these
properties to be changed externally, and is not required to respond if
the value is set by the platform. In short, these properties won’t be
found in initial setup. These are the “evaluation” properties, and will
be found in trap state conditions. An example of a read-only property
could be the result of a calculation done by the sim based on some
student inputs.

A write-only CAPI property is one that the simulation expects the

platform to write to but will never write to it its self. These are usually
configuration properties, and will be found in initial setup instead of
trap state conditions. A good example of a write-only property is
whether or not an element of the sim should be displayed.

Read/write CAPI properties are expected to both be read in trap

states and set in initial setup. These are things the author may want to
set on the sim, but the student should also have control over. These
values frequently have an effect on the way the sim works. An
example for a read/write property would be the angle of a cannon
that the student is going to fire.
Types of CAPI
When working with CAPI properties in the author, the value of a property
has a specific type.

• Number • Array • Math

Expression
◦ Ex: 42 ◦ List of

• Boolean multiple ◦ Latex

values equation
◦ true/false
◦ Ex: [1,2,3] ◦ Ex: 3x^{2}
• String or [“a”, “b”,
• Point array
◦ Line of text “c”]

◦ Ex: “Hello • Enum

world!”
◦ Options in
a drop-
down that
are defined
by the sim
or widget

◦ Ex:
(Monday,
Tuesday,
Wednesday
)

Read more about CAPI Types

Operators
Each property type has a set of operators associated with it in trap states.
When a condition is being evaluated the operator defines the way in
which the CAPI property (right-hand side) is compared to the evaluation
value (left-hand side).
Number Operators

Operator Description

= or is this condition is true if the left hand side and right

hand side are the same value. Recommend only
using =

!= or not is true if the left and right hand side are not the same
value. Recommend only using !=

is NaN (is not a number) This is a boolean. True if the left-hand side value is
not a number. For example, if someone put the
String “three” into an input box, “is not a number”
would be true. This is mostly used to see a number
input is left empty.

is any of More or less the same as != . So this condition is

true if the left hand side and right hand side are
NOT the same value. I recommend just using

> (greater than) true if the left hand side is strictly greater than the
right hand side. If the values are the same, this will
not be true.

>= (greater than or equal to) same as greater than, but will be true if the two
 >= (greater than or equal to) same as greater than, but will be true if the two
sides are the same.

< (less than) true if the left hand side is strictly less than the right
hand side. If the values are the same, this will not be
true.

<= (less than or equal to) same as less than, but will be true if the two sides
are the same.

~== (approximately equal to) this is true if the left hand side is approximately
equal to the right hand side, within a % range,
which is denoted by a comma and percentage value
after the number.

~!= (approximately not equal to) this is true if the left hand side is not approximately
equal to the right hand side, within a % range,
which is denoted by a comma and percentage value
after the number. Ex: [Link] Number
~!= 42,2 (i.e. not 42 within 2% range)

in range true if the left-hand side is greater than or equal to

the lesser of the two right-hand values, and less
than or equal to the greater of the two right-hand
values

not in range true if the left-hand side is strictly less than to the
lesser of the two right-hand values, or strictly
greater than to the greater of the two right-hand
values

Boolean Operators

Operator Description

= or is true if the left hand side and right hand side are the
same value. This will be evaluated as true/false.
Recommend only using =

!= or not is true if the left and right hand side are not
value. This will be evaluated as true/false.
Recommend only using !=
String Operators

Operator Description

= and is this condition is true if the left hand side and right
hand side are the same value.

!= true if the left and right hand side are not the same
value.

is exactly similar to =/is and !=/not is , except these would

be case sensitive.

not is exactly similar to =/is and !=/not is , except these would

be case sensitive.

contains Will be true if the right-hand string can be found

somewhere in the left-hand string. For example, if
the left-hand side is “Quick Brown Fox”,
will be true for “Fox”, “quick”, and “Ck br”.

does not contain The opposite of contains , this will be true if the
right-hand string cannot be found anywhere in the
left-hand string. For example, for “Quick Brown Fox”,
“jumps” would be true.

contains exactly Basically the same as contains but case sensitive

not contains exactly Basically the same as not contains but case sensitive

contains any Similar to contains , but this time for a list (array) of
values

not contains any Similar to not contains , but this time for a list
(array) of values

starts with Starts with will be true if the beginning of the left-
hand string is the right-hand string. For example, for
“Quick Brown Fox” as the left-hand string, “Quic” and
“Quick Brown Fox” would be true, but “uick” would
not.

ends with Just like starts with, but for the end of the string.
Examples with “Quick Brown Fox” - “Fox” or “Quick
 Brown Fox” are true, but “Fo” is not.

Array Operators

Operator Description

= and is this condition is true if the left-hand and right-hand

arrays are exactly the same, including order.

!= and not is true if the left-hand and right-hand arrays are not
the same, including order.

contains True if every element in the right-hand array is in the

left-hand array. It does not matter if the left-hand
array contains more than what is in the right-hand
array or not.

not contains True if all of the elements in the right-hand array are
not in the left-hand array. For example, if the left-
hand array is [a, c, e], “does not contain” will be true
for [a, b] and [e, f, g], but false for [c, a] or [a].

contains any True if any of the elements in the right-hand array

are in the left-hand array.

not contains any True if none of the elements in the left-hand array
are in the right-hand array.

contains only True if the elements in the right-hand array are the
only elements that appear in the left-hand array. This
works as = without order mattering. Duplicates can
cause this to be false, so “[a, a] contains only [a]” is
false.

Enum Operators

Operator Description

= or is true if the left hand side and right hand side are the
same value. Recommend only using =

!= or not is true if the left hand side and right hand side are
the same value. Recommend only using
 Math Expression Operators
This needs to be updated…

• is exactly - true if the left-hand expression is exactly the same as

the right-hand expression. This is not a string comparison of the
Latex, different operator notations (* or dot for multiply) are
considered the same, but variable usage and term order matters.

• is not exactly - true if the left-hand expression is not exactly the

same as the right-hand expression. The same caveats apply as “is
exactly”

• is equivalent of - true if the left-hand expression and right-hand

expression are equivalent to each other. This will be false if
different variables are used. This is used to see if a student has
input an expression that is not exactly the same as the
instructor’s, but is mathematically the same.

• is not equivalent of - opposite of “is equivalent of”.

• has same terms - true if the left-hand expression has the same
terms as the right-hand expression

has different terms- the opposite of “has same terms”

Point Array Operators

This needs to be updated…

Other CAPI Features

Firing Check Events

Normally check events happen when the student presses the check
button. Sims can fire check events too! This allows simulations to be
used without the check button, resulting in a much smoother lesson
flow. Simulations can use check events to control when the student
can leave a screen, give the student feedback without the student
needing to press the check button, and more. Check events can be
slow, can have an affect on lesson score, and the trap states that are
hit show up in analytics, so they may not always be right to
 hit show up in analytics, so they may not always be right to
implement.

Data Storage
Sims have the ability to store extra data outside of CAPI properties.
While the appropriate uses for this are fairly narrow (most state
should be in CAPI), sometimes there is data that doesn’t need to be in
CAPI, but should be stored to give a full experience. Currently this is
called “get/set data”. An inspired name, I know.

This data storage is used by sims that would like to store large
amounts of data that doesn’t need to be inspected. A check event
isn’t required to save this data, because it isn’t a part of the CAPI
snapshot, and the sim gets absolute control over when it is saved.

Configuring CAPI
Previously, setting a sim up requires creating an entry in the initial setup
section of the author for every property that needs to be set. This gets
very cumbersome and difficult to maintain very fast.
Now there is a way to set the simulation up in the authoring tool by
interacting with the simulation directly. Simulations are able to expose a
configuration mode that is accessible in the authoring tool that allows
authors to setup the initial state of the sim without using the author’s
initial setup. This is what we call Sim-config. It can greatly improve the
ease of using a simulation or widget in the authoring tool and clean up
the initial setup section of the author.
Additionally, it is possible to copy and paste an iFrame containing a sim
from one screen to another to carry over the configuration, which is not
possible with initial conditions.