Introduction

This System Admin Guide is written and intended for the person filling the role of Installation Administrator, and is most useful after the initial installation is completed.

Refer to the Lifecycle Manager Install Guide for an overview of the hardware and software installation requirements and detailed instructions on installing the base servers and product.

Table of Contents

The following topics are covered in this system admin guide:

General
  1. Administrator Accounts
  2. Admin Console for the Installation Administrator
  3. Commands You Can Run from the Admin Console
Configuring the application
  1. Installation Settings
  2. Configuration Designer
  3. Setting up native LDAP password policies
  4. Setting up group and role support in LDAP
  5. Setting up SSL
  6. LM behind a Load Balancer (cluster)
  7. LM behind a Reverse Proxy/Load Balancer that terminates SSL
  8. CSRF Security for Lifecycle Manager
  9. Update Installation-wide Properties
  10. Single Sign-on (SSO) Install and Configuration
  11. Customize user attributes and LDAP attributes
  12. Full-text artifact search
  13. Customize the com.soa.repository.custom.jar
  14. Customize the Web Page Branding Image (Top Banner)
  15. Customize the Footer for all Web Pages
  16. Customize Home Page Content (Web Browser Application)
  17. Customize Support Center Page
  18. Customize Top Navigation Links (Web Browser Application)
  19. Customize Context Sensitive Help Pages
  20. Using different languages
  21. Deploying custom class files
Start/Stop and Service Packs
  1. Starting and Stopping Servers
  2. Installing Service Packs
Log Files and Logging
  1. Log Files and Logging Levels
Creating Libraries and Import/Export Assets
  1. Creating Additional Libraries
  2. Download assets or upload assets automatically
Other
  1. Database Administration
  2. Backing up and Restoring the Application and Data
  3. Reset System Passwords
  4. Adding a Library User
  5. Super User
  6. Reset a User Password
  7. Saving files in UTF-8
  8. User License Report
  9. Managing Reports

Contact Akana Support for help on any issue or topic that is not covered here, in the Install documents, or any of the applications' on-line help systems.


Administrator Accounts

There are several different and distinct administrator roles that can be assigned to user accounts within the application. All roles are described here in order to provide context for the Installation Administrator responsibilities and required skills as described in this document.

Installation Administrator

This System Admin Guide is written and intended for the users assigned the role of Installation Administrator, also known as the system administrator for this installation. See System Admin Console for information on the UI provided to Installation Administrators. The initial list of Installation Admins is set in the lib.conf file in the {admin.users} property. After the initial installation, the list is maintained by the existing Installation Administrators through use of the Admin Console's Settings page. See the section Update Installation-wide Properties for more details.

Responsibilities of the Installation Administrator generally include these types of activities:

  • Coordinate installation of the base product and service packs with the underlying server sysadmins
  • Creating the initial Asset Library and additional libraries as required
  • Obtaining and reviewing system logs
Library Administrator (also known as the Library Support Account)

Each Asset Library is created with a user account that is authorized to all library administrative roles. This account is designated as the Library Administrator or Library Support Account.

Responsibilities generally include these types of activities:

  • Managing the Library parameters that are configurable (post-Library creation)
  • Managing the Global Definition Template used for the library's Asset definition

Please see the help system available in your Lifecycle Manager web browser application for more information on the Library Administrator role.

Usage Controller

Each Library has one or more users assigned the role of Usage controller.

The responsibilities generally include these types of activities:

  • Create and manage the library group and project hierarchy
  • Manage asset capture (constraint) templates
  • Assign and manage user roles and authorization
  • Create and manage additional items used in the library configuration, such as group profiles, asset views and classification criteria sets.

Please see the help system available in your Lifecycle Manager web browser application for more information on the Library Administrator role.

Project Manager

A Project Manager can perform user management tasks for your library, much like users assigned the Usage Controller role described above. However, the Project Manager role is assigned by project, and the capabilities of the Project Manager is scoped to their own project only.

Each project in a library has one or more users assigned the role of Project Manager.

The responsibilities generally include these types of activities:

  • Create new library users and assign them to the project. This capability can be withheld.
  • Manage group role assignments for project users.
  • Approve asset reuse requests instigated by project users. This capability is optional.

Admin Console for the Installation Administrator

System Admin Console Access

Lifecycle Manager provide access to a number of administrative functions via the System Admin Console. This application can be accessed from within a web browser (from the top navigation bar item called Administration that is available to users who are installation administrators) and also directly by URL as shown in the examples below. Replace the "/lm" in the examples with your context root, as appropriate. The context root is "logiclibrary" for systems that are upgraded from Logidex.

  • http://{web.server.url.host}/lm/admin/mainMenu.do
    • Login: anyone in {admin.users}
    • Password: a password specific to the user in {admin.users}
  • Super user access is only available from the following URL and is meant to be used only when the standard LDAP accounts are not available:
    • http://{web.server.url.host}/lm/application/access/suLogin.do
    • Password: {superuser.password} 

System Admin Console Main Menu

From the system admin console, the Installation Administrator can perform a number of administrative tasks. Here are the items provided in the Main Menu:

  • Execute Command - Selecting this item displays a page where you can enter a command and the applicable command parameters.
    • Some administration commands are documented in this document
    • Other commands may be provided by Akana support on an as-needed basis.
  • Create New Library - Click on this link to display the Create Library page.
  • Create Lifecycle Manager User - [Only valid when using LDAP in Native mode] Selecting this item displays a page where you can create a new LDAP user and assign it to a specific library.
  • Manage Visible Asset Sources - Selecting this item and designating your library from the drop-down list produces a listing of the Visible Asset Sources that are available to your library. A Visible Asset Source is a configuration that causes assets published from an individual library's asset source to be simultaneously published into your library as well. You can use Visible Asset Sources to create a "federated" library configuration with other libraries both in your Lifecycle Manager installation and from a remote Lifecycle Manager installation.
  • Manage Remote Asset Sources - Selecting this item produces a listing of the Remote Asset Sources currently available to your installation. A Remote Asset Source is a connection established to a library that exists on an installation separate from your own. Creating a Remote Asset Source results in the availability of the remote library for the creation of a visible asset source for a library local to your installation. See "Manage Visible Asset Sources" in the previous bullet. A Remote Asset Source entry establishes connection information to the remote library, as well as a polling interval for the update of published asset information between systems.
  • Settings - Click on this link to adjust various installation settings. These settings should not normally be changed after installation.
  • Browse Logs - Click on this link to display the Application Logs page. On this page is a list of logs produced, a means by which to email them to Akana support or any other recipient, and corresponding links to access the logs directly.
  • System Admin and Additional Documentation - This link provides access to the Service Center, where documentation (including this System Administration Guide) is provided.
Visible Asset Sources

Each library consists of two components: the library itself, which contains the published assets, and its associated asset source, where assets are created and edited prior to being published. When assets are published from an asset source into its associated library, you can also designate that a simultaneous publish take place into other libraries as well. The configuration necessary to cause this to take place occurs in the target library and consists of the establishment of a Visible Asset Source for each source library desired. Libraries that share content in this fashion are said to be "federated". Note that content shared in this manner can include reference models as well as assets. Published assets are refreshed in all applicable libraries with each publish from the originating asset source. In cases where the Visible Asset Source entry uses a remote library, the update takes place according to the polling interval established by the Remote Asset Source entry used by the Visible Asset Source.

Create a Visible Asset Source

On the Manage Visible Asset Sources page, selecting your library from the Library drop-down list causes the page to refresh and display a list of all other libraries existing for your installation. If you want to pull assets and models from a visible library into your library, click on the corresponding Selected box. As you do so, there are two important things to consider and choices to make:

  1. Ensure that you select a Responsible User that corresponds to a user account in your library that is associated with the "Reporting Group" you intend. The responsible user's reporting group will:
    1. Be used as the owning group for the assets from this asset source.
    2. Designate the publish template(s) to be used for the assets published from this asset source. The publish template used for these assets can:
      • Provide publish information, such as designation of private artifacts and establishment of asset owner involvement in asset reuse approvals.
      • Automatically establish forum topics for the assets' discussion forums.
    3. Note: the default "Responsible User" account is the account called Repository Application. This is a user account associated with the application itself, not a human user. The Super user account is configured in your web browser application in a fashion similar to other user accounts.
  2. Establish a Classification Criteria Set to use as a stereotype in order to filter the assets published from the Visible Asset Source. By naming a classification criteria set, you cause only those assets that meet the classification criteria of the named set to be included in the publish. Classification Criteria Sets (CCSs) are created and managed by your library's Usage Controller(s) through your web browser application.

See the help system available online in the application for more information on: Classification Criteria Sets, Publish Templates and their association with groups and asset types, asset publish information, Reporting Groups, and Reference Models.


Installation Settings

General Settings

  • Use SSL - If checked SSL will be used for generated URLs and login redirects.
  • Host - The host to use for generated URLs to the application.
  • Port - The port to use for generated URLs to the application.
  • Context Root - The context root the application is hosted on. Changing this does not change where the application is deployed, but is used for generated URLs to the application.
  • Administration Users - A semi-colon separated list of user accounts that have access to the admin pages.
  • Show Library List - If checked, shows a dropdown of available libraries on the login page
  • Default Sort Classifiers - A colon separated list of classifier names that is used for new library default sort classifiers and asset tree hierarchy.

Cache Settings

  • Asset Cache Size - The number of assets to cache in memory.
  • Org Group Cache Size - The number of org groups to cache in memory.
  • User Cache Size - The number of users to cache in memory.

E-mail Settings

  • Host - The SMTP server's host.
  • Port - The SMTP server's port. If not specified, port 25 will be used.
  • Enabled - If checked the libraries will send email. This can be used to temporarily disable email.

LDAP Settings

LDAP is used for authentication, searching for users, and authorization (if group / role based support is enabled). Various LDAP settings are available from the administration console (Settings -> LDAP Settings). This section describes the various settings and their purpose.

  • Host - The hostname of the LDAP server
  • Port - The port of the LDAP server. If this is not specified it will default to 389 for LDAP, or 636 for LDAPS
  • Use LDAPS - If this is checked, LDAPS:// will be used to connect to the LDAP server, otherwise the LDAP:// protocol will be used.
  • Bind DN - The LDAP DN of the user to authenticate with to perform searches. If this is not specified no user will be used to authenticate.
  • Bind Password - The LDAP bind DN's password.
  • Follow Referrals - Referrals are a mechanism to indicate that the entries you are looking for may be located on another server. If this is checked, the application will consult the other server for these entries. This incurs a performance penalty.
  • Native Mode - This should not normally be checked in a corporate environment. This allows the application to make updates to the LDAP server (e.g. create users, set passwords).
User LDAP Settings
  • Base DN - The LDAP DN defining where to start searching for LDAP users.
  • Search Scope - Whether to search all levels below the base DN (Sub) or just the first level (One) for users.
  • Object Class - The LDAP object class representing groups (e.g. 'inetOrgPerson', or 'organizationalPerson').
  • Account Attribute - The LDAP attribute representing the user's account name (e.g. 'samAccountName' or 'uid').
  • MemberOf attribute - The LDAP attribute representing which groups this user is a member of (e.g. 'memberOf').
  • Filter - An additional LDAP filter used to restrict which LDAP entries are considered users.
Group LDAP Settings

Group Settings are optional unless Group / Role mappings are used

  • Base DN - The LDAP DN defining where to start searching for LDAP groups.
  • Search Scope - Whether to search all levels below the base DN (Sub) or just the first level (One) for groups.
  • Object Class - The LDAP object class representing groups (e.g. 'groupOfUniqueNames' or 'groupOfNames').
  • Name Attribute - The LDAP attribute representing the group name (e.g. 'CN').
  • Member attribute - The LDAP attribute representing membership in this group (e.g. 'uniqueMember' or 'member').
  • Filter - An additional LDAP filter used to restrict which LDAP entries are considered groups.

Logging Settings

  • Properties - The logging properties. Normally, this does not need to be changed, except perhaps the logging paths.
  • Logging Level - The level at which logging statements (at or more severe) will be logged.
  • Persist Across Restart - If set, the logging changes will be persisted in the database and will be applied when a server is restarted.

Database Settings

  • Schema Name - The schema name containing the application data (tables, views, etc.). If not specified the default schema of the connecting database user is used.
  • Data Tablespace Name - The database tablespace containing the table data.
  • Index Tablespace Name - The database tablespace containing the index data.
  • Long Tablespace Name - The database tablespace containing LOB (Large Object) data.
  • Temp Tablespace Name - The database tablespace used for temporary data.
  • Schema Updateable - If checked, indicates the schema is modifiable by the database user. This is used to update some dynamic reporting views.

SSO Settings

  • User ID Header - The header containing an externally authenticated (via SSO) account ID. This header name should be set and validated via an external application (normally a web-server plugin).
  • Challenge URL - The URL to direct the user to when they need to provide authentication. By default, this is the application's authentication page.
  • Logout Redirect URL - The URL to direct the user to when they log out. By default, this is the application's authentication page.

Configuration Designer

The Eclipse-based Configuration Designer (CD) plug-in provides library administrators a rich client interface to manage the configuration for their libraries. CD is included in the Repository Client--a standalone, Eclipse-based IDE--or the plug-in may be installed into an existing Eclipse IDE. See the Download Center in your library for installation details. Once installed, administrators create one or more CD projects where each contains the configuration for a library. The following table outlines common administrative functions and the project file(s) associated with that function.

Configuration Function Files
Asset metadata definition \gdt.xml
\Capture-Templates\*
Workflow definition \lpc.lpc
Asset icons \Document-Source\icons\*
Email templates \Document-Source\messages\*
Custom scripts \Document-Source\scripts\*

CD documentation is available from the Help menu in the IDE.


Setting up native LDAP password policies

There is basic support for password policies when using native LDAP (where the application manages users instead of an externally managed LDAP system). These password rules are enforced whenever a user requests an account or changes their password.

The following properties are available to set using the SetInstallationProperty command:

  • password.rule.min_length - the password's minimum length
  • password.rule.max_length - the password's maximum length
  • password.rule.min_upper_case_count - the minimum number of upper case characters the password must contain
  • password.rule.min_lower_case_count - the minimum number of lower case characters the password must contain
  • password.rule.min_digit_count - the minimum number of digits the password must contain
  • password.rule.min_symbol_count - the minimum number of non-alphanumeric characters the password must contain
  • password.rule.max_repeat_count - the maximum number of consecutive characters that can appear in the password

Advanced policy controls

OpenLDAP has additional password policy support in addition to the password complexity support specified above. This includes account lockout, grace authentication, and password expiration rules. To enable these requires modifying OpenLDAP accordingly.

The steps below are from Lifecycle Manager version 7.1 and below where we show an example of running OpenLDAP using a static slapd.conf configuration file. However if you are running OpenLDAP using the newer on-line configuration (OLC), we defer to your LDAP administrators. In essence, you need to include OpenLDAP's Password Policy schema (ppolicy) and overlay, then create a default policy DN and populate it with the desired Password Policy attributes outlined below.

  1. Stop the ldap server (e.g. bin/slapd stop)
  2. Do the following to the conf/slapd.conf file.
    • Add this line at the top after the other schema includes, adjust the paths accordingly:
      include         /etc/openldap/schema/ppolicy.schema
    • Add this line near the middle next to the other moduleload entries. This loads the password overlay policy
      moduleload      ppolicy.la
    • Add these lines at the bottom. This enables the policy settings to be sourced from the "cn=defaultpolicy,ou=people,dc=Logidex" LDAP entry.
      overlay ppolicy
      ppolicy_default "cn=defaultpolicy,ou=people,dc=Logidex"
  3. Start the ldap server (e.g. bin/slapd start)

The LDAP server should now be enabled. To setup the password policies requires creating LDAP entries.

  1. Create an LDAP LDIF file (e.g. /tmp/policy.ldif) using the contents below. Within the Password Policy section below, the supported attributes are:
    • pwdMaxAge - The age of a password can be (in seconds) before it must be reset.
    • pwdExpireWarning - The number of seconds before a password expires that a user will start to be warned of the upcoming expiration.
    • pwdGraceAuthNLimit - The number of times a user can authenticate after their password expires.
    • pwxLockout - A Boolean indicating whether a user can get locked out by doing too many unsuccessful authentication attempts.
    • pwxLockoutDuration - The number of seconds a user will be locked out for if they have too many unsuccessful authentication attempts. A value of 0 indicates they are locked out until an administrator unlocks their account. Use the value "0" with caution to avoid unnecessary administrator requests.
    • pwxMaxFailure - The number of consecutive authentication failures that will lock out an account.
    #Default Password Policy:
    #Modify the line below according to your DN root (e.g. dc=Logidex)
    dn: cn=defaultpolicy,ou=people,dc=Logidex
    cn: default
    objectClass: pwdPolicy
    objectClass: person
    objectClass: top
    #All password changes use the bind administrative bind DN so pwdAllowUserChange is ignored
    pwdAllowUserChange: FALSE
    pwdAttribute: userPassword
    pwdCheckQuality: 0
    # 1 week expiration warning
    pwdExpireWarning: 604800
    pwdFailureCountInterval: 0
    # User can login 5 times after their password expires
    pwdGraceAuthNLimit: 5
    pwdInHistory: 0
    pwdLockout: TRUE
    pwdLockoutDuration: 0
    # 15552000 seconds is approximately 6 months
    pwdMaxAge: 15552000
    pwdMaxFailure: 0
    pwdMinAge: 0
    pwdMinLength: 0
    pwdMustChange: FALSE
    pwdSafeModify: FALSE
    sn: dummy value
  2. Import the LDAP contents using the following command. Modify the host, port, and bind DN as needed.
    ldapadd -h localhost -p 389 -D cn=manager,ou=people,dc=logidex -W -f /tmp/policy.ldif

Setting up LDAP over SSL

It is best to make sure the installation works without SSL first, then turn on SSL after you have verified that all the configuration parameters are set correctly. The steps to setup LDAP over SSL are as follows and will depend on the type of LDAP and application server you have installed.

  1. Configure and setup the LDAP server with a certificate to use for SSL.
  2. Export the certificate and save it in DER format (other formats may work).
  3. Import the certificate into the keystore for the Akana Platform (using the JRE's keytool command to import into {platform_home}/jre/lib/security/cacerts):
    {platform_home}/jre/bin/keytool -import -v -alias {CERT_ALIAS} -file /home/akana/{cert_name}.crt -keystore {platform_home}/jre/lib/security/cacerts
  4. Update the LDAP settings by changing the /lm/admin Settings -> LDAP Settings with the correct "Port" value, and the "Use LDAPS" box checked.
  5. Restart the platform container running the Lifecycle Manager feature.

Setting up Group and Role support in LDAP

LDAP groups can be used to define organization group membership and user roles for the application. A limitation of LDAP based mappings is that group and role combinations that are easily specified in the library, cannot be easily represented in LDAP. Therefore roles are either associated with groups or projects. The group/role combinations a user is granted are formed from the set of LDAP group-based mapped roles a user has with the LDAP group mapped groups a user belongs to. Likewise this is done for the LDAP project-based mapped roles a user has with the LDAP group mapped projects.

These roles are applied to the user on login or project / group create. For example:

  • If a user belongs to an LDAP group mapped to the "Enterprise Group" and belongs to an LDAP group mapped to an "Architect" role (defined to be a group-based role), the user will be granted the Architect Role on the Enterprise group.
  • If the user also belongs to an LDAP group mapped to the "Development Project" project, and belongs to an LDAP group mapped to the "Project Manager" role (defined as a project-based role), they will be a project manager for the Development Project.
  • The user will not be granted the "Architect" role for the "Development Project" or a "Project Manager" role for the "Enterprise Group" because "Architect" is a group-based role and "Development Project" is a project, correspondingly "Project Manager" is a project-based role and "Enterprise Group" is a group.

Special role considerations

There are several built-in roles, which can be mapped to LDAP groups.

  • "Project Manager". This is a project-based role. It cannot be defined as a group-based role.
  • "ACE" - Asset Capture Engineer. This is the role that can edit assets and is a project-based role. If a user is assigned to a project via an LDAP group, they will also get the ACE role by default.
  • "Asset Publisher". This is a seldom seen role and by default is a project-based role. If a user has any project based roles, they will also get the Asset Publisher role by default.
  • "Library Administrator". This allows a user to make configuration changes to the library. It is a library-wide role and the user does not need to belong to any LDAP mapped organizational group to get this role.

Mapping

For group / role mapping to work, the application must be able to determine a user's LDAP group membership. This can be accomplished in one of two ways: The group membership may be on the LDAP entry, or the group may contain the LDAP user DNs that belong to it.

To be able to determine group membership, the LDAP Settings from the Administration console need to be set up.

In the case where the LDAP user entry contains the list of groups it belongs to, the memberOf user attribute can be specified. If the LDAP groups contain the list of users that belong to it, the group section should be filled out (base DN, search scope, name attribute, member attribute).

By default, LDAP group membership will be done on a name matching basis to application organizational groups and role names. Therefore, if the library has roles defined as "Architect" and "Project Manager" (built-in), and Organizational Groups "Enterprise" and "Development Group", users will be granted rights based on LDAP groups with the same names: "Architect", "Project Manager", "Enterprise", and "Development Group". These names can be mapped differently using the mapping document. Any names that are not mapped will fall back to the default behavior.

The mapping document can be set or retrieved using the GetGroupRoleDefinitions and SetGroupRoleDefinitions commands. An example format is as follows:

This document defines 3 role mappings and two group mappings (one group, one project). The "ACE" role is mapped to an LDAP group called "Asset Editor", the "Enterprise Group" is mapped to an LDAP group called "Enterprise". The "ACE" and "Project Manager" roles are defined as project-based, the Architect role is group-based.

<?xml version="1.0" encoding="UTF-8"?>
<GroupRoleDefinitions>
    <Role name="ACE" project-role="true">
    	<ExternalSourceMapping source-id="LDAP" name-in-source="Asset Editor" />
    </Role>
    <Role name="Architect"> <!-- project-role is not set, defaults to false, meaning group role -->
    	<ExternalSourceMapping source-id="LDAP" name-in-source="Architect" />
    </Role>
    <Role name="Project Manager" project-role="true">
    	<ExternalSourceMapping source-id="LDAP" name-in-source="Project Manager" />
    </Role>
    <Group name="Enterprise Group">
    	<ExternalSourceMapping source-id="LDAP" name-in-source="Enterprise" />
    </Group>
    <Group name="Development Project">
    	<ExternalSourceMapping source-id="LDAP" name-in-source="Development Project" />
    </Group>
</GroupRoleDefinitions>

Starting and Stopping Servers

Admin Note: See the Akana Platform instructions concerning controlling the containers. In short, it's typically done via:

  • {platform_home}/bin/startup.sh {container_name} -bg
  • {platform_home}/bin/shutdown.sh {container_name}

The "-bg" parameter launches the JVM into the back ground. If using Windows, then startup.bat and shutdown.bat files will be used. On Windows, you can also use the RegisterContainerService.bat and UnRegisterContainerService.bat to register/unregister containers as Windows Services... See the Akana Platform documentation for details.


Installing Service Packs

Service packs are distributed via the Akana Support website. Each service pack will have a corresponding README file that will have instructions for installing that service pack.


Setting up SSL

Lifecycle Manager support the use of SSL (Secure Sockets Layer) encryption. However, by default, the installation is not configured to use SSL. If you want to use SSL for your installation, you will need to modify the Akana Platform container configuration running the Lifecycle Manager features.

You will need to obtain (or generate a self-signed) certificate and corresponding private key from your organizations Certificate Authority (CA). The certificate will need to be in Base64 encoded DER format, and the key will need to be in PKCS8 format.

An example of a quick self-signed certificate/key generation (note, that these steps require the OpenSSL packages and that these specific commands are using a deprecated SHA1 signature that is being called attention to by most browsers on 1/1/17):

  • 1st; Generate LM's SSL cert and key; a traditional way to generate the cert/key with full cert properties:

    # Generate the key:

    [akana@lxc1-pm8x-19 certs]$ openssl genrsa -des3 -out lxc1-pm8x-19.key 2048
    Generating RSA private key, 1024 bit long modulus

    # Generate the csr:

    [akana@lxc1-pm8x-19 certs]$ openssl req -new -key lxc1-pm8x-19.key -out lxc1-pm8x-19.csr

    # Remove passphrase from key:

    [akana@lxc1-pm8x-19 certs]$ cp lxc1-pm8x-19.key lxc1-pm8x-19.key.orig
    [akana@lxc1-pm8x-19 certs]$ openssl rsa -in lxc1-pm8x-19.key.orig -out lxc1-pm8x-19.key

    # Generate the cert:

    [akana@lxc1-pm8x-19 certs]$ openssl x509 -req -days 365 -in lxc1-pm8x-19.csr -signkey lxc1-pm8x-19.key -out lxc1-pm8x-19.local.akana.com.crt
    Signature ok
  • ...as an alternative, you could use the following one-liner (note that in the following example, we're naming the key as key.pem and cert and cert.pem whereas the examples above were based on the hostname...):
    [akana@lxc1-pm8x-19 certs]$ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=lxc1-pm8x-19.local.akana.com'
  • 2nd; Convert the private key to pk8 (this is required for either method of generating the cert)!:
    [akana@lxc1-pm8x-19 certs]$ openssl pkcs8 -topk8 -inform PEM -in key.pem -outform PEM -out key.pk8 -nocrypt
  • 3rd; create an {platform_home}/instances/{instance_name}/deploy/com.soa.transport.jetty.endpoint-{instance_name}.cfg transport config file using the cert and key. Note that you'll copy/paste the contents of the cert and key files without line breaks in-between the following tags:
    -----BEGIN CERTIFICATE-----
    -----END CERTIFICATE-----

    ...and...

     -----BEGIN PRIVATE KEY-----
     -----END PRIVATE KEY-----
    • Example com.soa.transport.jetty.endpoint-lm.cfg (https.private.key is the private key, and https.private.key.cert.chain is the certificate!):
      http.url=https://lxc1-pm8x-19.local.akana.com:9443
      https.private.key=MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC66WWIU5frKWw8aKA...
      https.private.key.cert.chain=MIIDzDCCArQCCQD2PPP8Wp1k2jANBgkqhkiG9w0BAQUFADCBpzELMAkG...
      scheme=https
      https.need.client.auth=false
      https.want.client.auth=false
  • 4th; The Plat jvm needs to trust the ssl cert:
    • # Delete any existing cert for the host using the same alias:
      [akana@lxc1-pm8x-19 log]$ /opt/akana/plat8/jre/bin/keytool -delete -alias LXC1PM8X19 -keystore /opt/akana/plat8/jre/lib/security/cacerts
      Enter keystore password:
    • # Then add cert:
      [akana@lxc1-pm8x-19 log]$ /opt/akana/plat8/jre/bin/keytool -import -v -alias LXC1PM8X19 -file /home/akana/certs/092616_1510/cert.pem -keystore /opt/akana/plat8/jre/lib/security/cacerts
      Enter keystore password:
      ...
      Trust this certificate? [no]: yes
      Certificate was added to keystore
      [Storing /opt/akana/plat8/jre/lib/security/cacerts]
  • 5th; Configure LM's /admin console's Settings -> General Settings -> [x] SSL checkbox and Port: properties so that LM's redirect logic and URL builder use the HTTPS protocol and the correct port.

LM behind a Load Balancer (cluster)

Placing LM nodes behind a front facing load balancer requires the following:

  • All LM nodes be pointed to the same backend database/schema.
  • All LM nodes be running on identical Akana Platform and LM feature versions.
  • Maintain Session Affinity (Sticky sessions); the load balancer must ensure that a given session be serviced by the same node for the duration of that session. You can either use the Akana Platform container session cookie (JSESSIONID_{container_name}) defined in the {plat_home}/instances/{container_name}/system.properties -> org.eclipse.jetty.servlet.SessionCookie property, or a LB specific cookie injected by your LB for the purpose.
  • All LM nodes must have an identical path to the LM app_*.log files. By default, this path is {plat_home}/instances/{container_name}/log/, however it's configurable to via the /lm/admin Settings -> Logging Settings; adjust the com.logiclibrary.common.logging.ThreadFileHandler.pattern, com.logiclibrary.common.logging.FileHandler.pattern, and com.logiclibrary.common.logging.IncidentHandler.pattern to the new path. The nodes *CANNOT* use shared storage to a common path (NFS mount, etc), as each node would clobber the others app logs.
  • LM 8.0.0 introduced a library configuration check timer (runs every 30 seconds) to ensure that all the nodes will automatically read in any new library configuration changes, regardless of the node serving the upload session.

LM behind a Reverse Proxy/Load Balancer that terminates SSL

If you place LM behind a reverse proxy or load balancer that terminates SSL, to avoid circular redirect issues with the login/challenge pages, you must configure that front facing device with X-Forwarded headers (X-Forwarded-Proto https and X-Forwarded-Ssl on) then configure the Akana Platform to honor those headers via the com.soa.platform.jetty -> http.incoming.transport.config.forwarded setting with a value of TRUE.


CSRF Security for Lifecycle Manager

From https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF):

"CSRF is an attack that tricks the victim into submitting a malicious request. It inherits the identity and privileges of the victim to perform an undesired function on the victim's behalf. For most sites, browser requests automatically include any credentials associated with the site, such as the user's session cookie, IP address, Windows domain credentials, and so forth. Therefore, if the user is currently authenticated to the site, the site will have no way to distinguish between the forged request sent by the victim and a legitimate request sent by the victim.

CSRF attacks target functionality that causes a state change on the server, such as changing the victim's email address or password, or purchasing something. Forcing the victim to retrieve data doesn't benefit an attacker because the attacker doesn't receive the response, the victim does. As such, CSRF attacks target state-changing requests."

Note: this is a blind attack - no data is returned to the attacker.

Also note: this is not the same as a XSS (Cross-site Scripting) attack.

To protect from CSRF attacks, a security token will be passed on requests to protected resources/actions.

To manage this, there is a configuration property section in the Platform admin console, com.soa.repository.csrfguard, with a property, set to false:

  • In version 2018.0.0, the property name is com.akana.lifecyclemanager.owasp.csrfguard.Enabled
  • In versions prior to 2018.0.0, the property name is org.owasp.csrfguard.Enabled

Setting this property to true enables CSRFGuard after a restart of the system.

Known issues:

  • Clicking on a link before the page is completely loaded may cause a violation because the token may not have been added to the link yet.
  • Redirect to CSRF Challenge Page on Violation; Some URLs like bookmarks or email notification links will not have the token. Rather than unprotecting all possible notification URLs or bringing up a static error page, we will give the user a chance to decide whether to proceed by forwarding to an error page with a button that sends the request back to the page with the token attached. Since this requires user intervention, it is not exploitable by CSRF.

Reset System Passwords

If you need to reset passwords, here is a list of the passwords that you may need to update:

  • Database user password
    • Use the Oracle sqlplus client for Oracle or the administration client/console for DB2.
    • Update the Akana Platform's /admin console -> Configuration section with the new password.

Log Files and Logging Levels

Log files and location

Below is a brief description of the most important log files (not all of the log files are listed here).

By default, the log files are in the directory {platform_home}/instances/{instance_name}/log

Changing the logging levels

The logging level may be changed dynamically at runtime through the Administration console (Settings -> Logging Settings).

Sample Logging file:

.level=INFO
com.logiclibrary.level=INFO

handlers=com.logiclibrary.common.logging.ThreadFileHandler, com.logiclibrary.common.logging.IncidentHandler

com.logiclibrary.common.logging.IncidentHandler.count=10
com.logiclibrary.common.logging.IncidentHandler.limit=1000000
com.logiclibrary.common.logging.IncidentHandler.pattern=/opt/lm/logs/webapp/incident_%g.log

com.logiclibrary.common.logging.ThreadFileHandler.count=10
com.logiclibrary.common.logging.ThreadFileHandler.limit=5000000
com.logiclibrary.common.logging.ThreadFileHandler.pattern=/opt/lm/logs/webapp/lm_%g.log

com.logiclibrary.common.logging.FileHandler.pattern=/opt/lm/logs/webapp/lm_%g.log

The only parameters that should need to be changed are the pathnames where the log files are placed and the logging level. The *.pattern properties specify where to place individual log files and how to number them; the %g is replaced with a sequential number. Logs are always written to the '0' log file. One it fills up, logs are archived so that '0' becomes '1', '1' becomes '2', up to 'count-2' becomes 'count - 1'

Possible logging levels are as follows (from most verbose to no logging). The most common ones are available from the log settings page, which will automatically update the log properties.

  • ALL
  • FINEST
  • FINER
  • FINE
  • CONFIG
  • INFO
  • WARNING
  • SEVERE
  • OFF

The default level for new installations is FINER, and can be changed to ALL or FINEST to get more detailed debugging information.

NOTE: Setting the logging level to one of the more "verbose" levels will tend to slow down the performance of the application so you should only turn up the logging if needed for debugging.


Database Administration

Database administration is not covered here. Generally DBA responsibilities are a separate and specialized responsibility.

There are no additional DBA requirements for Lifecycle Manager.


Backing up and Restoring the Application and Data

Full Installation Backup (code and data):

In some cases you will want to do a full backup of the installation, including data, code, and configuration information.

Prior to installing service packs you should do an installation backup. Most service packs will be simple code updates, however there may be times when a data update in a service pack is required to support new functions.

Here is a list of the items that should be backed up:

  1. Platform Home

    Note - make sure you back up so that the file and directory permissions and ownership and symbolic links are preserved.

    Example backup command using the tar command

    (you can use any backup/restore tool or utility, this is an example of one option)

    • login to the app server as root
    • su - {logidex.user}
    • cd {platform_home}
    • tar cvpf /tmp/platform-backup.tar
  2. The Database

Data Backup Only:

Your data is stored in the database, so only the database tables spaces need to be backed up when you are backing up data.

  1. Database users information
  2. Database tablespaces

    By default these tablespaces are named DBUSERDATA, and DBUSERTEMP, however if this had been upgraded from a previous version of LM, you may also have DBUSERLONG, DBUSERINDX, and DBUSERTEMP, unless you overrode the tablespace names.

Full Installation Restore (code and data)

If you ever have the need to do a full restore of Lifecycle Manager and the corresponding data, follow these steps:

  1. Stop all containers running from within the Akana Platform:
    {platform_home}/bin/shutdown.sh {instance_name}
  2. Restore the database from the last good backup copy
  3. Restore the {platform_home} tree from the last good backup

    Note - make sure you restore so that that the file and directory permissions and ownership and symbolic links are also restored

  4. Startup the containers:
    {platform_home}/bin/startup.sh {instance_name} -bg

Adding a Library User

If {ldap.ownership.mode}=guest, user information is obtained from the external LDAP server. Therefore, there is no concept of creating users from within the application. Valid LDAP users can simply login to the library to either request access from the usage controller or be allowed in, depending if controlled access is turned on or not.

If {ldap.ownership.mode}=native, users request accounts from the "Request an Account" link off the login page. Their entry is dependent on whether controlled access for a library is turned on or not.

Reset a User Password

A user can reset a password using the "Forgot Password" link on the login page.

NOTE: if {ldap.ownership.mode}=guest, then password resets must be done through the external LDAP server.


Super User

Lifecycle Manager provides the capability of accessing your libraries and your System Admin console by logging in with a special "user" account that does not require authentication by your LDAP system. This account, termed the "Super User" account can be used via the web browser application to access your library and the System Admin console. Logging in as Super User provides you with unlimited access to the libraries of your installation and the facilities provided by the System Admin console. Note that super user access can be enabled or disabled in the lib.conf file by assigning a password or leaving the password blank.

The Purpose of Super User

Super User access is provided to enable you to recover from the lack of an active Library Administrator account. By logging into a library as super user, you can activate an inactive account or create a new user account and assign the Library Administrator role.

Another purpose for the Super User account is to provide you with a user account that is portrayed as being associated with the application as opposed to being associated with an individual, human user. Lifecycle Manager provide for the use of the super user account as an "application user" called Repository Application. This user is available for such things as being recorded as the "submitter" of assets submitted by automation and being identified as the "responsible user" when establishing library federation through creation of Visible Asset Source and Remote Asset Source configuration.

Super User Role Assignments

The Super User account is assigned the library roles of Library Administrator, Usage Controller and Asset User. In addition, this account is also assigned the group roles of Asset Capture Engineer (ACE), Publisher and Asset Owner - all at the Enterprise Group level. See the web browser application's online help for more information on roles and their scope of application.

Creating Additional Libraries

If your installation needs to create multiple Asset Libraries, you can create them as needed. Additional libraries can be created using via the Admin Console for the Installation Administrator.


Download assets or upload assets automatically

The ability to automate asset operations is provided by the Automation Extensions (AE). There are two samples provided with the AE that allow a user to import a group of assets into a library or export a group of assets from a library. See the SampleLoader and SampleDownloader in the AE installable and accompanying documentation available from the support link off the top navigation bar in the library.


Commands You Can Run From The Admin Console

There are several special administrative and library maintenance commands that are only available to the Installation Administrator. See the Admin Console overview for how to access the Admin Console and select "Execute Command".

Types of admin commands:

NOTE: for each command, you will need to select the name of the library that the command is being executed against
Command Name Description File Parameter Field Parameter Fields (1-10)
Assets
DisplayAsset Displays information about an asset. If no asset name and version are specified, all assets are displayed. If an asset name without a version is specified, all assets with that name are displayed. Finally, if both an asset name and version are given, only those assets with the name/version will be shown. N/A
  1. Asset's name (optional)
  2. Asset's version (optional)
ShowAssetHistory Shows all changes to a catalog asset starting with its initial creation. N/A
  1. Asset Id (mandatory) Note that asset Id may be obtained from URLs used in accessing the catalog asset.
UnlockAsset Unlocks an asset with the specified name and version. If multiple assets exist with the specified name and version, all will be unlocked. N/A
  1. Asset's name (mandatory)
  2. Asset's version (mandatory)
RemoveAsset

Delete an asset. Optionally, delete a list of assets specified in XML file. Asset names are case sensitive.

For list format see the example Asset Deletion List XML file below

Filename of the asset deletion list XML file (if applicable).

UTF-8 Note

For single asset only:

  1. Asset name
  2. Asset version
  3. delete (optional, if the text "delete" is specified it also removes the asset from the catalog)
Attribute Definitions - See the Attribute Definition section for more information
GetAttributeDefinitionSchema Get the XML schema for contact attribute definition documents provided to the SetAttributeDefinitions command. Note that this command is installation scoped and ignores the "Library" parameter. N/A N/A
GetCurrentAttributeDefinitions Get the currently defined contact attribute definitions. Note that this command is installation scoped and ignores the "Library" parameter. N/A N/A
GetDefaultAttributeDefinitions Get the default contact attribute definition XML document provided by Akana. Note that this command is installation scoped and ignores the "Library" parameter. N/A N/A
SetAttributeDefinitions

Uploads an XML file of contact attribute definitions that will define the attributes maintained and displayed in User and Contact pages. The XML document must adhere to the attribute definition schema available through the GetAttributeDefinitionSchema command. The default attribute definitions document (available through the GetDefaultAttributeDefinitions command) is a useful example of an attribute definitions document. Notes:

This command is installation scoped and ignores the "Library" parameter.

The application server must be restarted to clear cached user information.

Filename of the attribute definitions XML File

UTF-8 Note

N/A
LDAP Group / Role Definitions - See the Setting up LDAP groups and roles section for more information
GetGroupRoleDefinitions Get the currently defined group and role mappings for the selected library. N/A N/A
SetGroupRoleDefinitions Set the group and role mappings for the selected library. Mapping file for the library
  1. remove (removes / disables all group / role mappings).
Documents
GetDocument Returns the document with the associated ID stored in the selected library. N/A
  1. The document ID of the file to retrieve
GetDocumentIDs Returns the list of available documents in the selected library N/A N/A
RemoveDocument Removes a document from the selected library N/A
  1. The document ID of the file to remove
StoreDocument Stores a file in the selected library. This document may be used by certain processing steps (e.g. by a Listener within the Library's workflow) The file to store
  1. The document ID of the file. If this is not specified, it will default to the filename
Templates
The Global Definition template and Asset Capture templates are normally managed via the Configuration Designer plug-in. The following commands are provided, beginning in version 6.3.1 of the product, in case the CD is not available.
GetDefinitionTemplate Retrieve the GDT for selected library N/A N/A
SetDefinitionTemplate Replace the GDT for selected library New GDT file N/A
SetCaptureTemplate Replace a capture template in the selected library New template file N/A
Email
See the Configuration Designer section of this document for details of HTML mail template configuration.
Export/Import
ExportConfig Exports the configuration from the specified library into a zip file. This includes the global definition template, capture templates, and Library Configuration document. N/A N/A
ImportConfig Imports and overwrites the configuration of the specified library with the contents of the provided zip file. Zip file from ExportConfig command N/A
ExportLibrary Exports data from the selected library into a zip file suitable for running ImportLibrary against. Items that can be exported (entered as comma-separated string Parameter 1) are as follows:
  • document - The local files in the document source
  • global-definition-template - The global definition template.
  • capture-templates - All capture templates.
  • type-template-associations - The mappings between asset types and capture templates.
  • mail-templates - All mail templates for the installation
  • library - A very limited set of information about the library. This will be extended in the future.
  • users - Basic user information of all users in the library.
  • ccsets - All classification criteria sets.
  • profiles - All profiles stored in the library.
  • asset-views - Asset view names and descriptions (see also: asset-view-assets).
  • groups - All groups, projects (see also: group-associations, user-roles).
  • reports - The list of reports from the Manage Reports section
  • publish-templates - All publish templates in the library.
  • publish-template-associations - Publish template to group associations.
  • lpc - The library process configuration
  • user-roles - User roles
  • user-properties - Custom user properties
  • group-properties - Custom group properties
  • models - Reference models
  • publish-models - Submits models for publish
  • assets - Published assets. Exports only published assets; asset requests, Assets in Progress assets and forums are not currently supported. When running ImportLibrary, the assets are imported into the Asset Source (Assets in Progress view.)
  • publish-assets - Asset publish information.
  • group-associations - Items associated with a group (models and asset views).
  • asset-view-assets - Assets attached to asset views
  • publish-infos - Publish information about an asset (contacts, public / private artifacts, etc.)
  • asset-subscriptions - Assets subscribed to by users
  • asset-acquisitions - Assets acquired for projects or consuming assets
N/A
  1. A comma separated list of items to export. See the command description for possible values.
ImportLibrary

Imports the contents of an XML file or zip file into the selected library. There are a few items of importance.

First, some items need to be imported before others. For example, assets should be published prior to asset views that use them (asset-view-assets). If you do import items in steps, they should be done in the order they are listed in the ExportLibrary command.

Secondly, some actions are asynchronous, requiring some time before they are visible in the library. Therefore, the items up to and including assets and models should be done prior to importing the items that follow. Ensure any assets and models are published before proceeding to the next items.

The zip file or individual xml file from the ExportLibrary command. Individual templates, assets, and models cannot be imported using XML.
  1. An optional comma separated list of items to import from the zip file. See the ExportLibrary command above for possible values.
  2. Optional flag to force import of assets with metadata not meeting template constraints: force-import=true
Installation Configuration
GetInstallationProperty Displays the initial and override value for the given property name. Note that this command is installation scoped and ignores the "Library" parameter. N/A
  1. Property name. Refer to list in the Installation Properties section
SetInstallationProperty Set or clear an override value for the given property. Note that this command is installation scoped and ignores the "Library" parameter. N/A
  1. Property name. Refer to list in the Installation Properties section.
  2. Property value or blank to clear a previous override
Licensing
GetLicenseProperties Returns the license properties that the installation is currently using. The library parameter is ignored. N/A N/A
SetLicenseProperties Sets the license properties that the installation will use. The license property is provided by Akana support. The library parameter is ignored. The license properties file.
  1. A digital signature that corresponds with the license properties file.
SetLicenseKey A license key specific to a customer. This file should only be updated when directed by Akana support. The library parameter is ignored. The license key file. N/A
Library Configuration - see the Library Configuration Guide (available with your Lifecycle Manager installation) for more details.
GetProcessConfigurationSchema Returns the Library Configuration schema, which can be used in schema aware XML editing tools to build LPC documents. This command is installation scoped and ignores the library parameter. N/A N/A
GetDefaultProcessConfiguration Retrieves the default Library Configuration for the selected library. This command is installation scoped and ignores the library parameter. N/A N/A
GetCurrentProcessConfiguration Returns the active Library Configuration. The LPC configuration is library specific, therefore the library parameter should be set to the library you wish to retrieve the LPC for. N/A N/A
SetProcessConfiguration Sets the Library Configuration used for the selected library. If you are running the application in a cluster, it needs to be restarted after running this command.

A valid XML file containing the configuration definitions.

UTF-8 Note

N/A
Logging
GetLoggingConfig Displays the current logging configuration Note that this command is installation scoped and ignores the "Library" parameter. N/A N/A
UpdateLoggingConfig Sets the logging configuration. Note that this command is installation scoped and ignores the "Library" parameter. Filename of the new logging configuration. See the logging section for an example.
  1. Set to "save" to persist the logging configuration across application restarts.
Policy Manager
PrimeOrganizationsFromPolicyManager Creates organizations based on a hierarchy in Policy Manager. The purpose of this command is to prime a library for integration with an existing Policy Manager system. Since it does more than simply creating groups (it cross-references the groups of the two systems), it should not be run on the same library with different Policy Manager groups or systems, nor should two RM systems use the same source Policy Manager organization. The Policy Manager group specified in the command arguments needs to correspond to a child organization of the "Registry" (a top level organization). The Enterprise group will be renamed to correspond to that group and all subordinates of that group will be created as well. N/A
  1. The name of the federated system that corresponds to the Policy Manager system
  2. The name of the top level organization in Policy Manager that the library will be associated with.
Other
ChangeLibraryName Change the name of an existing library. Note that this command does not affect other libraries that may be viewing or interacting with this library. For this reason any dependencies from other libraries(local or remote) such as visible-asset-sources or federated-repositories should be disconnected prior to changing a library name. Remote clients will also need to change connection information once the library name is changed. Asset data is changed asynchronously and changes may still be in progress after the command returns. N/A
  1. The new library name.
CreateStandardReports Creates the standard reports in an existing library specified in the library dropdown. N/A N/A
DisplayEventDefinitions Displays all defined events and their properties. Note that this command is installation scoped and ignores the "Library" parameter. N/A N/A
GenGrants Generates the SQL needed to give a different user the correct database permissions to run the application. N/A
  1. The schema the database entities are owned by.
  2. The alternate database user you wish to grant permissions to.
MigrateArtifacts Migrates artifacts from a regular tablespace to a long tablespace. N/A N/A
RunScript Executes either a BeanShell or Jython script. The script interpreter used is based on the file extension (.bsh, or .py). This is mainly to be used for support purposes, but can be used to test some ScriptListener code, without the need to integrate it into the Library Process Configuration. The library ID of the selected library is passed into the script as a variable named "libraryId". The script to execute. >Parameters to the script may be specified in the form "variablename=value" (without quotes). The parameters are then available in the script as variables.
SynchronizeContacts Refresh cached contact attribute information from an external contact source such as LDAP. Note that this command is installation scoped and ignores the "Library" parameter. N/A N/A
SynchronizeQueryableArtifacts The SynchronizeQueryableArtifacts command refreshes all queryable artifacts for assets in the specified Library. This command is useful when assets existed prior to marking an artifact type as queryable. It will ensure that the new queryable artifacts are searched. N/A N/A
SynchronizeRASA Force synchronization of a RemoteAssetSourceAdapter with its associated remote AssetSource. N/A
  1. Name of RemoteAssetSourceAdapter to synchronize
RemoveLibrary WARNING: This command deletes the library and its associated data objects (users, projects, assets, models, etc). There is no undo mechanism other than to restore from backup. Use with caution. N/A N/A
RemoveUser

The RemoveUser command is used to delete a user. This command should be used with caution as the deletion of a User is irreversible. In most cases it is recommended that users be deactivated (from the user details page) rather than being removed. Since a library may contain historical information associated with the removed user (such as request history, forum posts, etc.), it is necessary to provide a "substitute" User that such historical information can be assigned to once the original User is removed.

The library dropdown should be set to the library containing the user to remove

N/A
  1. user account (id) of the User to remove
  2. user account (id) of the substitute user

Example Asset Deletion List for RemoveAsset command

The following is the text of an example asset deletion list file. Note the "repository-delete" parameter shown in each entry indicates whether the asset should be deleted from the underlying "assets in progress" as well. If the "repository-delete" parameter is set to false, the asset will be placed back into "submitted" state in the catalog.

    <?xml version="1.0" encoding="UTF-8"?>
    
<asset_deletion_list> <asset name="Test asset" version = "V2.0" repository-delete = "false"/> <asset name="Bad asset" version = "1.5" repository-delete = "true"/> <asset id="1.0_123897897892734" repository-delete = "true"/> </asset_deletion_list>

Customize user attributes and LDAP attributes

The user properties that appear in the create and display user and contact pages are obtained and configured through the attribute definitions. Attribute definitions determine not only the names of fields that are available and displayed for users, but also the corresponding services to use when looking up user information. This is accomplished by configuring an XML document and uploading it through the Admin Console using the Attribute Definition commands: GetAttributeDefinitionSchema, GetCurrentAttributeDefinitions, GetDefaultAttributeDefinitions, and SetAttributeDefinitions.

The following is an example document.

<?xml version="1.0" encoding="utf-8"?>
<ContactAttributeDefinitions xmlns="http://www.logiclibrary.com/2004/ContactAttributesXML">
        <AttributeDefinition attribute-name="Full Name" include-in-filter="true" include-in-list="true">
		<ExternalSourceMapping source-id="LDAP" name-in-source="cn" />
	</AttributeDefinition>
	<AttributeDefinition attribute-name="Email" include-in-filter="true" include-in-list="true">
		<ExternalSourceMapping source-id="LDAP" name-in-source="mail" />
	</AttributeDefinition>
        <AttributeDefinition attribute-name="First Name" include-in-filter="false" include-in-list="false">
		<ExternalSourceMapping source-id="LDAP" name-in-source="givenName" />
	</AttributeDefinition>
        <AttributeDefinition attribute-name="Last Name" include-in-filter="false" include-in-list="false">
		<ExternalSourceMapping source-id="LDAP" name-in-source="sn" />
	</AttributeDefinition>
	<AttributeDefinition attribute-name="Phone" include-in-filter="false" include-in-list="true"></AttributeDefinition>
	<AttributeDefinition attribute-name="Fax" include-in-filter="false" include-in-list="false"></AttributeDefinition>
	<AttributeDefinition attribute-name="Cell" include-in-filter="false" include-in-list="false"></AttributeDefinition>
</ContactAttributeDefinitions>

Each AttributeDefinition element defines a user attribute that may be displayed (through the attribute-name XML attribute). The "Full Name" and "Email" attributes are the only ones required.

If the include-in-filter XML attribute is set to true, the attribute is searchable in user create and list pages, otherwise it is not.

The include-in-list XML attribute is currently ignored, and all attributes will show up in user detail pages.

The ExternalSourceMapping element determines which user attributes come from external sources through the source-id XML attribute. Currently only "LDAP" is supported, which signifies that LDAP is queried, and which LDAP element is used (name-in-source attribute), for user information related to that particular user attribute. If there is no associated ExternalSourceMapping element configured, then a Usage Controller can set that particular user attribute in the library. A user can also set any such attributes for their own account.

The sample Attribute Definition document configures 7 possible attributes for a user (Full Name, Email, First Name, Last Name, Phone, Fax, and Cell). The sample document also states where the user attribute values should come from in LDAP. In this case, the "Full Name" for a user comes from the LDAP "cn" attribute, the "Email" for a user comes from the LDAP "mail" attribute, and so on. The "Full Name" and "Email" attributes are the only searchable attributes.

One attribute that may be helpful to include is the account name of a user. This may be configured by adding the following entry to the XML file and editing the name-in-source attribute to correspond with the attribute you are using to authenticate users through LDAP (the user's account name attribute in the Admin Console's Settings -> LDAP Settings page):

<AttributeDefinition attribute-name="Account Name" include-in-filter="true" include-in-list="false">
    <ExternalSourceMapping source-id="LDAP" name-in-source="uid" />
</AttributeDefinition>

Full-text artifact search

Full-text artifact search on Oracle

By default, new Lifecycle Manager installations perform full-text searching of asset artifacts on Oracle. However if you've upgraded from RM 6.4, and had not yet enabled Full-text artifact searching on Oracle, perform the steps below.

Run the following to enable all asset queries to search for search terms within asset artifacts. See also the installation property "database_text_enabled" in this document. Note that there will be changes made to the database so the JDBC database user must have full privileges during this procedure.

  1. Install Oracle Text. This may have already been installed into the Oracle instance when it was created. However if it was not you'll need to install it and ensure the default Oracle Text entities are installed.
    • The ORACLE_HOME/ctx/admin/defaults/drdeflang.sql script ensures the default stoplist, lexer, and wordlist are setup for your language. You'll need to run this script if these are not setup in the Oracle instance.
  2. On the Lifecycle Manager Server, from the Installation Admin Console:
    • Execute Command
    • Command name: EnableTextSearchOnOracle
    • Choose the desired library from the dropdown list
    • Invoke
    • Several confirmation messages are output
    • Repeat for each library where full text searching is desired

    If an error is generated such as:
    "PLS-00201: identifier 'CTX_DDL' must be declared
    ORA-06550: line 1, column 7:
    PL/SQL: Statement ignored"
    Have your DBA execute this SQL query:
    GRANT CTXAPP TO yourDBuser
    Then re-run the command above.

  3. On the database, execute the GRANT statements output from the command above. These are listed here:
    • --Change "dbuser" to the database user name in your environment.
      GRANT EXECUTE ON CTX_CLS TO dbuser;
      GRANT EXECUTE ON CTX_DDL TO dbuser;
      GRANT EXECUTE ON CTX_DOC TO dbuser;
      GRANT EXECUTE ON CTX_OUTPUT TO dbuser;
      GRANT EXECUTE ON CTX_QUERY TO dbuser;
      GRANT EXECUTE ON CTX_REPORT TO dbuser;
      GRANT EXECUTE ON CTX_THES TO dbuser;

After successful command completion, set the installation property "database_text_enabled" to true so new libraries are automatically indexed.

Full-text artifact search on SQL Server

Full-text searching is enabled by default on SQL Server. However, SQL Server only "knows" how to index certain types of artifacts depending on which filters are installed.

Details on filters can be found here.

To determine which filters are installed on SQL Server, execute the following SQL:

EXEC sp_help_fulltext_system_components 'filter';

Update Installation-wide Properties

This section is mostly deprecated because installation properties are updated through the Administration Console's Settings page.

Most of the configuration values that are set through the Administration Console's Settings page during the initial installation. However, the following can also be updated through the UI via the Execute Command's SetInstallationProperty. This command works by manipulating override values that are stored in a database table. If no value has been set via SetInstallationProperty, or if a blank value is set, then the system uses values from the deployment descriptor--built from the 'conf' file properties--as was the case in previous releases. Use "GetInstallationProperty" to view a property value as set in the configuration file and the value persisted in the database, if it exists. Take care to not misconfigure properties that could lock you out of the system (e.g. LDAP parameters). The following table describes the properties that can and cannot be set by this method.

Property Name Description Notes
smtp_host SMTP hostname to forward email notifications  
smtp_port SMTP port of the SMTP server host (see above). Default: 25
smtp_authenticated A Boolean indicating whether or not SMTP authentication occurs. If this is specified smtp_user and smtp_password should also be set. Default: false
smtp_user User used to authenticate with the SMTP server.
smtp_password Password for the corresponding smtp_user used to authenticate with the SMTP server
smtp_ssl A Boolean indicating whether communication to the SMTP server is done over SSL. The corresponding smtp_port parameter should reflect a SSL port. The smtp_starttls should be set to false if this is true. Default: false
smtp_starttls A Boolean indicating whether a STARTTLS command should be issued to the SMTP server which causes all subsequent communication to be encrypted. The smtp_ssl parameter should be set to false if this is true. Default: false
logidex/webhostext The hostname and port portion of the application's URL. This value is used in email notifications and certain URL rewrites. E.g. rmserver.example.com:8080  
logidex/adminUsers Semi-colon delimited list of LDAP userIDs who have access to the Installation Administration console No application restart required
logidex/ldap/url LDAP connection. See LDAP section above. Requires appserver restart, but first, be sure superuser is enabled by logging in through .../application/access/suLogin.do
logidex/ldap/binddn DN of the LDAP user initiating connections See warning above
logidex/ldap/bindpassword Password for LDAP bind user See warning above
logidex/ldap/ownershipMode Either guest or native See warning above
logidex/followReferrals Specifies whether or not LDAP referrals are expected--true or false. See warning above
logidex/use_ssl See SSL section of this document  
logidex/showlibrarylist Value of true or false to show the list of libraries on the challenge and library prompt pages No application restart required
logidex/cache/asset_cache_size Performance setting for the maximum size of the Asset object cache. Integer.  
logidex/cache/user_cache_size Performance setting for the maximum size of the User object cache. Integer.  
logidex/cache/orggroup_cache_size Performance setting for the maximum size of the Group object cache. Integer.  
logidex/userIdHeader Name of SSO HTTP header. See SSO section of this document.  
logidex/challengeURL Complete URL of SSO challenge page. See SSO section of this document.  
logidex/logoutRedirect Complete URL of a logout page. Particularily useful in an SSO environment.  
logidex/wsauthorizationpolicy Standard or open web services authentication. Either "com.logiclibrary.security.WSAuthorizationPolicyStandard" or "com.logiclibrary.security.WSAuthorizationPolicyOpen".  
database_schema_updatable True or false: the database user can drop and recreate views.  
index_optimization_interval Oracle Text optimization interval in seconds. Default is 86400 (one day). Setting the value to 0 turns it off altogether. The interval change takes effect the next time the optimization fires. No application restart required
disable_email True, false, or null. When 'true', the system will not send email. No application restart required
suppress_publish_note True or false. When 'true', users will not be prompted to enter a note upon asset submission.  
database_text_enabled True or false. When 'true', new libraries on an Oracle system will be created with full-text indexing enabled. See also EnableTextSearchOnOracle. No application restart required
synchronous_text_update True or false. On DB2 systems when the property is 'false', the indexer that runs after every asset publish will be disabled. The index will still be updated by the DB2 index settings, which runs every 5 minutes.  
enable_xss_protection True or false. When true, HTML contained in the asset overview is displayed as raw HTML No application restart required
enable_captcha True or false. When true and using native LDAP, the request account page will require users to enter characters displayed in a captcha image. No application restart required
password.rule.min_length password.rule.max_length password.rule.min_upper_case_count password.rule.min_lower_case_count password.rule.min_digit_count password.rule.min_symbol_count password.rule.max_repeat_count Specific rules that are enforced on password complexity when using native LDAP. See the password policy section for more details. No application restart required
The following properties cannot be set via the SetInstallationProperty command
  • Superuser password
  • Database details such as instance name and connection details
   

Single Sign-on (SSO) Installation and Configuration

Single Sign-on (SSO) is a login mechanism that allows authorization by an external web server plug-in. This enables you to integrate with your own "single sign on" solution. External (thick) clients such as the Exclipse, .NET or the Automation Extensions will still prompt for authentication, meaning that they will not authenticate through your SSO provider.

Note: You will need to use a front facing web server proxy running a single sign-on agent to enforce that all traffic to the application has been authenticated/authorized. See your specific SSO implementation documentation.

This capability is enabled by configuring the following property in the Admin Console Settings (Settings -> SSO Settings)

 userIdHeader= 

The value of this entry should specify the HTTP header name that contains the authenticated user's user id (account name).So, for example if the User ID Header specifies "XYZ_USERID", the logon logic will look for a HTTP Header with that name. Effectively, you enable external authorization by specifying non-null values for this entry.

If incoming HTTP request contains the specified header, the login logic assumes that this user has been authenticated externally and does not present a login challenge page. Instead, it attempts to find an existing User object with the account name specified by the configured user id header. It then uses the found User object to establish a session for the user.

When properly configured and integrated with an external authentication mechanism, users never see the login challenge. Instead they see the challenge presented by the external authentication mechanism. In this mode it is not necessary for Usage Controllers to define new users.

When external authorization is configured, No "Logout" link appears on the top navigation bar.

The following resources should not be protected from SSO authorization:

  • contextroot/application/access
  • contextroot/ServerInfo
  • contextroot/services
  • contextroot/servlet/BirtReportServlet
  • contextroot/servlet/WSDLResourceServlet

Customize the com.soa.repository.custom.jar

In order to customize the following topics; Top Banner, Footer, Home Page Content, Top Navigation Links, and Context Sensitive Help Pages, you will need to modify a copy of the {platform_home}/lib/lifecyclerepository_8.0.0.{version}/com.soa.repository.custom.jar then update the contents with the relevant customizations detailed below. If you are modifying multiple items such as the Top Banner and Footer, you'll added your customizations to a single com.soa.repository.custom.jar. NOTE: if you are adding or updating any .jsp files, you will need to pre-compile them before adding them back to your new com.soa.repository.custom.jar.

The customizations are accomplished by:

  1. Unpack the {platform_home}/lib/lifecyclemanager_8.0.0.{version}/com.soa.repository.custom.jar to a temporary directory (such as /tmp/unpack_com.soa.repository.custom.jar)
    [akana@lxc3-pm8x-6 ~]$ mkdir /tmp/unpack_com.soa.repository.custom.jar
    [akana@lxc3-pm8x-6 ~]$ unzip /opt/akana/plat8/lib/lifecyclerepository_8.0.0.00339/com.soa.repository.custom.jar -d /tmp/unpack_com.soa.repository.custom.jar/
    Archive:  /opt/akana/plat8/lib/lifecyclerepository_8.0.0.00339/com.soa.repository.custom.jar
       creating: /tmp/unpack_com.soa.repository.custom.jar/META-INF/
      inflating: /tmp/unpack_com.soa.repository.custom.jar/META-INF/MANIFEST.MF
       creating: /tmp/unpack_com.soa.repository.custom.jar/com/
       creating: /tmp/unpack_com.soa.repository.custom.jar/com/soa/
       creating: /tmp/unpack_com.soa.repository.custom.jar/com/soa/repository/
       creating: /tmp/unpack_com.soa.repository.custom.jar/com/soa/repository/custom/
       creating: /tmp/unpack_com.soa.repository.custom.jar/com/soa/repository/custom/jsps/
       creating: /tmp/unpack_com.soa.repository.custom.jar/com/soa/repository/custom/jsps/custom/
      inflating: /tmp/unpack_com.soa.repository.custom.jar/com/soa/repository/custom/jsps/custom/i_005fhome_jsp.class
       creating: /tmp/unpack_com.soa.repository.custom.jar/META-INF/spring/
      inflating: /tmp/unpack_com.soa.repository.custom.jar/META-INF/spring/resource-registration.xml
       creating: /tmp/unpack_com.soa.repository.custom.jar/WebContent/
       creating: /tmp/unpack_com.soa.repository.custom.jar/WebContent/WEB-INF/
      inflating: /tmp/unpack_com.soa.repository.custom.jar/WebContent/WEB-INF/web.xml
       creating: /tmp/unpack_com.soa.repository.custom.jar/WebContent/custom/
      inflating: /tmp/unpack_com.soa.repository.custom.jar/WebContent/custom/custom.css
      inflating: /tmp/unpack_com.soa.repository.custom.jar/WebContent/custom/i_footer.jsp
      inflating: /tmp/unpack_com.soa.repository.custom.jar/WebContent/custom/i_home.jsp
      inflating: /tmp/unpack_com.soa.repository.custom.jar/WebContent/custom/i_support_info.jsp
      inflating: /tmp/unpack_com.soa.repository.custom.jar/WebContent/custom/logo.png
       creating: /tmp/unpack_com.soa.repository.custom.jar/WEB-INF/
      inflating: /tmp/unpack_com.soa.repository.custom.jar/WEB-INF/web.xml
  2. Modify/add the custom content in /tmp/unpack_com.soa.repository.custom.jar per the specific Customize topics below
  3. Update the MANIFEST to export any new packages being included (in the Export-Package: portion of the MANIFEST using a comma-separated list of packages such as):
    Manifest-Version: 1.0
    Ant-Version: Apache Ant 1.9.2
    Created-By: 1.7.0_75-b13 (Oracle Corporation)
    Bundle-Vendor: Akana
    Bundle-ClassPath: .,WebContent/
    Bundle-Version: 8.0.1.00384
    Bundle-Name: Akana Custom Branding
    Bundle-ManifestVersion: 2
    Bundle-Description: Custom branding plug-in
    Import-Package: com.soa.jsp;version="8.0.1",com.soa.transport.http.dep
    loy;version="7.0.0",com.soa.transport.http.deploy.impl;version="7.0.0
    ",javax.servlet;version="2.4.0",javax.servlet.http;version="2.4.0",ja
    vax.servlet.jsp;version="2.1.0",javax.servlet.jsp.tagext;version="2.1
    .0",org.apache.jasper.runtime,org.eclipse.gemini.blueprint.context;ve
    rsion="2.0.0",org.osgi.framework;version="1.5.0",org.osgi.service.htt
    p;version="1.2.0"
    Export-Package: org.apache.http.impl.client,x.y.z 
    Web-ContextPath: ${com.soa.repository:repository.config.contextRoot}
    Bundle-SymbolicName: com.soa.repository.custom
    Bundle-RequiredExecutionEnvironment: JavaSE-1.7
  4. Pack up the contents back into a new copy of com.soa.repository.custom.jar, being mindful to preserve the original directory structure!
    [akana@lxc3-pm8x-6 unpack_com.soa.repository.custom.jar]$ zip -r /tmp/com.soa.repository.custom.jar_011317 *
    updating: META-INF/ (stored 0%)
    updating: WEB-INF/ (stored 0%)
    updating: WebContent/ (stored 0%)
    updating: com/ (stored 0%)
      adding: META-INF/MANIFEST.MF (deflated 50%)
      adding: META-INF/spring/ (stored 0%)
      adding: META-INF/spring/resource-registration.xml (deflated 69%)
      adding: WEB-INF/web.xml (deflated 70%)
      adding: WebContent/custom/ (stored 0%)
      adding: WebContent/custom/i_support_info.jsp (stored 0%)
      adding: WebContent/custom/custom.css (deflated 41%)
      adding: WebContent/custom/i_footer.jsp (stored 0%)
      adding: WebContent/custom/logo.png (deflated 1%)
      adding: WebContent/custom/i_home.jsp (stored 0%)
      adding: WebContent/WEB-INF/ (stored 0%)
      adding: WebContent/WEB-INF/web.xml (deflated 70%)
      adding: com/soa/ (stored 0%)
      adding: com/soa/repository/ (stored 0%)
      adding: com/soa/repository/custom/ (stored 0%)
      adding: com/soa/repository/custom/jsps/ (stored 0%)
      adding: com/soa/repository/custom/jsps/custom/ (stored 0%)
      adding: com/soa/repository/custom/jsps/custom/i_005fhome_jsp.class (deflated 53%)
  5. Copy that new version to {platform_home}/instances/{container_name}/deploy/ (as com.soa.repository.custom.jar)
    [akana@lxc3-pm8x-6 /tmp]$ cp /tmp/com.soa.repository.custom.jar_011317 /opt/akana/plat8/instances/lm/deploy/com.soa.repository.custom.jar
  6. Restart that container
    [akana@lxc3-pm8x-6 ~]$ /opt/akana/plat8/bin/shutdown.sh lm
    Instance [lm] PID [4571] stopped
    [akana@lxc3-pm8x-6 ~]$ /opt/akana/plat8/bin/startup.sh lm -bg
    Starting instance [lm]

Customize the Web Page Branding Image (Top Banner)

You can customize the banner on the top of all web pages with your own branding information. This configuration is global, which means it will be in effect for all libraries on your installation.

Note: The styles in this document may override the global defaults. For example, the style sheet entry "A:hover { COLOR: #FFFFFF; TEXT-DECORATION: underline; }" will override the hover link color for the whole page.

  1. Create an image file for your banner

    If you want to have your own banner, you need to supply an image file. The image file can be any image format accepted by html (e.g. .gif, .jpeg, .png, etc). Store the image file in the com.soa.repository.custom.jar (/WebContent/custom/).

    Note: When you create a new image file, you must update the com.soa.repository.custom.jar (/META-INF/spring/resource-registration.xml) with the path to the image file.

  2. Create (or update) the custom.css file

    The brand banner is configured via a cascading style sheet (.css) located at - com.soa.repository.custom.jar (/WebContent/custom/custom.css). If the .css file does not exist, you can create the file using the options and values and the example .css file below.

  3. Copy the modified com.soa.repository.custom.jar to {platform_home}/instances/{container_name}/deploy/

    There are many references to .css files in the internet. Here is one web site that has information on general .css topics http://www.htmlhelp.com/reference/css/ and a page of color references http://www.htmlhelp.com/reference/css/color-background/background-color.html

    Basic Options and Values:

    #brand

    These sections apply to the background and image file (.gif, .jpeg, etc) for the top banner (header)

    • height: this value should be chosen to accommodate the actual size of the image (a height not greater than 75px is recommended).
    • background-image: URL("path-to/imagefile") where the path/imagefile is relative to the ApplicationRoot/customer/logidex.war/custom directory
    • background-repeat: determines how a specified background image is repeated (default is no-repeat)
    • background-color: sets the background color behind the image. color value format is #xxxxxx, where xxxxxx is a hex string specifying the color in RGB.

    Example custom.css file

    This example shows configuration of the library banner.

     #brand {
            height: 50px;
            background-image: url("MyBrand.gif");
            background-repeat: no-repeat;
            background-color: #339933;
         } 

The footer of each web page can be customized as needed for your installation. You may want to add additional information for terms of use, privacy, help desk contact information, etc.

To customize the footer pages, create the following html files in com.soa.repository.custom.jar (/WebContent/custom/) following the instructions above for "Customize the com.soa.repository.custom.jar" topic.

  • i_footer.jsp

This file can be customized using standard html syntax.

Note: The styles in this document may override the global defaults. For example, the style sheet entry "A:hover { COLOR: #FFFFFF; TEXT-DECORATION: underline; }" will override the hover link color for the whole page.


Customize Home Page Content (Web Browser Application)

You can customize the content presented on the home page of the web browser application. The area available for custom content falls below the web page Top Banner and above the Active Project designation on the home page. This configuration is global to this installation, which means it will be in effect for all libraries on your installation.

  1. Create a jsp file named i_home.jsp with your custom content.
  2. Save this file to the com.soa.repository.custom.jar (/WebContent/custom/) per the instructions above for "Customize the com.soa.repository.custom.jar" topic.

Customize Support Center Page

You may customize the content presented on the Support Center page of the web browser application. The area available for custom content is the Support Information section. This configuration is global to this installation, which means it will be in effect for all libraries on your installation. Library Administrators and Usage Controllers continue to see the default information.

  1. Create an html file named i_support_info.jsp with your custom content.
  2. Save this file to the com.soa.repository.custom.jar (/WebContent/custom/) per the instructions above for "Customize the com.soa.repository.custom.jar" topic.

You may change the target for the top navigation bar "Discussion" and "Help" links. This configuration is library-specific and can be different for each library.

  1. Access the Support Center page
  2. Click Configure Library
  3. Enter your desired URL's into the Help URL and/or Discussion URL fields
  4. Click Save at the bottom of the page

Customize Context Sensitive Help Pages

You may add text to the body of context sensitive Help pages by modifying the existing Help templates (which you will obtain from the {platform_home}/lib/lifecyclerepository_8.0.{version}/com.soa.repository.webapp_8.0.0.jar; in its WebContent/common/help/CustomContent/ directory).

  1. Unpack com.soa.repository.webapp_8.0.0.jar to a temporary directory
    [akana@lxc3-pm8x-6 ~]$ mkdir /tmp/unpack_com.soa.repository.webapp_8.0.0.jar
    [akana@lxc3-pm8x-6 ~]$ unzip /opt/akana/plat8/lib/lifecyclerepository_8.0.0.00339/com.soa.repository.webapp_8.0.0.jar -d /tmp/unpack_com.soa.repository.webapp_8.0.0.jar/
    Archive:  /opt/akana/plat8/lib/lifecyclerepository_8.0.0.00339/com.soa.repository.webapp_8.0.0.jar
       creating: /tmp/unpack_com.soa.repository.webapp_8.0.0.jar/META-INF/
      inflating: /tmp/unpack_com.soa.repository.webapp_8.0.0.jar/META-INF/MANIFEST.MF
      ...
  2. Navigate to the unpacked Help templates
    [akana@lxc3-pm8x-6 ~]$ cd /tmp/unpack_com.soa.repository.webapp_8.0.0.jar/WebContent/common/help/CustomContent
  3. Follow the steps in Customize the com.soa.repository.custom.jar in which you will unpack a copy of com.soa.repository.custom.jar. This is where you will copy in your customized Help templates.
  4. Customize the content in the <body> </body> of the appropriate HTML templates.
  5. Save the updated HTML templates to the temp directory (that you unpacked the com.soa.repository.custom.jar in) to its /WebContent/custom/help directory. Create the directory, if necessary. This is a different location from where you most likely copied the templates from (which was WebContent/common/help/CustomContent).
  6. Pack up the new com.soa.repository.custom.jar and copy it to your container's deploy/ directory

Using different languages

Lifecycle Manager can be configured so the user can select what language to display its contents. Contact Support for information on which languages are available and how to configure them.


Deploying custom class files

In certain instances, such as creating custom listeners, deploying custom class files is required. This is accomplished by adding your class files to the com.soa.repository.custom.jar (/) following the instructions above in the "Customize the com.soa.repository.custom.jar" topic. You'll need to ensure the package information is preserved in the class file's path. For instance, suppose you have a class named com.example.CustomListener.

It will need to be added to the com.soa.repository.custom.jar file as /com/example/CustomListener.class. Here is an example of the required steps:

  1. Create a directory called /tmp/com/example
  2. Copy the class file to the /tmp/com/example directory
  3. cd to the /tmp directory
  4. Run the following to update the deployed com.soa.repository.custom.jar with the new directory structure containing the new class file(s).
    jar uvf {platform_home}/instances/{instance_name}/deploy/com.soa.repository.custom.jar com/example/CustomListener.class
    ...as an alternative to using the above jar uvf command, you could unzip the com.soa.repository.custom.jar file to a temp directory, add the relevant com/example/CustomListener.class structure, then zip it backup (making sure to preserve the directory structure)...

Some custom classes are cached by the application in the database so, when replacing a custom listener class with an updated version, it's best to reload the LPC in any libraries where your custom listeners will run. See the commands GetCurrentProcessConfiguration and SetProcessConfiguration in the Commands section of this document.


Saving files in UTF-8

One needs to be concerned with saving files that have non-ASCII characters. There are several different encodings that one can use to safely preserve extended characters (UTF-16, UTF-8, etc). Lifecycle Manager use UTF-8 encoding in various places throughout the application. Most of these issues should be transparent to the end-user, but some should be noted. Wherever input takes the form of an XML file, the XML file has a declaration for specifying the encoding. Even if it is not specified, the default encoding is UTF-8 and the document will be interpreted as being encoded as such. It is recommended to leave this set to UTF-8 and ensure that your file is saved in UTF-8.

Most XML files displayed to the user will be preserved as UTF-8 if they are saved using the browser's File -> Save As option. Do not copy and paste this text from the browser to a text editor unless you know the text will be preserved as UTF-8 encoded without a BOM (byte-order mark).

Also, if overviews are uploaded using Automation Extensions, they should be encoded using UTF-8.

It is very easy to mess up a file by saving it in the incorrect encoding. Therefore these instructions should be used anytime you save a file containing non-ASCII characters.

  • Notepad: Choose the File menu, then Save As. Under the Encoding dropdown, select UTF-8 and save the file.
  • WordPad: WordPad does not handle UTF-8 encodings, use Notepad instead. WordPad does have a Unicode option, but unfortunately this is UTF-16, not UTF-8.
  • Vim: Some UNIX systems have an enhanced version of VI installed called Vim. Use the command ":set encoding=utf-8" when saving your file.
  • Visual Studio: Choose the File menu, then Advanced Save Option. In the Encoding dropdown, select Unicode (UTF-8 without signature) - Codepage 65001.

User License Report

A User License Report is included which you may link to in an appropriate group of your choice. The report provides a list of all users on the installation and the libraries to which each user has access. Create the report link as follows:

  1. Log into a library as a Usage Controller
  2. From the Home page, click Manage Reports
  3. Click Add Report for an appropriate group or project where you would like all users to see this report link
  4. Enter a meaningful name and description
  5. Enter the URL: {your server host}/lm/birt/run?__report=/reports/AdminUserLicense.rptdesign&database_schema_name=
  6. Note: the value for the database_schema_name parameter is optional unless you connect to the database as a user other than the schema owner.

Managing Reports

Customers may use the BIRT Eclipse tool to create custom reports and deploy those reports to the application server to be available to application users. Beginning in RM and PortM 6.3.1, BIRT reports are managed using the Configuration Designer plug-in. The report design files appear in your configuration project under Document-Source -> reports. Custom reports may be saved to this folder and uploaded to the library via the context menu.

Once a report has been uploaded to the library, follow the steps below to create the report link.

For version 6.7 installations, follow these steps once a report is ready to deploy:

  1. Be sure to replace the datasource property in your report design with the datasource used in Akana's standard reports. Compare the XML report designs for details.

Create the report link as follows:

  1. Log into a library as a Usage Controller
  2. From the Home page, click Manage Reports
  3. Click Add Report for an appropriate group or project where you would like all users to see this report link
  4. Enter a meaningful name and description
  5. Enter the URL: {your server host}/{context root}/birt/run?__report=/reports/{your report name}&database_schema_name=
  6. Note: the value for the database_schema_name parameter is optional unless you connect to the database as a user other than the schema owner.