Skip to main content

Printed Report

What is a Printed Report​

The Printed Report resource defines the widgets that appear in a report, as well as their placement and data input.

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.

It's a lot like the Container resource for dashboards, but this actually includes the direct links to questions in the Survey (rather than relying on a Field Set resource and Source Map resource).

Context​

The Printed Report resource will put the following fields on the context:

  • containerId

Container ids are strings composed of alphanumeric characters (0-9, a-f), like this: 6234a9bbce6cb6000f4fb4ba.

These values can be called with <step.id>.containerId.

Printed Report fields are not typically used for further resource creation.

How to import it into an XM Solution​

Using the XM Solution CLI​

You can import a Printed Report resource along with its associated Survey using the CLI import command as long as the imported Survey is linked to the Printed Report.

Start by running the following command

solution import

Then a project category list should show. Select "basicSurvey" to view all potential Surveys to import:

1. AgileVideoDiscovery
2. BrandTracker
3...
11. basicSurvey
12...

Then a list of all your basic Survey projects will show, and you can select one to import.

1. [basicSurvey] Survey1
2. [basicSurvey] Survey2
3. [basicSurvey] Survey3
4...

Now you should have your Survey project and all of its dependencies downloaded into a src/Resources_**** folder of your solution plugin. This will include any Printed Report resources that are attached to your Survey project.

Solution Execution​

Printed Report resources are created using a "Create" step or updated using an "Update" step in the Solution Execution file.

{
  "id": "printedReport",
  "type": "Create",
  "config": {
    "apiVersion": "printedReport.v0",
    "templateFilePath": "Resources/printedReport.json",
    "transformationFilePath": "Resources/printedReportChanges.js"
  }
},
{
"id": "newPrintedReport",
"type": "Update",
"target": "printedReport.id",
"config": {
"apiVersion": "printedReport.v0",
"templateFilePath": "Resources/printedReport.json",
"transformationFilePath": "Resources/printedReportChanges.js"
},
"dependencies": ["printedReport"]
}

The current apiVersion for Printed Report resources is printedReport.v0.

If you have a template that has a static Printed Report, it will need to be created after your Survey creation step as it does require the Survey ID.

The Printed Report will also need to come after the FSCS Field Set, because it requires the Field Set ID.

Common / Required changes​

Printed Reports have a bit more editing required when compared to Container files. There are a couple of big items you always need to address when creating a Printed Report template:

  • You need to add a field to the file, fieldSetId, which is set to the value of the fscsfieldset.fieldsetId - you can add this right at the top.
  • While you don't need to set the "description" to pull in a value, make sure that it's an appropriate title for reports. You can use the setup.answers.title field from the context to match the user's input when creating the solution.
  • Set the language value to user.language to ensure EN-GB users have the correct language set.
  • Change any instances of the survey ID (SV_****) to pull in survey.surveyId to match our newly created survey.

JavaScript library functions available​

For a Printed Report resource transformation, use the following functions:

  • addFieldset(report, fieldSetId): Add the fieldSetId to the Printed Report.

  • removeWidget(report, widgetId): Remove a widget from the Printed Report.

  • removePage(report, pageId): Remove a page from the Printed Report, and remove all widgets that are on that page.

  • changeSize(report, widgetId, row, col, rowSpan, colSpan): Change the size of a widget. row, col, rowSpan, and colSpan are all in px. row and col specify the position of the top and left side of the widget, respectively. rowSpan and colSpan specify the vertical length and horizontal length of the widget, respectively.