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 totrue
. - 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 samecontentURL
. - 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 thecontentURL
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
Attribute | Type | Value | Required | Description |
---|---|---|---|---|
type | BulletinTypeEnum | M or I | Yes | The type of bulletin. Can be mandatory (M) or informational (I). |
bulletinLinks | SysBulletinLink | Yes | A collection of links connecting a portal application with a bulletin. | |
contentURL | string | HTTP web address | Yes | The URL to load the bulletin content. Accepts absolute or relative URL. The HTML file should be deployed on the same host as the portal application. |
disagreeURL | string | HTTP web address | No | The URL to show if the user disagrees to the bulletin. This URL should be deployed on the same host as the portal application. |
publicationStartTime | timestamp | (now) for immediate. Otherwise, value is structured using the ISO 8601 date/time format. | Yes | The date to begin publication of the bulletin. |
publicationEndTime | timestamp | Leave blank for no defined end time. Otherwise, value is structured using the ISO 8601 date/time format. | No | The date to end publication of the bulletin. |
active | boolean | #t or #f | Yes | The active or inactive status of the bulletin. |
ordinal | integer | 0 displays first. | Yes | The ordinal for bulletin display order. Bulletins with a lower ordinal value will be displayed before those with a higher value. |
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
Attribute | Type | Value | Required | Description |
---|---|---|---|---|
application | SysApplication | Application name | No | The portal application. |
bulletin | SysBulletin | Bulletin name | Yes | The portal bulletin. |
viewGroup | UserGroup | Privilege group name | Yes | The privilege group to indicate which users should view this bulletin. |
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
Attribute | Type | Value | Required | Description |
---|---|---|---|---|
bulletinLink | SysBulletinLink | Bulletin name | No | The bulletin instance within a portal application. |
user | User | User name | Yes | The user account. |
acceptance | boolean | #t or #f | Yes | The user's response to the bulletin. |
viewTotal | integer | Number of views | Yes | Count the number of viewings of this bulletin instance. |
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:
Your login bulletin has been created or modified.