mDIS LogomDIS User Documentation
Home
Table of Contents
Source Code
Home
Table of Contents
Source Code
  • Shell Scripting

Shell Scripting

Developer page

bash Example

Accessing the mDIS REST API with bash

This example uses Unix command line tools:

  • curl to perform web requests, and
  • jq to parse the JSON response from mDIS.

This example uses an mDIS loaded with data from the GRIND project.

Instructions

Put the code block below into a shell script, and make it executable.

#!/bin/bash
#
# list-all-reports.sh - Enumerate all available reports for all models in mDIS
#
# This script first fetches all models from the /cg/api/summary endpoint,
# then calls /api/v1/global/reports for each model to get its available reports.
# 
# Usage:
#   ./list-all-reports.sh [API_TOKEN]
#
# If no token is provided, the script will attempt to extract it from the environment.

set -e

# Default API server
API_SERVER=${API_SERVER:-"http://localhost:8888"}

# Get the API token either from command line or environment
if [ -n "$1" ]; then
  API_TOKEN="$1"
elif [ -n "$API_TOKEN" ]; then
  echo "Using API token from environment"
else
  echo "Error: No API token provided. Please provide a token as an argument or set the API_TOKEN environment variable."
  echo "Usage: $0 [API_TOKEN]"
  exit 1
fi

# Check if jq is installed
if ! command -v jq &> /dev/null; then
  echo "Error: jq is not installed. Please install jq to run this script."
  exit 1
fi

# Create a temporary directory for storing the results
TEMP_DIR=$(mktemp -d)
SUMMARY_FILE="$TEMP_DIR/summary.json"
REPORT_DIR="$TEMP_DIR/reports"
REPORT_OUTPUT="$TEMP_DIR/all_reports.json"
REPORT_CSV="$TEMP_DIR/all_reports.csv"
REPORT_TEXT="$TEMP_DIR/all_reports.txt"

mkdir -p "$REPORT_DIR"

echo "Fetching models from /cg/api/summary..."
curl -sL -H "Authorization: Bearer $API_TOKEN" "$API_SERVER/cg/api/summary" > "$SUMMARY_FILE"

if [ ! -s "$SUMMARY_FILE" ]; then
  echo "Error: Failed to fetch summary data. Check your API token and server."
  exit 1
fi

# Extract all model fullNames
MODELS=$(jq -r '.models[].fullName' "$SUMMARY_FILE" | sort)

# Check if we got any models
if [ -z "$MODELS" ]; then
  echo "Error: No models found in the summary response."
  exit 1
fi

echo "Found $(echo "$MODELS" | wc -l) models."
echo "Fetching reports for each model..."

# Create JSON array and CSV header for the results
echo '[' > "$REPORT_OUTPUT"
echo "Model,TableSet,ReportType,ReportName,ReportTitle,ActionType" > "$REPORT_CSV"
echo "Model | TableSet | ReportType | ReportName | ReportTitle | ActionType" > "$REPORT_TEXT"
echo "------|----------|------------|------------|-------------|------" >> "$REPORT_TEXT"

# Counter for progress
TOTAL_MODELS=$(echo "$MODELS" | wc -l)
COUNTER=0
FIRST_MODEL=true

for MODEL in $MODELS; do
  COUNTER=$((COUNTER + 1))
  echo -ne "Processing model $COUNTER/$TOTAL_MODELS: $MODEL\r"
  
  # Get the module (TableSet) for this model from the summary file
  TABLESET=$(jq -r --arg model "$MODEL" '.models[] | select(.fullName == $model) | .module' "$SUMMARY_FILE")
  
  # Fetch reports for this model
  MODEL_REPORT_FILE="$REPORT_DIR/${MODEL}.json"
  curl -sL -H "Authorization: Bearer $API_TOKEN" "$API_SERVER/api/v1/global/reports?name=$MODEL" > "$MODEL_REPORT_FILE"
  
  # Process both single and multiple reports
  for REPORT_TYPE in single multiple; do
    # Check if the report type exists in the response
    if jq -e ".$REPORT_TYPE" "$MODEL_REPORT_FILE" > /dev/null 2>&1; then
      REPORTS=$(jq -c ".$REPORT_TYPE[]" "$MODEL_REPORT_FILE")
      
      # For each report, add it to our results
      if [ -n "$REPORTS" ]; then
        while IFS= read -r REPORT; do
          # For JSON output
          if [ "$FIRST_MODEL" = "true" ]; then
            FIRST_MODEL=false
          else
            echo "," >> "$REPORT_OUTPUT"
          fi
          
          # Add model name, module (TableSet), and report type to the report JSON
          REPORT_WITH_MODEL=$(echo "$REPORT" | jq --arg model "$MODEL" --arg tableset "$TABLESET" \
            '. + {model: $model, tableset: $tableset, reportType: "'$REPORT_TYPE'"}')
          echo "$REPORT_WITH_MODEL" >> "$REPORT_OUTPUT"
          
          # For CSV output
          REPORT_NAME=$(echo "$REPORT" | jq -r '.name')
          REPORT_TITLE=$(echo "$REPORT" | jq -r '.title')
          REPORT_TYPE_VALUE=$(echo "$REPORT" | jq -r '.type // "unknown"')
          
          echo "$MODEL,$TABLESET,$REPORT_TYPE,$REPORT_NAME,\"$REPORT_TITLE\",$REPORT_TYPE_VALUE" >> "$REPORT_CSV"
          echo "$MODEL | $TABLESET | $REPORT_TYPE | $REPORT_NAME | $REPORT_TITLE | $REPORT_TYPE_VALUE" >> "$REPORT_TEXT"
        done <<< "$REPORTS"
      fi
    fi
  done
done

# Close the JSON array
echo ']' >> "$REPORT_OUTPUT"

echo -e "\nDone! Processed $TOTAL_MODELS models."

# Create the final output files in the current directory
cp "$REPORT_OUTPUT" "./all_reports.json"
cp "$REPORT_CSV" "./all_reports.csv"
cp "$REPORT_TEXT" "./all_reports.txt"

echo "Results saved to:"
echo "  - all_reports.json (JSON format)"
echo "  - all_reports.csv (CSV format)"
echo "  - all_reports.txt (Text table format)"

# Cleanup
rm -rf "$TEMP_DIR"

echo "Summary:"
echo "  - Total models: $TOTAL_MODELS"
echo "  - Total reports: $(( $(wc -l < all_reports.csv) - 1 ))"
echo ""
echo "Top 10 reports by model (partial listing):"
echo "-------------------------------------------"
head -n 11 all_reports.txt

exit 0

To set get an API token, log in to the mDIS web interface, and open the developer console (F12) and get the token from the network tab. It is usually in the header of any request to $API_SERVER/api/v1/....
You can also call the '/api/v1/auth/login' endpoint to get a token from the tiny JSON response. This is the recommended way to get a token.
Then run the shell script:

chmod +x list-all-reports.sh
./list-all-reports.sh <API_TOKEN>

You can also set the API_SERVER environment variable to point to your mDIS instance, and run the script without any arguments. The script will then use the default API server.

The script will create three files in the current directory:

  • all_reports.json - a JSON file with all reports for all models
  • all_reports.csv - a CSV file with all reports for all models
  • all_reports.txt - a text file with all reports for all models

The script will also print a summary of the results to the console, including the total number of models and reports, and a partial listing of the top 10 reports by model.

Developer page

See developer page

REST API

See REST API page for extensive documentation.

More advanced examples

Similar to the code above, see a script showing how to enumerate all standard data input models in mDIS, and then list the reports and actions available for each model.

The mdis-installer git repository had more advanced use cases. There are shell scripts demonstrating how the mDIS REST API can be used for file upload, for example.