Renewed Report Builder: AI Prompt Widget

The AI prompt widget generates personalized content in your reports using OpenAI's GPT models. You write the prompt with your instructions, insert variables from the assessment, and the AI creates custom feedback for each report based on your assessment data.

---

---

This widget is useful when you want to provide dynamic, personalized insights that adapt to each respondent's specific assessment results without writing every possible variation manually.

This guide will teach you how to:

1. Connect your OpenAI API key
2. Add the AI prompt widget to your report 
3. Write your AI prompt with variables 
4. Choose your AI model
5. Test and preview AI-generated content
6. Additional widget settings 

1. Connect your OpenAI API key

Before you can use AI widgets, you need to connect your OpenAI API key at the organizational level.

Navigate to My Account → API & Integrations

In the API & Integrations section, you'll find the AI API area where you can connect to OpenAI.

How to find your OpenAI API key

You’ll need an OpenAI API key. Follow the official instructions here to create or find your key.

Plug in your API key and save changes

Paste your OpenAI API key into the API Key field, then click “Save Changes” before leaving the Integrations & API Settings tab.

2. Add the AI prompt widget to your report

To add the widget to the page, all you have to do is click on it and drag and drop it on the page.

Finding the AI widget:

1. In the Report Builder, click + Add widgets
2. Look for the new AI Widgets group
3. Click the AI prompt widget button

What happens next:

• The widget gets added immediately after you drop it inside the Report Builder
• It opens directly to the widget editor with placeholder greyed-out text that will disappear after clicking on it
• The widget automatically uses the OpenAI integration from account settings with the latest model selected

The simplified toolbar:

The AI prompt widget has a minimal toolbar. Everything has been removed except:

• Variable Selector (X) button to insert assessment variables
• Plain text area with no HTML styling options

This allows you to focus on crafting the perfect prompt while the AI handles the formatting.

3. Write your AI prompt with variables

You can add your AI prompt in the body of the widget. This is where you instruct the AI on what to generate based on the assessment data that you have to select via the variable menu.

Using the Variable Selector:

Click the Variable Selector (X) button to insert variables from your questionnaire. These variables will be replaced with actual respondent data when the AI prompt widget generates content.

Example prompts:

In this example:

• *|total_custom_score|* will be replaced with the respondent's total score
• *|qb1_custom_score|* through *|qb4_custom_score|* will be replaced with their scores in each category
• The AI will generate personalized feedback based on these specific numbers and the assigned tresholds
  
  

In this other example:

• *|q3_response|* will be replaced with the respondent’s answer to the open-ended question.
• The AI prompt widget will generate personalized feedback by:
  • Summarizing the main points of the response.
  • Highlighting any strengths or areas that may need improvement.
  • Providing concise insights or recommendations based on what the respondent shared.

How it works:

1. The AI prompt widget uses assessment data as context
2. Your prompt instructs the AI on what to generate
3. The variables are automatically replaced with the respondent's actual answers
4. The AI generates personalized feedback based on your prompts

Generated output:

• Will be basic text with default HTML styling (bold, italic, paragraphs, etc.)
• Follows the font decided in the Design tab or at the Widget Settings level
• The text will use default HTML formatting for readability

Generated output:

• Will be basic text with default HTML styling (bold, italic, paragraphs, etc.)
• Follows the font decided in the Design tab or at the Widget Settings level
• The text will use default HTML formatting for readability

Design and formatting constraints

What the AI prompt widget can generate:

• Plain text with basic HTML formatting (bold, italic, underline)
• Paragraphs and line breaks
• Bullet points and numbered lists

What the AI prompt widget cannot do:

• Add images or graphics
• Change text colors (text will always be black)

Font customization:

• You can change the font family in the Design tab (applies to entire report)
• You can also set the font at the Widget Settings level (applies only to that widget)

4. Choose your AI model

Each AI prompt widget can use a different OpenAI model. You can select which model to use in the widget settings.

Accessing model settings:

1. Click on your AI widget in the Report Builder
2. Click the Settings on the right side of the screen
3. Select the AI Model section
4. In the dropdown you can select which model you would like to use for the AI prompt widget

Available models:

For guidance on which model to use, see OpenAI’s official documentation: Model Selection and Models overview.

⚠️ Model names, capabilities, availability and pricing may change over time so always check the official OpenAI documentation for the latest information.

Model fallback:

If the selected model is unavailable, the system automatically attempts alternative models following the order shown in the AI model dropdown.

5. Test and preview AI-generated content

Before sending reports to respondents, always test your AI prompts to ensure they generate the content you expect.

Preview your report:

1. Retake your questionnaire so you get a fresh response to use for the AI prompt widget
2. In the Report Builder, click Preview
3. The AI widget will generate content based on that respondent's answers
4. Check if the output matches your expectations

Important notes about testing:

• Each preview generates new AI content, so it may vary slightly between previews
• Test with working variables (with a response taken), not placeholder data, to see realistic results
• If you see output with: "Error: OpenAI API key not configured" verify that your OpenAI integration is configured in My Account → API & Integrations.

5. Additional widget settings

Like all widgets in the Report Builder, the AI prompt widget has standard settings you can configure:

Widget Name

• Give your widget a descriptive name to identify it easily (e.g., "Career Recommendations" or "Leadership Summary")

Conditional logic

• You can add widget logic rules to control when the AI widget appears in reports:
• Click Edit rule in the widget settings
• Set conditions based on scores, or other assessment tresholds
• The AI widget will only appear when your conditions are met

This is useful when you want different AI prompts for different respondent segments.

What's next?

• Renewed Report Builder-PDF step by step example: Check out our step by step guide to create an attractive and stylish PDF. It includes videos but also very detailed instructions.
• Renewed Report Builder-Table: The Table widget allows you to display results clearly and concisely to your respondents. It is an easy and fast way of displaying any data in rows and columns. Rather than writing your data in text, you can make it more understandable and easy to read with this widget.
• Renewed Report Builder-Image widget: This widget allows you to add pictures to your personalized report, to make it more interesting. It can be a great way to keep respondents engaged and break up long blocks of texts or lots of tables. Adding pictures, in some cases, can provide more detail than words and it can be a great way to display information!