Configuring Neo Widgets

Introduction

This tutorial will teach you the basics of how to do the following:

  • Create different types of Neo Widgets:
    • KPI Widget
    • Analytical (Pivot) Widget
    • State Summary Widget
    • Report Widget
    • Shortcut Widget
  • Create a Widget Category
  • Configure a Neo Dashboard
  • Persist the Neo Dashboard to the module's source code

Initial Setup

This section walks through how to set up prerequisite data and configurations used in the tutorial.

Install and Start the SDK

  1. In order to follow along with this tutorial, you will need the SDK version NEO 3.2 or higher. If you do not already have the SDK installed, then install it now:
    1. Navigate to https://www.onenetwork.com/dev-net/developer-resource-center/
    2. Click "Register for a Free Account Now" if you do not yet have a Developer Network account. Or click "Login to DevNet" if you do already have an account.
    3. Sign in to the Developer Network portal.
    4. Download the latest version of the SDK.
    5. Double click on the SDK installer and follow the installation prompts.
  2. From the Windows start menu, select "One Studio".

Create a Module

  1. From the Studio menu, select File → New → Platform Module.
  2. Fill in the following values:
    1. Module Name: ExpenseTracker
    2. Source Code Package: com.onenetwork.expensetracker
    3. Request Module Prefix: EXTR
  3. Keep "Create sample dataset" checked.


  4. Click Finish.

Create a Data Model

  1. In Package Explorer, right-click on the "ExpenseTracker" module name.
  2. Select New → Model
  3. Fill in the following values:
    1. Project: ExpenseTracker (This will default to the name of your module.)
    2. Model Name: Transaction
  4. Click Finish.
  5. In Package Explorer, expand ExpenseTracker → models. 
  6. Double click on "Transaction.model".
  7. Type in a Description: This model stores expense transactions.
  8. Select the Fields tab.
  9. Add these fields:
    1. UniqueID - Integer
      1. Set Key Field to Natural Key - required
      2. Check Auto-increment
    2. Name - String
    3. Price - Monetary
    4. Category - String Enumeration
    5. TransactionDate - Date
    6. State - State
      1. Note: this field is required for State Summary type widgets.
  10. Create a new string enumeration called TransactionCategories.
    1. With Category selected, choose "Create ..." in the Enumeration drop down box.
    2. Enter the name "TransactionCategories". 
    3. Click OK.
    4. Add these values to the enumeration:
      1. Food
      2. Transportation
      3. Utilities
      4. Entertainment
  11. Save the changes.

Build the Module

  1. Open the Ant Dos prompt by running the file ant_dos.bat
  2. In the Ant Dos prompt, change directory to your module: cd ExpenseTracker
  3. Run: ant build
  4. You should receive a "Build Successful" message once the process completes. If you get any errors, then debug those errors and run the build process again.

Start the Server

  1. In the Ant Dos prompt, change the directory to the module's location if you are not already there.
  2. Run: ant run-server-jdwp
  3. The server will take a few minutes to start.

Configure the State Machine for Our Data Model

In order to create a State Summary type of widget, we will need to configure the State Machine for our Data Model.

  1. In Package Explorer, double click on Module Process Template.mpt under our ExpenseTracker module.
  2. In the Outline tab on the right-hand side of Studio, expense Module Process Type (ExpenseTracker) → ExpenseTracker
  3. Click on Transaction.
  4. Enable an action:
    1. Select the Actions tab at the bottom.
    2. Click Add under Actions.
    3. Set the following:
      1. Name: Update
      2. Type: Write
      3. Write Type: Standard
      4. Include in State Diagram: checked
      5. System of Control: checked
      6. Allow Ent Role Customization: checked
      7. Disable Bulk UI Edits: unchecked
      8. Launch Workflow: N/A
      9. Description: This action updates a Transaction record.
      10. Private: checked
      11. Action Screen Handline: Skip Detail Action Screen (Without Confirm)
    4. Click OK.
  5. Add the States and Transition:
    1. Choose the State Machine tab at the bottom.
    2. Select the State option.
    3. Click in the work area to add a new State.
    4. Name this state "Entered".
    5. Select the State option again.
    6. Click in the work area to add a second new State.
    7. Name this state "Confirmed".
    8. Select the Transition option.
    9. Click on Entered and then on Confirm to add the transition.
  6. Save the changes. 
  7. Submit the Module Process Template to the server.
    1. Click the submit to server button.
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Set up a Data File to Load Transactions

  1. Create a data file called Transactions.xml
    1. In the Package Explorer window of Studio, expand ExpenseTracker_dataset.
    2. Right-click on the data folder.
    3. Select New → File.
    4. Name the file: Transactions.xml
  2. Add the following text to that data file.
    1. <ModelList xmlns="http://www.onenetwork.com/Platform" xmlns:vc="http://www.onenetwork.com/Platform">
        <ValueChainId>9123</ValueChainId>
        <CustomModelName>Standard EXTR.Transaction</CustomModelName>
        <ActionName>PLT.Create</ActionName>
        <Transaction xmlns="http://www.expensetracker.onenetwork.com/ExpenseTracker">
          <ValueChainId>9123</ValueChainId>
          <Name>Kroger</Name>
          <PriceAmount>34.99</PriceAmount>
          <PriceUOM>USD</PriceUOM>
          <Category>Food</Category>
          <State>Entered</State>
        </Transaction>
        <Transaction xmlns="http://www.expensetracker.onenetwork.com/ExpenseTracker">
          <ValueChainId>9123</ValueChainId>
          <Name>Bank of America</Name>
          <PriceAmount>250.00</PriceAmount>
          <PriceUOM>USD</PriceUOM>
          <Category>Transportation</Category>
          <State>Entered</State>
        </Transaction>
        <Transaction xmlns="http://www.expensetracker.onenetwork.com/ExpenseTracker">
          <ValueChainId>9123</ValueChainId>
          <Name>City of Farmers Branch</Name>
          <PriceAmount>90.00</PriceAmount>
          <PriceUOM>USD</PriceUOM>
          <Category>Utilities</Category>
          <State>Confirmed</State>
        </Transaction>
        <Transaction xmlns="http://www.expensetracker.onenetwork.com/ExpenseTracker">
          <ValueChainId>9123</ValueChainId>
          <Name>Netflix</Name>
          <PriceAmount>15.99</PriceAmount>
          <PriceUOM>USD</PriceUOM>
          <Category>Entertainment</Category>
          <State>Confirmed</State>
        </Transaction>
        <Transaction xmlns="http://www.expensetracker.onenetwork.com/ExpenseTracker">
          <ValueChainId>9123</ValueChainId>
          <Name>Del Friscos</Name>
          <PriceAmount>99.99</PriceAmount>
          <PriceUOM>USD</PriceUOM>
          <Category>Food</Category>
          <State>Confirmed</State>
        </Transaction>
      </ModelList>
    2. Save the changes to the Transactions.xml file.
  3. Add a reference to Transactions.xml in the LoadData.xml file.
    1. Double click on the LoadData.xml file.
    2. Add the following line with the other ModelFile elements:
      <ModelFile>data/Transactions.xml</ModelFile>
    3. Note: You have more than one module if, for example, you are doing multiple tutorials in the same environment. If so, then remove the ValueChain line from your LoadData.xml file. Otherwise, you will get an error when attempting to run the load-data target.
    4. Save the changes to the LoadData.xml file.

Load the Data

  1. Once the server has started, you can load the data.
  2. In the Ant Dos prompt, change directory to your dataset: cd ExpenseTracker_dataset
  3. Run: ant load-data
  4. You should receive a "Build Successful" message once the process completes. If you get any errors, then debug those errors and run the build process again.

Creating a KPI Widget

In this section, we will add a KPI Widget. These widgets show a single numeric value to the user.

Example of a KPI widget:

Create a Report to Select the Data for our KPI Widget

  1. Create a reports file called TransactionTotal.reports.
    1. In the Package Explorer window of Studio, right-click on the "reports" folder of the ExpenseTracker module.
    2. Select New → File.
    3. Name the file
  2. Add the following report to the file:
    <?xml version="1.0" encoding="UTF-8"?>
    <ReportList xmlns="http://www.onenetwork.com/Platform">
    	<Report>
    	  <Name>TransactionTotal</Name>
    		<SqlDef Name="TransactionTotal" GroupName="SampleSqls">
    			<![CDATA[
    			SELECT 
    				SUM(PRICE_AMOUNT) AS PRICE_TOTAL,
    				PRICE_UOM
    			from EXTR_TRANSACTION
    			GROUP BY 
    				PRICE_UOM
    			]]>
    		</SqlDef>
    		<Retrieval>
            <CustomRetrievalField>
                <FieldRef levelType="EXTR.Transaction" category="PDF">
                    <FieldName>PriceAmount</FieldName>
                </FieldRef>
                <Hidden>false</Hidden>
                <Type>STRING</Type>
                <SimpleMapping sqlName="PRICE_TOTAL" />
            </CustomRetrievalField>
            <CustomRetrievalField>
                <FieldRef levelType="EXTR.Transaction" category="PDF">
                    <FieldName>PriceUOM</FieldName>
                </FieldRef>
                <Hidden>false</Hidden>
                <Type>STRING_ENUMERATION</Type>
                <EnumerationType>CurrencyCode</EnumerationType>
                <SimpleMapping sqlName="PRICE_UOM" />
            </CustomRetrievalField> 
    		</Retrieval>
    	</Report>
    </ReportList>
  3. Save the changes.
  4. Submit the reports to the server.
    1. Click the submit to server button.
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Configure a KPI Type Widget in the UI Meta Model

  1. In the Package Explorer window of Studio, double click on "Module Process Template.mpt" under the ExpenseTracker module.
  2. Make sure Module Process Type (ExpenseTracker) is selected in the Outline tab in the upper right.
  3. Select the UiMetaModel tab.
  4. Add the NeoWidgetType

    Under the WebInfo element add the following NeoWidetType element:

    <NeoWidgetType name="MoneySpent" componentPath="PLT/Widgets/KPI">
        <AllowedLayouts>COLUMNAR,FIXED,FLEXIBLE</AllowedLayouts>
        <PreviewImagePath>/oms/img/neo/widgets/kpi/kpi1.png</PreviewImagePath>
        <Config>
        {                   
          "reportName": "EXTR.TransactionTotal",
          "valueColumnName": "EXTR$Transaction$PriceAmount",
          "uomColumnName": "EXTR$Transaction$PriceUOM",
          "severityColumnName": "Undefined$PRICE_AMOUNT",
          "emptyValue": "0",
          filters: {filters: {"Undefined$Timeline_displayValue":"Money Spent","Undefined$Timeline":"Money Spent"}}
        }
    	</Config>
    </NeoWidgetType>
    
    1. The following is an explanation of the parameters:
      1. AllowedLayouts defines how the widget can be added to Neo dashboards.
      2. PreviewImagePath defines a path to an image that the user sees when choosing the widget to add.
      3. Config contains JSON formatted settings specific to this type of widget. For a KPI type widget, these are:
        1. reportName = Name of the report where kpi data is retrieved from.
        2. valueColumnName = The name of the report column with the actual KPI number value. Only used when reportName is specified. Defaults to 'Undefined$Count'.
        3. uomColumnName = The name of the report column with the KPI value UOM. Only used when reportName is specified.
        4. severityColumnName = The name of the report column with the KPI severity level. Only used when reportName is specified. Defaults to 'Undefined$Severity'.
        5. emptyValue = The value to show in UI when there's no KPI data (e.g. when related report returned 0 rows or row is returned without mapped KPI value). Defaults to 0. Can be defined as the internationalized value (key).
        6. filters = filters to use while fetching KPI data from report. Only used when reportName is specified.
        7. kpiDefName = KPI def name to fetch data from.
        8. customIndicatorColumnName = The name of a report column with additional info to show in UI. Only used when reportName and customIndicatorTooltipColumnName are specified.
        9. customIndicatorTooltipColumnName = The name of a report column with tooltip text to show in UI for custom indicator. Only used when reportName and customIndicatorColumnName are specified.
      4. For a list of support Widget types and the Config values for each, see: https://jenkins.elogex.com/job/platform_latest/ws/pltdocs/api/react/index.html
  5. Add a new NeoWidgetCategory
    1. Underneath the last NeoWidgetType element, add the following NeoWidgetCategory element.
      <NeoWidgetCategory name="ExpenseTrackerWidgets">
        <RoleTypeRef>
          <IntrinsicRoleType>EXTR.SampleRoleType</IntrinsicRoleType>
        </RoleTypeRef>
        <NeoWidgetTypeRef name="MoneySpent"/>
      </NeoWidgetCategory>
    2. This configures a new category of widgets that the user can choose from when they are adding a widget to a Neo dashboard.
    3. The name attribute is the name displayed to the user.
    4. The InstrinsicRoleType element(s) defines which user Role Types can see this widget group.
    5. NeoWidgetTypeRef adds the widget to the group. The name attribute of this element should correspond with the name of a NeoWidgetType element
  6. Save the changes.
  7. Submit the changes to the server.
    1. Click the submit to server button.
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Configure the Labels for our KPI Widget and our Widget Category

  1. In the Package Explorer window of Studio, double click on "messages.properties" under in the the ExpenseTracker module.
    1. This is found in the folder: web/cfg/war/bundle/
  2. Add the following text.
    meta.NeoWidgetCategory.EXTR.ExpenseTrackerWidgets=Expense Tracker Widgets
    
    meta.NeoWidgetType.EXTR.MoneySpent.name=Money Spent
    meta.NeoWidgetType.EXTR.MoneySpent.description=Money Spent Widget
  3. Save the changes.
  4. Submit the changes to the server.
    1. Click the submit to server button.
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Put the KPI Widget on the Dashboard

  1. Log in to the App:
    1. Open a web browser.
    2. Navigate to http://localhost
    3. Sign in:
      1. Username: ExpenseTrackerUser
      2. Password: password
  2. Create a Neo Dashboard:
    1. Starting from the Home screen of the app, click on the New Dashboard button in the upper right.


    2. Give the new dashboard a name and click Confirm.


  3. Add a Layout
    1. The new dashboard will open with Edit mode active.
    2. Click Add Columnar Layout to add a layout.


    3. A new layout will be added to the dashboard.


  4. Add the new Widget.
    1. Click the plus sign in the leftmost column


    2. Scroll down to the widget category we created in the previous section.


    3. Click Add Widget.
    4. The widget will appear in the dashboard.


    5. Click the Save the Dashboard button at the top to exit dashboard edit mode.

Creating an Analytical (Pivot) Widget

In this section, we will add an Analytical (Pivot) widget. These widgets show a visualization of data. They also are available with many different visualization options.

Example of an Analytical (Pivot) widget:

Prerequisite for Analytical (Pivot) Widgets

Creating an Analytical (Pivot) widget requires Flexmonster, a third-party tool, to be enabled for your internet domain.

For more information about Flexmonster, see: http://www.flexmonster.com/

Create a Report for our Analytical (Pivot) Widget

  1. Create a reports file called TransactionsByCategory.reports.
    1. In the Package Explorer window of Studio, right-click on the "reports" folder of the ExpenseTracker module.
    2. Select New → File.
    3. Name the file
  2. Add the following report to the file:
    <?xml version="1.0" encoding="UTF-8"?>
    <ReportList xmlns="http://www.onenetwork.com/Platform">
    	<Report>
    	  <Name>TransactionsByCategory</Name>
    		<SqlDef Name="TransactionsByCategory" GroupName="SampleSqls">
    			<![CDATA[
    			SELECT 
    				CATEGORY,  
    				PRICE_AMOUNT AS PRICE_TOTAL
    			from EXTR_TRANSACTION
    			]]>
    		</SqlDef>
    		<Filters bindSqlNulls="true">
    	      <CustomFilterField>
    	        <FieldRef category="PDF" levelType="EXTR.Transaction">
           			<FieldName>Category</FieldName>
    		    </FieldRef>
    		    <Type>STRING</Type>
    	        <SimpleMapping sqlName="CATEGORY"/>
    	      </CustomFilterField>
    	    </Filters>
    		<Retrieval>
            	<CustomRetrievalField>
    	            <FieldRef levelType="EXTR.Transaction" category="PDF">
    	                <FieldName>Category</FieldName>
    	            </FieldRef>
    	            <Type>STRING</Type>
    	            <SimpleMapping sqlName="Category" />
    	        </CustomRetrievalField>
    	        <CustomRetrievalField>
    	            <FieldRef levelType="EXTR.Transaction" category="PDF">
    	                <FieldName>PriceAmount</FieldName>
    	            </FieldRef>
    	            <Type>FLOAT</Type>
    	            <SimpleMapping sqlName="PRICE_TOTAL" />
    	        </CustomRetrievalField>
    		</Retrieval>
    		<Pivot>
    	      <PivotName>TransactionsByCategory</PivotName>
    	      <Rows>
    	        <FieldName>Category</FieldName>
    	      </Rows>
    	      <Measures>
    	        <FieldName>PriceAmount</FieldName>
    	      </Measures>
    	      <ChartsEnabled>true</ChartsEnabled>
    		  <ChartsActive>true</ChartsActive>    
      		  <ChartType>pie</ChartType>
    	    </Pivot>
    	</Report>
    </ReportList>
  3. Save the changes. 
  4. Submit the reports to the server.
    1. Click the submit to server button.


    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Configure an Analytical (Pivot) Type Widget in the UiMetaModel

  1. In the Package Explorer window of Studio, double click on "Module Process Template.mpt" under the ExpenseTracker module.
  2. Select the UiMetaModel tab.
  3. Add the NeoWidgetType
      1. Under the WebInfo element add the following NeoWidetType element:
    <NeoWidgetType name="TotalSpentByCategory" componentPath="PLT/Widgets/PivotWidget">
      <PreviewImagePath>/oms/img/neo/widgets/pivot/pivot2.png</PreviewImagePath>
      <Config>
              {
                "reportName": "EXTR.TransactionsByCategory",
                "editableFilters":true,
                "showFilterSummary": true,
                "pivotConfig": {
                  "toolbarEnabled": true,
                  "hideChartConfigPanel": false,
                  "options": {
                    "configuratorButton": true
                  }
                }
              }
      </Config>
    </NeoWidgetType>
    
    1. The following is an explanation of the parameters:
      1. AllowedLayouts = This defines how the widget can be added to Neo dashboards.
      2. PreviewImagePath = This defines a path to an image that the user sees when choosing the widget to add.
      3. Config contains JSON formatted settings specific to this type of widget. For our analytical (pivot) type widget, these are:
        1. reportName = The name of the report which defines the data
        2. editableFilters = Whether or not to allow the user to change the filters in the user interface
        3. showFilterSummary = Whether or not to show a summary of the filters underneath the widget's name
        4. pivotConfig
          1. toolbarEnabled = Whether or not to display a pivot toolbar at the top of the widget
          2. hideChartConfigPanel = Whether or not to display a filter toolbar above the widget's graph
          3. options
            1. configuratorButton = Whether or not to show an array shaped button which allows the users to change pivot settings
        5. filters = A set of named default filters that will be applied to the filter panel and report when generating the pivot.
  4. Add a NeoWidgetTypeRef to our NeoWidgetCategory
    1. Underneath the last NeoWidgetType element, find the NeoWidgetCategory element we created earlier. We named it "KPI Widgets".
    2. Add a new NeoWidgetTypeRef for our Analytical (Pivot) widget.
    3. <NeoWidgetCategory name="KPI Widgets">
        <RoleTypeRef>
          <IntrinsicRoleType>EXTR.SampleRoleType</IntrinsicRoleType>
        </RoleTypeRef>
        <NeoWidgetTypeRef name="MoneySpent"/>
        <NeoWidgetTypeRef name="TotalSpentByCategory"/>
      </NeoWidgetCategory>
  5. Save the changes.
  6. Submit the changes to the server.
    1. Click the submit to server button. 
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Configure the Labels for our Analytical (Pivot) Widget

  1. In the Package Explorer window of Studio, double click on "messages.properties" under the ExpenseTracker module.
    1. This is found in the folder: web/cfg/war/bundle/
  2. Add the following text.
  3. meta.NeoWidgetType.EXTR.TotalSpentByCategory.name=Total Spent by Category
    meta.NeoWidgetType.EXTR.TotalSpentByCategory.description=This is a chart showing the total spent by category.
  4. Save the changes.
  5. Submit the changes to the server.
    1. Click the submit to server button.
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Put the Analytic (Pivot) Widget on the Dashboard

  1. Navigate to http://localhost in your web browser.
  2. Enable edit mode: Click on the pencil icon at the top of the screen.


  3. Add the new Widget.
    1. Click the plus sign in the rightmost column


    2. Scroll down to the widget category we created in an earlier section.
    3. Click Add Widget for the "Total Spent by Category" widget.


    4. The widget will appear in the dashboard.


    5. Click the Save the Dashboard button at the top to exit dashboard edit mode. 

Adjust the Settings for our Analytical (Pivot) Widget

  1. This example displays the chart as a Pie chart. To use a different type of chart, edit the report's Pivot ChartType to change it.
  2. In the Package Explorer window of Studio, find the reports folder of the ExpenseTracker module.
  3. Double click on TransactionByCategory.reports file.
  4. Change ChartType to the type of chart that you want to show.
  5. Some examples of chart types are shown here:
    1. pie
    2. column
    3. bar
       
    4. line

Special Notes About Configuring Measures:

  • Our widget only has one Measure set for it (PriceAmount).
  • If we want to use the "scatter", "pie", or "bubble" chart types then we would need to add more than one Measure.
  • Measures can be added in the report like we did for PriceAmount.
  • Measures can alternatively be added by as slice → measures in the pivotConfig section of the NeoWidgetTypes' Config in the UiMetaModel.
  • Example (for illustration purposes only):
slice: {
  measures: [
    {
       uniqueName: "Orders Fulfilled",
       formula: "DISTINCTCOUNT('ORDER_ID')",
       individual: true,
       caption: "Orders Fulfilled",
       active: true
     },
     {
       uniqueName: "Products Supplied",
       formula: "'ORD_QUANTITY' * 'PROD_UNIT_PRICE'",
       aggregation: "sum",
       individual: true,
       caption: "Total Amount of Products Supplied",
       active: true
     }
  ]

Creating a State Summary Widget

In this section, we will add a State Summary widget. These types of widgets show information about how many records are in different states.

Example of a State Summary widget:

Note: A State Summary widget requires the associated Data Model to have a State field.

Create a Report for our State Summary Widget

  1. Create a reports file called TransactionStates.reports.
    1. In the Package Explorer window of Studio, right-click on the "reports" folder of the ExpenseTracker module.
    2. Select New → File.
    3. Name the file
  2. Add the following report to the file:
    1. <?xml version="1.0" encoding="UTF-8"?>
      <ReportList xmlns="http://www.onenetwork.com/Platform">
      	<Report>
      	  <Name>TransactionStates</Name>
      		<SqlDef Name="TransactionStates" GroupName="SampleSqls">
      			<![CDATA[
      			SELECT
      				STATE, count(STATE) AS COUNT
      			FROM EXTR_TRANSACTION
      			WHERE STATE IS NOT NULL
      			GROUP BY STATE
      			ORDER BY STATE DESC
      			]]>
      		</SqlDef>
      		<Retrieval>
              <CustomRetrievalField>
                  <FieldRef levelType="Transaction" category="PDF">
                      <FieldName>STATE</FieldName>
                  </FieldRef>
                  <Hidden>false</Hidden>
                  <Type>STRING</Type>
                  <SimpleMapping sqlName="STATE" />
              </CustomRetrievalField>
      		<CustomRetrievalField>
                  <FieldRef levelType="Transaction" category="PDF">
                      <FieldName>COUNT</FieldName>
                  </FieldRef>
                  <Hidden>false</Hidden>
                  <Type>STRING</Type>
                  <SimpleMapping sqlName="COUNT" />
              </CustomRetrievalField>
      		</Retrieval>
      	</Report>
      </ReportList>
  3. Save the changes. 
  4. Submit the reports to the server.
    1. Click the submit to server button.
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Add the State Summary Widget to the UiMetaModel

  1. In the Package Explorer window of Studio, double click on "Module Process Template.mpt" under the ExpenseTracker module.
  2. Select the UiMetaModel tab.
  3. Add the NeoWidgetType
      1. Under the WebInfo element add the following NeoWidetType element:
    <NeoWidgetType name="TransactionStateSummary" componentPath="PLT/Widgets/StateSummary">
    	<PreviewImagePath>/oms/img/neo/widgets/statesummary/statesummary4.png</PreviewImagePath>
    	<Config>{
    	  "reportName": "EXTR.TransactionStates",
    	  "stateField": "Transaction$STATE",
    	  "countFields": ["Transaction$COUNT"],
    	  "modelLevelType": 'Transaction'
    	}</Config>
    </NeoWidgetType>
    1. The following is an explanation of the available parameters:
      1. PreviewImagePath defines a path to an image that the user sees when choosing the widget to add.
      2. Config contains JSON formatted settings specific to this type of widget. For our analytical (pivot) type widget, these are:
        1. reportName = The name of the report which defines the data
        2. stateField = The name of the data field which defines records' states
        3. countFields = An array of field names with numeric counts.
        4. nonChainedStates = An array of field names where you do not want arrows showing state names connected.
          1. For example, you could add the following to the example above:
            1. "nonChainedStates": ["Entered", "Confirmed"],
          2. This would make the widget appear as follows:


        5. plugins = An array of one or more plugins, each of which should be an object which can contain the following functions:
          1. onStateClick = Callback which is called when the user clicks on a state label. It is passed the store and the state as the only parameters and expects no return value.
          2. onCountClick = Callback which is called when the user clicks on a state count. It is passed the store, the state, and the count object, and expects no return value.
        6. modelLevelType = model key prefix to use to internationalize state value
        7. stateI18nPrefix = i18n key prefix to use to internationalize state value (e.g. - 'meta.field.State.')
      3. AllowedLayouts defines how the widget can be added to Neo dashboards.
  4. Add a NeoWidgetTypeRef to our NeoWidgetCategory
    1. Underneath the last NeoWidgetType element, find the NeoWidgetCategory element we created earlier. We named it "KPI Widgets".
    2. Add a new NeoWidgetTypeRef for our Analytical (Pivot) widget.
    3. <NeoWidgetTypeRef name="TransactionStateSummary"/>
  5. Save the changes. 
  6. Submit the changes to the server.
    1. Click the submit to server button.
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Add labels for the State Summary Widget

  1. In the Package Explorer window of Studio, double click on "messages.properties" under the ExpenseTracker module.
    1. This is found in the folder: web/cfg/war/bundle/
  2. Add the following text.
  3. meta.NeoWidgetType.EXTR.TransactionStateSummary.name=Transaction State Summary
    meta.NeoWidgetType.EXTR.TransactionStateSummary.description=This widget shows how many transactions are in each state.
  4. Save the changes.
  5. Submit the changes to the server.
    1. Click the submit to server button.
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Put the State Summary Widget on the Dashboard

  1. Navigate to http://localhost in your web browser.
  2. Enable edit mode:
    1. Click on the pencil icon at the top of the screen.
  3. Add the new Widget.
    1. Click the plus sign under our KPI widget:
    2. Scroll down to the widget category we created in an earlier section.
    3. Click Add Widget for the "Transaction State Summary" widget.
    4. The widget will appear in the dashboard.
    5. Click the Save the Dashboard button at the top to exit dashboard edit mode.

Creating a Report Widget

A report widget shows a table of data in a widget. This widget can be filtered by the user. It also includes pagination of data.

Create a Report

  1. The first step is to create a report. We already created reports in an earlier step, so we will just use one of those for illustration. Let's use the report "TransactionsByCategory".
  2. For more information on how to create reports, please see the Report documentation: Reports - Developer Network Documentation (onenetwork.com)

Add the Report Widget to the UiMetaModel

  1. In the Package Explorer window of Studio, double click on "Module Process Template.mpt" under the ExpenseTracker module.
  2. Select the UiMetaModel tab.
  3. Add the NeoWidgetType
      1. Under the WebInfo element add the following NeoWidetType element:
    <NeoWidgetType name="TransactionsReport" componentPath="PLT/Widgets/ReportWidget">
    	<PreviewImagePath>/oms/img/neo/widgets/summarylist/summarylist1.png</PreviewImagePath>
    	<Config>
    	  { "reportName": "EXTR.TransactionsByCategory", "height": 250 }
    	</Config>
    </NeoWidgetType>
    1. The following is an explanation of the available parameters:
      1. PreviewImagePath defines a path to an image that the user sees when choosing the widget to add.
      2. Config contains JSON formatted settings specific to this type of widget. For our analytical (pivot) type widget, these are:
        1. reportName = The name of the report which defines the data.
        2. height: The height of the widget in pixels.
  4. Add a NeoWidgetTypeRef to our NeoWidgetCategory
    1. Underneath the last NeoWidgetType element, find the NeoWidgetCategory element we created earlier. We named it "KPI Widgets".
    2. Add a new NeoWidgetTypeRef for our Analytical (Pivot) widget.
    3. <NeoWidgetTypeRef name="TransactionsReport"/>
  5. Save the changes.
  6. Submit the changes to the server.
    1. Click the submit to server button.
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Add labels for the Report Widget

  1. In the Package Explorer window of Studio, double click on "messages.properties" under the ExpenseTracker module.
    1. This is found in the folder: web/cfg/war/bundle/
  2. Add the following text.
  3. meta.NeoWidgetType.EXTR.TransactionsReport.name=Transaction Category Report
    meta.NeoWidgetType.EXTR.TransactionsReport.description=This widget shows a report of transactions with categories.
  4. Save the changes.
  5. Submit the changes to the server.
    1. Click the submit to server button.
    2. A dialog in the bottom right of Studio will turn green when the changes have been uploaded to the running server.

Put the Report Widget on the Dashboard

  1. Navigate to http://localhost in your web browser.
  2. Enable edit mode:
    1. Click on the pencil icon at the top of the screen.
  3. Add the new Widget.
  4. Click the plus icon.
  5. Select the Transaction Category Report widget.
  6. Save the dashboard.
  7. The widget will now be visible.

Creating a Shortcut Widget

Shortcut widgets are clickable icons that open a web URL. They are easily added through the web user interface.

  1. Navigate to http://localhost in your web browser.
  2. Enable edit mode:
    1. Click on the pencil icon at the top of the screen.
  3. Click the Add Fixed Layout button to add a fixed layout.
  4. Click the plus icon to add a new widget.
  5. Select the Shortcut Widget. You will find it in the Other Widgets category.
  6. The widget will be added to your dashboard. Click on the vertical ellipses icon and select Settings.
  7. Configure the settings as desired.
    1. Selection Option: This allows you to toggle between a menu option and an external web URL.
    2. Shortcut Name: The name to display to the users.
    3. External Link: The web URL for an external link to open.
    4. Menu Item: The menu item to open.
    5. Image: The image to display on the dashboard.
  8. Click Apply changes.
  9. Click and drag the edge of the widget to the size you want.
  10. Save the dashboard.
  11. The widget will now be visible.

Save the Dashboard Configuration in the MPT

  1. After you've designed a dashboard, you will want that dashboard to persist in the source code control system.
  2. Our dashboard should look something like the following:
  3. Click on the View Dashboard Configuration button at the top of the page.
  4. JSON formatted data describing your dashboard will be displayed. Copy that text by clicking on the Copy to Clipboard button.
  5. Go back to the UiMetaModel tab of the Module Process Template in Studio.
  6. Under the last NeoWidgetCategory element, paste the JSON that we copied from the app's UI in an earlier step. The full NeoPortalDef element will look like the following:
    1. <NeoPortalDef name="Dashboard Tutorial" isDashboard="true">
        <DefaultConfig><![CDATA[
          {
            "schemaVersion": 1,
            "sections": [
              {
                "config": {
                  "colConfigType": "THIRD_LEFT",
                  "columns": [
                    [
                      {
                        "_defaultConfig": {
                          "autoRefreshInterval": 0
                        },
                        "widgetTypeName": "EXTR.MoneySpent"
                      },
                      {
                        "_defaultConfig": {
                          "autoRefreshInterval": 0
                        },
                        "widgetSettings": {
                          "filters": {},
                          "settings": {
                            "showZeroValueStates": true
                          }
                        },
                        "widgetTypeName": "EXTR.TransactionStateSummary"
                      }
                    ],
                    [
                      {
                        "_defaultConfig": {
                          "autoRefreshInterval": 0
                        },
                        "widgetSettings": {
                          "filters": {}
                        },
                        "widgetTypeName": "EXTR.TotalSpentByCategory"
                      },
                      {
                        "_defaultConfig": {
                          "autoRefreshInterval": 0
                        },
                        "widgetSettings": {},
                        "widgetTypeName": "EXTR.TransactionsReport"
                      }
                    ]
                  ],
                  "schemaVersion": 1
                },
                "customizedTitle": true,
                "titleKey": null,
                "type": "ColumnarLayout"
              },
              {
                "config": {
                  "items": [
                    {
                      "_defaultConfig": {
                        "autoRefreshInterval": 0
                      },
                      "customTitle": "One Network Enterprises Website",
                      "h": 2,
                      "w": 2,
                      "widgetSettings": {
                        "customizedTitle": true,
                        "externalLink": "https://www.onenetwork.com",
                        "image": 3,
                        "selectOption": "externalLink",
                        "webAction": ""
                      },
                      "widgetTypeName": "PLT.ShortcutWidget",
                      "x": 0,
                      "y": 0
                    }
                  ],
                  "schemaVersion": 1
                },
                "customizedTitle": true,
                "titleKey": null,
                "type": "FixedLayout"
              }
            ]
          }
        ]]></DefaultConfig>
      </NeoPortalDef>
    2. The NeoPortalDef element defines a Neo Dashboard available to users.
    3. The name attribute defines the name that appears in the upper left of the screen.
  7. To make the dashboard the default dashboard for a given role type, you need to add a WebAction that loads the NeoPortalDef you've defined. The WebAction will load a PLT/NeoDashboard React page that knows how to render dashboards, and the name property in the Properties element should correspond to the NeoPortalDef name (and include your module prefix):

    <WebAction singleton="true" name="DefaultNeoDashboard">
      <OneReactPage>
        <ModulePath>PLT/NeoDashboard</ModulePath>
        <Properties>{"name":"EXTR.DashboardTutorial"}</Properties>
      </OneReactPage>
    </WebAction>
  8. Then, you need to add a NeoDashboardRef which references the WebAction at the bottom inside each RoleTypeUiConfig you want to configure it for. The name should correspond to the same name used in the WebAction. Example:

    <RoleTypeUiConfig menuType="menu" ui="Neo">
      <RoleTypeRef>
        <IntrinsicRoleType>EXTR.SampleRoleType</IntrinsicRoleType>
      </RoleTypeRef>
      <WebActionGroupRef name="Administration" />
      ...
      <NeoDashboardRef name="DefaultNeoDashboard" />
    </RoleTypeUiConfig>
  9. Save the changes to the Module Process Template.
  10. Submit the changes to the server.
  11. To verify that the dashboard is now the "default dashboard", you can delete the record in the NEO_DASHBOARD table in the database that was created for the dashboard you created through the UI. Then refresh Neo UI. Verify that you still see the dashboard you created; this is appearing by default from the configuration you added to the Module Process Template.
  12. You can now commit all of the module and dataset changes to the source code repository.
  13. When the app is built and deployed, our widgets, widget category, and dashboard will all be available to the user.