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.

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.

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" }])
  • The 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.

Tools for Writing JSON Documents

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

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

Protocol Files

At a minimum, protocols must contain a file named protocol.json. See the What is a Protocol section for more details on the protocol architecture.

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

Development Environment

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

Develop Protocols on the Tablet

This method is appropriate for most users. More advanced protocol developers may choose to develop protocols in a web browser.

To load protocols via the Device Storage, see the section on Device Storage.

To load protocols from a Gitlab Repository, see the section on Gitlab.

Development Tips

  • Make sure to validate the syntax of your protocol before loading on to the tablet.
  • Select the Validate Protocols option within TabSINT to confirm that your protocol validates against the TabSINT protocol schema

Develop Protocols in a Web Browser

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

Steps

  • Clone the TabSINT source code from the TabSINT GitLab Repository

  • Follow the instructions in the Developer Guide located in the TabSINT repository to set up the necessary build tools and app dependencies.

  • 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
  • Add 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.
  • You may also choose to use the protocol sandbox that is included with the TabSINT source code. This protocol is already set up to be loaded by the config/example_config.json TabSINT configuration file.
  • Select the protocol from the Admin View and then press Load.

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 selecting the Validate Protocols option within TabSINT.

References

Last updated on 5/28/2020
← DosimeterResponse Areas →