Vine Web

This chapter includes information on Vine Web installation and configuration. In addition, it gives advice on solving problems probable to appear when using Vine Web.

To plan the installation and configuration of Vine Web, you need to have a general understanding of how Vine Web works. Information most important for you is presented below.

Vine Web Architecture

Vine Web is a web application that serves dynamic content to the user’s Web browser. It is implemented using the JavaServer Pages (JSP) technology which provides a way to efficiently prepare web content, such as HTML, on the web server side using the dynamically retrieved database data.

Vine Web adheres to the JSP 1.1 specification which means that it should run on any platform under any web server or web enabled application server with JSP 1.1 or higher support.

Figure 1. Vine Web interface to the Vine Server

JSP pages combine standard HTML tags with the additional JSP tags and Java code for server-side processing. Vine JSP pages execute database queries to the Vine database and prepare dynamic HTML pages which are then transferred to the client web browser.

Vine Web Installation & Configuration

To install Vine Web you have to:

Check that you have Vine Database Server installed and properly configured.

Check that you have necessary Java and JSP infrastructure in place.

Install necessary Vine Web components to the web server.

Install Vine Web support to the Vine database server.

Provide your users with login information.

Using Tomcat

Vine Web under Tomcat

Jakarta Tomcat is a JSP engine that can work as a standalone web server or can be installed as a JSP extension to a web server which has no built-in support for JSP, such as Microsoft Internet Information Server (IIS) or Apache. This configuration combines the fastest delivery of static HTML content by the web server, with the Tomcat's JSP support. Thus it won't slow down the performance of an existing web server, but will redirect all JSP requests to Tomcat:

Figure 2. Vine Web installed under Tomcat

If you are going to choose Tomcat JSP environment then you can check the following section which includes useful web links using which you can download the needed software.

Vine Web under Tomcat installation checklist

Java SDK

Java SDK 1.6.x or higher for your platform must be installed and configured on the computer where Vine Web will be installed. It is recommended to use the Java JRE included in the Vine Web MSI installer.

You can download Java SDK from:
http://java.sun.com/j2se/

Apache Tomcat

Apache Tomcat 7.0.41 or higher (it is recommended to use the Tomcat version included in the Vine Web MSI installer) must be installed and configured on the computer where Vine Web will be installed. You may want to configure it to work with a web server. This can provide for better Vine Web performance especially for Tomcat running on Linux. You can download the latest production release of Tomcat and check its installation instructions at:
http://tomcat.apache.org/index.html

Vine Web

Vine Web is a web application and is distributed as a .war file archive (vineyard.war). There are different ways of installing a web application under Tomcat. For instance, you can simply place the .war file into the "webapps" subfolder of the Tomcat folder and restart Tomcat.

You can download the vineyard.war file from the support section of the Vine International web site:

https://vine.eu

You can find more information about .war files and how to install them under Tomcat at:

http://jakarta.apache.org/tomcat/

After you have installed Vine.war you should edit Vine Web settings which are stored in the vyconfig.xml file.

JDBC connectivity to Oracle

A JDBC driver should be installed in order to provide connectivity to the Oracle server where the Vine database is installed. You must use the driver appropriate for your platform and Oracle's version. JDBC OCI drivers may perform a bit better but they need Oracle client installation. JDBC thin drivers do not need Oracle client installation. You can check more details at:
http://otn.oracle.com/software/tech/java/sqlj_jdbc/content.html

Vine Web uses the Vine database server running under the Oracle server specified in the vyconfig.xml file located at CATALINA_HOME\webapps\Vine\web-inf location. By default, Vine Web assumes that the Oracle server is located on the same computer, uses the 1521 port and the default Oracle instance (ORCL). If that is not true in your installation, please change connsStr manually: it must contain the correct IP address (or host name), the Oracle port number and the used Oracle instance name, for example:

<param-name>connStr</param-name>

<param-value>jdbc:oracle:thin:@127.0.0.1:1521:orcl</param-value>

If needed, check the acceptable format with the specification of the driver you are going to use.

Vine Web server support

The users will be able to access Vine data through Vine Web only after you have entered your Vine Web license key and added users to the Vine Web Users license group using Vine Server Setup.

A Vine Web user with administrator rights (a member of the “Vine Web Administrators” group) can add Vine Web users using the Vine Web Administrator’s Console.

Note: If you want new Vine users to be able to work with a custom object set, then you have to run Vine Object Manager and reassign the user group to the object set. That will cause Object Manager to assign all the users of the group the rights on that object set.

Vine Web URL

Create and test the URL you are going to provide your users with. The URL will depend on your Tomcat configuration:

http://<webserver_name_or_ip>/<Vine_folder_name_under_tomcat>/

By default, Tomcat creates the folder named "Vine" from the Vine.war file. The start Vine Web page is index.jsp, but there is no need to add it to the URL since Tomcat loads it automatically.

Using Tomcat Realm security

If needed, you can additionally limit access to some Vine Web resources (URL patterns) by using Tomcat’s container managed security. The web.xml configuration file of Vine Web declares a security constraint (“Vine Security Constraint”) and authentication method to protect access to several Vine Web plug-ins.

The default Tomcat configuration enables UserDatabaseRealm which has user permissions assigned in $CATALINA_HOME\conf\tomcat-users.xml. You can add a realm user who will be able to access the plug-ins defined in the Vine Security Constraint by declaring a role specified in the Vine constraint and adding a user with that role. For example:

<tomcat-users>

…

…

</tomcat-users>

You will need to restart Tomcat to activate the changes you have made to the file.

You can customize or disable altogether this additional Tomcat UserDatabase realm protection by editing the Vine Security Constraint.

Single Sign On(SSO) and Windows Authentication

Single Sign On with Vine Web means that if the user has already logged into a domain allowed by Vine Web then Vine Web opens without asking for username and password when the user enters an address of Vine web in the browser.

Vine Web supports the Negotiate (SSO), the NTLM and its own form based authentication modes.

Enabling Windows Authentication

To enable Windows authentication you have to set windowsAuthentication to TRUE in vyconfig.xml

Setting Allowed Domains

Domains allowed for windows authentication should be listed (comma separated) in the allowWindowsDomains setting in vyconfig.xml. If the list is empty, any domain is allowed.

Negotiate mode

The Negotiate mode means that the browser will pick either Kerberos or NTLM. Please note however that you can't make the browser to only use Kerberos.

Internet Explorer: If you want to use Negotiate mode, make sure that Enable integrated Windows Authentication is selected in the browser (In Internet Explorer 10: Tools->Internet Options-> Advanced tab: Security section). This enables “Negotiate”.

Firefox: add the Vine Web URL(web address) to network.negotiate-auth.trusted-uris (Type 'about:config' in the address bar and press enter to get the list of Firefox configuration settings).

NTLM

If needed, you can prioritize the use of NTLM for all or specific users:

For Internet Explorer users: The user can clear Enable integrated Windows Authentication which will make the browser to not try to use Negotiate (SSO) and it will try to use NTLM.

Firefox: add the Vine web URL to network.automatic-ntlm-auth.trusted-uris

SSO in ASP(MyVine) Mode

In the ASP mode, SSO requires a special plugin installed for Firefox (please ask from the Vine Support). If Internet Explorer is used then the zone security settings must be set to Low to allow ActiveX.

Troubleshooting SSO

For SSO to work, Internet Explorer and Google Chrome must think that the site is located in the Local Intranet zone. Automatic rules of detection if it is an intranet sometimes do not work (for example, if the server name has dots in it) and you have to explicitly add it to Local Intranet and/or disable "Automatically detect intranet network".

You can change these settings, used by both Internet Explorer and Goggle Chrome, on the Security tab of the Internet Options dialog.

Click Local Intranet and then Sites

Click Advanced to add the site to the local intranet zone if needed.

Tomcat normally should be running as a service under Local System.

In case of custom environments and configurations you have to use the setspn.exe utility and make sure that you have the Service Principal Name(s)(SPN) set correctly. Also it is worth noting that Kerberos heavily relies on correct and consistent functioning of DNS and name resolving.

In case, a user wants to use a special server name to connect to Vine web, it is possible to use the hosts file records, like :

192.168.0.30 Vineweb.domain.com vine

Here the full DNS name takes precedence over short name and makes sure IE constructs the proper SPN. (Provided there is correct SPN record in AD set for Vineweb.domain.com)

If you need to login as another user, not the one you are logged to windows domain you can remove the site from the trusted and then the login dialog will be displayed

Domain Authentication

Users can login to Vine Web with their Windows domain account from any computer on the Internet by providing their Windows username and password:

No special browser configuration normally needed from users.

Other Settings

Vine Web and the Administrator’s console use some other settings stored in vyconfig.xml and AC_Newuser.properties which you can find in the WEB-INF folder of Vine Web installation. Here is a full list of all the settings you need to configure:

Setting	Default value	How to set	Setting location
allowWindowsDomains		A comma-separated list of allowed windows domain names. Keep empty to allow all.	vyconfig.xml
adminUserName	Vinedb	Almost always this must not be changed.	vyconfig.xml
adminUserPass	PASSWORD	Change to the Vineyarddb password you set in Vine Server Setup	vyconfig.xml
ASPuse	no	Normally, should not be changed.	vyconfig.xml
notifyAdminEmail	admin@company.com	If the email address of the current Vine person who is using the Console is empty then the Console will use this address when sending notification emails.	vyconfig.xml
oracleDataSource	FALSE	FALSE: Vine web connection pool used, max 3 connections per user, usually slower than (b) recommended to use in case there are many users (estimated limit is >= 17) TRUE : Oracle connection pool used, faster = real asynchronous, can create as many connections as needed for speed (limited only by total pool size, which is one for all users), must be used in cases when there are not so many users (estimated limit is < 17)	vyconfig.xml
smtpServer	mailserver.company.com	Set to the smtp server address that the Console should use for sending emails	vyconfig.xml
smtpServerAuth	FALSE	Set to TRUE if your smtp server requires authentication	vyconfig.xml
smtpServerAuthUsername	smtp_username	Set username for smtp server that requires authentication	vyconfig.xml
smtpServerAuthPassword	smtp_password	Set password for smtp server that requires authentication	vyconfig.xml
smtpServerUseSSL	FALSE	SMTP SSL usage: smtps (TRUE) OR smtp (FALSE) protocol	vyconfig.xml
session-timeout	20	Timeout in minutes after which inactive user session disconnected	web.xml
adminName	Vine Administrator	Name used in emails if can’t get name of current user	AC_Newuser.properties
subject	Vine login information	New user email subject	AC_Newuser.properties
msg	Full text in AC_Newuser.properties.	Email body. Tags as <FIRSTNAME> are substituted with real data.	AC_Newuser.properties
useXmlInsteadOfAdminEmail	FALSE	TRUE: notifyAdminEmail used always. FALSE: the current administrator user email used (notifyAdminEmail used only if the current administrator user does not have email address)	vyconfig.xml
windowsAuthentication	FALSE	Enables Windows authentication	vyconfig.xml

Supporting Vine Web Users

Users

The users need only a web browser and a correct URL to connect to Vine Web.

After the installation of Vine Web, the users must be added to the Vine Web license group maintained in the Vine database.

For new Vine users, you have to create corresponding Vine accounts using Vine Web Administrator’s Console. You should provide new users with their Vine usernames and passwords.

Existing Vine users can continue using their current Vine usernames and passwords.

Providing Users with Login Information

After you have got everything ready for the users to work with Vine Web, you have to provide them with the following data:

Vine Web URL

Vine Username

Vine Password

Windows domain authentication and Single Sign On

SSO (Single Sign On). Set windowsAuthentication to TRUE in vyconfig.xml to enable it. Vine Web will not ask the user for username and password if the user has already logged in to a Windows workstation in the same domain with Vine Web.

Microsoft domain authentication. Set windowsAuthentication to TRUE in vyconfig.xml to enable it. The user will be able to login to Vine Web from any computer in the Internet by providing the Windows domain username and password.
Please note that special browser configuration might be needed for the browser to show a special popup login dialog. If the dialog does not show up then please add the Vine Web address to the Local Intranet Zone and select Prompt for username and password in Local Intranet Security Settings (Use the Custom level button)->User Authentication->Logon.

Vine Web Administration

After you have installed Vine Web and provided your users with the URL, you will only have to make modifications in accordance with wishes of the users.

Administration Console

Please refer to the section Vine Web Administrator’s Console for detailed information about the Administration Console

Tools Tab

The Tools tab in Vine Web lists plug-ins of the type URL installed in the Vine database.

Today Page

You can customize the following functionality of the Today page.

Today pane

Company messages list. The list shows events included in a special collection which can be configured using the System Setup Wizard available from the Vine Web Administrator’s Console.

To-Do pane

If an object type has a parameter field of type "Phase", then it should have the corresponding parameter table which includes available phases. Each phase has the "InToDoList" attribute which specifies whether the objects in this phase will be shown on the To-do page when they are connected to the current user.

Use Vine Web Administrator’s Console : Edit Parameter Values to set a phase to be shown.

Note that you can set multiple phases to be shown in the To-Do list and that you have to select Show in To Do List for at least one phase if you want Vine Web to add the corresponding object list to the To-Do page.

For example: The Projects list on the To-Do page shows projects connected to the current user under condition that those projects are in one of the phases set in the VY_PROJECTPHASE table by the “inToDoList” field. Usually the projects in the ‘Active’ phase are shown.

Timeout Setting

By default, a Vine Web session is closed if there is no user activity for 20 minutes. You can change this setting using the web.xml file. Find the definition of the "session-timeout" parameter and change its default setting. Restart the web server.

If you are using Tomcat, you can find web.xml at
CATALINA_HOME\webapps\Vine\WEB-INF

Troubleshooting Vine Web

Login Problems

If trying to connect to Vine Web, you do not get the Login screen then it is most probable that you entered the wrong Vine Web's address (URL). Please, consult your Vine administrator about the correct URL.

Invalid Username/Password

If, after you have entered the user name and password and clicked Login, you see an error message instead of the Vine Web desktop, then you should first check your username and password. If it doesn't help, consult your administrator.