Novell is now a part of Micro Focus

Creating Applets for Novell GroupWise with Advansys Formativ

Articles and Tips: article

Grant Johnson
Chief Software Engineer
Advansys Pty Limited
grant.johnson@advansyscorp.com

01 Mar 2002


This AppNote introduces Advansys Formativ, a third-party tool that adds applet functionality to Novell GroupWise 6 and 5.5, thus providing a new way for developers and users to automate and extend the GroupWise 32-bit Windows client. Formativ's Visual Basic-like development environment also allows you to create custom toolbar buttons, menu items, and more without requiring any programming.


Topics

Advansys Formativ, e-mail, GroupWise custom development, third-party add-ons

Products

Advansys Formativ, Novell GroupWise 6 and 5.5

Audience

network administrators, integrators, and developers

Level

intermediate

Prerequisite Skills

familiarity with integrated development environments

Operating System

n/a

Tools

none

Sample Code

yes

Introduction

Advansys Formativ introduces applets to Novell GroupWise 6 and 5.5, providing a new way for developers and users to automate and extend the GroupWise 32-bit Windows client. As more organizations adopt Novell GroupWise as their collaboration product of choice, developers are receiving an ever-increasing number of requests to automate, extend, and integrate GroupWise. This increasing demand is placing more pressure on development teams worldwide. Formativ was developed in response to this demand.

Formativ's applet language is based on industry standards and open technologies, which means that users are able to access greater functionality when building with GroupWise. By building solutions directly on top of GroupWise and by using a unified development tool, developers can enjoy shorter development cycles and have more satisfied users.

In many cases, Formativ removes the need for developers to be familiar with traditional GroupWise APIs, especially the Custom Third-Party Objects (C3PO) API. Formativ handles custom toolbar buttons and menu items in the GroupWise client. Formativ also provides the capability to assign applets to standard GroupWise events, such as "On Send" and "On Compose". This level of integration is achieved without any programming whatsoever.

Formativ ships with a number of pre-written applets which address common GroupWise enhancement requests. These applets include multiple signatures, template support, mass e-mailing, personalized mass e-mailing, search and replace within messages, holiday importing, and data import/export. The pre- written applets not only teach developers the basics of creating solutions with Formativ, but they also provide immediate functionality out of the box. Source code is included to allow users to modify the shipping applets to work as desired.

Formativ also provides an applet recording facility. Users can simply start recording and Formativ will remember the actions carried out in the GroupWise client. When the recording stops, an applet is automatically built that can be played back as-is, or edited to become the basis for a more complex applet.

Advansys Formativ is fully Novell eDirectory/NDS enabled and Novell YES, Tested and Approved. This means administrators may use Novell eDirectory to securely and centrally manage Formativ.

Working with Advansys Formativ

Advansys Formativ is both a development platform and a run-time extension for Novell GroupWise 6 and 5.5. It consists of a Custom Third-Party Object (C3PO) that provides applet development and execution.

Formativ consists of four main areas of functionality:

  • The applet component, which the Formativ C3PO server creates and executes and which runs in the GroupWise process.

  • A set of pre-written applets, representing out-of-the-box solutions for key GroupWise enhancements. The applets can be used as-is or they can be modified by end-users.

  • The development component, providing a new development environment for GroupWise. Completely integrated with the GroupWise client, Formativ appears as a natural extension to GroupWise.

  • The management tools. Formativ is fully eDirectory-enabled and is managed centrally using either ConsoleOne or the NWAdmin utility. Corporate applets may be stored in the directory. Individual, group, Organizational Unit (OU), or Organization (O)-wide client settings are also securely stored and managed in eDirectory.

About Formativ Applets

This section explains more about the Formativ applets component.

Standard Applet Language.  The Formativ applet language is syntactically compatible with Microsoft Visual Basic Script. In addition, the language contains over 500 functions and procedures that provide access to GroupWise's message store, user interface, and event system interfaces. The applet language also has support for building dialogs and forms.

Because Formativ's applet language is a true programming language, users are able to use standard programming techniques including variables, control structures, error handling, functions, and procedures. For example, the following applet creates three new GroupWise e-mail messages in the client. The subject of each new message changes to indicate the order in which they were created.

Sub Main(Client, GWEvent)

  Dim Msg
 
  for x = 1 to 3 

    ' Create a new visible email message
    GroupWise.NewMail

    ' Access the new message
    Set Msg = GroupWise.ComposingItem
    if Msg is Nothing then
      MsgBox("No composing item available")
    else
    
      ' Set a custom subject
      Msg.Subject = "This message No. " & x
      Msg.BodyText = "This is the body text."
      Set Msg = nothing
    end if
  next

End Sub

Based on COM. The Formativ applet language is based on COM (Component Object Model). This means applets are able to access any COM-compatible services, such as word processors, spreadsheets, databases, CRM (Customer Relationship Management), and financial applications. This makes Formativ a powerful tool for integrating GroupWise with third-party applications and systems.

For example, an applet may extract address book information from GroupWise and create a corporate directory in Microsoft Word using Word's COM automation features. Likewise, you can develop an applet which categorizes appointments from the GroupWise calendar and calculates durations and other statistics. It can then create a spreadsheet in Microsoft Excel to display the results for further analysis or presentation.

Access to Underlying GroupWise APIs. The Formativ applet language provides easy access to the native GroupWise application programming interfaces. The GroupWise Object API, Administrative Objects API, and tokens are fully exposed should they need to be accessed in an applet. The majority of functionality traditionally exposed by the C3PO interface is available to Formativ applets.

Access to GroupWise Information. The Formativ applet language simplifies access to GroupWise data. For example, accessing address book information has traditionally been difficult, especially when using foreign language versions of GroupWise. Field definitions used to identify address book fields are language dependent, which makes access complicated. The Formativ applet language simplifies address book access via the use of several language-independent objects and methods.

The following code snippet illustrates adding a new contact to an address book. This applet code will work with any language version of the GroupWise client.

Sub Main(Client, GWEvent)
    
        Dim AddressBooks
        Dim AddressBook
        Dim oAddressBookEntries
        Dim oAddressBookEntry
    
        Set AddressBooks = GroupWise.AddressBooks
        
        On Error Resume Next
        Set AddressBook = AddressBooks.Item("Test Book")
    
        if IsEmpty(AddressBook) then
            MsgBox("Could not locate that address book")
        else
            MsgBox(AddressBook.Name)
    
            Set oAddressBookEntry = AddressBook.AddContact("Bill Smith")
            with oAddressBookEntry
                .FirstName = "Bill"
                .LastName = "Smith"
                .Organization = "Smith Inc"
                .EmailAddress = "bill@Smith.com"
                .EmailType = "NGW"
                .Address = "This is the address"
                .City = "The city"
                .State = "The state"
                .ZipCode = "The zip"
                .Country = "The country"
                .Department = "The dept"
                .Title = "The title"
                .MailStop = "The mailstop"
                .Greeting = "The greeting"
                .OfficePhone = "555-7777"
                .HomePhone = "555-8888"
                .CellPhone = "555-9999"
                .FaxPhone = "555-0000"
                .Comments = "This is the comments field"
            end with
        end if
    
        Set AddressBooks = nothing
    
        MsgBox("Done")
    
End Sub

The Formativ Business Solutions Pack

Pre-written solutions are included in the Formativ Business Solutions Pack, a set of over 20 applets that address common GroupWise enhancement or automation requests. The product includes full source code which users and developers can examine to learn how to develop using Formativ, or to modify the applets to meet their needs more closely.

The Formativ Business Solutions Pack applets include:

  • Adding notes to GroupWise items

  • Address book publishing using Microsoft Word

  • Anti-spam rule creation

  • GroupWise mail merge

  • Address book searching

  • Forwarding multiple messages

  • Importing appointments into the GroupWise calendar

  • Mass e-mailing

  • Personalized mass e-mailing

  • Templates

Formativ Development Environment

The Formativ Admin Integrated Development Environment (IDE) is called FormativCentral and consists of an applet editor and GroupWise integration tools. The IDE integrates with the GroupWise client, and you can access it from either the main GroupWise toolbar or from a menu item.

Administrators can use the eDirectory management utility to remove the IDE from the GroupWise client, thereby providing applet creation only to authorized users. You can simplify this restriction by installing the Formativ Client, a run- time version which can execute only encoded applets that are produced by the Formativ Admin.

FormativCentral, the Formativ IDE, is shown in Figure 1.

Formativ's Integrated Development Environment (IDE).

The left side of the IDE shows the applet libraries to which this user subscribes. An applet library is a collection of applets, stored either on disk or in eDirectory. The right side of the IDE consists of a tabbed window with the Applet Editor, the Integrations Editor, and the applet Properties Editor as page selections.

The Applet Editor. The Applet Editor page contains a full-featured editor that includes syntax highlighting, an integrated debugging window, and code templates, as shown in Figure 2.

The Applet Editor page.

The Integrations Editor. The Integrations Editor page is used to integrate an applet with the GroupWise client (see Figure 3).

The Integrations Editor page.

You use the Integrations Editor to add buttons to toolbars, new items to context (right-mouse click), and standard menus that execute applets. You can also use the Integrations Editor to associate applets with GroupWise events. For example, an applet can be automatically executed when an item is sent or composed, or when new messages arrive in the mailbox. Over 23 events are supported for the standard GroupWise message types.

You can integrate applets with the GroupWise client by simply pointing and clicking. No programming is required, nor do you need any knowledge of the GroupWise event system. Integration information is stored within each applet. This means the integrations travel with the applets, making integrating new applets as simple as making them available to the user. In some cases it may be necessary to restart the GroupWise client to activate new integrations; when this is the case, the Formativ client advises the user that a restart is required.The Integrations Editor is also used to specify whether an applet should appear on the new GroupWise Favorites menu and the Run menu. All integrations can be disabled from the Integrations Editor.

The Property Editor. You use the Property Editor page to define the description, help hint, and button image for an applet (see Figure 4).

The Properties Editor page.

The Description appears throughout the GroupWise user interface: on toolbar buttons, on menu items, as well as on the Run and Favorites menu. The Help hint appears in pop-up button bar hint windows and in menu item mouse-overs in the GroupWise client. The selected image appears on buttons within the GroupWise client, which are defined using the Integrations Editor. A large number of predefined images are provided and it is possible to add new images to the collection.

Management Tools

Formativ is fully eDirectory-enabled. This means that system administrators can use eDirectory utilities (ConsoleOne or NWAdmin) to centrally manage Formativ applet libraries and assign functional rights to users within their organizations. In addition, tools and documentation are provided that makes mass deployment simple using ZENworks or the GroupWise AddOn facility.

Formativ's eDirectory administration and distribution capabilities include the ability to do the following:

  • Deploy Formativ to hundreds or thousands of users' desktops from a central location

  • Control which Formativ features are enabled for individuals, groups, Organizational Units, or Organizations from a central location

  • Share corporate applets to individuals, groups, Organizational Units, or Organizations from a central location

New eDirectory Objects

The Formativ installation extends the eDirectory schema to include three new objects, which are used to manage Formativ. No base eDirectory objects are modified, which means that, if desired, you can completely remove all Formativ eDirectory objects and attributes from the tree. The following types of objects are created when you extend the schema for Formativ:

  • Configuration objects. These contain information about which applet libraries are available to users, as well as the Formativ features which are to be available to those users (such as the ability to create applets or to run in GroupWise remote mode).

  • Applet Library objects. These are used to store one or more Applet objects.

  • Applet object. An Applet object represents a single applet.

Each object type is described below.

The Configuration Object

The Configuration Object is used to store and control:

  • The details of one or more applet libraries to which a user will have access

  • The Formativ features that are available to a GroupWise user, such as the ability to create personal applets

Every Formativ user who needs access to shared applets in eDirectory must have access to a single Configuration object. A user cannot have access to more than one Configuration object.

The Configuration Settings page is shown in Figure 5.

The Configuration Object properties page.

You use the Associate button is used to assign the Formativ Configuration object to a User, Group, OU, or O eDirectory object. Assigning the Configuration object to a target object performs the following functions:

  • Removes any old Configuration object references from the target object's "See Also" property

  • Adds the Configuration object reference to the target object's "See Also" property

  • Ensures that the minimum required rights ( [Entry] Browse, [Property] Read, and Compare) are assigned to the target object's "See Also" property

Different users may use different Configuration objects. For example, power users may use a Configuration object that allows for applet creation, while other users are only able to execute applets that have been allocated to them.

Administrators may even set up a Configuration object that completely removes all Formativ toolbar buttons and menu items from the GroupWise client, leaving only buttons, menu items, and event triggers that are defined by the applets to which they subscribe. This has the effect of making applet functionality appear to be new GroupWise features.

The Configuration object's Applet Libraries page specifies which applet libraries are available to any user associated with the Configuration object. By using the Add or Remove buttons, you can add or remove references to Formativ Applet Libraries. Figure 6 shows a Configuration object which makes three applet libraries available.

The Configuration object Applet Libraries page.

The Applet Library Object

The Applet Library object is a container used to group Formativ Applet objects. For example, you can create an Applet Library object for each OU in the tree, plus a master Library object that is shared by all users in the tree (see Figure 6).

Note: Applet libraries are not related to GroupWise document management libraries.

The Applet Library object also allows you to specify one or more users, called Formativ Library Administrators, who are authorized to create, edit, and delete applets within the library (see Figure 7).

The Applet Library object administrators.

The Applet Object

The Applet object represents a single applet and is placed in one or more Applet Library objects, which the Formativ client creates and manages. Figure 8 shows the Applet Properties page for this object.

The Applet Properties page.

When GroupWise starts, Formativ makes local copies of the applets that are contained in the eDirectory applet libraries to which the user subscribes. These applets are encrypted during the copy process so they cannot be discerned or edited by end-users. Formativ executes the local copies to reduce network traffic and give maximum responsiveness for end-users.

Example: Multiple Signatures Applet

Many GroupWise users have requested the ability to use different signatures when creating or replying to e-mail. However, GroupWise presently supports only one signature per account. The Multiple Signatures applet example presented in this section was written in one day to address this need. This applet demonstrates several key features of Formativ, including the ability to:

  • Add toolbar buttons to GroupWise without writing any code

  • Subscribe to GroupWise events without writing any code

  • Access GroupWise messages programmatically

  • Create a custom user interface

  • Use third-party services from within an applet

Writing the Applet

The source code for the applet is relatively simple. It was decided that each signature should be stored either as a simple text file or as an HTML file. Signature files could be stored on a local workstation or in a shared location. If desired, the applet could even be modified to extract the signatures from eDirectory using calls to the Netware NWDirCtrl ActiveX control.

The applet needed some "intelligence" to ensure that signatures are inserted at the appropriate location in the message (depending on the context in which the message is being created). If the user is composing a new message, the signature is added to the end of the message. If the user is replying to a message, the signature is inserted at the start of the existing message before the original message text.

This was achieved through the GWEvent parameter, which is passed to every applet and which contains the active GroupWise context at the time the applet executes. The Multiple Signatures applet checks this parameter to see if the context is a ‘GW#C#REPLY', which indicates the user is replying to a message.

The applet uses one of the built-in user interface elements-a listbox-to display the available signatures, from which the user can select the desired signature. The applet then uses the COM-based filesystemobject call to physically access the text file containing the signature.

Integrating the Applet with GroupWise

It was decided that the applet should be executed automatically when the user composes a new e-mail message, or replies to an existing e-mail message. The applet does this by checking the On Compose and On Reply events under the mail context in the Formativ IDE. Figure 3 shows the Multiple Signatures applet selected in the Formativ IDE, with the On Compose event checked on the Integrations tab. (Note that other events can also be selected but may not be appropriate for this applet.)

Distributing the Applet

Since this is a widely requested enhancement, all users in the organization require access to this applet. Accordingly, it was added to a corporate eDirectory applet library to which all users subscribed. Personal signature files are stored in each user's personal directory on the network and the applet source was modified to access these signature files accordingly. On starting the GroupWise client, users saw that the new signature capability was automatically available. Since Formativ Admin or Formativ Client (run-time) was already installed on each user's machine, there was no need to install or configure any further software on any workstation.

Using the Applet

The applet is made available to users via Formativ's eDirectory management capabilities, making its operation automatic. When a user either composes a new e-mail message or replies to an existing message, the applet executes and the signature selection dialog displays, similar to Figure 9.

The Multiple Signature selection dialog box.

The user selects the appropriate signature, which is inserted in to the e-mail message in GroupWise. The result is illustrated in Figure 10.

The automated signature is placed in a new e-mail message.

Conclusion

Advansys Formativ represents a new paradigm for GroupWise development. Formativ makes GroupWise development easier, faster, and more cost effective than was previously possible. Formativ's highly integrated architecture makes adding GroupWise toolbar buttons, menu items, and subscribing to GroupWise events simple, requiring no programming. Formativ's open architecture makes it an ideal tool for integrating GroupWise with other applications. Finally, Formativ's high level of eDirectory integration makes centralized management simple, secure, and cost effective.

For more information about Advansys Formativ, visit the company's Web site at http://www.advansyscorp.com.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates