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. Groups - Project


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. Groups - Custom Group Types


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 "20210101" -end "20211231"
}

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 Monitor.
  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.
  addgroup <type> <group>              - Add a group of the specified type.
  addgrouptype <membershipType> <type> - Add a group type based on the specified
                                         membership type (user or host).
  renamegroup <old> <new>              - Rename a group.
  renamegrouptype <old> <new>          - Rename a group type.
  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.