j5 Administration Manual V2.doc

J5 Administrator Manual

j5 Administrator Manual

St James Software

22 Hillside Rd.

Fish Hoek 7975

October 4th, 2007

Table of Contents

J5 Administrator Manual.....................................................................................................11 Introduction.......................................................................................................................6

1.1 Features......................................................................................................................61.1.1 Ajax.....................................................................................................................61.1.2 Open-source Facilities........................................................................................71.1.3 Industry-Standard Support..................................................................................71.1.4 Industrial Process Management Modules...........................................................71.1.5 j5-based Off the Shelf Applications...................................................................71.1.6 Further Information............................................................................................8

2 Getting Started..................................................................................................................82.1 Configuring the System.............................................................................................8

3 QuickLog Configuration...................................................................................................83.1 Overview....................................................................................................................9

3.1.1 Starting QuickLogs...........................................................................................103.1.2 Configuration Files...........................................................................................113.1.3 CSS Files..........................................................................................................11

3.2 Creating a new Logbook..........................................................................................123.3 General Configuration.............................................................................................123.4 Toolbar Positioning.................................................................................................133.5 Grid Specifications..................................................................................................133.6 Audit Logs...............................................................................................................143.7 Shift Definitions.......................................................................................................143.8 Field Specifications.................................................................................................153.9 Option Management................................................................................................183.10 Field Displays........................................................................................................19

3.10.1 Small View.....................................................................................................193.10.2 Large View.....................................................................................................20

4 Architecture....................................................................................................................224.1 General.....................................................................................................................23

4.1.1 j5 Applications..................................................................................................234.1.2 j5 Standard Applications Overview..................................................................234.1.3 Template Server................................................................................................244.1.4 Python and Kid.................................................................................................264.1.5 Resources..........................................................................................................27

4.2 Folder Organization.................................................................................................284.2.1 Python25 Folder................................................................................................28

4.3 Configuration Files..................................................................................................284.3.1 Location of the Configuration Files..................................................................284.3.2 Structure............................................................................................................29

5 Advanced Configuration.................................................................................................305.1 Special items............................................................................................................30

5.1.1 Getting Started..................................................................................................305.1.2 Authorizations...................................................................................................315.1.3 Sub Logbooks...................................................................................................355.1.4 Special Components.........................................................................................37

5.1.5 Weblinks...........................................................................................................445.1.6 Typical Functions.............................................................................................455.1.7 Shift Reports.....................................................................................................475.1.8 Overlays and Templates...................................................................................48

5.2 Control of the Tabs..................................................................................................495.2.1 Default Behaviour.............................................................................................495.2.2 Providing Titles and Tooltips...........................................................................505.2.3 Controlling the order of the tabs.......................................................................505.2.4 Moving second level tabs to the top row..........................................................505.2.5 chenlogbook.collapsetabs = True.....................................................................50

5.3 Database Interactivity..............................................................................................505.3.1 Database Connection Configuration.................................................................505.3.2 Using the TableSchemas.py file.......................................................................525.3.3 SQL type functions in the business rules..........................................................535.3.4 Adding Database Fields to the Template Form................................................54

5.4 Presentation..............................................................................................................555.4.1 j5 Designer (In development)...........................................................................555.4.2 Types of Presentation.......................................................................................565.4.3 Form defaults....................................................................................................585.4.4 Formatting the Data..........................................................................................615.4.5 Repeating Sections in the Template.................................................................615.4.6 Genshi...............................................................................................................625.4.7 Specifying the css files.....................................................................................66

5.5 Business Rules.........................................................................................................675.5.1 j5 Hooks............................................................................................................675.5.2 Special Fields....................................................................................................725.5.3 Historical Information......................................................................................745.5.4 Filtering and Sorting.........................................................................................755.5.5 Scheduled Tasks...............................................................................................75

6 Administration................................................................................................................766.1 Documentation.........................................................................................................766.2 Requirements...........................................................................................................76

6.2.1 Operating System..............................................................................................766.2.2 St James Software.............................................................................................766.2.3 Database Software............................................................................................766.2.4 Web Server Software........................................................................................776.2.5 Real-Time Connection to Process Devices.......................................................776.2.6 Optional Software Items...................................................................................776.2.7 Client Requirements.........................................................................................77

6.3 Large Installation.....................................................................................................776.3.1 Downloading.....................................................................................................776.3.2 Installation........................................................................................................786.3.3 Configuring Apache..........................................................................................806.3.4 Restarting the web servers................................................................................836.3.5 Configuring the Site..........................................................................................846.3.6 LDAP................................................................................................................85

6.4 Installation...............................................................................................................866.4.1 Standalone Installation......................................................................................866.4.2 Batch Installation..............................................................................................88

6.5 Upgrades and Site Files...........................................................................................896.5.1 New Release Install..........................................................................................896.5.2 Site Install.........................................................................................................896.5.3 Database Install.................................................................................................90

6.6 Starting the server....................................................................................................906.6.1 Standalone Version...........................................................................................906.6.2 Apache Version................................................................................................90

6.7 The Server Admin Application................................................................................906.8 Setting the j5 Port Number......................................................................................91

6.8.1 j5 Port Number.................................................................................................916.8.2 Server Admin Port Number..............................................................................91

6.9 System Status Overview..........................................................................................916.10 Application Monitoring.........................................................................................926.11 Backing Up and Restoring.....................................................................................93

6.11.1 Backing Up the j5 System..............................................................................936.11.2 Restoring the j5 System..................................................................................936.11.3 Partial Backups...............................................................................................936.11.4 Restoring Tables.............................................................................................936.11.5 Creating a Customer Site................................................................................94

6.12 Monitoring the Resources......................................................................................956.12.1 Database Monitoring and Management..........................................................956.12.2 Storage Resource............................................................................................96

6.13 User and Group Management................................................................................976.13.1 Group Definitions...........................................................................................976.13.2 Configuring a Group.......................................................................................976.13.3 Give the new Group Access to the Tables....................................................1006.13.4 Provide advanced (rule based) permissions for the tables............................1006.13.5 Advanced Permission Modifications by directly setting the config files.....1016.13.6 Adding column specific rights......................................................................102

6.14 User Management................................................................................................1036.14.1 Users.............................................................................................................1036.14.2 Adding a User to the New Group.................................................................1036.14.3 Setting or changing the Password.................................................................1036.14.4 LDAP Configuration....................................................................................103

6.15 Version Control...................................................................................................1036.16 Licensing..............................................................................................................103

6.16.1 Automatic Log Off.......................................................................................1046.17 Languages............................................................................................................105

6.17.1 Steps required in a project............................................................................1056.18 Advanced Administration....................................................................................1066.19 Error and Trace Files...........................................................................................107

6.19.1 Viewing the Error and Trace Files................................................................1076.19.2 Location of Error and Trace Files.................................................................107

6.19.3 For apache systems.......................................................................................1076.19.4 Error Procedures...........................................................................................1086.19.5 Debugging via Error Messages.....................................................................1086.19.6 Running as a standalone...............................................................................109

6.20 Troubleshooting...................................................................................................1096.20.1 Canonical URLs............................................................................................1096.20.2 Logging In....................................................................................................1096.20.3 Remote Connections.....................................................................................110

1 IntroductionThe St James Software j5 system is an Industrial Development System. In addition to a set of hardened industrial applications that function in a zero client mode, the j5 System can be used to develop clean, maintainable, agile database-driven applications for the industrial corporation.

Ease of Application Development: New applications can be created quickly and serve a large number of users in a rugged environment.

Layout: The layout of the application is designed using standard html and css files. Components: There is a wide range of industrial components available that can be plugged into the template.Parameterized support: Parameters may be created (via the template) and stored in the database. Client-Side Interaction: The AJAX engine provides a rich user experience without the need to contact the host computer. This layer is also user programmable.Server-side Business Rules Programmatic Engine: In addition to a comprehensive range of server side components (e.g. User management facilities, scheduler facilities, tag management facilities etc.) the user can create the business logic quickly using the powerful Python scripting language. Additionally, core software changes can be made quickly via the St James Software Custom Override Facility.Database Interaction: There is a powerful, easy to use application interface to the database so that developers can manage the data section of their application.

1.1 Features

1.1.1 AjaxUnlike form-based Zero Client systems, j5 uses an AJAX engine. Whilst retaining all the advantages of Zero Client Architecture, the AJAX based systems handles many of the user interface tasks (such as

http://www.sjsoft.com/technicalpapers/ZeroClientIntro.htm

http://en.wikipedia.org/wiki/AJAX

formatting, input verification, menus, tag management etc.) without having to communicate with the server. This provides a much more satisfying user interface that is comparable with resident applications. (Note: most Zero Client applications are form based. I.e. the user submits a form and waits for the server to respond to the form. Depending on the speed of the connection, form based systems do not give the fast response that AJAX based systems can give.)

1.1.2 Open-source FacilitiesThe j5 Architecture gives users an unprecedented amount of open-source support through the various levels of the structure. End users can create solutions almost entirely using the open source options. For example: Operating System: Linux, Databases: Postgres, My SQL, Languages: Python, Javascript, Web server: Apache and jServer, j5 framework: jToolkit (includes AJAX engine, database access software, database access components, scheduler), Browsers: Firefox and others.

Open-source solutions are the only effective hedge against vendor dependency and commercial exploitation.

1.1.3 Industry-Standard SupportIn addition to the open-source support, j5 also supports industry standards; ensuring that end users can line up with their corporate standards. I.e. in addition to the open source support, J5 also supports the following standards: Operating System: Windows variants, Databases: Oracle, SQL Server, Access, Languages: C++ for the jHistorian engine, Web server: IIS (Under development): Browsers: Internet Explorer.

1.1.4 Industrial Process Management Modulesj5 includes a comprehensive array of industrial process modules that become part of the tailored application. These modules include parameterized business modules as well as widget support in the application front end. Developers can quickly configure these modules to meet their requirements or override the business rules with their own rules. j5 provides support for the following modules: Date/Time/Shift management and event tagging, Operating Area, Tag Management, User Management, Auditing facilities, Special Industrial Searching and Filtering Modules, Real-time and Historical data collection and Viewing, Scheduling management, Process Monitoring, Support Center Management, Alarm Management, Parameterized Configuration Data Management, Spreadsheet Support, Report printout support.

1.1.5 j5-based Off the Shelf ApplicationsThere is a rapidly growing portfolio of Industrial Applications that are based on the j5 development platform. These applications exhibit all the benefits of the j5 architecture. I.e. Zero client, industrial hardened, configurable and customizable, AJAX rich user interface and open source framework. Among the applications currently supported or being developed are the following: Operating Log Books, Order Books, Knowledge Base, Down Time Manager, Historical Trend Viewer, Shift Report Manager, Permitting Software, Process Support Center, Help Desk and others.

Typical Application Creation Scenario

To create a new application, an application engineer will:

· Create the application template (the front end of the application) using a standard html application like Dreamweaver,

· Add ready made components to enrich the presentation of the front end (or create new components based on the existing ones)

· Add ready made components to the server side application (or create new modules to satisfy any special requirements)

· Test the application and notify the end users of the URL for the new application.

1.1.6 Further InformationFor further information on the j5 application and application development framework, please contact St James Software at [email protected], or contact us directly.

2 Getting StartedTo run the system, you will need to:

· Install the system as a standalone web server or as an apache web server. (See the Administration Installation section)

· Have a system configured for your site or have the demo system. (The demo system is normally attached to the initiation e-mail from St James Software)

· Have a valid license

· Have started the j5 web server. (see the Administration section on Starting the server.)

Once you have started the web server, you connect to the web server as follows:

Apache System

· From a web browser (Internet Explorer or Firefox) enter the url:http://<nameOfServer>

· You will see the j5 welcome screen.

· Enter the user name and password. (For the demo, this is admin and test.)

Standalone System

· From a web browser (Internet Explorer or Firefox) enter the url:http://<nameOfServer>:8080

· You will see the j5 welcome screen.

· Enter the user name and password. (For the demo, this is admin and test.)

Note: If you want to change the port that you are to connect to, (from the default of 8080,) enter this line in the config.local configuration file.

web.default.port = 8082

Where in this case, 8082 is the new port number.

2.1 Configuring the SystemGenerally, you will configure a new system as follows:

· Create the basic system using the QuickLog Configuration

· Add User Permissions using the User and Group Management section in the Administration section.

· If you want Advanced features, then use the Advanced Configuration section. (We recommend this mainly for people who have completed the Advanced Training.

3 QuickLog ConfigurationNote that the wiki based QuickLogs documentation at http://projects.sjsoft.com/wiki/Reference/QuickLogs is the definitive documentation. This section will not be as up to date as the wiki based docs and should only be read as a general guide.

http://www.sjsoft.com/company/contact.htm

mailto:[email protected]

3.1 OverviewThe preferred method of configuring the logbooks is via the Quick Logs Configuration System. Essentially, this is a "fill-in-the- blanks type of configuration that is accessed via the Logbook screen itself.

The diagram below shows how the QuickLogs configuration functions.

Functionality

· A system configuration person fills in the blanks in the QuickLogs user interface.

· The QuickLogs system makes changes to the Global and Local Configuration Files.

· The j5 System uses the changes in the Configuration Files as the basis of the Logbooks or other applications.

· The j5 System then accesses the database and provides information to the Users' Browsers via the Web Server.

Special Notes

· The Configuration Files may be edited directly to achieve the same results. It is recommended that only people who have undergone the training sessions do this.

· The QuickLogs system can be used to create logbooks that meet the vast majority of requirements. In the event that there are special requirements, then the Configuration files and the underlying Templates and Business Rules can be modified to meet these special requirements.

· The QuickLogs system does not interact with the j5 System, it is purely a window into the configuration files.

Areas not covered by QuickLogs

The following areas are not covered by Quick Logs:

User Management: This is covered in the System Administration Manual

Database Connectivity: This is also covered in the System Administration Manual

Special Requirements: Features such as LDAP, Emailing, Historical Storage, 3rd part Interfacing etc. are not covered by the Quick Logs System.

3.1.1 Starting QuickLogsChoosing the QuickLogs Tool

You can use the QuickLog system to configure the Logbooks using:

· The QuickLogs Application by clicking on the QuickLogs tab at the top of the screen (if you have admin rights.) This enables you to edit all the logbook configurations.

· The Designer link at the top of each logbook. (If you have designer rights.) This gives you access into the configuration of a single logbook.

To start QuickLogs from the QuickLogs Tab

· Click on the QuickLogs tab at the top of the screen. (if you have admin rights.)

· Click on the Link to the Logbook you want to edit.

To start QuickLogs from the Designer link in a Logbook:

· Click on the Logbook tab for the Logbook you want to re-configure,

· Click on the Designer label next to the Logbook name, (See Below)

Using the QuickLog Editor

· The QuickLogs Main Page will apear. (See Below)

· Start editing the configuration. (You open (and close) the different sections by clicking on the icon next to the link.)

· When you have finished making the Configuration Changes, click on the Save Logbook link.

3.1.2 Configuration FilesThe QuickLog system will write to the following files:

In the root folder (e.g. in c:\sjsoft-j5\customers\demo_1.6)

· global.config

· local.config

In the application folder (e.g. in c:\sjsoft-j5\customers\demo_1.6\Logbooks)

· <yourLogbookName>_quicklog.kid

· <yourLogbookName>.config

You may also add: (e.g. in c:\sjsoft-j5\customers\demo_1.6\Logbooks)

· <yourLogbookName>.py to add business rules to the new logbook.

3.1.3 CSS FilesYou can choose any of the styles defined in the jlogbook.css file. The QuickLog system uses the file sjslogbook.css in the folder:

c:\program files\sjsoft-j5\sjsoft\Apps\Logbook\css folder.

The available styles in this css file will be increased to provide more options.

3.2 Creating a new LogbookTo create a new Logbook, you need to have access to the QuickLogs tab at the top of the screen.

Creating a new Logbook

· Click on the QuickLogs Tab:

· Enter a name for the new logbook in the New Logbook field.

· Click on the Create button.

· Restart the Logbook. (You need to restart the application (either the service or the executable)

· TODO: Work on this documentation at this point.

Cloning a Logbook

· Click on the QuickLogs Tab:

· Enter a name for the new logbook in the Clone Logbook line.

· Click on the Clone button.

· Restart the Logbook. (You need to restart the application (either the service or the executable)

· Log in again, you should see the new Logbook in the tab. (The logbook will be pointing at a new table called <nameOfNewLogbook>. For example, in the example above, it will point at the table called MyLogbook.>

· Restart the application.

3.3 General ConfigurationThis section specifies various general items of information relating to the logbook.

Name: Typically you will have a number of logbooks in a system. This is the name that will differentiate between these logbooks.

Tab Title: What you want to appear in the Tab.

Application Title: The title that will appear when you move the cursor over the tab. Also, the Browser will show this as the title of the page.

Modify Timestamp Field: This is the field in the logbook table which will be updated with the current time when a modification of the log occurs.

Disabled: If this is a logbook within another logbook (I.e. a sublogbook), then you should set the logbook to disabled. (This means there will be no tab to click on to activate the logbook. If you want the logbook to have an associated tab, then select False for Disabled.

3.4 Toolbar PositioningThis section is used to define the position of the tab in the toolbar.

In this example, the tab is located in the 2nd level toolbar and it is located 4th from the left hand side of the menu.

3.5 Grid SpecificationsThis section allows the user to specify various critical parameters relating to layout of the grid (table presentation) in the logbook.

Grid Based: If you set this True, then the presentation of the logbook will be in a Grid or Tabular form. (This is generally the most useful format.) If you specify False, then the logbook will consist of a series of rows that are not contained in a table or grid.

Has Expand/Contract Modes: This refers to the ability to have two views of the same information. I.e. a Small (Compact) view and a Large (Expanded) view.

If you select False, then the logbook will consist of a number of Large View Rows which do not expand/contract.

Small View

Large View

Grid View Editable: This refers to the ability to edit the unexpanded logs. Often, you will only want the user to edit the logs when they are expanded, however, for example, if you set the "Grid Expand/Contract" to False, then you should set the Grid View Editable to True.

User Permissions Note: To control who can actually make the changes, you will need to modify the permissions of each user group as described in the User Management section.

3.6 Audit LogsThe logbook provides an Audit Log as a standard facility. When a log is deleted, the "deleted logs audit" will list the deleted log. This log can become quite long if there are a large number of deleted records. You can define the number of logs that appear in this list using the field below.

3.7 Shift DefinitionsIn process control systems, the management of shifts is important. This section provides enables you to specify the details of the shifts for the particular logbook.

Clicking on the icon next to the Shifts Heading, will open the following section.

Shift-Based: If the logbook is Shift-Based (True), then this configuration will be a Shift Type Logbook. In this case, each page will only show the log associated with a given shift. For example, if the user clicks on the Logbook Tab, then only the log associated with the current shift will be displayed. Clicking on the previous link will show the log associated with the previous shift etc. The system will also ensure that there is only one log per shift.

If the logbook is not Shift-Based (False), then the logbook will be a conventional logbook and the number of logs per page will be fixed. (Typically 20 logs per page.) Operators may add logs at any time of the day and there is no limit to the number of logs per day.

Shift Configuration

Even if this is not a Shift Type Logbook, the shift information may still used in the system. (For example, to populate the shift fields in a logbook.) This section is used to define the specifics of the shifts.

Number of Shifts: The number of shifts per day. Typically there are 2 or 3 shifts per day. (For a day type logbook, enter a 1.) The system assumes that the shifts are all of the same duration. E.g. if you specify 3 shifts, the system assumes thy are each 8 hours duration.

Start of Day: This is the starting time of the first shift of the day. (Note that although the QuickLogs system does not support abnormal types of shifts, (e.g. the first shift for the day starts at 11pm on the previous day or there are 2 shifts over the weekend and 3 during the week), the j5 system can be made to easily cater for these through the use of business rules.)

Shift Names: The names of each of the shifts that will be automatically added to the logs in the shift calculations.

3.8 Field SpecificationsIn this section, the fields for the Logbook (and in fact the fields in the Logbook table) are defined.

Each field can exist in either or both of the small view and the large view.

Clicking on the icon shows the existing fields in the current logbook. Clicking on the icon next to the field will show all the details of the field.

To add a new field to the Logbook:

Click on the Add Field Link. A screen similar to the screenshot below will appear.

Field Name: Enter the name of the field. It should be lowercase and not have any spaces in the name.

Data Type

Field Type: Choose from the following options as follows:

Text: is for a standard text field. For example, a single string of information.

Attachment: is a field where a pointer to an attachment will be stored.

Combo: is a field that has a fixed number of options which will be presented to the user to choose from in a combo box. The options entry area will show up below the field entry section if you choose combo. (See the next section Option Management)

Datetime: is a field where a date time will be stored. (The system will only accept a date time field)

Textbox: is a field where it is expected to store a large amount of text data which will normally be displayed in a multi-line text box.

Weblink: is a field where a link to another website (a URL) will be stored.

Field Data Type: This is where you can specify what kind of storage the field should be.

Field Data Size: This is the number of characters that make up the field.

Data Constraints: You can specify what constraints should be imposed on the data in this section.

Default Value:

None: There will be no default value set when a new record is added.

Value: If you select the Value radio button, then you will see a screen similar to the following.

Enter the default value in the space provided.

Special: You can also specify that the default value is defined as one of the special fields as shown below:

In this example, we want the default value to be populated by the shift name (as defined in the section Shift Definitions above.)

Required or Optional: If this is required, a record may not be added if the field has not been populated.

Format: If you require the data to be formatted (both when displayed and also when entered), then you would specify the format here. The format can be specified using the accepted options.

The formatting string is of the form [flag][width].[precision] [formatcode] where:

flag is one of -, +, blank, # and 0

width refers to the total width of the string and precision refers to the number of characters after the decimal point. (* to specify that an integer argument gives the actual width or precision)

formatcode must be one of the following: c, s, i, d, u, o, x, X, e, E, f, g, G, r,

Here are some examples:

High and/or Low Constraints: You can constrain the value to be entered by either a high constraint, a low constraint of both.

(Click on the Value Radio Button, then click on the High or Low Limits and enter the values for these constraints.)

3.9 Option ManagementIn this section, you can define the options (and their characteristics) for a given field.

Adding Options: Click on the Add option link and add the options for this field. The field in the upper box is the name of the option. The value that will appear to the user in the combo box is shown in the Value Field. If the user chooses this option, then the Value in the Value box will be displayed.

In the example above, the values m1, m2 and m3 will be displayed as options when the combo box is clicked.

Option Order: The order of the options from top to bottom when the combo box is clicked are defined in the Option Order. In the example above, the order will be m1, m2, m3.

If no order is specified, then the order will be alphabetic.

3.10 Field DisplaysThese sections define the presentation of fields in the Logbook. In particular, they define which fields are shown, where they are positioned and how the fields are styled.

There are currently two kinds of presentation:

· Small View: Generally a single line per row of information and

· Large View: A multi-line form usually displayed as an expansion of the single line view.

3.10.1 Small ViewThe Small View of the logs is generally a single line per record. (See Below) By clicking on the Expand or Edit link, the record is expanded to show the Large View.

The configuration of the Small View is carried out via the Small View Section shown below:

Positioning: Here you list the fields as they appear in the view. In this example, the fields are Actions (this is there always and you do not list it) then logdatetime, event, followup and j5username.

Adding Fields that are relevant to the Small View:

Click on the Add Field to Small View Link and choose the field from the drop down list.

Label: Enter a Label for the field if it is different to the Field Name. This Label will appear at the top of the grid.

Attributes: Enter any attributes (e.g. special formatting attributes) for the update. E.g. you can add style attributes to the information.

Cell Attributes: Enter any cell attributes for this field. For example, you can add a style from the css style sheet. In the example below, you can see the update attributes and the cell attributes.

In this example, the cell class is set to the sjs-c45 class (See CSS Files) and the width is set to 35%.

Note: The options relating to a field are specified in the database section.

3.10.2 Large ViewThe Large View of the logs is generally the form that opens when the Expand or Edit link in the small view is clicked. (See Below)

(If you are using the "Has Expand/Contract Modes : False", then the large view will appear on the main screen without having to click on the Expand or Edit links.)

The configuration of the Large View is carried out via the Large View Section shown below:

Positioning: The fields are arranged in a matrix of rows and columns. In the example above,

Row 1: Fields are logdatetime, event, priority, and j5username. Note that in fact there are two columns in the grid for every field since the columns support the label as well as the value. For example, in this case, there are 4 fields and 8 columns to the grid.

Row 2: The first column is shift and the next 6 columns are occupied by the followup field. (one field for the label and 5 for the actual field.)

Row 3: The first column is the reportdatetime and the next 6 columns are again occupied by the followup field. (one field for the label and 5 for the actual field.) The followup field therefore occupies two rows of 6 cells each.

Note that the attachment field is always present and does not need to be specified.

Adding Fields that are relevant to the Large View:

Click on the Add Field to Large View Link and choose the field from the drop down list.

Label: Enter a Label for the field if it is different to the Field Name. This Label will appear at the top of the grid.

Attributes: Enter any attributes (e.g. special formatting attributes) for the update. E.g. you can add style attributes to the information.

Cell Attributes: Enter any cell attributes for this field. For example, you can add a style from the css style sheet. In the example below, you can see the update attributes and the cell attributes.

Note: The options relating to a field are specified in the database section.

4 ArchitectureWhen building applications in j5, it is important to understand how to use the server architecture. This page provides details of the architecture and examples of working within it.

_Overview

1. All programs are divided into Applications (which are program logic) and Resources (which are things that programs do to influence things outside of themselves)

2. The key driving force behind this architecture is to provide a way for multiple Applications (or one complex Application) to reuse Resources in an easy way, be able to switch Resource back-ends and not have to be aware of any of it.

3. Reusing resources eg. - Two applications are running, and they both have tasks that need to be scheduled. They ask for a scheduler from the Server. The Scheduler Resource passes them an

interface they can use to access the one running scheduler, so for both applications only one scheduler runs.

Switching resource backends eg. - An application needs a database. The type of database can be changed just by changing the backend which supplies the Database resource. This can be done in the Server, and the Application never even needs to know.

Configuration

Configuration for the server resides in a configuration file, but the main method of configuration is a web interface on a specific port. This interface relies on the modules controlling Resources and Applications (the ones in the Plugin directory) to be able to specify how they should be configured and what the options are.

The target here is that a user should be able to start a Server without a configuration file at all, go to the admin interface, and set up everything they need in a user-friendly way.

4.1 General

4.1.1 j5 ApplicationsCurrently, the following standard applications exist in j5.

Logbook

Shift Report

Database Viewer

Server Admin application

j5 Data Reactor (OPC connection and spreadsheet parser)

Each of these applications can be used as the basis for multiple applications. For example, a site may comprise several different logbooks for different areas and several shift reports.

4.1.2 j5 Standard Applications Overview

The j5 System Install includes a number of Standard Applications. Among the applications are:

1. The Database Viewer: A web based application that can be used to view and edit the database tables referenced in the j5 Resource file. The same application can be used to alter the structure of the tables. (For example to add new fields.) Currently the application will connect to MS Access, MS SQL Server, Oracle and MySQL.

2. The j5 Scheduler: This is a general purpose scheduler that uses an extended “cron” command set. Applications such as the j5 Procedure Book and the j5 Historian use this application to sequence their tasks. It can also be referenced from Hooks within other applications.

3. The j5 Logbook: This application is suitable for general purpose logs that can be added at any time of the day. It can be configured using the internal web- based editor.

4. The j5 Shift Log Application: A Shift Log type of application is identical to a standard kind of j5 Logbook application with the exception that each page refers solely to the events that take place in the time period specified by the duration of a nominated shift.

5. The j5 Data Reactor: This application is suitable for historizing process information (usually from an OPC source) into a database or a csv file. In contrast to many commercially available

historians, instead of using hard coded algorithms, the j5 Historian can be end-user customizable using chains to achieve specific historical collection objectives.

Additional Facilities: In addition to the Standard Applications, additional facilities are also available (or are under development) as follows:

· Facility to read and write information to spreadsheets,

· Facility to email information to nominated recipients,

· Facility to display process tag information,

· Facility to send commands such as Inserting of Logbook entries via a remote procedure call using SOAP

· Facility to use LDAP type authorization.

· Facility to use high performance web servers like Apache.

· Reporting facility. (Selecting records from a shift and collating the records.)

4.1.3 Template ServerThe j5 system is a template server application. The diagram below shows the main components of the system.

A URL is received by the web server from a browser application like Internet Explorer or Firefox. The URL contains the application and template information. The web server activates the relevant application and the application loads the associated template. At this point, any Business rules are executed and any

components are loaded. In addition, any data is retrieved from the database and added to the template which is then sent in standard html format to the browser that requested the information.

This page summarizes how to create the html so that the j5 system renders the Genshi file to meet your objectives.

Form Definition

The data input should be in a form as follows:

<div id="logform">



</div>

The logform id tells the logbook to interpret the following form like a logbook form. I.e. repeat the form, show options like edit etc.

You do not need to create a different form for the viewing area. The same form will be used for both viewing and editing. (The j5 system will just change the inputs to spans when in view mode.)

Simple Inputs

Often, you will need to input simple text values and often these will be in a cell table. For example,

<td>

<strong><input type="text" name="logdate" /></strong>

</td>

j5 uses the name of the input to link the variable with the column in the nominated database table. In the above example, the text entered into this field will be stored in the logdate column in the nominated table.

Combo (Pull Down) Boxes

Use the select ststement to implement a combo box. For example,

<td>

<strong><select style="width: 100%; background-color: rgb(204, 255, 255);" name="shift">

<option value="Morning"> Morning </option>

<option value="Afternoon"> Afternoon </option>

<option value="Night"> Night </option>

</select></strong>

</td>

j5 will render this code as a combo box with the options Morning, Afternoon and Night. It will write the selected value to the shift column in the nominated table.

Text Areas

Here is an example of a textarea in a j5 Genshi template:

<td valign="top" colspan="1" style= "background-color: rgb(255, 255, 153);" rowspan="2">

<textarea cols="85" name="followup">

</textarea>

</td>

This tells j5 to create a textarea in a table cell and place the edits into the column called followup.

Skipping Inputs

Sometimes, you don't want the j5 system to write the data into a column in the table. (For example, when the variable is to be used for something in the business rules or hooks.) In this case, you can add the skip=”true” token in the tag. For example:

<textarea cols= "85" name="dontstorethis" skip="true">

</textarea>

In this case, the text area will be treated as a simple textarea and it will not be stored in the database table.

4.1.4 Python and KidThe j5 server expects to find the business rules in the <application>.py file written in the Python language. Attributes in the template can be defined in the “Python- like” Genshi language.

If you are familiar with Python, we suggest you try the j5 “10 minute Database Tutorial”. This will give you a good idea on how the system fits together from a programmers perspective.

PythonNot only is Python a powerful language, it is also pleasure to learn. (One of the design requirements of Python was that it should be enjoyable to use!). It is also interpretive. I.e. you can type a command in and immediately see the results. To learn more about the Python Language, we would recommend trying the Python Tutorial on the Python Web Site.

Because the Python language is so powerful and easy to use, you will find the business rules are often created in a few minutes and comprise a few lines. Initially, you may want to just browse or tailor the business rules but later you may want to create your own business rules.

http://www.python.org/

For j5 users, another important benefit is that the data structures in the business rules are also available in the templates themselves. For example, if you create a dictionary of users in a business rule, then you can use the same structure (using the Genshi language) in the template.

Here is a python function which creates an array of 24 timeslot dictionaries to be used by a template:

def gettimeslots(startdate):

slots = []

for hour in range(24):

slotdate = startdate + datetime.timedelta(hours=hour)

datestring = slotdate.strftime("%Y-%m-%d %H:%M")

slot = {"date": slotdate, "datestring": datestring, "target_name": "targ%d" % slotdate.hour}

slots.append(slot)

return slots

The Genshi attribute language is basically a subset of Python that can be embedded in a template and used to present dynamic html pages. (It is a subset so as to maintain the security of the system.) If you understand Python, you will have little difficulty understanding Genshi.

In addition to the Genshi language being a subset of the Python language, the data structures created in the business rules (in Python) are also available to the Genshi language in the template.

Here is an example of a Genshi directive in an html file.

<tr py:for="slot in timeslots">

<td width="15%">

<div align="right" py:content="slot.datestring">9:00AM

</div>

</td>

</tr>

This code will add a new record into a table for every “slot” in the dictionary “timeslots” which has been created by the python business rule.

Note that the py:for=“slot in timeslots” directive in the template has a python equivalent in the business rules that looks like this: for slot in timeslots:

4.1.5 ResourcesCurrently j5 supports the following resources:

· authentication

· components

· database

· emailer

· ldap

· logging

http://kid.lesscode.org/

· reports

· rpcclient

· rpcserver

· schedule

· storage

· web

· opc

Each resource is available to the applications to achieve specific functionality.

4.2 Folder OrganizationTo maintain the j5 system, it is important to know where the relevant files are located.

Configuration Files

These are typically laid out in the following format:

SiteFolder Application1Folder

Application2Folder

cssFolder

In the site folder, there is the config file. (Where the system configuration parameters are stored.) and the license files.

In the Application there are typically many template files (.Genshi files) and many business rules files (.Genshi files)

In the css folder, there are styling files. E.g. sjs.css.

4.2.1 Python25 Folder.This folder contains all the python files that make up the application. These include:

sjsoft Folder Application specific files are resident here.

j5 Folder Base j5 files are resident here.

Other Folders E.g. the search algorithm, the Routes manager etc.

Apache folder (If applicable). Contains the files relating to the Apache web server. Note that it is not necessary to know where the key files are because you can reach them from the program files- >apache menu item.

4.3 Configuration Files

4.3.1 Location of the Configuration FilesTypically, the configuration file is located in the j5 home folder. Typically the application configurations are located in child folders under this configuration folder.

Often there are two configuration files:

A config.local (which is specific to the machine) and

A config.global which will work on any machine.

This enables a configuration to be developed on one machine and moved over to another machine.

4.3.2 StructureIt is important to know how a Server configuration file is put together. Here is an example with one application using one resource:

schedule.default.provider = plugin.Scheduler

database.sqlite1.provider = plugin.SQLite

database.sqlite1.databaseName = "/tmp/mydb.sqlite"

database.access1.provider = plugin.Access

database.access1.username = "admin"

database.access1.databaseName = "c:\mydb.mdb"

test1.type = module.Control.test_Scheduler.ScheduleDriver

test1.database.default = database.sqlite1

test1.database.historydata = database.access1

test1.schedule.task1.function = module.Control.test_Scheduler.funcTest

test1.schedule.task1.minute = "0,30"

test1.schedule.task1.hour = "12"

test1.schedule.task1.dayofmonth = "*"

test1.schedule.task1.month = "1-12/2"

test1.schedule.task1.dayofweek = "mon- fri"

The format is as follows:

· Resources are configured under their provides() name. Seen is a default-set “schedule” resource and two configured “database” resources.

· Any top-level node which has a “type” attribute is an Application. The value of this attribute specifies the function or class which will handle configuring the Application, requesting all the resources, etc. Here, there is one Application called test1.

· When an application asks for a resource, its settings are read. The application can ask for a named resource (database “backup”) or the server will pick the default setting (database “default”). If the application has no such setting, the Server will look for a top- level default configuration (e.g. the schedule).

· The configuration information for an application (e.g. the “test1” node) is passed to the handling class intact - the only parts of interest to the Server are the “type”attribute and anything that looks like resource settings. The Server sets an extra attribute get_resource, through which an Application can request resources.

There are two special types of values for nodes:

· Starting with “plugin.” specifies a module to be imported from the Plugin directory (situated in the running directory of the Server).

· Starting with “module.” specifies a module which can be imported in a normal Pythonic way.

For further details about how the Application should deal with its configuration, please refer to Writing Applications.

http://dev.sjsoft.com/wiki/j5/application/creation

http://dev.sjsoft.com/wiki/j5/application/creation

5 Advanced Configuration

5.1 Special items

5.1.1 Getting Started

Creating an Application

The easiest way to create the j5 Template or application template is to copy an existing one e.g. from the logbooks folder and rename it.

The main elements you need in the template include the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns:dbsync='http://www.sjsoft.com/dbsync' xmlns:py=

'http://purl.org/Genshi/ns#' xmlns="http://www.w3.org/1999/xhtml">

<head>

//Any head information//

</head>

<body>

//The body of the application.//

<form>

//The form where data is entered and displayed//

</form>

</body>

</html>

Note: that you will need to replace the text above that is in the double // signs with the information specific to the form.

Note: that the html file must be in the form of xhtml standard. I.e. each directive must have closing directive.

UserOnce you have created the new html file, you need to add the form and table permissions to the user groups that will use the template, (see the section User and Group Management in the Administration section of this manual) so that it will appear in the tabbed area and so the users can select and run the application.

To add your application to the portfolio:

· Save the template (generally a .Genshi or .html file) in the j5\templates folder.

· Save any business rules (these rules will reside in a .py file) associated with the template in the same folder. (The file name should be the same as the template name but with a py extension.)

· If you have any specific css files associated with the application, save these in the css folder.

Once you have saved these files, you may access the application from the j5 main menu without having to restart the j5 server. You can also modify the files and enhance the capabilities of the application while the files are in the system.

5.1.2 Authorizations

Using the Server Admin PagesThe section User and Group Management in the Administration Section of the Manual describes how you can add Users and Groups using the Server Admin Pages.

Editing the Config File.

ApplicationsBasic Form and Application definition.

chenlogbook is j5.Control.ServerConfig.ApplicationNode

chenlogbook.type = "sjsoft.Apps.Logbook.Logbook.LogbookApplication"

chenlogbook.web.default.baseurl = "chenlogbook"

chenlogbook.web.default.title = "Other Logbooks"

genoplogbook.web.default.tooltip = "DCS, Abnormal and Car Seals Logbooks"

chenlogbook.users is j5.Config.OverlayNode.OverlayNode

chenlogbook.users.overlay = "users"

In this we define the type and characteristics of the application.

The application will appear on the Server Admin page ?

· In the local config file, set the folder to be used for this application. I.e. in cheniere.config.local

chenlogbook is j5.Control.ServerConfig.ApplicationNode

chenlogbook.logbooksdir = "c:/docs/j5-tortoise/j5- trunk/customers/cheniere/Logbooks"

Special Note:If you want to have an application displayed, it must have the disabled line in the business rules file either set False or commented out. I.e.

# disabled = True

or

disabled = False

TabsIn the event that there are more than one application under an application, then sub tabs will automatically be generated.

Forms (Design and SortBy)You can modify the forms rights from the Server Admin -> Advanced page or directly in the config files. I.e.

OR in the config files:

# Default Cheniere Logbook Form Rights

chenlogbook.forms.dcs.rights.view = True

chenlogbook.forms.WorkPermit.rights.view = True

chenlogbook.forms.Issues.rights.design = True

chenlogbook.forms.Issues.rights.view = True

You can have multiple forms for an application. The application will create a top level tab, if there is more than one form in an application, it will create sub-tabs (one per form).

Note: If you specify the default rights as view, and you want to prevent a user group from seeing that form, then you specify the specific rights for the usergroup to be false. For example:

chenlogbook.forms.InspectionTemplates.rights.view = True

specifies that every on can see the InspectionTemplates form however:

groups.operators.forms.InspectionTemplates.rights.view = False

overrides this, preventing the operators group from seeing the InspectionTemplates form.

TablesYou can modify the table rights directly in the config file. here is an example of a table rights specification:

chenlogbook.tables.asset.rights is j5.Database.Config.TableScopeRights.Loose

chenlogbook.tables.asset.rights.all.A = True

chenlogbook.tables.dcs.rights is j5.Database.Config.TableScopeRights.Loose

chenlogbook.tables.dcs.rights.all.A = True

chenlogbook.tables.issues.rights is j5.Database.Config.TableScopeRights.Loose

chenlogbook.tables.issues.rights.all.A = True

Note that you can also modify the tables rights from the Server Admin->Groups page. (This is the preferred way of doing it.)

ColumnsIndividual column rights can also be specified directly in the config files. I.e.

In this example, the dcsoperators group can view the issuedby column in the workpermit table, but they cannot change it.

groups.dcsoperators.tables.workpermit.rights.columns.issuedby is j5.Database.Config.TableScopeRights.Loose

groups.dcsoperators.tables.workpermit.rights.columns.issuedby.view.rule = True

groups.dcsoperators.tables.workpermit.rights.columns.issuedby.change.rule = False

Users and Groups# Create User List (activates app level authentication)

users is j5.User.Config.UserList.UserList

# User: admin

users.admin is j5.User.Config.User.User

users.admin.group = "groups.admin"

# Admin Group

groups.admin is j5.User.Config.Group.Group

# Authentication

authentication.default.provider = "ConfigAuthenticator"

authentication.default.users.admin.password = "098f6bcd4621d373cade4e832627b4f6" # admin password is "test"

Apps and Forms

groups.admin.apps.chenlogbook = True

Special case:

This is the Server Administration application:

groups.admin.apps._adminapp = True

Tables

Table Rights· Available table rights are: all, change, add, view

· All the sub conditions of a right are ORed together to determine if a user has access.

· Table rights can be made per-column by doing: columns.<colname>.<right type, e.g. all>.X = <... right clause ...>

· Valid table right clauses are True, False and "columnname = constant"

Examplesgroups.admin.tables.workpermit.rights is j5.Database.Config.TableScopeRights.Loose

groups.admin.tables.workpermit.rights.all.first = True

groups.operators.tables.gassamples.rights.modify.rule = "NOT samplestatus IN ('In Storage','Expired','Closed')"

Columnsgroups.operators.tables.orderbook.rights.columns.wrdesc is j5.Database.Config.TableScopeRights.Loose

groups.operators.tables.orderbook.rights.columns.wrdesc.view.rule = True

groups.operators.tables.orderbook.rights.columns.wrdesc.change.rule = False

groups.operators.tables.orderbook.rights.columns.message is j5.Database.Config.TableScopeRights.Loose

groups.operators.tables.orderbook.rights.columns.message.view.rule = True

groups.operators.tables.orderbook.rights.columns.message.change.rule = False

AuthenticationThere are two kinds of Authentication supported. I.e. Local Authentication and LDAP Authentication.

Local Authentication:j5 checks the password (which is stored in an encrypted form in the config file) against the password entered by the user. If they match, then the user is authenticated and allowed access.

Example:

authentication is j5.Control.ServerConfig.ResourceTypeNode

authentication.default.provider = 'ConfigAuthenticator'

authentication.default.users.amousselli.password = '40be4e59b9a2a2b5dffb918c0e86b3d7'

LDAP authentication:j5 passes the username and password to the LDAP system which returns a message confirming or denying that the user has been authenticated.

Example:

authentication.default.provider = "LDAPAuthenticator"

authentication.default.attrs.dc = "adtest.sjsoft.com"

authentication.default.secret_token_file = "/share/sjsoft/code/j5/customers/demo/ldap-secret.token"

ldap.default.provider = "ActiveDirectory"

ldap.default.uri = "ldap://192.168.10.219/"

5.1.3 Sub Logbooks

Create the sublogbookFirst create a normal logbook. (This will be the sublogbook) then:

· Create a table (you will need to know the linking fields)

· Create the py file

· Create the Genshi file

The logbook will consist of a record(s) with

<th>

<thead id="logtableheader">

<th>

etc

plus a single row of inputs:

</thead>

<tr id="logform">

<td>

<span py:replace="over_include('actions.Genshi', 'actions')"/>

</td>

<td class="inv-sublog">

<input type="text" name="starthr" />

</td>

The data row will be repeated in the main logbook.

· Make sure the form has the linking fields in it even if they are hidden. E.g.

<td class="inv-sublog">

<input type="text" name="tank6" />

<input type="hidden" name="j5username" />

<input type="hidden" name="valuedt" />

<input type="hidden" name="revision" />

<input type="hidden" name="logdatetime" />

</td>

Notes:

· Currently, you can't put calendar components into the sublogbook.

Create the Main Logbook

The py fileYou will need these main items:

from sjsoft.Apps.Logbook import SubLogModel

# In the init module

def __init__(self,*args,**kwargs):

super(LogModel,self).__init__(*args,**kwargs)

# Set up sublogs

logbookdir = os.path.dirname(os.path.abspath(dtovalues.__file__))

self.dtovalues = SubLogModel.SubLogModel(self.components, self.get_resource, dtovalues, "dtovalues", self.db, logbookdir, self.userfactory,

{"valuedt":"valuedt", 'revision':'revision'})

""" in this case, the linking fields are valuedt and revision. I.e. all sublogs that have the same valuedt and revision will be linked to the main log with the same valuedt and revision. Also, when a new sublog is added to the main log, it will set these fields (in the sublog record) to be the same value as the main log."""

# In the customise_context

def customise_context(self, context, action, components):

editing = action in [self.EDIT,self.ADD]

context["show_picker"] = editing

context["dtovalues"] = self.dtovalues.get_sublog(context, action)

# And the get_sublogpages module

def get_sublogpages(self):

"""Return a list of sublogpages which we pass changetable kwargs to."""

return self.dtovalues.get_sublogpages()

The kid fileAt a strategic place in the Genshi file (Not in a table)

</table><br /> 

<table>

...... normal expanded view of logs with multiple records.

</table>

</td>

</tr>

</table>

Explanation: The expanded view actually is shown within a single cell in the record that has an id called logform.

2/ In the py file,

import the sublog module with import <nameofsublogmodule>

and, in the LogModel class, add the function:

def get_sublogpages(self):

"""Return a list of sublogpages which we pass changetable kwargs to."""

return self.<nameofsublogmodule>.get_sublogpages()

Header in the Expanded View: If you would like a header in the expanded view, you can add the header information just before the table in the logform I.e.

<td colspan="n"> 

<div py:strip="not update_mode" class="updatewatcher expandview" updatetarget="${htmlid}"

updateurl="${me.url_for('editupdate',htmlid=htmlid)}"

updateargs="late_innerid=${htmlid}"

updatemode="${update_mode}">

<p>Entry for <b>${logid}</b>

<b py:if="infostr">${infostr}</b>

<span py:replace="over_include('actions.Genshi', 'actions')"/>

<span py:replace="auditlog(rowid=auditrowid)"/>

</p>

<input py:if="actionfield" type="hidden" name="${actionfield}" value="true" skip="true" />

<table>

remembering to add the </div> after the </table> at the bottom of the html.

AnnotationOften you will want users to add comments to a comment field and for each comment to be annotated. (Without giving the user the ability to modify previous comments.)

Here is an example of how this can be done:

1/ Create a field called new_opcomment. (This is the field the user will enter the new comment into.)

2/ In the py file, add a hook to append and annotate the opcomment field.

class MarkCommentHook(object):

def __init__(self, session):

self.session = session

def pre_addrow(self, argdict):

return (self._modify_row(argdict), )

def pre_modifyrow(self, argdict, rowid=None, limit=None):

return (self._modify_row(argdict), rowid, limit)

def _modify_row(self, row):

if "new_followup" in row and row["new_followup"].strip() != "":

currenttime = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")

row["new_followup"] = "%s (%s): %s" % (currenttime, self.session.user, row["new_followup"])

return row

** not forgetting to add the new hook in the list of hooks

sessiontablehooks = [SessionRowHook, MarkCommentHook]

5.1.7 Shift Reports(Often called Shift Logs or Handover Logs.)

In contrast to a standard logbook where logs are added at any time of the day, a shift log has a single record for a given period. (Typically there are 2 or 3 shifts per day.)

Shift logs are a special case of the standard logs. I.e. use a standard Logbook model but override it with the shiftpagemodel.

You will also need to specify various parameters in the py file. I.e.

# Shift log details

shift = True

shiftconfig = ConfigTree.Node()

shiftconfig.shiftstarttime = "04:00" # your starting time here

shiftconfig.numshifts = 1 # your number of shifts here

To understand better how to do this, please contact St James Software for an example.

5.1.8 Overlays and TemplatesSometimes you may want to refer to an html (kid) template and use it a number of other kid files.

Here is an example of moving the template out into another area, accessible by many apps.

Once the template is moved, and you make the changes, it affects all the logbooks that use it.

Template1/ Create the template from a working file and save it in a folder that is accessible by multiple apps.

In this example, we copied bare.kid into two folders higher in the tree and called it bare_template.kid

2/ Create spans for the various sections of the template file...e.g.


<tr id="bare_template_header">

.........

</tr>

</thead>

and

<tr id="smallview">

<span id="bare_template_smallview" py:strip="True">

..........

</span>

</tr>

and

<tr id="logform">

<span id="bare_template_logform" py:strip="True">

.........

</span>

</tr>

kid fieRemove all the code that is now in the template file and replace it with directors to the template. This simply includes the section templates in the html.I.e.

<tbody>


<tr py:replace="over_include('bare_template.kid','bare_template_header')" />

</thead>

<tr id="smallview">

<span py:replace="over_include('bare_template.kid', 'bare_template_smallview')" />

</tr>

<tr id="logform">

<span py:replace="over_include('bare_template.kid', 'bare_template_logform')" />

</tr>

</tbody>

py fileUse the filefinder class to select the template.

from j5.WebComponents import FileFinder

import os

class LogModel(CustomComponents.GwfLogModel):

def __init__(self,*args,**kwargs): self.components.filefinder.add_finder(FileFinder.SpecificFileFinder(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), "bare_template.kid"))

In this example, the file bare_template.kid is found 2 folders up in the tree.

5.2 Control of the Tabs

5.2.1 Default Behaviour· The system will create Tabs on the top level of the application for each of the Application

instances that are running in j5.

· The system will also create tabs on the second level of the tabs for each of the forms running in an application. For example, if you create a Logbook Application that has two forms: Maintenance and HelpDesk then when the Logbook tab on the top level is clicked, then two tabs Maintenance and HelpDesk will appear on the second level of tabs.

5.2.2 Providing Titles and TooltipsYou can override the Title of the tabs and also provide tooltips using the following directives in the config file.

orderbook is j5.Control.ServerConfig.ApplicationNode

orderbook.shorttitle = "Orders"

orderbook.title = "The Operator Orders Logbook"

This example will create the following tab structure:

5.2.3 Controlling the order of the tabsYou can set the order of the tabs using the navorder directive

In the business rules (.py file), add a directive as follows:

navorderkey = 1

This directive for example, would set the tab in the left most position.(After the Home and Log Off tabs)

5.2.4 Moving second level tabs to the top rowchenlogbook is j5.Control.ServerConfig.ApplicationNode

chenlogbook.type = "sjsoft.Apps.Logbook.Logbook.LogbookApplication"

.............

5.2.5 chenlogbook.collapsetabs = True

In this example, the forms that use the application will be displayed on the top level of tabs since we have set the collapsetabs directive to true.

Setting the tab names of formsOften you will have several logbooks running in a single application. In this case, you can set the tab names, tab descriptions etc. in the business rules program. (The .py file.)

e.g.

title = "General Operations"

shorttitle = "Operations"

5.3 Database Interactivity

5.3.1 Database Connection ConfigurationThe database connection details are typically held in the local.config file which is located in the customers\<nameOfSite> folder.

The system can connect to the following types of database: Oracle, MS SQL Server, MS Access, PostgreSQL and MySQL.

The applications communicate with the databases via the St James Software JToolkit application which is embedded in the j5 server.

Here is an example of the configuration for a SQL Server database:

DBNAME = 'ewv'

DBHOST = ""

DBUSER = "sa"

DBPASSWORD = ""

DBPROVIDER = "SQLOLEDB.1"

DBTYPE = "sqlserver"

These items are discussed in more detail here:

Configuring the database connection parameters

Customize the login information so that the system is aware of the database you intend using as described below.

· DBNAME: Enter the name of the database you are going to connect to.

Access: Simply the filename of the database. E.g. 'C:\\Program Files\\jLogbook\\jLogbookDemoV40.mdb'

SQL Server: The name of the database. E.g. 'Process1'

Oracle: The name of the database. E.g. 'LogBook'

· DBHOST: This is a SQL Server specific parameter. The host name of the computer in which the database is running. I.e. if SQL Server is running in a different computer, then you should enter the name of the computer host here. E.g. 'dbserver'. Note that if you are using the database in the same machine as the jLogBook application, or are using a database other than SQL Server, just enter the word None here without any enclosing hyphens.

· DBUSER: The name of the user login for the database that jLogBook will use to log in to the database. E.g. Access: the name would typically be 'Admin'.

SQL Server: The name of the user that jLogBook will use to log in to the SQL database. E.g. 'System'. (Often the database may have been created with the user 'sa' and with password ''. Oracle: You may have created a new schema to run the application so you would enter the schema name here.

· DBPASSWORD: Enter the password here. E.g. 'userpassword'

DBPROVIDER: This is the name of the OLEDB provider that will be used to communicate with the database server. You can either use a predefined provider name from ADOProviders, or enter a name as a string. E.g.

Access: ADOProviders.AccessProvider or “Microsoft.Jet.OLEDB.4.0” SQL Server: ADOProviders.SQLServerProvider or “SQLOLEDB.1” Oracle: ADOProviders.MSOracleProvider or “MSDAORA.1” Note: to use the Oracle- supplied OLE DB Provider for Oracle instead of the Microsoft-supplied provider, enter ADOProviders.OracleProvider.

· DBTYPE: This should be one of the following 'access', 'oracle', 'mysql, 'postgres' or 'sqlserver'.

SQL Express ConnectionFirst set up SQL Server Authentication

· SQL Express starts up with this disabled, you have to enable it.

· In SQL Server Management Studio Object Explorer, right-click the server, and then click Properties.

· On the Security page, under Server authentication, select the new server authentication mode, (SQL Server and Windows Authentication) and then click OK.

· Right click the server object again and select Restart.

Now Set up the user that you will log in with.

· Open the Security Object and look at the logins.

· Right click the user and select properties.

· Select SQL Server Authentication and enter a password

· Unclick the enforce password policy

· Click on the User Mapping area. Set the Default schemas to db_owner

· Click on the Status object. Make sure Grant and Log In are enabled.

· Click on OK to close the user property pop-up

Now in the config.local file

Enter values like these:

# Database

database.default.provider = "SQLServer"

database.default.DatabaseName = "mydbname"

database.default.Username = "myusername"

database.default.Password = "mypassword"

database.default.Server = "myservername\SQLEXPRESS"

5.3.2 Using the TableSchemas.py fileYou can specify the structure of the tables in the file TemplateSchemas.py. This single file holds the definitions of all the tables in the j5 system. The purpose of the file is:

· On start up, to check the integrity of the tables and correct the structure if there are any discrepancies. (This may mean creating the table, or creating fields within the table. (Note that this is currently in the process of being implemented).)

· Provide database table objects that can be used in the business rules programs to access the tables.

· Enable the migration from one database type to a different type. (The specification is applicable to multiple databases.)

Table SpecificationA typical table specification looks like this:

schema_asset = Table.TableSchema(

tablename = "asset",

columns = [ ("name",basestring,50),

("description",basestring,100),

("depth",int,4),

("parent",basestring,50),

("logdt",datetime.date,16),

("tank1",float,8),

],

rowidcols = "name"

)

In the above context, the rowidcols is the name of the key field. j5 often needs a unique field to identify the record.

If there are two fields that make up the unique key, they should be entered like this:

rowidcols = ["roundname", "seq"]

Note that if these fields are not unique, then when you click the edit link in a log, j5 will not know which field to bring up in the edit mode.

Using the Table ObjectsTo use the table objects in the business rules program, you can define a table object using:

from j5.custom.cheniere import TableSchemas

and then use code like:

self._assettable = TableSchemas.schema_asset.get_table(self.dbtable.db)

Then use the table object with (for example):

rows = self._assettable.gettablerows(filter=filterstr, orderbycols = ['name'])

This will return a list of row dictionaries filtered by the filterstr and ordered by the field 'name'

Or, if you want to get a single row:

self._pml = TableSchemas.schema_pml.get_table(self.dbtable.db) # in the init function

then

parentrow = self._pml.getrecord(context['row']['pmlid']) # in the customise_context function

5.3.3 SQL type functions in the business rules.If you want to perform sql operations within the business rules, you will need to know the functions that initiate these sql calls.

These functions are defined in the internal code of j5 and will be described shortly in this section.

The internal code is stored in the /src/j5/Database folder. There are a number of python modules viz:

FacadeBase.py, FacadeSQLDialects.py and Table.py.

Table.pyThe functions available in Table.Table are:

'addcolumn', 'addrow', 'altercolumns', 'coercevalue', 'coercevalues', 'countrows', 'createtable', 'deleterow', 'deleterowbyid', 'droptable', 'filtermatchessome', 'get_columntypes', 'get_default_row', 'getdefaultrecord', 'getfilterclause', 'getrecord', 'getrowid', 'getsomerecord', 'getsometablerows', 'getsqlcolumns', 'gettablerows', 'modifyrow', 'multicoercevalues', 'orderbyclause', 'rowid2textid', 'rowidclause', 'rowidexists', 'rowidparamstring', 'textid2rowid', 'to_xml'

You can create a table object from the db object using (for example):

_emailspecs = TableSchemas.schema_emailspecs.get_table(db)

Then use any of the functions described above. E.g.

recipient_dicts = _emailspecs.gettablerows(filter = "j5form = '%s'" % formname)

FacadeBase.pyThe Functions available in FacadeBase.Database are:

'_cursorexecute', '_execute', '_query', 'allrowdicts', 'allrows', 'delete', 'execute', 'fetch', 'insert', 'rollback_transaction', 'row2dict', 'rows2dict', 'singlecolumn', 'singlerow', 'singlerowdict', 'singlevalue', 'somerowdicts', 'somerows', 'update'

FacadeSQLDialects.pyIn this module, there are modules relating to each database. I.e.

'AccessDialect', 'BaseSQLDialect', 'Dates', 'MySQLDialect', 'OracleDialect', 'PostgresDialect', 'SQLServerDialect', 'SQLiteDialect', 'SnakeSQLDialect'

In each of these modules (e.g. SQLServerDialect) there are functions like:

'and_phrases', 'catclauses', 'dbdateformatfn', 'dblowerfn', 'dbstrconcat', 'dbstrequalityexpr', 'equals_phrase', 'get_database_version', 'getaddcolumnsql', 'getdeletesql', 'getdeletewithlimitsql', 'getdropcolumnsql_list', 'getinsertsql', 'getselectsql', 'getupdatesql', 'getupdatewithlimitsql', 'multi_equals_phrase', 'or_phrases'

e.g.

sql = db.getselectsql(tablename, ['max(issuenum)'])

res = db.singlevalue(sql)

5.3.4 Adding Database Fields to the Template Form

Often, you will want the user to enter information in a form and for that information to be stored in a database. The j5 system enables you to create input fields in the form that will be linked to the fields in a database. Here is the convention used to create these links to the database:

· The name of the form in the form directive in the template, is the name of the table in the database. For example, the directive:

<form id=“shiftform”name=“vaporizer”> means that input fields will be stored in the table vaporizer.

· The name in the input directive in the template is the name of the field in the table. For example, the directive:

<input type=“radio”name=“valveposn” value= “Closed”/> will create a radio button which will write its value into the field called valveposn in the table.

Please see below for more examples of the input directive and how it is used to store the information in the database.

Setting the default values in the fields

Often you will want to pre-load defaults into the fields which will then be saved in the database. If it is a fixed value, then just use the normal html method for setting defaults. I.e. often the value after the enclosing '>' in the input specification is the default loaded.

If you want to dynamically create the default values, then use the getdefaultrecord hook to load the values. (For example, you may want to load the current time into a datetime field.) Please see the section on defaults on how to do this.

Examples of Input Directives

Examples of text input, radio button input and check boxes are shown below.

<td width="100%" colspan="3">

<div style="TEXT-ALIGN: left"></div>BOG Observations:

<input style="WIDTH: 80%; BACKGROUND-COLOR: rgb(255,255,153)" size="200" name="bogobservation" />

</td>

<td width="33%" colspan="2">

<div style="TEXT-ALIGN: left"></div>BOG C102A Valve Posn VA241579

Open <input type="radio" checked="checked" name="valveposn" value="Open" />

Closed <input type="radio" name="valveposn" value= "Closed" />

</td>

<td>

<div align="center">

<input type="checkbox" checked="checked" name="u1status" value="on" /> On Line

</div>

</td>

5.4 Presentation

5.4.1 j5 Designer (In development)The j5 Designer is an html editor with GUI type facilities to enable the creation of templates without having to know how to code in html. Currently the Designer is in Beta status.

http://dev.sjsoft.com/wiki/j5/documentation/defaultvalues


To activate the Designer, there must be a config file entry similar to the following:

chenlogbook.forms.Issues.rights.design = True

When the application for the form is clicked, you will then see the Designer link. To activate the Designer screen, click on the Designer link.

5.4.2 Types of Presentation

LabelsSimple Example:

This example creates a label called Site.

<td><div class="label">Site </div></td>

The presentation of the label will be defined in the css file by the class called "label"

For example, in the css file:

td div.label {

text-align: right;

color: purple;

padding-right: 2px;

}

Special CharactersYou can get a list of special characters from:

http://www.w3schools.com/tags/ref_entities.asp

e.g. Eléctricos should be written Eléctricos

Input DataSingle Line input:

<td>

<input type="text" name="j5username" />

</td>

Multi-line Input:

<td valign="top" colspan="3" rowspan="2">

<textarea name="activity">

</textarea>

</td>

Displaying a Variable <td class="inv-value">

<span py:replace="j5module"/>

</td>

In this case, you would just set up a variable in the py file using:


context['j5module'] = parentrow['j5module']

Combo BoxesCombo boxes may be loaded statically from within the template or dynamically using the business rules and the supported Genshi template language.

Static Example:

<td>

<select name="stat" style="width:100%;">

<option value="Started">Started</option>

<option value="On Hold">On Hold</option>

<option value="Cancelled">Cancelled</option>

<option value="Complete">Complete</option>

</select>

</td>

Dynamic Example:

See the section on using Genshi Macros Example 2. (Using Genshi Macros)

CheckboxesHere is an example of a checkbox in the Genshi file.

<td>

<div>

<input type="checkbox" value="Clsd" name="clsd"/>

</div>

</td>

This example will write the value Clsd into the field called clsd if the check box is checked.

Radio ButtonsHere is an example of a radio button:

<td>

<input class="sjs-radio" type="radio" name="service" value="1"/> Yes

<input class="sjs-radio" type="radio" name="service" value="0"/> No

</td>

In this case, you may need to check the css for this kind of input. For example:

.sjs-radio{

width: 1em;

}

or, without a style sheet:

<td>

<input style="width:1em;" type="radio" name="service" value="Yes"/> Yes

<input style="width:1em;" type="radio" name="service" value="No"/> No

</td>

5.4.3 Form defaults

Static Defaults:If the defaults of the form do not change, then you can use the standard html nomenclature to load them. For example, if you want the default of a value position to be Open, then the input field may look like this:

<input type=“radio” checked=“checked” name=“valveposn” value=“Open” />

Dynamic Defaults:If you want the defaults to be determined dynamically by the business rules, then you need to do the following:

· In the business rules program*, create a hook called getdefaultrecord which must return a record that contains a dictionary of default values.

· In the template, link the default values in the dictionary created in the first step above to the value in the input field.

Note * The business rules program will be called <application>.py where <application> is the name of the application and it will be located in the j5\templates folder.

Note The Genshi file will be called <application>.Genshi where <application> is the name of the application and it will be located in the j5\templates folder.

Note that j5 looks for names that line up with the elements in the record dictionary and replaces the values with the values of the elements in the dictionary.

Business Rule:The hook below returns a dictionary with a single element called logdate which has a formatted string containing the current shift start time.

def getdefaultrecord(logdatetime):

shiftmanager = ShiftReports.getshiftmanager()

shiftdate = shiftmanager.getshiftstart(logdatetime, shiftmanager.getshift(logdatetime))

record = {"logdate": shiftdate.strftime("%Y-%m-%d+%H:%M:%S")}

return record

HTML presentation:The html code below loads the dynamic value created above as a default value for the input field.

<td width="33%">

<div align="right"> Date: <input style="WIDTH: 65%" size="200" name="logdate" />

</td>

Setting the colors of updates

Overview

There are a number of ways to apply a style to the updates in the form. I.e.:

1. Use the on-line editor to specify the static styles of the update. This has been discussed here.

2. Use the resources file to specify the dynamic style based on the value of the update. (I.e. an expression is put in the resource file which assigns a style to the update)

3. Use a database table to define the dynamic style based on the value of the update. (Currently under development. (August, 2006))

4. Use the css style sheets to define the style of the update.

Example 1: Using the Business Rules to define dynamic colors

First create a select in the template:

<select name="priority" size="1" style="${priority_style}" updatesneeded="true">

<option value="Normal">Normal</option>

<option value="Emergency">Emergency</option>

<option value="Security">Security</option>

</select>

Now in the business rules, define the colors:

colordict = { "Emergency": "red", "Security": "A8FFA8", "Normal": "white" }

color = colordict.get(context["log"].get("priority",None),None)

This sets the color of an object based on its value in the form.

Example 2: Use a dictionary of fields to specify the color for each option <td >

<select name="priority" size="1" style="${colorstyledict['priority']}" updatesneeded="true">

<option value="Normal"> Normal </option>

<option value="Emergency"> Emergency</option>

<option value="Audit Only"> Audit Only </option>

</select>

</td>

In the business rules:


context["colorstyledict"] = self.get_color_style_dict(context)

return context

def get_color_style_dict(self, context):

""" create a dictionary of styles in the form:

{field1:"background-color: red", field2:"background-color:blue" etc}

colors for each option defined in colordicts I.e

colordicts = {'field1': { "option1": "red", "option2": "#A8FFA8", etc },

'field2': { "option1": "red", "option2": "#A8FFA8", etc }}"""

if not "log" in context:

return {}

styledict ={}

for field in colordicts.iterkeys():

colordict = colordicts[field]

color = colordict.get(context["log"].get(field,None),None)

if not color is None:

styledict[field] = "background-color: %s" % color

return styledict

and we define the colors in a dictionary as:

colordicts = {'priority': { "Emergency": "red", "Normal": "#A8FFA8", "Audit Only": "white" },

'site': { "North Site": "red", "South Site": "#A8FFA8", "Central Site": "yellow" }}

5.4.4 Formatting the Data

Using HooksYou can use the hooks to format the data (See the section on hooks later.) Here is a Hook to set the format of the field schedstart:

from j5.Basic import Formatters

tablehooks = [RowHooks.FormatValuesHook(testdt=Formatters.DatetimeFormatter("%Y- %m-%d %H:%M"),

startdt=Formatters.DatetimeFormatter("%Y-%m- %d %H:%M"),

duration=Formatters.FloatFormatter("%.2f"))]

The above example formats two date time fields and also a floating point field.

Note that if you are using a calendar component, the format for the calendar needs to line up with the format hook.

Using the business RulesYou can use the business rules in the format the information in the template. Typically, this is done twice, once when the data is retrieved and once when the data is saved in the database.

Using GenshiYou can use the Genshi language to format the information appearing in the template.

Example: Formatting a datetime value.

This example formats the current date and time (logdatetime) in the form: Wednesday 3 February 2006, 14:21

<span id="title" py:content="logdatetime.strftime('%A %d %B %Y, %H:%M')"> current date and time</span>

Here is an example where we restrict the number of decimal points to 2.

<span py:content="'%.2f'% tanklvl"> Tank Level</span>

You can get more information on the types of formatting at:Detailed Formatting Information

Note: For a more generic way of linking functions in the business rules with the functions in the template see the section on Free format rules

5.4.5 Repeating Sections in the TemplateOften you will need to repeat sections in an application. For example, you may want to have a record for each of 20 machines in the production line.

To do this, use the py:for Genshi construct. Here is an example of this:

<tr py:for="slot in timeslots">

<td width="25%">

<div align="right" py:content="slot.datestring"> 3/1/06 9:00AM </div>

</td>

<td width="75%" class="rightcol">

<div align="left">

http://dev.sjsoft.com/wiki/j5/documentation/freeformatrules

http://docs.python.org/lib/typesseq-strings.html

<input style="width: 100%;" dbsync:hidden="True" name="${slot.comment_name}" size="200" />

</div>

</td>

</tr>

In this case, you would already have created an array of 24 (say) elements in a sequence called timeslots. Each element will comprise a dictionary with two elements, a datestring element and a comment_name element. The directive above will create multiple records and will substitue the values in each record for each of the timeslots.

The html code will create 24 rows, with 2 cells each in a table. The first column in the table will contain the datestring in the sequence and the second column will be an input field with the name held by the element comment_name in the dictionary.

Note that you can nest repeating structures within higher level repeating structures. For example, you could have a table for each of many plant areas and within the table, a record for each of the equipment items.

5.4.6 GenshiGenshi is a language derived from Genshi which is supported by j5. Like Genshi, it is a templating language and like Genshi it is based on Python. I.e. it is used to generate the template using program lines embedded in the Genshi file.

You can get more details on genshi at:

http://genshi.edgewall.org/wiki/Documentation/0.3.x/xml- templates.html

This section shows how Genshi can be used to create intelligent industrial applications simply.

Here are the main facilities available with Genshi

py:if -- The element is only rendered if the expression evaluates to a truth value:

e.g.

<input py:if="row['datatype'] == 'Value'" type='text' name='value'/>

will render

<input type='text' name='value'/>

if the variable datatype is equal to 'Value'. Otherwise, it will not show anything.

py:choose -- used in conjunction with when and otherwise.

py:for -- The element is repeated for every item in an iterable

e.g.

<select py:if="row['datatype'] == 'Combo'" name='value'>

<option py:for="opt in row['optionslist'].split(',')" value="${opt.strip()}">${opt.strip()}</option>

</select>

Will create a select statement with all the values from a comma separated list of values (stripped of white spaces) in the database variable called optionslist fed into the options part of the statement. E.g.

<select name='value'>

<option value="Good">Good</option>

<option value="Bad">Bad</option>

<option value="Maintenance">Maintenance</option>

</select>

if optionslist was 'Good,Bad,Maintenance'

py:def -- used to create macros, i.e. snippets of template code that have a name and optionally some parameters, and that can be inserted in other places. See the subsection on Genshi def.

py:match -- defines a match template: given an XPath expression, it replaces any element in the template that matches the expression with its own content

py:with --

py:attrs -- This directive adds, modifies or removes attributes from the element.

py:content -- replaces any nested content with the result of evaluating the expression

py:replace -- replaces the element itself with the result of evaluating the expression

e.g: <div py:replace="row['datatype']" py:strip="True"></div> will return the value of the variable datatype

py:strip -- conditionally strips the top-level element from the output

Note on using the $ format.Genshi expects the arguments for for and def to be py expressions, so there is no need to use the ${} format for these.

e.g. <option py:for="opt in colordicts[fieldname].keys()" value="${opt}">${opt}</option>

However, when assigning a value, style or anything else, the ${} form must be used.

e.g. style="background-color: ${colordicts[fieldname][log[fieldname]]};"

Linking the py variablesUse the customise_context function to setup variables that are passed to the genshi functions in the template.

In this example, various objects are passed to the genshi functions.

E.g. The colordicts dictionary is passed to the genshi function as a dictionary.

E.g. The value of a field moduletype is fetched from another table and passed to the genshi template.


context = super(LogModel,self).customise_context(context, action, components)

context["datetime_picker"] = self._datetimepicker


context['colordicts'] = colordicts

try:

parentrow = self._pml.getrecord(context['row']['pmlid'])

context['j5module'] = parentrow['j5module']

context['moduletype'] = parentrow['moduletype']

except:

pass

return context

Example: Using the py:if featureIn this example, the row is only shown when the logtype is equal to 'OPERATIONS' The py:if provides a blank row so that the table structure remains unaltered.

<tr py:if="log['logtype'] == 'OPERATIONS'">

<td style="width: 10%"><div class="label">Event</div></td>

<td style="${event_style}">

<select name="event" size="1" style="${event_style}" updatesneeded="true">

<option value="Abnormal">Abnormal</option>

<option value="Normal">Normal</option>

<option value="Trip">Trip</option>

<option value="Startup">Startup</option>

<option value="Shutdown">Shutdown</option>

<option value="Assumed the Watch">Assumed the Watch</option>

<option value="Relieved By">Relieved By</option>

</select>

</td>

<td> </td>

</tr>

<tr py:if="log['logtype'] not in 'OPERATIONS'">

<td> </td>

<td> </td>

<td> </td>

</tr>

Using Genshi MacrosMacros can be conveniently created in Genshi where html code must be repeated often. This is useful, for example where you have a number of equivalent select boxes for many machines.

Example 1

The Genshi Function Definition

<td py:def="unit_input(field)" style="text-align:center;">

<div>

<input type="checkbox" value="1" name="${field}" checked="checked"/>

<span style="font-weight: bold;">On Line</span>

</div>

</td>

Using the Genshi Function

<td py:replace="unit_input('u1status')"></td>

The Resulting HTML

<td style="text-align:center;" xmlns="http://www.w3.org/1999/xhtml">

<div xmlns="http://www.w3.org/1999/xhtml">

<input checked="checked" type="checkbox" name="newrow_concentrator_1169035351226000676290_u1status" value="1" skip="skipper" xmlns="http://www.w3.org/1999/xhtml" />

<span style="font-weight: bold;" xmlns="http://www.w3.org/1999/xhtml">On Line</span>

</div>

</td>

Note that, in addition to the genshi code, j5 also adds components to the html.

Example 2The Genshi Function Definition



<td py:def="dot_cell(field,classname='inv-value',colspan=1)" style="text- align:center;" class="${classname}" colspan="${colspan}">

<span py:if="update_mode == None" py:replace="field" />

<input py:if="update_mode != None" type="text" style="width:100%;" value="${field}" />

</td>

Using the Genshi Function

<td py:replace="dot_cell(item['sendoutscf'])">

or

<td py:replace="dot_cell(item['numvap'],'inv-label')">

Example 3The Genshi Function Definition (Placed in the same form as the statement where it is used.

<tr id="logform">

<td py:def="procfield(fieldname)" >

<select name="${fieldname}" style="background-color: ${colordicts[fieldname][log[fieldname]]};" updatesneeded='true'>

<option py:for="opt in colordicts[fieldname].keys()" value="${opt}">${opt}</option>

</select>

</td>

Using the Genshi Function:

<td py:replace="procfield('priority')"></td>

The py file extract for this:

context["colordicts"] = colordicts

colordicts = {'priority': { "Emergency": "red", "Normal": "#A8FFA8", "Audit Only": "white" },

'site': { "North Site": "red", "South Site": "#A8FFA8", "Central Site": "yellow" }}

5.4.7 Specifying the css filesYou can specify the css files in the business rules. A typical spec will look like this:

from j5.WebComponents import HeaderObjects

class FormModelMixIn(object):

LogbookHeaders = HeaderObjects.HeaderFactory(dirpath=os.path.dirname(os.path.abspath(__file__)))

my_headers = [

LogbookHeaders.MimetypeRoute("css", "text/css"),

LogbookHeaders.CssMimeLink("sjslogbook.css")

]

def rdepends(self, components):

deps.update(self.my_headers)

return deps

Then in the logmodel, pass this object in as well

class ThisLogModel(FormModelMixIn,LogbookPage.LogModel):

This will pass the header information to the browser so that it knows where to get the css files.

5.5 Business Rules

5.5.1 j5 HooksIf you would like to add your own business rules to the application, then you do this by either

· writing specific business rule modules or

· using the structured j5 Hooks.

Hooks are points in the processing of the j5 template or processing of the nominated tables where the system will look to see if you have provided any specific code that needs to be processed. (i.e. j5 hooks in your custom code)

For example, before the templates are displayed, the server will look for a getdefaultrecord hook in the py file. This hook will be a routine which can set up the default values in the form.

Likewise, if a record is to be added to a database table, then the pre-add hook for that table will be executed. (If it exists.)

A powerful feature of hooks is that they can be chained together to get sophisticated results. For example, a post add hook that writes an audit log could be chained to a postadd hook that emails nominated plant personnell.

Much of the internals of the j5 system are written with hooks and by adding a custom hook or hooks, you are simply enriching the existing functionality without changing any of the structure.

Note also that hooks often have their own configuration fields (for example the emailing hook will have configuration data as to which email addresses to send information to and when to send the information.

In summary then, a hook is a python function which resides in the <application>.py file and which will be executed at the appointed time. The name of the hook will determine when it is to be executed. The hook function can of course call other functions (for example, getting data out of a database.)

There are two main kinds of hooks:

· Hooks that relate to the form and

· Hooks that relate to a database table.

Form-Related HooksThese hooks relate to the operation and presentation of information in a form

· getdefaultrecord(logdatetime): Runs just before the presentation of the template. Used to select default values for the form.

· getviewparams(logdatetime): Runs just before the presentation of the template. Used to select values for the non-form elements of the template.

Table Related HooksThese hooks are related to a database table. Whenever any form or other application attempts to access the database, the relevant hook is looked for and will be executed if it is found.

· preadd, validateadd and postadd

· premodify, validatemodify and postmodify, predelete, validatedelete and postdelete

_Hook Example

Here is a typical getdefaultrecord hook. This hook gets the targets for 24 hourly records from a remote database.


shiftdate = datetime.datetime.today()

timeslots = gettimeslots(shiftdate)

targetdict = gettargetdict(shiftdate)

for slot in timeslots:

target = targetdict[slot['target_name']]

slot["value"] = target

record = {"logdatetime": shiftdate, "timeslots": timeslots}

return record

Database Hook Examplefrom j5.Database.Hook import RowHooks

class SetIssueNumber(object):

def pre_addrow(self, argdict, db, tablename):

sql = db.getselectsql(tablename, ['max(issuenum)'])

res = db.singlevalue(sql)

# check for the case when there are no rows in the database

if res is None:

res = 0

argdict["issuenum"] = res + 1

print "<< SetIssueNumber: Setting the issuenum to %s >>" % str(res + 1)

return argdict

tablehooks = [SetIssueNumber()]

Hook Arguments

ArgumentsA hook function (e.g. validate_this_function_has_hooks below) can have two types of arguments.

· it can specify any argument which is passed to the function it's wrapping.

· it can specify any attribute of the object which holds the function it's wrapping.

For example, assume a j5 class :

class Hooked(object):

def __init__(self):

self.test = 3

self.unique = 5.4

def this_function_has_hooks(self, arg1, arg2):

do_something()

Now in the business rules (.py file):

class HookProper(object):

def validate_this_function_has_hooks(self, arg1, unique):

use_arg1_and_unique()

return self.validate_this_function(arg1, unique)

def post_this_function_has_hooks(self, test):

use_test()

return self.post_this_function_has_hooks(test)

tablehooks = [HookProper()] # to register this as a hook class

For a hook (like validate_this_function_has_hooks) wrapping the function this_function_has_hooks, the available arguments are arg1, arg2, test and unique.

Since in Python, object methods are attributes, there are two other available arguments - __init__ and this_function_has_hooks (which will be the function object, callable from within the hook).

Any arguments which aren't specified in the hook function header are not passed in. There is one exception to this. If writing a preprocessing hook (one with the prefix pre_), it is compulsory to ask for all arguments of the hooked function, or an exception is thrown. This is a sanity check to make sure a preprocessing hook is aware of all the possible arguments, as the tuple returned from one becomes the arguments for the function itself, which creates the possibility of preprocessing hooks mysteriously discarding arguments if they're not aware of them.

Example HookIn this example, we check to see if all the columns have a non-None argument and throw an exception if we find one.

In the example, we have passed argdict (one of the arguments in the hooked function) and db (one of the attributes of the hooked class.)

In the j5 Program:class DBTable(object):

def __init__(self, db, tablename, columnlist=None, rowidcols=None, orderbycols=None, setupdb=False, columnlengths={}):

self.db = db

self.tablename = tablename

self.columnlengths = columnlengths

tableexists = db.exists(tablename)

etc:

def modifyrow(self, argdict, rowid=None, limit=None):

"""modify the row in the table. rowid will be got from argdict if not given (but required if changing rowid values)"""

argdict = self.coercevalues(DictUtils.filterdict(DictUtils.cidict(argdict), self.columnlist))

etc:

In the business rules py file:class ValidateHooks(object):

def validate_modifyrow(self,argdict,db):

cols = [col[0] for col in db.get_columntypes("handover")]

for col in cols:

if col is None:

raise Hook.ValidationException("Enter a value for %s before saving" % col)

return self._validate_row(argdict, db)

Summary of Hook argumentsTypically, the arguments for a hook are self, argdict and db.

argdict: is a dictionary of the form arguments.

db: is the database object including all the methods associated with the database. Here is a list of the methods and arguments of the db object:

'adjust_description',

'allrowdicts',

'allrows',

'and_phrases',

'cache',

'catclauses',

'close_db_connection',

'config',

'convert_unicode_sql',

'create_connection_properties',

'create_db_connection',

'datetime_to_dbsql',

'db',

'db_config_lookup',

'dbdateformatfn',

'dberror',

'dblowerfn',

'dbstrconcat',

'dbstrequalityexpr',

'dbtypename',

'delete',

'driver',

'equals_phrase',

'eval_db_binary',

'eval_db_datetime',

'eval_db_number',

'eval_db_string',

'execute',

'exists',

'fetch',

'float_to_dbsql',

'from_dbobj',

'from_dbrow',

'from_pystr',

'get_columntype',

'get_columntypes',

'get_database_version',

'get_default_cache_type',

'get_default_pool_type',

'get_native_columntypes',

'get_supported_types',

'getaddcolumnsql',

'getdeletesql',

'getdeletewithlimitsql',

'getdropcolumnsql_list',

'getfieldnames',

'getinsertsql',

'getselectsql',

'gettables',

'gettables_fromschema',

'getupdatesql',

'getupdatewithlimitsql',

'importdriver',

'insert',

'integer_to_dbsql',

'is_disconnect_exception',

'local',

'long_to_dbsql',

'multi_equals_phrase',

'or_phrases',

'pool',

'rollback_transaction',

'row2dict',

'rows2dict',

'set_access_connection_properties',

'set_mysql_connection_properties',

'set_oracle_connection_properties',

'set_sqlserver_connection_properties',

'singlecolumn',

'singlerow',

'singlerowdict',

'singlevalue',

'somerowdicts',

'somerows',

'sqlstats',

'string_to_dbsql',

'supports_database',

'test_connect',

'to_dbsql',

'to_pystr',

'update']

5.5.2 Special FieldsThere are some fields in the business rules that have special meaning. These are discussed here.

LogdatefieldWith most logbook applications, the date and time of the logbook is important. If you do not specify this field, then the system will look for the field logdatetime.

To specify this field, add it in to the business rules directly under the class LogModel statement. I.e.


logdatefield = "taskdt"

def __init__(self, *args, **kwargs):

etc.....

In this case, the logbook will use the field logdt as the datetime field associated with each log.

If you do not have a logdatefield specifier and you do not have a field called logdatetime, then the system will print an error but will not stop.

rowidcolsThis is the primary key of the logbook. It can be set in the TableSchemas.py file (preferred) or in the business rules program. The field should be unique.

EITHER In the TableSchemas.py file:

enter the specifier on the same level of indenting as the columns specifiers. I.e.

columns = [ ("valuedt",datetime.date,16),

..........

("finishhr",int,4)

],

rowidcols = "valuedt"

OR In the business rules program:

Place the statement in the lower part of the program but do not indent it. E.g.

rowidcols = "logdatetime"

Note: If you are using an id, to force the id to be unique, then add this hook to the hooks:

RowHooks.UniqueIdHook("logid")

Note: The rowid must be in the form even if it is hidden. For example,

<input type="hidden" name="logid"/>

Note: The auditlog link specifier in the kid file is described as follows:

<span py:replace="auditlog(textid=auditrowid)"/>

The default for the rowidcols parameter is logdatetime. If it is not set, then the symptoms will be that on editing, you will see a record other than the one you originally selected.

rowsperpageYou can set the number of rows displayed on a page with this parameter in the business rules (py file). E.g.

rowsperpage = 3

scrollinglogIf you would like the tabs at the top of the page to remain stationary and the logs to scroll, then you can set the scrollinglog parameter to true. I.e. simply set:

self.scrollinglog = True

in the logmodel init function in the .py file.

auditlog_maxdeletedrowsWhen the Audit Log for Deleted Rows is clicked, the system provides a view of all the logs that have been deleted. If there is a lot of deletions taking place, then this can become a large window. If you set this parameter to 20 for example, then only the latest 20 deleted rows will be shown.

This is specified in each of the business rules (*.py) files like this:

auditlog_maxdeletedrows = 20

You can always use Server Admin - > dbviewer to view the deleted logs by clicking on the audit log of interest and then setting the filter to Delete. This will show all the deleted logs in a paged format.

5.5.3 Historical InformationOften reports require data that originates from a SCADA system or is stored in an Industrial Historian like jHistorian.

The j5 system supports various techniques for getting historical data into the reports as follows:

· Direct connection to an OPC source. One of the resources included in the j5 system is an OPC data collector. This module can connect directly to any OPC source such as KEPWare's OPC servers. Typically, you would use the getdefaultrecord hookto fetch the information and pre-load it into the report. For more information on the inbuilt historian, please see the inpython documentation.

· Connection to the St James Software jHistorian application. You can connect information directly from the jHistorian database using these connection algorithms. There is an example of this below.

· Direct Connection to a third party historian database. Often the information is available from the third party via a standard database connection. (Examples are InSQL, the Invensys historian.)

· Connection via a spreadsheet. Many of the third party historians write the information into a spreadsheet. (For example, the PI system.) In cases such as these, use the j5 Spreadsheet interface to get the information out of the spreadsheet.

OPC Data CollectionTo configure the OPC data collection, you need to:

· Configure the OPC data source, (this identifies the OPC source),

· Configure the OPC Event Giver (you specify the tag names, collection frequency etc) and

· Configure the Storage Module (this specifies where the information will be stored.)

jHistorian Data CollectionIn this example, data is collected from the jhistorian database using the getdefaultrecord hook.

tag2fieldmap = {

"Sine.Sine1": "u1feedlvl",

"Sine.Sine2": "u1feedconc",

"Ramp.Ramp1": "u1feedflow",

"Sine.Sine3": "u1dischargetemp",

"Sine.Sine4": "u1dischargeconc",

"Ramp.Ramp2": "u1dischargeflow"

}


shiftmanager = ShiftReports.getshiftmanager()

shiftdate = shiftmanager.getshiftstart(logdatetime, shiftmanager.getshift(logdatetime))

desiredtags = tag2fieldmap.keys()

historydata = CheniereDemoHistoryData.get_columns(shiftdate, desiredtags)

record = {"logdate": shiftdate.strftime("%Y-%m-%d+%H:%M:%S")}

for tag, value in historydata.iteritems():

http://dev.sjsoft.com/wiki/jhistorian/inpython

http://dev.sjsoft.com/wiki/jhistorian/inpython


column = tag2fieldmap.get(tag, tag)

record[column] = value

return record

5.5.4 Filtering and Sorting

FilteringThere are a number of ways that filtering can be carried out as follows:

· Many of the applications (e.g. Logbook)provide an in-built filtering mechanism in the application itself. On the logbook main screen, for example, there is an “Edit Filter” link which can be used to filter the required records.

· Filtering strategies can also be implemented in the business rules. Typically, you would define the record set to be collected using a SQL statement and a “where” clause.

· Filtering is automatically carried out by the system according to the rights of the users and the database tables. These rights can be seen and altered from the System Admin Apps and Users screens. (The specifications are held in the configuration start up file.)

SortingThere are a number of ways that filtering can be carried out as follows:

· You can set the ordering of the records for each application via the System Admin page. You would add an entry into the System Admin → Apps under the relevant application like: sortby : logdatetime desc

· You can also set the ordering directly by adding a line in the startup config file. In the config file, you would enter a directive like: logbook.forms.LogBook.sortby = “logdatetime desc”

· Sorting strategies can also be implemented in the business rules. Typically, you would define the record set to be collected using a SQL statement and the “Order By” clause.

Note that you need to restart the j5 server if you modify the startup config file.

5.5.5 Scheduled TasksTasks are typically created and scheduled from within the Business Rules (.py) files.

In the example below,

· The scheduled task is created in the expire_samples function.

· The task is passed to the scheduler together with the details of schedule (in this case every 15 minutes) in the add_task method.

Create the schedule self._scheduler = self.get_resource("schedule")

self._scheduler.add_task(self.make_expiration_task())

def make_expiration_task(self):

schednode = ConfigTree.Node()

schednode.hour = "0"

schednode.minute = "15"

schednode.function = self.expire_samples

schednode.targetargs = ()

return schednode

Create the taskdef expire_samples(self):

updates = ["samplestatus = 'Expired'"]

now = self.dbtable.db.to_dbsql(datetime.datetime.now().date())

sql = self.dbtable.db.getupdatesql(self.dbtable.tablename, updates, "expirationdate < %s" % (now,))

self.dbtable.db.execute(sql)

6 Administration

6.1 DocumentationThis documentation is the hard copy version of the documentation at http://www.sjsoft.com/download/AdminstratorManual.doc

Generally, it is advisable to use the on-line documentation as this is the updated more frequently.

6.2 Requirements

6.2.1 Operating System· Windows Variants (2000, XP or 2003 Server) operating system or

· Linux operating System. (Currently, Red Hat and Fedora are supported. Please check to make sure you have a compatible distribution.)

6.2.2 St James Software· St James Software j5 System.

· j5 floating licenses for the number of expected sessions that need to connect to the application.

6.2.3 Database Software

Connection to one of the following Databases:

1. MS Access

2. MS SQL Server

3. PostreSQL

4. Oracle (Oracle 8 or later)

6.2.4 Web Server Software

Use one of the following web servers:

· CherryPy Web Server (included in the j5 Installer)

· Apache Web Server (included in the j5 Installer

6.2.5 Real-Time Connection to Process Devices

If you intend using the j5 Historian, you will need to have an OPC server connection (like KEPWare's OPC server) to the field devices.

6.2.6 Optional Software Items

For multiple database applications, we recommend a Query tool like QTADO to view the information in the database. (Alternatively use the internal database viewing tool.)

For Spell Checking (will be supported shortly in j5) you will need the Aspell spell checking software. (Unzip the archive and install ASpell and the dictionary, additional information is available in this document.)

Note that Spell Checking is native in Firefox so no additional spell checking is required.

6.2.7 Client Requirements

Client machines need to have the following software loaded:

Any standard web browser like

1. Microsoft Internet Explorer version 6 or higher,

2. Firefox or equivalent.

The system has been extensively tested with Internet Explorer version 6 and Firefox.

6.3 Large InstallationCarry out the steps in this section for large applications that include apache and LDAP etc.

Once complete, go to the next section which is the section on Upgrades and Site Files.

(Note revision numbers may different and are only shown here as examples)

6.3.1 Downloading

If you intend running IIS in the same machine:

Stop IIS (IIS Admin Service)

This will tell you there are some services which depend on it. Make note of which services they are, as you will need to start them again later

Download the Zip File

The Zip file contains all the dependencies listed below. It is at: http://www.sjsoft.com/download/sjsoft-j5-requirements-1.3.x-20070516.zip

Download the latest j5 Installer at:

http://www.sjsoft.com/download/Isjsoft-j5-1.3.5.win32-py2.4.exe or similar.

6.3.2 InstallationInstall the following components in this order:

Python 2.4.4

This is required for runtime interpretation of the j5 web server software

Install file: http://www.python.org/ftp/python/2.4.4/python-2.4.4.msi

Alternate location: http://www.sjsoft.com/download/opensource/python- 2.4.4.msi

Security information: http://www.python.org/news/security/

2.4.4 contains all the latest security fixes

Our software is not yet fully tested with the Python 2.5 series which contains significant changes

Options required:

Python (base install), Register Extensions

i.e. don't install Tcl/Tk, Documentation, Utility Scripts or Test suite

Apache 2.0.59

This provides a secure, efficient and extensible web server

2.0.59 is the latest release in the 2.0 series, and security updates are still provided for this series

The 2.2 series is not being used because changes to support it in mod_python have only recently been made and we want to test it thoroughly

Install file: http://www.apache.org/dist/httpd/binaries/win32/apache_2.0.59- win32-x86- no_ssl.msi

Alternate location: http://www.sjsoft.com/download/opensource/apache_2.0.59- win32-x86- no_ssl.msi

Security information: http://httpd.apache.org/security_report.html

mod_python 3.3.1

This provides Python support to Apache

Install file: http://www.apache.org/dist/httpd/modpython/win/3.3.1/mod_python- 3.3.1.win32- py2.4-Apache2.0.exe

Alternate location: http://www.sjsoft.com/download/opensource/mod_python- 3.3.1.win32- py2.4-Apache2.0.exe

Genshi 0.4

This is used for rendering the web templates to XHTML

Install file: http://ftp.edgewall.com/pub/genshi/Genshi-0.4.win32.exe

Alternate location: http://www.sjsoft.com/download/opensource/Genshi- 0.4.win32.exe

Routes 1.6.3

This is used for URL handling within the j5 Web Framework.

Install file: http://www.sjsoft.com/download/opensource/Routes-1.6.3.win32.exe

Source file (for reference): http://cheeseshop.python.org/packages/2.4/R/Routes/Routes- 1.6.3.tar.gz

Python Windows Extensions 210

This is used for connecting Python to the database using ADO

Install file: http://downloads.sourceforge.net/pywin32/pywin32-210.win32- py2.4.exe

Alternate location: http://www.sjsoft.com/download/opensource/pywin32- 210.win32- py2.4.exe

Also required: http://www.sjsoft.com/download/opensource/mfc71.dll (copy into windows\system32 directory)

ZSI (Python SOAP extensions) 2.0.1

These extensions provide SOAP client and server functionality in Python

Install file: http://www.sjsoft.com/download/opensource/ZSI-2.0.1de.win32.exe

Python LDAP 2.0.6

Python LDAP client API (used for authentication against LDAP server etc)

Install file: http://www.agescibs.org/mauro/python-ldap-2.0.6.win32-py2.4.exe

Alternate location: http://www.sjsoft.com/download/opensource/python-ldap- 2.0.6.win32- py2.4.exe

ElementTree 1.2.6

XML processing on Python 2.4

Install file: http://effbot.org/downloads/elementtree-1.2.6-20050316.win32.exe

Alternate location: http://www.sjsoft.com/download/opensource/elementtree- 1.2.6- 20050316.win32.exe

cElementTree 1.0.5

XML processing speedup on Python 2.4

Install file: http://effbot.org/downloads/cElementTree-1.0.5-20051215.win32- py2.4.exe

Alternate location: http://www.sjsoft.com/download/opensource/cElementTree- 1.0.5- 20051215.win32-py2.4.exe

wsgiref 0.1.2

Standard interface between Python web servers and web applications

Install file: http://www.sjsoft.com/download/opensource/wsgiref-0.1.2.win32.exe

pyXML

6.3.3 Configuring ApacheTo configure Apache for the j5 system, carry out the following steps:

· Edit httpd.conf (to get there, Start→Programs→Apache→Configure Apache→Edit httpd.conf)

· Look for Listen 80 and change 80 to the port you want. (If IIS is not on the same machine, leave this at 80 ) Choose a port number that doesn't conflict with any of the ports on the machine. E.g. Can't choose 80 (IIS) or 8080 (Oracle)

· Look for ServerName servername:80 and change that 80 to the same port as above.

· Find the section with lots of LoadModule lines and add the line LoadModule python_module modules/mod_python.so

· Find the section inside <Directory “C:/Program Files/Apache Group/Apache2/htdocs”> and change the line saying AllowOverride None to AllowOverride FileInfo

· .htaccess file

· Open c:\Program Files\Apache Group\Apache2\htdocs

· Copy the section below (marked .htaccess file contents) into a text file called .htaccess in c:\Program Files\Apache Group\Apache2\htdocs

· Using Notepad or Wordpad, change the PythonOption j5.config “c:\path\to\cheniere.config” to the directory you want (it does not need to exist), with <sitename>.config. For example:PythonOption j5.config “c:\sjsoft-j5\cheniere- site\cheniere.config”

.htaccess file contents

# NOTE: We need AllowOverride FileInfo to be defined for this location, in order to allow SetHandler

# Use Python to serve all files in this location

SetHandler python-program

# Set PYTHONPATH to include j5 if neccessary - shouldn't be under normal installation, thus this is commented out

# PythonPath "sys.path + ['c:\\path\\to\\include']"

# Set the handler to our BootstrapServer

PythonHandler j5.Web.Server.Apache.BootstrapServer::handler

# Set the logging level

PythonOption j5.loglevel "INFO"

# Set our script name - this is the name relative to the root

PythonOption SCRIPT_NAME ""

# Put PythonDebug on so we get tracebacks - this can be turned off once the deployment is successfully running

PythonDebug On

# Set the config file name - edit this manually

PythonOption j5.config "c:\path\to\j5demo.config"

Apache File InformationApache

Apache is a widely-used, robust web server application. One of its core features is the ability to handle large volumes of simultaneous requests.

Apache runs as a Windows Service, and is configured via an http.conf file and one or more .htaccess files.

We will configure Apache to:

1. start up j5

2. capture all web requests sent to http://j5.server.com/

3. pass all requests on to the j5 Service

4. pass j5-generated web pages back to the user

http.conf

On a default installation the core configuration file is found at C:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf

The http.conf file contains web server configuration settings. These set up Apache to capture web requests and return web pages.

The following settings are modified for a default j5 setup (search for the setting name to find them in the http.conf file):

1. Modify the server root, the top of the directory tree under which the server's configuration, error, and log files are kept.

* ServerRoot "C:/Program Files/Apache Software Foundation/Apache2.2"

2. Add a listen directive, binding Apache to port 80, the default web port

* Listen 80

3. Add the following line to the LoadModule list, adding support for Python

* LoadModule python_module modules/mod_python.so

4. Set the ServerAdmin email address

* ServerAdmin [email protected]

5. Set the server name, the name and port that the server uses to identify itself.

* ServerName j5.server.com

6. Set the document root, directory containing further configuration files. (On a non-j5 site, this directory would also contain web pages.)

* DocumentRoot "C:/Program Files/Apache Software Foundation/Apache2.2/htdocs"

All other settings remain the same.

.htaccess

Our http.conf settings point to the DocumentRoot, containing our single .htaccess file: C:/Program Files/Apache Software Foundation/Apache2.2/htdocs/.htaccess

.htaccess files contain Apache configuration directives which apply to that directory and all subdirectories thereof. These instruct Apache on how to handle requests to that directory.

Using the provided template (see footnote 1) we direct Apache to

1. start up the j5 service using our j5 configuration files and

2. pass all web requests on to j5

The lines of interest are those pointing to the j5 configuration files:

PythonOption j5.localconfig "C:\Program Files\sjsoft- j5\customers\mysite\mysite.config.local"

PythonOption j5.globalconfig "C:\Program Files\sjsoft- j5\customers\mysite\mysite.config.global"

Log files

If the website is inaccessible an error may have occurred with Apache rather than j5. To investigate web server errors, consult the Apache log files:

Access log

C:\Program Files\Apache Software Foundation\Apache2.2\logs\access.log

Error log

C:\Program Files\Apache Software Foundation\Apache2.2\logs\error.log

Managing the Apache service (how to restart Apache)

The Apache web server runs as a Windows Service. When any configuration or code changes take place, the service must be restarted for them to take effect.

1. Under Administrative Tools, double-click Services

2. On the list on Services, find and select Apache2.2

3. Click "Stop" to stop the service

4. Make the required modifications and/or overwrite files

5. Click "Start" to start the service again

Footnote 1 (.htaccess template)

# NOTE: We need AllowOverride FileInfo to be defined for this location, in order to allow SetHandler

# Use Python to serve all files in this location

SetHandler python-program

# Set PYTHONPATH to include j5 if necessary - shouldn't be under normal installation, thus this is commented out

# PythonPath "sys.path + ['c:\\path\\to\\include']"

# Set the handler to our BootstrapServer

PythonHandler sjsoft.Web.Server.Apache.BootstrapServer::handler

# Set the logging level

PythonOption j5.loglevel "INFO"

# Set our script name - this is the name relative to the root

PythonOption SCRIPT_NAME ""

# Put PythonDebug on so we get tracebacks - this can be turned off once the deployment is successfully running

PythonDebug On

# Set the local and global config file name - edit this manually

# PythonOption j5.localconfig "c:\path\to\j5demo.config.local"

# PythonOption j5.globalconfig "c:\path\to\j5demo.config.global"

PythonOption j5.localconfig "C:\Program Files\sjsoft- j5\customers\mysite\mysite.config.local"

PythonOption j5.globalconfig "C:\Program Files\sjsoft- j5\customers\mysite\mysite.config.global"

6.3.4 Restarting the web serversRestart Web Servers

· Stop Apache

· Start IIS

· Also start all the dependent services you made a note of earlier

· Start Apache

Set Service User· If the j5 server needs to access any network resources, it cannot be run as LocalServer

(including database, LDAP, etc)

· If this is the case, adjust which user it needs to run at through the properties tab of the Apache2 service under Administrative Tools\Component Services

6.3.5 Configuring the SiteUpload and adjust Config

· Point a browser towards http://computername:apacheport (replace computername and apacheport with the correct values)

· Go to the Server Admin app

· Click Browse next to the Import Site Config button and browse for the site

· Click Import Site Config

· Restart Apache and reload the page

1. We normally ship the config file with one user, admin, who will belong to the Admin group, with password test. (In some cases, we will ship the config file with many user groups configured.)

Databases

1. Go to the Resourcestab

2. In the database section:

1. Delete the default database (click Delete next to its name and then click Save Config)

2. Add the default database resource

1. Click Add Child under database

2. Select Oracle (or the preferred database) from the drop-down list of providers

3. Name the database default (put default in the text field to the left of the drop-down)

4. NB: you must enterdefault above after choosing the preferred database from the drop-down

5. Fill out the config details

6. Please include the server name under both Server and DatabaseName

7. Click Save Config

8. If the Port option has been set to 0 (current bug) delete that value and click Save Config

Licensing

· Configure Licensing by copying the license file onto the machine, and adjusting it's position in the Advanced tab of Server Admin:

· Click on Advanced under Server Admin

· Scroll down to near the bottom of the page and edit the filename key under license (the main keys are in alphabetical order)

· This must be the full path to the file e.g. c:\sjsoft- j5\<licensename>.lic

· Go back up to the top of the page and click Save Config

· Stop Apache

· Start Apache again - this will reload with the new configuration

Import Databases

· Go to the Status tab

· Click Browse next to the Import Databases button and browse for the site

· Click Import Databases

Restart

· Stop Apache

· Create the required attachment directories (Logbooks\attachments Metering\attachments and Orderbook\attachments)

· Start Apache

6.3.6 LDAPLDAP

Note that getting this wrong will prevent you using the web interface to configure (you won't have the rights!)

That is why this is being done in a separate step after the rest of configuration...

· Back up your config file before performing this step in case something goes wrong (<sitename>.config in the site directory)

· Go to the Resources tab

· In the ldap section:

1. Click Add Child under ldap

2. Select ActiveDirectory as the provider

3. Enter the name (to the left) as default

4. Enter the uri which must be of the form ldap://server_address/ (with server_address a domain name or IP address)

5. Click Save Config and verify the values are correct

· In the authentication section:

1. Delete the default authentication (click Delete next to its name and then click Save Config)

2. After doing this you must successfully complete the rest of the steps in this section, or you will not be able to log in!

3. Add a new authentication resource using LDAP:

1. Click Add child under authentication

2. Select LDAPAuthenticator from the dropdown list of providers

3. Set ldapname to default (this corresponds to the LDAP resource above)

4. Set attrs to a comma-separated list of LDAP resource identifiers (for ActiveDirectory, this will be dc=subdomain,dc=domain,dc=com for subdomain.domain.com)

5. Create a text file with a secret password in it, and enter the filename in secret_token_file - this is used to sign cookies to show that they come from an authentic login. This file should not be accessible to any user except the Administrator / Apache service user.

4. Click Save Config. Verify that all the details are correct.

· Adjust Users - make sure that you have a user in the Admin Group whose name will be a valid login on the LDAP server!

1. If you don't you will not be able to log in and adjust the parameters, so this is important

2. Go to the Users tab under Server Admin

3. Click on Add User and enter a known user name (e.g. Administrator) that is valid on the LDAP server

4. Select the Admin group next to the user name

5. Click on Save Config

· Save the config, check everything, and restart Apache...

· Go back to the home page - you should be able to log in using LDAP credentials, and access the Server Admin interface if you are in the Admin group (as defined in the j5 config).

6.4 Installation(Note revision numbers may different and are only shown here as examples)

6.4.1 Standalone InstallationYou can download the j5 installer from the following location:

http://www.sjsoft.com/download/sjsoft-j5-1.1.45-setup.exe

You will just double click the installer to install the j5 system. It will install in the c:\program files\sjsoft-j5 folder as a default.

To start the j5 system, cd into the root customers folder.

For example, to start the demo,

cd c:\program files\sjsoft-j5\customers\demo

then run the startj5.bat program.

The relevant start command in the bat file will look similar to this:

..\..\sjsoftstart config.global config.local

Alternatively, you can start the system in a service using the startj5 service.bat command. E.g.

cd c:\program files\sjsoft-j5\customers\demo

startj5service

For more information on running j5 as a Windows service, please see the section below "J5 as a Windows Service"

j5 as a Windows ServiceManagement (installing, uninstalling, other controlling) of j5 as a Windows Service is done via one of two executables. If just j5 is required, without the sjsoft addons, the executable is "j5WinService.exe". If the sjsoft addons are required, the executable is "sjsoftWinService.exe". Both these executables are included in the standard standalone install. The argument "-- servicedebug" will print out debug information for any service command

Installing

The j5 Service works by saving normal command-line arguments to the registry to be run by the service when started. Thus, if you would normally run "sjsoftstart <arg1> <arg2> <arg3>", to install the service, you should run "sjsoftWinService --serviceinstall <arg1> <arg2> <arg3>". The service is installed under the name "j5Server"

One point which must be noted is that a service is started with a different path, so all file system references need to be absolute.

* Check all configuration files for file or directory names. Make sure they contain the full path

* Configuration files specified on the command line need to be absolute paths. If they have spaces in their names, they need to be enclosed in double quotes

e.g. sjsoftWinService --serviceinstall "c:\Program Files\sjsoft- j5\petrofacc\petrofacc.config.global" "c:\Program Files\sjsoft- j5\petrofacc\petrofacc.config.local"

Other arguments for installation:

* --serviceuser=username

o Specifies the user with which to run the service

* --servicepassword=password

o Specifies the password of the user with which to run the service

* --servicestartup=startuptype

o startuptype is one of "manual", "auto" or "disabled". Specifies the default service startup option

Uninstalling

To uninstall, run the service executable with the option "--serviceremove", e.g. "sjsoftWinService -- serviceremove".

Controlling from the Command Prompt

The following arguments can be specified on the command-line to the service executable to control the service:

* --servicestart

This will start the service

* --servicerestart

This will restart the service

* --servicestop

This will stop the service

* --servicestatus

This will print out the running status of the service

6.4.2 Batch Installation

Downloading and InstallingDownload the file http://www.sjsoft.com/download/sjsoft-j5- 1.0.2-install-pack.zip

Unzip the application into an install folder and run the application:

install_sjsoft_j5_with_apache.bat

If you have IIS in the same machine:Stop IIS (IIS Admin Service)

3. This will tell you there are some services which depend on it. Make note of which services they are, as you'll need to start them again later

Run the install scriptRun the install_sjsoft_j5_with_apache.batscript from the command prompt (this is in the apache-dist directory)

4. Generally you click a lot of “Next” in this step

5. Installing Apache

1. Install Apache for all users on port 80

2. You need to fill out correct domain names (can just use the computer network name, as long as that is how other computers will access it) and administrator's email address

http://www.sjsoft.com/download/sjsoft-j5-1.0.2-install-pack.zip

6. Installing mod_python

1. Just click OK in the mod_python install when it asks for the Apache directory

7. If you get any Package is broken or Package is corrupted messages (happens if a download was interrupted or broken):

1. Continue through the rest of the installs (unless it happens in the Python or Apache installs)

2. Afterwards, remove the offending install file from the apache-dist folder on your machine

3. Run python download.py again

4. Copy the redownloaded install across

5. Run just the corrupted install again

Once you have completed this section, you need to go to the section on configuring Apache in the Large Installation section.

6.5 Upgrades and Site FilesAlthough the j5 system is included in the install pack, often the version in the install pack is a number of revisions behind the latest j5 installer. Because of this, it is usually necessary to download and install the latest j5 installer. The new installer can be found at:

New install at http://www.sjsoft.com/download/sjsoft-j5-r.r.r.win32- py2.5.exe

where r.r.r is the latest revision number. (currently 1.4.5)

(Note the server referenced below can be either the standalone server or Apache)

6.5.1 New Release Install8. Do any necessary backups. (You can make a copy of the whole site folder if you like.)

9. Stop the server; run the installer (sjsoft-j5- r.r.r.win32- py2.5.exe) ; start the server

10. Go to web site, verify it is still running successfully

6.5.2 Site InstallThe site install will include the latest business rules and templates. Often this is prepared for you by St James Software. To install such a site,

· Go to the Server Admin interface, upload the site file <sitename>- yyyymmdd.zip with the Config and Import Instance items checked (but not the Database item)

· Restart server

6.5.3 Database InstallIn some cases, you will need to update the database itself. (Usually occurs during the early stages of a project)

· Click on the dbviewer tab,

· Upload the new <sitename>-db-YYYYMMDD.zip. (Check all 3 check boxes in the upload.)

· Restart Apache.

6.6 Starting the server

6.6.1 Standalone VersionTo start the j5 system, cd into the c:\program files\sjsoft- j5\customers\<customerName> folder and enter the following command:

..\..\sjsoftstart global.config local.config

Note that there is often a batch file in the same folder called startj5.bat which will start the j5 system. Likewise, you can start the j5service with the startj5service.bat file.

Once the server has started, open IE or Firefox and enter the URL

http://<nameOfYourComputer>:8080

You should be able to log in as admin with the password test.

Note: If you want to change the port number, see the section on j5 Port Numbers below.

6.6.2 Apache VersionSimply start the Apache Web Server by clicking on the apache icon in the tray and selecting start.

Once the server has started, open IE or Firefox and enter the URL

http://<nameOfYourComputer>

where <nameOfYourComputer> is the name of the server computer.

You should be able to log in as admin with the password test.

6.7 The Server Admin ApplicationThe Server Admin Application is the console used to maintain most of the administration tasks.

The Server Admin Application is a j5 web-based application which runs on port 6425 by default. (You can change the port number if required, see below).

It is not necessary to have a database connection to run the server admin application.

Once you have started the j5 Server and have logged into the j5 system via a Browser like I.E. or Firefox, just click on the Server Admin Tab to see the Server Admin Options.

6.8 Setting the j5 Port Number

6.8.1 j5 Port NumberNote: If you want to change the port that you are to connect to, (from the default of 8080,) enter this line in the config.local configuration file.

web.default.port = 8082

Where in this case, 8082 is the new port number.

6.8.2 Server Admin Port NumberThe server admin application uses the port 6425 by default. You can change this by adding the following lines in the config.global file:

_adminapp is j5.Control.ServerConfig.ApplicationNode

_adminapp.web.default.port = 6062

_adminapp.web.default.baseurl = "adminapp"

In this example, the port will be set to port 6062

6.9 System Status OverviewThe status overview page provides:

· An overview of the status of the server and also each of the applications.

· Ability to stop or start the applications and the server

· Facility to save or restore the configuration.

6.10 Application MonitoringYou can see the health of the application from the Server Admin page under the tab Apps.

You can also manage the basic functionality of the application from here.

Note that there is an overview of each of the applications on the status page.

6.11 Backing Up and Restoring

6.11.1 Backing Up the j5 System

To back up a complete j5 system, you should:

· Back up the relevant databases

There may be several connected to multiple applications) This is normally considered as part of the corporate back up procedure. I.e. the corporate backup procedure will normally automatically back up the databases regularly and this is considered sufficient.

· Backup the relevant configuration files

There are several configuration files which should be backed up regularly. These files include the license file and the resources files as well as the templates and business rules files.

Typically, the complete directory structure is held in the c:\program files\j5 folder. If this folder and its sub-folders are regularly backed up, then this is considered sufficient.

6.11.2 Restoring the j5 System

In the unlikely event that there is a catastrophic breakdown of the system. E.g. the disk is disrupted, the following procedure should be carried out:

1. The database backup should be used to restore the database

2. The configuration backup should be used to restore all the configuration files

3. The j5 system should be re-installed from the latest installation files (available on the web at http://www.sjsoft.com/download)

4. A new license (if the software has to be relocated to a new machine) must be acquired from St James Software.

6.11.3 Partial Backups

If you require partial backups of the database. To achieve this, use the DBViewer facility. I.e. click on the Data Base Browser tab and locate the database table to be backed up. Then click on the XML tab. (A screen showing the complete xml of the database will appear.) Save this information into a file using the browser's file saving facility. (E.g. File, Save As ...)

To back up all the tables, click on the “XML for all Tables” link at the bottom of the page.

6.11.4 Restoring Tables

To restore the data from an xml file, use the Browser to locate the file, select the options you require (see below) and click on the “upload” button.

Note: You can also save and restore from Zip files. (Zip files must have been previously created using the DBViewer facility.

6.11.5 Creating a Customer SiteThe j5 framework has the concept of a site for specific configurations.

A site consists of:

* A config file

* Optional database setup (table structure and data)

* Optional custom files

which can be installed and upgraded in the Server Admin interface.

Creating a site install specification

In the customer site directory (e.g. "customers/newsite"), create a file called "sitedetails.py". All files specified should be relative to the customer site directory. In this file, define three Python variables:

* configfiles - this should be a list of the config files to include in the install. It allows you to define multiple config files, if

there's a reason to separate out the configuration into different files. e.g. configfiles=['newsite- install.config']

- NOTES

- All files need to end in the prefix ".config"

- All absolute paths in the config file (e.g. "c:\mysites\customers\newsiteMetering") should replace the full path

to the customer site directory with "${customdir}" (e.g. "${customdir}\Metering")

- Make very sure all secret information (e.g. database passwords) is removed from the config files

- Make sure the config file is in subversion so anyone can generate the install.

* databases - this should be a dictionary mapping database resource names to xml files containing the tables to be imported.

e.g. databases={'default':'dbxml/alltables.db.xml'}

- NOTES

- The name of the database resource refers to the name in the config file - so for the example above, there will be (at the time of data import) a "database.default" section in the config

- Make sure the xml does not contain rows of data which you don't want automatically loaded into the client's database on install

* sitefiles - a list of files to install in the custom directory on installation of the site. This should include all .py and .Genshi files,

all .css files, all custom images, etc.

e.g. sitefiles=['Logbook/Logbook.py', 'Logbook/Logbook.Genshi', 'css/*.css']

Creating a site install zip

First, make sure the sitedetails.py file has been created and is in the customer's directory. Then, open a command shell in the "customers" directory.

Run "python makesite.py <customerdir>", e.g. "python makesite.py acme". In the example given, this will produce a file

called "acme-site-yyyymmdd.zip" (where yyyymmdd will be filled in with the year, month and day).

6.12 Monitoring the ResourcesThis section describes the facilities for monitoring the various resources used by and within the j5 system.

6.12.1 Database Monitoring and Management

The facilities available for monitoring and management will depend on the database chosen. Generally, modern database systems provide management and monitoring facilities to ensure the smooth operation and integrity of the database. The Database Manager should follow the normal database management scenario for the databases connected to the j5 system. This includes for example:

1. Managing the size of the database and ensuring that there is sufficient space for the addition of new data.

2. Monitoring the processes and the frequency of errors and clashes.

3. Monitoring the speed of typical retrievals.

4. Monitoring the amount of cpu usage of the database.

5. Managing the user system and where necessary promulgating a password change mechanism to ensure the security of the database.

6. Managing the Authentication server.

Additionally, the Database Manager should have put a regular backup procedure in place. In the unlikely even that there is a catastrophic failure, there should be a procedure for restoring the database.

Web ResourceInformation on the web resource can be accessed from the Resources page.

Typically, an Apache web server, a CherryPy web server or a SimpleHTTP server will be used.

6.12.2 Storage Resourcedefines where attachments are stored.

Authentication Resourcedefines how the users are authenticated. (Using the internal authentication or the LDAP authenticator.

Other Resourcessuch as OPC servers or special components are also defined here.

Here is an example of an OPC configuration:

6.13 User and Group ManagementThe system enables users (who are authenticated) to be added to groups. Each group defines the characteristics (e.g. permissions of its members.)

6.13.1 Group DefinitionsEach group defines:

· which applications (the programs behind the logbooks) the group can access,

· the rights and of its members to see forms (generally, these are the names of the logbooks and shift reports.),

· the rights (view, read, modify, delete) of its members for tables.

6.13.2 Configuring a GroupTo configure a group, you can either enter the config information directly into the config file (we recommend you attend the training before doing this (see the Section Editing the Config File.) or use the following procedure using the server admin pages:

Create the GroupLog in as admin, click on the Server Admin tab and then click on the Groups Tab. Then click on the New group... option. I.e.

Enter the name of the new group and click on the Save Config link.

The new group will now appear in the list of groups in the pull down.

Enable the Applications for the New GroupSelect the new group from the combo (in this case Technical ) and modify the permissions for the different applications.

Click on the Save Config to save the settings.

Give the new Group Access to the FormsThis is where you allow the new Group to access the Forms. (I.e. the individual templates that you have configured into the system.)

Select the new group (in this case Technical) from the left combo and the forms option from the right combo.

Using the Add Form link, enter the names of the forms you want this group to have access to. I.e.

Choose the Can View option if you want this group to be able to view the form and the Can Design option if you want this group to be able to design the form.

Click on the Save Config link to save this information.

6.13.3 Give the new Group Access to the Tables.First select the group (in this case Technical) and then in the right combo, the tables option.

Use the Add Table facility to add new tables to this user groups permissions.

Select whether you want the user to be able to View, Add, Modify or Delete from each of the tables.

Click on the Save Config Link when you are happy with the configuration.

6.13.4 Provide advanced (rule based) permissions for the tables.You can assign more advanced rule based permissions to each table.

In the example below, the user is only allowed to modify the table if the j5username field is set to the current user. I.e. the user can only modify his or her own logs.

For more advanced rule based permissions (e.g. to limit the changes of a log to a defined grace period), you can use the authentication rules in the business rules program.

6.13.5 Advanced Permission Modifications by directly setting the config files

For advanced users, you can directly change the config files using the facilities described below:

In a text editor, open the configuration file. (It will be in the j5\<sitefolder> folder.)

Example 1: To allow full access to the tables, add the following lines to the config file.

groups.Test.tables.logbook.rights is j5.Database.Config.TableScopeRights.Loose

groups.Test.tables.logbook.rights.all.first = True

Example 2: For more complicated permissions, you can assign multiple rules to the table permissions. E.g.

groups.Test.tables.orderbook.rights is j5.Database.Config.TableScopeRights.Loose

groups.Test.tables.orderbook.rights.add.rule = True

groups.Test.tables.orderbook.rights.modify.rule = 'j5username = ${user}'

groups.Test.tables.orderbook.rights.view.rule = True

groups.Test.tables.orderbook.rights.delete.rule = False

This will allow adding of new records, no deleting, modifying only if the user is the original author and viewing of the records in the table.

Note: You can put these directives anywhere in the config file.

Once you have saved the rules for the tables, you should restart the web server and check that the rules are operational.

For the configuration above, the table rights should look like this:

6.13.6 Adding column specific rightsYou can also control the rights of users to access specific columns in the database table. This too can only be done directly in the config file. For example, to limit the user to only viewing the data in the column j5username, add this statement to the config file:

groups.test.tables.logbook.rights.columns.j5username is j5.Database.Config.TableScopeRights.Loose

groups.test.tables.logbook.rights.columns.j5username.view.rule = True

The resulting entry in the Server Admin page will look like this.

Note: Setting view True implies that the user can only view the column. Setting modify will imply the user can view and modify the column.

6.14 User Management

6.14.1 UsersUsers are assigned to groups in the Server Admin Page. If the authentication is local, then the password (encrypted) must also be stored in the configuration file.

6.14.2 Adding a User to the New GroupClick on the Users Tab in the Server Admin Tab and enter the data as shown below.

6.14.3 Setting or changing the PasswordClick on the Users Tab in the Server Admin Tab and enter the new password as shown below.

6.14.4 LDAP ConfigurationIf you are using LDAP, you do not need to add any more information, since the LDAP server will be doing this for you.

6.15 Version ControlVersion control Information can be obtained from the Version tab in the server admin page.

6.16 LicensingThe licensing information can be retrieved from the Licenses tab of the Server Admin Page.

The information on this screen will tell you where the license is located.

The license relates to:

· The kind of applications you can run,

· The allowable version number of each application,

· The number of concurrent sessions you can run, (please see the subsection Automatic Log Off below which describes how idle users will be automatically logged off.)

· The kind of databases you can connect to,

· The machine that the license is valid for. Typically permanent licenses are issued for a specific machine that is identified by the Machine Code.

Here is an example of a license that will work on any machine and will allow 10 users to access the logbook application (up to version 1.99) up to the 30th October, 2007.

sjsoft.Apps.Logbook 1.2

License status valid license

License file C:/program files/sjsoft-j5/customers/demo/logbook_shiftrep.lic

Machine code ak1hY2hpbmUgMS4wCjc2NDg3LU9FTS0wMDExOTAzLTAwMTAwCjMyMEQxODBF

Product sjsoft.Apps.Logbook version 1.99

Licensed to St James Software, None (None)

maxsessions 10

maxmachines 1

expiry 2007-10-30 00:00:00

Note: To create a permanent license, you will need to copy and paste the Machine Code information (from your licenses page) into an e-mail to St James Software. St James Software will send the permanent license back via e- mail to you.

6.16.1 Automatic Log OffThis facility is designed to prevent inactive logged-on users from using the available concurrent licenses to the detriment of users who want to use the logbooks.

If the number of users is about to exceed the licensed number of users, the system looks for idle users and logs them off so that the licensed number is not exceeded.

Here is a summary of how this works:

* The system keeps track of when each user last accessed a Logbook.

* The system marks a logged on user as idle if the user has not used the system for more than 10 minutes.

* For convenience, if someone tries to access Logbook, and the number of licensed users has been exceeded, the system invalidates (logs off) any idle sessions, so that the new person trying to access Logbook can do so.

* No invalidation (logging off) happens unless the number of licensed users is exceeded.

* If the number of users supercedes the number licensed and there are no idle users, then the system will present a screen to that effect, and the new user will not be able to access the Logbooks.

6.17 Languagesj5 supports multiple languages. The management of the languages is via the Localization tab in the server Admin Pages.

There are a number of levels of localization:

1/ Information in the templates and business rules.

2/ Messages created by j5: E.g. Please enter your password.

These are created by the end-user configuration using the PO tool which is part of the j5 software.

Here are the procedures for managing the localization:

6.17.1 Steps required in a project.

1/ Creating the POT (Template) files (This is the source of English phrases)

Log in to j5 as admin and click on the server admin tab,

Click on Localization

Click on Extract Templates. This will create the templates for all the applications)

2/ Set up the folders

Find the po folder (its under for example the Shifts application)

add a new folder called es (in the spanish example.)

2/ Creating the PO Files. (There is a po file for each language) This example is spanish.

Start the poedit program

click file, new catalog from POT file

go to the templates folder (e.g. under Shifts)

copy the name of the pot folder (for later pasting) e.g. sjsoft.Apps.ShiftReports.custom.shiftrep.pot

then open the pot file

Add any settings to the settings screen. (e.g. your email address)

Go up one level in folders then down to the es folder

Save the file as sjsoft.Apps.ShiftReports.custom.shiftrep.po (same name but with a po extension.)

You should see the catalog in front of you.

3/ Adding to the dictionary.

start poedit

click Open or click on one of the previously selected catalogs.

The editor will look similar to this:

Use Control Up arrow or Control Down Arrow to navigate and enter the translations.

When finished, click Save

4/ Compiling the dictionaries

Log in to j5 as admin and click on the server admin tab.

Click on Localization.

Select the language from the list.

Click Compile Messages.

(No need to restart)

6.18 Advanced AdministrationThe Advanced Tab provides for detailed information on the system configuration. Essentially, it is a way to view every item in the system configuration file.

6.19 Error and Trace FilesThe j5 Logbook system provides a comprehensive trace on any problems detected in accessing the database. This trace information will be time and application stamped and will generally provide a printout of the SQL statement that was involved in the problem.

6.19.1 Viewing the Error and Trace FilesYou can view the error and trace log files from the Server Admin Application by clicking on the Logging tab.

As shown above, the different log files are organized into Critical, Error, Warn and Info.

Generally, you should only be concerned with Error and Critical messages. For tracing and information purposes, you can also monitor the Warn and Info tabs.

6.19.2 Location of Error and Trace FilesThe location of the logs is defined in the configuration file.

To make the system create log files, you should add the following lines to the configuration files. (Typically the config.local file.)

logger is j5.Logging.Config.RotatingFileLogger.RotatingFileLogger

logger.filename = 'C:\Program Files\sjsoft-j5/logfile.txt'

logger.loglevel = 'info'

In this example, a log file called logfile.txt will be created in the C:\Program Files\sjsoft-j5 folder.

6.19.3 For apache systemsThe logs can be reached from the apache, log file menu.

The j5 system also generates Error, Audit and Trace Files. These files can be accessed at any time to get a history of the interactions occurring in the system. In the event that there is a problem, then these files will give a comprehensive summary of the workings of the system during the problem.

6.19.4 Error Procedures

Procedures to follow in the event of an Error

Errors may be classified as:

1. User errors: The system will generally inform the user of the problem and it can be corrected,

2. Database errors: Errors that result from an attempted operation with the database. The system will attempt a reconnection with the database which usually correct the problem. The j5 system will in any event provide sufficient diagnostics to define the exact problem.

3. Operating system errors and web server errors: The j5 system will generally be able to point the system administrator to the system causing the problem.

4. j5 errors: These can be divided into non-critical errors (which do not cause a loss of service to the users) and (unlikely) critical errors. In both cases, the system will provide comprehensive diagnostics so that the issue may be quickly addressed.

Typically, error messages comprise a “stack trace” which will quickly point to the location of the problem. These error messages can be emailed to St James Software if required.

6.19.5 Debugging via Error MessagesThere are various levels of error messages that can be completed. I.e.

warning, error, info and debug. You set the logging level in the startup script. E.g.

..\..\src\sjsoft\sjsoft.py demo.config --loglevel=warning

The amount of information will depend on the logging level with no loglevel set as the lowest amount and debug as the highest amount.

so if you select error you get error

warning gives you error + warning

info gives you error + warning + info

debug gives you error + warning + info + debug

These levels of debug are activated via the start up command. I.e. in the startup command, you would add the token:

--loglevel=error

to see all messages that have a severity of warning and error. If you set:

--loglevel=debug

then you would see levels, warning, error, info and debug.

If you want to force a log message, then in the py file, you would

import logging

and use a statement like:

logging.warning("This message will print out")

then set the logging level at the startup prompt.

NOTE: If you do not use the --loglevel in the startup script, you will get all the error and warning messages in the command console.

Warning: It is not a good idea to leave the debug level at an elevated level for an extended period since a large amount of debug information will be stored in the log files.

6.19.6 Running as a standaloneFor debugging purposes, sometimes it is worth while to run j5 at the command shell. This means that the output (and input for pdb) is available for debugging

· Set the python path to include access to the j5 and sjsoft directories and run "python sjsoftstart.py configfile"

· Then create a modified configfile with the correct web resource (i.e. SimpleHTTP and not Apache).

6.20 TroubleshootingThis section handles commonly encountered problems and how to solve them. If there you have difficulties and cannot find a solution in this section, please call your system administrator who will advise you about the next steps.

6.20.1 Canonical URLsYou can force the default web address of jLogbook using the Canonical specification. I.e.

web is j5.Control.ServerConfig.ResourceTypeNode

web.default.canonical_url = 'http://oermlogbook.dev.cheniere.com'

This means you will be able to connect to the Logbook via

http://oermlogbook.dev.cheniere.com

The tabs will then hold a URL similar to the following:

http://oermlogbook.dev.cheniere.com/chenlogbook/view/LabNames

In the above is for the application chenlogbook and the Logbook is LabNames.

6.20.2 Logging In· When logging in, you must have (i) a valid username and (ii) a valid password and you must enter

this information correctly. If this information is not entered into the log in screen correctly, then the screen will clear and prompt you to enter it again. (There will be no additional message saying that you have failed to enter a valid user name and password.)

· If you still cannot log in correctly, please call your systems administrator to verify that you have the correct username and password.

· Note that in some systems (ones that use LDAP) the capitalization is important.

6.20.3 Remote ConnectionsIf you are having no difficulties connecting to the server when you run a browser on the server machine, but you cannot connect to the same server when running a browser on a remote machine, then you should look at the following steps:

1/ On the server machine, in the firewall, open the ports 8080 and 6425. Your firewall may be Windows firewall, Nortons or another firewall. You can test that it is open using the telnet facility described below.

2/ If you are running j5 as a service, and you cannot connect remotely, it may be that the user associated with the service does not have the right permissions. When the service is installed, by default, the default is set to Local System Account. If this does not have networking permissions, then you need to (i) change it to an account that does have networking permissions and(ii) change the startj5service.bat file as described below.This will start the service up with the correct user group the next time round.

Changing the User Account associated with the j5 Service· Open the services panel from the control panel

· Click on the j5 service link and select properties

· Click on the Log On tab and then on the This Account radio button

· Enter the require user name and password (twice)

· Click on the OK button

· Restart the service

· Connect via the remote computer

· (If this works, don't forget to change the startj5service.bat script as described below since (if you don't), the j5startservice.bat program will remove the existing service and reinstall a new one (with the account Local System Account).

Updating the startj5service.bat fileUsing an editor like notepad, add the user name and password in the statement:sjsoftWinservice --serviceinstall "c:\program files\sjsoft- j5\customers\demo\config.global" "c:\program files\sjsoft- j5 \customers\demo\config.local" --servicestartup=auto --serviceuser=<username> -- servicepassword=<password>

Testing the port remotelyYou can test the server port remotely as follows:

· On the remote computer, in a command shell, type telnet <serverIPAddress> 8080 (Where serverIPAddress is the IP address of the server machine)

· If the connection is open, the screen should go blank. Press Q to get back to the prompt.

· If there is a problem, it will say: telnet <serverIPAddress> 8080 Connecting To 127.0.0.1...Could not open a connection to host on port 8080 : Connect failed

Documents

j5 Administration Manual V2.doc