Project and Group Management

For reporting purposes, users can be grouped to keep track of projects, departments, or other organizational units.

By default, Monitor supports one group, referred to as "project", for each checkout record. The project is assigned to each checkout and shows up in all current and historical reports for checkout data. The value of the project is "none" unless otherwise configured per the instructions below. The value can also be specified at the command line by the checkout user. This allows for more granular reporting of projects, using the LM_PROJECT environment variable, the current UNIX group, or a specified value. For more information on this capability, see Project Tracking.

If grouping by organizational units other than "project" is required (for example, departments or sites), custom groups can be defined. Custom groups are comprised of time-based memberships for users. This allows for fine-grained control over users and their groups. Group memberships can be defined via the web interface, configuration file, or they can be driven by LDAP. See below for more details on defining custom groups and memberships.
Note: Project assignments are currently not supported for denial data. Custom group memberships apply for all data.

Web-based Project Configuration

To define project assignments via the web interface, click on the Admin tab and navigate to the Groups page:


Figure 1. Project Administration Page
The default sub-page is for managing project assignments. Projects can be defined, along with the users that belong to them and/or associated UNIX groups (if Monitor is running on a UNIX-based platform). If using UNIX groups, and a user is found in more than one group, the first group appearance is honored.
Note: Configuring projects via the web interface only establishes the configuration. One of the two assignment methods below will need to be performed in order for the account definitions to be activated.

Web-based Custom Group Configuration

Custom accounts and types can be managed by visiting the appropriate sub-page of the accounts management page above. Each custom account must be of a certain type. To define a type, simply enter its name. To rename an existing type, select it from the list and type in the new name.


Figure 2. Custom Group Type Administration Page
Once a type has been created, the type will show up in the custom group sub-page. From here you can create groups for each type that has been created.


Figure 3. Custom Group Administration Page
Once a custom group has been created, it can be edited, deleted, or renamed. Edit the group to add or remove members, as well as select a member to edit its memberships.


Figure 4. Edit Custom Group
To view edit a member's memberships, select the user from the drop-down menu and choose the edit function. A form containing a list of existing memberships will appear that can be used to add, update, or delete membership periods.


Figure 5. Edit Membership
Note: Configuring custom groups via the web interface only establishes the configuration. One of the two assignment methods below will need to be performed in order for the group definitions to be activated.

File-based Configuration

Both projects and custom groups can be defined via configuration file as well. This enables an administrator to keep an accurate list of assignments for all users that is easily maintained. The configuration files are:
  • licmon.swd/config/accounts.cfg - Hand-written configuration file.
  • licmon.swd/config/accounts.web.cfg - Configuration file that is generated by the group administration page, not to be hand-edited.

The administrator must take care that there are no conflicts in the assignment of users to projects and groups between the definitions found in both files. If conflicts are detected, the first assignment is honored. It is recommended to use one approach for all definitions to avoid conflicts altogether. The configuration files are used for the first two group management methods described below.

Example Configuration: $VOVDIR/etc/config/lm/accounts.cfg
#
# Static project definition
# These definitions are read by "ftlm_accounts setliveall", which is called once
# every hour by the "live_update_accounts" liveness script.
#
set FTLM_ACCOUNT(GPS_CHIP) {
    joe
    bob
    sue
}

#
# Project defined via Unix group, first group encountered for a user is honored
# These definitions are read by "ftlm_accounts setliveall", which is called once
# every hour by the "live_update_accounts" liveness script.
#
set FTLM_UNIXGROUPS(GPS_CHIP) {
    gps
}

#
# Static custom group definition
# These definitions are read by "ftlm_accounts loadfromfile", which is called
# once every hour by the "live_lm_update_memberships_from_file" liveness script,
# and can be used to define user- and host-based group types.
# These definitions establish a group membership starting at the time the file
# is read and ending 10 years later by default. Use -start and -end to specify
# other times.
#
# Time formats supported are:
#     10-digit Unix timestamp
#     YYYYMMDD#     YYYY-MM-DD
#     Full date as shown in "ftlm_accounts -showmemberships" output
#
#         TYPE          GROUP    USERLIST   OPTIONS
UserGroup "department"  "GPS" {
#          USERLIST   OPTIONS
    Member "joe"
    Member "bob mark" -start "20100101" -end "20101231"
}

HostGroup "Site"        "San Jose" {
    Member "sjhost1 sjhost2"
}

#
# Custom group definition via NIS maps
# Define NIS data to use for populating group memberships in the LM DB.
# These definitions are read by "vovnis_update_memberships", which is called
# once every hour by the "live_lm_update_memberships_from_nis" liveness script.
# These definitions establish a group membership starting at the time NIS is
# is queried and ending 10 years later. Formats are:
#
# set NIS(<customGroupName>,map)    <nisMapName>
# set NIS(<customGroupName>,column) <columnNumber>
# set NIS(<nisMapName>,usercolumn)  <columnNumber> (default is 1 if unspecified)
#
set NIS(location,map)      sites
set NIS(location,column)   2
set NIS(group,map)         organizations
set NIS(group,column)      4
set NIS(department,map)    organizations
set NIS(department,column) 5

Project Configuration Activation

Once project and/or custom group definitions have been created, they must be activated in order for projects to be applied to new checkouts and for custom groups to be populated in the Monitor database.

The ftlm_accounts utility can be used to manually manage projects. The usage syntax for the utility is:

ftlm_accounts: Usage Message
  
  Utility to show and manage user project and custom group definitions.
  
  USAGE:
  
    ftlm_accounts [OPTIONS] <ACTION> ....
  
  PROJECT ACTIONS:
  
    showdb                    - Show ALL project assignments found for each user
                                in the database. For users with no project
                                assignments, the default of "none" is printed.
    autofill                  - Automatically assign projects to users by
                                searching for previously assigned projects. The
                                most frequently used project is assigned. If
                                none are found, a warning is printed.
    setdb <users> <project>   - Assign a project to one or more users. If a
                                user is not already in the database, an error is
                                printed for that user. To clear all project
                                assignments for the specified user(s), pass ""
                                as the <project>.
    reset                     - Clear all project assignments for all users.
                                WARNING: This is destructive and can take a
                                while.
    showlive                  - Show project assignments that are to be applied
                                to new checkouts as they occur.
    setlive <users> <project> - Assign a default project to one or more users
                                for checkouts that will be detected by
                                LicenseMonitor.
    setliveall                - Assign a default project for all live checkouts
                                based on the definitions in the project
                                configuration.
    clearlive                 - Clear all live project assignments.
  
  PROJECT OPTIONS:
  
    -origin <N>               - Restrict to given origin.
  
  CUSTOM GROUP ACTIONS:
  
    addmembership                        - Deprecated.  Use addusermembership.
    addhostmembership                    - Add a host to a host-based custom
      <type> <group> <host>                group. If overlap is detected, an
      <startDateSpec> <endDateSpec>        extension to the existing membership
                                           is made.
    addusermembership                    - Add a user to a user-based custom
      <type> <group> <user>                group. If overlap is detected, an
      <startDateSpec> <endDateSpec>        extension to the existing membership
                                           is made.
    backdatememberships                  - Backdate the start time of
      <TIMESPEC> [type] [group]            memberships that belong to the
                                           optionally specified type or
                                           type/group pair. If no type is
                                           passed, all memberships will be back-
                                           dated. TIMESPEC may be specified as a
                                           number of seconds or as a time
                                           abbreviation such as 1m, 1h, 1d,
                                           or 1w.
    deletegroup <type> <group>           - Delete a group.
    deletegrouptype <type>               - Delete a group type.
    deletemember                         - Delete all memberships for the member
      <type> <group> <member>              and group specified.
    deletemembership                     - Delete a specific membership for the
      <type> <group> <member>              member and group specified. Times
      <startDateSpec> <endDateSpec>        must match an existing membership
                                           exactly.
    dumpmemberships                      - Dump existing memberships in config
                                           file format.
    loadfromfile [external file path]    - Load membership information from
                                           configuration file. Default file is
                                           licmon.swd/config/accounts.cfg.
                                           Optionally, an external file may be
                                           specified.
    loadfromoptions                      - Load membership information from
      [external file path]                 FLEXlm options file. Specify a group
      <groupType> <optionsGroupList>       type and the options file group(s)
                                           that will be used to populate a group
                                           by the same name. To use all groups,
                                           specify "all".
                                           A user cannot be a member of more
                                           than one group of the same type, so
                                           make sure different group types are
                                           specified for each group that
                                           contains a common user.
    showgroups <type>                    - Show custom groups of specified type.
    showgrouptypes                       - Show custom group types.
    showmembers <type> <group>           - Show group members.
    showmemberships                      - Deprecated. Use showusermemberships.
    showhostmemberships <host>           - Show group memberships for the
                                           specified host.
    showusermemberships <user>           - Show group memberships for the
                                           specified user.
    updatemembership                     - Update a membership. Times must match
      <type> <group> <member>              an existing membership exactly. This 
      <oldStartDateSpec> <oldEndDateSpec>  is normally used to shorten a
      <newStartDateSpec> <newEndDateSpec>  membership due to how the 
                                           addmembership action creates
                                           extensions upon overlap.
  
  ABOUT CUSTOM GROUP DATESPECS:
  
    Times may be specified in the following formats:
  
    10-digit Unix timestamp
    YYYYMMDD
    YYYY-MM-DD
    Full date shown in "ftlm_accounts -showmemberships" output
  
    Examples:
    ftlm_accounts deletemembership location "San Jose" joe 1293655667 1293655668
    ftlm_accounts deletemembership location "San Jose" joe 20100101 20110101
  
  COMMON OPTIONS:
  
    -f                        - Force flag (use with reset to avoid dialog).
    -v                        - Increase verbosity.
    -h                        - This help.
  
  EXAMPLES: DATABASE MANIPULATION:
  
    % ftlm_accounts setdb "john mary dan" "ChipA"
    % ftlm_accounts reset
    % ftlm_accounts -f reset
    % ftlm_accounts autofill
  
  EXAMPLES: NEW CHECKOUTS:
  
    % ftlm_accounts showlive
    % ftlm_accounts setlive "john mary dan" "ChipA"
    % ftlm_accounts setliveall
    % ftlm_accounts clearlive
  
  SEE ALSO:
     ftlm_lmproject
  

Manually Set the Project for Live Checkouts

By using ftlm_accounts with either the setlive or setliveall actions, new checkouts can be assigned to project of your choosing.

The setlive action requires a user and project specification, whereas the setliveall action uses the configuration files to determine the project assignments. All live checkout assignments are preserved when the checkouts are loaded into the database.

Automatically Set the Project for Live Checkouts

For automatic updating of the project definitions for live checkouts, a periodic job is available. The Configuration Information page can be used to configure this task. Refer to the documentation for the UPDATE_PROJECTS task for more details.

Manually Annotate the Database with Project Information

It is possible to perform a post-processing on the database to modify the project for each checkout. This is required if the project configuration was not created during the initial Monitor installation. Database post-processing is also handled by the ftlm_accounts utility. This process may take a while depending on the size of the database.

The setdb action sets the all checkouts in the database to the specified project for the specified user.

The autofill action automatically fills-in projects for all checkouts that have no project assigned. The information for the automatic filling is derived from three sources:
  • The licmon.swd/config/accounts.web.cfg file.
  • The licmon.swd/config/accounts.cfg file.
  • If a user is not included in any of the projects defined in the configuration files, the utility then looks at the database information itself for previous assignments of projects to the user. If any are found, it picks the most frequently used project. Otherwise, a project of "none" is used.

Custom Group Configuration Activation

Manually manage custom groups
The ftlm_accounts utility is also used to manage custom groups. The utility can be used to show, create, update, and delete groups, group types, and group memberships. Memberships can be specified as arguments to the script or a map file can be used. See the usage syntax above for details on using these functions.
Custom groups can driven by LDAP. In this scenario, the vovldap_update_memberships utility is used to extract the data from LDAP, based on the LDAP Integration, and populate it in the database. The utility can also be used to generate a map file instead, which can then be imported using the ftlm_accounts utility. The usage syntax for the vovldap_update_memberships utility is:

vovldap_update_memberships: Usage Message
  
  DESCRIPTION:
      This utility queries an LDAP server to look up configured user attributes
      that are used to define group memberships in the LicenseMonitor
      database. Resulting memberships begin at the time this command is
      executed with durations of 10 years unless otherwise specified. If a user
      has an active membership on one account and becomes a member of a
      different account, the previous membership is terminated and the new one
      begins at the time this command is executed.
  
  USAGE:
      % vovldap_update_memberships [OPTIONS]
  
  OPTIONS:
      -h                   -- This help.
      -duration "timeSpec" -- Specify the duration for the membership
                              definitions.
                              Time specification format is (Xd, Xw, Xm, Xy).
                              Examples: 1d, 5d, 2w, 6m, 1y, 2y.
                              Default duration is 1d.
      -f "output_file"     -- Save output to the <output_file> instead of
                              writing results into the database. The @PROJ_DIR@
                              variable can be used in the <output_file>
                              specification which will be substituted with the
                              full path to the server working directory (SWD).
      -users "a b c"       -- Use specified user list instead of obtaining user
                              list from the database.
      -v                   -- Increase verbosity.
  
  EXAMPLES:
      % vovldap_update_memberships
      % vovldap_update_memberships -f 
                    /home/rtda/licmon/licmon.swd/config/accounts.ldap.cfg
      % vovldap_update_memberships -f @PROJ_DIR@/config/accounts.ldap.cfg
  
Custom groups can also be driven by NIS. In this scenario, the vovnis_update_memberships utility is used to extract the data from NIS, based on the configuration defined in the accounts configuration file (see example above) and populate it in the database. The utility can also be used to generate a map file instead, which can then be imported using the ftlm_accounts utility. The usage syntax for the vovnis_update_memberships utility is:

vovnis_update_memberships: Usage Message
  
  DESCRIPTION:
      This utility queries NIS to look up group members that are used to define
      group memberships in the LicenseMonitor database. Resulting memberships
      begin at the time this command is executed with durations of 10 years
      unless otherwise specified. If a user has an active membership on one
      account and becomes a member of a different account, the previous
      membership is terminated and the new one begins at the time this command
      is executed.
  
  USAGE:
      % vovnis_update_memberships [OPTIONS]
  
  OPTIONS:
      -h                   -- This help.
      -duration "timeSpec" -- Specify the duration for the membership
                              definitions.
                              Time specification format is (Xd, Xw, Xm, Xy).
                              Examples: 1d, 5d, 2w, 6m, 1y, 2y.
                              Default duration is 1d.
      -f "output_file"     -- Save output to the <output_file> instead of
                              writing results into the database. The @PROJ_DIR@
                              variable can be used in the <output_file>
                              specification which will be substituted with the
                              full path to the server working directory (SWD).
      -users "a b c"       -- Use specified user list instead of obtaining user
                              list from the database.
      -v                   -- Increase verbosity.
  
  EXAMPLES:
      % vovnis_update_memberships
      % vovnis_update_memberships -f 
                   /home/rtda/licmon/licmon.swd/config/accounts.nis.cfg
      % vovnis_update_memberships -f @PROJ_DIR@/config/accounts.nis.cfg
  
Automatically manage custom groups
For automatic updating of the custom group definitions from file, LDAP, or NIS, a periodic job is available. The Configuration Information page can be used to configure these tasks. Refer to the documentation for the UPDATE_MEMBERSHIPS_* tasks for more details.

Custom Groups Driven By FlexNet Publisher Options File

Custom groups can be obtained from an options file. This is mainly useful when there are user-locked licenses or reservations to groups defined in the options file. To extract and load these groups and their members into the Monitor database, use the ftlm_accounts utility (see above for usage details). It is important to make sure that the custom group type being specified for the group to extract be unique. For example, for the following user-locked license INCLUDE/GROUP pair in the options file:
GROUP nnu bob joe sue
INCLUDE MATLAB:asset_info=12345 GROUP nnu
An appropriate call for the ftlm_accounts utility would be:
% ftlm_accounts loadfromoptions MLM.opt asset12345 nnu

This is required in case the nnu group is used for multiple user-locked licenses (asset tags). If there is only one usage of the nnu group in the options file, and there is no chance that it will be used with other asset tags in the future, then a more generic custom group type could be used, such as MATLAB-NNU.