Panel Designer

Panels are custom displays of data that you are able to name, build, arrange in grids, and add to your site. Using panels, your users can browse, edit, add, and delete their data, as you specify.

You can import your existing user-defined tables directly from the Panel Editor content item configuration. In addition, your Activity table data is automatically available as a source, so that you can use and extend that data. Panel sources can include existing user-defined tables (defined in the UD_Table table) and other user-defined sources (identified by the Panel Editor via the DB Maintenance Tool).

You can conveniently manage your custom data directly from the web pages where you place these content items:

  • Panel Editor - Creates panels and shows one panel
  • Panel Collection Editor - Combines existing panels into tabbed displays

Note: Panels are shared. When you update one panel or field, it updates within every content item that uses it.

With the Panel Designer, you can craft reusable panels that combine fields from many tables. You can also define new data structures (business objects and properties) to manage information for your organization. Without special tools or knowledge of the iMIS schema, you can add data sources right from your browser. When you save the panel, you save your newly created data sources as iMIS business objects.

Note: You can see your new data source show up as a business object in Business Object Designer, but it will be read-only. Continue to edit and manage these special sources in Panel Designer. A ContactKey is automatically generated for the business object that represents the panel data source. The ContactKey is a unique value used to join the business object to other panel data sources and business objects in IQA. It is also used as the iMIS ID for linking in IQA.

Access the Panel Designer in the following ways:

  • From the Staff site, go to RiSE > Panel Designer. Select an existing panel to edit, or select Add panel definition to create a new panel.
  • Edit the Panel Editor content item directly from a content record by clicking the gear cog icon.

Here are key layout features to help you optimize screen display:

  • Multiple columns: Click the + or – icons next to the panel layout to add columns to or remove columns from your panel. For best display results, place multi-column panels into single-column content records.
  • Hide in summary view: Select this option if you want to display the property only when users open the full window for viewing, adding or editing.
  • Read-only: Check this box to provide information in read-only form while still allowing users to edit other information on the panel.

    • Note: To prevent editing of all of the properties, disable Allow users to edit on the content item configuration instead of editing in the Panel definition.

  • Collapsible panel (not configurable): In order to maximize utility and minimize scrolling on the page, users are able to click on the arrow to expand and collapse content items.

    • Note: Be sure to add an optional Title to any content item that you make collapsible, so that title bar text guides your users as to what information they will access by clicking Show.

Version2 virtual table model

The version2 virtual table model is a file structure for all virtual tables created in iMIS version 20.2 or later (tables created through the Panel Editor for user-defined data), with improved performance for sites with large amounts of data. The version2 structure applies to any virtual tables created in iMIS version 20.2 or later created through Panel Editor. Existing tables created using the original (version1) structure will remain unchanged and are also fully supported.

All virtual tables created in iMIS version 20.2 or later use the version2 file structure by default. If you have any customizations that directly access the tables that contain user-defined data, you might have to modify those customizations to handle any version2 tables created in the future.

Note: This setting in the web.config file only affects virtual tables created in iMIS version 20.2 or later. Any table created using the version1 model will remain unchanged, and any user-defined tables created through the iMIS Customizer will remain unchanged.

To create your own data source with properties, work within Panel Editor. Each new source you create is available for immediate use in the current panel. When you Save the panel, that new business object is saved to the iMIS database for use throughout the system. After you save it, you cannot rename it.

To create a new panel, do the following:

  1. From the Staff site, go to RiSE > Panel Designer.
  2. Select Add panel definition.
  3. Enter a Panel name and Panel description.
  4. Select Show data sources that allow only one entry per object instance. This option means that members and contacts will only be able to enter or select one option per data source you create. To allow users to be able to enter multiple entries per object, see Panels with multiple entries.
  5. Select Create source.
  6. Enter a Source Name for each new source that meets the following criteria:
    • Starts with a letter.
    • Contains only letters, numbers, and underscores.
    • Is unique across iMIS. The name cannot match any existing iMIS data or SQL Reserved Words.

      • Note: We recommend that you use an organizational prefix (such as ABC_Name) so that your sources are unique, sort together in the tree view, and are easy to identify as sources that you created.

  7. Click OK.
  8. Click Add property for the new source added.

  9. Enter a Property name that:
    • Starts with a letter
    • Contains only letters, numbers, and underscores
    • Is unique within its source
  10. Choose a property type that best fits your purpose, within these valid ranges:
    • Currency: 19 total digits (precision), with four digits to the right of the decimal point (scale). The default masking displays two decimal places.
    • Date, Date and Time, Time: January 1st, 1753, through December 31st, 9999
    • Decimal: 28 total digits (precision), with 12 digits to the right of the decimal point (scale). The default masking displays two decimal places.
    • Email: Creates a mailto link, which launches the user’s default mail application when selected.
    • File upload: Allows contacts to associate a file with their record. After a file is uploaded, it can be downloaded by anyone who can view the panel. By default, all file types are accepted. Enter specific Allowed file types to restrict the type of files that can be uploaded. The maximum file size allowed is 10 MB.

      • Note: For security reasons, we recommend that you do not allow .exe files.

    • Integer: –2,147,483,648 to 2,147,483,647 (±2 billion)
    • Text: By default:
      • The maximum character limit for single and multi-line Text fields depends on when the original table was created. Older tables will have a maximum of 400 and newer tables will have a maximum of 4,000.
      • Pre-defined values from a query or explicit list that display as a drop-down at runtime:
        • Query – Lists the results from a query, such as a list of countries.
        • Explicit List – Lists specific terms that you define, such as industry type or regions.
    • URL: Creates a live hyperlink. When selected, a new browser is opened.
    • Yes/No: Provides a checkbox for the user to select if Yes, or to leave blank if No.
  11. Enable Log all changes if you want to track any data change made to the property. 

    12. Note: The Change History Display content item must also be on the content record in order to properly display data changes. See Logging changes to data and displaying the change log for more information about logging changes with panels and business objects.

  12. (Text Property type only) The Pre-defined values option allows you to present a list from which the user can select:
    • Enable the Allow multi-selections option to allow users to select multiple values for a single property.
    • The Defined by query option provides validation-type properties based on the query results. For example, instead of typing out a list of countries, you could select a query that displays country values.
      • Enable the Pre-defined values checkbox and select the Defined by query option.
      • Click Browse, select a query, and click OK.
      • Two additional fields are displayed:
        • Data Value - The field you want saved in the database.

          • Note: If Allow multi-selections is enabled, the Data Value properties cannot contain any commas. If the Data Value contains a comma, the properties will not properly display in the drop-down.

        • Display Value - The field you want displayed in the list presented as a selection on the panel.

        While these values can be same, you may want to choose a different value to display on the panel. For example, the country code may not be as clear as the country name.

      • Select the fields from the drop-down in the Data Value and Display Value fields.
      • Click OK.

    • The Defined by explicit list option allows you to create a list to display on the panel:
      1. Enable the Pre-defined values checkbox and select the Defined by explicit option.  A table grid is displayed.
      2. Click the plus icon (+) to add a data row. The data row contains two icons: Insert and Cancel, and two fields: Data Value and Display Value. The Data Value is the field saved in the database. The Display Value is the field displayed in the list presented as a selection on the panel. While these values can be same, you may want to choose a different value to display on the panel.
      3. Enter the appropriate values in the Data Value and Display Value fields.
      4. Click the Insert icon located to the left of the data row.
      5. Click the plus icon (+) to add additional data rows.
      6. Click OK.

      Note: To learn how to edit an explicit value list, see Editing explicit value lists.

  13. Drag the fields to the layout area. You can also double-click a property to add it to the next available space in the layout area.
  14. Click Save and Continue:
    1. After you save a property, you cannot rename it. Note that the sources will alphabetize properly on reopening.
    2. Each new property you create is available for immediate use in the current panel, but it is not limited to that panel.
    3. When you save the panel, the new business object property is saved in the iMIS database for use throughout the system.
    4. Once you save it, you cannot rename it.
    5. Do not save until you create all of the properties. This way, you can view them as a set of properties and improve your naming convention before it is finalized.
  15. Navigate to any content record and add the Panel Editor content item to the page.
  16. From the Panel drop-down, select the panel you just created.
  17. Select Allow users to edit and any other content item configuration options you want to enable, then click OK.
  18. Save & Publish the content.

Warning! If there is a multi-instance panel with a text property in the first position, the panel will prevent the page from loading. Text properties should not be added to the first position in multi-instance panels.

Multi-instance panels allow users to enter multiple items for a single property. For example, you could allow your users to enter more than one degree in an Education panel. Multi-instance panels are also created in order to use Activity types.

Note: The Panel Designer uses the PagedResults.Maxrecords value to determine how many results to display for a multi-instance panel. The PagedResults.Maxrecords option can be found in the C:\Program Files (x86)\ASI\iMIS\Net\web.config file.
If you are not self-hosted, you must contact your host for assistance modifying web.config files.

Note: Multiple entry sources cannot be mixed in a single panel.

Do the following to create a new panel with an activity type:

  1. From the Staff site, go to RiSE > Panel Designer.
  2. Select Add panel definition.
  3. Enter a Panel name and Panel description.
  4. Select Show data sources that allow multiple entries per object instance.
  5. Select the drop-down arrow for the desired activity type from the left column.
  6. Drag-and-drop the activity properties to the white space. The properties will appear in the Add window in the order you arrange them in here.

  7. Click Save & Continue.
  8. (optional) Continue creating panels for activity types.
  9. Navigate to the RiSE page you need the activity data to be on.
  10. Open the content record for edit.

  11. Select Add content.
  12. Open the Content folder, then do one of the following:
    1. If you have one panel you want to add to the content record, select the Panel Editor content item:
      1. Click OK.
      2. From the Panel drop-down, select the activity panel you just created.
    2. If you have two or more panels you want to add in a tabbed format to the content record, select the Panel Collection Editor content item:
      1. Click OK.
      2. Choose Select individual panels.
      3. Select the activity types you want grouped in the panel. The activity types will appear in a tabbed format.
  13. (optional) Enable Multi-Instance Panel Options:
    • Enable scrolling for panel - Select this checkbox to set a height and width for a multi-instance panel. If the panel exceeds the set dimensions, scrolling is enabled.
      • Panel width - Enter the width in pixels.
      • Panel height - Enter the height in pixels.
    • Enable scrolling for cells - Select this checkbox to enable a vertical scrollbar for cells whose values are greater than 100 characters.
    • (Panel Editor only) Allow users to add - When enabled, users are able to manually add data to the panel.
    • Allow users to delete - When enabled, users are allowed to delete entire rows of data from the panel.
    • Allow users to edit - When enabled, users are able to edit the panel data. For Panel Collection Editor, enabling this option allows users to edit and add data to the panel.
      • (PCE only) Open single-instance panels in edit mode by default - Select this checkbox to always display a single-instance panel in edit mode for website users who have permission to edit the panel data.
      • (PCE only) Commit sequence - Allows you to explicitly define the execution order of multiple content items in a content record. The number in this field indicates the processing order for this content item, relative to the other content items in the same content record. The value must be 0 or greater. You can leave the default value of 0 if the execution order of content items is not a concern. Content items with a value of 0 are processed after any other content items with a non-zero Commit sequence value that are on the same content record.
      • Edit window width - Enter the default width, in pixels, of the pop-up edit window for a multi-instance panel.
      • Edit window height - Enter the default height, in pixels, of the pop-up edit window for a multi-instance panel.

      Note: When Allow users to add, Allow users to edit, or Allow users to delete are enabled, the content record must be configured so that users must be logged in to access the page.

  14. Click OK.
  15. Click Save & Publish.

The following is an example of how to build a multi-instance panel when creating a new source (Create source). In this example we will build a Training table, and the end result will look something like this:

  1. From the Staff site, go to RiSE > Panel Designer.
  2. Select Add panel definition.
  3. Enter a Panel name and Panel description. For this example, we will name the panel Training.
  4. Select Show data sources that allow multiple entries per object instance.
  5. Select Create source, and enter a unique Source Name.
  6. For this example, we need to create five properties. These properties will be the Training panel rows: Class, Date, Hours, Certificate, Notes.
    1. Select Add property:
      1. In the Property name field, enter Class.
      2. From the Property type drop-down, select Text.
      3. Click OK.
    2. Select Add property:
      1. In the Property name field, enter Date.
      2. From the Property type drop-down, select Date.
      3. Click OK.
    3. Select Add property:
      1. In the Property name field, enter Hours.
      2. From the Property type drop-down, select Text.
      3. Click OK.
    4. Select Add property:
      1. In the Property name field, enter Certificate.
      2. From the Property type drop-down, select File upload.
      3. Click OK.
    5. Select Add property:
      1. In the Property name field, enter Notes.
      2. From the Property type drop-down, select File upload.
      3. Click OK.
  7. Drag the properties you created into the table. The first property will be the first row in the panel.
  8. Click Save and Continue.
  9. Navigate to any content record and add the Panel Editor content item to the page.
  10. From the Panel drop-down, select the panel you just created.
  11. Select Allow users to add, Allow users to edit, and any other content item configuration options you want to enable, then click OK.
  12. Click Save & Publish.

When users edit information on the Training panel, the Add window will look like this:

As a Staff user, you are able to edit virtual dynamic business objects that were created with the Panel Designer. You can edit panels directly from the content record using Easy Edit, or from RiSE:

  1. From the Staff site, go to RiSE > Panel Designer.
  2. Select the panel.
  3. The design view of the panel is displayed. Expand the source you want to edit.
  4. To continue editing, click the X to remove the field from the display grid.

  5. Right-click on the property in the left pane and select View.

  6. The Edit property window is displayed:
    • Select Log all changes and Pre-defined values.
    • Enable Allow multi-selections to allow user to select multiple values for a single property.
    • Select the Defined by explicit list radio button.

  7. Click the + icon to add values:
    1. Enter the value in the Data Value and Display Value fields.
    2. Click the check button to save the entry on each line.

    8. Note: The new values you add will appear at the bottom of the list in the Edit Property window. However, when the list of values is displayed for selection by a user, the new values you added will display in alphabetical order.

  8. Click OK.
  9. In the Edit Panel window, click and drag the property back into the display grid.

  10. Click Save & Continue.

With Panel Designer, you can create new data sources from your browser. You can also access all user-defined tables and the Activity table.

Referencing existing business objects

Panel Designer can display existing business objects that have a ContactKey or ID property. When ContactKey or ID is the primary key, Panel Designer treats it as a single-instance table. Otherwise, Panel Designer assumes it to be multi-instance.

Panel Designer cannot display your business objects until they are made visible to the panel editor as a data source. This is done by using the DB Maintenance Tool:

  1. Launch the DB Maintenance Tool.
  2. Click the Panels tab.
  3. Click Manage Panel Editor Sources.
  4. Click Add Static Source.

When you click Manage Panel Editor Sources, the following window is displayed:

The source name is displayed in the first column. Then in the following columns, other information is displayed:

  • Is Dynamic Source – This column indicates whether the source is a dynamic source (for example, created by Panel Editor), or a static source (for example, just a business object that Panel Editor is able to use).
  • Is Single Row Source – This column whether the source is a single-row source (for example, there is one row for each contact), or a multi-instance source (for example, there are multiple rows for each contact).

The check-boxes allow you to filter the list down to only what you're interested in. 

Click Add Static Source to add another source. For example, if you create a new business object that has an ID and represents data associated with Contacts, you can add the source here. This adds a row to the ObjectMetaData table.

Adding your own Static Source

Before you can add your own Static Source:

  1. You must have a table created that contains data types supported by Panel Editor, and has the required columns:
    • For single-instance - varchar(10)
    • For multi-instance - varchar(10) and int
  2. The table must have an appropriate primary key, covering the required columns.
  3. The business object is built over the table.
  4. The business object names the required column:
    • Single-instance - ContactKey (the required varchar(10) column)
    • Multi-instance - ContactKey (the required varchar(10) column, and Ordinal (the required int column)

Note: Receiving the error message Invalid table name specified, means that the business object does not exist, or the business object name was entered incorrectly.

Click Remove Static Source if you have a business object (non-dynamic source) selected. This allows you to remove business objects to which you don't want Panel Editor have access.  If the selection is a dynamic source, the button reads Purge Dynamic Source instead.

If you click Remove Static Source, the following confirmation dialog is displayed:

Click Yes to remove the associated row from the ObjectMetaData table. The source is no longer available to Panel Editor. No data is destroyed, and the source can be re-added using the Add Static Source button.

If you click Purge Dynamic Source, the following confirmation dialog is displayed:

If you click Purge Data Source while the checkbox is unselected, the dynamic data source is removed from the ObjectMetaData table.  The dynamic source will no longer be available to Panel Editor to create new panel editor instances.  However, the backing Business Object, View, and Data are all untouched.  There is currently no way to restore access to a purge dynamic data source in this state, except for re-adding the row manually through SQL.  Any panel editors currently using the source should continue to work, but might not be editable.

If the checkbox is selected, then a red warning is displayed:

Selecting this option will also delete the backing Business Object documents, drop the View, and delete all associated Data.  This is useful when performing testing, and you have a number of test objects you want to remove. 

Note: Any Panel Editors using the source will break, and it's the responsibility of the customer to ensure that no Panel Editors are using the source when it is purged.

Do the following to purge orphaned properties from your Panel Editor source:

  1. Launch DB Maintenance.
  2. Connect to the database.
  3. Click the iParts tab.
  4. Click Manage Panel Editor Data.
  5. Verify there are orphaned properties in your selected source.
  6. Select the source that has the orphaned property.
  7. Click Purge Orphans.
  8. Click Purge Property and Data. The following message is displayed:
    9. Are you SURE you want to remove all the data associated with orphaned property '<Property Name>'?
  9. Click Yes. This will remove all data associated with the orphaned property. This action cannot be reversed. If you return to the Panel Editor content item, and recreate the property, there will be no data available for that property.
  10. Click Close.
  11. Select the source that has the orphaned property.
  12. Click Purge Data. This deletes all the data for the source. The following message is displayed:
    13. Are you SURE you want to remove all the data associated with Panel Editor Source '<PanelEditorSourceName>'?
  13. Click Yes. This will remove all data associated with the Panel Editor source. This action cannot be reversed. If you return to the Panel Editor content item, and view the source, there will be no data available.

Settings for Business Object Designer (BOD)

  1. From the Staff site, go to RiSE > Business Object Designer.
  2. Edit the object and open the BOD (Properties tab > Display tab).
  3. To make a property available to your panels, enable the Available to UI? option.

    4. Note: To see your BOD changes immediately, restart IIS.

  4. To allow the user to select multiple options for a property, select Check box(es) under Display Control so that you can enable the Allow multiple selection option.
  5. To enable HTML editing, select HTML Editor under Display Control. Be sure to use the property in a single-column panel to allot sufficient width for the display.

Troubleshooting

If you get an error when creating a new data instance at runtime (either single or multi-instance), check that your business object does not have a Read-only constraint set on the ContactKey or ID property's Definition tab. Also, make sure that a column of column type timestamp is not included as a property in the business object.

There are two different types of data sources that can be logged using the Change History Display content item:

  1. Data created with Panel Designer - When you create and save a new data source in Panel Designer, a business object is also created and automatically associated with the data source. This allows the Panel Designer data source to easily communicate with the Change History Display since the Change History Display only properly logs data when there is an associated business object .
  2. User-defined table data - User-defined tables are legacy tables (created using the iMIS Desktop) that you would import into a panel on the Web. These tables must manually be connected to an iMIS business object in order to properly communicate with the Change History Display.

Logging data changes in the change log history

To log changes for a Panel Designer data source, do the following:

  1. Add the Change History Display content item to your account page.

    2. Note: It is recommended that you make a copy of the out-of-the-box account page and make changes to the copy. See Tailoring account pages for more information.

  2. Make a change to the fields you wish to log, and then refresh the page to see if your changes are displayed in the Change History panel.
  3. If your changes are not displayed, then those particular fields are not configured for changes to be logged. Do the following as necessary:
    • Check the Panel Designer data source:
      1. Open the panel in Panel Designer. Click the gear icon.
      2. If the property is already in the layout area, click the X to remove the property.
      3. Right-click a property for which you want to log changes, and select View.
      4. In the Edit Property window, select the Log all changes checkbox.
      5. Click OK.
      6. Add the property back to the layout area of the panel.
      7. Click Save & Close.

In order to log changes when using user-defined tables as panel editor data sources, you must use business objects. All legacy user-defined sources must be imported and configured properly. For customizer user-defined tables, you can use the Build All utility to automatically create a business object, or you can manually create the business object.

Do the following to associate a business object with your user-defined table:

  1. Do one of the following:
      1. Create a new business object from a legacy user-defined table:
        1. From the Staff site, go to RiSE > Business Object Designer.
        2. Select New > Design Business Definition.

          3. Note: When creating a new Business Object, ensure you add the new Business Object in the Design Business Object Definition folder only. Do not create subfolders in the Design Business Object Definition folder.

        3. (Definition tab) Enter the business object's information.
        4. Click Create Object.
        5. Add properties to the business object, saving after you edit each tab:
          1. (Database tab) Add the tables that contain the columns you want to use in your business object. In the Available Columns list, select which columns to use.
          2. Click Add as Properties or Add All as Properties.

            3. Warning!
            Do not include a timestamp or text column as a property.

          3. Click Save.
          4. (Properties tab) Enable the option Log all changes? for all properties you wish to log changes.
          5. Click Save.
        6. Click Publish.

      Warning!
      Changes made from the web will not replicate in the Desktop change log.

      1. From the Staff site, go to Settings > Utilities > User defined tables.
      2. Click Build All. The Build Results field will display a log of the business objects that were built, compiled, and published.
      3. Verify that Name_Demo is listed in the Build Results field.

        4. Note: Name_Demo is not an actual iMIS table name, and is used here for example purposes only.

      4. Go to RiSE > Business Object Designer.
      5. Select the Name_Demo object.
      6. Click Edit.
      7. Make sure Available to screen designer? is enabled.
      8. (Properties tab) Verify that a Property Name value exists for each column in the Name_Demo table.

        9. Warning!
        Do not include a timestamp or text column as a property.

      9. Enable the option Log all changes? for all properties you wish to log changes.
      10. Click Save, then click Publish. A results window is displayed, listing any messages and errors.
      11. Click Close.

        12. Note: Rerunning the Build All command in the Auto-Generate Business Objects from User-Defined Tables window will cause your changes to be overwritten and lost. The business objects for user-defined tables are recreated by that operation.

  2. Run the DB Maintenance Utility (See Running DB Maintenance for more information):
    1. Click the Panels tab.
    2. Click Manage Panel Editor Sources.
    3. Click Add Static Source.
    4. Enter the exact Source Name. This field is case sensitive.
    5. Click Add Data Source.
  3. From the Staff site, go to Settings > About iMIS.
  4. Click Purge System Cache. This will clear the cache that panel editor uses when loading data sources.
  5. Reset IIS.
  6. Add the panel to a content record and add the fields from the newly created business object.

    7. Warning! Use the properties from the business object name, and not the table name. The table name will appear in the list of sources if you imported the tabled directly using Panel Designer.

You can configure your panel source to auto-populate the date and time an entry is updated. Do the following to add sources that will automatically populate when an entry is updated:

  1. From the Staff site, open the desired panel for edit. For this example, we are editing the Personal details panel on the out-of-the-box user account page.

  2. In Panel Designer, select Create source.

  3. Enter a Source name, then click OK.

  4. Under the new source, select Add property, and add the property you want to track.

  5. Continue to add the following properties:

    6. Property name Property type
    CreatedByUserKey Text
    CreatedOn Date and Time
    UpdatedByUserKey Text
    UpdatedOn Date and Time
  6. Add all of these properties to the panel by double clicking the source.
  7. Mark the CreatedByUserKey, CreatedOn, UpdatedByUserKey, and UpdatedOn properties as Read-only.

  8. Click Save & Close.
  9. Edit the panel data and change the value of the field.

  10. After saving, the four read-only fields are automatically populated with the user key that made the changes.