Protocols

TabSINT supports many features for developing test protocols out of the box. Test protocols can be developed to accommodate for a wide range of research studies. Protocols allow you to customize your exam in TabSINT. See the TabSINT Protocol Workshop references for more information.

What is a protocol?

A protocol is a machine-readable file that defines the content and logic for a set of interactive pages. These pages may be organized to form unique and complex test protocols and questionnaires.

Protocol pages can contain text, audio, images, and videos, as well as 25+ predefined response areas and WAHTS-specific response areas. These response areas allow for the input of text and integer data, as well as the execution of audiometry exams and many standard speech in noise tests.

Protocol Files

At a minimum, a protocol should be a folder with a meaningful name and must contain a file named protocol.json. The protocol.json file may also reference files:

  • .wav, .mp3: audio files
  • .png, .jpg: image files
  • .mp4: video files

Supporting files may be stored in subdirectories, but protocol.json must be at the top level. All file references must be relative to the root protocol directory (i.e. images/image1.png).

Format

Protocols are written in the text-based JavaScript Object Notation (JSON) format. This format is commonly used for transmitting data objects that are both human and machine readable.

{
    "key": "value",
    "page": {
        "name": "json example"
    }
}

Because this format is machine readable, the syntax is very strict. Each comma, brace, and quote is significant.

The basic JSON structure is:

  • double quotes around keys and values, which are paired with a colon ("key": "value")
  • curly braces to group key/value pairs ({ "key": "value" })
  • square braces to denote an array of similar items ([1, 2, 3])
  • commas to separate groups ([{ "key": "value" }, { "key": "value" }])
  • line breaks are insignificant (they are an aid for the reader but have no syntactic meaning)

Warning: The JSON structure makes it relatively easy for a human to understand the content of the document at a glance, but writing a JSON document can be tricky since every double quote, colon, comma, curly brace, and square brace has syntactic significance. Misplacing even a single one will result in a syntax error.

Attention to detail, along with frequent syntax validation, will ease the development of the protocol.

Protocol Schema

In addition to writing a syntactically valid JSON document, it must be structured in accord with a schema. The schema defines the properties and property types allowed to be used in a protocol. All protocols must adhere to the schema to ensure that TabSINT will know how to interpret the protocol file.

The complete TabSINT Protocol Schema is hosted in the TabSINT source code repository on Gitlab.

For more information on how JSON schema files are structured see http://json-schema.org/.

Elements of a Protocol

  • Global Properties: Protocols contain a set of top level properties that define the parameters and context in which a protocol should be administered. The global properties are inherited by each page and can be used to customize the protocol flow. Global properties are defined in protocol_schema.json.
  • Pages: Protocols contain a set of pages that are presented to the user in a specified order. Each page contains a combination of text and media to present to the user and a response-area to collect a user response. Page properties are defined in page.json.
  • Response Areas: The user response can be obtained in many formats, including yes/no, integer, multiple choice, checkbox, Likert, MRT, OMT, and QR codes.
  • Subprotocols: A protocol can have different sections, referred to as subProtocols, which have their own global properties (set according to protocol_schema.json), including page defaults and page randomization.
  • Dynamic Content: In addition to these static attributes, a protocol can be made dynamic using customized logic between pages. This logic includes the capability to skip pages, set test flags, and ask follow on questions.

Simple Protocol Example

{
    "title":"A Very Simple Test",
    "pages":[
        {
            "id":"question1",
            "questionMainText":"How many years of service do you have?",
            "responseArea": {
                "type":"integerResponseArea"
            }
        },
        {
            "id":"question2",
            "questionMainText":"How many times have you been deployed to Iraq or Afghanistan?",
            "responseArea":{
                "type":"integerResponseArea"
            }
        }
    ]
}

This protocol presents 2 pages, both of which contain question text and an integer response. The global title property is inherited by each of the pages, but each page defines its own questionMainText to present.

Subprotocols

Sets of pages can be grouped together into larger sections referred to as subProtocols. subProtocols can define specific attributes to a subset of pages within a larger protocol.

For example, one subProtocol may specify a certain type of randomization, while another does not. They can also be used to repeat or reuse groups of pages in different parts of the protocol.

Example Using Subprotocols

{
    "title":"A Simple Multiprotocol Exam",
    "pages":[
        {
                "reference": "no_randomization"
            },
            {
                "reference": "randomized",
            }
        ],
        "subProtocols":[
            {
                "protocolId": "no_randomization",
                "pages":[
                    {
                        "id":"question 1-1",
                        "questionMainText":"How many years of service do you have?",
                        "responseArea":{
                            "type":"integerResponseArea"
                        }
                    },
                    {
                    "id":"question 1-2",
                        "questionMainText":"How many times have you been deployed to Iraq or Afghanistan?",
                        "responseArea":{
                            "type":"integerResponseArea"
                        }
                    }
                ]
            },
            {
                "protocolId": "randomized",
                "randomization": "WithoutReplacement",
                "pages":[
                    {
                        "id": "question 2-1",
                        "questionMainText": "What is your age?",
                        "responseArea":{
                            "type": "integerResponseArea"
                        }
                    },
                    {
                        "id": "question 2-2",
                        "questionMainText": "What is your favorite number?",
                        "responseArea": {
                            "type": "integerResponseArea"
                        }
                    }
                ]
            }
        ]
}

Distributed Protocols

There are full protocols distributed with this software which are good examples to work from when developing a new questionnaire. The protocols distributed with TabSINT are in the src/res/protocol folder of the source code and are available in the Protocols table in TabSINT.

Audiometry

Audiometry Admin

cha-sandbox (contains examples of all of the WAHTS Response Areas)

feature-demo (contains examples of all of the non-WAHTS Response Areas)

Developing Protocols

The following section will provide an overview on the methods for developing protocols.

More advanced tools for developing protocols are described in the Protocol Development Tools section of the Developer Guide.

Tools for Writing JSON

There are many tools that can assist in writing syntactically valid protocols.

Text Editors

The following text editors auto indent and highlight matching braces:

Online Editors

  • JSON Editor Online: An online editor that presents both a text view and object view. The object view presents a hierarchical representation of the JSON document.

Syntax Validators

  • JSON Lint: Copy and paste the protocol text into this editor and it will confirm that JSON syntax is valid.

Development Environment

In order to develop protocols most effectively, a user should have:

Development Workflow

When developing protocols, you can iterate and test on a tablet or in a web browser. While the tablet method is appropriate for most users, more advanced protocol developers may choose to use the web browser method (documented in the Protocol Development Tools section of the Developer Guide).

To test a protocol on your tablet:

  1. Draft your protocol.
  2. Validate the syntax of your protocol.
  3. Check the Validate protocols option on the Protocols Tab (to confirm that your protocol validates against the TabSINT protocol schema)
  4. Load the protocol on your tablet via Device Storage or a Gitlab repository.
    • If the protocol fails validation, edit the protocol so that it adheres to the TabSINT schema. Then go back to Step 2.
  5. Run through the exam.
  6. Make any desired changes in the protocol.json file.
  7. Iterate steps 2-5 until the desired functionality is reached.
Last updated on 6/23/2021
← DosimeterResponse Areas →