Configuring portal login bulletins

You can configure login bulletins for your NexJ applications on desktop and mobile platforms.

Login bulletins present users with a message they must acknowledge or agree to before accessing the application. They often contain terms of service agreements or important announcements.

Login bulletins consist of a portlet and HTML file. The portlet facilitates interaction with NexJ Framework and the HTML file contains the bulletin's content.

Bulletins are defined using classes in your model. UI Events facilitate communication between user actions in the bulletin and the NexJ application. Bulletin appearance is defined using user interface elements in the Presentation layer of your model.
When you create and configure a login bulletin you can customize bulletin behavior, including:

• Type and importance of the bulletin.
• Application and platform of use.
• Date range when the bulletin is active.
• Intended user group.
• Content of the bulletin.
• Order of appearance (if multiple bulletins are active).

You can add, edit, and remove login bulletins by executing a script in the Scheme Console in NexJ Studio.

Types of login bulletins

There are two types of login bulletins: mandatory and informational.

Mandatory bulletins
Mandatory bulletins present information to users with Accept and Decline buttons. Users must accept the bulletin to proceed to the application. Users who decline the bulletin will be unable to access the application. They will be presented with the bulletin each time they load the application until they choose to accept. If there are active mandatory and informational bulletins, mandatory bulletins will be shown first.

An example of a mandatory bulletin is a terms of service agreement that users must consent to.

Informational bulletins
Informational bulletins present information to users with an OK button. Users must acknowledge the bulletin before they can proceed to the application. There is not an option to decline.

An example of an informational bulletin is an announcement of a planned service interruption.

Scopes of login bulletins

There are two login bulletin scopes: system and application.

System bulletins
System bulletins are displayed in all of your NexJ applications and platforms, however, they only need to be accepted or acknowledged once.

Application bulletins
Application bulletins are only displayed in specific NexJ applications. Application bulletins can apply to one or more NexJ applications.

You can define the type of bulletin you are configuring using a Scheme script executed in the NexJ Studio Scheme Console.

Login bulletin conditions

Login bulletins have conditions that must be met to be displayed to a particular user.

Each of the following criteria must be true for a user to be presented with a login bulletin upon loading a NexJ application:

• The bulletin's active attribute is set to true.
• The user is a member of the viewGroup that the bulletin is set for. Alternatively, the viewGroup attribute is null.
• The user is accessing the application after the bulletin's publication date and before the expiration date (if one is set).
• No instance of SysBulletinResponse with an acceptance attribute of true exists for the user.

If all of the above conditions are met, the bulletin is displayed.

If there is more than one active login bulletin, the order of appearance is determined by two factors:

• Bulletin type
• Ordinal value

Mandatory bulletins are displayed before informational bulletins. Bulletin priority is then determined by ordinal value. Bulletins of the same type with a lower ordinal value are displayed before those with a higher value.

Login bulletin content

Login bulletin content is contained in an HTML file that is referenced by the contentURL attribute in SysBulletin.meta.

There are best practices surrounding login bulletin content to ensure that it is compatible with the NexJ Framework and can be accessed on all platforms:

• The HTML file defined in the contentURL attribute should be deployed on the same host as the NexJ application. Users may encounter warning messages if it is hosted elsewhere.
• Each bulletin in your NexJ application should use a unique contentURL address. Conflicts may arise if multiple bulletins share the same contentURL.
• Web pages used as login bulletin content should be optimized for both desktop and mobile platforms. They should not contain any JavaScript code.
• Login bulletins support locales and localization. Bulletin model strings are localizable, but there can only be a single contentURL. The exception to this is if multiple locales need to be supported, it will be the responsibility of the web page serving the contentURL to perform the needed localization based on the user's selected portal locale.

Login bulletin classes

Login bulletins are defined using multiple classes.

The following classes implement login bulletins in NexJ applications:

SysBulletin.meta

Holds the properties of a bulletin instance. These attributes are defined by the addBulletin event using a Scheme script in NexJ Studio when creating a new login bulletin or editing an existing instance.

SysBulletin attributes

SysBulletinLink.meta

An instance of a bulletin within a portal application. Controls the application, or applications, the bulletin will be displayed in and what user groups it will affect. These attributes are defined by the addBulletin event using a Scheme script in NexJ Studio when creating a new login bulletin or editing an existing instance.

SysBulletinLink attributes

SysBulletinResponse.meta

Holds the user's acknowledgement of a bulletin. NexJ Framework automatically populates this class once a user has used a button in a login bulletin.

SysBulletinResponse attributes

Login bulletin UI Events

Login bulletins use multiple UI Events to interact with the NexJ Framework. The following events contribute to the functionality of login bulletins:

addBulletin

Creates a new instance of a login bulletin. Arguments include all required attributes of SysBulletin, SysBulletinLink, and the application name list (appNameList[]). A null appNameList[] is interpreted as a system-wide bulletin. For more information on addBulletin, see Administering login bulletins.

sysBulletinAck

Updates the SysBulletinResponse for the current bulletin. Changes the acceptance attribute to either true (#t) or false (#f) based on the user's response to the login bulletin. This event is fired when the user selects the Accept or Decline button in a mandatory bulletin or OK button in an informational bulletin.

If the user agrees with the login bulletin, the following workflow takes place. After the Agree or OK button is clicked, SysBulletinLink'acknowledge is fired to indicate the user's consent with the current notice. The SysBulletinLink instance is changed to the next selection in the SysBulletinHolder current form. If there is another instance, it invokes the event SysBulletinLink'onBulletinView to display the next login bulletin. If there are no remaining bulletins, the popup is closed and the user proceeds to the application.

If the user disagrees with the login bulletin, the following workflow takes place. After the Disagree button is clicked, SysBulletin'acknowledge is fired using a false argument to indicate the negative response. Then the popup is closed and the sysExit UI Event is fired to log the user out of the portal container.

onBulletinView

Finds a matching instance of SysBulletinResponse for the current user. If one does not exist, a new instance is created. Increases the viewTotal attribute for the bulletin by one increment.

Login bulletin user interface elements

The login bulletin user interface is defined using a number of forms, screens, and UI Event handlers.

You can modify these files in your model using NexJ Studio to customize how login bulletins will appear and function in your NexJ application:

sysBulletin UI Event handler

A UI Event handler in PortalApplicationController. It loads a modal popup using the SysBulletin.screen with fixed dimensions and disables the user's ability to close the popup by removing the close button. When the popup closes and the login bulletin has been accepted or acknowledged, it initializes the workspace.

SysBulletin.screen

Displays a hidden form which binds the login bulletin collection and the SysBulletin detail form with an association to the hidden form that drives the selection of a bulletin.

The UI Event closing the resulting popup, either sysClose or sysCancel, should be handled so that the triggering event is cancelled if there are any remaining unconfirmed or mandatory bulletins. This practice removes the end user's ability to avoid consenting to the agreement. The screen should also handle the sysBulletinAck and sysOnLoadBrowser UI Events.

sysBrowserOnLoad UI Event handler

Enables all the available buttons in SysBulletinButtons.

SysBulletin.form

A form that displays the desired layout for an instance of SysBulletinLink. It uses a browser control to display the external URL resources within an iframe. In the initialization script, the SysBulletinLink'onBulletinView event is invoked.

SysBulletinHolder.form

A hidden form to hold the collection of SysBulletinLink and its selection. It drives the detail form SysBulletin.form.

SysBulletinButtons.form

Bulletin buttons should have a polymorphic layout to display either:

• Two buttons, btnAgree and btnDisagree, if the type attribute is set to mandatory (M).
• One button, btnOK, if the type attribute is set to informational (I).

These buttons fire the sysBulletinAck UI Event.

Administering login bulletins

Administer login bulletins for your NexJ application using NexJ Studio. Bulletins are added and edited using Scheme scripts.

For a description of all the attributes contained in the following scripts, see Login bulletin classes.

There are two Scheme scripts used to administer login bulletins: adding login bulletins and editing login bulletins.

Adding login bulletins

This script creates a new login bulletin instance in SysBulletin.meta using the addBulletin event.

To associate a bulletin with all NexJ applications, leave the appNameList[] attribute blank. If the appNameList[] attribute has application names specified, the bulletin will only be applicable for those applications.

Syntax:

addBulletin(type, name, 
 caption, description, contentURL, disagreeURL, publicationStartTime, 
 publicationEndTime, ordinal, viewGroupName, appNameList[])

In the following example, a new mandatory bulletin is added to the Provider Portal application. This bulletin is presented to all users belonging to the Provider user group. It is active immediately and does not have an expiration date:

Example:

(begin-transaction
   (SysBulletin'addBulletin "M" "bulletin1" "Sample Bulletin"
    "My mandatory bulletin description"
    "http://www.your-website.com/mandatory-bulletin.html"
    "http://www.your-website.com/disagree-to-mandatory-bulletin.html" (now)
    () 0 "Providers"
    "ProviderPortal")
)

Editing login bulletins

This script edits the properties of an existing login bulletin. The bulletin being modified is specified in the first line of the script and the attributes that will be changed are defined thereafter. If attributes in the bulletin are not included in this script or are left null, they will remain unchanged:

Use this script to disable a login bulletin by setting the publicationEndTime attribute to (now).

Syntax:

(define bulletin (SysBulletin'read '(name ordinal publicationStartTime publicationEndTime) '(= name “name”) '() '() '() #f))

In the following example, bulletin1 has its ordinal attribute changed to 1 and publicationStartTime changed to (now).

Example:

(define bulletin (SysBulletin'read ' (name ordinal publicationStartTime publicationEndTime) '(= name "bulletin1") '() '() '() #f))
   (bulletin'ordinal 1)
   (bulletin'publicationStartTime (now))

Adding and editing login bulletins in NexJ Studio

You can add and edit login bulletins in your NexJ application by executing a Scheme script in the Scheme Console.

Write a Scheme script to administer a login bulletin before beginning this task. For more information on login bulletin scripting, see Administering login bulletins.

To add or edit a login bulletin in your NexJ application:

1. In NexJ Studio, ensure that the Set Current Server button 

   

   value and Set Current Connections button 

   

   value are set to the NexJ application you are setting the login bulletin for.
2. Click the Set Current User button 

   

   and select a user with administrative privileges.
3. Click the Run Scheme Console button 

   

   to open the Scheme Console.
   The Scheme Console opens.
4. In the Scheme Console, enter the login bulletin script you are administering and press Enter to execute it.
5. Confirm the script has successfully run with no errors.
6. Press the Terminate button 

   

   to close the Scheme Console.
   The Scheme Console closes.

Your login bulletin has been created or modified.