Skip to main content

Dashboard

What is a Dashboard​

A Dashboard is a Qualtrics project that incorporates data from Surveys to display graphs, charts, and tables with enhanced reporting functionality like filters.

If you would like to join the early access program for XM Solution Plugins, then please let us know by taking this survey.

Not generally available

This feature is in Early Access and is not yet generally available. Functionality, APIs, and documentation may change before general availability.

The Dashboard itself is collection of widgets that use metrics from data sources to create visualizations that can update in real time as more Survey responses come in. Additionally, Dashboards can integrate data from multiple Survey sources.

A Dashboard needs three different resources in order to function properly: Container, Field Set, and Source Map.

Container​

The Container resource is a JSON file that defines the widgets and pages of a Dashboard for your project. It's similar to the Printed Report resource in structure and layout, but it requires the Field Set and Source Map resources to correctly function.

Field Set​

The Field Set resource is the outline of how all variables are connected from a Source Map to a Dashboard. It is necessary to create a Dashboard. Unlike the Source Map resource, you only need a single Field Set regardless of the number of Surveys you are using in your Dashboard.

Source Map​

Source Map resources are keys that link your Survey resource with your Field Set resource, which then ensures the survey data appears correctly in your Container resource (for your Dashboard). They are created the same way as the Field Set resource, but they require a few additional steps.

Source Map resources can also be used to map other data sources, such as imported data projects.

Context​

Container​

The Container resource will put the following fields on the context:

  • containerId

Container ids are a string composed of alphanumeric characters (0-9,a-f), like this: 6234a9bbce6cb6000f4fb4ba. These values can be called with <container-step.id>.containerId.

Field Set​

The Field Set resource will put the following fields on the context:

  • fieldsetId

Field Set ids are comprised of alphanumeric characters and hyphens (0-9, a-f), like this b87f93fb-6e02-1860-f877-8172f71baf2b. These fields can be called with <fieldset-step.id>.fieldsetId.

The fieldsetId will be needed to create your Container resource correctly, and it will also be needed to create Source Map resources.

Source Map​

The Source Map resource will put the following fields on the context:

  • sourceMapId

The sourceMapId will be your Source Map id, which is a string of alphanumeric characters (0-9, a-f) like this: 11261155AC79B68EEF5477A2A2491656. It can be referenced with <sourcemap-step.id>.sourceMapId.

The id field will concatenate your relevant Field Set id and Source Map id with a | like this: b87f93fb-6e02-1860-f877-8172f71baf2b|11261155AC79B68EEF5477A2A2491656.

This id is needed for your Container resource, and if you have multiple Source Maps you will need to add each sourceMapId to your Container for your Dashboard to function correctly.

How to import all CX Dashboard resources into an XM Solution​

Start by running the following command:

solution import

Then select CXDashboard to view all available CX Dashboard projects.

1. survey
2. CXDashboard
3. EXProject
please select a resource type to begin import [1]: 2

Then a project category list should show. Select vocalize to view all potential CX Dashboards to import.

1. vocalize

Select the project you want to import [number / string] [1]:

Now, a list of all your CX Dashboard projects (also called Vocalize projects) will show, and you can select one to import.

1. [vocalize] TestTranslationAgain - Panel Invite Dashboard
2. [vocalize] dashboard nbame
3. [vocalize] vocproject123 Dashboard 
4. [vocalize] mlm - Panel Invite Dashboard
5. ...

Select the project you want to import [number / string] [1]:

By selecting a Dashboard project to import, not only will the Container, Field Set and Source Map resources be downloaded, all related Surveys, triggers/tasks, and Printed Reports will be downloaded as well to ensure the full project will work as expected.

Now you should have your Dashboard project and all of its dependencies downloaded into a src/Resources_**** folder in your solution plugin's src folder.

How to import an EX Dashboard resource into an XM Solution​

You can import EX Dashboard resources along with other associated EX Project resources using the CLI import command.

To do this, follow these directions to import an EX Project.

Now you should have your EX Project and all of its dependencies downloaded into a src/Resources_**** folder of your solution plugin. This will include any EX Dashboard resources if the EX Project has a Dashboard.

Solution Execution​

Container, Field Set and Source Map resources are created using a "Create" step or updated using an "Update" step in the Solution Execution file.

[
  {
    "id": "dashboardContainer",
    "type": "Create",
    "config": {
      "apiVersion": "container.v0",
      "templateFilePath": "Resources/dashboardContainer.json",
      "transformationFilePath": "Resources/dashboardContainerChanges.js"
    }
  },
  {
    "id": "newDashboardContainer",
    "type": "Update",
    "target": "dashboardContainer.id",
    "config": {
      "apiVersion": "container.v0",
      "templateFilePath": "Resources/dashboardContainer.json",
      "transformationFilePath": "Resources/dashboardContainerChanges.js"
    },
    "dependencies": [
      "dashboardContainer"
    ]
  }
]
[
  {
    "id": "fieldset",
    "type": "Create",
    "config": {
      "apiVersion": "fieldset.v0",
      "templateFilePath": "Resources/fieldset.json",
      "transformationFilePath": "Resources/fieldsetChanges.js"
    }
  },
  {
    "id": "newFieldset",
    "type": "Update",
    "target": "fieldset.id",
    "config": {
      "apiVersion": "fieldset.v0",
      "templateFilePath": "Resources/fieldset.json",
      "transformationFilePath": "Resources/fieldsetChanges.js"
    },
    "dependencies": [
      "fieldset"
    ]
  }
]
[
  {
    "id": "sourcemap",
    "type": "Create",
    "config": {
      "apiVersion": "sourcemap.v0",
      "templateFilePath": "Resources/sourcemap.json",
      "transformationFilePath": "Resources/sourcemapChanges.js"
    }
  },
  {
    "id": "newSourcemap",
    "type": "Update",
    "target": "sourcemap.id",
    "config": {
      "apiVersion": "sourcemap.v0",
      "templateFilePath": "Resources/sourcemap.json",
      "transformationFilePath": "Resources/sourcemapChanges.js"
    },
    "dependencies": [
      "sourcemap"
    ]
  }
]

Note that if your Dashboard is a part of an EX Project, your Source Map and Container steps' dependencies fields must also contain the EX Project step.

The current apiVersion for these three resources are "container.v0", "fieldset.v0" and "sourcemap.v0".

Common / Required changes​

Container Editing​

  • Update container.fieldSetId to <fieldset-step.id>.fieldsetId to ensure it aligns with your Field Set resource
  • Update container.description field to ensure the name matches the project with the context's setup.answers.title. This will be the name that appears for the project in the My Projects page.
  • If this Container is part of an EX Project, update container.contextMeta.primarySourceMapId to <sourcemap-step>.id.
  • If this Container is part of an EX Project, update container.contextMeta.projectId to <EXProject-step.id>.id to ensure it aligns with your EX Project resource.
{
  "container": {
    "_id": "605a1287a2b8e1001041d513",
    "fieldSetId": "{{$.fieldset.fieldsetId}}",
    "description": "{{$.setup.answers.title}} Dashboard",
    "containerType": "dashboard",
    "product": "vocalize",
    "language": "EN",
    "creationDate": "2021-03-23T16:08:39.254Z",
    "lastModifiedDate": "2021-03-23T16:08:39.254Z"
    //...
  }
}

The Field Set and Source Map will handle the needs for data input.

Fieldset Editing​

Surveys​

For every Survey included in this Dashboard's Field Set, you need to replace the original Survey ID with the key as it was established in the Solution Execution file.

The sources can be found in an array at fieldset.sources.

{
  "name": "New Normal: Readiness | Parents/Family",
  "sources": [
    {
      "id": "{{$.survey1.surveyId}}",
      "type": "survey"
    },
    {
      "id": "{{$.survey2.surveyId}}",
      "type": "survey"
    },
    {
      "id": "{{$.survey3.surveyId}}",
      "type": "survey"
    }
  ],
  "permissionedFields": {
    "sensitiveFields": []
  },
  "scales": {}
  //...
}

Additionally, if this Field Set is a part of an EX Project, make sure you replace the value of sources.projectId with "{{ $.EXProject.id }}", replace the value of sources.sourceResponseSetId with "{{ $.survey.responseSetId }}", and delete the metaFields object.

Field Set​

If the Field Set contains the original fieldSetId, you MUST remove this or the project will fail.

{
  "contextMeta": {
    "name": "Name of the dashboard",
    "defaultLang": "EN",
    "lastSave": "1599762536201"
  }
  // ...
}

Source Map Editing​

Structure​

Each Source Map file should have this structure:

{
  "mapping": {
    //...
  },
  "responseSetId": "{{$.survey.responseSetId}}",
  "sourceId": "{{$.survey.surveyId}}",
  "fieldSetId": "{{$.fieldset.fieldsetId}}",
  "sourceName": "{{$.setup.answers.title}}",
  "sourceType": "survey"
}

The "mapping" section will contain all of your questions and embedded data fields as they relate to both your Survey and the Field Set.

You need to add the "fieldSetId" element after the sourceId at the end of the file, as well as set each of the elements as shown above. You MUST also remove the element named sourceMapId, as this will be automatically added on transformation with the resource's new id.

If your Dashboard includes multiple Surveys, or if the Survey name should be distinct from the project name, you can keep the original Survey title as a String for the value of sourceName.

Transformation Syntax

Notice the syntax used to reference resource fields you intend to replace during transformation, such as {{$.survey.responseSetId}}. This bracket notation should be stripped out during the transformation step and replaced with a real value that would exist on the context at that time (in this case, context.survey.responseSetId). The best way to do this is to run the interpolate function on each resource in its corresponding transformation file. This function is available as a part of the @qualtrics/solution-utils package.

JavaScript library functions available​

Container​

For a Container resource transformation, use the following functions:

  • addFieldset(container, fieldSetId): Add the fieldSetId to the Container.

  • changeName(container, newName): Change the Container name. This will change the name that appears on the My Projects page.

  • removeWidget(container, widgetID): Remove a widget from the Container.

  • removePage(container, pageID): Remove a page from the Container, and remove all widgets that are on that page.

Field Set​

For a Field Set resource transformation, use the following functions:

  • removeFieldsetID(fieldset): Remove any existing fieldSetId fields to avoid errors when creating.

  • updateSurvey(fieldset, oldSurvey, newSurvey): Replace an old survey id in sources with a new one. If you are creating a new Survey you can use that Survey id with <survey-step.id>.surveyId.

  • changeName(fieldset, newName): Change the Field Set name. This name should be the same as your Container's name.

  • removeField(fieldset, fieldID): Remove a field from the Field Set. This could be a question ID from a Survey or an embedded data field name, like QID9_TEXT, QID1_NPS_GROUP, or ConsiderProduct. If you remove a field, make sure you remove that same field from all Source Maps as well.

Source Map​

For a Source Map resource transformation, use the following functions:

  • addFieldset(sourcemap, fieldSetId): Add the fieldSetId to the Source Map.

  • removeSourcemapID(sourcemap): Remove any existing sourceMapId fields to avoid errors when creating.

  • changeName(sourcemap, newName): Change the Source Map's name. This name should be the same as the Survey it is connected to.

  • removeMapping(sourcemap, mapID): Remove a mapping from the Source Map. This will be the same as a field in the Field Set, and it could be a question ID from a Survey or an embedded data field name, like QID9_TEXT, QID1_NPS_GROUP, or ConsiderProduct.