Tutorial - Create a Layer Report Using the Blank Report Template

If you have never created and run a VertiGIS Studio report before, you may want to start with the quick steps given in the Get Started section. In the Get Started tutorial, you use the Layer Report template to create a layer report and then you preview the report.

The Blank Report template creates an empty report. This allows you to create a report from scratch.

This tutorial uses the Blank Report template to create a layer report from scratch and make it available to end users. When you are finished the tutorial, you will be able to run the report in a ArcGIS Web AppBuilder app or a Geocortex HTML5 viewer.

The data source in this report is a public ArcGIS Online map service with a layer called Shelters. The purpose of the report is to find local emergency shelters that are open. Because it is a layer report, the report takes one or more feature IDs as input. These are the IDs of the shelters that are in the user's local area. The user selects the local shelters in the host application and then runs the report. The generated report includes only those shelters that the user selected.

The tutorial provides instructions for configuring Web AppBuilder in Portal for ArcGIS, Web AppBuilder (Developer Edition), and the Geocortex Viewer for HTML5 to host the report. It also provides instructions for making the report accessible by the public. When you have finished the tutorial, you will be able to run the report in the host applications.

Before you Begin

can run in two environments—in the cloud or on premises. To do this tutorial, you must have an ArcGIS identity that gives you access to one of these environments.

Main Steps to Create a Report from the Blank Report Template

The main steps to create a report from the Blank Report template and run the report are as follows:

Step 1: Create a new report from the Blank Report template

Step 2: Save the report

Step 3: Configure the data source

Step 4: Add the data source to the report

Step 5: Configure a report parameter

Step 6: Add filter conditions to the query

Step 7: Add data to the report

Step 8: Add other content to the report

Step 9: Save the completed report

Step 10: Preview the report

Step 11: Share the report

Step 12: Configure an application to host the report

Step 13: Run the report in the host application

Step 1: Create a new report from the Blank Report template

  1. Open VertiGIS Studio Report Designer.

    If you are using VertiGIS Studio Reporting in the cloud, you can access Report Designer here.

  2. Click Blank Report.

    Report Designer opens a new, blank report.

    New, blank report in VertiGIS Studio Report Designer

Step 2: Save the report

  1. Press Ctrl+S.

  2. Type the report's name: Shelters

  3. Click Save.

Step 3: Configure the data source

In this step, you will configure the connection information for the ArcGIS map server that will provide the data for the report. You will select the layer that you want to use in a later step.

You only need to configure a data source's connection information once. After you have configured the connection information for a particular data source, you can use it in any report that you author.

  1. In Report Designer's sidebar, click Data Sources.

  2. Click Add Data Source and select ArcGIS.

  3. In the Name box, type: Shelters

  4. In the Service URL box, type or paste: http://sampleserver5.arcgisonline.com/arcgis/rest/services/NapervilleShelters/MapServer

    If the data source was secured, you would also configure the username and password for VertiGIS Studio Reporting to use to access the server. You can also configure other parameters to include in the connection string. Click Add Parameter to configure the username, password, and other parameters.

  5. Click Test to try connecting to the server using the connection information you have configured.

    If the connection fails, verify the connection information that you have configured.

  6. Click Save.

  7. Click away from the Data Sources panel to close the panel.

Step 4: Add the data source to the report

In the previous step, you configured the map service's connection information. In this step, you will configure the new report to access the map service from within the report. As part of this step, you will specify which layers and fields you want to use in the report. This defines one part of the query that will get the report's data from the map service.

  1. Click Add SQL Data Source to open the SQL Data Source Wizard.

    Location of Add SQL Data Source tool

  2. Select Shelters and click Next.

  3. Click the arrow to expand Tables.

    This shows the data tables for the map service's layers. The Shelters service has one table.

    Layer in the ArcGIS map service

  4. Click the arrow to expand Shelters.

    This shows the table's columns, which correspond to the layer's attributes.

  5. Select the checkbox for each attribute that you want to be available to add to the report:

    • objectid
    • facname
    • sheltcap
    • sheltcurpop
    • petfriend
    • wheelchair

    These are the attributes that will be returned when the layer is queried.

    Shelters layer with attributes selected

  6. Click Finish to close the wizard.

Step 5: Configure a report parameter

Report parameters allow you to pass data into a report at run time. The report in this tutorial will have a single parameter that takes one or more feature IDs from the Shelters layer as its value. When you preview the report in Report Designer, you will be prompted to enter the feature IDs. When a user runs the report in a host application, the feature IDs are provided through a search, query, or identify operation.

It is worthwhile creating a new report's parameters right away so they are available to use in expressions when you design the report.

  1. In the Field List , click Parameters to show the management buttons.

  2. Click Add Parameter .

  3. Click Edit .

  4. In the Name box, type the following name for the parameter: FeatureIds

    The report parameter must be called FeatureIds.

  5. In the Description box, type a description of the parameter, for example: Object IDs of one or more shelters

  6. Select the MultiValue checkbox.

    Multi-value parameters can take more than one value as inputs. If the MultiValue checkbox is cleared, the report can only include one record. In this report, we want to be able to include multiple shelters in the report.

  7. Select Number (32 bit integer) from the Type drop-down list.

    Esri feature IDs are 32-bit integers.

  8. Configure a default feature ID for the Preview function to use.

    In a production environment, layer reports operate on the features that are currently selected by the user. When you preview a layer report in Report Designer, there is no selection set to operate on, so the Preview function prompts you to enter feature IDs. You can also configure default feature IDs for the Preview function to use.

    1. Use the Shelters layer's service directory to query the layer for the objectid field (Out Fields: objectid) of all the records (Where: 1=1).

      Object IDs in the map service can change, so you cannot depend on being able to use the object IDs shown in this tutorial. The tutorial uses object IDs 220830 - 220833.

      Results of querying the layer, showing values of the objectid field

    2. In the Field List , click Value to show the plus sign, and then click the plus sign. Enter the feature ID that you chose to be the default value.

      Default feature ID configured for a report parameter

  9. Keep the Field List open for the next step.

Step 6: Add filter conditions to the query

In this step, you will define a filter expression to filter the query results. You want the query to return open shelters whose feature ID matches one of the IDs passed into the report at run time. The filter expression has two conditions:

  1. In the Field List , click Shelters to show the management buttons.

  2. Click Edit Query to open the SQL Data Source Wizard.

  3. Click Run Query Builder.

  4. In the Query Properties panel, click the icon in the Filter box to open the Filter Editor.

    There are two ways to configure a filter expression using the Filter Editor:

    • Advanced Mode: Advanced Mode allows you to type in the filter expression. To show the editing area for Advanced Mode, select the Advanced Mode checkbox.

      The syntax to use feature attributes in an expression is [layer.attribute]. For example, to access the objectid attribute of the current feature from the Shelters layer, you would use [Shelters.objectid].

    • Default Mode: The default mode allows you to define the filter expression as a hierarchy of conditions grouped by operators. The Filter Editor offers auto complete suggestions so you can select attributes, properties, and parameters, instead of having to type them in.

      Initially, the expression consists of a single operator: . Hovering the pointer to the right of the operator shows the plus icon that you click to add groups (operators) and conditions.

      Example of an operator that groups three conditions

  5. Add the filter conditions using the Advanced Mode or Default Mode:

    Advanced Mode:

    1. Select the Advanced Mode checkbox.

    2. Type or paste the following filter expression in the box: [Shelters.sheltstat] = 1 And [Shelters.objectid] In(?idsFromUser)

      You can use the == operator instead of the = operator:

      [Shelters.sheltstat] == 1 And [Shelters.objectid] In(?idsFromUser)

    Default Mode:

    1. Add the condition for open shelters:

      1. Hover the pointer to the right of the And operator to show the plus icon .

      2. Click the plus icon and select Add condition.

        New condition, ready to be configured

      3. Click the blue box, click the arrow to expand the Shelters layer, and select sheltstat.

        Shelters.sheltstat appears in the blue box.

      4. Click the gray Enter a value box to make it editable and type 1.

      5. Click away from the condition.

        The filter expression will look like this:

    2. Add the condition to match the feature ID:

      1. Click the plus icon beside the And operator and add another condition.

      2. Click the blue box, expand Shelters, and select objectid.

        Shelters.objectid appears in the blue box.

      3. Click the green box and select Is any of.

      4. Click the arrow in the gray Enter a value box and select Parameter.

        The box turns yellow and displays Create new parameter.

      5. Click the yellow box and select Create new parameter to create a new query parameter.

      6. Type the following name for the parameter: idsFromUser

      7. Click away from the condition.

        The filter expression looks like this in the default mode:

      8. Select the Advanced Mode checkbox and type the parameter name idsFromUser after the question mark in the In term.

        The expression should look like this:

  6. Click OK.

    The filter expression appears in the Filter box in the Query Properties panel.

    Do not attempt to preview the results yet. The filter expression includes a query parameter that does not yet have a value, so the query will fail.

  7. Click OK to close the Query Builder.

  8. Click Next.

  9. Click the arrow to expand the IdsFromUser query parameter.

  10. Set Type to Expression.

    A setting for the result type appears.

  11. Make sure Result Type is set to Number (32 bit integer).

  12. Click the icon in the Value box to open the Expression Editor.

    Initially, the expression is 0.

  13. Delete the expression.

  14. Click the arrow to expand Parameters.

    These are report parameters.

  15. Double-click the FeatureIds parameter, shown at in the screen capture below.

    The Expression Editor will build the expression and display it, shown at . The expression is [Parameters.FeatureIds].

    Expression that accesses the FeatureIds report parameter

  16. Click OK.

    Report parameter FeatureIds bound to query parameter idsFromUser

  17. Click Finish to close the SQL Data Source Wizard.

  18. Keep the Field List open for the next step.

Step 7: Add data to the report

In this step, you will specify where in the report to present the data and how to format it.

You will add the data to the Detail1 band. Detail bands like Detail1 are used to show data from a data source, in this case, feature attributes. When a user runs the report, each field in a detail band is repeated once for each record in the report.

  1. In the Field List , click the arrow to expand Shelters.

    This shows the attributes that you selected when you added the data source to the report.

    Attributes in the Shelters layer that are available to add to the report

  2. Drag the bottom edge of the Detail1 band toward the BottomMargin1 band to increase the size of the Detail1 band.

  3. Drag each field in turn from the Field List panel and drop it on the Detail1 band.

  4. Arrange the fields as shown in the screen capture.

    To move an item on the design surface, drag it to its new location.

  5. Format the facname field:

    1. Click Properties, expand Appearance, and then expand Font.

    2. Double-click the facname field on the design surface to select the contents.

    3. In the Font section of the Properties panel, set the font size to 11 and click the Bold icon to make it bold.

    4. Increase the size of the facname field so the facility names will fit on one line. To change the size of a control on the design surface, click the control and drag one of the control's handles.

      Control with draggable handles

    5. Click away from the facname field to see the formatting.

  6. Add labels for the four bottom fields:

    1. Drag an XRLabel control to the design surface once for each of the four indented fields. Position the labels to the left of the fields.

    2. Change the contents of the labels to say Capacity:, Current occupancy:, Wheelchair access:, and Pets allowed:. To edit a label, double-click the label on the design surface and then type your text.

    3. Increase the size of the Current occupancy: and Wheelchair access: labels so the text fits on one line.

    Instead of using a separate Label control to label a field, you can concatenate the label to the field using the + operator in the Label control's Expression setting, for example, 'Capacity: ' + [sheltcap]. This method does not align the labels and fields in columns. For more information, see Expressions.

  7. Keep the Properties panel open for the next step.

Step 8: Add other content to the report

In this step, you will add a report header band to the report and add a title to it.

  1. In the Properties panel, expand Actions and click Insert Report Header Band .

    A new band called ReportHeader1 appears between the TopMargin1 and Detail1 bands.

  2. Drag an XRLabel control to the ReportHeader1 band.

  3. Double-click the label on the design surface and enter the following title: Local Shelters

  4. Increase the title's font size to 18 and make it bold.

  5. Reduce the height of the ReportHeader1 band.

Step 9: Save the completed report

  1. Press Ctrl+S to save the report.

Step 10: Preview the report

Report Designer's Preview function allows you to run the report without having to configure a host application. The Preview function provides a quick way to test your reports while you are designing them. In the preview, reports that take inputs from the user prompt the user for the input values. This is different from running a report in a host application. Instead of prompting the user, host applications use the currently selected features as inputs.

To preview a , your browser must allow pop-ups from apps.vertigisstudio.com (cloud ) or from your domain (on-premises ).

  1. Click Preview .

    You are prompted to enter shelter IDs. The default ID is already entered.

    To preview a , your browser must allow pop-ups from apps.vertigisstudio.com (cloud ) or from your domain (on-premises ).

  2. Add the other feature IDs that you chose.

    To add a feature ID, click in the FeatureIds box, type the ID, and then press Tab or Enter.

  3. Click OK.

    The report generates and then opens as a PDF in a separate browser tab.

    Note that the report will only include the records that satisfy the query's filter conditions. For example, the screen capture of the previewed report shows only three of the four features that were specified in the Preview prompt. This is because one of the features (220832) was filtered out by the [Shelters.sheltstat] = 1 condition.

    Report preview

    Now that you can see the report's output, you may want to return to Report Designer and modify the report's formatting or content. As a report author, you will typically create a first draft of the report, preview it, make some improvements, preview it again, and so on, until you are satisfied with the result.

Step 11: Share the report

When you first save a report, only you have access to the report. You can share reports with groups that you belong to, with your entire organization, or with everyone (including the public). In this tutorial, for simplicity, you will share the report with everyone.

Normally, you have to share the host app in addition to the report. You do not need to share the host app in the context of this tutorial because no-one else besides you will run the app.

To share a report, you share the report item in ArcGIS. In some Web AppBuilder scenarios, you also have to share the VertiGIS Studio Reporting widget that runs the report.

Normally, we do not recommend sharing reports with everyone unless the application is public and you want to allow anyone to run the report.

  1. Sign in to your ArcGIS account.

    You can open your ArcGIS account from Report Designer. Click Info | View to open ArcGIS at the details page for the report that is currently active in Report Designer.

  2. Share the report item:

    1. Go to your Content area.

    2. Open the report item's details.

    3. Click Share.

    4. Select the Everyone (public) checkbox.

    5. Click OK.

  3. If you are running Web AppBuilder in Portal for ArcGIS 10.6+, share the widget item.

    This allows anonymous users to run the report.

    1. Go to your Content area.

    2. Open the widget item's details.

    3. Click Share.

    4. Select the Everyone (public) checkbox.

    5. Click OK.

Step 12: Configure an application to host the report

VertiGIS Studio reports run in host applications. You can use ArcGIS Web AppBuilder or the Geocortex Viewer for HTML5 to host reports.

Follow the instructions to configure a host application:

Configure a Web AppBuilder app

In this step, you will create a new 2D app, add the report widget to the app, and configure the widget to run your report.

This step assumes that you have already registered the 2D Reporting widget. For information, see Register the VertiGIS Studio Reporting Custom Widgets.

To configure a ArcGIS Web AppBuilder app to host a report:

  1. Launch Web AppBuilder.

  2. Create a new 2D app. Use the default theme.

  3. Add a web map that has the Shelters layer in it.

    If necessary, create a new web map. The URL for the Shelters layer is:

    http://sampleserver5.arcgisonline.com/arcgis/rest/services/NapervilleShelters/MapServer/0

  4. Add the Reporting widget to the app.

    To add the widget, open the Widget panel, click Set the widgets in this controller, and then click the icon to add widgets. Select the Reporting widget and click OK.

    Because you are creating a 2D app, only the 2D widget is available to add. When you create a 3D app, only the 3D Reporting widget is available to add.

    Reporting widget

  5. Click Add Report.

  6. In Public, select the report and click OK.

  7. Choose the Shelters layer.

  8. Click OK.

  9. Save the app.

    You can now run the report.

Configure a Geocortex HTML5 viewer

To configure an HTML5 viewer to run a layer report, you add the report to your Geocortex Essentials site.

Geocortex HTML5 viewers can host other types of reports besides layer reports. The steps to configure other types of reports are different. See Configure an HTML5 Viewer to Run a Report Using a Command for information.

This tutorial assumes that you have already configured a site as follows:

To configure a Geocortex HTML5 viewer to host a layer report:

  1. Launch Geocortex Essentials Manager.

  2. Click Map in the side panel, click the Map Services tab, expand the Shelters map service, and then click the Edit icon next to the Shelters layer.

  3. Click the Reports tab. 

  4. Click Add Report.

  5. Make sure A report defined by an ArcGIS item is selected.

  6. Click Next.

  7. Type a display name and description for the report.

    The display name and description can contain spaces and special characters.

  8. Click Next.

  9. Copy the report's URL from the Info panel in Report Designer and paste it in the box. When the results show, select the report in the list.

  10. Click Finish.

    The report is added to the list of reports on the Reports tab. Its type is ArcGIS Item.

  11. Click Save Site.

Step 13: Run the report in the host application

Follow the instructions to run the report in the host application:

If you get a permissions error when you run the report, make sure you have shared the report as described in Step 11: Share the report.

Run the Report in a Web AppBuilder App

  1. Launch the Web AppBuilder app that hosts the report.
  2. If you are using Web AppBuilder in Portal for ArcGIS10.5.1, sign in.

    Anonymous users cannot run reports in Web AppBuilder in Portal for ArcGIS 10.5.1.

  3. Open the Layer List.
  4. Select the ... button next to the Shelters layer.
  5. Select View in Attribute Table.
  6. Select one or more features in the table.
  7. Select the Reporting widget.
  8. In the Reporting dialog that appears, select the report.

    The report is created using the shelter you selected.

  9. When prompted, open the report.

Run the Report in a VertiGIS Studio HTML5 Viewer

  1. Launch the viewer in a browser.

  2. Select the shelters that you want to include in the report.

  3. Click to open the Panel Actions menu and select Run a Report.

  4. Select the report.

    The report is created using the currently selected shelters.

  5. When the report is ready, click Download report file and open the downloaded PDF.