Item Encoding

In the Janus API, “Items” are any data point that come from either the results of the Data Gatherer or Evaluate phases. Some examples of items are first name, response to question 1, total score, assessment date, and many more. Any single data point in a measure is an Item.

Items are encoded into the API requests through pipe-delimited strings, grouped into Observation and Outcome Sets. Items can be one of multiple types as defined in the ScalesItems file, for example numeric, one-of, or string. The ScalesItems file provided for a measure defines each Item within the “ObservationSets” and “OutcomeSets” tabs of the Excel file. Each table represents an Observation or Outcome Set, and each row in the table represents an Item. Each table has a unique identifier seen in the “ID” field above the table, which corresponds to the “interpretAs” (for Observation Sets) or “outcomeSetID” (for Outcome Sets) in the request JSON.

Figure 1 – A sample Observation Set table with two Items from a ScalesItems file.

The ScalesItems file contains the definitions for all the items of a measure. In the figure above is an Observation Set containing two items. The columns of the table define the following:

• Identifier: A ShortID (8 alphanumeric characters, case sensitive) used as an identifier for the specific item.
• Prompt: Defines what the item represents.
• Type: Defines what type of item is represented, either Observation or Outcome.
• Domain: Defines the data type of the item.
• Values: For OneOf and N-State types, defines all possible values for the Item, delimited by pipes.
• ValuesPrompt: For OneOf and N-State types, defines the meaning of each of the Values, delimited by pipes. The first item in the “ValuesPrompt” string matches the first item in the “Values” string, the second in ValuesPrompt matching the second in Values, and so on. So in this example, for the item with Prompt “Gender”, a value of 1 represents “Female”
• SeqNum: The order in which the items appear in the Observation or Outcome Set. Will always be sequential in the same order as the table.

So in this sample, a Data Gatherer might return the following pipe-delimited Items string:

“Items”: “21|0”

Looking at the table above, the “21” belongs to the Item with prompt “Age”, and “0” belongs to the Item with prompt “Gender”. Because age is a Numeric Item, the value of 21 can be taken literally. Gender is a OneOf Item, so the associated ValuesPrompt should be referred to; here a value of 0 represents “Male”. Therefore, it can be understood that the gathered data is describing a 21-year-old male.