Create surveys in your portal

This guide is designed to help you implement and manage a complete survey experience within your organization using Port.

With surveys, you can collect structured feedback, track user responses, and visualize the results in a custom dashboard.
In this guide, we will build the core components:

Blueprints for surveys, questions, and responses.
A webhook datasource to capture survey data.
A self-service action for survey participation.
A dashboard to monitor survey metrics.

Prerequisites

Complete the onboarding process.
Admin access to your Port environment.

Set up the data model

First, let's create the necessary blueprints to store survey data.
We will create several blueprints: Survey Template, Survey, Question, Question Template, and Response.

Survey template blueprint

Navigate to your Port Builder page.
Click the + Blueprint button to create a new blueprint.
Click on the Edit JSON button.

Copy the definition below and paste it in the editor:

Survey Template blueprint (click to expand)

{
  "identifier": "survey_template",
  "title": "Survey Template",
  "icon": "GroupBy",
  "schema": {
    "properties": {
      "description": {
        "type": "string",
        "title": "Description"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {}
}

Survey blueprint

Create a blueprint for survey:

Survey blueprint (click to expand)

{
  "identifier": "survey",
  "title": "Survey",
  "icon": "Bar",
  "schema": {
    "properties": {
      "description": {
        "type": "string",
        "title": "Description",
        "format": "markdown"
      },
      "version": {
        "icon": "DefaultProperty",
        "type": "string",
        "title": "Version"
      },
      "start_date": {
        "type": "string",
        "title": "Start date",
        "format": "date-time"
      },
      "end_date": {
        "type": "string",
        "title": "End date",
        "format": "date-time"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "survey_template": {
      "title": "Survey Template",
      "target": "survey_template",
      "required": false,
      "many": false
    }
  }
}

Question template blueprint

Create a blueprint for question templates:

Question Template blueprint (click to expand)

{
  "identifier": "question_template",
  "title": "Question Template",
  "icon": "Template",
  "schema": {
    "properties": {
      "numeric_question": {
        "type": "boolean",
        "title": "Numeric Question"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "survey_template": {
      "title": "Survey Template",
      "target": "survey_template",
      "required": false,
      "many": false
    }
  }
}

Question blueprint

Create another blueprint for survey questions:

Question blueprint (click to expand)

{
  "identifier": "question",
  "title": "Question",
  "icon": "Bulb",
  "schema": {
    "properties": {
      "numeric_question": {
        "type": "boolean",
        "title": "Numeric Question"
      }
    },
    "required": [
      "numeric_question"
    ]
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "question_template": {
      "title": "Question Template",
      "target": "question_template",
      "required": false,
      "many": false
    },
    "survey": {
      "title": "Survey",
      "target": "survey",
      "required": false,
      "many": false
    }
  }
}

Response blueprint

Finally, create a blueprint for survey responses:

Response blueprint (click to expand)

{
  "identifier": "response",
  "title": "Response",
  "icon": "Register",
  "schema": {
    "properties": {
      "value": {
        "icon": "DefaultProperty",
        "type": "string",
        "title": "Answer"
      }
    },
    "required": []
  },
  "mirrorProperties": {
    "team": {
      "title": "Team",
      "path": "user.$team.$identifier"
    },
    "question_template_identifier": {
      "title": "Question Template Identifier",
      "path": "question.question_template.$identifier"
    },
    "survey_title": {
      "title": "Survey Title",
      "path": "question.survey.$title"
    }
  },
  "calculationProperties": {
    "numeric_value": {
      "title": "Numeric Value",
      "icon": "DefaultProperty",
      "calculation": ".properties.value | (tonumber // null)",
      "type": "number"
    }
  },
  "aggregationProperties": {},
  "relations": {
    "user": {
      "title": "User",
      "target": "_user",
      "required": false,
      "many": false
    },
    "current_team": {
      "title": "Current Team",
      "target": "_team",
      "required": false,
      "many": true
    },
    "question": {
      "title": "Question",
      "target": "question",
      "required": false,
      "many": false
    }
  }
}

Add calculation and aggregation properties

Now that we have our basic blueprints set up, let's add calculation and aggregation properties to enable advanced metrics and analytics for our surveys.

Add score tracking to question template

Go to the builder page, find and expand the Question Template blueprint.

Click on the ... button and select Edit blueprint, then click on the Edit JSON button.

Let's add a calculation property to create a scorecard based on average scores.
Under the calculationProperties key, paste the following JSON:

"calculationProperties": {
  "avg_score_scorecard": {
    "title": "Score Standards",
    "icon": "DefaultProperty",
    "calculation": "if (.properties.avg_score == null) then null else if (.properties.avg_score < 3) then \"low\" elif (.properties.avg_score <= 4) then \"medium\" else \"high\" end end",
    "type": "string",
    "colorized": true,
    "colors": {
      "low": "red",
      "medium": "yellow",
      "high": "green"
    }
  }
}

This calculation property creates a color-coded scorecard that categorizes average scores into three levels:

Low (red): scores below 3
Medium (yellow): scores between 3 and 4
High (green): scores above 4

Let's add an aggregation property to calculate the average score from responses.
Under the aggregationProperties key, paste the following JSON:

"aggregationProperties": {
  "avg_score": {
    "title": "Avg. Score",
    "type": "number",
    "target": "response",
    "calculationSpec": {
      "func": "average",
      "averageOf": "total",
      "property": "numeric_value",
      "calculationBy": "property",
      "measureTimeBy": "$createdAt"
    }
  }
}

This aggregation property:

Calculates the average of all numeric responses
Uses the numeric_value from responses
Updates in real-time as new responses are submitted

Add score tracking to question

Go to the builder page, find and expand the Question blueprint.

Click on the ... button and select Edit blueprint, then click on the Edit JSON button.

Under the calculationProperties key, paste the following JSON:

"calculationProperties": {
  "avg_score_scorecard": {
    "title": "Score Standards",
    "icon": "DefaultProperty",
    "calculation": "if (.properties.avg_score == null) then null else if (.properties.avg_score < 3) then \"low\" elif (.properties.avg_score <= 4) then \"medium\" else \"high\" end end",
    "type": "string",
    "colorized": true,
    "colors": {
      "low": "red",
      "medium": "yellow",
      "high": "green"
    }
  }
}

Under the aggregationProperties key, paste the following JSON:

"aggregationProperties": {
  "avg_score": {
    "title": "Avg. Score",
    "icon": "DefaultProperty",
    "type": "number",
    "target": "response",
    "calculationSpec": {
      "func": "average",
      "averageOf": "total",
      "property": "numeric_value",
      "calculationBy": "property",
      "measureTimeBy": "$createdAt"
    }
  }
}

Add mirror properties to response

Go to the builder page, find and expand the Response blueprint.

Click on the ... button and select Edit blueprint, then click on the Edit JSON button.

Under the mirrorProperties key, paste the following JSON:

"mirrorProperties": {
  "avg_score": {
    "title": "Avg Score",
    "path": "question.avg_score"
  }
}

This mirror property allows responses to reflect the average score from their related questions, providing easy access to this metric at the response level.

Create a webhook datasource

To capture survey responses, let's set up a webhook datasource:

Go to the Data Sources page of your portal.
Click + Data Source.
Select Webhook.
Select Custom Integration.
Title it Calculate Survey Response.

Configure the webhook with the following mapping:

Webhook configuration (click to expand)

[
  {
    "blueprint": "survey_template",
    "operation": "create",
    "filter": "true",
    "entity": {
      "identifier": ".body.port_context.actionId",
      "title": ".body.port_context.actionId"
    }
  },
  {
    "blueprint": "survey",
    "operation": "create",
    "filter": "true",
    "entity": {
      "identifier": "[(.body.port_context.actionId | ascii_downcase | gsub(\" \"; \"_\")), (.body.port_context.version | ascii_downcase | gsub(\" \"; \"_\"))] | join(\"_\")",
      "title": "[.body.port_context.actionId, .body.port_context.version] | join(\" \")",
      "properties": {
        "version": ".body.port_context.version"
      },
      "relations": {
        "survey_template": ".body.port_context.actionId"
      }
    }
  },
  {
    "blueprint": "question",
    "operation": "create",
    "itemsToParse": ".body.responses",
    "entity": {
      "identifier": "[.item.key,(.body.port_context.actionId | ascii_downcase | gsub(\" \"; \"_\")), (.body.port_context.version | ascii_downcase | gsub(\" \"; \"_\"))] | join (\"_\")",
      "title": "[.item.key,(.body.port_context.actionId | ascii_downcase | gsub(\" \"; \"_\")), (.body.port_context.version | ascii_downcase | gsub(\" \"; \"_\"))] | join (\"_\")",
      "properties": {
        "numeric_question": ".item.value | type == \"number\""
      },
      "relations": {
        "question_template": ".item.key",
        "survey": "[(.body.port_context.actionId | ascii_downcase | gsub(\" \"; \"_\")), (.body.port_context.version | ascii_downcase | gsub(\" \"; \"_\"))] | join(\"_\")"
      }
    }
  },
  {
    "blueprint": "question_template",
    "operation": "create",
    "itemsToParse": ".body.responses",
    "entity": {
      "identifier": ".item.key",
      "title": ".item.key",
      "properties": {
        "numeric_question": ".item.value | type == \"number\""
      },
      "relations": {
        "survey_template": "(.body.port_context.actionId | ascii_downcase | gsub(\" \"; \"_\"))"
      }
    }
  },
  {
    "blueprint": "response",
    "operation": "create",
    "itemsToParse": ".body.responses",
    "entity": {
      "identifier": "[.headers.run_id, .item.key, .item.value] | join(\"_\") | gsub(\" |/|,|\\\\.|\\\\(|\\\\)\"; \"\")",
      "title": "[.headers.run_id, .item.key, .item.value] | join(\" \") | gsub(\" |/|,|\\\\.|\\\\(|\\\\)\"; \"\")",
      "properties": {
        "value": ".item.value"
      },
      "relations": {
        "question": "[.item.key,(.body.port_context.actionId | ascii_downcase | gsub(\" \"; \"_\")), (.body.port_context.version | ascii_downcase | gsub(\" \"; \"_\"))] | join (\"_\")",
        "user": ".body.port_context.user",
        "current_team": ".body.port_context.teams"
      }
    }
  }
]

Webhook URL

Make sure to copy and save the webhook URL - you'll need it when configuring the survey action in the next section.

Understanding survey versions

The version property in the survey configuration enables you to run the same survey multiple times and track responses over time. This is particularly useful for:

Running periodic surveys (e.g., quarterly developer satisfaction surveys).
Comparing results across different time periods.
Tracking trends and improvements.

When you create a new instance of a survey:

The survey template remains the same.
A new survey entity is created with a unique version (e.g., "Q1 2024", "Q2 2024").
All responses are linked to this specific version.
The aggregation properties will show metrics both per version and across all versions.

For example, you can:

Compare average scores between Q1 and Q2.
Track improvement trends over multiple quarters.
View combined statistics across all versions of the survey.

The distinction between Question Templates and Questions is similar:

Question Templates define the base structure of questions that can be reused across different survey versions.
Questions are specific instances of these templates, linked to a particular survey version.
This allows you to track responses to the same question across different survey versions while maintaining the connection to the original template.

tip

Use a consistent versioning format (e.g., "Q1 2024", "Q2 2024") to make it easier to organize and compare survey results.

Set up a survey action

Below are various examples of survey actions, covering common use cases.
You can use these examples for your own survey actions, or modify them to fit your specific needs.

To create a survey action in your portal:

Go to the self-service page.
Click + Action button to create a new action.
Click on the Edit JSON button.
Copy the definition of the relevant survey action and paste it in the editor: