Build a Visualization

A Visualization turns the data of a Data Source into a chart, which you then add to your Reports as a Visualization Block.

The Visualization Builder has two steps. First you select your data and the fields that matter, then you select a chart type and describe what to show. Deepwell makes the Visualization, and you review it in a preview.

The procedure

1. Select New Visualization on the Visualizations page.
2. Type a name in the Untitled Visualization field at the top of the Builder.
3. On Select Data, select a test Organization. See How to select an Organization.
4. Select Add Data Source and select a Data Source. This is the data for the chart. To combine data from more than one source, add each one. See Data Sources.
5. Review the data that comes back on the right. If a Test window is shown, set a start and an end in days ago.
6. Select the fields that the chart needs. See Fields.
7. Select Continue to Chart.
8. On Build Chart, select Choose a chart type. See Chart types.
9. Give a description of what to show, for example "tickets opened vs. closed each week". Then select Generate Visualization.
10. Review the preview with your real example data. To make it better, change your description or your fields, then select Regenerate Visualization. Do this again until the preview is correct.
11. Select Publish. The Visualization becomes a Visualization Block that you can add to a Report.

To go back to the first step, select the back arrow, Back to Select Data. Your Data Sources and fields stay as you left them.

Data Sources

Deepwell shows the Add Data Sources section after you select a test Organization. Each Data Source that you add runs immediately, its data appears on the right, and they all run again each time you change the test Organization.

If a run returns no records, the panel reads This run returned no fields. Check that the selected Organization has data for the selected Data Sources in the run window. and Continue to Chart stays unavailable until a run returns data. Select a different test Organization, or review the Data Source. If a request fails, the panel shows Unable to Run Data Sources with the error from the tool.

The Data Sources run in the order of the list, and a Data Source can use a value from the one before it. See How to chain a Data Source. Use the arrows next to a Data Source to move it up or down. If a Data Source reads from the one before it but runs first, Deepwell shows a warning under it: ⟨name⟩ reads a value from the Data Source before it, but it runs first. Move it below the Data Source it reads from. Move it below the one it reads from, and the warning goes away.

The test Organization must be mapped in the system of each Data Source. If it isn't, Deepwell shows This Organization is not mapped to ⟨Integration⟩. Only an MSP Admin can map it on the Org Mapping screen, so ask one to map it, or select a different Organization. See Organizations and Mapped Organizations.

Fields

The panel on the right shows what the Data Sources returned. Select a field on the Fields tab to use it in the chart. Raw Data shows the response as Deepwell received it.

To find a field, type in the Search fields box. Select Include values to search the values as well as the field names, for example to find the field that holds "Critical". Point at a field to see its distinct values and how many records hold each one.

Fields are optional. If you continue with none selected, Deepwell asks Continue without fields? and tells you that it works from the whole response and guesses which fields matter. Select Select Fields to go back, or Continue to go on. A chart with selected fields is more exact, so select them when you can. You can also change your fields later on Build Chart, on the Data Selection tab.

The Test window

The Test window sets the Date Range of the example data only: set a Start and an End in days ago. A Report supplies its own Date Range when it runs, so the Test window doesn't change what your client sees. If the Test window isn't shown, the Data Sources don't use a Date Range.

Build Chart

The second step has a Describe tab, a Data Selection tab, and, after Deepwell makes a chart, a Data Transformation tab.

On Describe, type what to show in the Describe what the chart should show. field, with the fields that you selected listed under it. Until you generate, the preview shows a sample chart of the type you chose, not your data. For a Visualization with one ConnectWise Data Source and selected fields, you can select Examples. Deepwell then shows Example prompts for the chart type that you selected, which change when you select a different one. Select an example to use it as your description.

Data Selection shows the same field panel as the first step, so you can change your fields without going back.

Data Transformation shows the expression that Deepwell wrote to shape your data for the chart. It's view only, but you can copy it, for example to send it to Deepwell support with a question.

If Deepwell can't make the chart, a message in red appears under Generate Visualization. It ends with Adjust the prompt or fields, then try again., and its first part tells you what happened:

• Something went wrong with our system. Please try again or contact support. A fault on Deepwell's side, not in your description. Generate again. If you see it a second time, contact support with your description and the fields that you selected. Something went wrong on our end. means the same.
• AI service is temporarily at capacity. Please try again in a few minutes. Wait a few minutes, then generate again.
• AI service took too long to respond. Please try again. Generate again. A shorter description or fewer fields can help.

Any other message describes a problem in your description or in your fields. Change what it names, then generate again.

Suggestions

After you give a description, Deepwell shows suggestions below it, each one a chip that you select to apply. A word on the chip tells you what it does:

• chart selects a different chart type.
• add adds to your description.
• replace replaces your description.

Point at a chip to see its effect before you select it.

Deepwell does not suggest fields, because it works only from the fields that you selected on Select Data. If a chart needs a field that you did not select, go to the Data Selection tab and add it.

How to select an Organization

The test Organization supplies example data for your design only, because the Visualization that you publish uses the Organization of the Report Schedule that it runs in.

If a Data Source gets data for one client only, you must select an Organization, so Deepwell leaves None out of the Organization control. Until you select one, the panel on the right reads Choose a test Organization to begin.

If no Data Source needs an Organization, the control includes None, and None is correct.

If a run still reaches Deepwell without an Organization it needs, the run shows the message "an organization must be selected for this datasource". Select an Organization and make the Visualization again.

Which Organizations a Visualization works for

A Visualization works only for the clients that are Mapped Organizations in the system of its Data Source, so a Visualization with SentinelOne data fails for a client you didn't map in SentinelOne. Review the mappings of each client before you run a Report for your full list of clients.

Recommendations

• Select the fields that matter before you describe the chart. Deepwell builds the chart from the fields that you selected, and with no fields it guesses, which is more often wrong on a large response.
• Tell Deepwell the exact position of each item. The description "tickets opened vs. closed per week, one line each" gives you two lines on one timeline. A less exact description gives Deepwell more assumptions to make.
• Select the exact field if the words are ambiguous. For example, a ticket has a "status" field, and its assigned technician also has a "status" field, so a description alone can't separate the two. Select the one you mean on Select Data. See Suggestions.
• Make a basic Visualization first, then make it better with small, exact changes. For example, "split into a separate line per status". Do not write the full description again.
• A field that is not available is a Data Source problem. Deepwell can chart only the fields that your Data Source returns, so review your Data Source rather than writing the same request in different words.
• Deepwell knows only what you tell it. It can't infer the data that you don't give it. Give the name of the tool, for example "ConnectWise tickets" and not only "tickets", and give the endpoint URL if you know it. If the data comes on more than one page, tell Deepwell where the pagination is, or your chart can show the first page only. The same recommendations apply to the Data Source.
• Make sure that the data is the data that you want. Before you use the chart, compare the preview with the source tool. Make sure that the counts, the Date Range, and the Organization agree for the same question, because a chart can be correct in its shape but incorrect in its data.

Chart types

Multi-Line Chart: one or more lines across a shared set of values. Use it for a trend in time, for example tickets closed per week, or to compare more than one set of values, for example open tickets per technician.

Bar Chart: compares values across categories, for example the number of tickets for each priority.

Pie Chart: shows the parts of a total, for example the percentage of devices in each status.

Hero Value: one large number, for example the rate of successful backups this month. Use it for a value that a reader sees immediately.

Table: rows and columns of the values themselves, with a label on each column, for example each device with its backup attempts and its failures. Use it when the reader needs the records rather than a shape.

Description

Details, at the top of the Builder, opens a Description field. The description shows on the Visualization's card, so use it to tell your team when to use this chart.

Save your work as a draft

You don't have to finish a Visualization in one sitting. Select Save Draft to save your progress, then leave and come back to it later from the Drafts tab of the Visualizations page. A draft keeps your test Organization, your Data Sources and their order, your fields, your chart type, and your description. When you open it again, Deepwell runs the Data Sources again and opens the step you were on.

If you try to leave with unsaved changes, Deepwell shows an Unsaved changes prompt. Select Save Draft to save and leave, Discard to leave without saving, or Keep Editing to stay.

When you publish, Deepwell asks Publish Visualization? and tells you that "Publishing saves your latest changes, exits the Builder, and makes this Visualization available for Reports. Once published, it can't be edited." You don't need to save first, so review the preview and then select Publish. To change a published Visualization, make a new one.

The Visualizations page

Go to Reporting → Visualizations to control the Visualizations that you saved. The page has three tabs:

• Active shows each published Visualization. These are the Visualization Blocks in the sidebar of the Report builder.
• Drafts shows the Visualizations that you started and didn't publish, which are not available in a Report. Each row shows when you last changed it, and Continue opens one where you left it.
• Archived shows the Visualizations that you archived.

How to archive a Visualization

Archive a Visualization that you no longer want in new Reports by selecting Archive on its card. Deepwell asks you to confirm and tells you that "This visualization will no longer be available when building new Reports. Reports that already use it will continue to run." It then confirms with Visualization Block archived.

An archived Visualization moves to the Archived tab and leaves the sidebar of the Report builder. To put it back, select Restore on the Archived tab, and Deepwell confirms with Visualization Block restored.

What to do next

Publish your Visualization, then add it to a Report. See Build a Report.