VOC Project

What is a VOC Project

The VOC Project resource is a wrapper for CX dashboards, which correspond to the container resource in a solution. They provide a useful method for users of your solution to access their dashboard, as well as serving as a place to link together multiple dashboards if your solution contains more than one.

CX Dashboards

Only dashboards with vocalize as their type are CX dashboards.

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.

Context

The VOC Project resource will generate one field:

• projectId

The projectId will be your VOC Project's id (VOC_***) and can be accessed with <step.id>.projectId or <step.id>.id.

The VOC Project id will be necessary for linking resources to the project, as well as directing users to the page for that project in a location.

Solution Execution

VOC Project resources are created using a "Create" step.

{
  "id": "vocproject",
  "type": "Create",
  "config": {
    "apiVersion": "vocproject.v0",
    "templateData": {
      "name": "{{ $.setup.answers.title }} - Dashboard"
    },
    "transformationFilePath": "Resources/interpolate.js"
  }
}

The current apiVersion for VOC Project is "vocproject.v0".

VOC Project Resource

Because this resource is so simple, only requiring the name field, you can insert the definition inline using the templateData field. You can still add a file and reference it using the templateFilePath field instead if you like.

Actions

Actions are additional operations you can perform after a resource is created, and there is one associated with the VOC Project resource. To include an action, your solution execution steps might look like this:

[
  // ...
  {
    "id": "vocproject",
    "type": "Create",
    "config": {
      "apiVersion": "vocproject.v0",
      "templateData": {
        "name": "{{ $.setup.answers.title }} - Dashboard"
      },
      "transformationFilePath": "Resources/interpolate.js"
    }
  },
  {
    "id": "link_container",
    "type": "Action",
    "dependencies": ["vocproject", "container"],
    "config": {
      "apiVersion": "vocproject.v0",
      "actionName": "linkresource",
      "templateData": {
        "projectId": "{{ $.vocproject.id }}",
        "resourceId": "{{ $.container.id }}",
        "resourceType": "dashboard"
      },
      "transformationFilePath": "Resources/interpolate.js"
    }
  }
]

Link Resource

The linkresource action links a resource to a VOC Project. Currently, the only supported resourceType is "dashboard", and you can link container resources to the project. The body the action expects is a JSON object with the following fields:

Field	Description	Example
projectId	The id of the VOC Project resource	"projectId": "{{ $.vocproject.id }}"
resourceId	The id of the resource to link	"resourceId": "{{ $.container.id }}"
resourceType	The type of the resource to link	"resourceType": "dashboard"

This action produces no data.

Transformation Syntax

Notice the syntax used to reference resource fields you intend to replace during transformation, such as {{ $.survey.id }}. 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.id). 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.

If you are doing string interpolation as the only transformation on several resources, you can make a single transformation file that calls that function and reuse it for all of those resources. I do that here in this file with the a reference to Resources/interpolate.js.