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.

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. These response areas include text and integer inputs, as well as many standard speech in noise tests.

Protocol Files

At a minimum, protocols must contain a file named protocol.json. The protocol may also reference files:

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

Protocol 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.

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

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.
  • 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.
  • 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, 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.

Example: Simple Protocol

{
    "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.

The basic JSON structure is apparent :

  • 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.

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.

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/.

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: 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"
                        }
                    }
                ]
            }
        ]
}

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.

Tablet Workflow

This method is appropriate for most users. More advanced protocol developers may choose to use the web browser.

  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.
  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.

Web Browser Workflow

This method is appropriate for rapid, iterative protocol development. To use this method, a user must also install:

  1. Draft your protocol.
  2. Validate the syntax of your protocol.
  3. Clone the TabSINT source code from the TabSINT GitLab Repository
  4. Follow the instructions in the Developer Guide located in the TabSINT repository to set up the necessary build tools and app dependencies.
  5. Serve TabSINT in a local browser by running the running the following command from a terminal in the root of the repository:
$ npm run serve
  1. Add your protocol as a local protocol to TabSINT to test. See Testing a protocol in the browser for the steps to add a local protocol to the application.
  2. Select the protocol from the Protocols list and then select Load.
  3. Run through the exam.
  4. Make any desired changes in the protocol.json file.
  5. Iterate steps 5-7 until the desired functionality is reached.
Development Tips

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

  • In Chrome, press F12 (windows) or Option+Command+J (mac) to open the developer tools. There, you can:
    • View any errors in the Console
    • Set breakpoints in the Source Code to explore errors
    • Set the Emulate tab to your tablet to see the protocol as it will appear on the tablet
  • Use the TabSINT command line tool npm run validate to test if your protocol validates against the TabSINT protocol schema. This can also be achieved by checking the Validate protocols option on the Protocols Tab.
Last updated on 3/18/2021
← DosimeterResponse Areas →