You are on page 1of 145

Administration

& Operations Manual


v3.0.04
PA G E 2 O F 145

FirM Administration Manual v3.0 © 2009 HADSL


Table of Contents
Introduction ..................................................................................................7
The Chairmanʼs Introduction .................................................................................................................7
What is FirM? ........................................................................................................................................7
How does it work? ................................................................................................................................7
What does FirM do? .............................................................................................................................7
How does FirM handle large groups? ...................................................................................................8
What are profiles? How are they used? ...............................................................................................8
Does FirM work with Domino 5, 6, 7, 8 and 8.5? ..................................................................................9
Feature List v3.0 ...................................................................................................................................9
What does FirM consist of? ................................................................................................................12
Target Audience ..................................................................................................................................12
How FirM Works .................................................................................................................................12

Installing FirM .............................................................................................13


Introduction .........................................................................................................................................13
Who should install FirM? ....................................................................................................................13
How this product is delivered ..............................................................................................................13
Installation & Configuration of FirM .....................................................................................................13
Quick Installation Process ...................................................................................................................13
Stage 1: Encryption key creation ........................................................................................................14
Stage 2: Initial install of FirM ...............................................................................................................15
Stage 3: Basic FirM Configuration. .....................................................................................................18
Stage 4: FirM System Profiles Set Up ................................................................................................19
Stage 5: FirM User Profiles Set Up .....................................................................................................21
Stage 6: FirM Group Profiles Set Up ..................................................................................................22
Importing Certifiers & Passwords ........................................................................................................24

System Configuration ................................................................................25


Target Audience ..................................................................................................................................25
Introduction .........................................................................................................................................25
System Configuration – Databases ....................................................................................................25
System Configuration - Servers ..........................................................................................................26
System Configuration - Directories .....................................................................................................27
System Configuration – Admin Settings ..............................................................................................27
System Configuration – Billing ............................................................................................................30
System Configuration – Name Validation ...........................................................................................31
System Configuration – Workflow .......................................................................................................32
System Configuration – Archiving & Expiry .........................................................................................33
System Configuration – Active Directory (AD) ....................................................................................34
System Configuration – BlackBerry ....................................................................................................35
System Configuration – License .........................................................................................................35

Administration Tools ...................................................................................36


Config Tab ...........................................................................................................................................36
Profiles Tab .........................................................................................................................................36
Monitoring Tab ....................................................................................................................................36
Import Tab ...........................................................................................................................................37
'Group Restore' Tab ............................................................................................................................37
BlackBerry Management Tab ..............................................................................................................37
System Views Tab ...............................................................................................................................38

Configuring System Profiles ......................................................................39


Common System Profile Tab – “Fields” ...............................................................................................39
ID Profiles ............................................................................................................................................39
Country Profiles ...................................................................................................................................41
Certifier Profiles ...................................................................................................................................41
Location Profiles .................................................................................................................................41
Business Group Profiles ......................................................................................................................42
Company Profiles ................................................................................................................................42
Internet Address Profiles .....................................................................................................................42
Group Profiles .....................................................................................................................................42
Automatic Recertification Profiles .......................................................................................................43
Configuring Notification Profiles ..........................................................................................................44
Configuring Agent Trigger Profiles ......................................................................................................44

Creating a new Request ............................................................................46


Creating a single request ....................................................................................................................46
Creating Bulk requests ........................................................................................................................46
Importing Transactions using CSV .....................................................................................................46

FirM Domino User Transactions ................................................................48


Common Tab - Authorisation ...............................................................................................................48
Name Construction and Token Replacement ......................................................................................49
User Create .........................................................................................................................................50
User Cross-Certify ...............................................................................................................................57
User Modify .........................................................................................................................................58
User Disable .......................................................................................................................................58
User Enable ........................................................................................................................................60
User Delete .........................................................................................................................................61
User HTTP password reset .................................................................................................................65
User Mail file Grant Access .................................................................................................................66
User Move Domain .............................................................................................................................68
User Move in Hierarchy .......................................................................................................................69
User Move Location ............................................................................................................................71
User Move Server ...............................................................................................................................72
User Password Digest Enable ............................................................................................................74
User Password Digest Disable ...........................................................................................................75
User Password Digest Reset ..............................................................................................................75
User Recertify .....................................................................................................................................76
User Rename Common Name ...........................................................................................................77
User Resend User ID and Password ..................................................................................................79
User Roaming Enable .........................................................................................................................80
User Roaming Disable ........................................................................................................................82

FirM Group Transactions ...........................................................................83


Group Create ......................................................................................................................................83
Group Modify ......................................................................................................................................85
Group Manage Members ....................................................................................................................86
Group Delete ......................................................................................................................................87

FirM Application Transactions ....................................................................89


Application Create ...............................................................................................................................89
Application Modify ...............................................................................................................................90
Application Delete ...............................................................................................................................91

Active Directory Overview .........................................................................93


Architecture .........................................................................................................................................93

Installing & Configuring Active Directory ....................................................94


Activating and Configuring Active Directory ........................................................................................94
Installing the FirM AD Component ......................................................................................................95
Heartbeat Task ..................................................................................................................................101
Share Names ....................................................................................................................................101
The FirMAD LSX DLL .......................................................................................................................102
FirM AD Synchronisation .........................................................................103
Architecture and Workflow ................................................................................................................103
Configuration ....................................................................................................................................104

Active Directory Transactions ..................................................................106


AD User Create ................................................................................................................................106
AD User Disable ...............................................................................................................................109
AD User Enable ................................................................................................................................110
AD User Password Reset .................................................................................................................111
AD User Modify .................................................................................................................................111
AD Group Create ..............................................................................................................................112
AD Group Delete ..............................................................................................................................113
AD Group Modify ..............................................................................................................................114

BlackBerry Overview ...............................................................................116


Architecture. ......................................................................................................................................116
Installing the BlackBerry interface ....................................................................................................116

BlackBerry Transactions ..........................................................................118


Authorisation .....................................................................................................................................118
BlackBerry Provision ........................................................................................................................118
BlackBerry Enable ............................................................................................................................119
BlackBerry Disable ...........................................................................................................................119
BlackBerry Reset Password .............................................................................................................120
BlackBerry Delete .............................................................................................................................120

The FirM Application Monitor ...................................................................122


The Application Monitor Database ....................................................................................................122
The Application Usage Database .....................................................................................................124

FirM Group Monitoring .............................................................................125


Group Monitoring Explained .............................................................................................................125
Group Monitoring Components .........................................................................................................125
Setting up Group Monitoring .............................................................................................................125
Selecting the Groups to Monitor ........................................................................................................126
Limitations of Group Monitoring ........................................................................................................126

ID Backup, Refresh and Escrow .............................................................127


ID Backup .........................................................................................................................................127
ID Escrow ..........................................................................................................................................129
The ID Refresh Process ...................................................................................................................130

User MailFile Quota Management ...........................................................131


Non-Person Document Update Mode ...............................................................................................131
Person-Document Update Mode. .....................................................................................................131

The Automatic User Recertification Engine .............................................132

The Expiry Engine ...................................................................................133


The User Expiry Engine ....................................................................................................................133
The Group Expiry Engine .................................................................................................................133

Troubleshooting & Support ......................................................................134


The Log Database ............................................................................................................................134
Mailing Log Documents to Support ..................................................................................................134
Document types within the Log Database ........................................................................................134
Raising a support call ........................................................................................................................134
Known Issues ....................................................................................................................................135

FirM Databases .......................................................................................136


Request Processor ...........................................................................................................................136
Log Database ...................................................................................................................................136
Extended AdminP processor .............................................................................................................136
Group Registry ..................................................................................................................................136
Monitored Group Shadow Repository ...............................................................................................137
Certifier Repository ...........................................................................................................................137
Password Repository ........................................................................................................................137
ID Repository ....................................................................................................................................137
ESCROW Database .........................................................................................................................138
Audit Repository ................................................................................................................................138
Archive Repository ............................................................................................................................138
Billing Database ................................................................................................................................138
Deleted Records Database ..............................................................................................................138
Application Monitor ...........................................................................................................................138
Application Usage Log ......................................................................................................................138

The AdminP Push around Agent ..............................................................139


Overview ...........................................................................................................................................139
Configuration of AdminP Push around Agent ...................................................................................139

Interfacing with FirM ................................................................................141


Triggering your agents from a FirM process .....................................................................................141
Using the CSV interface programmatically .......................................................................................141
Create FirM requests from your own programs. ...............................................................................143
Creating Transactions Using Web Services ......................................................................................144
1 INTRODUCTION PA G E 7 O F 145

1. Introduction
1.1. The Chairmanʼs Introduction
Congratulations on choosing and using FirM - the premier solution for optimising the management of your
Domino infrastructure. Over the R5 to nd8.5 releases of Domino the Lotus arm of IBM has worked hard to
increase the value that can be derived from your Domino infrastructure. We at HADSL are committed to
ensuring that you can unlock this value without the penalty of increased administration costs, in fact, with
FirM you can match the value gains from your Domino infrastructure with equal gains in value in your
Domino administration. Our designers and architects not only track technical changes in Domino but also
follow best practice usage patterns in IT management in general and Domino Administration in particular; to
bring you a truly effective solution for controlling and reducing your administration and management costs.
With HADSL solutions you will not only keep pace with the market, but move ahead of the market in best
practice administration and management.
At HADSL we value each and every one of our customers, to make sure that you get the best from FirM and
HADSL, make sure that you give us any feedback, both good and bad on the use of any of our products or
services. We particularly urge you to let us know how you would like to see our products develop. Keeping
us in touch with your problems helps us to make sure that our solutions make your life easier.
Ian Tree,
Chairman, HADSL

1.2. What is FirM?


FirM is an Identity Management suite for Lotus Notes/Domino designed to automate group and user
management. It enables the delegation of most user and group-related administrative functions to non-IT
personnel thereby providing considerable cost savings without any loss of security and with increased
service levels.

1.3. How does it work?


FirM presents permitted end-users (Requesters) with simple Domino-based forms to fill in. Optionally, other
users (Authorisers) authorise and accept these change requests. The request is then passed to a back-end
processor, which:
 validates that the request is allowed
 validates the request security
 performs checks to ensure that the request will not cause problems
 performs the request
 informs the Requesters and Authorisers of the change

1.3.1. How does this help me cut costs?


FirM reduces Total Cost of Ownership (TCO) by reducing the administrative burden and overhead costs. It
moves Domino systems closer to a ʻno touchʼ user administration model by moving the user administration
and group administration functions out of the expensive corporate IT departments and into the business units
themselves.
FirM significantly decreases the amount of time it takes to set up a Domino user. FirM is automated and
always available so remote users in another time zone don't have to wait a business day for new users to be
created.
FirM increases security by removing all certifiers and certifier passwords from the majority of Domino
administrators.
The quality of users created by FirM is guaranteed. There are no broken mail files, no incorrect templates,
and all required information is guaranteed to be complete and correct.
FirMʼs ʻprofilesʼ ensure that naming standards and database placement rules are enforced resulting in a
known and coherent infrastructure.

1.4. What does FirM do?


FirM allows non-technical users (“Requesters”) a simple end-user interface to perform complex user, group,
application, active directory and Blackberry based transactions.
FirM Administration Manual v3.0 © 2009 HADSL
1 INTRODUCTION PA G E 8 O F 145

1.4.1. Why is FirM the best Domino User and Group Management tool?
 FirM is very easy to install and implement and does not require expensive code-changes to reflect
your business model.
 FirM is very easy for the end-user to use.
 FirMʼs operations are based on ʻprofilesʼ held within FirM. Profiles pre-define all the technical
infrastructure-based settings of a particular type of request. This means that a business user
making a request, say, to create a new user, only needs to supply information relevant to their
business needs. In the case of creating a new user all that is required is the userʼs name.
 FirMʼs ʻdynamic fieldsʼ enable the FirM Administrator to specify in a profile that, when a request is
made, information specific to the request is provided by the Requester. For example, the Requester
may be presented with a question such as ʻWhat is the personʼs new office telephone number?ʼ.
The supplied information, in this case the telephone number, is then written to the personʼs
document in the appropriate field.
 FirM is based on LotusScript, which means that dedicated add-in tasks do not need to be run on the
server. Add-in tasks are a frequent cause of instability.
 FirM can run on multiple servers with failover capability, giving reliable 24x7 operations.
 At particular stages in a request, FirM can run Domino agents in designated databases. For
example, when a ʻUser Createʼ request succeeds, FirM can run an agent in a designated database
and pass it all the information from the request document.
 FirM may be integrated into other applications using object-oriented LotusScript classes. This
enables group-management functionality to be simply added to an in-house application, say a web-
user management application for the intranet, by writing less than 20 lines of LotusScript code.
 FirM supports a Domino multi-domain environment.

1.4.2. How does FirM take advantage of load-balancing and server clusters?
FirM fully exploits Domino load-balancing and server clusters. The following happens when a user is
created:
 The new name is checked for duplicates in all Domino directories. If the name already exists then
numbers are optionally added to ensure uniqueness
 the name elements are optionally checked against an external database, such as a global short
name directory
 the user is added to relevant groups based on information in the profile
 profile-based information is used to query the directory in order to determine the least-loaded server
 The user's mail file is created using a profile-specified template name and user access level. If that
server is part of a cluster and the configuration variable ʻAdd mail file to all clustersʼ is set in the
System Configuration, then replica mail files are created on all cluster mates

1.5. How does FirM handle large groups?


FirMʼs group management capability easily accommodates large groups. Domino limits group size to less
than 16K of information so when a group approaches this size, FirM automatically ʻspawnsʼ subgroups. For
example, when a group called ʻMail Usersʼ gets close to a pre-defined limit, FirM will move the existing
members to a new group called ʻMail Users_01ʼ, and add ʻMail Users_01ʼ as a member to ʻMail Usersʼ. FirM
does not limit the number of spawned subgroups.

1.6. What are profiles? How are they used?


Profiles are templates for FirM requests. A profile is created for a specific request, say, creating a new user
in the marketing department. Then, when a specific user is to be created, the request is made using that
profile. The profile contains all the technical infrastructure-related information and the Requester simply
provides the business-specific information needed to complete the request, in this case, the userʼs name and
perhaps other user-related information like their phone number.
A profile is a collection of rule information that defines:
 The name of the profile as seen by the Requester. This will be a meaningful name in the business
context such as ʻNew marketing user in Londonʼ instead of ʻAppSev01Mar/Lon/Business/IBMʼ
 Who is authorised to use this profile to make requests
 Who needs to authorise requests made with this profile
FirM Administration Manual v3.0 © 2009 HADSL
1 INTRODUCTION PA G E 9 O F 145

 Static fields, i.e. the pre-defined content of specific fields on the person document which this profile
creates or modifies.
 Dynamic fields, i.e. the content of fields on the person or group document being created or modified,
which is provided by the Requester at the time a request is made
 The groups to which a newly created person should be added.

For the ʻUser Createʼ profile, a number of sub-profiles can be specified:


 The ʻID Typeʼ sub-profile. The ID Type sub-profile defines different types of IDs. For example, the
ID Types ʻPermanent Staffʼ and ʻTemporary Staffʼ would have different certificate expiration periods,
ID file encryption strengths and so on
 the Certifier sub-profile specifies the certification hierarchy for a user
 The Location sub-profile specifies which server(s) a new user should be created on. If more than
one server is specified then the server with the fewest users will be used. If the selected server is a
member of a cluster then replicas of the user mail file will be created on all cluster mates, if so
specified in the configuration profile.
 the Country sub-profile allows different groups, static fields and dynamic fields to be used based on
country
 the Company sub-profile allows different groups, static fields and dynamic fields to be used based
on company
 The Business Group sub-profile allows FirM administrators to define different business rules for
different business groups, and to enforce control whilst retain complete flexibility.

1.7. Does FirM work with Domino 5, 6, 7, 8 and 8.5?


Currently, the infrastructure in which FirM operates has to be Domino 5.0.8 or better, and the Requesters
must be using Notes 5.0.8 or better. It has been tested on a cross-platform, cross-domain infrastructure that
includes Domino 5.0.11 and Domino 6.0, 6.5, 7.0. 8.0.x and 8.5 servers, without difficulty.

1.7.1. Upgrading to R6, R7, R8, or R8.5 will reduce administration effort in any case ?
Case studies and reports have shown that Domino sites upgrading to newer versions of Lotus Domino can
show significant TCO decreases. These sites report that many facilities within the new administration client
substantially increase the productivity of their support staff. Many sites will have reduced TCO because they
are able to take advantage of the infrastructure consolidation that is possible with later releases. Admin
client utilities for registering users, and many enhanced AdminP functions too will reduce TCO.
However, this does not solve the problem addressed by FirM - a skilled and trained administrator is still
needed to be able to use the Notes administration client. The Notes administration client is a complex,
sophisticated and highly technical tool. Not the sort of software that a business user would want to have to
use and who, because the tool is inappropriate, would make many errors resulting in replication conflicts and
duplicated groups.
FirM provides a ʻzero technical knowledgeʼ interface to Domino administration, and does so in a safe and
secure way. FirM may be easily operated by non-technical business staff that do not need any knowledge or
skills in Domino group and user administration.
FirM, in fact, extends in many ways the capabilities of the administration client. Groups are only ever edited
centrally so replication conflicts should not occur. Also group membership rules are enforced as are naming
conventions. Additionally, a full audit trail and request history is maintained for actions carried out against
the address book.
FirM complements and significantly enhances the core administration functionality of R6 enabling significant
further reductions in TCO whilst simultaneously delivering an increase in system control.

1.8. Feature List v3.0


FirM is a comprehensive Federated Identity and Resource manager for Lotus Domino.
FirM allows you to create profile information on all user and group operations and allow delegation to non-
technical users, in a completely automated, secure and audited manner, thus reducing administrator burden
and increasing service level
At v3.0 release, it performs the following operations:

FirM Administration Manual v3.0 © 2009 HADSL


1 INTRODUCTION PA G E 10 O F 145

1.8.1. User Operations


 User Create. Full Lotus domino user creation with
 Load balancing - given a selection of Lotus Domino serves, FirM will choose the one with least
users.
 Cluster mail file creation on one or more server cluster mates.
 ID and Password secure storage & distribution to mandatory or optional recipients.
 Adding the new user to specified groups.
 Setting specified person document fields.
 Enable ND6 style Roaming User.
 Create Password Digest.
 And sending a customised Welcome Message to the user.
 User Delete. A multi-ability deletion process, including full retention of person document, group
membership, optional archiving of mail file to archive server, optional "data owner" workflow cycle,
allowing another user to view the mail file for a limited period of time
 User Modify. Allow modification of specific fields on a users' person document for directory
maintenance.
 User Http Password Reset. Allow a non-administrator to set a new internet password for a user
 User Resend User ID and Password. Allow the sending of the latest user ID and password from the
secure repositories.
 User Disable. The addition of a user to a terminations group, preventing user access to your Lotus
Domino environment.
 User Enable. The removal of a user from a terminations group, allowing user access to your Lotus
Domino environment
 User Move in Hierarchy. Recertify a user to a new Lotus Notes certificate hierarchy, with no
administrator intervention whatsoever.
 User Rename common Name. Rename a users' common name.
 User Recertify. Recertify a user with his existing certificate to extend access to your Lotus Domino
environment.
 User Move Server. Move a user (and their mail files) to a new Lotus Domino server automatically.
 User Move Location. Move a user (and their mail file) from one location to another, optionally
removing the user from location specific groups and adding the user to new location specific groups.
Also recertify the user to a new hierarchy if required.
 User Grant Mail File Access. Grant temporary mail file access to a users mail file to another person.
 User Password Digest Enable. Enable user password periodic changes for a user
 User Password Digest Disable. Disable user password periodic changes for a user
 User Password Digest Reset. Allow access to a user if they have exceeded their password change
time period.
 User Roaming Enable. Set the user to a "Roaming" style ND6 user. .
 User Roaming Disable. Stop the user being a "Roaming" style ND6 user. .
 User MailFile Quota. Set a users Mail File Quota.

1.8.2. Group Operations


 Group Create. Create a new Lotus Domino group with full authentication and delegation rights.
 Group Modify. Modify a groupʼs attributes.
 Group Manage Members. Add and remove users from groups
 Group Delete. Remove a group from the Lotus Domino Directory

FirM Administration Manual v3.0 © 2009 HADSL


1 INTRODUCTION PA G E 11 O F 145

1.8.3. Application Operations


 Mail in Database Create. Create a new application and all relevant replicas from a list of allowed
templates. Populate the applications ACLʼs and grant modification access to the application owner.
Set the application quota and warning thresholds. Create a directory mail-in database entry in the
Domino directory.
 Mail in Database Manage. Modify a mail in database.
 Mail in Database Delete. Remove a mail in database and all replicas, the groups associated with this
mail-in database, and the directory mail-in document itself.
 Scanning all applications and providing user usage and ACL change log information across all
databases in your environment.

1.8.4. Active Directory Operations


 User Create. Create a new user in Active Directory, checking for uniqueness, in a specified
container. Create the users home drive and assign sharing rights. Update any Active Directory
attribute associated with this person, and optionally add him to AD groups.
 User Disable. Prevent a user logging into Active Directory
 User Enable: Allow a user to log into Active Directory
 User Modify. Change an attribute on the users' Active Directory record
 User Password Reset: Set a users Active Directory password.
 Group Create: Create an Active Directory group
 Group Manage Members: Add or remove users from Active Directory groups

1.8.5. Blackberry Support


As of version 3.0, FirM supports the following Blackberry handset operations:
 Provision Handset
 Enable Handset for user
 Disable Handset
 Reset password handset
 Delete Handset
 Kill Handset

1.8.6. Automated Tasks


 Automatic User Recertification: Users can be automatically recertified should they match an
administrator-defined profile
 User Expiration. You can specify when a User should be expired from the system. A pre-set number
of days beforehand, an automated message will be sent to the person's manager asking them to
confirm or reject deletion of this user. Should the manager do nothing or confirm deletion, the user is
deleted on that specified date.
 Group Expiration. You can specify when a Group should be expired from the system. A pre-set
number of days beforehand, an automated message will be sent to the group's owner asking them to
confirm or reject deletion of this user. Should the manager do nothing or confirm deletion, the Group
is deleted on that specified date.
 AdminP Push around. FirM supports multi-domain environments, and allows the administrator to
specify which AdminP transactions should be copied between the various domain admin4.nsf
databases.

1.8.7. Security Features


The ID Repository, Password Repository and Certifier Repository are all encrypted databases with each
database using a different encryption key.
The system maintains a complete audit history of every processed transaction.

FirM Administration Manual v3.0 © 2009 HADSL


1 INTRODUCTION PA G E 12 O F 145

1.9. What does FirM consist of?


FirM consists of 15 or so Lotus Notes databases (depending on installation type), of which four need to be
replicated around your environment. See the section titled “FirM Databases” on page 152 for more
information.

1.10. Target Audience


This document is targeted at the FirM Administrators, likely to be Notes Super-Administrators who will
configure, monitor and maintain FirM.
It is assumed that these people are:
 Notes Administrators with Notes Administration access to their Domino environments
 Skilled Notes Administrators with at least three years experience of Domino Administration, PCLP
accreditation for Release 5 onwards or both.

1.11. How FirM Works

1.11.1. Introduction
The Federated Identity and Resource Manager is a Delegated Proxy Administration system for Lotus
Domino. This means that:
 Administrators can delegate common user, group and application tasks to non-technical personnel.
 These personnel can request that tasks be performed
 FirM automatically validates and checks that the tasks are correct, and if so, carries these tasks out
automatically.
Typically, tasks will be completed within 10 minutes of request (depending on authorisation stage and
replication topology).

1.11.2. Architecture
Architecturally, FirM is a number of Lotus Domino databases. The entire set of these databases reside on the
FirM processing server (or servers, should you choose to have a backup FirM processing server).
A subset of these databases can be replicated throughout the Domino environment to allow requesters
(people who request FirM tasks) to interact with FirM.
The processing server need only be a supported version of Lotus Domino server, running on a supported
server platform. Typically, this server will also be the Administration server for that environment.
FirM can manage single or multiple Lotus Domino domains.

1.11.3. Workflow
Within FirM, there is a two-stage workflow process.
The person creating the request (The “Requester”) may also be allowed to “Authorise” the request. In this
case, the request is processed immediately.
Should the Requester not be permitted to authorise this request, then details are mailed to personnel
allowed to authorise this request. One of these group of people can then Authorise or reject this request.

1.11.4. Client Experience


The requester interacts with FirM via a Lotus Notes client. They can only see options that have been made
available to them, and every item of information is validated before proceeding.
Web clients are now supported. We require that the Lotus Domino server be v7 or above to support Web
Services, and that the user client machines have Adobe Flash installed.

FirM Administration Manual v3.0 © 2009 HADSL


3 I N S TA L L I N G F I R M PA G E 13 O F 145

2. Installing FirM
2.1. Introduction
This document contains a step-by-step guide to the procedures that must be followed to install and set up
FirM. The installation instructions are written for Domino administrators and assume familiarity with basic
Domino administration tools and procedures.
If problems are encountered please contact your sales consultant, who will be able to provide assistance and
route your question to technical support if necessary.

2.2. Who should install FirM?


FirM should be installed by a Domino Administrator with complete administration access (“Manager”) to their
Domino environment, including certifiers and certifier passwords, etc.. Usually this is the head Domino
Administrator for a company.

2.3. How this product is delivered


This product is delivered in two parts:
 An installation package, downloadable from the HADSL web site (http://www.hadsl.com) , which
contains all Notes Databases required for FirM to function, as well as the Windows LSX code should
you wish to install the Active Directory component.
 A License key supplied by HADSL, which allows you to unlock and install a copy of FirM.

2.3.1. How to obtain a license key.


Your Sales Representative will provide you with a license key, which will allow you to install and operate
FirM. Two types of license key are available – Evaluation and Full. The evaluation keys are time-limited, and
FirM will stop operating once the expiration date has been passed.

2.4. Installation & Configuration of FirM


These installation instructions are written for Domino administrators and assume familiarity with the basic
Domino administration tools and procedures.
If problems are encountered, please contact your Sales Representative who will be able to provide
assistance and, if necessary, obtain technical support.

2.5. Quick Installation Process


FirM now includes a “Quick Config” wizard which quickly and painlessly leads you through the post-
installation configuration steps. The quick configuration guide is available from the Downloads page of our
web site.
We recommend that you use the Quick Config wizard only once, and only on an empty, installed copy of
FirM.

2.5.1. Prerequisites: Necessary information and access rights


In order to install FirM the following are required:
1. A Domino R5 or R6 server (R5.0.8 or above, R6.0.1 or above), and an administrator workstation
running Notes R5.0.8 or above or R6.0.2 or above, or R7.0 or above.
2. The administrator ID used must have permission to be able to modify the Domino directory, and issue
Administration (AdminP) Requests.
3. A copy of FirM.
4. A license key - this should arrive in an email from HADSL. The licence will be either for a time-limited
evaluation or will be the fully licensed copy. The licence information should be copied and pasted
from the email into the FirM installer when requested.
5. Domino directories must be properly configured; the directory profile must be set up so that the
domain name matches the actual name of the domain that the directory serves. The following are
required; each domain to be managed, the filename and path of the directory (e.g. names.nsf) and the
filename and path of the AdminP database (e.g. admin4.nsf).

FirM Administration Manual v3.0 © 2009 HADSL


3 I N S TA L L I N G F I R M PA G E 14 O F 145

6. Access to the server console, either physical access or through a remote server management tool
such as PCAnywhere, VNC etc..
7. The certifier ID(s) for all hierarchies to be managed together with the password(s) for these certifiers.
Note that FirM does not currently support certifier IDs that have been set up to require multiple
passwords.

2.6. Stage 1: Encryption key creation


Note: New in v2.1.01, you may skip this step for evaluation installations only. This means that all certifiers,
passwords, and user IDʼs you create will NOT be encrypted, thus lessening security. It does however mean
that you can skip this fairly time consuming step in order to get an evaluation copy of FirM up and running.
Should you choose to do this, you MUST install encryption keys before converting your license to a “full”
license as FirM will not permit unencrypted
certificates and passwords during normal
production running.
FirM uses three encryption keys to keep
sensitive files and passwords secure.
The three keys are created in the serverʼs ID
file and are subsequently imported into the
administratorʼs ID file.
N.B. Problems have been experienced when
passing the keys between the ID files in the
other direction due to differing degrees of
security in the two ID files. Please ensure that
the encryption keys are created in the serverʼs
ID file and then imported into the
administratorʼs ID file.
These encryption keys are called:
 iDM Certificate Encryption Key
 iDM Password Encryption Key
 iDM ID Encryption Key
Creating the Keys
a) Take backup copies of the serverʼs and the administratorʼs ID files and
store these in a secure location.
b) Copy the serverʼs ID file to a location accessible from the
administratorʼs Notes client.
c) Using the administratorʼs Notes Client, switch to the server ID. You may get warning messages
saying that you are not allowed to use a server ID to connect to a Domino server, but this doesnʼt
matter – you do not need to communicate with a server at this stage.
d) From the menu choose ʻFile, Security, User Security…ʼ
e) Enter password (if a server ID password has been set...).
f) Click on the ʻNotes Dataʼ tab on the left, and then click on ʻDocumentsʼ.
g) Click on the ʻNew Secret Keyʼ button at the bottom of the dialogue.
h) Name the key ʻiDM Certificate Encryption Keyʼ. Enter the name without quotes and retain
capitalisation.
i) Choose an appropriate encryption type, e.g. North American, International, ND6+, etc. (if the option
is available). Enter a description for the key and click ʻOKʼ.
j) With the key highlighted, click on the ʻOther Actions…ʼ button at the bottom of the dialogue and
select ʻExport Secret Key…ʼ.

k) Give the key a secure password in accordance with your security guidelines and procedures.
l) Save to a file on a removable disk or to a network path accessible from the administratorʼs
workstation.
m) Repeat steps 1h. to 1m. for the keys…
 ʻiDM ID Encryption Keyʼ
FirM Administration Manual v3.0 © 2009 HADSL
3 I N S TA L L I N G F I R M PA G E 15 O F 145

 ʻiDM Password Encryption Keyʼ


It is essential that the names of the keys match the above names exactly. FirM expects to find keys with
these names.
Note: existing iDM customers do NOT need to change the names of their existing encryption keys.
a) Switch back to the administratorʼs ID and copy the server ID back to the server.
b) Restart the Domino server and ensure that it is possible to connect to it from the Notes client.
c) The newly created encryption keys must now be imported into the administratorʼs ID.
d) On the administratorʼs Notes client, select ʻFile, Security, User Security…ʼ, and click on the ʻNotes
Dataʼ tab on the left, and then click on ʻDocumentsʼ.
e) At the bottom of the dialogue click on
ʻOther Actions…ʼ and select ʻImport
Secret Key…ʼ.
f) Navigate to the files containing the
encryption keys and select the ʻiDM
Certificate Encryption Keyʼ, enter the
password for the secret encryption key,
click ʻOKʼ and then click ʻAcceptʼ in the
Accept Secret Encryption Key dialogue
box.
g) Repeat steps 1s. and 1t. for the keys…
 ʻiDM ID Encryption Keyʼ
 ʻiDM Password Encryption Key
N.B. The encryption keys do not need to be distributed to users or administrators in order for them to
operate FirM. The only server IDs that require these encryption keys are the FirM primary (and optionally
secondary) processing servers. You should store these encryption keys securely in the same manner that
you normally secure certificate files.

2.7. Stage 2: Initial install of FirM


 Extract the FirM installer file (firminstall.nsf) and open it using the administratorʼs Notes client. (Note
that this client needs to be v6.0.1 or greater for the installation to succeed. This version limitation
does NOT apply to the Notes clients who will ultimately use FirM).

In order to prevent ECL (execution control list) errors whilst installing FirM, its best to copy the
installer NSF database to your local data directory, and sign the database using your ID file.

When you open the database using your normal Notes client, the first page of the installation wizard
dialog is displayed.

 If this is the first installation of FirM, select ʻFull


Product Installʼ. If upgrading from an existing
installation select ʻProduct Updateʼ.

FirM Administration Manual v3.0 © 2009 HADSL


3 I N S TA L L I N G F I R M PA G E 16 O F 145

 Confirm acceptance of the terms of


the Customer Software Licence to
continue.

 Enter the name of the FirM server.


This may be selected from the
address book using the drop-down.
Enter the name of the target directory
into which FirM should be installed or
accept the default (recommended). If
required, a secondary server may be
set up during Stage 3 – Basic
Configuration of FirM.

 The databases required by FirM are


now checked. Please note that a
green tick indicates that a required
database was found. A red cross
indicates that an existing database
with that name was not found and
that a new one will be created.

 Next, the group of users who


are to manage FirM must be
defined. These people will be
granted Manager Access to all
databases, and will be assigned
to the 'Administrator' role
allowing them access to the
FirM configuration screens.

 A check is now made to ensure


that the encryption keys have
been successfully installed into
the administratorʼs ID file.

FirM Administration Manual v3.0 © 2009 HADSL


3 I N S TA L L I N G F I R M PA G E 17 O F 145

 Access control checks are now


made to the Domino directory
(names.nsf), the administration
database (Admin4.nsf) and the
certifier log database (certlog.nsf)
on the target server.

 Complete the licence


information fields. If upgrading,
these fields will be pre-
populated with values from the
existing installation. If this is a
new installation, the Company
Name, License Key and License
Data information may be found
in the License Confirmation email you will have received from HADSL.

 Choose whether the databases should be signed using your current


Administration ID, or the ID of the server chosen in step 2.

 A summary of the installation settings is displayed.

 FirM templates and databases


are now created on the primary
server and icons are added to the
administrator's workspace. The
Install log will be written to the
screen during the installation –
the text will appear at the top of
the dialog and flow down the
screen. The installation process takes between 5-15 minutes depending on your network and
workstation performance.

 N.B. Installation will fail if the administrator's ID does not contain the FirM encryption keys. These
should have been created and imported during Stage 1 of this installation.
 Once the installation is
complete, you will see the
following screen:
 The installation process will
generate a number of requests
to sign databases with the
server ID which, by the time this
point is reached, should have all
completed successfully. If some
requests are still pending then
their processing may be
expedited by issuing the ʻtell
adminp process allʼ command at
the server console.

 Where specific security standards require that databases be signed with a special development ID,
this must be carried out manually.

FirM Administration Manual v3.0 © 2009 HADSL


3 I N S TA L L I N G F I R M PA G E 18 O F 145

 Configure the Access Control Lists for the FirM databases as required. Only FirM Administrators
should be members of the [Administrator] role.
 Replicate a copy of the FirM Extended AdminP database to each Domino server that will host users
and/or applications managed by FirM.
During the installation phase, the primary processing server will be requested to sign the FirM Request
Processor database with the server's ID file. In many cases, the server will be listed in the Administration
Execution Control List (ECL). Should the server NOT be listed in the Domino Administration ECL, the FirM
Request Processor database may be signed with the normal ʻapplication signingʼ ID file.
Later, the scheduled agents in the FirM Request Processor and, optionally, the FirM Extended AdminP
databases will be signed with an ID capable of running restricted agents.

2.8. Stage 3: Basic FirM Configuration.


FirM may now be configured by supplying it with some basic information about its operating environment.
Do the following from the administratorʼs Notes client.
a) Create bookmarks to the FirM databases which reside on the server.
b) Ensure that default access to all FirM databases is either ʻNo Accessʼ, ʻReaderʼ, or ʻAuthorʼ
depending upon FirM rollout and security requirements. Default access must not be set to
ʻManagerʼ.
c) Open the ʻFirM Request Processorʼ (firmrequestprocessor.nsf)
d) Click on the ʻToolsʼ item in the left-hand pane, and then choose the ʻConfigʼ tab.
e) Click on ʻEdit the System Configurationʼ and edit, if necessary, the following :
f) On the ʻDatabasesʼ tab:
 In the ʻFile Locationsʼ tab two temporary directories must be specified. The first temporary
directory (Local Temporary Directory) is located on the administratorʼs workstation and is used
during initial set-up and when certifiers are imported in to FirM. The second temporary directory
(Serverʼs Temporary Directory) is located on the server, is used to run scheduled agents and is
required for the normal operation of FirM.
 These directories must be created manually.
 The contents of the fields on the other tabs within the Databases tab will have been
automatically populated by the installer.
g) ʻServersʼ tab:
 The ʻPrimary serverʼ field must contain the fully qualified name of the FirM Domino server.
 The ʻSecondary serverʼ field should be left blank until the correct configuration and operation of
FirM has been confirmed. Once FirM has been installed and is working correctly, return to this
field and specify a secondary server if increased system resilience is required.
 Accept the default value for ʻSecondary Server Delayʼ (5 minutes).
h) ʻDirectoriesʼ tab:
 Use the ʻAdd Entriesʼ button to add the directories to be managed by FirM. Each directory
(names.nsf) should have both an Admin4 database (admin4.nsf) and a ʻDeny Accessʼ group
specified for that domain.
 Note that the installer creates the first ʻdefaultʼ directory entry but cannot at that stage define the
terminations group used in the environment. It is therefore important that the default entry be
edited post-installation to define a terminations group for the primary environment.
 The ʻEdit Entriesʼ and ʻRemove Entriesʼ buttons can be used to manage the directories list.
i) ʻAdmin Settingsʼ tab:
 It is recommended that the default values in the fields on all three sub-tabs be used.
 On the ʻMisc Settingsʼ tab:
 The default value of ʻNoʼ for ʻDisable UI request creation for non-administratorsʼ should be used.
This setting is used to disable the standard UI creation of requests in the situation where a
bespoke front-end has been implemented for FirM, and is beyond the scope of this
administration manual.

FirM Administration Manual v3.0 © 2009 HADSL


3 I N S TA L L I N G F I R M PA G E 19 O F 145

 The ʻDefault FirM Administratorʼ is used in conjunction with notification profiles to enable an
administrator, group of administrators or mail-in database to receive notifications. Default
administrators can also resubmit, cancel and ʻprocess nowʼ transactions.
 The default value for ʻAutomatic recertificationʼ of ʻDisabledʼ should be used for initial installation.
j) ʻBillingʼ tab:
 Billing information is only written to the FirM Billing Repository database when ʻEnable Billingʼ is
set to ʻYesʼ.

Select each request type to be recorded in the Billing Repository database.
k) ʻName Validationʼ tab:
 This tab allows the elements of both user and group names to be comprehensively defined.
 Under the ʻGroup Namesʼ sub-tab the way in which groups are split may be selected. The
options are to split a group when the group exceeds 15KB in size or when a specified number of
group members is exceeded.
 Ensure that a subgroup separator character is specified (ʻ_ʼ is suggested).
 ʻExternal Lookupʼ tab:
 FirM supports the use of an external database which database that can be used to provide
additional keys and codes to ensure unique naming standards. The default setting of ʻNoʼ
should be used as this is an advanced option and setting up this database is beyond the scope
of these installation instructions.
l) ʻWorkflowʼ tab:
 Accept the default of 3 hours for ʻNotify Every:ʼ
 It is recommended that all days, i.e. Sunday through to Saturday, are checked in ʻNotification
Window Daysʼ
 Similarly, change the notification times to start at ʻ1ʼ and end at ʻ23ʼ.
m) ʻArchiving & Expiryʼ tab:
 These settings control the archiving of requests from the FirM Request Processor to the FirM
Archive Repository database.
 The default values are usually sufficient. Archiving may be enabled at a later date.
n) ʻADʼ tab:
 Active Directory support may be enabled by clicking the ʻYesʼ radio button. A licence for Active
Directory support must have been purchased to enable this extension.
o) j. Click on the ʻSave & Closeʼ button to save the changes.

2.9. Stage 4: FirM System Profiles Set Up


FirM system profiles are the building blocks of User Profiles upon which are based various User Requests.
Other profiles, such as Notification Profiles, enable the FirM Administrator to tailor FirM to suit the both the
organisation's management and its IT infrastructure.
Group Profiles, although categorised as System Profiles, describe FirMʼs group creation and management
capabilities.
To create FirM ʻSystem Profilesʼ:
a) After opening the FirM Request Processor, click on ʻToolsʼ in the menu on the left-hand side of the
screen.
b) First select the certifier to be used by clicking on the ʻCertifier IDʼ tab; then click on ʻImport a new
Certifierʼ.
c) The ʻAdd Certifierʼ file-attach dialogue will be displayed. Select the certifier ID file to be imported.
Type the password for the certifier into the next dialogue and then reconfirm the password. Note:
certifiers requiring multiple passwords cannot be used with FirM.
d) Click on the ʻProfilesʼ tab
e) Click on the ʻSystem Profilesʼ sub-tab and perform the following steps…
a) Click on ʻSystem Certifier Profilesʼ radio button. System Certifier Profiles contain information on
how to use the certifier in the ʻUser Createʼ, ʻUser Moveʼ and ʻUser Renameʼ transactions. Do
the following:
FirM Administration Manual v3.0 © 2009 HADSL
3 I N S TA L L I N G F I R M PA G E 20 O F 145

 Click on ʻCreate a new Profileʼ.


 Enter a name for the Certifier Profile. This name should be meaningful to Requesters as it is
used to distinguish between different Certifier Profiles. Normally the name is the same as
the certifierʼs hierarchy.
 Select the imported certifier to use from the Certifier Hierarchy list.
 In the ʻFieldsʼ tab, static and dynamic fields may be specified. Static fields enable the value of a
field to be set to a pre-determined value in the target document. Dynamic fields allow the
contents of a field to be defined by the Requester when creating a user based on this profile.
For example, when a user is created the ʻTelNumberʼ field would be set to the userʼs
supplied telephone number. A static field is set with the same information every time a
request is processed which uses this profile. For example, the ʻOfficeLocationʼ field always
set to ʻLondonʼ.
 In the ʻDefault Groupsʼ box, specify the groups to which a User Created with this profile should
be added. All settings on this tab are optional.
 Entries in the ʻKeysʼ tab should not be changed.
 Click on ʻSaveʼ to save this profile, or ʻCloseʼ to close the dialogue without saving.
b) Repeat these steps for all the certifiers to be used by FirM.
f) To create a profile for the Company, click on the ʻSystem Company Profilesʼ radio button and do the
following:
a) Click on ʻCreate a new Profileʼ
b) Give the company profile a name, typically the name of your organisation.
c) Specify the Static and Dynamic field settings and default groups, as necessary.
d) Click on ʻSaveʼ or ʻCloseʼ.
g) To create a location profile, click on ʻSystem Location Profilesʼ radio button and do the following:
a) Click on ʻCreate a new Profileʼ.
b) Give the new location a name that is meaningful in the business context such as ʻLondonʼ or
ʻNew Yorkʼ or ʻEdinburgh 5th floorʼ.
c) In ʻTarget Mail Serversʼ define the primary mail server for users created with this profile. If more
than one server is specified, FirM will automatically load balance and create new users on the
server with the fewest users, based upon the ʻServer\Mail Usersʼ view in the Domino Directory.
d) Note that this location can share servers with other locations.
e) Static and dynamic field settings and default groups can be specified if necessary.
f) Click on ʻSaveʼ or ʻCloseʼ.
g) Repeat these steps for as many locations as necessary.
h) System ID Profiles specify the type of ID to be generated in a given user request. To create an ID
profile, click on the ʻSystem ID Profilesʼ radio button and do the following:
a) Click on ʻCreate a new Profileʻ
b) System ID profiles allow for the comprehensive specification of IDs; for instance, International or
North American, the recertification period, whether a mail file should be created, etc.. Note that
the mail template name refers to the actual file name of the Domino template which must exist
on the server. It is possible to specify different classes of user ID with this profile type – e.g.
ʻStaffʼ, ʻContractorsʼ, ʻand Functional Idsʼ, etc..
c) Static and dynamic field settings and default groups can be specified if necessary.
d) Click on ʻSaveʼ or ʻCloseʼ.
e) Repeat these steps for as many ID Types as necessary.
i) System Business Group Profiles are optional.
j) System Country Profiles are optional.
k) System Agent Trigger Profiles are not relevant during this initial set-up of FirM.
l) System Notification Profiles. At each step of the process of executing a transaction, an admin-
defined notification email may be sent. A default set of notification profiles is supplied with FirM and
these may be changed as necessary. A tag language enables different parts of the request to be
inserted into the message; for instance, the name of the requested user ID.

FirM Administration Manual v3.0 © 2009 HADSL


3 I N S TA L L I N G F I R M PA G E 21 O F 145

2.10. Stage 5: FirM User Profiles Set Up


FirM User Profiles tie together all the other profiles in the system enabling the creation of a very specific
request. Such a specific request might be, for example, a request to generate a ʻContractor IDʼ in the
ʻACMEʻ certification hierarchy for a ʻLeeds office-basedʼ user. A profile is created for every type of request
used in the organisation, thus constraining users to ID file requests that are correct and complete.
 Click on the ʻToolsʼ entry in the menu on the left-hand side of the screen. Select the ʻUser Profilesʼ
sub-tab.
 Click on the ʻUser Create profilesʼ radio button and perform the following steps:
 Click on ʻCreate a new Profileʼ
 Give the profile a meaningful name (e.g. ʻLondon Staff Userʼ)
 In the Fields and Groups tab specify static and dynamic field settings and default groups as
necessary.
 Next, click on the ʻNames & Domainsʼ tab.
 In the ʻDomino Namingʼ tab, use the drop-down list to select the Notes Domain in which this user will
be created. The ʻNotes Nameʼ and ʻNotes Short Nameʼ fields will be pre-populated with elements
from FirMʼs tag language. The tag language enables the construction of a userʼs Notes name,
Internet mail address and mail file name so that they comply with corporate naming standards.
 In the 'Optional OU' tab, select whether or not this profile should have Optional OU hierarchy
support.
 In the ʻInternet Namingʼ tab, use the tag language keywords to construct the userʼs Internet email
address. The keyword <INTERNETDOMAIN> takes its value from the Internet domain selected in
the ʻInternet Domainʼ box.
 The ʻMail File Namingʼ tab allows you to specify the construction of the userʼs mail file and the
cluster mail file name if the user is clustered.
 The ʻSub-Profilesʼ tab allows the selection of all the elements that determine a specific user ID. If
more than one sub-profile is selected within a section then the user will be prompted for the
appropriate sub-profile to use at the point of request creation. If only one sub-profile is selected for a
section then no prompt will appear for the user.
 The ʻIDʼ tab allows the selection of the ID profile that will be applied to the creation of this type of
user.
 The ʻLocationsʼ tab allows for the selection of a choice of one or more Location profiles to be used
for this particular type of ID. If more than one Location profile is selected the Requester will be
prompted to choose between them at the point of request creation.

 The ʻCertifiersʼ, ʻCompaniesʼ, ʻCountriesʼ and ʻBusiness Groupsʼ tabs similarly allow for the selection
of a relevant pre-defined profile for this type of ID request.
 The ʻID & Passwordʼ sub tab allows the recipients of any newly generated user ID and password
pairs to be defined.
 The Authorisation tab enables the definition of those users (Requesters) who are permitted to create
new users with this profile. Specify either individual names, or the names of multi-purpose groups
from the address book.
 The ʻAuthorisersʼ sub-tab enables the definition of those users who will authorise the creation of new
users made with this User Create profile. If a Requester should not authorise their own request,
provide the name of an alternative Authoriser. It is common to find that the LocalDomainAdmins
group is used for the Authorisers field.
 In the ʻNotificationʼ tab specify the names of users or groups who should receive a notification
whenever an ID is created using this profile. This is especially useful where there are security
considerations for certain certification hierarchies.
 Click on ʻSaveʼ.
 Repeat these steps for as many user creation profiles needed.
 Similar profiles must be created for each type of user request that FirM is able to process. For
example, User Modify, User Delete, User Disable etc..
In profiles other than the ʻcreateʼ profiles an additional sub-tab will be found in the Authorisers tab – the
ʻUsers Managed by this Profileʼ tab. This should contain a name mask, such as ʻ*/ACMEʼ, thereby restricting
who can be deleted, renamed, etc., using this profile.
FirM Administration Manual v3.0 © 2009 HADSL
3 I N S TA L L I N G F I R M PA G E 22 O F 145

2.11. Stage 6: FirM Group Profiles Set Up


Group profiles define the type of the group created thus ensuring that users of FirM do not have to
understand the difference between different types of groups, e.g. a Mail Group, an ACL group or a Multi-
Purpose group.
Membership of the group may be restricted. For example, a Group profile called ʻConfidential Internal
Emailsʼ would disallow the addition of any Internet email addresses.
Workflow can also be set up - for instance, restrictions can be placed upon who can submit group create
requests, who can authorise them and who is notified. The Group Profiles define what actions can be done
for each type of group that FirM can manage, what its allowed content is, what the name of the group should
be and who can submit requests to create these groups.
1. Click on the ʻToolsʼ entry in the menu on the left hand side of the screen. The control panel screen
should open and default to the ʻProfilesʼ tab. Select ʻSystem Profilesʼ.
2. Click on ʻSystem Group Profilesʼ radio button entry and perform the following steps:
 Click on ʻCreate A Profileʼ
 Give the profile a name, e.g. ʻACME Mail Groupʼ
 Select the type of group – e.g. ʻMail Groupʼ
 Select foreign Dir Sync setting.
 In the Membership tab specify whether each type of group content is allowed or not allowed to be a
member. Valid Notes users are always allowed to be members of a group.
 In the Name tab, the mask for the group name is created. If a group is not to be given an Internet
address when it is created then the Internet Address field should be left blank. The tag
ʻ<GROUPNAMEUSERELEMENT>ʼ will be replaced with the userʼs descriptive element of the group
name.
 The final three tabs are ʻRequestʼ, ʻAuthoriseʼ and ʻNotifyʼ. These fields need to be populated with the
names of people who are able to request and authorise the creation of a group. The rights for
modification, deletion and management are governed by the groupʼs entry in the database ʻFirM
Group Registerʼ.
 The Notification tab allows the person to be specified who will be notified when a request progresses
through the workflow for the creation, management or modification of a group created with this
profile.
 Click on ʻSaveʼ or ʻCloseʼ.
3. Repeat for as many different types of group profiles as are necessary. It is possible and perfectly
normal to have more than one type of profile for each group type. This is useful when different naming
conventions must be enforced for, say, a global mailing group as opposed to a regional mailing group,
and to assign the authority to create each of these group types to different people or groups of people.
4. At a minimum there must be a profile defined for each of the basic Domino group types Mail Group,
ACL Group, Multipurpose group, Server Group and Terminations (Deny only) group.

2.11.1. Stage 7: Group Import Utility

In order for a group to be managed with FirM it must have an entry in the FirM Group Registry. This entry
contains information about the group such as which profile it will use, which domain it belongs to, and who
are the Owners and Administrators of this group.
The roles of Owner and Administrator are described in the FirM Help database, but broadly an Owner is a
person who is able to modify the groupʼs list of owners and administrators, manage the content of the group,
and request the groupʼs deletion. An Administrator is a person who is only able to manage the content of the
group.
A typical Domino installation will have many groups in each Domino Directory, and the import utility is used to
create Group Registry entries for each of these groups. The tool is run from the FirM Request Processor,
and is accessed from the ʻToolsʼ button under ʻImport Group(s)ʼ.
1. Click on the ʻToolsʼ entry in the menu on the left-hand side of the screen.
2. Click on ʻImportʼ tab, and ʻgroupʼ sub-tab.
 Click on ʻImport Groupsʼ
 You will be presented with a dialog with instructions. Click on 'Forward' to continue.
FirM Administration Manual v3.0 © 2009 HADSL
3 I N S TA L L I N G F I R M PA G E 23 O F 145

 Select whether a single group, a selection of groups or all groups of a type in the directory should be
imported.
 Select the Directory/Domain from which the group/groups is/are to be imported.
 Select whether the groups are to be imported straight into a ʻLiveʼ state (i.e. can be managed from
FirM without further intervention) or into a ʻDraftʼ state, in which case the groups must be manually
moved to Live from within the Group Registry.
 It is possible to import spanned groups into FirM as a hierarchy. In order to do this the spanned
groups must follow the naming convention of
[parent group name][separator character][number of subgroup]
 Also, the parent group must contain only the names of subgroups. FirM will honour the existing
separator characters and will add and remove users from subgroups in this hierarchy.
 The settings in the ʻOwnershipʼ tab allow default entries for group owners and administrators to be
specified. The values contained in these fields will be added as an owner and administrator
(respectively) to each group imported with the utility.
 Assign which group profiles should be set for each type of group imported:

Finally, click on ʻOKʼ and the groups will be imported.


3. If groups have been imported into a Draft status, open the FirM Group Registry, navigate to the Draft
Groups view, and once the group entry is confirmed to be correct, select the group from the view, and
use the ʻToolsʼ, ʻFlag selected groups as Liveʼ action to mark the group as live for management.
4. This operation must be carried out for every directory that contains groups that are to be managed.

2.11.2. Stage 8: Agent Enablement


This stage in setting up FirM for use is to enable the processing and workflow agent. This part of the
operation must be carried out using an ID which is allowed to run ʻRestricted and Systemʼ operations on
scheduled agents on any of the Domino servers.
1. Open the FirM Request Processor and select the 'Tools' menu from the left hand side. When the
control panel appears, select the 'Monitorʼ tab, then the ʻScheduled Agents' tab.
2. Click on the ʻRefresh Agent Statusʼ button.
1. On the 'Process Requests and Workflow' agent line, click on the server name, and select the
correct processing server for FirM. Then click on the traffic light on the left hand column to
enable the agent.
2. On the 'Ext AdminP' agent line, click on the server name, and set the processing server to a
single asterisk ( * ). This means that this agent will run on every server where this database
is replicated to. Then click on the traffic light on the left-hand column to enable the agent.

2.11.3. Stage 9: Access Control on FirM Databases


The following FirM databases are accessed by the users during normal operation, and require access to
these databases. This is usually achieved by creating a group called “firmRequesters” within Domino, and
adding all FirM users to this group.
Database Title Database filename ACL Level
Request Processor Database FirmRequestProcessor.nsf Author+Create Document
Group Registry Database FirmGroupRegister.nsf Reader
Log File FirmLog.nsf Author+Create Document

This step should be performed before users are allowed access to FirM.

2.11.4. Stage 10: Replicate FirM to the rest of the Domino Environment
The final stage in setting up FirM for use to replicate it to all relevant servers.
1. Replicate the following FirM Databases to all servers (and any intermediate replication servers)
where users will access the FirM Request Processor:
1. The FirM Request Processor (firmrequestprocessor.nsf)
2. The FirM Group Registry (firmgroupregistry.nsf)
3. The FirM Log Database (firmlog.nsf):

FirM Administration Manual v3.0 © 2009 HADSL


3 I N S TA L L I N G F I R M PA G E 24 O F 145

2. Replicate the following FirM Databases to all servers (and any intermediate replication servers)
where users and/or applications are to be managed by FirM:
1. the FirM Extended AdminP Request Processor (firmextendedadminp.nsf)
FirM is now installed, configured and ready to be used to create and process user and group management
requests.
Note that if you replicate FirM to other domains in your environment, you should add ACL groups to the
databases mentioned above in order to allow inter-domain replication. We have deliberately left out the
'OtherDomainServers' ACL entry in order to improve default security. You should use the Admin client to set
the relevant groups for your environment in each database appropriately.

2.11.5. Normal Operation: Creating Requests


1. Open the FirM Request Processor database.
2. The default view is the ʻAll Requestsʼ view. This shows all requests by status. Click on the ʻNew
Requestʼ button.
3. A dialogue is displayed allowing the type of request to be chosen. The list of requests to chose from
are those where you are named as a Requester in the relevant user or group profile.

2.12. Importing Certifiers & Passwords


FirM requires that certifiers are imported into the FirM Certificate repository. Administrators can perform this
procedure by opening the FirM Request Processor, clicking on the ʻToolsʼ button, and selecting the ʻImportʼ
Tab, then the ʻCertifierʼ tab:
The certifier file to import must now be specified. Using the file dialog box, select the certifier file.
The Certifier password is then validated. Two prompts will appear.

If the two passwords match, the certifier and password is imported into
FirM.
During this process, the ID file provided is
checked to ensure that it is a certifier file, and its
certifier hierarchy is extracted. FirM then checks
to see if these already exist in the FirM certifier repository and the FirM Password
repository. If they do, the old versions may be overwritten with the new versions if
desired.
The Certifier has now been imported into the FirM
Certifier repository.

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 25 O F 145

3. System Configuration
3.1. Target Audience
This section is intended for use by the FirM Administrator.

3.2. Introduction
The System Configuration dialog box contains all system-wide configuration settings for FirM. The users
never see this dialog – only the FirM Administrators. This is usually set up at FirM installation time, and is not
normally updated.
To navigate to the System Configuration Pane, click on the Tools option, followed by the “Config” tab.Then
click on ʻEdit the System Configurationʼ

3.3. System Configuration – Databases

Sub-Tab Field Explanation

File Locations Local In the ʻFile Locationsʼ tab two temporary directories must be specified.
Temporary The first temporary directory (Local Temporary Directory) is located on
Directory the administratorʼs workstation and is used during initial set-up and
when certifiers are imported in to FirM. The second temporary
Servers directory (Serverʼs Temporary Directory) is located on the server, is
Temporary used to run scheduled agents and is required for the normal operation
Directory of FirM.
These directories will temporarily contain items such as certifier IDs,
user IDs etc.. It is important that these directories are not accessible
to users. These directories must be created manually. Should these
directories not exist, then the normal ʻtempʼ directory defined on the
operating system will be used.
On a Unix-based system (such as Linux, AIX, Solaris, HP/UX for
instance), the directory should be specified in the form ʻ/tmp/ʼ, using
forward slashes to separate directories. On a Windows-based system,
the directory should be specified in the form ʻc:\temp\ʼ where a drive
letter followed by a colon and the backslash character is used to
separate directories.
The contents of the fields on the other tabs have been automatically
populated by the installer. These values should be changed only if the
databases have been renamed or moved.

This Database Request The complete file path to the firmRequestProcessor.nsf database,
Processor

Applications Monitor The complete file path to the firmApplicationMonitor.nsf database,

Usage The complete file path to the firmApplicationUsage.nsf database,

Extended Extended The complete file path to the firmExtendedAdmin.nsf database,


AdminP Admin

Group Registry Group Registry The complete file path to the firmGroupRegister.nsf database,

Group Shadow The complete file path to the firmGroupShadow.nsf database,

Repositories Cerfier The complete file path to the firmCertifiers.nsf database,


Repository

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 26 O F 145

Sub-Tab Field Explanation

Password The complete file path to the firmPasswords.nsf database,


Repository

ID Repository The complete file path to the firmIDs.nsf database,

Enable ID If Yes, then the ESCROW database will be required, and the ID
Recovery recovery process agents made available
Process

ID ESCROW The complete file path to the firmEscrow.nsf database,

Deleted The complete file path to the firmDeletedUsers.nsf database,


Names
Register

History Audit The complete file path to the firmAudit.nsf database,

Archive The complete file path to the firmArchive.nsf database,

System Log The complete file path to the firmLog.nsf database,

AD Sync Is Available Enable this in order to view the FirMADSync.nsf database

The complete file path to the firmADSync.nsf database,

Marvel Marvel Client The complete path to the Marvel Client main processing database on
the Primary FirM processing server

3.4. System Configuration - Servers

Field Explanation

Primary Server The fully qualified name of the FirM Domino server.

Secondary The ʻSecondary serverʼ field should be left blank until the correct configuration and
Server operation of FirM has been confirmed. Once FirM has been installed and is working
correctly, return to this field and specify a secondary server if increased system
resilience is required.

Secondary The secondary server delay value is critical. The secondary server will wait until a
Server Delay request is this number of minutes ʻoldʼ before attempting to process it. Should the
primary and secondary servers be clustered, then this value can be as low as thirty
minutes. Should the primary and secondary server just rely on scheduled replication,
then this figure should be at least three times the replication period defined between
these two servers for this database.

If this value is too low, then both servers will attempt to process requests, resulting in replication conflicts and
at worst, instances where executing the transaction twice would result in duplicate entries – for instance User
Create, group create, etc..
We recommend that two program documents be created in your directory to support this configuration.
 One program document should run on your primary server, and have the command “rep
<secondaryServer> <firmDirectory”>, and schedule type of “startup”
 The second program document should run on your secondary server, and have the command “rep
<primaryServer> <firmDirectory”>, and schedule type of “startup”
This ensures that the FirM directory is immediately replicated should a server be down for any reason, and
prevents requests being processed twice.

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 27 O F 145

3.5. System Configuration - Directories


This pane shows a list of all Lotus Domino domains managed by FirM. Each domain requires:

Field Explanation

Name The database filename of the directory database

Domain The domain name for the directory

Admin4 The database filename for the admin4.nsf database for that domain

Teminations The terminations group for that domain


Group

Domains can be added, edited or removed by clicking on the relevant button at the bottom of the list.
Use the ʻAdd Entriesʼ button to add the directories to be managed by FirM. Each directory (names.nsf)
should have both an Admin4 database (admin4.nsf) and a ʻDeny Accessʼ group specified for that domain.
 Note that the installer creates the first ʻdefaultʼ directory entry but cannot at that stage define the
terminations group used in the environment. It is therefore important that the default entry be edited
post-installation to define a terminations group for the primary environment.
 If more than one domain is to be managed, then the directory and the admin4.nsf database should
be replicated on a scheduled basis from the other domains onto the primary (and secondary server,
if defined). The other domainsʼ directory and administrative databases can then be added to this list
of domains to be added.
It is important that if more than one domain is to be managed, that each domain has a unique
domain identifier set in the directory profile in each directory database. This can be updated by:
 Opening the directory database
 Clicking on the Actions menu, and then ʻEdit Directory Profileʼ
 Editing or updating the ʻDomain defined by this directoryʼ field.
 The ʻEdit Entriesʼ and ʻRemove Entriesʼ buttons can be used to manage the directories list.

3.6. System Configuration – Admin Settings

Sub-Tab Field Explanation

Log Settings Debug Level The debug level will initially be set to ʻ4. Very Detailedʼ. This will
generate a large amount of logging and debugging information which
is of use during the initial configuration phase of FirM. During normal
operation, this value should be set to ʻ3. Detailedʼ in order to provide
more manageable levels of logging and debugging information.

Logging The ʻLogging Destinationʼ allows default Notes output to be logged,


Destination that is, the status line in the client, as well as the FirM log database.
The default Notes output is only recommended during the initial
configuration phase and should not be enabled during normal
production use as it displays a large amount of information on the
Notes client status line, which might be confusing.
It is recommended that logging and debugging information is written to
the FirM log database.

Number of Days Choose the number of days you wish to retain log entries for

Log File Mail In If you add a Mail-In document in your directory pointing at the FirM
Address Log database (firmlog.nsf), then the client can eMail in log entries
instead of having to open the database. This also means that you do
not have to replicate the firmLog.nsf database to other servers from
the FirM Primary processing server.
(This is highly recommended)
Choose the Mail-In address from the address boo.

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 28 O F 145

Sub-Tab Field Explanation

Should Clients This switches the client log mode from directly writing to the
Mail In their log FirmLog.nsf database, and rather uses the mail-in address defined
documents above. This has a direct performance gain, as the client no longer has
to open the log database, and of course this means that the Log
database need not be replicated to all servers – it need only reside on
the Primary and Secondary Processing servers.
Other server processes that create log documents will use the mail
address if it is defined, unless the other servers are the primary or
secondary processing servers.

Log Switch this on in order to log output from the configuration object. We
Configuration have found that in an idle system, the output from the configuration
Object object represents about 85% of the log output. This reduces the
chatter on a stable system.

Misc Settings Disable UI This setting is used to disable the standard UI creation of requests in
request creation the situation where a bespoke front-end has been implemented for
for non- FirM, and is beyond the scope of this administration manual.
administrators

Default FirM This is used in conjunction with notification profiles to enable an


Administrator administrator, group of administrators or mail-in database to receive
notifications. Default administrators can also cancel requests.

Automatic This enables the automatic recertification engine.


recertification

Recertification The number of days before the end-user certificate expires that the
Days recertifcation engine processes users. This should normally be greater
than the 90 days that the Notes client starts warning the user of the
certification expiry

Group Changes This will then allow the selection of groups in the Group Registry for
Monitoring monitoring. Should any monitored groups be changed, the changes
are noted and communicated to selected users.

Use Password If enabled, this allows the user ID and password recovery mechanism
Recovery to to use the Password Recovery mechanism to recover ESCROW ID
recover files. files. You must be running on Domino 7.0.2 or above (8.x or above
recommended) in order for this to work. You must also identify
Recovery Authorities in each Certifier profile, and these recovery
Authorities must exist in the ID and Password repositories.

Default Footer Allows the definition of a rich-text footer which will be appended to all
Notification notification messages generated by FirM. This can be used to add
Footer graphics, as well as a standard footer explaining to the user that this is
a system-generated email message.

Application Maximum age The number of days manual scanning should go back in the user
Montior activity log.

Maximum Users The Total number of users in your environment. This is used to
indicate how many users may access this application, where the ACL
contains elements such as *.

Ignore Zero This allows the reduction in the number of access logs recorded, by
Read/Zero Write ignoring sessions which dont result in reads or writes. However, this
Records does give the false impression that nothing is accessing the
application.

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 29 O F 145

Sub-Tab Field Explanation

Ignore Server This allows you to ignore the server based activity, which results in a
based Records huge reduction of tracking records.

Mail File Bands The administrator should define up to five band “names”, and the Mail
Quota File Quota figures to should increase from top to bottom. The last
Management figure - for “unlimited” - should be set to zero.
If you do not wish to use a particular band, leave its name blank.

Allow Extended The mechanism relies on writing ʻhiddenʼ fields to the users Person
AdminP to document in order to communicate the users Mail File Quota band,
update Person replica ID of mail file, etc. This has to be enabled for the mechanism to
Documents work.
Note that when this is enabled, there will be a large number of
updated Person documents in the first night, as the Mail File
managment system uipdates each person document.

FieldName Each of these fields allow you to define what this hidden field is called,
For... in order to reduce the possibility of collisions. Note that if these are
changed, it may take several days for the Mail File quota managment
system to recover. It is recommended that these are only changed
before enabling the system.

If a user does Chose the action to perform if a user does not have a mail file quota
NOT have a set. It is recommended that the option ʻSet to level above users
mailfile quota currentl mail file sizeʼ is chosen.
set...

ID Backup Mail In Address Create a mail-in document pointing at the FirM request processor in
order for the ID backup mechanism to work.

AdminP Search The number of hours back that the mechanism will search looking for
Hours requests to process.

Store retention This is the number of hours that an ID Backup will retain the
hours temporary records of processed AdminP records.

Reminder (In Days). The number of days between reminds that users will receive
Frequency to back up their ID and Password. This should be a minimum of one
day.

Maximum The maximum number of reminders that a user will receive in order to
Reminders back up their ID file.

Users to include A list of users specified by wildcards - NOT group names - for people
to be incldued in this ID backup mechanism.

Language Languages Select the number of languages on offer to the end-user.


Support

Notification Select the language that notifications will be sent in.


Langauge

External Enable External Enable External queue processing if you wish to handle mailed-in
Queue Queue requests, and requests generated in other databases.
Processing Processing

Enabled Queue Select the types of queue you wish to enable.


Types

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 30 O F 145

Sub-Tab Field Explanation

Only accept A list of people or groups that are allowed to send in requests. This
requrests from means that you can restrict this functionality to a subset of users - for
these people or instanced. signed, scheduled agents.
groups

External Click on the button to choose an external database to scan for


Database to requests. This may be on another server, but remember that the agent
scan will be running on the FirM processing server.

Database View Select a view from the target database


to scan.

Document field Enter a fieldname on the target document, and a success & failure
and Value value to set. This means that after processing the document is
updated using the field and values appropriate to the target database.

CSV data is in The fIeld that contains Comma Separated Values that represent the
field request(s) contained in this document.

3.7. System Configuration – Billing

Field Explanation

Enable Billing Billing information is only written to the FirM Billing Repository database when ʻEnable
Billingʼ is set to ʻYesʼ

Billing Location The target Billing database.

Bill for the Enable the transactions you wish the Billing engine to record.
following
transactions

Write biliing It is recommended that the ʻWrite Billing Records for sub transactionsʼ be set to ʻNoʼ.
records for In most billing circumstances, only the initial or main transaction is relevant for billing
subtransactions purposes. For instance, should a User Create transaction be created, its four or more
sub transactions (send User ID, Create Replica Mail file, etch) are of little value from a
billing perspective.

Billing target for The field ʻFor Groupsʼ should be set to the individual relevant for group transactions;
Groups that is the owner of the group, or the person who requests the group change.

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 31 O F 145

3.8. System Configuration – Name Validation

Sub-Tab Field Explanation

Name Name This tab defines which name uniqueness checks are to be performed
Uniqueness Uniqueness during FirM operation:

ʻFull Name Uniquenessʼ. This checks the entire Lotus Notes name of
an object. For instance, ʻJoe Bloggs/HADSLʼ would be compared
against ʻJoe Bloggs/Acmeʼ. It is recommended that this value is
checked.

ʼInternet Address Uniquenessʼ. This checks that each object has a


unique internet address defined. For instance,
Joe.Bloggs@hadsl.com would be compared against
Joe.Bloggs@acme.com. It is recommended that this value is
checked.

ʻShort Name Uniquenessʼ. This checks that each object has a unique
Lotus notes ʻshortnameʼ. For instance, ʻJBloggsʼ would be compared
against ʻJBloggsʼ (and found to be non-unique). It is recommended
that this value is checked.

ʻCommon Name Uniquenessʼ. This checks the userʼs common name


field of an object. For instance, ʻJoe Bloggsʼ from ʻJoe Bloggs/HADSLʼ
would be compared against ʻJoe Bloggsʼ from ʻJoe Bloggs/Acmeʼ and
found to be non-unique.

It is recommended that this value is checked as this allows the


consolidation of all internet domains to one domain, and still
preserves address uniqueness.

First Name Is required Is required – check this box if this name field is required.
Middle Initials
Last Name Minimum This defines the minimum length (in characters) allowed in your
Short Name Length environment.
Alternate Name
Group Name Maximum This defines the maximum length (in characters) allowed in your
Mail In Length environment.

Allow Non- Checking this box allows characters other than A-Z, a-z in this name
ASCII field.

Allow Checking this box allows number characters 0-9 in this name field.
Numbers

Allow This allows the underscore character ʻ_ʼ to be used in this name field.
Underscores

Allow This allows the hyphen character ʻ-ʼ to be used in this name field.
Hyphens

Allow This allows punctuation characters such as ʻ;ʼ, ʻ,ʼ etc. to be used in
Punctuations this name field.

Allow This allows the space character to be used in this field. This could
Spaces allow people with two words in their first name – for instance, ʻJan
Willemʼ.

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 32 O F 145

Sub-Tab Field Explanation

Force Case This forces this name field to be one of the following:
No Change. No case changing is performed. For example if the
requester types in ʻjan williemʼ, it is left as ʻjan williemʼ
All Lowercase. The name field is converted to lowercase. For
example if the requester types in ʻJan Williemʼ, it is converted to ʻjan
williemʼ
All Uppercase. The name field is converted to uppercase. For
example if the requester types in ʻjan williemʼ, it is converted to ʻJAN
WILLIEMʼ
Propercase. The first letter of each word is made uppercase, and the
rest of the word made lowercase. For example if the requester types
in ʻjan williemʼ, it is converted to ʻJan Williemʼ

Allowed This allows the definition of non-ASCII characters allowed in name


Characters fields, without allowing every possible non-ASCII character.

Group Name Membership The number of users in each group before splitting into subgroups.
Limit Typically this should be around 200 names, but in some cultures with
more names, this might be lower.

Subgroup The Character used to separate the group name from the subgroup
Separator text

Subgroup Subgroups can have a prefix in order to sort the subgroups to a


Prefix different part of the directory listing

Require The Name of the field used to set Owner Approval.


Owner
Approval
field name

External Allow If you enable this, it allows lookups against an external database in
Database External order to perform name uniqueuess checking.
Database
Lookup

Name Choose which name elements should be compared.


Elements to
Compare

External The Name of the database ito examine


Database

View Name The View to check. We use the name component, and if an entry is
found in this view, using the name as a keyword, then the uniqueness
check fails.

3.9. System Configuration – Workflow


The workflow tab allows the definition of the frequency with which the workflow engine emails notification
messages to individuals involved in the authorisation of requests.

Field Explanation

Notify Every The number of hours that the workflow messages should be sent out.

Notification Choose the working days appropriate for your work environment
Windows Days

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 33 O F 145

Field Explanation

Notification Time The start of the business day in your environment


Start

Notification Time The end of the business day in your environment.


Finish

3.10. System Configuration – Archiving & Expiry


Controls the archive and expiry engine, and dictates how long to wait before a transaction is moved from the
FirM Request Processor to the transaction archive, the FirM Archive Repository database.
The default values are usually sufficient. Archiving may be enabled at a later date.
The FirM archiving engine is driven by the agent ʻArchive Old Requestsʼ and governed by the settings in this
tab. The agent should be enabled to run on the same server as the primary FirM request processing agent.
On each run cycle the agent looks at the current top-level requests in the FirM request processor and checks
the date of the last process that occurred on the request (and any sub-requests). It then looks at the status
of the request and compares the status to the list of expiry times that are set in this tab. These settings are
specified in days.
If the number of days that have passed since the time that the request was last processed exceed the
number of days specified for that particular request status then the request and all of its sub-requests are
moved to the FirM Request Archive repository. The location of the Archive Repository is defined in the
ʻArchived Requestsʼ entry on the ʻDatabases, Historyʼ tab of the configuration profile.
The request and all of its sub-requests will then be removed from the FirM Request Processor.

Field Explanation

Staus of There are several status values that can have expiry periods set:
Requests  DRAFT – this is the status of a request that has been added to the Request
Processor but not yet submitted. This status is not available from UI-
created requests and will only occur if a request was created from an
external process using the FirM LotusScript API.
 COMPLETE – this is the setting for removing old requests that have fully
completed their processing.
 REJECTED – these are requests where the Authoriser has declined the
transaction.
 CANCELLED – requests that have been cancelled by the Requester, an
Authoriser or the default FirM administrator will be archived according to
this setting.
 FAILED OR INVALID – requests that have failed processing or rejected due
to broken signatures will be archived according to this setting.
Requests that are awaiting processing, deferred or awaiting approval will never be
archived.

FirM has the ability to create and monitor groups and users for auto-expiry. That is to say, that a date can be
set after which an automatic deletion workflow will remove them from the environment.
This facility is not currently available from the standard FirM UI and is only accessible from the FirM
LotusScript API – this facility may be accessible from the UI in a future release of FirM.
The three settings relating to the automatic expiry of users and groups should therefore be ignored in the
standard install of FirM and only changed under instruction of HADSL or one of its resellers.

Field Explanation

Person Documents The name of the field on each of these types of document, which will be
Group Documents updated with an expiry date.
Mail-in Database
Documents

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 34 O F 145

3.11. System Configuration – Active Directory (AD)


Active Directory configuration and operation is outlined in the section - “Installing and Configuring FirM Active
Directory”.

Sub-Tab Field Explanation

Active Directory Set this to Yes to enable active directory support within FirM.
Enabled A license for Active Directory support must have been purchased
to enable this extension.
Due to the amount of UI changes this causes, its best to save the
configuration document and restart FirM.

AD Domains Domain List Add, Edit and Remove supported Active Directory domains from
this list by clicking on the add, Edit and Remove Entries buttons.
Each entry requires
 The Domain Name. This should be the ʻDNʼ part of the
top of the Active Directory tree - such as ʻhadsl.localʼ,
instead of the NT domain name (“HADSL”)
 The name of the primary AD server. This will be the
windows server which calls back to the FirM processing
server and collects user and group transations to
process. You should enter the ʻCommon Nameʼ part of
the server (such as ʻServer1ʼ) instead o the full AD name
(such as ʻServer1.servers.hadsl.localʼ)

AD Name Name Validation This sub-tab allows you to define the same name validation rules
Validation as exist for Lotus Domino.

Synchronisation Perform Set this to yes to enable AD directory syncronisation between the
Syncronisation Active Directory domains defined above, and the Lotus Notes
domains controlled by FirM.

Person Document When a Notes Person document is ʻlinkedʼ to an Active Direcotry


field to store object, we store the AD object GUID (Global Unique Identifier) in
GUID field a field on the person document. This allows both the AD and
Domino entities to change name without losing this link.
Many AD/Domino syncronisation tools use this mechanism and
store the information in the NetUserName field on the person
document. We recommend that FirM also uses this field name.

Frequency How often should the AD syncronisation occur. We recommend


on a daily basis - 24 hours.

Start Time When should the syncronisation agent tell the windows machine
to start sending its directory information? We recommend a time
outside of normal business hours and outside of the backup
windows (when the servers are going to be busy).

Admin Settings Web Service When the windows web service collects its configuration, it is told
cycle time by this setting how often (in seconds) it should poll for new work.
The default is 300 seconds (5 minutes). It is not recommended
that this be set to less than one minute.

Users Notes For User ID and Password resend, we can drop a new copy of
Folder within the users ID file into the users home directory on their home file
Home follder server.
name Enter the name of the Lotus Notes data directory within a normal
users home share in order for the ID to be placed in the correct
folder.

FirM Administration Manual v3.0 © 2009 HADSL


5 S Y S T E M C O N F I G U R AT I O N PA G E 35 O F 145

3.12. System Configuration – BlackBerry

Field Explanation

BlackBerry Blackberry Support can be enabled by setting the radio button to Yes. A license for
Enabled BlackBerry support must have been purchased to enable this extension. Note that
BlackBerry transactions, profiles, etc will not be visible until this has been set to 'Yes.
Due to the sheer amount of UI changes that this causes, its recommended that after
this is changed, you save the configuration document and exit FirM.

Verbose Logging This echoes the actual output from the BlackBerry Resource kit to the FirM log,
dramatically increasing the size of the log file. It is recommended that this only be
switched on whilst debugging BlackBerry Resource Kit issues.

BlackBerry The BlackBerry Resource Kit Executable name has to be set. This means that the
Reource Kit BlackBerry resource toolkit must be installed on the same location on both the primary
Executable and secondary FirM processing servers.
Name On installing the BlackBerry Resource Toolkit, you were prompted to generate a new
password for security purposes. Enter that password to FirM by clicking the
“Password” button.

Set SQL If your BES servers share a common SQL server, then enter the username and
Username and password that is in use.
Password If your BES servers run local databases for their operation - they do NOT use a
separate MS SQL database - leave this entry blank.

BlackBerry List all of the BlackBerry Enterprise Server “BlackBerry” policies that you wish to
Policies expose to FirM for management. Note that at this point, it is not possible for FirM to
automatically build that list, and so the administrator must maintain this list manually.

You must now visit each Location document and enter the servers which are running your BlackBerry
enterprise server software, in order that relevant locations are associated with zero or more BES servers.
See the entry “Location Profiles - BlackBerry servers tab” on page 34 for more information on this.

3.13. System Configuration – License


This shows read-only information about the currently installed FirM license.

FirM Administration Manual v3.0 © 2009 HADSL


6 A D M I N I S T R AT I O N T O O L S PA G E 36 O F 145

4. Administration Tools
The Administration Tools panel is accessible only to FirM Administrators – people who have the ACL role
[Administrator] enabled. To access the administration tools, click on “Tools” on the left hand navigator in the
FirM Request Processing database.
The Administration Tools assist the administrator in the set-up, configuration and day to day running of the
FirM application.

4.1. Config Tab


The Config Tab enables the administrator to:
 View and edit the global system configuration.
 Update the License key within FirM. This may be necessary from time to time with new releases in
order to enable new transactions. To Update your license key,
 Click on “Update the FirM License”
 Copy and paste the License key information supplied to you by HADSL into the relevant fields
 Click on “Update License.

4.2. Profiles Tab


The Profiles tab allows the administrator access to the FirM profiles that define how each transaction should
be processed.
Note that the Active Directory and BlackBerry profiles will only be visible if these options are switched on
(and you are properly licensed to use these transactions) within the System Configuration Screen.

4.3. Monitoring Tab


The Monitoring tab assists the administrator in viewing the current status of the FirM processing
environment.

4.3.1. Scheduled Agents sub-tab


The Scheduled Agents sub-tab shows all scheduled agents within the FirM processing environment. To view
their current status, click on the “Refresh Agent Status” button.
Each agent can be controlled or changed:
 Click on the diamond shaped coloured button to enable or disable the agent. Green means the
agent is enabled, and red is not.
 Click on the green arrow beside the agent to run the agent manually on the server. This is not
recommended on a product environment – it may cause performance bottlenecks – it is however
very useful whilst testing.
 Click on the Server name for each agent to change the server, if required.

4.3.2. Database Versions Sub-tab


This tab allows the administrator to quickly establish the release version of all FirM databases in his
environment. Click on the “Check Db Versions” button to refesh this page.

4.3.3. “Check Extended AdminP” tab


This tab allows the administrator to check the status of all servers in the environment, and the status of their
Extended AdminP subsystems. Note that Extended AdminP only runs once per 30 minutes, and of course
runs on remote servers.
The “Last Run” time will reflect this time difference, and of course any replication schedules involved in
replicating the status document back to the Request Processor database.
If you have more than 10 servers in your environment, click on the arrows on the right of the screen to scroll
the display up and down.
For more information on the Extended AdminP database, see the sub-section “Extended AdminP Processor”
in the “FirM Databases” section on page 153.

FirM Administration Manual v3.0 © 2009 HADSL


6 A D M I N I S T R AT I O N T O O L S PA G E 37 O F 145

4.4. Import Tab


The Import tab is used to import various objects to the FirM Environment.
 The Certifier ID sub-tab allows you to import new Certifier ID's into the FirM processing system.
 The Server ID sub-tab allows you to import a Server ID into the secure ID repository. FirM does not
manage servers and therefore will perform no operation on the server ID files once they are
imported. It does however, give the administrator a consistent ID repository for all his ID files.
 The CSV sub-tab allows the administrator to import FirM transactions from a CSV (Comma
Separated File).
 The Group sub-tab allows you to import groups from your existing Notes environment into FirM in
order that they can be managed.
 The User ID and Password tab allows you to import a CSV file containing passwords and references
to ID files. These are imported to the ID repository and Password repository.

4.5. 'Group Restore' Tab


The Group Restore Tab allows the System Administrator to restore a group that has been previously deleted
by the FirM Group Delete Request. To restore a group,:
 Click on “Restore a group previously deleted by FirM”.
 You will be prompted to select a group.
 You will be asked to confirm or modify the list of owners and administrators for this group. If this
group was deleted some time ago, it is entirely possible that some of the people named in this list
may no longer be valid.
 You may now be prompted for an expiry date for this group, if it was deleted during the expiry
process.
 Click on the “Recover Group” button to recreate this group in the directory.

4.6. BlackBerry Management Tab


The BlackBerry management tab is only visible if the BlackBerry feature has been enabled in the System
Configuration document. See the sub-section “System Configuration - BlackBerry” in the “System
Configuration” section on page 28 for more information.
This tab shows a number of internal views that FirM requires to manage BlackBerry users.

4.6.1. BlackBerry Users sub-tab


The BlackBerry Users sub-tab allows you to view all BlackBerry handset users that FirM has detected within
the BackBerry Enterprise servers defined within System Location Profile documents.
If you click on a user record, you see the following information:
 The Notes Name for this user
 The BES server responsible for this users BlackBerry communcations
 The PIN number of the users BlackBerry device
 The database name of the users “state” database on the BES server
 The date that this user account was first activated on the BES server.
You should not manually edit any of this information, as it is programmatically gathered from each BES
server.

4.6.2. BlackBerry Servers sub-tab


The BlackBerry Servers sub-tab shows all BlackBerry servers defined in location documents within the FirM
environment.

4.6.3. BlackBerry users by Server sub-tab.


This sub-tab shows BlackBerry handset users, categorised by the BES server responsible for their
communication.

FirM Administration Manual v3.0 © 2009 HADSL


6 A D M I N I S T R AT I O N T O O L S PA G E 38 O F 145

4.7. System Views Tab


The System Views tab contains views that FirM requires for its operation. You should never change
information within this tab unless expressly instructed to do so by HADSL support.

4.7.1. System Variables sub-tab


The System Variables sub-tab shows internally defined system variables used by FirM. These variables are
used to override default system behaviours, and as such should not be changed unless expressly instructed
to do so.
If you open one of these variables, you can observe the variable name and its value.

4.7.2. System Classes sub-tab


FirM is a data-driven, object orientated application. This table helps FirM find where pieces of code for each
transaction are located, and what they are called.

4.7.3. Static Fields sub-tab


Static Fields are defined within FirM, and linked to internal code. They help expose internal keywords (such
as “<UserName>” for instance) to the various “keyword” buttons on the FirM Profiles. These static fields are
then replaced at run-time with relevant values.

4.7.4. Active Directory Static Field Definitions


This tab shows keywords associated with Active Directory objects. These keywords show which object
attributes may be amended by FirM.

4.7.5. Active Directory DLL sub tab


This sub-tab allows you to view, install and update the DLL required for Active Directory operation.

4.7.6. MSI Scripts sub tab


This sub tab allows you to view and manage MSI (Microsoft Script Interface) Scripts which are used during
Active Directory Create User operations.

FirM Administration Manual v3.0 © 2009 HADSL


7 C O N F I G U R I N G S Y S T E M P R O F I L E S PA G E 39 O F 145

5. Configuring System Profiles


All System Profiles are found by navigating to the “Profiles, System Profiles” tab of the “Tools” control pane in
the FirM Request processor databases.

5.1. Common System Profile Tab – “Fields”


Some System Profiles, as well as the User Create Profile, have a “Fields” tab:
In this case, this is the “Fields” tab from the System ID Profile document.
If a Fields tab exists, this allows certain operations to be carried out on a new user created using this profile:

5.1.1. Defining Fields


Fields. Define fields that are created on the new users Person document. For instance:
 OfficePhoneNumber=121-212-232-1212
 Will populate the field “OfficePhoneNumber” on the person document with the value
“121-212-232-1212”. This is useful for defining static information that is common for all users
created using this profile type.
 Owner,AUTHOR=LocalDomainAdmins
 This will create a field called “Owner”, set it as an Author field, and assign it the value
LocalDomainAdmins.
Permitted keywords for the Field directive are:
Keyword
SUMMARY Make this a Summary Field.
All fields are Summary by default – this need not be explicitly defined
AUTHORS Make this an Authors field
PROTECTED Make this a Protected field
NAMES Make this a names field
READERS Make this a readers field on the target document
SIGNED Make this a signed field
ENCRYPTED Make this field available for encryption on the target document.
Bear in mind that the document should also have a “secretEncryptionKeys” field
specifying the encryption key to be used, and that this key should be available
on both the server and the client. Making a field ENCRYPTED means that the
field cannot be used in view indexes.
NOTESDATETIME Make this a Notes Date/Time field
NUMBER Make this a number field instead of a string field
DELETEFIELD Delete this field from the document

Multiple keys can be specified. For instance:


Owner,READERS,PROTECTED,SIGNED=LocalDomainAdmins
Bear in mind that “Dynamic Fields” can also be defined.

5.1.2. Groups
Groups. Should one or more groups be added to this field, then all users created using this profile will be
automatically added to these groups.

5.2. ID Profiles
ID Type profiles are mandatory profiles used during a User Create process. One or more of these profiles
may be associated with a particular User Create profile.

FirM Administration Manual v3.0 © 2009 HADSL


7 C O N F I G U R I N G S Y S T E M P R O F I L E S PA G E 40 O F 145

Sub-Tab Field Explanation

Detals Profile Name Give the profile a meaningful name in the context of your environment.

Description A description (that only the adminstrators can see) of this profile

Mail File Mail Template Gve the filename of the template you wish to use to create a user using
this profile. The template must exist on the target server you wish to
create the user upon.

Create a Full Should a Full Text Index be created?


Text Index

ACL Level Choose the ACL level the user should be granted in the mailfile

Mail Quota Set a mail file quota (in Mb) for this mail file

Mail Set a mail file warning threshold (in MB) for this mail file
Threshold

Create If the user is being created on a mail server which has cluster mates,
Replica on all and this parameter is set to ʻYesʼ, then their mail file would also be
Cluster created on all other members of the cluster.
Servers

ID Type User Type Choose whether users created using this profile are Notes users (and
therefore have an ID file created for them) or Web Users (where an ID is
not created)

Notes ID Type Lotus Notes supports two Notes Client key lengths - 64 bit
(International) and 128 bit (Global or US).

ID Validity Typically this would be measured in years (720+ days ) for full time staff,
or in hundreds of days for Contractors. Note that setting this value to a
lower number means more administrative work recertifying these
people.

Minimum The minimum length of password that these people have to use when
Password they choose a new password.
Length

Create HTTP This should be set to ʻYesʼ to allow FirM to create their Internet (or
password ʻHTTPʼ) password at the same time that the users are created.

 Password Change interval. This value is written to the new usersʼ Person document in the directory,
and dictates how often the new user should change their password.
 Grace Period. This allows the user to NOT change his password beyond his change interval –
usually 14 days or so. Only after the password change interval AND the grace period have expired is
the users account locked by Domino.
 Password Digest Enable Profile. If a Password Digest Enable profile is selected here, then the User
Password Digest function is ran after a user is created, using the details defined in the selected
profile.
 Roaming Profile. If a Roaming Enable profile is selected here, then the User Enable Roaming
function is ran after a user is created, using the details defined in the selected profile. (Note that
Roaming User enable is only relevant in Domino v6 or above)
 ID File Name. This field allows you to define how the usersʼ ID file is created.
 It should be noted that the userʼs mail server is determined using their Location Profile.
FirM Administration Manual v3.0 © 2009 HADSL
7 C O N F I G U R I N G S Y S T E M P R O F I L E S PA G E 41 O F 145

5.3. Country Profiles


Country profiles are profiles used to help define country specific information in the User Create and the User
Move Location processes. Zero, one or more of these profiles may be associated with a particular User
Create profile. You must, however, associate one Country profile with each Location profile.

Sub-Tab Field Explanation

Detals Profile Name Give the profile a meaningful name in the context of your environment.

5.4. Certifier Profiles


Certifier profile documents contain information on how to use the certifier within the User Create, User Move
and User Rename transactions.

Sub-Tab Field Explanation

Detals Profile Name Give the profile a meaningful name in the context of your environment.

Certifier This is picked directly from the Certifier Repository's list of certifiers and
Hierarchy cannot be edited. This ensures that this certifier profile always points at
a valid certificate entry in the Certifier Repository. This hierarchy field is
also used to find the certifier password from the Password Repository.

5.5. Location Profiles


Location profiles are mandatory profiles used in the User Create Process, and explicitly chosen in the User
Create profile document.
 ʻNameʼ Field allows definition of this Location profile. Care must be taken to define profile names that
are meaningful for your business users – as the location profile names may be visible and offered as
choices during user transactions.
 The ʻTarget Mail Serversʼ field contains a list of one or more target mail servers relevant for this
location name. In the above example there is one mail server named. This server will be the one
chosen for the userʼs target mail file.
If there is more than one mail server explicitly named in this field, the load balancing rule defined
below will be used.
 If one or more servers are specified in the Replica Mail Servers field then all users created using this
profile will have replicas of their mail files created on these servers.
 This location should be associated with a particular Country profile. This allows the User Move
Location transaction to calculate groups associated with Countries and Locations.
 The load balancing method for this method should be used. If there is more than one server to
choose from, FirM will use one of these rules to decide which server is most appropriate. The
choices are::
1. Least Users. At the moment the new user is created, the directory will be queried to
establish the server with the fewest number of users.
2. Most Free Disk Space . At the moment a new user is created, the System Extended AdminP
view “Server Heartbeat” will be queried to establish which server has the most available free
disk space.
3. Most Percentage Free Disk Space. At the moment a new user is created, the System
Extended AdminP view “Server Heartbeat” will be queried to establish which server has the
most available free disk space.

5.5.1. Location Profiles – 'Allowed Certifiers' tab.


This tab allows you to associate particular certifier hierarchies with this location. If your environment tightly
binds certifier hierarchies with locations, select certifier profiles valid for this location.

5.5.2. Location Profiles – 'Active Directory Servers' Tab


This tab allows you to assign one or more Active Directory file serves to this location. This is then used by
the Active Directory Create User transaction to assign new users to File Servers.

FirM Administration Manual v3.0 © 2009 HADSL


7 C O N F I G U R I N G S Y S T E M P R O F I L E S PA G E 42 O F 145

5.5.3. Location Profiles – 'BlackBerry Servers' tab


This tab allows you to define which BlackBerry Enterprise server services this site. This information is used
during a BlackBerry Provision transaction.
If more than one BES server is defined, then FirM allocates the next new person to the least loaded BES
server.

5.6. Business Group Profiles


Business group profiles are non-mandatory profiles used to help define business group-specific information
in the User Create process. Zero, one or more of these profiles may be associated with a particular User
Create profile.
All of the fields on a business profile form are ʻstandardʼ fields - see ʻUser Create Profiles - Standard Fieldsʼ
for more information.
The general term ʻBusiness Groupʼ is used in place of terms such as ʻDivisionʼ, ʻGroupʼ, or ʻDepartmentʼ as
these are company-specific terms.
ʻNameʼ. Care must be taken to define profile names that are meaningful for your business users – as the
Business Group profile names may be visible and offered as choices during user transactions.

5.7. Company Profiles


Company profiles are non-mandatory profiles used to help define country specific information in the User
Create process. Zero, one or more of these profiles may be associated with a particular User Create profile.

ʻNameʼ. Care must be taken to define profile names that are meaningful for your business users – as the
Company profile names may be visible and offered as choices during user transactions.

5.8. Internet Address Profiles


Internet Address profiles are non-mandatory profiles that enable you to set up more complex management of
the Internet Address field in users' person documents, and additional Internet addresses that should be
assigned to new users.
They are used in the User Create process and are associated with User Create Profiles. The User Rename
process can also use Internet Address profiles, as it needs to recalculate users' Internet Addresses.

ʻNameʼ. Care must be taken to define profile names that are meaningful for your users – as the Internet
Address profile names may be visible and offered as choices during user transactions.
ʻInternet Domainʻ. Enter the domain part of the Internet Address in this field, for instance “hadsl.com”. Do not
include “@” in this field.
ʻLocal-Part Constructionʻ. Enter the tags required for constructing the local part of the Internet Address in
this field. For instance, “<FIRSTNAME>.<LASTNAME>”. These tags will be replaced during request
processing, when the Internet Address is calculated.

5.9. Group Profiles


Group Profiles define the type of groups that users are allowed to create with FirM.

5.9.1. Group Profile – 'Details' Tab


 Profile Name:
 Group Type:
 Foreign Directory Synchronization:
 Owner Approval:
 Initial Membership:
 Allow Group Creation in:
A group profile is set up for each distinct type of group. This does not necessarily correspond to the Domino
group types (ACL, Mail, etc.) as there can be many different profiles defined.

FirM Administration Manual v3.0 © 2009 HADSL


7 C O N F I G U R I N G S Y S T E M P R O F I L E S PA G E 43 O F 145

Certain restrictions can be placed upon group types, for instance the Domino group-type. This means that
users of FirM do not have to have technical knowledge about the difference between a Mail Group, an ACL
group and a Multi-Purpose group.
Allowed membership of the group can be restricted so that, for instance, SMTP addresses cannot be added
to a group that has been set up using a ʻConfidential Internal Emailsʼ profile.
Workflow can also be set up. For instance, restrictions can be placed upon who can submit group create
requests, who can authorise them and who is notified.

5.9.2. Group Profile – 'Name Mask' tab


 Group Name – this enables group names to be built up using keyword tags. The part of the group
that the user enters is represented by the “<GROUPNAMEUSERELEMENT>” tag, and this is used
to construct the group name.
 Case Translation
 White space Removal
 Translation Order
The latter three fields define how the group name field should be translated, and in what order.

5.9.3. Group Profile – 'Internet' tab


 Internet Address: This is the internet address that will be assigned to the group. If an internet
address should not be assigned to a group then leave this field blank.

5.9.4. Group Profile ' Members' Tab


This tab defines what kind of address may be added to this group:
 SMTP Addresses: e.g. addresses of the format “fred@hadsl.com”
 Notes/Domino Users: Users listed within a Domino Directory
 Servers: Servers listed within a Domino Directory
 Mail-In Databases: Mail-in Databases listed within a Domino Directory
 Mail Groups: Mail-only groups listed within a Domino Directory
 ACL Groups: Access-Control list only groups within a Domino Directory
 Multi-Purpose groups: Multi-purpose groups within a Domino Directory
 Deny-Access Groups: Deny List Only groups within a Domino Directory
 Server Groups: Server Only groups within a Domino Directory
 Cross-Domain Membership: If this is set to “Deny” then groups and Notes users from only the
groupʼs domain will be permitted as members.

5.9.5. Group Profile ' Request' Tab


People listed in the “Create Group” field are allowed to request the creation of groups of this type.

5.9.6. Group Profile – 'Authorise' Tab


Who can authorise the construction of groups using this profile.
Force Separate Authoriser – if this is set to “Yes” then an authorisation is forced, i.e. a user cannot effect a
group creation without further authorisation by virtue of them being in both the “Request” and “Authorise”
lists.
Enable anyone to manage this group without authorisation: If this is set to “Yes” then group membership
management requests can be submitted by anybody and will not require further approval. This option
enables you to create non-critical groups for ʻpublicʼ membership – for instance contact lists for staff sports/
social events.

5.9.7. Group Profile – 'Notify' tab


Notification: In common with other FirM profiles, you can specify who should be notified upon successful
completion of various requests types against groups associated with this profile.

5.10. Automatic Recertification Profiles


Fields Defined:
FirM Administration Manual v3.0 © 2009 HADSL
7 C O N F I G U R I N G S Y S T E M P R O F I L E S PA G E 44 O F 145

 Profile Name
 Users Managed by this Profile. You may enter a “name mask” such as “*/Acme”, or “*” in this field, or
a list of user names, or a list of group names.
 Recertification Profile. Choose the Recertification profile that should be used for these users for this
profile.
 ID Profile. This is used to calculate the expiry period of this recertification event.
Automatically re-certify: Choose Yes for the Recertification Engine to perform automatic recertificationʼs on
these users.

5.11. Configuring Notification Profiles


Notification Profiles contain information required for FirM to construct email messages.
Notification messages are sent out by:
 The User Create process - this is the primary distribution method for sending out user ID files and
user passwords
 The back-end transaction processor - when agent or notification trigger points are reached.
 The back-end workflow processor - to inform people of authentication requirements or status.
Everything in a notification profile can be tailored by the administrator, i.e. the language used, the formatting,
whether doclinks to the original requests are included, etc..
 Trigger Event - This is the transaction type. For example, a User Create transaction.
 Trigger Name - This is a transactional stage. In this case, a notification message is sent out at the
ʻSendIDʼ stage of the User Create transaction.
 Principal - The name that appears in the ʻFromʼ field of the mail message that the user or
administrator receives, regardless of where this agent runs. This is useful to demonstrate to users
that this email address is non-functional, and should not be sent mail. It can also be used to
differentiate error messages from status messages and from informational messages.
 Recipients - To, CC, BCC. In many cases, the users receiving this message are set by the process.
In the case of the UCR-SendID file notification, the person to whom this message is sent is named in
the transaction as the ʻID Recipientʼ. The ʻTo, CC, BCCʼ fields can hold additional names of people
who will also receive this message.
 Attach files: You may define files that are attached to the email message from the hard drive of the
FirM processing servers. (This feature may be more conveniently performed by attaching the files
within the Rich Text footer – see below.
 Encrypt mail message - If this is set then only the Notes user(s) intended to get this message can
read this message. In the case of User ID files and passwords, it is strongly recommended that this
is set to ʻYesʼ.
 Keep Private: Switching this to “Prevent”.. ensures that the recipient of the notification cannot print,
forward nor copy the notification to the clipboard,
 View Icon Number: By selecting a view icon number, the notification is sent and a view icon
displayed in the recipientʼs inbox. This is useful in differentiating system created mail messages or
messages that require urgent attention from other email messages.
 Subject line - Enter the subject line text that the user receives, with optional tokens to be replaced at
run-time. For instance, during this User Create transaction, the token ʻ<firstname>ʻ is replaced with
the userʼs first name, etc..
 Body Text - The text that appears in the body of the mail message. Tokens may be included.
 Rich Text Footer. This allows rich text (formatted text, graphics, tables, file attachments, etc) to be
appended to the bottom of this particular notification profile. Note that you may also append a rich
text footer to the bottom of ALL notification messages by defining one in the Configuration Profile.

5.12. Configuring Agent Trigger Profiles


To trigger your own agents from any process within FirM,
 Navigate to the System Profiles configuration tab, and select “System Agent Trigger Profiles.
 Click on “Create a new Profile”
 Select the transaction or “trigger” that you wish to act upon

FirM Administration Manual v3.0 © 2009 HADSL


7 C O N F I G U R I N G S Y S T E M P R O F I L E S PA G E 45 O F 145

 Select the trigger type – “Success” means that the transaction was successful.
 Enter the name of your database
 Enter the name of your agent.

FirM Administration Manual v3.0 © 2009 HADSL


8 C R E AT I N G A N E W R E Q U E S T PA G E 46 O F 145

6. Creating a new Request


FirM allows you to create requests on a one-by-one basis, and allows the creation of multiple requests for
particular transactions.

6.1. Creating a single request


To create a single request:
 Open the request processing database, and click on the “New Request” button. A new frameset will
open, allowing the requester to create a request in the top pane, whilst still being able to see the
existing requests in the bottom pane.
 A dialog box will appear, inviting you to click on the “Forward” button.
 A “Checking security settings” dialogue will appear for a few seconds. At this point in time, FirM is
establishing (by looking up all FirM profiles) precisely which transactions this particular requester
may be able to see.
 The requester will then need to select the type of management request they want to create. This can
be done by selecting the option from the drop-down menu.
 The requester then chooses one request type, and clicks on “Forward”.
 At this point, the requester is led through the construction of the selected transaction.

6.2. Creating Bulk requests


In order to create multiple requests of the same transaction type (“Bulk Requests”), open the FirM request
processor database, and click on “New Bulk Request”
 A dialogue box will appear inviting you to click on “Forward”
 At this point, the current requesterʼs security information is being evaluated.
 The requester can then select a particular transaction type. Not all transaction types are available,
as some transactions require more information than a username to proceed.
 (Note that all transaction types can be imported from a CSV file. See the chapter entitled “Importing
transactions using CSV” on page 131).
 The requester may now select one or more names to perform the selected transaction on, by
entering them (or copy+Pasting them), selecting from a directory and so forth.
 All of the names entered are then validated against the directory to ensure that they exist. The list of
Accepted and Rejected users is now shown.
 The requester may now be prompted for a profile name for this particular transaction. In this case,
the requester has been prompted for a “Delete User” profile name.
 Depending on the profile, the requester may be prompted to defer this transaction.
 The transaction is now performed against all selected users and a status for each selected user is
displayed.

6.3. Importing Transactions using CSV


FirM allows transactions to be imported via a CSV file. This is of value where a large number of changes
need to be performed in a short period of time.

6.3.1. CSV File Overview


A CSV (Comma Separated File) is a text file,
 Where each data row is on a separate line
 Where each item of data is separated with a comma
 Where strings which may contain commas are surrounded by double inverted comma quotes
 Where the first line defines the field names contained in the file.

For example, a very simple CSV file might look like:


Name,address,postcode,phone number
“Joe Bloggs”, “1 The Penthouse, Anytown, England”, “PE1”, 0555-555-5555

FirM Administration Manual v3.0 © 2009 HADSL


8 C R E AT I N G A N E W R E Q U E S T PA G E 47 O F 145

The fields “Name”, “Address”, “Postcode”, “Phone Number” are defined in the top line, and the file contains
one record for “Joe Bloggs”.
The simplest way to generate a CSV file is to use a spreadsheet,
laying out columns and rows to mimic this:
You can then save the spreadsheet as a CSV file. In most
packages, “File”, “Save As” offers a CSV file format:

6.3.2. Importing Transactions Using CSV


FirM imports one CSV file at a time. This file may contain
one or more transactions, and transactions need not be of
the same type.
In order to import a CSV file, select “Tools”, and then
choose the “Import” Tab, and the “CSV” Subtab:

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 48 O F 145

7. FirM Domino User Transactions


7.1. Common Tab - Authorisation
The FirM Domino User Transaction Profiles all share a common “Authorisation” tab. This tab allows you to
set:
 Who can request a transaction using this profile
 Who can authorise a transaction created using this profile
 Which group of users can be acted upon.
The contains the following data items:

Tab Field Explanation

Requesters Users Self If this is set to YES, then any user can request this transation be
Request applied themselves. No requesters are required, and this
transaction is only visible on the web client.

Requesters A list of people who are allowed to request this transaction.


Names such as */Acme, groups and specific user names may be
used

Authorisors Authorisation Use List of Authorisers Below” means use the authorisors field.
Method Some transactions may allow user self-service, or for the
manager field in the target user document to be used.

Authorisors Authorisers tab controls who may authorise transactions created


using this profile.
Names such as */Acme, groups and specific user names may be
used
Should the requester appear in both tabs (either explicitly named
or by virtue of group membership), then the transaction is
deemed immediately authorised and then processed.

Separate You may enforce separate requesters and authorisers to override


this behaviour in more secure circumstances. Should this be set
to “Separate Requester and Authoriser”, then a new Authoriser is
required regardless of the requesters appearance in this tab.

Notification Who shall be A list of users or groups who shall recieve a mail message when
Notified the request is complete.

Manage Users Users Managed A list of name masks defining users to be managed by this
by this Profile profile. This allows certain profiles to be only applied against
certain users.

Defer Allow requesters If this is set to NO, then the requesters may not defer requests
to defer requests created using this profile.

Default days to The default value of days that this request will be defered by. The
defer request requester may override this.

Default Deferred The default time at which this process will be executed at. The
request time requester may override this.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 49 O F 145

Tab Field Explanation

Chain Chained A list of zero or more ʻChained Transactionʼ documents. If the


Transactions request is successful, then each chained transaction is
processed and may create more transactions based on the
current transactions run-time values.
This allows complex sequences of transactions to be
constructed.

Console Console A list of zero or more ʻConsole Commandʼ documents. If the


Commands request is successful, then each console command is processed,
allowing run-time information to be used and sent as a console
command to other servers.
This feature was introduced to allow the automatic creation of
QuickR personal folders when new users are created, and for the
folders to be removed when the user is deleted.

MC Marvel Client This allows zero or more Marvel Client configuration commands
Commands to be processed if this request is successful.

7.2. Name Construction and Token Replacement


A common method used throughout FirM is the ability to construct run-time information – such as the users
new Internet address – by using a token replacement language. For instance, to specify the Lotus Notes
“ShortName” field, you may use:
<FirstNameInitial><LastName>
Which is translated at run-time to the users first name first initial, plus the users last name.
A list of relevant keywords are available beside relevant fields by clicking on the “Keyword” button adjacent
to the field.
In some instances, in order to ensure uniqueness, it is necessary to introduce a sequential number at the
end of a name field. For instance, using the rules above, the first John Smith's shortname might be
“Jsmith001” and the second might be “Jsmith002”.
Three special keywords exist within the token processing system to cater for this:
 <UNIQUENUMBER1> - this generates a one-digit unique number – between 1 and 9
 <UNIQUENUMBER2> - this generates a two-digit unique number – between 01 and 99
 <UNIQUENUMBER3> - this generates a three-digit unique number – between 001 and 999
If these keywords are used in name fields, then the suggested name is attempted with an increasing number
sequence until uniqueness is ensured.

7.2.1. Unique Number Tokens


The unique number tokens are added to the name field being constructed, and then the potential name is
then tested against the Domino Directory and the Deleted User Repository.
For instance, if the short name field contains “<FirstNameInitial><LastName><UNIQUENUMBER2>,” and
the user “John Smith” is being created, then the system will construct “Jsmith01” and test for uniqueness. If it
is not unique, it will then increment the number and continue to test uniqueness until the name is unique.
This means that user “John Smith” might have short name “Jsmith01”, and Barney Stone might have short
name “BStone01”, and so forth.
It is important to note that this name uniqueness and unique number tokens is only available on the four
names fields – ShortName, FullName, Internet Address and Alternative Language Name. Fields such as Mail
File Name or Cluster File Name do not test for uniqueness.

7.2.2. Field Replacement Tokens


You can also use the Token Replacement system to pull in any fieldname from the current user document.
For instance, during a user delete, you can use <=Manager> to pull in the field 'Manager' from the current
person document.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 50 O F 145

7.3. User Create


User create allows a Requester to create a user in a FirM-registered Domino Directory.
Details relating to the notification of completion of this transaction are stored in the User Create profile
documents.

7.3.1. Walkthrough of transaction


To create new request, select “New Request” and click forward to the request selection dialog. Now select
ʻUser Createʼ.
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select one New Accounts user in Bracknell
user Create Profile from the list of profiles
available to him

Location Profile Each of these profile types may be set in the Dublin
User Create profile document. If more than
Certifier Profile one of each type is selected, then the /Acme
requester is asked to choose which
ID Profile particular profile is most appropriate for this Staff
operation.
Company Profile Acme

Country Profile UK

Business Group Accounting


Profile

AD User Create AD User in Bracknell


Profile

BlackBerry Provision BlackBerry user in Dublin


Profile

First Name Enter a valid name component for this user. John
This name is checked against name
Middle Initials validation rules to ensure that it conforms to A
the global system configuration Name
Last Name Validation rules set by the administrator. The Smith
Shortname component can be automatically
Short Name generated in which case it is not visible to JSmith101
the requester.
Each of these three name values is
compared against validation rules in the
System Configuration profile. If the names
pass validation rules, then the Domino
Directories are checked for uniqueness. If
any name fails, the Requester is informed
and invited to re-enter them.

Alternate Name A non-ASCII version of the users name. This


is enabled on the User Create profile by
enabling Alternate Name support.

ID Recipients A list of people who will receive the users


new ID File and Password. Depending on
the profile, this may be a fixed field (in which
case the requester can only see the
recipient) or can select recipients.
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 51 O F 145

Prompt Explanation
A list of people who will receive the users Example
new ID File and Password. Depending on
Password Recipients the profile, this may be a fixed field (in which
case the requester can only see the
recipient) or can select recipients.

Optional Groups The requester is prompted to select one or Accounts in Bracknell


more groups from a fixed list, or from the
Domino directory. The new user is then
added to these groups

Clone User This allows the requester to select another Joe Bloggs/Acme
user in the Directory. The new user will be
added to all groups that the selected clone
user belongs to, along with all other groups
from all selected profiles

Optional OU The profile document may allow the Purchase Ledger


requester to enter an optional OU for this
new user.

Defer Processing The profile document may allow the


requester to defer processing on this
transaction to some point in the future, if
approprate. Enter a date and time for this
transaction to initiate processing.

Other Prompts The profile may prompt the requester for


more information, which will ultimately be
added to the newly created users person
document in the directory.

7.3.2. FirM Processing


The Requester of the transaction will be compared against the Requester and Administrators fields in the
User Create profile. (See “User Create Profile” on Page 73). If the Requester is not allowed to submit this
request then it will fail.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor makes exhaustive checks to ensure that the user names requested (Notes Full Name, Short
name, Internet Name and common name - all are configurable in the System Configuration Profile) are
unique across all domains managed by FirM.
The Requester then constructs the user ID in the home FirM directory (irrespective of target domain) - and
then moves that record to the correct domain. (This is a notes limitation). Any static or dynamic ʻfieldsʼ
specified in the User Create profile, or any of the six system Profiles (ID, Location, Certifier, Company,
Country or Business Unit) is also applied, replacing ʻtokensʼ with run-time variables as necessary.
The userʼs Notes ID (if requested by the ID profile) and the userʼs initial password are stored in the encrypted
User ID repository and the Password Repository.
A UUP (Resend User ID and Password) request is constructed which will mail the userʼs Notes ID (if
created) and their password to the ID and Password recipients listed in the initial request.
Zero or more group manage member requests are created to add the user to groups specified in the User
Create profile, and any of the six system profiles (ID, Location, Certifier, Company, Country or Business Unit)
is also applied, replacing ʻtokensʼ with run-time variables as necessary
Using the User Create profile, the correct Location profile is examined to establish the target server. If more
than one target mail server is listed, the target server with the fewest users (according to the Domino
Directory) is used as the target server (load balancing).
The usersʼ primary replica mail file path is then constructed, together with the cluster mail file if this has been
specified. Otherwise the cluster mail file name will be the same as the primary replica mail file path.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 52 O F 145

An Admin4 request is then issued to create the userʼs primary replica database:
 On the correct target server
 Using the template name, quota and trigger level specified in the ID profile
 Adding the user's name to the mail file ACL at the level specified in the ID profile.
If a cluster replica mail file/s is/are specified in the ID profile, and the server is part of a Domino cluster
(again, established from the Domino directory), then an Extended AdminP request is constructed, which:
 Replicates to the userʼs primary mail server, and waits until the userʼs mail file has been created by
AdminP
 Creates one or more AdminP requests creating the mail file replica on the other cluster mates as
governed by AdminP
Once processing has completed then any people specified within the Notification list for the relevant group
profile will be sent an email telling them that the group has been created.
If the System ID profile dictates Roaming and/or Password digest operations, sub transactions will be
created to perform these tasks.
The request will remain in the state ʻPending Sub transactionʼ until the AdminP requests and the Extended
AdminP Requests have completed. It will then progress to ʻCompleteʼ.
As with all FirM requests, logging information at every stage is created in the Log Database, Audit trail
records are created in the Audit Database, and Billing information is created in the Billing Database.
A welcome message (defined in System Notification profiles, with a name of “UCR-Welcome” will be mailed
to the user.

7.3.3. Internet Address Profiles


The FirM User Create process can be set to use one of two methods for assigning Internet mail addresses to
users - “Simple Internet Address” and “Internet Address Profiles”.
The Simple Internet Address method calculates a single mail address for the user and sets the new user's
Internet Address field in their person document. This is useful if your organisation has only a single Internet
domain for mail addressing.
If, however, you have multiple Internet mail domains then Internet Address profiles allow much more
flexibility in assigning these addresses to users.

7.3.4. User Create Profile


The User Create profile document enables the FirM Administrator to define how FirM Requesters are able to
create users and defines the following data fields:

Tab Sub-Tab Field Explanation

Name Profile Name The name of this profile.


The User Profile Name is used within FirM as a reference,
and can be any text string. It is recommended that this
name is appropriate to the corporate context in which it will
be used so that FirM Requesters may readily identify the
User Profile they need.

Description A textual description for this profile, visible only to


administrators

Fields Field Field Settings This defines values to set in person document fields, as well
and Definitions as dynamic fields which prompt the requester at run-time.
Groups

Mandatory Default Groups Zero or more Domino groups which the new user will be
Groups added to.
Each group addition is handled in the same manner as a
normal Group Manage Members request, and will therefore
honour any instructions on that group policy – such as
requesting permission from the Group Owner.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 53 O F 145

Tab Sub-Tab Field Explanation

Allow user If set to yes, the requester will be prompted for the name of
Cloning a user to clone. That is, the newly created user will be
added to all groups that the selected ʻcloneʼ user is already
a member of.
Each group addition is handled in the same manner as a
normal Group Manage Members request, and will therefore
honour any instructions on that group policy – such as
requesting permission from the Group Owner.

Optional Allow Optional If set to Yes, the requster will be prompted to add the new
Groups Groups user to optional groups
Each group addition is handled in the same manner as a
normal Group Manage Members request, and will therefore
honour any instructions on that group policy – such as
requesting permission from the Group Owner.

Limit optional If set to No, then the requester may choose any group from
groups the directory. If set to yes, then the requester is only shown
the list of groups defined in the profile

Optional A list of Domino Groups which the requester may add the
Groups newly created user to

Termination Enable User This allows name-reuse in that the new user name is
Groups Profile automatically ʻenabledʼ - that is, their name is removed from
the terminations group. Select a User Enable profile in this
field to enable this feature.

Names Full Name Notes Domain Select (from a list) the relevant Lotus Domino domain that
and the new user will be created in. These values are retrieved
Domains from the Global Configuration Profile

Notes Name A list of tokens which help define how the Notes Full Name
is defined. Use the adjacent ʻKeywordsʼ Button to browse
available run-time keywords to use.

Alternate This enables the Lotus Domino Alternate Name support,


Name Support filling in the users ʻAlternate Nameʼ in their person document
with non-ASCII versions of their names.

Short Name Generate If set to Yes, allow FirM to generate the users ShortName
Short Name value using the rules defined below. If set to No, will prompt
the requester at run-time.

Define Short A list of tokens which help define how the Notes ShortName
Name is defined. Use the adjacent ʻKeywordsʼ Button to browse
available run-time keywords to use.

Alternate If the first rule results in a non-unique shortaname, then the


ShortName optional Alternate ShortName field is used. If this is
Rules unsuccessful, then the request fails.

Translate Short This allows the shortname to be transated to lowercase,


Name uppercase, or Propercase.

Optional OU Optional OU This allows the administrator to define how Optional OUʼs
Handling are handled for this profile.

use this OU If a mandatory OU is set then the value in this field is used
as the optional OU component

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 54 O F 145

Tab Sub-Tab Field Explanation

Choose from If a list of OUʼs is provided, then the requester will be asked
OU to choose one item from this list.

Optional OU is If set to Yes, then the requester is not forced to pick or enter
Optional an optional OU field

Internet Internet Addres If this is set to ʻUse Simple Internet Address Specificaitonʼ
Naming Profiles then the new user will have a single internet address set,
using the rules defined on this tab. Otherwise, the internet
address profile scheme will be used.

Character Decide how various characters are to be translated when


Translation generating internet address values. The apostrophe
replacement, space replacement and translation fields are
common to both Simple and Internet Address Profile
options. Use these to define the translations that are
applied to the final calculated Internet addresses.

Internet Define the users simple Internet Address using tokens


Address (availble by pressing the adjacent ʻKeywordʼ button)

Alternate If the Internet Address does not result in a unique internet


Internet address, attempt to generate an internet address using this
Address rule instead. If this still fails, then the transction will fail.

Internet The Internet Domain used to create this users simple


Domain Internet address

Internet Allowed First, use the Allowable Profiles field to select the Internet
Profiles Profiles Address Profiles that are to be enabled for this User Create
profile.

Outbound Next, specify whether you want the outbound address to be


Internet calculated and applied automatically, or whether there
Address should be a selection displayed to the requester at request
creation time. If you apply the address automatically, then
you must select an outbound profile from the list in the
Outbound Internet Address field.

Inbound If you want to enable additional inbound Internet Addresses,


Address Field then specify a person document field name in the “Inbound
field name” field. If this field is left blank then it will default
to using the “FullName” field.

Always add The “Always add Outbound address to Inbound field” will
Outbound ensure, if enabled, that the user's Internet address is always
address to added to the inbound field. Use this, for instance, to make
Inbound field sure that user's Internet address always appears in the
FullName field.

Mandatory or Finally, use the “Mandatory or Optional” field to determine


Optional how additional inbound Internet addresses are assigned.
You can set the profile so that additional addresses are
never added, that all additional addresses are automatically
calculated and added, or to allow the requester to select
which addresses should be added at request creation time.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 55 O F 145

Tab Sub-Tab Field Explanation

Mail File Compute Mail This allows the use of @Formula to define which primary
Naming File and secondary mail file database name should be used for
this user. The first item on the text list returned defines the
primary mail file name, and the second item on the list
defines the cluster mail file name if different.

Mail File Name You define the file name that the new users mail file will
have using tokens, available by pressing the adjacent
ʻKeywordsʼ Button.

Translate Mail Apply any case-translations to the mail file name, such as
File Name setting it all to lowercase.

Cluster Mail You define the file name that the new users cluster file will
File Name have using tokens, available by pressing the adjacent
ʻKeywordsʼ Button. If this is blank the same name as the
mail file will be used.

Translate Apply any case-translations to the cluster mail file name,


Cluster Mail such as setting it all to lowercase.
File Name

Sub- ID ID Types Choose one or more ID profiles to use whilst creating new
Profiles users. If more than one profile is checked, the requester will
be asked to choose between them at run-time. At least one
must be chosen.

Locations Locations Choose one or more Location profiles to use whilst creating
new users. If more than one profile is checked, the
requester will be asked to choose between them at run-
time. At least one must be chosen.

Certifiers Certifiers Choose one or more Certifier profiles to use whilst creating
new users. If more than one profile is checked, the
requester will be asked to choose between them at run-
time. At least one must be chosen.

Companies Companies Choose one or more Company profiles to use whilst


creating new users. If more than one profile is checked, the
requester will be asked to choose between them at run-
time.

Countries Countries Choose one or more Country profiles to use whilst creating
new users. If more than one profile is checked, the
requester will be asked to choose between them at run-
time.

Business Business Choose one or more Business Group profiles to use whilst
Groups Groups creating new users. If more than one profile is checked, the
requester will be asked to choose between them at run-
time.

Active Active Choose one or more Active Directory profiles to use whilst
Directory Directory creating new users. If more than one profile is checked, the
Profile requester will be asked to choose between them at run-
time. At least one must be chosen.
If one or more is selected, then an Active Directory User
Create transaction will be automatically created when this
Domino User Create transaction is successful.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 56 O F 145

Tab Sub-Tab Field Explanation

Set AD Login Use Tokens (available from the adjacent Keywords button)
Name to select tokens to construct the users Active Directory login
name.

BlackBerry BlackBerry Choose one or more BlackBerry profiles to use whilst


Profile creating new users. If more than one profile is checked, the
requester will be asked to choose between them at run-
time.
If one or more is selected, then BlackBerry Handset
Provision transaction will be automatically created when this
Domino User Create transaction is successful.

ID & ID Files ID Distribution Choose how the ID file will be distributed from the ID
Password repository.

ID Mail Choose how the recipients of the ID file mail message are
Recipients set - either set using the profile or chosen at run-time.

Passswords Password Choose whether the new usersʼ notes Password is


Distribution distrubuted when the user is created.

Password Mail Choose how the list of people to receive the users
Recipients Password is constructed.

7.3.5. User Create CSV Definition


The following fields are defined in the CSV interface for this transaction.

Header Field Mandatory Comments


Transaction Yes This should always be “UCR”
TransactionProfile Yes A User Create profile defined in FirM
NewFirstName Yes The new usersʼ first name
NewMiddleInitials Depends on The new usersʼ middle initials field
UCR Profile
NewLastName Yes The new usersʼ Last or Family name
BusinessGroupProfile See Note Below The name of the Business Group profile to be used
during this user creation.
CertifierProfile See Note Below The name of the Certifier profile to be used during this
user creation.
CompanyProfile See Note Below The name of the Company profile to be used during
this user creation.
CountryProfile See Note Below The name of the Country profile to be used during this
user creation.
IDProfile See Note Below The name of the ID Profile to be used during this user
creation.
LocationProfile See Note Below The name of the Location profile to be used during
this user creation.
IDRecipients Yes One or more users who shall receive the ID file
created for this user. Separate multiple recipients with
the semi-colon (“;”) character.
PasswordRecipients Yes One or more users who shall receive the password
automatically created for this user. Separate multiple
recipients with the semi-colon (“;”) character.
AlternateName No A users Alternate Name.

If a particular User Create profile only allows one Business Group Profile, for instance, it need not be
specificed in the CSV file import.
An example CSV file for a User Create Transaction would look like:
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 57 O F 145

Transaction, TransactionProfile, NewFirstName, NewMiddleInitials, NewLastName,


BusinessGroupProfile, CertifierProfile, CompanyProfile, CountryProfile, IDProfile, LocationProfile,
IDRecipients, PasswordRecipients
“UCR, “Default UCR Profile”, “Joe”, “”, “Bloggs”, “Business Group Profile Name”, “Certifier Profile
Name”, “Company Profile Name”, “Country Profile Name”, “ID Profile Name”, “Location Profile
Name”, “My IT Support/MyCo”, “My Boss/MyCo”

7.4. User Cross-Certify


The User Cross-Certify transaction allows a requester to cross-certify a user with a new Notes Hierarchy.
Details relating to the notification of completion of this transaction are stored in the User Cross-Certify
Profile.

7.4.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Cross-Certifyʼ
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Cross Certify Profile from the
list of profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

7.4.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the User
Cross-Certify Profile document. If the Requester is not allowed to submit this request then it will fail. A
similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then find the userʼs latest Safe-ID stored in the repository, and then apply a Cross-Certificate
operation against that and the new Hierarchy defined in the Profile document.
Once processing has completed then any people specified within the Notification list defined in the User
Cross Certify Profile will be sent an email telling them that the request has succeeded.

7.4.3. User Cross-Certify Profile


The User Cross-Certify profile allows the administrator to define who can request that a target user has their
user ID cross-certified with another hierarchy.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

Certifier Profile The name of the certifier to cross certify target users against.

ID Profile Define the ID profile to be used in order to calculate how long the
Cross-certification is valid for.

7.4.4. User Cross Certify Definition

Header Text Mandatory Comments


Transaction Yes URCC
TransactionProfile Yes A User Cross Certify profile defined in FirM
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 58 O F 145

UserName Yes A fully hierarchical name identifying the user for this
transaction

7.5. User Modify


Allows a user to modify details on a person record in a FirM-registered Domino Directory.
Details relating to the notification of completion of this transaction are stored in the User Modification profile.

7.5.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Modifyʼ.
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the Update Telephone Number
relevant user Modify Profile from the list of
profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

Other Prompts The profile may prompt the requester for


more information, which will ultimately be
added to the newly created users person
document in the directory.

7.5.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the User
Modification profile document. If the Requester is not allowed to submit this request then it will fail. A similar
check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then updates the person document identified in the request with the information entered by
the user.
Once processing has completed then any people specified within the Notification list defined in the User
Modification profile will be sent an email telling them that the group has been created.

7.5.3. User Modify Profile


A User Modify Profile allows you to define exactly what fields on a target users “person” document you wish
to allow modification to, and define who should be allowed to request transactions of this type.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

Fields Fields One or more field defintions. Dynamic fields - information prompted for at
run-time - can be used by clicking on the Dynamic Fields button.

7.6. User Disable


The User Disable transaction allows a requester to disable a user in a FirM-registered Domino Directory. The
user is disabled by adding their name to the relevant “terminations” group in the Domino Directory.
Details relating to the notification of completion of this transaction are stored in the User Disable Profile.

7.6.1. Walkthrough of transaction


To create new request, select ʻNew Request”, ʻUser Disableʼ.
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 59 O F 145

The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Disable Profile from the list of
profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

7.6.2. FirM Processing


The Requester of the transaction will be compared against the User Disable Profile Requesters and
Administrators field. If the Requester is not allowed to submit this request then it will fail.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor will now add the user to the deny-access group defined in the System Settings - Directories
tab.
Once processing has completed then any people specified within the Notification list for the relevant User
Disable Profile will be sent an email telling them that the request has succeeded.

7.6.3. User Disable Profile


The User Disable profile specifies how a particular user should be disabled from the environment and who
should be allowed to disable users.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

Active If defined, the Domino User Disable transation will then generate an Active
Directory Directory user Disable transation using this profile.
Profile

BlackBerry If defined, the Domino User Disable transation will then generate a
Profile BlackBerry Disable transation using this profile.

Move Person This option moves the person to the deleted users repository when the
Document to user is disabled. This means that the user is no longer visible in the
Deleted Users Domino directory, nor can authenticate to servers or receive new mail
Repository messages.
Do NOT use this option when including this disable profile in a User Delete
request.

7.6.4. User Disable CSV Definition

Header Field Mandatory Comments


Transaction Yes Should always be “UDI”
TransactionProfile Yes A User Disable profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction
An example CSV file for a User Disable transaction would look like:
Transaction, TransactionProfile, UserName
“UDI, “Default UDI Profile”, “Joe Bloggs/MyCo”

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 60 O F 145

7.7. User Enable


Allows a user to request a user to be enabled in a FirM-registered Domino Directory. The user is enabled by
removing their name from the relevant “terminations” group in the Domino Directory.

7.7.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Enableʼ.
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

User Enable Profile The user is being prompted to select the


relevant user Enable Profile from the list of
profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

7.7.2. FirM Processing


The Requester of the transaction will be compared against the User Enable Profile Requesters and
Administrators field. If the Requester is not allowed to submit this request then it will fail.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor will now add the user from the deny-access group defined in the System Settings - Directories
tab for the userʼs domain.
Once processing has completed then any people specified within the Notification list for the relevant User
Enable profile will be sent an email telling them that the request has succeeded.

7.7.3. User Enable Profile

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

Active Directory If defined, the Domino User Enable transation will then generate an
Profile Active Directory user Enable transation using this profile.

BlackBerry Profile If defined, the Domino User Enable transation will then generate a
BlackBerry Enable transation using this profile.

Allow re-enable This option moves the person from the deleted users repository back
from Deleted into the domino directory when the user is enabled.
Users Reposiitory

7.7.4. User Enable CSV Definition


Header Field Mandatory Comments
Transaction Yes Should always be “UEN”
TransactionProfile Yes A User Enable profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction
An example CSV file for a User Enable transaction would look like:
Transaction, TransactionProfile, UserName
“UEN, “Default UEN Profile”, “Joe Bloggs/MyCo”

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 61 O F 145

7.8. User Delete


The User Delete transaction allows Requester to request deletion of a user in a FirM-registered Domino
Directory.
Details relating to the notification of completion of this transaction are stored in the User Delete Profile

7.8.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Deleteʼ.
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Delete Profile from the list of
profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

Deletion Date The day on which this user should be


deleted from the directory. This allows the
requester to delete this user in the future.

Data Owner The profile can specify that another user -the
Data Owner - can be owner of the deleted
users mail file for a short period of time.

7.8.2. FirM Processing


The Requester of the transaction will be compared against the Requesters and Authorisers in the User
Delete Profile. If the Requester is not allowed to submit this request then it will fail.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.

7.8.3. Initial processing phase – immediate


The list of groups that this user is a member of is enumerated, and listed to the UDE request.
A ʻDisable Userʼ request is immediate processed for this user, using the Disable User Profile name defined in
the User Delete Profile.
This in turn generates a Group Manage Members sub-transaction, which then places the user name in the
relevant deny-access group (defined by domain membership in the System Configuration Directories pane).
If the profile option to hide the person document with readerfields has been enabled, then a readers field will
be created on the person document and populated with the list of usernames provided in the profile. This
will prevent the person from appearing in mail addressing and other name dialogs.
If a ʻdata ownerʼ has been defined, the data owner is informed that he has access to the userʼs mail file. A
mail message is sent using the notification profile UDE-DDONotify.
A ʻSystem ACLʼ Extended AdminP Process is spawned to grant the Data Owner access to the userʼs mailfile.
The ACL entry is by default set to ʻREADERʼ.

The ACL for the userʼs mailfile will be updated in order to change the ACL level for the DDO.

A ʻclass variableʼ called ʻDDOACLLevelʼ allows you to set different Data Owner ACL Levels. In order to
change this, edit the class definition for the UDE, go to the ʻClass Settingsʼ tab on the class definition, and
ensure that in the ʻClass Settingsʼ section, you create a new line with:
ʻDDOACLLevel=<ACLLEVEL>ʻ, where <ACLLEVEL> is replaced with one of:
 Depositor
 Reader
 Author
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 62 O F 145

 Editor
 Designer
 Manager
(See the section “System Variables Sub-tab” on page 31)
If a ʻdata ownerʼ has been defined:
 The transaction will defer itself for 30 minutes, and wait until the ʻSystem ACLʼ Extended AdminP
transaction is complete, and has been replicated back to the FirM processing server. It will keep
repeating this check until the ʻSystem ACLʼ request is complete.
 Once the transaction is complete, FirM will then retrieve the users mail file database replica ID from
the ACL request, and use it to populate the ʻ<DBLINKBYUNIDʼ token on the UDE-DDONotify mail
message, in order that the data owner can then click on a database link to open the users mailfile.
The transaction then ʻdefersʼ itself to the supplied Deletion Day. On or after 1 minute past midnight on that
day, it will then proceed to the next stage.

If the deletion date is today (that is, the user is to be immediately deleted) the transaction defers itself for 30
minutes to allow time for the UDI operation to complete.

7.8.4. Deletion Day process


On the day that the user should be deleted, the transaction wakes up from ʻdeferredʼ mode again. It checks
to see if the UDE profile allows the ʻarchivingʼ of the userʼs mail file.

7.8.5. Deletion Day Process – Non Archiving flow.


The process flow for non-archiving UDEs is quite different from those that allow archiving. The non-archiving
process is described:
 The userʼs person document is backed up to the deleted names register.
 The personʼs document is copied to the audit log.
 The userʼs status in the ID and Password repository is set to ʻdeletedʼ.
 An AdminP request is generated to remove
 this user from the Directory
 this user from All ACLʼs
 this user from All names fields
 the userʼs mail files. (if set in the UDE profile document)
Note that the AdminP request – A type ʻ0ʼ – ʻDelete User in Directoryʼ spawns these other requests, including
the ʻApprove Mail File Deletionʼ request (Type ʻ22ʼ). This means that the Domino Administrator has to
approve the removal of the userʼs mail databases in the AdminP database before they will physically be
removed.

7.8.6. Deletion Day Process –Archiving mail file process


When we enable the ʻarchivingʼ of the userʼs mail file in the UDE profile document, we are telling FirM that
instead of removing the userʼs mail file from all servers, we wish that a replica of the userʼs mailfile be placed
on a particular server (defined in the UDE profile) and in a particular directory (again, defined in the UDE
profile).
In this process flow, the user person document has to be completely removed from the directory before the
mail file can be archived – AdminP will then convert this ʻmove replicaʼ request to a ʻmove mailfile replicaʼ
request. This of course may fail as the user is no longer in the directory, or the user is not allowed to place
databases on the archive server.
This process flow has to manage the timing of these AdminP requests.
The UDE process flow looks like:
 The userʼs person document is backed up to the deleted names register.
 The personʼs document is copied to the audit log.
 The userʼs status in the ID and Password repository is set to ʻdeletedʼ.
An AdminP request is generated to remove
 this user from The Directory

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 63 O F 145

 this user from All ACLʼs


 this user from All names fields
Note that the userʼs mail files are NOT explicitly removed by AdminP at this stage.
The UDE transaction is then ʻdeferredʼ or put to sleep for 30 minutes.
The UDE transaction awakens, and checks to see if the person document still exists in the directory. If so, it
defers itself for another 30 minutes, and returns to this point to re-check that the user has been removed.
At this stage, since the user name is no longer in the directory, an extended AdminP request (ʻSYSMBDʼ or
System Move Database) is created.
This in turn creates an extended AdminP document in the Extended AdminP database
The document is replicated to the userʼs HOME mail server.
The System Extended AdminP Agent ʻServerAgentʼ picks up this document, and creates a new AdminP
request (Type ʻ14ʼ – ʻMove Replicaʼ) in the serverʼs Admin4.nsf database. It uses the userʼs primary mail file
as the source server and database, the archive server as the target server, and places the userʼs mail file
into the defined Archive directory, using the full source path of the userʼs mail file.
For instance, if the userʼs mail file was called ʻmail/user1.nsfʼ, and the archive directory was defined as
ʻArchiveʼ, then the mail file will be moved to target directory ʻArchive/mail/user1.nsfʼʼ.
It then marks this extended AdminP request as complete.
AdminP then processes this new AdminP request. This is done in various stages, generating:
 Initially the Type 14 – Move Replica
 A type 25 – Monitor Replica Stub
 then a Type 15 – ʻdelete original replica after Moveʼ. This means that the AdminP process itself
removes the userʼs primary mailfile ONLY when it is satisfied that the replication process has been
successful between the userʼs home server and the archive server.
Now UDE creates a ʻSYSDBDELʼ transaction. It examines the UDE profile ʻdelete userʼs mail fileʼ setting. If
this is set to ʻjust delete the userʼs mail fileʼ, (ʻ0ʼ) or set to ʻdonʼt delete the userʼs mail fileʼ (ʻ1ʼ) then no
SYSDBDEL transaction is created. Otherwise, if the profile setting is set to ʻDelete userʼs mail file and all
replicasʼ, then a SYSDBDEL sub-transaction is created. This:
 Creates an Extended AdminP transaction, which in turn creates a new document in the Extended
AdminP Database, with a transaction type of ʻ(SYSDBDEL)ʼ.
 This is then replicated to the userʼs home server.
The Extended AdminP ServerAgent then picks up this document and:
 Works out which other servers are in the same cluster as this server.
 For each other server in the cluster, it generates a (SYSDBDEL) transaction, passing the database
replica ID of the userʼs mail file.
 It then marks this transaction as complete, and terminates.
Note that this mechanism is NOT used to remove the userʼs primary mail file from the cluster, as its entirely
possible that the AdminP process to ʻarchiveʼ this mail file might still be in operation. It is left up to the
AdminP process to remove the primary mail file once the archive process has completed.
The new (SYSDBDEL) ExAmp transactions then replicate to the cluster mates of the userʼs home server.
Each cluster mate picks up the ExAmp (SYSDBDEL) transaction. If it finds a replica of the userʼs mailfile (by
path or by replicaID), it then generates a (SYSDBDEL2) EXAMP transaction, destined for the AdminP
administration server for the domain. This is defined as the server listed as the administration server of the
Domino directory for this domain.
The (SYSDBDEL2) transactions are then replicated to the Administration server for the domain.
The administration server Extended AdminP process then picks up these (SYSDBDEL2) transactions, and
forms type ʻ21ʼ ʻDelete Mail fileʼ AdminP transactions for each of the replicas found on the cluster mates.
Note that no authorisation is required within AdminP for these transactions to continue (unlike the non-
archive process flow listed above).
AdminP then replicates back to the servers containing the userʼs mail file, and removes those databases.
At this point, the UDE itself is complete. Note that it may take some time for the ExAmp and AdminP
transactions themselves to complete – perhaps four or five replication cycles. The UDE transaction itself
sets itself to ʻawaiting sub transactionsʼ and awaits the SYSMBD and SYSDBDEL transactions to complete.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 64 O F 145

7.8.7. User Delete Profile


The User Delete profile specifies how a particular user should be deleted from the environment and who
should be allowed to delete users. Note that each user deleted is also immediately disabled from the
Domino environment.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

User Disable Select a Domino User Disable profile from this list. This User Disable
Profile profile will be used to disable the user as soon as this request is
processed.

BlackBerry Profile If defined, the Domino User Delete transation will then generate a
BlackBerry Delete transation using this profile.

Allow retreval This option allows the requester to choose a Domino User to delete
from Deleted from the Deleted users repository.
users

Deletion Allow the the FirM Requester may specify a person who is automatically
Process Requester to granted access to the deleted users' mail file for a period of time.
assign a data The Data Owner is defined at run-time. Use of this option should be
owner in line with your organisationʼs data retention and security guidelines.

Data Owner Allow the requester to choose whether a Data Owner should be
Mandatory assigned

Delete Users Delete Userʼs Mail file. Choose how the delete process should deal
Mailfile with the deleted users mail file.

Hide Person Specify whether you want to hide the person document with reader
Documents fields at the start of the process. If this option is selected then a field
name must be provided, and a list of users, groups or roles that will
see the document. You must ensure that mail and adminp servers are
still able to see the document afterwards – and this includes the name
of the user that enabled the FirM processing agent.

Archiving Archving Choose whether or not to archive the users mail file at the end of the
process.

Archive Server Choose whether the mail files are to be moved to an archive server, or
just to another directory on the same mail server

Server Name The Archive server where the users mail file will be moved

Archive Directory The Directory in which the mail file will be placed.

7.8.8. User Delete CSV Definition


Header Field Mandatory Comments
Transaction Yes Should always be “UDE”
TransactionProfile Yes A User Delete profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction
DataOwner No The name of a person who will “own” this users mail
file.
DeletionDate Yes The date on which this user will actually be removed.
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 65 O F 145

An example CSV file for a User Delete would look like:


Transaction, TransactionProfile, UserName, DataOwner, DeletionDate
“UDE, “Default UDE Profile”, “Joe Bloggs/MyCo”, “”, “01/01/2005”

7.9. User HTTP password reset


Allows a requester to reset a userʼs HTTP (or “Internet”) password.

7.9.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻReset HTTP password”.
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user HTTP Password Reset Profile
from the list of profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

Password The target usersʼ new password. A default


new password is generated, which the
requester may override.
The password strength is checked and that
the requester may be prompted to enter a
new password if the one entered is not
strong enough. The password strength is set
on the transaction profile document.

7.9.2. User Reset HTTP Password Profile


The User Reset HTTP Password profile is used to specify how a particular user's HTTP (or Internet)
password should be changed and who should be allowed to change it.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

Force Password Force the user to change their HTTP password next time they log into
Change on next Domino using their browser
Login

Password The higher the number, the more complex the password - its specified
Strength on a scale of 0 to 16. Levels are defined in the Lotus Administratorʼs
manual in the article ʻThe Password Quality Scaleʼ.

Active Directory If set, run an Active Directory User Password reset transaction
Profile immediately after the HTTP password reset transaction, setting the AD
password for this user.

7.9.3. User Reset HTTP Password CSV Definition


Header Text Mandatory Comments
Transaction Yes URP
TransactionProfile Yes A User Reset HTTP Password profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 66 O F 145

NewPassword Yes The users new password

7.10. User Mail file Grant Access


The User Mail file Grant Access transaction a requester to open a users mail file for access to another
person, then optionally close that access down at a later point. This feature is of particular value to a security
audit team.
Details relating to the notification of completion of this transaction are stored in the User Mail file Grant
Access Profile.

7.10.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Grant Mail file Accessʼ
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Grant Mailfile Access Profile
from the list of profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

Data Owner A user from the directory who will have Auditor McAudit/Acme
access to the target users mail file.

Remove Access The date on which access should be


removed

7.10.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the User
Grant Mail file Access Profile document. If the Requester is not allowed to submit this request then it will fail.
A similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor will then issue an Extended AdminP request to change the target users mailfile ACL. Once
that has completed, then the data owner is sent an eMail informing them that they now have access.

Optionally, at the end of the access period, another Extended AdminP request is issued to remove the data-
owners access from the target users mail file.
Once processing has completed then any people specified within the Notification list defined in the User
Grant Mail file Access Profile will be sent an email telling them that the request has succeeded.

7.10.3. User Mail File Grant Access Profile


The User Mail File Grant Access profile allows you to define who is allowed to delegate access for a target
user. This transaction is useful for temporarily granting access of a target users mailfile to another Notes
user.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 67 O F 145

Tab Field Explanation

User Target Name Choose how the requester will choose the target user
Mailfile
Grant
Access

Send Mail Setting this to Yes means that the user is sent a message at the start
Message to user of the process informing them that the data owner has access to their
mail, and at the end to inform them that the access has been removed

Requester can set The requester can choose how long the data owner has access to the
Access Period target users mailfile

Number of working The Number of days that the data owner has access to the target
days to grant users mail file.
access

Access Control Choose an appropriate ACL level for the Data Owner
Level granted

Remove this entry Allow the control over the removal of the data owner from the target
from the users users mailfile.
mailfile

7.10.4. User Grant MailFile Access CSV Definition


Header Field Mandatory Comments
Transaction Yes Should always be “UMA”
TransactionProfile Yes A User Mail file Grant Access profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction
DDODuration Yes The time, in days, that a DDO should be allowed
access to this users mail file
DataOwner Yes The name of the data owner

An example CSV file for a User Grant Mailfile Access transaction would look like:
Transaction, TransactionProfile, UserName, DDODuration, DataOwner
“UMA, “Default UMA Profile”, “Joe Bloggs/MyCo”, 3, “My Boss/MyCo”

This transaction would allow “My Boss/MyCo” access to “Joe Bloggs/MyCo”ʼs mailfile fot three days.

7.10.5.User MailFile Quota


The User MailFile Quota transaction allows a requester to optionally view and set a target users mailfile with
a new Quota and Threshold. Details relating to the notification of completion of this transaction are stored in
the User MailFile Quota Profile.
7.10.5.1.Walkthrough of transaction
To create a new request, select ʻNew Requestʼ, ʻUser MailFile Quotaʼ
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Mailfile Quota Profile from the
list of profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 68 O F 145

Prompt Explanation Example

Quota Band The requester is asked to choose a relevant


quota band for this user (from a list defined i
the global adminstration configuration
profile).

7.10.5.2.FirM Processing
The Requester of the transaction will be compared against the list of valid Requesters defined in the User
MailFile Quota Profile document. If the Requester is not allowed to submit this request then it will fail. A
similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then generate an Extended AdminP request to update the users mailfile Quota and Threshold
Levels.
Once processing has completed then any people specified within the Notification list defined in the User
MailFile Quota Profile will be sent an email telling them that the request has succeeded.
7.10.5.3.User Mailfile Quota Profile
The User MailFile Quota profile allows the administrator to define who can request that a target user has
their mailfile set with a Quota and Threshold.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

Quota Bands Define which quota bands the requester can assign to the target users mail
Allowed file. Leaving all deselected means that the requester can choose all bands,

7.10.5.4.User MailFile Quota Definition


Header Text Mandatory Comments
Transaction Yes UMQ
TransactionProfile Yes A User MailFile Quota profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction

7.11. User Move Domain


The User Move Domain transaction allows a requester to move a target user from one Domino domain to
another. This allows simple domain consolidation or split activities.
Note that this transaction ONLY moves the person document between domains, and therefore assumes:
 that all servers in all domains to be manage exist in all domain directories. This can be achieved by
cutting and pasting server documents between directories.
 All servers in all domains use Directory Assistance to make available all other Domain directories to
all servers.
At the end of this operation, the user is still on the same server, with the same mail directory, but has been
moved between domain directories. The users person document has been set with the correct target
domain.
In order to move users between domains and servers in the same operation, see the User Move Location
Transaction.
Details relating to the notification of completion of this transaction are stored in the User Move Domain
Profile.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 69 O F 145

7.11.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Move Domainʼ
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Domain Move Profile from the
list of profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

Target Domain A list of potential target domains is displayed.


If the transaction profile only allows the
movement between two domains, then the
other domain – the domain that the user is
currently not a member of – will be selected.

7.11.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the User
Move Domain Profile document. If the Requester is not allowed to submit this request then it will fail. A
similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then moves the users person document between Domain directories, and resets the user
domain name in the person document to the name of the target Domain.
Once processing has completed then any people specified within the Notification list defined in the User
Move Domain will be sent an email telling them that the request has succeeded.

7.11.3. User Move Domain profile


The User Move Domain profile allows the administrator to define who can request that a user is moved
between domains, and what the target domains should be.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

Allowed Select one or more Domino domains which can be used as a target for this
Target transaction.
Domains

7.12. User Move in Hierarchy


Allows a Requester to move a user in certifier hierarchy in a FirM-registered Domino Directory.
Details relating to the notification of completion of this transaction are stored in the User Move in Hierarchy
Profile.

7.12.1. Walkthrough of transaction


To create new request, select ʻUser Move in Hierarchy.
The requester may be prompted for some or all of the following data items:

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 70 O F 145

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Move in Hierarchy Profile from
the list of profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

New Hierarchy The profile document dictates one or more /Stobart


valid choices for the target hierarchy.

7.12.2. FirM Processing


The Requester of the transaction will be compared against the Requesters and Authorisers in the User Move
in Hierarchy Profile. If the Requester is not allowed to submit this request then it will fail.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request. An AdminP Request is then spawned requesting that the user be available for Move in
Hierarchy
This request is then immediately accepted by the ʻtargetʼ certifier.
The AdminP Process then confirms with the user that they accept this Move in Hierarchy.
If they answer ʻYesʼ, then the user's ID is updated, and their name changed using normal AdminP Processes.
The request will remain in the state ʻPending Sub transactionʼ until the AdminP request has completed. It will
then progress to ʻCompleteʼ.
Should there be any groups defined in the users source and target Certifier profile document, then the user
will be removed from the groups defined in the source Certifier Profile document, and added to the groups
defined in the Target Certifier Profile.

7.12.3. User Move in Hierarchy Profile


The Move in Hierarchy profile is used to specify how a user should be moved in the Notes Name hierarchy
and who is allowed to perform the operation.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

Allowed If one or more entries are selected from this list of profiles, then the
Cerfifiers requester will only have the choice of the selected Certifiers.
Otherwise, the requester will be able to choose from any Certifier
defined within FirM.

User Enable If selected, a User Enable transaction is automatically ran for the users
Profile. new Notes Name. This ensures that if a previous users' notes name
was added to the terminations groups, and this new user name
matched it, then the target user would not be barred from accessing
your Notes environment.

ID Profile. Select an ID profile in order that the ID expiry period can be set.

Optional OU Optional OU The profile can dictate whether a users Optional OU is updated whilst
Handling the move in hierarchy is taking place.

7.12.4. User Move in Hierarchy CSV Defintion

Header Text Mandatory Comments


Transaction Yes UMV
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 71 O F 145

TransactionProfile Yes A User Move in Hierarchy profile defined in FirM


UserName Yes A fully hierarchical name identifying the user for this
transaction
NewHierarchy Yes The new hierarchy that this user is moving to
OptionalOU No Any optional OU that the user should be inserted in
the users hierarchical name.

7.13. User Move Location


User Move Location allows a requester to move a user:
 To a new Location. Each system Location profile defines one or more servers which are responsible
for that location. If the users existing mail server does NOT service the new location, then a User
Move Server transaction is initiated.
 To a new certifier. If the userʼs certifier profile is NOT allowed in the new location, the requester is
prompted for a new certification hierarchy, and a User Move in Hierarchy request is initiated.
 If groups are defined in the source and target location profile documents, then the user is removed
from the groups in his current location, and added to the groups in his new location. (Note that if a
group is defined in both, no action is performed).
 Locations (in v2.1.01 are now linked to system Country Profiles. If the change in location means a
change in country, then the user is removed from the groups defined in his current Country profile,
and added to groups defined in his new Country profile. (If the same group is defined in both Country
profiles, then no action is performed)
Details relating to the notification of completion of this transaction are stored in the User Move Location
Profile.

7.13.1. Walkthrough of transaction


To create new request, select ʻUser Move Locationʼ.

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Move Location Profile from the
list of profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

Current Location The FirM location name associated with the Dublin
users current home server. If this cannot be
calculated then the requester is prompted to
choose from a short list of Location Profiles

New Location If the profile allows more than one target Edinburgh
profile, the requester is prompted to choose
the target users new profile

New Certifier If the new locationʼs allowed certfier list (in /Stobart
the location profile) doesnt include the users
current certifier, then the requester is
prompted (if there are more than one
choices) to choose the best certifier
hierarchy for this user.

7.13.2. FirM Processing


The Requester of the transaction will be compared against the Requesters and Authorizers in the User Move
Location Profile. If the Requester is not allowed to submit this request then it will fail.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 72 O F 145

Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
If the users change in location means a change in server, then a User Move Server transaction is initiated.
If the users change in location means a change in notes name hierarchy, then a User Move in Hierarchy
transaction is initiated.
The user is removed from his current Location (and Country groups, if this change in location means a
change in Country), and added to his new Location and Country groups.

7.13.3. User Move Location Profile


The Move Location profile is used to specify how a user should be moved in terms of Locations and
Hierarchies and who is allowed to perform the operation.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

User Move Server Select a User move Server profile that this transaction will use.
Profile

Allowed Allowed Current Select one or more locations from which you wish to move users from.
Locations Locations Selecting NO profiles means that all system location profiles can be
used.

Allowed Target Select one or more locations to which you wish to move users.
Locations Selecting NO profiles means that all system location profiles can be
used.

7.13.4. User Move Location

Header Text Mandatory Comments


Transaction Yes UML
TransactionProfile Yes A User MailFile Quota profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction
CurrentLocation Yes The current user location
NewLocation Yes The users new Location
NewHierarchy Yes The users new Hierarchy, if required.

7.14. User Move Server


Allows a Requester to request that a user be moved from his home server to a new Domino server in a FirM-
registered Domino Directory.
Details relating to the notification of completion of this transaction are stored in the User Move Server Profile.
Please note that the User Move Server transaction calls the Domino “Move Mail User” transaction, and
therefore shares the same capabilities as this function. In particular, the Domino “Move Mail User”
transaction will not move a user via a “passthrough server” connection.

7.14.1. Walkthrough of transaction


To create a new request, select ʻUser Move Serverʼ.
The requester may be prompted for some or all of the following data items:

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 73 O F 145

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Move Server Profile from the
list of profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

Target Server Target server you wish this user to move to. EdinburghServer1/Acme
You must choose a server object from the
Notes directory, and you cannot choose the
userʼs existing server.

Mail File The name of the users mail file on the new mail/FredBloggs.nsf
server. By default this is the same as the
users mail file on his existing server.

7.14.2. FirM Processing


The Requester of the transaction will be compared against the User Move Server Profile Requesters and
Administrators field. If the Requester is not allowed to submit this request then it will fail.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor will now initiate an AdminP request to move this user from their existing server to a new
server, and optionally rename their mail file database name.
Once processing has completed then any people specified within the Notification list for the relevant User
Enable Profile will be sent an email telling them that the request has succeeded.
The request will remain in the state ʻPending Sub transactionʼ until the AdminP request has completed. It will
then progress to ʻCompleteʼ.

7.14.3. User Move Server Profile

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

7.14.4. User Move Server CSV Definition


Header Text Mandatory Comments
Transaction Yes Should always be “UMS”
TransactionProfile Yes A User Move Server profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction
TargetServer Yes The name of the target server to which you wish to
move this user.
TargetMailDb Yes The users target mail file name on the new server.

An example CSV file for a User Move Server transaction would look like:
Transaction, TransactionProfile, UserName, TargetServer, TargetMailDb
“UMA, “Default UMA Profile”, “Joe Bloggs/MyCo”, “cn=newServer,ou=Acme”,”mail/JoeBloggs.nsf”
This transaction would move user Joe Bloggs to server ʻnewServer/Acmeʼ

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 74 O F 145

7.15. User Password Digest Enable


The User Password Digest Enable transaction allows a requester to enable the Domino “Password Digest”
facility for a user.
Details relating to the notification of completion of this transaction are stored in the User Password Digest
Enable Profile.

7.15.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Password Digest Enableʼ
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Password Digest Enable
Profile from the list of profiles available to
him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

7.15.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the User
Password Digest Enable Profile document. If the Requester is not allowed to submit this request then it will
fail. A similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then creates an AdminP process request to enable password digest usage for this user.
Once processing has completed then any people specified within the Notification list defined in the User
Password Digest Enable Profile will be sent an email telling them that the request has succeeded.

7.15.3. User Passsord Digest Enable Profile


The User Password Digest Enable specifies who is allowed to request that a target user has a password
digest created for them.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

Password Speciy the number of days before the HTTP password is expired, and
Expiration the user forced to change their HTTP password

Grace Period Specify the number of days a user can ignore the ʻchange passwordʼ
prompts before their account is locked out.

7.15.4. User Password Digest Enable CSV Definition

Header Text Mandatory Comments


Transaction Yes UPE
TransactionProfile Yes A User Password Digest Enable profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 75 O F 145

7.16. User Password Digest Disable


The User Password Digest Disable transaction allows a requester to disable the Domino “Password Digest”
facility for a user.
Details relating to the notification of completion of this transaction are stored in the User Password Digest
Disable Profile.

7.16.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Password Digest Disable
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Password Digest Disable
Profile from the list of profiles available to
him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

7.16.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the User
Password Digest Disable Profile document. If the Requester is not allowed to submit this request then it will
fail. A similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then creates an AdminP process request to disable password digest usage for this user.
Once processing has completed then any people specified within the Notification list defined in the User
Password Digest Disable Profile will be sent an email telling them that the request has succeeded.

7.16.3. User Password Digest Disable Profile


The User Password Digest Disable specifies who is allowed to request that a target user has their password
digest disabled.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

7.16.4. User Password Digest Disable CSV Definition

Header Text Mandatory Comments


Transaction Yes UPD
TransactionProfile Yes A User Password Digest Disable profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction

7.17. User Password Digest Reset


The User Password Digest Reset transaction allows a requester to reset the Domino “Password Digest”
facility for a user. This means that the user can then authenticate with the Domino environment, ignoring all
previous password changes and/or expirations.
Details relating to the notification of completion of this transaction are stored in the User Password Digest
Reset Profile.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 76 O F 145

7.17.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Password Digest Resetʼ
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Password Digest Reset Profile
from the list of profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

7.17.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the User
Password Digest Reset Profile document. If the Requester is not allowed to submit this request then it will
fail. A similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then creates an AdminP process request to reset the password digest for this user.
Once processing has completed then any people specified within the Notification list defined in the User
Password Digest Reset Profile will be sent an email telling them that the request has succeeded.

7.17.3. User Password Digest Reset Profile


The User Password Digest Reset specifies who is allowed to request that a target user has their password
digest reset.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

7.17.4. User Password Digest Reset CSV Definition

Header Text Mandatory Comments


Transaction Yes UPR
TransactionProfile Yes A User Password Digest Reset profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction

7.18. User Recertify


This transaction allows a Requester to recertify a user in a FirM-registered Domino Directory.
Details relating to the notification of completion of this transaction are stored in the User Recertify Profile.

7.18.1. Walkthrough of transaction


To create new request, select ʻNew Requestʼ, ʻUser Recertifyʼ.
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Recertify Profile from the list of
profiles available to him

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 77 O F 145

Prompt Explanation Example

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

7.18.2. FirM Processing


The Requester of the transaction will be compared against the Requesters and Authorisers in the User
Recertify Profile. If the Requester is not allowed to submit this request then it will fail.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
An AdminP Request is then spawned requesting that the user be recertified, with the expiry time dictated by
the relevant ID profile selected in the User Recertify Profile.
The user's ID is updated, and their public key updated to show the new expiry date using normal AdminP
Processes.
The request will remain in the state ʻPending Sub transactionʼ until the AdminP request has completed. It will
then progress to ʻCompleteʼ.

7.18.3. User Recertify Profile


The User Recertify Profile specifies how a user is recertified within the Notes environment and who is
allowed to perform the operation.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

ID Profile Select an ID profile in order that the ID expiry period can be set.

7.18.4. User Recertification CSV Definition

Header Text Mandatory Comments


Transaction Yes URE
TransactionProfile Yes A User Recertify profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction
OptionalOU No An Optional OU to recertify this user with.

7.19. User Rename Common Name


This transaction allows a Requester to rename a target userʼs common name in a FirM-registered Domino
Directory.
Details relating to the notification of completion of this transaction are stored in the User Rename Common
Name Profile.

7.19.1. Walkthrough of transaction


Create new request, select ʻUser Rename Common Nameʼ.
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Rename Common Name
Profile from the list of profiles available to
him

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 78 O F 145

Prompt Explanation Example

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

First Name The users current name elements are Fred


retrieved from the person document in the
Middle Intials directory - the requester can then edit these
to new values.
Last Name These name components are then checked Bloggs
against the name validation values in the
global configuration document.
The users new names are then computed
and checked for uniqueness against the
Domino Directories.

7.19.2. FirM Processing


The Requester and Authoriser of the transaction will be compared against the User Rename Common Name
Profile document. If the Requester is not allowed to submit this request then it will fail.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor will now initiate an AdminP Request which will:
 Invite the user to accept their rename request (if the user is running the Notes v5 client. The Notes
v6 client automatically accepts name change requests by default)
 If the user accepts, the user record is then updated via AdminP
 The request will now complete. The AdminP database should be monitored for a successful
completion of the AdminP request.

7.19.3. User Rename Common Name Profile


The User Rename Common Name Profile specifies how a user is renamed within the Notes Name hierarchy
and who is allowed to perform the operation.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

User Enable If selected, a User Enable transaction is automatically ran for the users
Profile new Notes Name. This ensures that if a previous users' notes name
was added to the terminations groups, and this new user name
matched it, then the target user would not be barred from accessing
your Notes environment.

ID Profile Select an ID profile in order that the ID expiry period can be set.

User Create Select a UCR Profile in order that the User Rename Common Name
Profile transaction can work out the users new internet address. The users
“old” internet address will be appended to the users “fullname” field so
that both internet addresses work for this user.

Append old Setting this to yes appends the users current internet address to their
internet address to fullanem field, so that they can still receive incoming eMail using their
fullname old address.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 79 O F 145

7.19.4. User Rename Common Name CSV Definition


Header Field Mandatory Comments
Transaction Yes Should always be “URC”
TransactionProfile Yes A User Rename Common Name profile defined in
FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction
NewFirstName Yes The users new First Name field
NewMiddleInitials Yes The users new Middle Initials field
NewLastName Yes The users new Last Name field
OptionalOU No The users new Optional Organizational Unit

An example CSV file for a User Rename transaction would look like:
Transaction, TransactionProfile, UserName, NewFirstName, NewMiddleInitials, NewLastName,
OptionalOU
“URC, “Default UCE Profile”, “Joe Bloggs/MyCo”, “Joseph”, “”, Bloggs”, “”

7.20. User Resend User ID and Password


This transaction allows a user to re-send (from the ID repository and password repository) the last set of user
IDs and passwords for a particular user defined in an FirM-registered Domino Directory.
Details relating to the notification of completion of this transaction are stored in the User Resend ID and
Password Profile.

7.20.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Resend User ID and Passwordʼ
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Resend User ID and Password
Profile from the list of profiles available to
him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

ID Recipients Depending on the profile configuration, the


requester may be prompted for one or more
Password Recipients ID or Password recipients for this request.

7.20.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the User
Resend ID and Password Profile document. If the Requester is not allowed to submit this request then it will
fail. A similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then find the user ID and Password stored in the User ID repository and Password repository
for this user. If these cannot be found, the request will fail.
Two mail messages (using ʻnotificationʼ profile documents UUP-SendID and UUP-Send Password) are
constructed, the information attached, encrypted and sent.
Once processing has completed then any people specified within the Notification list defined in the User
Resend ID and Password Profile will be sent an email telling them that the request has succeeded.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 80 O F 145

7.20.3. User Resend ID & Password Profile


The User Resend User ID & Password Profile specifies who is allowed to request that a target users last
user ID and password should be mailed from the secure ID and Password repositories.

Tab Sub-Tab Fields Explanation

Details Profile The Name of this profile


Name

Description A textual description of this profile viewable only by


Administrators

Password Selecting a profile means that the transaction will run a User
Digest Password Digest Reset transaction, which will clear any
Reset Password Digests, allowing the user to authenticate using an
Profile old password.

Distribution ID Files ID How should the ID files be distributed


Options Distribution

ID Mail Define how the list of people to be mailed the ID file will be
Recipients defined - either using the profile, or prompt the requester at
run-time.

Default ID A list of default entries who should receive the ID file


Recipients

Passwords Password Define how the list of people to be mailed the Password will
Mail be defined - either using the profile, or prompt the requester
Recipients at run-time.

Default A list of default entries who should receive the Password


Password
Recipients

7.20.4. User Resend User ID and Password CSV Definition

Header Text Mandatory Comments


Transaction Yes UUP
TransactionProfile Yes A User Resend ID and Password profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction
IDRecipients Yes The ID file will be sent to these people
PasswordRecipients Yes The Password will be sent to these people

7.21. User Roaming Enable


The User Roaming Enable feature allows a requester to enable a userʼ Domino v6 “Roaming” feature
Details relating to the notification of completion of this transaction are stored in the User Roaming Enable
Profile

7.21.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Roaming Enableʼ
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Roaming Enable Profile from
the list of profiles available to him
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 81 O F 145

Prompt Explanation Example

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

7.21.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the User
Roaming Enable Profile document. If the Requester is not allowed to submit this request then it will fail. A
similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor will then submit an AdminP request to enable Roaming for this user.
Once processing has completed then any people specified within the Notification list defined in the User
Roaming Enable Profile will be sent an email telling them that the request has succeeded.

7.21.3. User Roaming Enable Profile


The User Roaming Enable specifies who is allowed to request that a target user is set to be a Notes v6
“Roaming” user.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

Store on Mail The users roaming information is stored on the users Home server.
Server

Base Roaming The root directory on the domino server under which all roaming users
Directory directories are created

Roaming Folder Enter some keywords to define how the users own roaming folder will
Format be specified.

Client Cleanup Choose between ʻDo Not Clean Upʼ, ʻClean up Periodicallyʼ, ʻAt Notes
Shutdownʼ, and ʻPrompt Userʼ

Store ID in Set this to yes to create an AdminP request to store the users ID file in
Address Book their personal address book.

Create Bookmarks Set this to yes to create a new BookMarks Database in the users
DB for new roaming directory.
Roaming Users

Create Journal for Set this to yes to create a new Journal Database in the users roaming
new Roaming directory.
Users

Create Personal Set this to yes to create a new Personal Directory Database in the
Directory Db for users roaming directory.
new Roaming
Users

7.21.4. User Roaming Enable Definition

Header Text Mandatory Comments


Transaction Yes URME
TransactionProfile Yes A User Roaming Enable profile defined in FirM
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 82 O F 145

UserName Yes A fully hierarchical name identifying the user for this
transaction

7.22. User Roaming Disable


The User Roaming Disable feature allows a requester to disable a userʼ Domino v6 “Roaming” feature
Details relating to the notification of completion of this transaction are stored in the User Roaming Disable
Profile

7.22.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ, ʻUser Roaming Disableʼ
The requester may be prompted for some or all of the following data items:

Prompt Explanation Example

Profile The user is being prompted to select the


relevant user Roaming Disable Profile from
the list of profiles available to him

User Name The target user against which you wish to Fred Bloggs/Acme
apply this transaction

7.22.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the User
Roaming Disable Profile document. If the Requester is not allowed to submit this request then it will fail. A
similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor will then submit an AdminP request to disable Roaming for this user.
Once processing has completed then any people specified within the Notification list defined in the User
Roaming Enable Profile will be sent an email telling them that the request has succeeded.

7.22.3. User Roaming Disable Profile


The User Roaming Disable specifies who is allowed to request that a target user has their Notes v6
“Roaming” user capability disabled.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A textual description of this profile viewable only by Administrators

7.22.4. User Roaming Disable Definition

Header Text Mandatory Comments


Transaction Yes URMD
TransactionProfile Yes A User Roaming Disable profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this
transaction

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 83 O F 145

8. FirM Group Transactions


8.1. Group Create
The Group Create transaction allows a user to request the creation of a group in a FirM-registered Domino
Directory.
A Group Create transaction is defined in a Group Profile (See the section “Group Profiles” on page 35 for
more information) document and includes such specifications as the name mask, allowable group content,
Internet name, type of group, authorised Requesters and Authorisers.

8.1.1. Walkthrough of transaction


To create a new request, select ʻNew Requestʼ at the top of the FirM Request Processor. Then, under Group
Management, select ʻGroup Createʼ.

Prompt Explanation

Profile The user is being prompted to select the relevant Group Profile from the list of
profiles available to him

Free Text Part of This is the part of the group name that the Requester specifies. Additional
Group Name elements will be added to the group name to enforce naming standards and
consistency as determined by the selected Group Profile.

Domain Select the domain in which this group is to be created. Although FirM supports
the management of groups in different domains with the same name, it is
possible that the administrator has switched on enforcement of ʻglobally unique
group namesʼ within the FirM configuration setup.

Calculated Group The group naming rules will be applied to the group name to ensure that it meets
Name such specified requirements as only containing acceptable characters and that it
meets the minimum or maximum length.
The calculated full group name is displayed, together with the Internet name if
the profile specifies that one is required.

Description Enter a group description

Group Owner/ The Group Owner is the person with ultimate responsibility for the group and is
Sponsor usually also the billing contact. The Group Owner is also by definition a group
manager for this group.

Owner Approval Depending on the group profile, the requester may be prompted to choose
whether every group request has to be approved by the group owner.

Group Managers Enter a list of people who will become Group Managers for this group.
Group managers are able to create requests to rename this group, change the
ownership, management and administration lists, change the group description,
manage the group's membership content and ultimately delete the group.

Group Administrators Enter a list of people who will become Group Administrators for this group.
The Administrators are only able to change the group's membership content.

Initial Members to The administrator may have enabled membership content to be added at the
Add to group time of creation to groups created with this group profile. If this is the case then a
screen will be displayed enabling initial membership content to be added. Add
initial members, if required.

8.1.2. FirM Processing


The Requester of the transaction is compared against the list of people allowed to submit Group Create
requests for a group using the selected profile. See the section “Group Profiles” on page 35 for more
information. The request fails if the Requester is not an authorised FirM Requester.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 84 O F 145

If the Requester is permitted to submit the request but may not authorise the request then details of the
request are sent to all the listed Authorisers in the profile. The Authorisers then follow the doclink in the mail
and either authorise or reject the request.
If the Requester is also present in the authorisation list and the option ʻenforce separate authorisationʼ is not
selected in the relevant group profile, then the request requires no further intervention.
Processing checks that all relevant information is present in the request. If, for any reason, vital information
is missing (although this should not be possible), the request fails with failure details written to the FirM log
and to the request.
The proposed group name is checked for uniqueness in the target domain, and optionally across all
managed domains. If the name is unique then a new group document is created in the Domino Directory
and a shadow entry added to the FirM Group Repository - this ensures that the group is available for
management by FirM. Name uniqueness is tested against other group names, mail-in database names,
user names, resource names, server names, etc..
Once processing has completed, people specified in the Notification list for the relevant group profile are
sent an email notifying them of the successful group creation.
This group can now be managed within FirM.

8.1.3. Configuration settings for Group Create


FirM setup configuration (See the section: “ʻName Validationʼ tab, ʻGroup Name' subtab: “ on page Error:
Reference source not found for more information) allows the following global settings to be applied to
requests for group creation:
 Maximum length of the Requester's free-text part of the group name.
 Allowed and disallowed characters in the free-text element.
 Name uniqueness to be tested on a global basis, or limited to a per-directory basis.
Group profiles (See the section “Group Profiles” on page 35 for more information) obviate the need for FirM
Requesters to be familiar with many of the group settings, e.g. group type, etc.. The following options can be
specified within the group profiles:
 The type of Domino group to be created with this profile, e.g. Multi-Purpose, ACL Only, etc..
 The name mask to be applied to the group name and the group Internet name. For instance, you
can ensure that ʻ_mail_ʼ is prepended to all mail group names. If no Internet name mask is specified
then no Internet name will be created for the group.
 Whether the foreign directory sync flag is set or not.
 The detailed list of permitted membership types. For instance, SMTP addresses can be prohibited
from being added to ACL groups; server-only groups can be created, etc..
 Whether membership for Notes users and resources is restricted to being from the group's domain
only.
 Whether a group's content can be managed without restriction by any Notes user with access to
FirM.
 Who is permitted to request the creation of this type of group and who is able to authorise the
request. A further restriction may also be defined that the Requester and the Authoriser must be
different people.
 Who will be notified when a group is created with this profile and when a group based on this profile
is modified, deleted or managed.
The profile selected when a group is created will be recorded in the groupʼs record in the FirM Group
Repository. This can only be changed by directly editing the repository record, and it governs the groupʼs
membership masks and some security settings.

8.1.4. Group Create CSV Definition

Header Text Mandatory Comments


Transaction Yes GCR

TransactionProfile Yes A Group Profile defined in FirM


GroupName Yes The User Text of the group name
Domain Yes The Domain that this group should be created in
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 85 O F 145

GroupDescription Yes The textual Description of this group


GroupOwner Yes The full hierarchical name of this group owner
GroupManagersTo Yes One or more full hierarchical names of Group Managers
Add (separated by Semi-colon characters)

8.2. Group Modify


The Group Modify transaction allows a FirM Requester to request the modification of a FirM-registered group
in a FirM-registered Domino Directory and to manage the Ownership, Management and Administration
permissions for that group.

8.2.1. Walkthrough of transaction


To create a new request, select ʻGroup Modifyʼ.

Prompt Explanation

Group Name Select the group to be modified from the list. The list will only contain those
groups in which you are the owner or have been given management rights.
This list is managed through the Group Modify function.

Elements to Update Select the group elements you wish to modify or update

New Free Text Part of Clicking on the recalculate button applies the relevant profile's name mask
Group name and displays the new group name. The group's Internet name is also
recalculated. If the new name is the wrong length or contains prohibited
characters, correct the error before proceeding.

New Group Enter the new group description.


Description

New Owner/Sponsor Update or select a new Owner/Sponsor for this group

Owner Approval Depending on the Group Profile, choose whether the Owner Approval cycle
is enabled,.

Managers to Add Add and remove Managers and Administrators as Appropriate

Managers to Remove

Administrators to Add

Administrators to
Remove

8.2.2. FirM Processing


The Requester of the transaction is compared against the Owner and Managers list for this group. The
request will fail if the Requester is not allowed to submit this request.
Checks are now made to ensure that all relevant information is present in the request. If required
information is missing (which should not be possible) the request fails. The reasons for the failure are
detailed in the FirM log and also in the request.
If group rename is specified then the new group name is checked for uniqueness in the directory according
to the rules specified in the FirM setup configuration.
The group document in the Domino Directory is modified with the new name and all subgroup names
adjusted accordingly. The membership of the parent group is updated to reflect the new subgroup names
and the descriptions of the subgroups are modified accordingly.
An AdminP sub request is created which requests ʻgroup rename in address bookʼ. The status of this
AdminP request is monitored for completion.
If group description change has been requested, the description of the group in the group document in the
Domino Directory is updated with the new description.

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 86 O F 145

If a request to update the owner or managers list of the group has been requested, FirM updates the group's
entry in the FirM Group Repository.
If a request to update the administrators list of the group has been requested then FirM updates the group's
entry in the FirM Group Repository.
Once processing is complete, any people specified in the Notification list for the relevant group profile are
sent an email notifying them of the modifications to the group.
If there are any incomplete AdminP requests open, the request is marked with a status of ʻPending Sub-
transactionʼ
Once any sub-transactions have completed the request is marked with the status of ʻCompleteʼ.

8.2.3. Configuration for Group Manage Members


FirM setup configuration allows the following global settings to be applied to requests for group modification:
 Maximum length of the Requester's free-text part of the group name.
 Allowed and disallowed characters in the free-text element.
 Whether name uniqueness is on a global basis or limited to a per-directory basis.
FirM searches for the group profile that governs the behaviour of this group. The following information in this
profile is relevant to the ʻgroup manage membersʼ request:
 The name mask to be applied to the group name and the group Internet name. For example,
ʻ_mail_ʼ is to be prepended to all mail group names. If no Internet name mask is specified then no
Internet name will be created for the group.
 Who will be notified when a group with this profile is modified.

8.2.4. Group Modify CSV Definition

Header Text Mandatory Comments


Transaction Yes GMO

GroupName Yes The group name as shown in the directory


GroupDescription No A new Group Description
GroupOwnersToAdd No A new fully hierarchical name for a group owner to add
GroupOwnersTo No A new fully hierarchical name for a group owner to remove
Remove
GroupAdministrators No One or more fully hierarchical names for group Administrators to
ToAdd add (separated by semi-colon characters)
GroupAdministrators No One or more fully hierarchical names for group Administrators to
To Remove remove (separated by semi-colon characters)
Note that a valid Group Modify must have at least one of the non-mandatory fields defined to be valid and
effect any changes

8.3. Group Manage Members


This transaction allows user to request the management of the membership list of a FirM-registered group in
a FirM-registered Domino Directory.
The Group Profile documents define valid content and the notification recipients for this transaction.

8.3.1. Walkthrough of transaction


To create a new request, select ʻGroup Manage Membersʼ

Prompt Explanation

Group Name Select the group to be modified from the list. The list will only contain those
groups in which you are the owner or have been given management rights.
This list is managed through the Group Modify function.

Members to Add Add people to this list whom you wish to add to the group

FirM Administration Manual v3.0 © 2009 HADSL


9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 87 O F 145

Prompt Explanation

Members to Remove Add people to this list whom you wish to remove from the group

8.3.2. FirM Processing


The Requester of the transaction is compared against the Owner, Managers and Administrators list for this
group. The request fails if the Requester is not allowed to submit this request.
Checks are now made to ensure that all relevant information is present in the request. If required
information is missing (which should not be possible) the request fails. The reasons for the failure are
detailed in the FirM log and also in the request.
Each person on the delete list is removed from the group and any of its spawned subgroups.
Each name on the add list is evaluated to determine the type of entity it represents. It is compared against
the list of allowable members as determined by the profile governing the group. If the name satisfies all
criteria it is added to the list. If the name does not pass any of the criteria an error is generated, the name is
not added to the list and processing passes to the next name on the add list.
If a group exceeds its size limit, as determined by the FirM setup Configuration, subgroups are automatically
created according to the following: a new subgroup is created and the contents of the parent group member
list are copied into this subgroup. A new subgroup is created, and the member is added to that group. The
parent group's membership is replaced with a list of all its subgroups. New subgroups will be spawned
whenever there is no room for the new member in any subgroup.
Once processing is complete, any people specified in the Notification list for the relevant group profile are
sent an email notifying them that the group has been created.
The request is marked with the status of ʻCompleteʼ.

8.3.3. Configuration for Group Manage Members


The following global settings as defined in FirM setup configuration are applied to requests for group
management:
 The group is split into subgroups either when it reaches the Domino 15Kb size limit or when the
number of entries specified is exceeded.
 The separator character used to identify subgroups. For example, when the separator character is
ʻ_ʼ, a group named Mail Group will spawn subgroups named MailGroup_01, MailGroup_02, etc. By
default this character is ʻ_ʼ.
FirM searches for the group profile that governs the behaviour of this group. The following information in the
profile is relevant to the ʻgroup manage membersʼ request:
 Whether all members must be from the same Domain as the group.
 The types of members that can be added to this group, e.g. whether to allow or disallow SMTP
addresses, Server Names, Mail Groups etc..
 Who will be notified when membership changes to this group are made.

8.3.4. Group Manage Members CSV Definition

Header Text Mandatory Comments


Transaction Yes GMM
GroupName Yes The GroupName as it appears in the Domino Directory
Domain Yes The Notes Domain in which this group belongs
MembersToAdd No Full Hierarchical names of users to add to this group, separated
by semi-colon characters
MembersToRemove No Full Hierarchical names of users to remove to this group,
separated by semi-colon characters
Note that a valid Group Manage Members transaction must have at least one of the non-mandatory fields
defined to be valid and effect any changes

8.4. Group Delete


ʻGroup deleteʼ allows a user to request the deletion of a FirM-registered group in a FirM-registered Domino
Directory.
FirM Administration Manual v3.0 © 2009 HADSL
9 F I R M D O M I N O U S E R T R A N S A C T I O N S E X P L A I N E D PA G E 88 O F 145

Information relating to the notification of completion of this transaction is stored in the Group Profile
documents.

8.4.1. Walkthrough of transaction


To create a new request, select ʻGroup Deleteʼ.

Prompt Explanation

Group Name Select the group to be deleted from the list. The list will only contain those
groups in which you are the owner or have been given management rights.
This list is managed through the Group Modify function.

8.4.2. FirM Processing


The name of the Requester of the transaction is checked to see that either it is the Owner of the group or is
in the list of Managers for this group. The request fails if the Requester is not allowed to submit this request.
Checks are now made to ensure that all relevant information is present in the request. If required
information is missing (which should not be possible) the request fails. The reasons for the failure are
detailed in the FirM log and also in the request.
A copy of this group and all FirM subgroups contained in the group are added to the FirM ʻDeleted Groups
and Usersʼ repository.
The status of the entry for this group in the FirM Group Repository is changed to ʻDeletedʼ and the name of
the person deleting this group is added to the record together with the date and time at which the group was
deleted.
The group is now deleted from the specified domainʼs Domino Directory and a sub-request is created to
create and track an AdminP ʻDelete group in address bookʼ transaction.
Once processing is complete, any people specified in the Notification list for the relevant group profile are
sent an email notifying them that the group has been deleted.
The request remains in the state ʻPending Sub transactionʼ until the AdminP request completes. It then
changes to ʻCompleteʼ.

8.4.3. Group Delete CSV Definition


Header Text Mandatory Comments
Transaction Yes GDR
GroupName Yes The Group name as it appears in the directory
Domain Yes The Notes Domain in which this group belongs

FirM Administration Manual v3.0 © 2009 HADSL


1 2 F I R M A P P L I C AT I O N T R A N S A C T I O N S E X P L A I N E D PA G E 89 O F 145

9. FirM Application Transactions


FirM allows management of Lotus Domino applications. This facility allows the FirM Administrator to delegate
the right to create new applications in the Domino environment to non-technical, non-authorised personnel.
When FirM creates an application on your behalf, it creates a mail-in database document in the directory,
and stores all relevant information in that document. So all applications are by default mail-in applications.
This has the side-effect of preventing the storage of application information in a separate database, and thus
reducing management effort.
When FirM creates a new application for a requester:
 the requester chooses from a pre-defined list of templates
 The requester assigns an Owner (someone who can manage the application and delete it if
required) as well as zero or more administrators (people allowed to manage the application but not
allowed to delete it.
 The requester chooses a Domino server based on a pre-defined list
FirM then:
 Creates the new mail-in database record, and populates it
 Creates an AdminP request to create the new application with the new file name on the correct
server
 It issues AdminP requests to create additional replicas of this database if required
 It creates one or more Groups associated with this application, and populates the database ACL with
these groups. The owners and administrators of the application are set to be owners and
administrators of the groups, and can therefore manage the application via the groups.

9.1. Application Create


The Application Create request allows a user to request the creation of an Application database record, its
associated database and any replicas on cluster-mates of the database server.
Details relating to the notification of completion of this transaction are stored in the Application Create profile
documents.

9.1.1. Walkthrough of transaction


To create a new request, select ʻApplication Createʼ.

Prompt Explanation

Profile If the requester has the choice of more than one Application Create transaction,
a list of Application Create profiles

Domain The domain in which the application should be created.

Database Title The Title of the new Application

Server The Domino server on which this application is to be depoyed.

Template The name of the template on which the application should be based.

Owners Specify the Application Owners.

Administrators Specify zero or more designed Administrators for this application

9.1.2. FirM Processing


The name of the Requester of the transaction is checked to ensure that it is contained in the list of allowed
Requesters in the Application Create profile. The request fails if the Requester is not allowed to submit this
request.
Checks are now made to ensure that all relevant information is present in the request. If required
information is missing (which should not be possible) the request fails. The reasons for the failure are
detailed in the FirM log and also in the request.
FirM Administration Manual v3.0 © 2009 HADSL
1 2 F I R M A P P L I C AT I O N T R A N S A C T I O N S E X P L A I N E D PA G E 90 O F 145

A check is made on the name of the Application database in the target domain. If an Application database
already exists with that name the request fails.
An Application database record is created in the Domino directory and is populated with information from the
request. The ownerʼs field is populated using the list of owners supplied by the Requester and the list of
default owners defined in the ʻApplication Createʼ profile. Similar action is taken for the administratorʼs field.
An AdminP request is submitted to create the mail-in database on the Domino server with the supplied
template name.
An Extended AdminP request is submitted to update the database Access Control List with any default
database managers defined in the ʻApplication createʼ profile.
If the ʻApplication createʼ profile record requires the creation of a cluster replica of the mail-in database, and
the target server is in a cluster, then an Extended AdminP request is created that will create an AdminP
request on the target server to create a cluster replica of the mail-in database.
Once processing is complete, any people specified in the Notification list for the relevant ʻmail-in database
createʼ profile are sent an email notifying them that the mail-in database record has been created.
The request remains in the state ʻPending Sub transactionʼ until the Extended AdminP request(s) and the
AdminP request are all complete. It then changes to ʻCompleteʼ.

9.1.3. Application Create Profile

Tab Field Explanation

Details Profile Name The Name of this profile

Mail Address The mail-in database name of the application that will be created.

Internet Address Should the database also have an internet address associated
with it

Database Path The database file name

Cluster Db Should this applcation be replicated to cluster servers

Cluster Db Path The cluster database file name

Servers Possible Servers Define one or more servers on the “Servers” tab that will be given
as a choice to the requester. If only one is given, then the
application will be deployed on that server. If no choices are given,
the requester can choose any server in the directory.

Templates Allowable Define one or more Template databases that the user can use to
Templates create the target application. Note that the template database must
exist on the target server for AdminP to successfully create the
database.

Owners Default Owners Enter a list of mandatory owners for all applications created using
this profile. These people/groups will be added as “Managers” to
this database ACL and can perform any operation on those
applications.

Administrators Default Enter a list of default Administrators for this Application – personnel
Administrators who can manage this application, but may not delete it.

ACL Managers Default Managers Enter a default list of one or more entities to be added to the
in ACL Application as Default managers.

9.2. Application Modify


The Mail-In Database Modify profile allows a user to request modification of a mail-in database record and its
associated database and any replicas on cluster-mates of the database server.

FirM Administration Manual v3.0 © 2009 HADSL


1 2 F I R M A P P L I C AT I O N T R A N S A C T I O N S E X P L A I N E D PA G E 91 O F 145

Details relating to the notification of completion of this transaction are stored in the Mail-In Database
Modification profile documents.

9.2.1. Walkthrough of transaction


To create a new request, select ʻMail-In Database Modifyʼ.

Prompt Explanation

Profile If the requester has the choice of more than one Application Modify Profiles, a list of
Application Create profiles

Application Select the application to modify

Address The Domino mail address of this application

Internet Address The Internet address of this application

Administrators The list of Administrators for this applcation

Owners The list of Application Owners for this applcation

9.2.2. FirM Processing


The name of the Requester is compared against the owner and administrator fields in the Application
database record. If the Requester is not listed directly (by Notes full name) or indirectly (by being the
member of a group or subgroup), the request fails.
Checks are now made to ensure that all relevant information is present in the request. If required
information is missing (which should not be possible) the request fails. The reasons for the failure are
detailed in the FirM log and also in the request.
The Application record is updated with the information in the request.
Once processing is complete, any people specified in the Notification list for the relevant ʻApplication modifyʼ
profile are sent an email notifying them that the mail-in database record has been modified.

9.2.3. Application Modify Profile


The application Modify profile allows the FirM administrator to delegate the management of applications to
non-technical users.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A description for this profile

9.3. Application Delete


The Application Delete request allows a user to request the deletion of an Application record, its associated
database and any replicas on cluster-mates of the database server.
Details relating to the notification of completion of this transaction are stored in the Application Delete Profile
documents.

9.3.1. Walkthrough of transaction


To create a new request, select ʻApplication Deleteʼ.

Prompt Explanation

Profile If the requester has the choice of more than one Application Delete Profiles, a list of
Application Delete profiles

Application Select the application to delete

FirM Administration Manual v3.0 © 2009 HADSL


1 2 F I R M A P P L I C AT I O N T R A N S A C T I O N S E X P L A I N E D PA G E 92 O F 145

9.3.2. FirM Processing


The name of the Requester is compared against the owner and administrator fields in the mail-in database
record. If the Requester is not listed directly (by Notes full name) or indirectly (by being the member of a
group or subgroup), the request fails.
Checks are now made to ensure that all relevant information is present in the request. If required
information is missing (which should not be possible) the request fails. The reasons for the failure are
detailed in the FirM log and also in the request.
A copy of this Application record is added to the ʻFirM Deleted Groups and Usersʼ repository.
The mail-in database record in the domainʼs Domino Directory is deleted and a sub-request is created to
create and track an AdminP ʻDelete in Names Fieldʼ request.
An AdminP request is created which:
 Runs on the server specified in the mail-in database record.
 Creates deletion AdminP requests for all cluster mates of the server for any replicas of the database.
 Deletes the database specified in the Application record.
A further AdminP request is created which:
 Deletes all references to the mail-in database from any author name or reader name (names fields)
in the environment.
Once processing is complete, any people specified in the Notification list for the relevant ʻmail-in database
modifyʼ profile are sent an email notifying them that the mail-in database record has been deleted.
The request remains in the state ʻPending Sub transactionʼ until the Extended AdminP request has
completed. It then changes to ʻCompleteʼ.

9.3.3. Application Delete Profile


The application Delete profile allows the FirM administrator to delegate the management of applications to
non-technical users.

Tab Field Explanation

Details Profile Name The Name of this profile

Description A description for this profile

FirM Administration Manual v3.0 © 2009 HADSL


1 3 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 93 O F 145

10. Active Directory Overview


The FirM Active Directory component (or “FirM AD”) allows you to extend FirM and facilitate Active Directory
user and group management.

10.1. Architecture
FirM is a set of native Lotus Domino applications that run on an IBM Lotus Domino Server. FirM manages
Lotus Domino identities and resources
FirM manages Active Directory objects and shared directories via a Windows Service component called the
FirM AD Service. This service is installed on target Windows servers and it makes web-service calls back to
the Primary FirM Processing Server to pick up outstanding work. This architecture allows FirM to manage
multiple Active Directory Domains or Forests.
This means that four pre-requisites exist:
 The Primary FirM Processing Server must be running Lotus Domino v7.x or above. This is to give
the FirM request processor database the ability to host a LotusScript Web Service.
 The FirM AD Service must be installed on all Windows servers that will be used to create (or
manage) home directories or user profile directories.
 You must nominate one or more Windows servers in each Active Directory domain or forest to
perform changes within Active Directory. The FirM AD Service must be installed on these servers.
These servers need NOT be domain controllers, but it should be noted that since the FirM AD
service will create, amend and delete AD Objects, the server that these operations are performed on
should be as close to the replication hub in your Active Directory environment to reduce the number
of AD replication events required for the changes to replicate across the environment. We advise
that the FirM AD Updates are at least performed within the same AD 'site' as your current AD 'root'
server.
 All windows servers which run the FirM AD service must be able to make web-service calls back to
the FirM processing server across your intranet.
In order to manage the configuration of the Active Directory components within FirM, we make use of a DLL
file which can 'browse' the Active Directory namespace. This component is required by FirM administrators. It
may also be required by FirM Requestors if you make FirM Active Directory requests available to them and
the profiles controlling these requests allow them to choose between multiple Active Directory containers.
This file is installed by FirM when required, or you may elect to incorporate it into your Lotus Notes client
distribution.

FirM Administration Manual v3.0 © 2009 HADSL


1 5 I N S TA L L I N G & C O N F I G U R I N G A C T I V E
D I R E C T O R Y PA G E 94 O F 145

11. Installing & Configuring Active Directory


This section deals with installing and configuring the two FirM AD components within your FirM environment.

11.1. Activating and Configuring Active Directory


Open the FirM Request Processing database, click on “Tools” and then choose the Configuration pane.
Click on Edit Config, and then
choose the “AD” tab.
Set “Active Directory Enabled” to
“Yes”.
Now click on the 'Add Entries to
add Active Directory domains
and primary processing servers
for these domains.
In this case, I have entered
Active Directory domain
'HADSL.local', with primary
processsing server
'DUNVEGAN', and domain
'redloh.local' with processing
server GANDALF.
As you can see we expect the
server COMMON name, not the servers full AD object name.
The next tab allows you to set
the Name Validation options
for each of the Active Directory
name components – First
Name, Middle Initials, and last
name. The button 'Set same
as Domino validation' allows
you to copy the Domino name
validation options to the AD
ones, if both are the same.

The 'Synchronisation' tab


allows you to define whether
Active Directory should be
synchronised with Lotus
Domino. In this case, we have
enabled synchronisation by
selecting 'Yes',

FirM Administration Manual v3.0 © 2009 HADSL


1 5 I N S TA L L I N G & C O N F I G U R I N G A C T I V E
D I R E C T O R Y PA G E 95 O F 145

The “Person Document Field to


store AD GUID field” defaults to
“NetUserName”, and is the field
on the domino directory person
document upon which we will
place the AD GUID (Global
Unique ID) number. This then
connects the Domino person
with an entity in Active Directory.
It is highly recommended that
this value is not changed
frequently, as previously created
person documents will have to
be updated manually.
This is the same field name as Lotus Active Directory Synchronisation uses. If this field is used, then the field
is visible on the users Person document, on the “Administration” tab, without modifying the standard
Directory template:
We normally advise that the AD directory is not synchronised frequently with Domino – once or twice per day
is usually sufficient. In this case, we've chosen every 24 hours.
Start Time in 24-hour clock
format tells the AD service
when we wish this
synchronisation to start.
Note that there are more
configuration steps required to
enable synchronisation –
please refer to the next chapter
for more information.
The last tab – Admin Settings –
allows you to define how often
the FirM AD Service should cycle on the Windows servers. By default this is set to 300 seconds – every five
minutes. In an environment where there is considerable Active Directory management activity, you may
consider reducing this to 120 seconds, but bear in mind that this may increase the load on the server (both
the FirM Domino server and the Windows server).
Lastly, the users Notes folder in their network home directory is requested. This allows the User reset ID and
password process to drop their ID file into the correct lotus notes direcory. The assumption is, of course, that
all users will have the same directory name.

11.2. Installing the FirM AD Component

11.2.1. Prerequisites
The FirM AD Component and its accompanying setup program both are reliant the “Microsoft .NET
Framework Version 2.0 Redistributable Package (x86)”.
MS .Net v2.0 framework loaded onto the target computer. This is usually downloaded automatically as part
of the automatic update process – but can be manually downloaded and installed from this web site:
http://www.microsoft.com/downloads/details.aspx?FamilyID=0856eacb-4362-4b0d-8edd-
aab15c5e04f5&DisplayLang=en
In particular, if you receive this error message:

We advise you to download and install the .Net v2 framework.

FirM Administration Manual v3.0 © 2009 HADSL


1 5 I N S TA L L I N G & C O N F I G U R I N G A C T I V E
D I R E C T O R Y PA G E 96 O F 145

11.2.2. FirM AD Service Installation


The FirM AD Windows service has the following pre-requisites:
 It connects back to the FirM processing server, and collects work from the server using a web
service consumer. This means that the FirM processing server needs to run on a Domino v7.x server
or above, in order to provide web services. Note that the Windows service component itself does not
use nor require Microsoft IIS server on the target AD server.
The Domino web site should NOT be set up to use 'session' based authentication. Please refer to
the following section on Domino Authentication types for a detailed explanation and work-around.
 The FirM AD Windows Service should be installed on ALL win2k3 file servers upon which you
anticipate creating user home directories and/or user profile directories. It should also be installed on
the nominated AD server which will process user and group AD operations, as well as any backup
server you nominate.
 The windows service requires the Microsoft .Net framework v2 or greater
 It uses a Domino HTTP username and password in order to log into the Domino web service to
collect work. This username and password should have the same level of access to FirM as a
normal requester.
 It then uses a windows-based configuration tool to update the Windows Registry on that server,
and stores the target URL for the web service, as well as the username and the password in
encrypted form. It is possible to copy the registry settings from one server and apply them to any
other servers, as well as installing the Windows Service using a 'silent' installation.
 You should be logged into the target server using an ID capable of installing service applications.
In order to install the FirM AD Windows service on the AD server:
 Open Internet Explorer on the target AD server, and navigate to the following URL:
 http://<server>/firm/firmrequestprocessor.nsf/InstalFirmAD.html
Where you should replace <Server> with the name of your FirM Processing server
You may have to change the directory name if you have installed FirM in another location.
 You will be prompted for a username and password. Please enter the username and password for a
Domino user who can access the FirM Request processor.
 You will then be presented with an HTML based screen with instructions, and the ability to download
and install the Windows AD service.
Alternatively, you can navigate (using a notes client) to the Administration 'Tools' section. Choose the
'System Views' tab, then the 'Active Directory' Tab, and finally the 'AD Service Installer' Tab. This will show a
view with a document containing the installer for the FirM AD Windows service. This can be detached and
coped to target servers.

11.2.3. FirM AD Service Installer


Once the installer is started, the following screens are shown:
This startup screen confirms the version number of the install
package. The latest version of the install package is always
included in the latest release of FirM.

Click Next to continue.

FirM Administration Manual v3.0 © 2009 HADSL


1 5 I N S TA L L I N G & C O N F I G U R I N G A C T I V E
D I R E C T O R Y PA G E 97 O F 145

This screen outlines the normal FirM EULA. Click 'I accept the
terms of the License Agreement' and then click on Next.

The installer now requires your confirmation that you should


proceed. Click Next to continue.

The service is now installed and configured. If the FirM registry


elements do not exist, then the FirM setup application is
displayed. See the next section for more information.
If you have not installed the .net v2 framework, then an error
will be displayed at this stage.

Once installation is complete, this screen is displayed. Click on


Finish to exit the install package.
At this point in time, the FirM AD Service application is installed
and running as a service. By default, it installs the service to
run under Local Service Authority.

FirM Administration Manual v3.0 © 2009 HADSL


1 5 I N S TA L L I N G & C O N F I G U R I N G A C T I V E
D I R E C T O R Y PA G E 98 O F 145

11.2.4. FirM Setup Appliction


The FirM setup application is a
small .net framework v2 based
application which allows you to create
or update registry entries used by the
FirM AD Service.
During installation of the FirM AD
service, if the required registry
elements do not exist, the setup
application is automatically shown.
Otherwise, you can run the
configuration application manually by
clicking on Start, Applications,
HADSL, and then FirM AD Setup.

When the setup application


launches, any existing registry
entries are read into the
application and displayed.
You should then complete this
form, and click 'Apply'.
In order to construct the web
service URL (the last item on
the form), you should enter the
domino server name, and the
database name and location
on your FirM Processing Lotus
Domino server.
Please note that the FirM AD
service uses web service calls
to the Lotus Domino server in order to retrieve configuration, retrieve outstanding work for that server, and
update request information within the FirM processing database. In order to successfully make the web
service call, it must call the Lotus Domino server. And as the request information is both confidential and
secure, it must use a username and password (which you supply on this form).
It is important to realise that this web service call cannot use any form of 'single sign on' cookie in order to
authenticate itself. If you were to open the URL for this web service (by clicking the 'Test URL') button, you
should be prompted for a username and password using a dialog box. If you see an HTML form with a
username and password, then this indicates that the Domino server has been set up to use session
authentication. See the next section on how to resolve this.
You should fill in the details on the setup application, and click on 'Apply'. This will write the information to the
machines registry. If you open the 'regedt32' application on this machine and navigate to the
HKEY_LOCAL_MACHINE tree, and select 'Software\hadsl\FirMAD', you should see entries corresponding
to the information you keyed into the setup program.
Note that the password is encrypted and stored in binary format in the registry. This information is not
specific to this server. If you wish to use the same URL, Username and Password for all servers on which
you wish to install the FirM AD Service, you can copy these registry elements from this server and apply
them to other servers. This makes installation to a large number of servers simpler.
The setup application can detect the status of the service, and start or stop the service if required. If you
change the values for the server URL or the username/password, then the service should be stopped and
restarted, as it only reads these values on startup.

FirM Administration Manual v3.0 © 2009 HADSL


1 5 I N S TA L L I N G & C O N F I G U R I N G A C T I V E
D I R E C T O R Y PA G E 99 O F 145

11.2.5. Troubleshooting the FirM AD Service


The FirM AD Service writes application logging
and error event information to the machines
Event log. You can examine the event log and
establish whether the service is running properly.
The event information is writen the the
Application event log.
In this example, you can clearly see that the
application (named 'FirM AD Effector') is having
some issues.

The most common error we encounter is that of session-based


authentication, instead of username+password basic authentication.
Should this be the case, then errors such as “response content type of
'text/html'” will be generated. See the next section to help resolve this
issue.

If the URL is incorrect – for instance, the server name does not resolve
in DNS, or the domino database name is misspelt – then “HTTP Status
404” errors will be generated.

When the FirM AD service correctly calls the FirM Processing server
and receives a correct response, it will generate a short summary of
relevant configuration information. This indicates that the service is
working correctly.
A common issue we have encountered is that the Event Log fills up
(especially if verbose level debugging is enabled). In order to prevent
the error 'Event Log Full', you can right click on the 'Application' folder
on the left pane and allow the Event Log to overwrite older events.
Finally, if the FirM AD Service does not appear to be able to
communicate with the Primary FirM Processing Server then check any
anti-virus software installed, ensuring that it is not quarantining the
service and preventing any network interaction.

11.2.6. Validating the FirM AD Service is correctly configured


In order to confirm that the FirM AD Service, we need to confirm that FirM recognises that the server which is
calling in has been correctly identified. In this case, we wish to confirm that the server which we have chosen
to perform Acive Directory updates has been correctly identified as the server which will perform these
updates.
Open the FirM Log, and select the view 'Miscelaneous Logs' and then 'By Type'. This then shows a list of all
log documents by the request type. Click on View, Collapse All, in order to reduce the view to a list of
headings. Navigate down the view to the entry which starts 'Web Service (Configuration) for: <servername>'
where <Servername> is the common name of the server we are checking. Open the twistie, and select the
last day, and then the last entry, and open the most recent log entry of this type:
Miscellaneous Events:

FirM Administration Manual v3.0 © 2009 HADSL


1 5 I N S TA L L I N G & C O N F I G U R I N G A C T I V E
D I R E C T O R Y PA G E 100 O F 145

...

26/09/2008 10:43:47 Web service starting up

26/09/2008 10:43:47 WebService:getRequestsForDomains: Responding to server: DUNVEGAN with


domain: hadsl.local

26/09/2008 10:43:47 WebService:getRequestsForDomains: The calling server: DUNVEGAN is


defined as the processing server (DUNVEGAN) for this domain: hadsl.local

26/09/2008 10:43:47 WebService:getRequestsForDomains: No outstanding requests for this


domain: hadsl.local

26/09/2008 10:43:47 WebService:getRequestsForDomains: No outstanding requests for this


server: DUNVEGAN

26/09/2008 10:43:47 WebService:getRequestsForDomains: No outstanding requests for all


servers

26/09/2008 10:43:47 WebService:getRequestsForDomains: Finished responding to server:


DUNVEGAN with domain: hadsl.local
The Log line 'The calling server' (which is in bold in the example above) shows that FirM has correctly
identified the calling server (in this case the server 'DUNVEGAN') and domain ('hadsl.local') and has
confirmed that this server is the main Processing Server (the server which will perform Active Direcory work
in this domain).
If your designated server does NOT show this log entry, then please review the Configuration document,
Active Directory tab, and confirm that you have correctly entered the server name (as reported in the log
document) and the Active Direcory domain (as reported in the log document).

11.2.7. FirM AD Service Authentication


In order to perform work within Active Directory, the service itself must
be authenticated using some name, and must be allowed to perform
changes within AD using that name.
By default, the service is installed to use the Local System Account.
This means that the service itself authenticates using the name of the
Active Directory server on which it is running. This does rely on the
server nominated to be the Active Directory manager to be in a secure
location. It should be impossible for an unauthorised person to gain
access to this machine and install any malicious software.
Some sites may choose not to run the service under Local System
account authentication. In this case, you may choose to select 'This
Account' and enter a different username and password.
In either case, it is necessary to ensure that the nominated account –
whether its the default Local System account (and therefore the
computer object within Active Directory), or another selected account –
is able to manage Active Directory objects in your Active Directory forest.
This is best done by selecting the container(s) in which your users and groups reside, and delegating control
to the computer account or nominated accounts you wish to use.
Remember that a windows servers' authentication is worked out when the server logs into the domain – so
you will have to reboot the server for it to pick up this new delegated authorisation.
One last point to consider. If the service is installed on a MEMBER server within the Active Directory domain,
the localService account that the service runs under does NOT have access – by default – to manage users.
This permission is granted by default to domain controllers within Active Directory.
As you can see there are various levels of convenience versus security. Installing on a domain controller and
running as local service requires no additional delegation. Installing on a member service and running as the
default local service requires that the computer is delegated the ability to manage users. Lastly, you could
override the default local service ID and use a nominated username and password, which will require
delegation.

FirM Administration Manual v3.0 © 2009 HADSL


1 5 I N S TA L L I N G & C O N F I G U R I N G A C T I V E
D I R E C T O R Y PA G E 101 O F 145

11.2.8. Domino Web Service Authentication


The Windows service running on each of the Active Directory servers uses non-session based authentication
to securely log into the Domino web service. This means that the URL they use to open the web service
cannot use a 'Login Page' to authenticate – it has to use 'Default' Domino authentication, where the user is
prompted with a dialog box for their username and password.
If you require this server to also support session based users, you may use the Domino 7.x feature 'Internet
Sites' to allow users to log in using session-based authentication, whilst also allowing Web Service agents to
log in without using session-based authentication. To achieve this:
 Enable 'Use Internet Site Documents' on the first page of the server setup document.
 Create a new Internet Site document for default usage, and enable session-based authentication
 Create a new Internet Site document using a different host name, and disable session-based
authentication.
 Enable in DNS the new hostname, pointing at the same IP address as your Domino server.
 Remember to restart your HTTP task to enable these changes.
Please examine the Lotus Administration manual on these features if you are unsure of this process.

11.3. Heartbeat Task


In normal
operation, the
FirM AD service
will update a
document in the
FirM Extended
AdminP
database on the
FirM primary
server. This
document
confirms that this
component is “alive” and also reports back on disk space characteristics for this file server. This allows us to
correctly calculate the most relevant win2k3 file server based on disk space usage to create new users on.
To view this heartbeat information, open the FirM Extended AdminP database database, click on “System
Profiles”, and select “Server Heartbeat”
Lotus Domino Servers hosting the Extended AdminP database are shown with their full Lotus Notes
abbreviated names, and win2k3 file servers are shown using their short “common” names.
The highlighted entry is a win2k3 file server, and the “status” column shows that the service is running, as
well as the last time the service updated this heartbeat record.
This is a useful test of the functionality of the service, without having to create any FirM transactions.

11.4. Share Names


When the FirM AD service runs, it is passed (from the FirM processor, which calculates the share information
based on the FirM AD User Create profile) a directory name of the form:
\\<servername>\<sharename>\<userDirectory>
Where <servername> is the name of the win2k3 file server, the “shareName” is the name of the windows file
share hosting all the users directories, and the <userDirectory> is the name of the directory we shall create
for the user.
For instance
“\\aphrodite\users\Mike Rodin”
indicates the directory “Mike Rodin” in the share “users” on server “Aphrodite”.This means that the share
“users” must be created on this file server and point to a valid directory on the server, for the FirM AD to be
able to establish what that directory is and then create the subdirectory “Mike Rodin”.

FirM Administration Manual v3.0 © 2009 HADSL


1 5 I N S TA L L I N G & C O N F I G U R I N G A C T I V E
D I R E C T O R Y PA G E 102 O F 145

11.5. The FirMAD LSX DLL


Open the FirM Request Processor database,
and select “Tools”. Choose the last tab,
ʻSystem Viewsʼ:
This shows the FirmAD.dll file held in a Notes
Document.
The LSX DLL is used by administration
clients and requester clients which need to
browse the Active Directory tree, or select
Active Directory objects.
The LSX is installed automatically when the
user uses a relevant FirM request for the first
time – it is copied to the users data directory.
Alternatively, the network administrator can detach this DLL file and arrange to have it copied to each users
Lotus Notes Program directory. This may be relevant where users are not allowed to copy DLL files to their
machines.

FirM Administration Manual v3.0 © 2009 HADSL


1 6 F I R M A D S Y N C H R O N I S AT I O N PA G E 103 O F 145

12. FirM AD Synchronisation


FirM can help synchronise Active Directory with Lotus Domino directories. It does this by pulling in active
directory object listings – users and groups from particular containers – into a Domino directory. This is then
compared with one or more Lotus Domino directories, and synchronisation actions are recommended.
These can then be approved if correct, and relevant FirM transactions are then generated.
This two-stage approach prevents the synchronisation tool from performing actions which are not well
understood or desired.

12.1. Architecture and Workflow


The FirM suite contains an Active Directory Synchronisation database (ADSync), which forms the basis for
all synchronisation activities.
The FirM AD Service (described in previous chapters) pushes in required AD Objects to this database, and
these objects are compared to Domino objects.
Specifically, the Windows server
running the FirM AD Service, and
configured as the primary processing
server for that AD domain (The
server listed on the AD tab of the
configuration document) checks to
see if it should 'push' the AD
directory to the FirM server every
time it 'calls in' looking for work.
The FirM Web service checks the
last time that this server performed a
directory synchronisation, and if it is
due (or overdue!), will instruct the
FirM AD service to start pushing up
the AD Directory. This mechanism is
controlled by the Configuration
document, 'AD tab' and 'AD
Synchronisation' sub-tab options.
Also, a 'System Variable' is used to record the next time a directory synchronisation event is due for this
particular domain.
This means that for testing purposes, it is possible to go to 'Tools', 'System Views' and 'System Variables'.
You will find a system variable named ADSYNC_ DOMAIN_<DOMAINNAME> where <DOMAINNAME> will
contain an uppercase-version of the AD domain to be synchronised. It will contain a time/date string such as
“26/09/2008 23:00:01 GDT” which can be set to a time in the past. Next time the relevant Windows server
FirM AD service calls in for work, it will push up the Active Directory directory..
Once these objects have been pushed to the AD Sync database, they
are marked with a status of '0. Awaiting Analysis'. Two further Domino-
based agents run comparing the records in the AD Sync database
with records in the Lotus Domino directories.
The records are then moved from status '0' to other status values,
indicating the objects' status. Status are:
 01. Domino record not in AD. We have found a person
document in the Domino directory that is not linked to an Active
Directory object.
 02. AD Record not in Domino. We have found an Active
Directory person object which is not connected to a Lotus Domino person.

FirM Administration Manual v3.0 © 2009 HADSL


1 6 F I R M A D S Y N C H R O N I S AT I O N PA G E 104 O F 145

These objects can then be selected from the view and


marked with an action. For instance, we have selected a
Domino entry that does not have a corresponding Active
Directory object. In this case, we can:
 Request syncronisation between these objects. We
will be prompted to select an object from the other
Directory. We will then link them.
 Never synchronise this record. This flags this record
as only ever existing in one direcory, and we should
remove it from the list of entries we're interested in.
 Request deletion of this record. Remove this record (from AD or Domino) as we suspect its an
'orphan' record.
 'Request Creation of other object'. If we find a record in AD, this would create a Domino person, and
vice-versa.
 'Requested Common Name Rename of AD Object'. We have found (and linked) two objects, and we
shall make the AD Common name the same as the Domino common Name.
 'Requested Common Name Rename of AD Object'. We have found (and linked) two objects, and we
shall make the Domino Common name the same as the AD common Name.
Once the action has been selected, the record will move in the view to the relevant status. Some actions
require more information before they will successfully complete. Specifically, in some cases we have to
choose a relevant profile to apply to the new transaction.
For instance, if we select an Active Directory object without a corresponding Domino person, and we choose
to 'Create other object', the record will move to status '22. Requested creation of other object'. The record will
display a a red exclamation mark ('!') should more information be required. If so, edit the document, and you
will be prompted for information necessary to complete this transaction.
Once one or more records have been marked, we can click on the 'Commit
Changes' button on the view. This will analyse all outstanding requests in
the database, and create relevant FirM transactions for each request.
It then marks the request with the 'refresh' icon to show that a request is in progress.
Once the request completes, and the next AD
synchronisation operation completes, the records
in the AD Sync database are brought up to date. If
a deletion was requested, and was successful,
the record in the AD Sync database is removed.
If two records are 'joined', then the AD Sync
database record looks like this.
It then generates a transaction in the FirM
processing database of type 'System User Update
Fields'. This then puts the AD UNID (the AD Object
Unique Identifier) into the designated field on the
person document.

12.2. Configuration
The normal AD configuration (from the previous chapter) should be completed and successfully tested. Once
this has been achieved, go to the AD Sync database and open the AD Sync Profiles view.
We should then create a new synchronisation profile.

FirM Administration Manual v3.0 © 2009 HADSL


1 6 F I R M A D S Y N C H R O N I S AT I O N PA G E 105 O F 145

Firstly, we should choose which AD Domain this profile


relates to. We should only have one profile per AD
Domain. Choose from the list of AD domains
configured in the FirM requester Tools, Configuration,
Configuration Document, AD Tab.
Then choose one or more containers that you wish to
synchronise. Sub-containers are automatically
included.
Click on the 'Add' Button to view an AD Container
browser. (Note that this relies in the LSX discussed in
the previous chapter).
Select which kind of AD objects you are interested in
synchronising. In this case, we've chosen Users and
Groups.
We then choose the Lotus Domino domain, server and
directories which we wish to synchronise with.
We then have options to suggest matches based on
common name, short name and so forth. One option – 'Common Name – All Domino Names' is useful, as it
matches the common part of ALL names defined on the person document. This catches people who have
been renamed in one system, but not the other.
We then choose whether this is enabled or not.
The option to synchronise fields is currently not supported and greyed out.
'Limit Profiles based on' allows you to limit the profiles that are suggested based on the users AD hierarchy.

FirM Administration Manual v3.0 © 2009 HADSL


1 7 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 106 O F 145

13. Active Directory Transactions


13.1. AD User Create
AD User create allows a Requester to create a user in Active Directory
Details relating to the notification of completion of this transaction are stored in the AD User Create profile
documents.

13.1.1. Walkthrough of transaction


To create new request, select “New Request” and click forward to the request selection dialog. Now select
ʻAD User Createʼ.

Prompt Explanation Example

Profile If the requester has the choice of more than one AD User
Create transaction profiles, a list of AD User Create
profiles.

Location Profile Each of these profile types may be set in the AD User Dublin
Create profile document. If more than one of each type is
ID Profile selected, then the requester is asked to choose which Staff
particular profile is most appropriate for this operation.
Company Profile Acme

Country Profile UK

Business Group Profile Accounting

Container If the requester has been given the ability to choose the hadsl.local/
AD container for the target user, then the requester may Users
use the AD brower tool to choose the relevant container

First Name Each of these three name values is compared against Joe
validation rules in the System Configuration profile. If the
Middle Intials names pass validation rules, then the Active Directory is X
checked for uniqueness. If any name fails, the Requester
Last Name is informed and invited to re-enter them. Bloggs

Password Recipient One or more people who are to receive an encrypted mail Manager Bloggs
message containing the userʼs password. This is typically
the new userʼs immediate manager.

Dynamic Fields Depending on the settings in the User Create profile, the
Requester may be prompted for one or more pieces of
ʻdynamicʼ data, which will then be used to update the new
userʼs ʻpersonʼ document in the Domino Directory.

13.1.2. FirM Processing


The Requester of the transaction will be compared against the Requester and Administrators fields in the
User Create profile. If the Requester is not allowed to submit this request then it will fail.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor makes exhaustive checks to ensure that the user names requested (Login Name, Common
Name - all are configurable in the AD User Create Profile) are unique across Active Directory.

FirM Administration Manual v3.0 © 2009 HADSL


1 7 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 107 O F 145

The Requester then constructs the user object in Active Directory, setting all relevant AD Person object
fields. Any static or dynamic ʻfieldsʼ specified in the AD User Create profile, is also applied, replacing ʻtokensʼ
with run-time variables as necessary.
The userʼs initial password is stored in the encrypted Password Repository.
A UUP (Resend User ID and Password) request is constructed which will mail the userʼs AD Password to the
Password recipients listed in the initial request.
Zero or more AD Group Manage Member requests are created to add the user to groups specified in the AD
User Create profile.
Using the AD User Create profile, the correct Location profile is examined to establish the target file server.
If more than one target mail server is listed, the target server with the most amount of percentage free disk
space is used as the target server (load balancing).
 An external request is then issued to create the userʼs Home and Profile Directories.
Once processing has completed then any people specified within the Notification list for the relevant group
profile will be sent an email telling them that the group has been created.
The request will remain in the state ʻPending Sub transactionʼ until the AdminP requests and the external
Requests have completed. It will then progress to ʻCompleteʼ.
As with all FirM requests, logging information at every stage is created in the Log Database, Audit trail
records are created in the Audit Database, and Billing information is created in the Billing Database.

13.1.3. AD User Create Profile


The Active Directory User Create profile allows the definition of Active Directory user create transactions.
These transactions create new user objects in your Active Directory environment.

Tab Sub-Tab Sub-Sub Field Explanation


Tab

Name Profile Name The Name of this profile

Fields and Property Properties Zero or more attribute specifications. These are
Groups Settings similar to the Notes ʻFieldsʼ settings in that
tokens and dyanmic field style specifications
can be used.
However, unlike Domino, these have to be
mapped to existing AD Schema property
names for the Person object - these can be
viewed by clicking the ʻAttributeʼ Button.
Care must be taken not to change ʻnameʼ
information attributes using this method as
these fields will be updated by other AD
processes.

Allow User If this is set, then the requester may choose


Cloning another AD user, and the new AD user will be
added to the same AD groups as the selected
clone user.

Default Default Zero ore more AD groups that the new user will
Groups Groups be added to. Groups can be added by clicking
on the ʻSelectʼ button.
All AD groups selected will be added to the new
user using the selected AD Group Create
profile.

Names & Directory Container Generate Pre- If this is not enabled, then the requester will be
Shares Naming Naming Windows 2000 prompted to enter the users Pre-Windows 2000
Login Name login name. Otherwise the definition below will
be used.

FirM Administration Manual v3.0 © 2009 HADSL


1 7 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 108 O F 145

Tab Sub-Tab Sub-Sub Field Explanation


Tab

Pre-Windows A definition using tokens for this name


2000 Login component
Name

Generate If this is not enabled, then the requester will be


Common prompted to enter the users common name.
Name Otherwise the definition below will be used.

Common A definition using tokens for this name


Name component

Generate If this is not enabled, then the requester will be


Display Name prompted to enter the users Display login
name. Otherwise the definition below will be
used.

Display Name A definition using tokens for this name


component

Login/UP If this is not enabled, then the requester will be


Name prompted to enter the users login/UP name.
Otherwise the definition below will be used.

Login/UP A definition using tokens for this name


Name component

AD Tree Container The container in which the target user will be


Navigation created

Specify Parent If set to Yes, the requester can specifiy


Containers containers outwith the default container

Specify sub- If set to Yes, the requester can specify


Containers containers below the default container.

Users Home Users Home Specify how the users home directory will be
Directory Directory Directory created. Its important to include an existing
share name in this directory specification.

User Owns If set to Yes, the new AD user will be set as the
Directory owner of this new folder, otherwise the
Administrator will be set as owner.

Share Share Name If non-blank, then a Windows Share will be


Name created for the new home directory.

Rights User Access Choose the users rights for the home directory.
Level

Set Rights Set zero or more sets of rights for this directory
by choosing AD objects (using the ʻSelectʼ
button) and appending on the relevant rights
flag.

Delegate Set zero or more delegated rights for this


Rights directory by choosing AD objects (using the
ʻSelect button) and appending on the relevant
rights flag.

FirM Administration Manual v3.0 © 2009 HADSL


1 7 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 109 O F 145

Tab Sub-Tab Sub-Sub Field Explanation


Tab

Home Home Drive If set, this drive specification will be copied to


Drive the new users AD attribute for Home drive.

Profile Profile Users Profile Specify how the users profile directory will be
Directory Directory Directory created. Its important to include an existing
share name in this directory specification.

User Owns If set to Yes, the new AD user will be set as the
Directory owner of this new folder, otherwise the
Administrator will be set as owner.

Share Share Name If non-blank, then a Windows Share will be


Name created for the new profile directory.

Rights User Access Choose the users rights for the profile directory.
Level

Set Rights Set zero or more sets of rights for this directory
by choosing AD objects (using the ʻSelectʼ
button) and appending on the relevant rights
flag.

Delegate Set zero or more delegated rights for this


Rights directory by choosing AD objects (using the
ʻSelect button) and appending on the relevant
rights flag.

Script File Script File You can choose a script profile. This will result
Name in tokens in the script being replaced at run
time and the script file sent to the users home
drive server. The script will then be ran on the
users home server, allowing you to perform
other common new user operations.

Sub- Locations Locations Choose one or more Locations reevant for this
Profiles profile.

Business Business Choose zero or more Business Groups


Groups Groups relevant for this profile

Companies Companies Choose zero or more Companies relevant for


this profile

Countries Countries Choose zero or more Countries relevant for this


profile

ID Types ID Types Choose zero ore more ID Types relevant for


this profile

Password Password Choose how you wish the password for the
Distribution new AD user to be distributed

13.2. AD User Disable


AD User Disable create allows a Requester to disable a user in Active Directory.
Details relating to the notification of completion of this transaction are stored in the AD User Disable profile
documents.

FirM Administration Manual v3.0 © 2009 HADSL


1 7 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 110 O F 145

13.2.1. Walkthrough of Transaction

Prompt Explanation Example

Profile If the requester has the choice of more than one AD


User Disable transaction profiles, a list of AD User
Disable profiles.

User Name Select an existing AD user from the directory using hadsl.local/Users/Fred Bloggs
the AD Brower tool

13.2.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the AD User
Disable Profile document. If the Requester is not allowed to submit this request then it will fail. A similar
check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then find the selected user within the AD environment, and sets the “Disabled” flag to 'true'.
Once processing has completed then any people specified within the Notification list defined in the profile will
be sent an email telling them that the request has succeeded.

13.2.3. AD User Disable Profile


The Active Directory User disable profile only prompts you to define the name and description. All
authorisation for this activity is defined using the (common) Authorisation tab.

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

13.3. AD User Enable


AD User Enable create allows a Requester to enable a user in Active Directory.
Details relating to the notification of completion of this transaction are stored in the AD User Enable profile
documents.

13.3.1. Walkthrough of Transaction

Prompt Explanation Example

Profile If the requester has the choice of more than one AD


User Enable transaction profiles, a list of AD User
Enable profiles.

User Name Select an existing AD user from the directory using hadsl.local/Users/Fred Bloggs
the AD Brower tool

13.3.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the AD User
Enable Profile document. If the Requester is not allowed to submit this request then it will fail. A similar
check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then find the selected user within the AD environment, and sets the “Disabled” flag to 'false'.
FirM Administration Manual v3.0 © 2009 HADSL
1 7 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 111 O F 145

Once processing has completed then any people specified within the Notification list defined in the profile will
be sent an email telling them that the request has succeeded.

13.3.3. AD User Enable Profile


The Active Directory User enable profile only prompts you to define the name and description. All
authorisation for this activity is defined using the (common) Authorisation tab.

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

13.4. AD User Password Reset


AD User Password Reset create allows a Requester to reset a user's password in Active Directory.
Details relating to the notification of completion of this transaction are stored in the AD User Password Reset
profile documents.

13.4.1. Walkthrough of Transaction

Prompt Explanation Example

Profile If the requester has the choice of more than one AD


User Password Reset transaction profiles, a list of
AD User Password Reset profiles.

User Name Select an existing AD user from the directory using hadsl.local/Users/Fred Bloggs
the AD Brower tool

Password The users new password 4^HwCp;

13.4.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the AD User
Reset Password Profile document. If the Requester is not allowed to submit this request then it will fail. A
similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then find the selected user within the AD environment, and sets the user password to the one
specified by the Requester.
Once processing has completed then any people specified within the Notification list defined in the profile will
be sent an email telling them that the request has succeeded.

13.4.3. AD User Password Reset Profile


The Active Directory User Password Reset profile only prompts you to define the name and description. All
authorisation for this activity is defined using the (common) Authorisation tab.

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

13.5. AD User Modify


AD User Modify allows a Requester to modify a user in Active Directory.

FirM Administration Manual v3.0 © 2009 HADSL


1 7 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 112 O F 145

Details relating to the notification of completion of this transaction are stored in the AD User modify profile
documents.

13.5.1. Walkthrough of Transaction

Prompt Explanation Example

Profile If the requester has the choice of more than one AD


User Modify transaction profiles, a list of AD User
Modify profiles.

User Name Select an existing AD user from the directory using hadsl.local/Users/Fred Bloggs
the AD Brower tool

Dynamic Data One or more dynamic fields as defined in the AD


User Modify Profile

13.5.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the AD User
Modification Profile document. If the Requester is not allowed to submit this request then it will fail. A similar
check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then find the selected user within the AD environment, and modifies the specified attributes to
the values selected by the Requester.
Once processing has completed then any people specified within the Notification list defined in the profile will
be sent an email telling them that the request has succeeded.

13.5.3. AD User Modify Profile


The 'Details' tab of Active Directory User Modification profile prompts you to define the name and description.
Remember - all authorisation for this activity is defined using the (common) Authorisation tab.

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

Fields Fields The “Fields” tab allows you to define which AD


User Object attributes will be updated for the
target user.
In order to see which AD attributes are
available for modification, click on the 'Attribute'
Button. A list will be displayed allowing you to
select a value.
The “Keyword” button pops up a list of
keywords available for this transaction.
The “Dynamic Field” button allows you to use
the dynamic field helper to build one or more
prompts for the requester at run-time. Each
attribute defined in each prompt will be updated
by the AD User Modification transaction.

13.6. AD Group Create


AD Group Create allows a Requester to create a group in Active Directory.

FirM Administration Manual v3.0 © 2009 HADSL


1 7 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 113 O F 145

Details relating to the notification of completion of this transaction are stored in the AD Group Create profile
documents.

13.6.1. Walkthrough of Transaction

Prompt Explanation Example

Profile If the requester has the choice of more than one AD


Group Create transaction profiles, a list of AD Group
Create profiles.

Container The Requester should choose the target container in hadsl.local/Users


which this group will be created, if this is allowed by
the profile document

Group Name The name of the new group Mail Users - Swindon

Group A description for the new group. This will be visible in Users in the Swindon Office
Description Active Directory

Group Type The requester should choose between a security


group and a mail distribution group

Members Choose zero or more existing AD users to add to this


group

13.6.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the AD
Group Create Profile document. If the Requester is not allowed to submit this request then it will fail. A
similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then ensure that a group of this name does not already exist. It then creates the group in the
correct container, and populates the group with all information entered by the Requester.
Once processing has completed then any people specified within the Notification list defined in the profile will
be sent an email telling them that the request has succeeded.

13.6.3. AD Group Create Profile


The 'Details' tab of Active Directory Group Create profile prompts you to define the name and description.
Remember - all authorisation for this activity is defined using the (common) Authorisation tab.

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

13.7. AD Group Delete


AD Group Delete create allows a Requester to create a delete in Active Directory.
Details relating to the notification of completion of this transaction are stored in the AD Group Delete profile
documents.

FirM Administration Manual v3.0 © 2009 HADSL


1 7 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 114 O F 145

13.7.1. Walkthrough of Transaction

Prompt Explanation Example

Profile If the requester has the choice of more than one AD


Group Delete transaction profiles, a list of AD Group
Delete profiles.

Group Name Select an existing AD group from the directory using hadsl.local/Users/Mail Users -
the AD Brower tool Swindon

13.7.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the AD
Group Delete Profile document. If the Requester is not allowed to submit this request then it will fail. A
similar check is performed against the Authoriser of the request.
Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then ensure that a group of this name already exists. It then removes the group from the
Active Directory environment.
Once processing has completed then any people specified within the Notification list defined in the profile will
be sent an email telling them that the request has succeeded.

13.7.3. AD Group Delete Profile


The 'Details' tab of Active Directory Group Delete profile prompts you to define the name and description.
Remember - all authorisation for this activity is defined using the (common) Authorisation tab.

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

13.8. AD Group Modify


AD Group Modify create allows a Requester to modify a group in Active Directory.
Details relating to the notification of completion of this transaction are stored in the AD Group Modify profile
documents.

13.8.1. Walkthrough of Transaction

Prompt Explanation Example

Profile If the requester has the choice of more than


one AD Group Modify transaction profiles, a
list of AD Group Modify profiles.

Group Name Select an existing AD group from the directory hadsl.local/Users/Mail Users -
using the AD Brower tool Swindon

Members to Add Select zero or more existing AD users to either


add or remove from this group
Members to Remove

13.8.2. FirM Processing


The Requester of the transaction will be compared against the list of valid Requesters defined in the AD
Group Modification Profile document. If the Requester is not allowed to submit this request then it will fail. A
similar check is performed against the Authoriser of the request.
FirM Administration Manual v3.0 © 2009 HADSL
1 7 C O N F I G U R I N G A P P L I C AT I O N T R A N S A C T I O N S PA G E 115 O F 145

Processing will check that all relevant information is present in the request. If vital information is missing
(this should not be possible) then the request will fail, detailing the reasons for failure in the FirM log and also
in the request.
The processor then ensure that a group of this name already exists. It then updates the groups attributes to
reflect the changes requested.
Once processing has completed then any people specified within the Notification list defined in the profile will
be sent an email telling them that the request has succeeded.

13.8.3. AD Group Modify Profile


The 'Details' tab of Active Directory Group Modification profile prompts you to define the name and
description. Remember - all authorisation for this activity is defined using the (common) Authorisation tab.

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

FirM Administration Manual v3.0 © 2009 HADSL


1 9 B L A C K B E R R Y O V E R V I E W PA G E 116 O F 145

14. BlackBerry Overview


The BlackBerry component within FirM allows basic management of BlackBerry handsets in your Domino
environment.

14.1. Architecture.
The FirM BlackBerry interface relies on the BlackBerry Enterprise Server Resource kit (BRK). A copy of this
kit has to be installed on the FirM primary (and optionally secondary) processing servers.

BES Server
Domino
BES Server Handset
BES Server

FirM Primary Processing


Server

Requests entered in the FirM request processor database are then processed on the FirM primary
processing server. This server, once the request has been validated will then make calls to the BlackBerry
Resource Kit client executable. This in turn will make network calls to the relevant BlackBerry Enterprise
Server on your intranet, and perform the required transactions.
From a network perspective, this means that the FirM Processing Server(s) and all BlackBerry Enterprise
servers require to be able to communicate with each other, using whatever network protocol is utilised by the
BES server.
As all BlackBerry components are windows based, this does mean that the FirM Primary and Secondary
processing Domino servers also have to be windows based.

14.2. Installing the BlackBerry interface


We advise using v4.x or above of the BlackBerry Enterprise Server Resource Kit (BRK).
The BRK can be downloaded from: http://www.blackberry.net/support/downloads/resourcekit.shtml
1. Install the tool as directed in the Resource Kit instructions.
 You need to install the “BesUserAdminClient” service on the FirM Primary (and optionally
secondary) processing servers.
 You need to install the “BesUserAdminService” on each of the BES Enterprise servers you wish
to manage.
 You will be asked to enter a password in the resource kit during the installation. If you are
installing the BRK in both the FirM primary and secondary processing servers, ensure that the
same password is used. This password will then be lodged in the FirM Password repository
using the button on the Configuration Profile form. See page 28 for more information.
 If you are installing the BRK on the primary and the secondary FirM processing servers, please
install the toolkit to the same location, and enter the full path and executable file into the
Configuration Profile – BlackBerry tab. See page 28 for more information.
2. Test that the BRK is functioning by running the “BESUserAdminClient” with a test transaction from the
command line.
3. Set the Domino server service to log on using a user account rather than the system logon.
 In order that the Domino server application can communicate with the BRK, it is necessary for the
Domino service to be started with a user account rather than the system account.
4. Enable the BlackBerry components within the FirM Processing database. See “System Configuration
– BlackBerry” on Page 28 for more information.
5. Associate one or more BES servers with each relevant location. See the section “Location Profiles -
BlackBerry servers tab” on page 34
FirM Administration Manual v3.0 © 2009 HADSL
1 9 B L A C K B E R R Y O V E R V I E W PA G E 117 O F 145

6. Create one or more BlackBerry Profiles. See the section titled “Configuring BlackBerry Transactions”
on page 127.
7. Create new FirM requests using these profiles.

FirM Administration Manual v3.0 © 2009 HADSL


2 1 B L A C K B E R R Y T R A N S A C T I O N S E X P L A I N E D PA G E 118 O F 145

15. BlackBerry Transactions


This section shows the end-user experience and interaction in creating transactions for BlackBerry
Transactions.

15.1. Authorisation
The Authorisation process for BlackBerry transactions mirror that for Domino User transactions:
 A list of potential Requesters are defined on the relevant transaction profile document. Only
Requesters listed on that transaction document can create transactions based on that profile.
 A list of Authorisers is listed on that transaction. If a requester is also on the list of Authorisers, then
the transaction is immediately processed.
 A list of name masks is defined on the profile document, showing who this transaction can be
applied against, using that users Lotus Notes name.

15.2. BlackBerry Provision


BlackBerry Provision allows you to associate a Lotus Domino mail user with a new BlackBerry device.
To create new request, select “New Request” and click forward to the request selection dialog. Now select
ʻBlackBerry Provisionʼ.

Prompt Explanation Example

Profile A list of profiles for this transaction if the user has the choice of more
than one.

User Name Choose a user to provision a BlackBerry handset for. Joe Bloggs
At this point, the BlackBerry provision transaction will look up the
users home mail server, and try and establish if this home server is
associated with a location which has a BlackBerry server associated
with it. If not, the requester will be prompted to select another user.
If the users home mail server is associated with more than one
location, then the requester is prompted to select the location that the
user is actually associated with (in order to choose the correct
BlackBerry Enterprise server). If the user's mail server is only
associated with one location, then that location will be displayed.

Activation An activation password is generated, which the requester may


Password optionally override.

15.2.1. BlackBerry Provision Profile

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

15.2.2. BlackBerry Provision CSV Defintion


Header Text Mandatory Comments
Transaction Yes BPR
TransactionProfile Yes A BlackBerry Provision profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this transaction
Password Yes The users activation Password for Blackberry

FirM Administration Manual v3.0 © 2009 HADSL


2 1 B L A C K B E R R Y T R A N S A C T I O N S E X P L A I N E D PA G E 119 O F 145

Location Yes The name of a location (as you have defined within FirM) that the
users home server is associated with, and has a BlackBerry
server associated with it.

15.3. BlackBerry Enable


This transaction enables “Mobile Data Service” for a BlackBerry handset user. This is enabled by default
when a new user is created – therefore this transaction is only of value if a BlackBerry handset user has
previously been disabled.
To create new request, select “New Request” and click forward to the request selection dialog. Now select
ʻBlackBerry Enableʼ.

Prompt Explanation Example

Profile A list of profiles for this transaction if the user has the choice of more than
one.

User Name Choose a User from the directory Joe Bloggs

15.3.1. BlackBerry Enable Profile

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

15.3.2. BlackBerry Enable Defintion


Header Text Mandatory Comments
Transaction Yes BEN
TransactionProfile Yes A BlackBerry Enable profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this transaction

15.4. BlackBerry Disable


This transaction disables “Mobile Data Service” for a BlackBerry handset user. This is of value if a user does
not wish to use their BlackBerry handset for a short period of time – say – whilst on vacation.
To create new request, select “New Request” and click forward to the request selection dialog. Now select
ʻBlackBerry Disableʼ.

Prompt Explanation Example

Profile A list of profiles for this transaction if the user has the choice of more than
one.

User Name Choose a User from the directory Joe Bloggs

15.4.1. BlackBerry Disable Profile

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

15.4.2. BlackBerry Disable CSV Defintion


Header Text Mandatory Comments

FirM Administration Manual v3.0 © 2009 HADSL


2 1 B L A C K B E R R Y T R A N S A C T I O N S E X P L A I N E D PA G E 120 O F 145

Transaction Yes BDI


TransactionProfil Yes A User Cross Certify profile defined in FirM
e
UserName Yes A fully hierarchical name identifying the user for this transaction

15.5. BlackBerry Reset Password


This transaction allows a requester to reset the password on a users BlackBerry handset.
To create new request, select “New Request” and click forward to the request selection dialog. Now select
ʻBlackBerry Reset Passwordʼ.

Prompt Explanation Example

Profile A list of profiles for this transaction if the user has the choice of more than
one.

User Name Choose a User from the directory Joe Bloggs

15.5.1. BlackBerry Reset Password Profile

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

15.5.2. BlackBerry Reset Password CSV Defintion


Header Text Mandatory Comments
Transaction Yes BRP
TransactionProfile Yes A BlackBerry Reset Password profile defined in FirM
UserName Yes A fully hierarchical name identifying the user for this transaction
Password Yes The users new handset password

15.6. BlackBerry Delete


This transaction deletes the association between the BlackBerry server and a Lotus Domino mail user.
To create new request, select “New Request” and click forward to the request selection dialog. Now select
ʻBlackBerry Deleteʼ.

Prompt Explanation Example

Profile A list of profiles for this transaction if the user has the choice of more than
one.

User Name Choose a User from the directory Joe Bloggs

15.6.1. BlackBerry Delete Profile

Tab Field Explanation

Name Profile Name The Name of this profile

Description A description for the profile.

FirM Administration Manual v3.0 © 2009 HADSL


2 1 B L A C K B E R R Y T R A N S A C T I O N S E X P L A I N E D PA G E 121 O F 145

15.6.2. BlackBerry Delete CSV Defintion


Header Text Mandatory Comments
Transaction Yes BDE

TransactionProfil Yes A User Cross Certify profile defined in FirM


e
UserName Yes A fully hierarchical name identifying the user for this transaction

FirM Administration Manual v3.0 © 2009 HADSL


2 3 T H E F I R M A P P L I C AT I O N M O N I T O R PA G E 122 O F 145

16. The FirM Application Monitor


The FirM application monitoring suite is a new addition to FirM v2.1. This allows the Administration staff of a
Domino environment to track more effectively the application usage throughout the Domino environment.

Architecturally, it comprises two databases. These databases should be replicated to each server (and any
intermediate server on your replication path) upon which you wish to measure and track application usage.

Two scheduled agents exist within this database. These


can be enabled via the “Tools, Validation, Scheduled
Agents” control panel:

16.1. The Application Monitor Database


The Application Monitor database contains:
 Summary information on each database instance on every server throughout your environment.
 ACL information for each database instance.
 ACL Change log information for each application instance.
 Optional Template copies of each application
 Optionally “Design Complexity” information for each application instance.

To open the Application Monitor database, open the database


“firmapplicationmontior.nsf” in your FirM directory on the main FirM
processing server, or click on the Icon.

Double clicking on an Application instance document:. The Details tab


shows:
 The Application Title
 Application Type
 Instance status – 0 means “Discovered”
 The Application Replica ID
 The server that this instance is hosted on.
 The File Path of the application instance
 Whether the database instance has been removed from the
server, and if so, when it was deleted.

The “Size” tab shows size information for this instance, and when it was
last updated.

The “ACL” tab shows all instances of this database. Double clicking on one shows the current ACL of this
database:

FirM Administration Manual v3.0 © 2009 HADSL


2 3 T H E F I R M A P P L I C AT I O N M O N I T O R PA G E 123 O F 145

This shows a Database current


Access Control List, and the
time that it was collected

The “ACL Log” tab shows all ACL modifications for all
instances of this application.

The “Instances” tab shows all instances of this database,


and current size information for each instance.

The “Used By” Tab shows usage information for this


database, and allows easy access to the Application
Usage database to highlight actual user usage.

FirM Administration Manual v3.0 © 2009 HADSL


2 3 T H E F I R M A P P L I C AT I O N M O N I T O R PA G E 124 O F 145

16.2. The Application Usage Database


The Application Usage Database contains a combined User Activity record for every single database
instance in your environment.
This allows the tracking of Application usage for security
and maintenance/operational reasons.

You can browse the database and open a particular


tracking event – this shows application static
information such as Title, Replica ID, server, FilePath
and file name, as well as event information such as
User ID, date & time, reads and writes, transactions
and duration.

FirM Administration Manual v3.0 © 2009 HADSL


2 4 I M P O R T I N G T R A N S A C T I O N S U S I N G C S V PA G E 125 O F 145

17. FirM Group Monitoring


17.1. Group Monitoring Explained
The FirM Group Monitor is designed to tell you if the membership of a critical group was changed without
using FirM.
For example, if you use FirM to manage the group “High Sensitivity Mailing List” then you will have set up
ownership and delegation such that only certain people are authorised to change it's membership.
It is possible that somebody has inappropriate access to the Domino Directory and is able to modify the
group membership directly, adding themselves to this group in order to be the recipient of sensitive emails.
So, the group can be flagged as being monitored, and FirM will alert you to changes of this group's
membership that did not occur through FirM, which now gives you assurance that user in the environment
cannot silently use round-about means to gain access to the group's mailings.

17.2. Group Monitoring Components


There are 4 components to FirM Group Monitoring:
 The “Shadow Group Monitoring” agent
 The FirM Monitored Group Shadow repository database
 Settings within the group's entry in the FirM Group Repository
 The “GSR-Group Change” notification profile

The Shadow Group Monitoring agent provides the engine that periodically checks groups and issues
warnings of changes. This can be configured to run at any periodic interval – hourly, daily, weekly, etc.
The FirM Monitored Group Shadow repository database contains reference copies of the groups and their
contents. Every time the Shadow Group Monitoring agent runs it checks for monitored groups and creates
and deletes these documents as required. If a group's content differs from the contents of it's entry in the
shadow repository then the monitor creates and sends a notification, and then updates the membership
contents of the shadow repository document so that persistent notifications are not created.
The group's entry in the FirM Group Repository contains a check box field that tells the group monitor
whether it should check this group for changes or not.
Finally, the notification profile is the template that is used by the group monitor when it creates notification.
You can tailor this notification to your exact requirements.

17.3. Setting up Group Monitoring


The Shadow Group Repository will have been created and configured by the FirM Installer and must have a
valid path specified in the FirM Configuration Profile (this is under the “Databases\Group Register” tab). If
the Shadow Group Repository database is not present then you will need to download and install the latest
version of FirM.
Review the text of the notification profile “GSR – Group Change” and change if necessary. By default, the
notification is set to mail the “<DEFAULTADMINISTRATOR>” tag with any warnings – this tag is replaced by
the Shadow Group Monitoring engine with the names of the users and groups specified in the FirM Default
Administrators setting of the FirM Configuration Profile.
Now you must enable the Shadow Group Monitoring agent. Under the Tools Menu select the “Validation”
tab, and click on the “Refresh Agent Status” button. (See the subsection called “Validation Tab” in the
“Administration Tools” section on page Error: Reference source not found.)
Locate the entry for the Shadow Group Monitoring agent and ensure that it is set to run on the correct server
– if not, click on the server name and choose the correct server from the displayed list.
Finally, enable the agent by clicking on the red diamond. This should change to a green diamond once the
agent has been enabled.

FirM Administration Manual v3.0 © 2009 HADSL


2 4 I M P O R T I N G T R A N S A C T I O N S U S I N G C S V PA G E 126 O F 145

17.4. Selecting the Groups to Monitor


You must manually mark groups that should be monitored by editing their entries in the FirM Group
Repository.
 Open the firm Group Repository database and select a suitable view to locate the group's entry;
 Locate the entry for the group that you want to monitor and double click on it to open the document;
 Select the “Details” tab;
 Select the check box field “Report unauthorised changes to this group”; and finally
 Save and close the group entry
See the sub-section titled “Group Registry” in the “FirM Databases” section on page 154 for more
information.
When the Shadow Group Monitor agent next runs, it will create a shadow entry for this group. Whenever the
group membership changes and there is no corresponding FirM Group Manage Members request for the
group then it will report that the group has been modified.

17.5. Limitations of Group Monitoring


Whenever FirM processes a Group Manage Membership request it will update the group's entry in the FirM
Monitored Group Shadow database to reflect the new membership.
However, some processes such as the Domino Administration Process will also change group membership
for such tasks as user/group deletes and renames. In the current version FirM will report changes made by
AdminP as being unauthorised changes.
Therefore it is recommended that only sensitive groups are monitored for changes, and that the alert list for
modifications is kept fairly small.
You may also consider changing the text on the notification profile so that it warns the recipient that the
notification may have happened as part of a user delete or rename.

In order for FirM Group Monitoring to be able to monitor a group's content, the group must have been
imported into FirM for management, or the group must have been created using FirM. It is the action of
importing or creating a group that will create the group's entry in the FirM Group Repository.

FirM Administration Manual v3.0 © 2009 HADSL


2 6 I D B A C K U P, R E F R E S H A N D E S C R O W PA G E 127 O F 145

18. ID Backup, Refresh and Escrow


Within a corporate Lotus Domino environment, user ID file management, recovery and auditability are key
security policies. Security within this area should be rigorous and well understood.
FirM will automatically enable you to meet a basic requirement of ID file management, which is to keep
secure copies of all new user IDs and passwords that are created. However, once these IDs are distributed
to the Notes clients and actions such as renames, recertifications, moves, etc are performed against the
users there is a problem in that the local Notes workstation copies of the ID files will be updated but not the
stored copies.
If loss or irrecoverable software failure occurs on the local computers then you need to be able to restore the
latest version of the ID files – this is especially important in environments that implement the password
checking/digest features of Notes & Domino, or where private encryption keys are used.
FirM incorporates two features that will help you to ensure that stored IDs are always kept up to date – ID
Backup and ID Escrow.
ID Backup is a process that monitors the administration request databases looking for requests that will
trigger changes to the users' ID files. The users who are the subject of these requests will then receive an
email that will enable them to lodge the updated copy of their ID file and password with FirM. The advantage
of this method is that the ID and password combination lodged with FirM is available for immediate use when
restoring a workstation. The disadvantage is that it requires user interaction.
ID Escrow is a process that will leverage the Password Recovery mechanism within Notes and Domino, and
lodge copies of returned IDs in FirM. The advantage of this mechanism is that no user interaction is
required. However, the disadvantage is that the IDs recovered are not immediately useable when restoring
an end-user workstation, and the password recovery procedure must be performed on the ID prior to use.
We recommend that you configure and enable one of these ID maintenance features, but both features
must not be enabled simultaneously.

18.1. ID Backup
ID Backup is the process that will actively monitor administration requests that modify the user's ID file, send
an email the user (requesting that they lodge a backup of their ID and password) and process the returned
IDs and passwords so that they are securely stored in FirM's ID and Password repositories.
We recommend enabling this process so that it runs on a periodic basis once per day. The process for ID
backup is as follows:

 ID Backup monitors all Administration Process (AdminP) databases for domains managed by FirM
for new requests of type “Rename User”, “Recertify User” and “Update User Password”.
 When a request is found ID Backup checks for an outstanding request for the user to lodge the
password & ID. If no current request is found then an email is sent to the user requesting that they
lodge their ID and password. This email contains a rich-text button containing code to return the
user's ID and password. A temporary document is created in the Escrow database – this document
contains details of the status of the backup request, all matching AdminP requests for this user,
number of reminders sent, alternative user names, etc. It has an initial status of “Pending”.
 When the end user clicks on the button in the email it will check that they are the mail file owner (this
ensures that incorrect IDs cannot be lodged inadvertently by someone using delegation privileges to
access a mail file), locate the current ID, ask for the password and then create two return emails –
one for the ID file and one for the password. These emails are additionally encrypted (using the
public key in the Escrow database mail-in database document), which ensures that IDs and
passwords cannot be intercepted at any stage of the mail routing.
 ID Backup monitors these returned emails, and will then create encrypted documents in the FirM ID
and Password repositories. The email returned from the user is removed, and the temporary backup
request document is updated with a “completed” status.
 ID Backup also monitors outstanding notifications with a status of “Pending”. If a response has not
been received from the user within a set period of time then it will send a reminder to the user – the
total number of reminders sent to a user for any outstanding request can be specified in the ID
Backup configuration settings.

FirM Administration Manual v3.0 © 2009 HADSL


2 6 I D B A C K U P, R E F R E S H A N D E S C R O W PA G E 128 O F 145

 Temporary request documents for Completed backup notifications will be retained for a period of
time (in order to prevent repeated requests to back up IDs being triggered by the same AdminP
request). After this time they will be removed from the Escrow database.

18.1.1. Configuration of ID Backup


A few simple steps must be followed to configure and enable ID Backup:
 Create a new mail-in database document in your Domino Directory:
 The mail-in name must be “escrow”
 The domain, server name and file name must point to your copy of the FirM Escrow Agent
database
 Under the “Administration” tab you will find a section called “Certificates”. You must copy the
public key of the FirM Primary Processing Server into the “Notes certified public key” field (the
server's public key can be found in the “Certified public key” field under the Administration tab of
the server document – this field is only visible for a user with editor or above access, when the
document is in edit mode). Note – if the public key is not present in this document then users
will be presented with a dialog “this email could not be encrypted – ok to send?” when they click
on the button in the backup request email.
 Save and close this mail-in database document.
 If you are implementing this in a multi-domain environment then you must ensure that this mail-in
database is addressable and can receive encrypted emails from all managed domains.
 In the FirM Request Processor database, open the Tools menu, click on the “Config” tab and then
click on the “Edit the System Configuration” link.
 Click on the “Admin Settings” tab, and then the “ID Backup” tab underneath this.
 Set the following field values:
■ “AdminP Search Hours” - this sets the number of hours backwards that ID Backup will
search for matching AdminP requests. This should be set as a minimum to the number of
hours between runs of the ID Backup agent, or the longest replication time from any mail
server Admin4.nsf database to the FirM Processing server (whichever is the longer). This
setting ensures that new administration requests cannot be missed by successive runs of
the ID Backup agent.
■ “Store Retention Hours” - this sets the minimum number of hours that completed temporary
backup-request temporary documents will be retained in the FirM Escrow Agent database.
Set this value so that it is equal to or greater than the AdminP Search Hours field value.
■ “Reminder Frequency” - this is the number of days that will elapse between users being
reminded to back their ID file up (if they have not already responded). This should be set to
be a minimum of one day (note – for testing purposes this field can be set to be a negative
number. In this case then the reminder frequency will be in minutes, not days).
■ “Maximum number of reminders” - this field should be set so that the user does not continue
to receive reminders indefinitely. It sets the maximum number of reminders that will be sent
to the user after the initial backup request.
■ “Users to Include” - this is a name-mask field, to enable you to set ID Backup to run for only
a specified subset of users in your organisation. Multiple masks can be defined – separate
entries with new lines. Full usernames or wildcard entries are acceptable – note that it is
NOT possible to specify a group in this name mask field.
■ Save and close the configuration document.
 Change to the “System Profiles” sub tab of the “Profiles” section of the tools menu.
 Select “System Notification Profiles” in the radio button selection
 Scroll down through the profiles and locate the “IDB-RequestBackup” profile.
 Select the “Rich Text Footer” tab
 Right-click on the button contained within the rich text footer field, and choose “Edit Button” from
the menu. Note – do not left-click on this button as this will attempt to execute the button code.
The lotusscript edit pane will be displayed.
 Place your cursor anywhere on a blank line or at the end of a line within the lotusscript code and
insert a space.

FirM Administration Manual v3.0 © 2009 HADSL


2 6 I D B A C K U P, R E F R E S H A N D E S C R O W PA G E 129 O F 145

 Now click anywhere on the notification profile (except for on the button!) and the lotusscript edit
pane will disappear.
 Now use the “Tick” button to save and close this notification profile.
 The code contained within the button has now been signed with your ID. This should prevent
the end users from receiving ECL warnings when they click on the received button. If a different
ID is used to distribute code within your environment then use this ID to sign the button code –
contact your FirM support representative for help with this step if it is required.
 Now change to the “Validation” tab on the Administration Tools menu and click on the “Refresh Agent
Status” button.
 Locate the “Process Incoming Escrow IDs” agent and ensure that this agent is disabled (it
should have a red diamond icon against it). If it is currently enabled then this must be disabled
before enabling the ID Backup agent – click on the green diamond icon to disable it.
 Now locate the “ID Backup” agent and ensure that it is set to run on the FirM primary processing
server (this can be changed by clicking on the server name and selecting the server from the
address book dialog). Enable the agent for execution by clicking on the red diamond icon.
The ID Backup process is now configured for execution.

18.1.2. Monitoring the ID Backup process.


The ID backup process can be monitored through the use of the views
in the FirM Escrow Agent database.
All documents relating to the ID Backup process can be viewed through
the links under the “ID Backup” menu section.
The “Requests” views show the temporary request documents that are
created and updated when new AdminP requests are found by the
agents, emails sent to the users and returns processed.
The “Returns” views show the ID Backup emails that are generated and
returned from users when they click on the button contained within the
email. These emails are encrypted with the server's public key, and
you will not be able to access either the ID file or the password
contained within them. Once they have been processed then they will
be deleted from the database.
The Identifier that is referred to within these views and documents is
the UNID of the originating AdminP request.

18.2. ID Escrow
Since Lotus Notes/Domino v6, a “password recovery” mechanism has been built into the core Lotus Notes
product. ID Escrow is the alternative mechanism within FirM by which end-user ID files can be captured by
leveraging the password recovery mechanism.
ID files captured with this mechanism do not require end-user intervention, but they do require password
recovery to be performed against them before they can be used to reconstruct a Notes workstation client.

This process must not be enabled if you are running the FirM ID Backup procedure – ID Backup should be
disabled prior to enabling the ID Escrow process.
To install “Password Recovery” in your Lotus Notes environment, open the Lotus Notes Administration Help
database, and look for the document entitled “Setting up ID recovery”. The process is:
 To open the administration client
 Click on the “Configuration” tab
 Click on the “Edit Recovery Information” option under “tools” (on the right)
 Open your Notes Certifiers
 Enter the Certifier password
 You will see the Recovery Information Dialog screen:
 Enter one or more names in the “Recovery Authorities”

FirM Administration Manual v3.0 © 2009 HADSL


2 6 I D B A C K U P, R E F R E S H A N D E S C R O W PA G E 130 O F 145

 Enter a mail-in database name that the modified ID files will be mailed to. We strongly recommend
that the Escrow Database is used for this purpose. See the section “Escrow Database” on page 156
for more information.
From now on, whenever a client updates their local ID file with their notes client – for instance when they
change their password, accept a new name etc. – their ID file will be automatically and (by default) silently
mailed in encrypted form to this database. (Lotus Notes v5 also performed this function, but prompted the
users for confirmation, resulting in a low success rate).
It should be borne in mind that ID's sent back in this manner require to be “recovered” using the Password
Recovery mechanism.
This method is secure, foolproof, and gives you a complete record of all ID files in use in your environment.
This process is the only reliable secure and non-user reliant method of maintaining an up-to-date ID
repository.

18.3. The ID Refresh Process


The ID refresh process has been added as an optional agent to:
 Detect, via the Admin4.nsf database, significant ID file changes, such as rename common name, or
move in hierarchy.
 Find the latest copy of the users ID file in the ID repository, and then refresh that ID+Password pair
against the change requests registered in that User's person document in the Domino directory.
This means that even through you may not have a physical copy of the users new ID file (it may still be on
their workstation), the copy of their ID in the ID repository is kept up-to-date.
This process is set to run once per night, and will update each User ID + Password pair only once per
change request. To enable this, enable the agent 'Refresh ID Files', using the Administration 'Tools' page,
'Monitoring' tab.
This process can be monitored by examining the log database, selecting 'Logs by Type' and choosing logs in
the category 'Refresh ID Files'.

FirM Administration Manual v3.0 © 2009 HADSL


2 7 U S E R M A I L F I L E Q U O TA M A N A G E M E N T PA G E 131 O F 145

19. User MailFile Quota Management


The User MailFile Quota Management system within FirM allows an administrator to delegate User MailFile
quota operations to non-technical staff.
 The configuration section is outlined in section: “User MailFile Quota Tab” on 26.
 The user request is outlined in section: “User MailFile Quota” on page 68.
 The user profile is outlined in section: “User MailFile Quota” on page 81
User MailFile Quota Management supports two modes of operation:

19.1. Non-Person Document Update Mode


By default, FirM does not update person documents in your directory to indicate current user Quota settings.
This reduces the amount of change in the Domino directory, but does mean that requesters cannot see a
users existing quota setting whilst setting a new quota.

19.2. Person-Document Update Mode.


In this mode, FirM's Extended AdminP Processor (See the section “Extended AdminP Processor” on Page
153 for more information) will:
 On each new Quota Management request, set the fields outlined in the configuration tab (See Page
26 for more information) in the relevant person document. The users' person document is updated
on the Administration server for the domain in order to prevent replication conflicts occurring with the
users person documents.
 Every evening, a scheduled agent will compare all user files on the server against the quota
management band defined in the person document. If the users Mail File Quota and Threshold are
different, it will set the users mailfile Quota and Threshold figures to the correct values.
This means that should the Administrator update the Quota Bands on the configuration document,
then overnight all user mail files and cluster replicas will be set to the correct values.
The scheduled agent also checks the users cluster MailFile replicas and set them to the quota limits
defined in the person document, ensuring that the users MailFile and cluster replicas of his MailFile
have consistent quota information set.
 For people who have no quota band figure set, you can choose – using the Configuration Document
– how you wish these people to be managed. The recommended option is to set a mail file quota
band initially above their current mail file quota usage – in order that everyone has a quota band set,
and no users initially are prevented from using their mail file.
In order to view all users by MailFile band, you may wish to amend the design of your Domino Directory to :
 Add a new system-administrators only view categorised by the field you defined for the quota band
name – defined on the Configuration tab.
 Add a table to the subform “$PersonExtensibleSchema” containing the four fields defined on the
configuration tab. This will allow you to open a person document and view the quota information in
the “other” tab.
Note that these modifications are not required for operation, and should only be used to display the MailFile
Band information for users. You may have to reapply these changes whenever you upgrade your Domino
Directory design – for instance, should you upgrade to a new Domino version.

FirM Administration Manual v3.0 © 2009 HADSL


2 8 T H E A U T O M AT I C U S E R R E C E R T I F I C AT I O N
E N G I N E PA G E 132 O F 145

20. The Automatic User Recertification Engine


The Automatic User Recertification Engine is used to recertify users whose certificates expire in a pre-
configured number of days.
The automatic User Recertification Engine looks for candidates every day, week or month and generates
user recertification requests for any users that expire within the pre-configured number of days.
This relies on two main pieces of configuration:
 The System Configuration Profile screen – ʻAdmin Settingsʼ tab, ʻMisc Settingsʼ sub-tab. The engine
is enabled in this tab. Recertification requests are created a certain number of days before the
certificate expires – the number of days is also specified in this tab. See System Configuration –
Admin Settings on page 25.
 The System Recertification Profiles. This attempts to find a match between an expiring user, and a
user expiry profile. See Automatic Recertification Profiles on page 36
If a user matches a profile, a recertification request is automatically created using the matching profile
information. This recertification request uses the userʼs certifier to recertify their user ID.
To enable the Automatic User Recertification Engine, enable the agent “Automatic User Recertification. See
the subsection “Validation Tab” in the “Administration Tools” section on page Error: Reference source not
found for more information.

FirM Administration Manual v3.0 © 2009 HADSL


2 9 T H E E X P I R Y E N G I N E PA G E 133 O F 145

21. The Expiry Engine


FirM contains an Expiry Engine which allows you to programmatically set object to expire in time – this is
useful if your organisation has a high turnover of contract staff, or create groups for specific short-term
projects.

21.1. The User Expiry Engine


FirM has the ability to manage an expiry workflow for users through the “System User Expiry” transaction.
This is currently a transaction that must be created by the FirM API and has not yet been exposed to the
FirM UI. Therefore this section contains only a brief outline of the operation of this transaction – for further
information please contact HADSL.
When a User Create transaction is generated by an external programme using the FirM API, there is the
option to set a user expiry date. This date is recorded within a field in the Person Document. This field
name is specified within a setting in the System Configuration Profile screen – See System Configuration –
Archiving & Expiry on page 27.
The external process is responsible for monitoring this field in the Domino Directory and when a user nears
their expiry date it must create a transaction of type “System User Expiry”, passing the name of the user, the
expiry date and a list of authorisers who can accept this expiry or change the expiry date.
This expiry transaction will then notify the authorisers of the impending expiry, and they can choose to
approve the deletion of the user or extend their expiry date. If the expiry date is extended then the user
expiry request simply changes the userʼs expiry date in their person document, and proceeds to completion.
However, if the authoriser chooses to approve the deletion or does not respond to the request then the
transaction will create a User Delete sub transaction.
The User Deletion process is then followed to completion for this user.

21.2. The Group Expiry Engine


FirM has the ability to manage an expiry workflow for groups through the “System Group Expiry” transaction.
This is currently a transaction that must be created by the FirM API and has not yet been exposed to the
FirM UI. Therefore this section contains only a brief outline of the operation of this transaction – for further
information please contact HADSL.
When a Group Create transaction is generated by an external program using the FirM API, there is the
option to set a group expiry date. This date is recorded within a field in the Group Document and also within
the groupʼs entry in the Group Repository. This field name is specified within a setting in the System
Configuration Profile screen – See System Configuration – Archiving & Expiry on page 27.
The external process is responsible for monitoring this field in the Domino Directory and when a group nears
its expiry date then the process must create a transaction of type “System Group Expiry”, passing the name
of the group, the expiry date and a list of authorizers who can accept this expiry or change the expiry date.
This expiry transaction will then notify the authorizers of the impending expiry, and they can choose to
approve the deletion of the group or extend its expiry date. If the expiry date is extended then the group
expiry request simply changes the groupʼs expiry date in its group document, and proceeds to completion.
However, if the authorizer chooses to approve the deletion or does not respond to the request then the
transaction will create a Group Delete sub transaction.
The Group Deletion process is then followed to completion for this group.

FirM Administration Manual v3.0 © 2009 HADSL


3 0 T R O U B L E S H O O T I N G & S U P P O R T PA G E 134 O F 145

22. Troubleshooting & Support


In any complex software product, issues will occur that require to be resolved via a support call. This section
shows how to most efficiently pass information back to HADSL

22.1. The Log Database


The Log database logs all system and user events, and allows you to quickly see more information around a
particular issue.
Upon opening the log database, the “Miscellaneous logs” view is shown, showing all users and servers. The
“Errors” column shows the number of unhandled errors that has been produced by this particular user or
process.

22.2. Mailing Log Documents to Support


You can select one or more documents from this list, and mail them to the Logs@hadsl.com mailbox. This
packages up all selected documents in DXL format, and eMails them from your account to our
logs@hadsl.com mailbox. They are unpacked, and put pack in log file format.
HADSL never put user or certifier passwords in log documents, so they are perfectly safe to eMail to us.
For instance, two documents are selected. Clicking on the “Send Selected..” button will send these two
documents to our support log database.

22.3. Document types within the Log Database


There are two main document categories in the log database – log events, and error events.
 Log events (controlled by the Configuration Profile, Admin Settings tab) logs information on every
process.
 Error events are “memory dumps” caused when any particular program does not handle an error in a
controlled manner.
This log document, generated by a user interaction, shows a fatal error in Red, with an asterisk at the start of
the line.
This entry shows a server-generated log entry with a run-time error (in this case, the error is not in red, as
LotusScript does not allow colour coding of Rich Text items in a schedule agent). The Asterisk still appears at
the start of the line.
This is the second type of log document – a memory dump of all system variables during an unhandled error.
These should be mailed back to logs@hadsl.com if they occur.
This performs the software equivalent of an “NSD” dump, and shows us all objects in memory.

22.4. Raising a support call


After purchasing FirM from HADSL, you
will be issued with a username and
password to log into our web site –
http://www.hadsl.com.

Once logged in, you should navigate


(via the left-hand toolbar) to the
“Software Problem Report” (SPR)
database. When opened, you should
see:
Click on the “Open SPRʼs” to view the open SPRʼs that your company has raised.
Click on “Create new SPR” to create a new Software Problem Report:
A support representative from HADSL will contact you on the same business day.

FirM Administration Manual v3.0 © 2009 HADSL


3 0 T R O U B L E S H O O T I N G & S U P P O R T PA G E 135 O F 145

22.5. Known Issues


This section lists known configuration and installation issues.

22.5.1. AdminP Database


AdminP – do NOT enable “dont support specialised response hierarchy”. This
setting switches off internal support in LotusScript for Response documents.
Response documents are an integral part of AdminP processing and causes ALL
AdminP processes to fail.
FirM manifests this by never being able to find successful AdminP responses to
AdminP requests that FirM generates. Requests appear to never process.

22.5.2. This Platform has a fatal code-page issue


“This Platform has a fatal code-page issue” means that this platform does not properly support ASCII
characters above 127. This error will appear at the top of a “log” report from FirM at the start of a FirM
scheduled agent processing run, and prevent FirM from processing requests.
Red Hat Enterprise v4.0
To fix this issue in Red Hat Enterprise v4, edit the file /etc/sysconfig/i18n
LANG="en_US"
SUPPORTED="en_US.UTF-8:en_US:en"
SYSFONT="latarcyrheb-sun16"
and change the “Lang=” line to “en_US”. This is especially true if this line contains en_US.UTF-8, as Red Hat
linux UTF-8 support appears to be sub optimal. More information is available on this page: http://cc.jlab.org/
services/linux/faq.html
Windows XP
On the bottom right hand side of your taskbar, whilst your Lotus Notes client is open, select a language code
page that does not give this error, such as “EN”.

FirM Administration Manual v3.0 © 2009 HADSL


3 1 F I R M D ATA B A S E S PA G E 136 O F 145

23. FirM Databases


FirM is composed of a number of Lotus Notes databases. These databases are discussed in detail here.

23.1. Request Processor


The core engine of FirM. This contains:
 All configuration and profile documents
 All requests

23.2. Log Database


An application-specific log database that details all activity performed by both servers and users.
See the section titled “The Log Database” on page 149 for more information.

23.3. Extended AdminP processor


An extension to AdminP that allows manipulation of databases on remote servers.
Extended AdminP should be replicated to all servers upon which you wish to manage User and/or
Applications.
It has a setup and profile dialog – choose “System Profiles” and then “Extended AdminP Setup”. Fields
defined are:
 “Servers to run on”. You can choose “*” meaning that the Extended AdminP agents will run on all
servers upon which there is an ExAmp replica, or give a list of servers (or groups or servers).
 “Servers NOT to run on”. This allows you to easily exclude zero or more servers from the list defined
above.
 “Report Faults to”: Provide a list of FirM administrators who should be notified upon critical error.
Extended AdminP also provides a “heartbeat” function – every time the agents run on the remote servers,
they update a server specific profile document. This profile document is then replicated back to the main
processing server.

23.4. Group Registry


A reference database for group ownership and responsibility. This maintains the relationships
between Groups and their profiles. This registry is populated by the Group Import agent.
Each group defined in the registry can be managed by FirM. The Administrator may modify group references
in this database whilst troubleshooting.
Fields defined on the “Ownership” tab are:
 “Name” – the group name
 “Type” – the type of the group.
 “Domain” – the name of the Lotus Notes domain that this group exists
 “Profile” – the System Group Profile associated with this group.
 “Owner/Sponsor”. The person who owns this group and may delete it.
 “Managers” – a list of Group Managers
 “Administrators” – a list of people who are allowed to add and remove group members.
 “Group Status” - The status (within FirM) of the group.
Fields defined on the “Details” tab are:
 “Is this a spanned group”. If the group has one or more sub-groups, this is set to “yes”.
 “Force Owner Approval for Mgmt Requests”. Set this to “yes” if the group owner requires to see and
authorise all group requests.
 “Group Created Date”. The date that the group was created.
 “Group Deleted Date”. If set, the date the group was deleted.
 “Group Expiry Date”. If set, the date the Group Expires

FirM Administration Manual v3.0 © 2009 HADSL


3 1 F I R M D ATA B A S E S PA G E 137 O F 145

 “Report Unauthorised Changes to this group”. If set, FirM Group Monitoring will detect changes
made outwith FirM, and report these changes to the group owner.
 “Prohibit all FirM Management of this group”. This allows you to define this group within FirM but
prevent FirM from ever changing this group. This may be useful for very high-security applications.

23.5. Monitored Group Shadow Repository


A backup Group repository for tracking group changes. FirM Group Monitoring populates and
maintains information in this database.

23.6. Certifier Repository


Encrypted storage for system certifiers. A single certifier has the following fields defined:
 Name – the name of this certifer in abbreviated, hierarchical format.
 A description, if provided
 Document Readers – you may choose to restrict further who has access to this document.
 Certificate – the rich text field containing the certificate.
 Certificate Key Name. The name of the private encryption key used to encrypt this document.
 Certificate File Name. The file name of the certificate Key.
 Certificate Key strength – either International or Global
 Alternative Hierarchy and Alternative Language. If Alternate Language support is set up, these are
populated with this certifier keys alternative languages.

23.7. Password Repository


The encrypted passwords of certifiers and user Ids.

A password document has the following fields defined:


 Type – the type of password
 Name – the full name of the object for this password.
 Previous Names – if this person changed their name- the previous names will be listed here.
 Description – you may put a textual description of this documentation
 Password (text only). Note that you have to have edit-mode and then check the “show password”
checkbox to view or edit this password.

23.8. ID Repository
An encrypted repository containing all user IDs created in FirM.
User ID's are automatically created in this database by FirM when new users are created.
This database can also be used to store other ID files – such as server ID's, encryption keys and so forth.
An ID document has the following fields defined:
 ID Type
 Status – active or deleted.
 Name – the full name of the user object for this ID
 Previous names – if the user has been renamed, this field will contain a list of previous names.
 Description – you may enter a textua description of this ID document.
 Document Readers – you may further restrict who has access to this document by defining reader
names in this field.
 ID File – a rich text field containing the ID file
 Encryption Key Name – the name of the encryption key used to encrypt this document.
 ID Strength – Global or International
 Expires – the ID expiration date
 Allow ID files to be resent. You may set this to “no” to prevent this ID file being sent out as part of a
“User Resend User ID and Password” request
FirM Administration Manual v3.0 © 2009 HADSL
3 1 F I R M D ATA B A S E S PA G E 138 O F 145

 Comments – used to record system level information about this ID file.

23.9. ESCROW Database


The ESCROW database gives the administrator a convenient mail-in database for collecting modified User
ID's as part of the ID recovery process.

23.10.Audit Repository
Stores a full audit history of actions performed by the system.

23.11.Archive Repository
Contains an archive of all completed and unsuccessful requests.

23.12.Billing Database
Each FirM transaction can be configured to create billing transactions, which can help recharge costs within
your Domino environment.

23.13.Deleted Records Database


Storage for all documents deleted by the system. When users are deleted by FirM, for instance, their person
documents are copied to this database.

23.14.Application Monitor
A list of all Domino applications in your environment, highlighting ACLs and ACL changes

23.15.Application Usage Log


A list of all application usage events in your environment.

FirM Administration Manual v3.0 © 2009 HADSL


A P P E N D I X A - T H E A D M I N P P U S H A R O U N D A G E N T PA G E 139 O F 145

24. The AdminP Push around Agent


This chapter is only of relevance to those environments that:
 Have multiple Notes domains with individual admin4.nsf databases.
 Only process FirM transactions in one of those domains.
 Require AdminP requests to be processed in the other domains.
 Do not wish to use the Lotus Domino ʻCross-Domain AdminPʼ functionality.
The FirM processor incorporates an agent which, on a scheduled basis:
 opens up each domainʼs admin4.nsf databases
 Establishes which transactions need to be copied to any other domainʼs admin4.nsf databases.
This chapter outlines this agentʼs functionality and setup.

24.1. Overview
In order to illustrate how this agent works, consider an environment where there is:
 One administration domain – called ʻAdminʼ.
 One production domain – called ʻProductionʼ
 One test domain – called ʻTestʼ.
All relevant transactions created in the ʻAdminʼ domain must be copied to the relevant other domain, i.e.
ʻProductionʼ or ʻTestʼ. These transactions also may spawn other transactions which need to be copied
around.
Consider a ʻRename in Address Bookʼ AdminP operation. This is initiated with a
ʻ8ʼ = ʻInitiate Rename in Address Bookʼ operation. This AdminP request then has to be copied into the
relevant admin4.nsf database so that it can be processed and accepted by the userʼs home server. When
the user accepts this request, then, at least, the following requests are generated:
ʻ1ʼ = ʻRename in ACLʼ
ʻ5ʼ = ʻRename in Address Bookʼ
ʻ20ʼ = ʻRename in Reader/Author Fieldsʼ
Each of these requests may then have to be copied around the environment into other domains to update
that user name in ACLʼs, names fields on documents in databases, etc..
So, considering this rename operation, we may wish to push transaction number ʻ8ʼ from the ʻAdminʼ domain
to the ʻProductionʼ domain, and then pull transactions 1, 5 and 20 from the production domain back in the
ʻAdminʼ and ʻTestʼ domains.

24.2. Configuration of AdminP Push around Agent

24.2.1. System Configuration Variables


The push around agent is configured using ʻSystem Configurationʼ variables. These are simple documents
located the Tools ʻSystem Viewsʼ, ʻSystem Variablesʼ which allow the FirM administrator to override default
system behaviour.

N.B. Other than the push around agent configuration, no other variables should be changed unless
instructed to do so by the FirM Support team.

24.2.2. Push around Rules


Each domain can have one or more push around rules associated with it and each of these rules can dictate
which other domains this particular AdminP will be copied to.
The general format for this rule is:
ʻAdminPPusharound_<SOURCEDOMAIN>_<RULENUMBER>=<TRANSACTION>,<DOMAIN>,
[<DOMAIN>,…]
Where:
 SOURCEDOMAIN is the domain where the request is copied from

FirM Administration Manual v3.0 © 2009 HADSL


A P P E N D I X A - T H E A D M I N P P U S H A R O U N D A G E N T PA G E 140 O F 145

 RULENUMBER is a two digit number starting at ʻ01ʼ, and is used to differentiate rules. Once the
push around agent finds that a rule number is missing for a particular domain, the agent will assume
that the rules have been exhausted for this domain. It is therefore important to number your rules
uniquely and sequentially starting at ʻ01ʼ, then ʻ02ʼ, etc..
 TRANSACTION is the AdminP Request transaction number.
 DOMAIN is the target domain to which this AdminP request should be copied. There are also two
special keywords that can be used instead of the domain name:
 The string ʻ<ALL>ʻ means copy this request to ALL other domains.
 The string ʻ<TARGETDOMAIN>ʼ means that the push around agent will attempt to find this
object and only copy it to the relevant target domain.
Multiple domains can be specified, separated by the comma character ʻ,ʼ.

24.2.3. Push around Rule Examples:


 AdminPPusharound_ADMIN_01=5,Production
 This is rule number ʻ01ʼ for ʻAdminʼ domain. It instructs the push around agent to copy any
AdminP request number ʻ5ʼ to the ʻProductionʼ domain.
 AdminPPusharound_ADMIN_02=10,<TARGETDOMAIN>
 This is rule number ʻ03ʼ for the Admin domain. It instructs the push around agent to copy the
AdminP Request number ʻ10ʼ to the target domain relevant for the user mentioned in the
AdminP request. The push around agent looks-up this user name in the directories to determine
the relevant target domain.
 AdminPPusharound_ADMIN_03=18,<TARGETDOMAIN>,Test
 This is rule number ʻ03ʼ for the Admin domain. It instructs the push around agent to copy the
AdminP Request number ʻ18ʼ to the target domain relevant for the user mentioned in the
AdminP request and also to the ʻTestʼ environment (if this is different). The push around agent
then looks-up this user name in the directories and establishes the relevant target domain. This
type of rule is useful to reflect ʻProductionʼ environment changes in the ʻTestʼ domain, for
instance.

FirM Administration Manual v3.0 © 2009 HADSL


A P P E N D I X B - I N T E R FA C I N G W I T H F I R M PA G E 141 O F 145

25. Interfacing with FirM


FirM has been built from the ground up to be extensible. You can interface FirM with your own Lotus Domino
environment.

25.1. Triggering your agents from a FirM process


To trigger your own agents from any process within FirM,
 Navigate to the System Profiles configuration tab, and select “System Agent Trigger Profiles.
 Click on “Create a new Profile”
 Select the transaction or “trigger” that you wish to act upon
 Select the trigger type – “Success” means that the transaction was successful.
 Enter the name of your database
 Enter the name of your agent.
Please note that from v2.4 onwards, the agents are passed copies of the request documents, not the
documents themselves. This prevents any uncontrolled changes to the requests.
You can of course create these agents in the FirM processing database itself – but please remember to
enable the flag 'Deny Design Refresh', in order to preserve these agents when FirM is next updated!
An example agent trigger agent is shown below. This Agent trigger actually uses some FirM logging
interfaces, and merely lists all the fields on the document that is passed to it.
(Note that if you choose to use the FirM methods in this manner, then you will have to set Agent Security to
at least level 2)
Function TestHarnessAgentTrigger()
Dim IMF As IMFactoryClass
Set IMF = New IMFactoryClass("", "")
Dim sSession As New NotesSession
Dim dbThis As NotesDatabase
Set dbThis = sSession.CurrentDatabase
Dim A As notesAgent
Set A = sSession.CurrentAgent
Dim docParam As NotesDocument
If (A.ParameterDocID <> "") Then
Call IMF.logVerboseMsg( _
"Agent trigger was called with NoteID: " + A.ParameterDocID)
Set docParam = dbThis.GetDocumentByID( A.ParameterDocID)
Dim itm As NotesItem
Forall thisItm In docParam.Items
Set itm= thisItm
Call IMF.logVerboseMsg(" " + itm.Name + " = " + itm.Text)
End Forall
Else
Call IMF.logVerboseMsg( _
"Agent trigger was called without a parameter ID")
End If
End Function

25.2. Using the CSV interface programmatically


This section is intended to document how the Federated Identity and Resource Manager (FirM) can be
extended, by allowing customers to inject new requests pro grammatically.
It should be noted that this interface is quite simple, and allows requests to be built as specified in the CSV
interface. For more information on the CSV interface see section 20 - “The CSV interface”.
A more complex, full API allows full interaction with FirM, and is used to build fully-featured GUI's in Lotus
Notes and HTML clients.

25.2.1. CSV Introduction


In order to use the CSV LotusScript interface, some background description is required.
A "Comma Separated File" is a text file, typically generated by spreadsheets. Usually, the first row (the
"header row") defines keywords, and second and subsequent rows define data per record.
For instance:

FirM Administration Manual v3.0 © 2009 HADSL


A P P E N D I X B - I N T E R FA C I N G W I T H F I R M PA G E 142 O F 145

"Transaction", "TransactionProfile", "UserName"


"UDI", "User Disable", "Bill S Buchan/HADSL"

is a fairly simple, complete example of a CSV file. (I've added the <TAB> character between columns to help
differentiate columns -these are not required.)
The FirM CSV interface allows you to import one or more transactions, of any kind, and convert them into
valid FirM transactions (should they pass validation and testing). This means that the CSV interface has to
use the header fields to establish what the data means. This also means that the columns can be in any
order
All currently supported transaction types and field definitions are listed in the FirM administration manual.
In some instances, some fields may contain more than one logical value. In this case, separate the values
WITHIN the data field with a semicolon character. For instance, this example has two separate names in the
same data field. This will be converted into a multi-value field by the interface.
..., "MembersToAdd", ...
..., "Joe Bloggs/Acme; Fred Bloggs/Acme", ...

25.2.2. Programmatically interfacing using the CSV interface


Using the CSV interface, the programmer has to:
 Create a string array, defining the column headers that he shall use
 Create one or more strings with data values.
Note: If cutting and pasting this example, please be careful that the double-inverted comma characters used
are set to the correct ones, as the word processor manual used in creating the manual often replaces them
with more sophisticated but incorrect versions, which then cannot be imported.
For example, (taking the example above), the programmer would:

dim Header() as String


redim Header(2) ' Remember, arrays start at ZERO
Header(0) = "Transaction"
Header(1) = "TransactionProfile"
Header(2) = "UserName"

dim dataLine as String

' Note that I'm using the BAR character - | - to define


' the start and the end of the string, in order to preserve
' the double-inverted-commas within the string
' For clarity, I've left in the TAB characters at the start,
' and between each column. The TAB characters are not required.

dataLine = | "UDI", "User Disable", "Bill S Buchan/


HADSL" |

The important note is that the data line fields have to correspond to the same order as the
header fields.
Creating an Agent to programmatically create requests
There now follows an example LotusScript agent demonstrating the CSV interface.

(options)
option public
option declare
Use "class:IMFactoryClass"
Use "class:IMCSVImport"

sub initialise()
dim IMF as variant

' Items in GREEN in this listing illustrate the calls to the FirM API. All other
' lines are normal Lotusscript operations.

' Instantiate a single copy of the FirM factory class.


' If this agent is created in the FirM request processor database, then pass two
' empty strings meaning "use the current database for profiles".
FirM Administration Manual v3.0 © 2009 HADSL
A P P E N D I X B - I N T E R FA C I N G W I T H F I R M PA G E 143 O F 145

' If this agent has to be in another database, then ALL script libraries from the FirM
' Request processor have to be copied to the new database, and
' the path to the FirM request processor passed to the IMFactoryClass
' create as a server, and a filepath.
Set IMF = New IMFactoryClass("", "")

' Create our data for this transaction


dim Header() as String
redim Header(2) ' Remember, arrays start at ZERO
Header(0) = "Transaction"
Header(1) = "TransactionProfile"
Header(2) = "UserName"

dim dataLine as String

' Note that I'm using the BAR character - | - to define


' the start and the end of the string, in order to preserve
' the double-inverted-commas within the string
' For clarity, I've left in the TAB characters at the start,
' and between each column. The TAB characters are not required.

dataLine = | "UDI", "User Disable", "Bill S Buchan/


HADSL" |

' Now create a new CSV object with this line.


Dim thisCSV As Variant
Set thisCSV = New IMTestCSVLine(IMF)

' For each "data line",


Call thisCSV.addLine(dataLine, Header)

If Not thisCSV.applyAsRequest(IMF) Then


Print "Request Failed:"
Dim E As Variant
e = Split(thisCSV.getCSVLineErrorMessage(), Chr(10))

' Now print out the errors that FirM has returned to us, one line at a time.
Forall thisError In E
Print thisError
End Forall

' The following line writes to the FirM log file, flagging the
' message as an error
Call IMF.cLog.Write(LOG_LEVEL_ERROR, "Initialise: Failed to apply CSV line")

Else
Call IMF.cLog.Write(LOG_LEVEL_VERBOSE, "Initialise: Applied CSV line")

' This call flags the current log document with our transaction type.
Call IMF.cLog.setCurrentRequestSummary("UDI")
End If

end Sub

25.3. Create FirM requests from your own programs.


FirM includes a full LotusScript Application Programming interface (API). Documentation for this API is
available on request from HADSL. FirM itself uses this interface to create its own user interface, and
therefore anything that can be done from the user interface can be enabled via the API.
This API allows you to create and monitor requests in FirM as if the requests were created using a Notes
client. This is useful in enabling existing processes to create FirM requests to manage your Domino
environment.

25.3.1. Example agent


Add the class library ʻclass:IMFactoryClassʼ to your existing lotusscript code by including the statement:
use ‘class:IMFactoryClass’
in the ʻoptionsʼ section of your code Initialise the FirM classes by creating a new instance of the
IMFactoryClass object:
dim IMF as new IMFactoryClass(strTargetserver, _ strTargetDatabase)

FirM Administration Manual v3.0 © 2009 HADSL


A P P E N D I X B - I N T E R FA C I N G W I T H F I R M PA G E 144 O F 145

Note that you have to pass the name of the target server, and the database path name, of the IMFactory
ʻrequestsʼ database for the IMFactory object to successfully construct itself.

If you choose to put your agent in the FIRM database itself, you can replace the servername and database
name with a blank string:
dim IMF as new IMFactoryClass(””, ””)
Check, by calling the IMFactoryClass::isFactoryValid() that the factory has initialised correctly
if (not IMF.isFactoryValid()) then
msgbox ‘The factory failed to initialise’
exit function
end if
Create a new request by instantiating a new IMRequestClass object
dim IMR as Variant
set IMR = IMF.getRequestClass()
Set the request Type and who the requestor is
Call IMR.SetRequestType("UCR")
Call IMR.setRequestorAsMe()
Set the User Create profile name you wish to use. This is the name of an existing Profile for this type of
transaction:
call IMR.setProfile(‘My User Create Profile Name’)
Set the new request type, and gain an instance of the sub-request class type by:
dim IMUCR as Variant
set IMUCR = IMR.getRequestObject()
Now set the data for the sub-request class type. In this instance, we're setting up a User Create Request
Call IMUCR.setFirstname("Derek")
Call IMUCR.setMiddleInitials("D")
Call IMUCR.setLastName("Test ")
request Check to see if this request is valid:
if (not IMR.isValidRequest()) then
msgbox ‘The request failed validity check. ‘+_
‘Check the Request Log database for more information’
exit function
end if
And check that we're authorised to submit this document
if (not IMR.isAuthorised()) then
msgbox ‘You are not permitted to submit this request’
exit function
end if
Now that we're sure that its a valid, authorised request, lets write it out to our blank request document:
dim docTarget as NotesDocument
call IMR.getNewRequestDocument()
Write the request to the document
call IMR.WritetoDocument(docTarget)
Sign and save the request
call IMR.SignAndSaveDocument()
That completes the creation and signing of a request document. The back-end process will now revalidate,
and re-authenticate the request before processing it.

25.4. Creating Transactions Using Web Services


Our web service interface - used by our Flex-based web client - can also be used to input transactions
directly into FirM. We use exactly the same data definition and interface as we do in our CSV file import -
and so the same field definitions can be used.

In order to interface with the web service, you must


 Use a username and password that can authenticate to the Domino server as a FirM requester.
 Call the Web service defined as ʻRichClientʼ. So the URL would look like

http:// <yourserver> / <directory> / firmRequestProcessor.nsf/RichClient?WSDL

FirM Administration Manual v3.0 © 2009 HADSL


A P P E N D I X B - I N T E R FA C I N G W I T H F I R M PA G E 145 O F 145

Where you need to replace <yoursever> with the name of the primary FirM processing server, and
the <directory> with the name of the directory that the FirM requests are stored.
The strings defined in the request are of the form:
field=value
Where field is the CSV column name, and value is a string representation of the value.

The web service then posts the request, and attempts to process it, before returning the status of the request
to the calling process.

This means that the Web Service call may take several seconds to complete.

FirM Administration Manual v3.0 © 2009 HADSL

You might also like