JSONata Help Guide for AssessFluence

Welcome to the JSONata guide! JSONata is a powerful language designed for querying and transforming JSON data. While it offers a lot of functionality, this guide will walk you through common tasks with clear examples to make learning easier.

Getting Started with JSONata

Our app allows you to input JSON data and apply JSONata expressions to extract, modify, or reshape that data. Use the built-in JSONata Exerciser to test your expressions:

• Paste your JSON data in the left pane.
• Write your JSONata expression in the top-right pane.
• See the results instantly in the bottom-right pane.

Getting Started with JSONata in Assessment Context - we are using a 360-degree feedback assessment for this guide

Your input JSON might look like this (example data):

{
  "assessment_id": "A12345",
  "evaluators": [
    { "name": "Alice", "role": "Manager", "score": 4.5 },
    { "name": "Bob", "role": "Peer", "score": 4.0 },
    { "name": "Carol", "role": "Self", "score": 4.8 }
  ],
  "reviewee": {
    "name": "John Doe",
    "department": "Sales",
    "overall_score": 4.4
  },
  "assessment_date": 1643398446,
  "feedback": [
    { "question": "Leadership", "score": 4.7, "comment": "Excellent leader" },
    { "question": "Teamwork", "score": 4.2, "comment": "Works well with others" }
  ],
  "settings": [
    { "name": "anonymous_feedback", "value": true },
    { "name": "review_period_days", "value": 30 }
  ]
}

You can use JSONata to perform various data queries and transformations to support your assessment analysis.

1) Extract Specific Data

Example: Get the reviewee's name

reviewee.name

Result: "John Doe"

Example: Get the overall score

reviewee.overall_score

Result: 4.4

2) Create a Smaller JSON Object

Suppose you want a summary containing only the assessment ID, reviewee name, and overall score:

{
  "assessment": assessment_id,
  "reviewee": reviewee.name,
  "score": reviewee.overall_score
}

Result:

{
  "assessment": "A12345",
  "reviewee": "John Doe",
  "score": 4.4
}

3) Add New Fields

You can enhance your data with custom properties. For example, create a summary with a custom status message:

{
  "assessment": assessment_id,
  "reviewee": reviewee.name,
  "status": "Completed",
  "average_score": ($sum(evaluators.score) / $count(evaluators))
}

Result: 

{
  "assessment": "A12345",
  "reviewee": "John Doe",
  "status": "Completed",
  "average_score": 4.33
}

4) Transform Data into a Different Structure

Suppose your reporting system requires a simplified structure:

{
  "review": {
    "id": assessment_id,
    "name": reviewee.name,
    "date": $fromMillis(assessment_date * 1000),
    "scores": {
      "overall": reviewee.overall_score,
      "evaluators": evaluators
    }
  }
}

Result: A nested JSON with formatted date and evaluator details.

5) Use Built-in Functions for Data Processing

Example: Extract evaluator roles into a list

evaluators.role

Result: ["Manager", "Peer", "Self"]

Example: Calculate average evaluator score

$average(evaluators.score)

Result: 4.43

6) Working with Dates and Times

Example: Add a timestamp of when the assessment was processed

{
  "processed_at": $now()
}

Result: Current date-time in ISO format.

Example: Convert assessment date to a readable string

{
  "assessment_date": $fromMillis(assessment_date * 1000)
}

7) Conditional Logic

Example: Generate a feedback message based on overall score

{
  "feedback_message": overall_score >= 4.5 ? "Excellent performance" :
                      overall_score >= 4.0 ? "Good performance" :
                      "Needs improvement"
}

Result: Depending on reviewee.overall_score.

8) Creating Functions for Reusable Logic

Suppose you want to categorize scores:

(
  $scoreCategory := function($score) {
    $score >= 4.5 ? "Excellent" :
    $score >= 4.0 ? "Good" :
    "Needs Improvement"
  };
  {
    "reviewee_category": $scoreCategory(reviewee.overall_score),
    "evaluators": evaluators~>
      $map(function($e) {
        {
          "name": $e.name,
          "role": $e.role,
          "category": $scoreCategory($e.score)
        }
      })
  }
)

Result: Categorized scores for reviewee and evaluators.

9) Sorting and Filtering Data

Example: List evaluators with scores above 4.0

evaluators[$.score > 4.0]

Result: List of evaluators with high scores.

Example: Sort evaluators by score descending

evaluators^(score)

Result: Evaluators ordered from highest to lowest score.

Summary

JSONata offers a flexible way to extract, transform, and analyze data from your assessments. Use it to generate summaries, perform calculations, create conditional reports, and automate data processing tasks.

For more advanced features, consult the JSONata documentation for functions, operators, and best practices.

Need Help?

Feel free to reach out with specific questions or use cases, and we’ll guide you through crafting the right JSONata expressions for your assessment data!

Happy analyzing!