Lifecycle Manager System Administrator Guide

Information for the person filling the role of Installation Administrator, after the initial installation is completed.

For system requirements and installation instructions, see Installing Lifecycle Manager.

Table of Contents

The following topics are covered in this system admin guide:

General

• Introduction
• Administrator Accounts
• Admin Console for the Installation Administrator
• Commands You Can Run from the Admin Console

Configuring the application

• Installation Settings
• Configuration Designer
• Setting up native LDAP password policies
• Setting up group and role support in LDAP
• Setting up SSL
• LM behind a Load Balancer (cluster)
• LM behind a Reverse Proxy/Load Balancer that terminates SSL
• CSRF Security for Lifecycle Manager
• Update Installation-wide Properties
• Single Sign-on (SSO) Install and Configuration
• Customize user attributes and LDAP attributes
• Full-text artifact search
• Customize the com.soa.repository.custom.jar
• Customize the Web Page Branding Image (Top Banner)
• Customize the Footer for all Web Pages
• Customize Home Page Content (Web Browser Application)
• Customize Support Center Page
• Customize Top Navigation Links (Web Browser Application)
• Customize Context Sensitive Help Pages
• Using different languages
• Deploying custom class files

Start/Stop and Service Packs

• Starting and Stopping Servers
• Installing Service Packs

Log Files and Logging

• Log Files and Logging Levels

Creating Libraries and Import/Export Assets

• Creating Additional Libraries
• Download assets or upload assets automatically

Other

• Database Administration
• Backing up and Restoring the Application and Data
• Reset System Passwords
• Adding a Library User
• Super User
• Reset a User Password
• Saving files in UTF-8
• User License Report
• Managing Reports

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.

For an overview of the hardware and software installation requirements and detailed instructions on installing the base servers and product, refer to Installing Lifecycle Manager.

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, contact Akana Support.

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.

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.platform.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.platform.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://owasp.org/www-community/attacks/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 in which no data is returned to the attacker. 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 CSRF filtering, use the configuration category com.soa.repository.csrfguard, available in the Akana Administration Console when the Akana API Platform Repository Plug-In is installed. This category contains one property, com.akana.lifecyclemanager.owasp.csrfguard.Enabled. By default, this is set to false; to enable CSRF filtering after a system reboot, set this property to true.

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
  • For Oracle, use the Oracle sqlplus client.
  • 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 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:

• Assets
• Attribute Definitions
• LDAP Group Role Definitions
• Documents
• Templates (version 6.3.1)
• Email
• Export/Import
• Installation Configuration
• Licensing
• Library Configuration
• Logging
• Policy Manager
• Other

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:

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.

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;
        } 

Customize the Footer for all Web Pages

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.

Customize Top Navigation Links (Web Browser Application)

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.