Customize a Starter App Example Project (Release 7.4 only)

The information below helps walk you through the process of customizing a Starter Application and linking it to a project created using the Assessment Framework. Because this information is for demonstration/instructional purposes we have used generic data object names, such as "meta1". To create a Starter Application intended for production use, please discuss your project with a LogicNets representative.

Preparation

Complete the following steps prior to customizing your Starter Application:

1. Determine the name of the published Assessment Framework project your Starter App will call.
2. Identify the variable names for up to 5 key variables you want to display on the Starter Portal; for example, "department_name".
3. Identify the titles for each of the variables identified above; for example, "Department".
4. Create a new Starter Application project in the Designer account where you created your Assessment Framework application, using the attached Starter Template project.

For an alternative Starter Template that includes record locking use this example. Record locking indicates which sessions are in use, and it gives the user the choice to continue with or without the latest edits from the in use session. 

STEP 1: Specify the Assessment Framework Application to Launch

The Starter Application opens a blank copy of the designated application and starts a new session when the user clicks the New button. In STEP 2 you set the name of the application the system opens when the user clicks the New or Resume buttons. For this step, you will need to reference the variable names from your application that you identified as part of the preparation.

Customization Options/Steps

To set the name of the application the system should open, do the following:

1. In the Project pane, navigate to the logicnet called "starter_configuration" and go to node 10 - "SET LAUNCH PACKAGE".
2. Click on the node and the system opens the editor.
3. In the "Value" field enter the name of the published Assessment Framework project.
4. Click save at the top of the editor to save your updates.

Test Your Updates

To verify that you made your changes correctly, click on your project in the Project pane and click the Test button on the Details tab. Click the New button to start a new session and watch your Assessment Framework application load. You can also return to the Starter Application main page by clicking the Submit or Save buttons and look at the grid to see if there are changes in the modified date and status.

Advanced Options and Notes

In this simple example, the Starter will open a single published application every time. If you make updates to the Assessment Framework application you connected to your Starter Application, make sure you publish the updates under the same name. For more sophisticated applications, however, your users may choose between different packages, or launch based on a category name (this is helpful when dealing with application versions). This article does not describe the design of these features. Ask your LogicNets representative for more information on this.

STEP 2: Customize the Columns of the Session Grid

Each time a user interacts with an application it's called a session, and users can start, save, and restart sessions using the Starter Application. The main page of the Starter Application displays prior sessions and important high-level data (meta data) about each session, which allows users to identify, review, and/or restart a session. The system displays this data in a grid/table, and this step shows you how to customize the table with appropriate column titles.

By default, the session grid includes the following columns:

• session id (the unique identifier for the session from the data table)
• meta1 (field available for customization)
• meta2
• meta3
• meta4
• meta5
• created date (date/time stamp of when the session was first created)
• modified date (date/time stamp of when the sesssion was last saved)
• modified by (first and last name of person who last saved the session)
• status
  • In Progress - This is the status that displays after the session is created and when the user saves the session.
  • Completed - This is the status that displays after the user submits the session.

Customization Options/Steps

To modify the titles in the session grid, do the following:

1. In the Project pane, navigate to the logicnet called "main_panel_ui" and go to node 100 - "SESSION GRID".
2. Click on the node and the system opens the editor.
3. For each column where you want to change the title, click change, type the new name in the "Title" section, and click save.
4. Remove any column that is not required by clicking the remove button next to that column.
5. Click save at the top of the editor to save your updates to the node.

Test Your Updates

To verify that you made your changes correctly, click on your project in the Project pane and click the Test button on the Details tab. Your column titles should display in the grid.

Advanced Options and Notes

• To display currency or dates as meta data you must change the type in the type column. See the Support Article on DBGrid3 for help.
• You can style the session grid--including colors, column widths, fonts, and other items--by adding styling details to the "custom_css" file under resources/layout/css.
• Adding additional meta data items IS possible but it is a more involved process than adding columns here. We recommend reviewing the steps of the following logicnets for a more in-depth understanding:
  • resume_session and in particular the load data node
  • save_session_data to understand how data is written back to the table.

STEP 3: Save Assessment Framework Meta Data Values Back to the Session Grid

When the user has finished interacting with the Assessment Framework-based application and clicks the Save or Submit buttons, the system saves all of the data values for resuming the session in future.

Customization Options/Steps

To set the data values, do the following:

1. In the Project pane, navigate to the logicnet called "populate_metadata" and go to node 10 - "meta1_collection".
2. This node contains more than one part. Double-click on the part called Query Collection.
3. In the "Query" field, replace the variable_name with the data object name from your application(*). The variable must be contained within single quotes, e.g. 'department_name'.
4. Click save at the top of the editor and repeat the steps above for each meta data item.
   
   

* Variable names are the full path container.data_object names from the launched application that have been specified by the Designer. To refresh memory of these, run that application in TEST mode and answer the questions that contain the meta data to be transferred back to the Starter, then click on the DATA button and search for those values. The variable names can be gleaned from this view.

Each of the the meta data items are set to receive text inputs. If one or more of your meta data items is in date or number format, then do the following:

• In each meta data process node, click the Set Data Object Value part.
• Select the appropriate data type.
• Selection from the format options available depending on the data type.

Test Your Updates

To verify that you made your changes correctly, click on your project in the Project pane and click the Test button on the Details tab. Run your Starter Application and verify that the meta data is updated correctly when you click the Save and Submit buttons. Clicking the Review and Cancel buttons should not change the data.

Advanced Options and Notes

The "populate_metadata" logicnet also contains the steps and conditions that tell the system to set the project status to In Progress or Completed. To implement a more sophisticated set of stages/status points, you can copy a process node and extract the additional data needed from the project and then model the rules to determine current status. The system updates the session grid with the value held in "variable = status".

STEP 4: Setting the Topbar Values in the Application

When the user is running the application, the topbar at the top of the screen can display key meta data--such as last modified date--so the user is always aware of which session they are viewing/editing. The purpose of this step is to show you how to present the meta data values on the topbar of the application.

Customization Options/Steps

1. In the Project pane, navigate to the logicnet called "topbar for AF (Starter-linked)" and form part nodes (in orange) for META1 through META5.
2. Click on the META1 node and the system opens the editor.
3. Change the contents of the "Caption" field to the title for this meta data item. Because this will display in the topbar, where space is limited, keep the title short; for example, Dept. instead of Department Name.
4. Click save at the top of the editor and repeat these steps for each meta data item. NOTE: If you do not use a meta data item you can ignore it.

5. Copy the logicnet you just updated and paste it into the Assessment Framework application. NOTE: Do not paste the logicnet in the forms or reports subfolders.
6. In your Assessment Framework project, go to the Framework settings page and select the logicnet you copied and pasted as the custom topbar.
7. Save and publish the Assessment Framework project, naming it the same name that it had previously.

Test Your Changes

To verify that you made your changes correctly, click on your project in the Project pane and click the Test button on the Details tab. If you have done the above correctly, you can now see the meta data items represented at the top of the screen in the topbar of the assessment application.

Advanced Options and Notes

The meta data and titles associated with status and last modified date can also be customized in the same way in nodes 160 and 170. You can add other meta data items if you want, but you should review how the layout and styling of the topbar because of space restrictions.

In addition to modifying the contents of the topbar, you can also create or update the navigation buttons associated with the Assessment Framework application.

• If your assessment application does not generate a pop-up report or PDF file, remove nodes 60/350 (report_button) prior to publishing the project.
• If your assessment application does generate these,you can customize the button text in nodes 60/350.
• You can also customize the Submit, Save, and Cancel buttons but that action is not described in this article.

STEP 5: Share Your URL

You have completed the steps to customize your Starter Application. Publish this project and you can share the link to the application with authorized users. 

WARNING: This Starter Application should not be used for any PRODUCTION installation due to a number of set-up simplifications made. In particular, note that REPUBLISHING the Starter App will overwrite any saved sessions. (For PRODUCTION environments, the session data is stored in a separate database from the logicnet application).

Advanced Options and Notes

In addition to the customizations identified above, you can also use other customizations: 

• You can add other buttons or links above the session grid to take users to other URLs.
• You can define and apply user roles to any access buttons. For example, you could set a "Reviewer" role and only allow users with that role to review existing sessions rather than start new ones.
• With additional modelling, you could set the session grid to display only those items for which the user has the right permissions. 
• Using the main Starter Portal template (not this one) you can launch multiple applications or work with application versions. This is definitely something to consider for PRODUCTION applications.

Known Issues

The system will not send data contained in the Starter App topbar to the Assessment Framework if any of the meta data variables contains an apostrophe.