How-To Tutorials

The advantage of separating out decision points as external rules is that we not only ensure that each rule is used in a consistent fashion, but in addition make it simpler and quicker to modify; that is we only have to modify a rule once and can do this with almost immediate effect, thus increasing the agility of our solution. Business Rule concepts Before we implement our first rule, let's briefly introduce the key components which make up a Business Rule. These are: Facts: Represent the data or business objects that rules are applied to. Rules: A rule consists of two parts, an IF part which consists of one or more tests to be applied to fact(s), and a THEN part, which lists the actions to be carried out should the test to evaluate to true Rule Set: As the name implies, it is just a set of one or more related rules that are designed to work together . Dictionary: A dictionary is the container of all components that make up a business rule, it holds all the facts, rule sets, and rules for a business rule. In addition, a dictionary may also contain functions, variables, and constraints. We will introduce these in more detail later in this article. To execute a business rule, you submit one or more facts to the rules engine. It will apply the rules to the facts, that is each fact will be tested against the IF part of the rule and if it evaluates to true, then it will perform the specified actions for that fact. This may result in the creation of new facts or the modification of existing facts (which may result in further rule evaluation). Leave approval rule To begin with, we will write a simple rule to automatically approve a leave request that is of type Vacation and only for 1 day's duration. A pretty trivial example, but once we've done this we will look at how to extend this rule to handle more complex examples. Using the Rule Author In SOA Suite 10.1.3 you use the Rule Author, which is a browser based interface for defining your business rules. To launch the Rule Author within your browser go to the following URL: http://<host name>:<port number>/ruleauthor/ This will bring up the Rule Author Log In screen. Here you need to log in as user that belongs to the rule-administrators role. You can either log in as the user oc4jadmin (default password Welcome1), which automatically belongs to this group, or define your own user. Creating a Rule Repository Within Oracle Business Rules, all of our definitions (that is facts, constraints, variables, and functions) and rule sets are defined within a dictionary. A dictionary is held within a Repository. A repository can contain multiple dictionaries and can also contain multiple versions of a dictionary. So, before we can write any rules, we need to either connect to an existing repository, or create a new one. Oracle Business Rules supports two types of repository—File based and WebDAV. For simplicity we will use a File based repository, though typically in production you want to use a WebDAV based repository as this makes it simpler to share rules between multiple BPEL Processes. WebDAV is short for Web-based Distributed Authoring and Versioning. It is an extension to HTTP that allows users to collaboratively edit and manage files (that is business rules in our case) over the Web. To create a File based repository click on the Repository tab within the Rule Author, this will display the Repository Connect screen as shown in the following screenshot: From here we can either connect to an existing repository (WebDAV or File based) or create and connect to a new file-based repository. For our purposes, select a Repository Type of File, and specify the full path name of where you want to create the repository and then click Create. To use a WebDAV repository, you will first need to create this externally from the Rule Author. Details on how to do this can be found in Appendix B of the Oracle Business Rules User Guide (http://download.oracle.com/docs/cd/B25221_04/web.1013/b15986/toc.htm). From a development perspective it can often be more convenient to develop your initial business rules in a file repository. Once complete, you can then export the rules from the file repository and import them into a WebDAV repository. Creating a dictionary Once we have connected to a repository, the next step is to create a dictionary. Click on the Create tab, circled in the following screenshot, and this will bring up the Create Dictionary screen. Enter a New Dictionary Name (for example LeaveApproval) and click Create. This will create and load the dictionary so it's ready to use. Once you have created a dictionary, then next time you connect to the repository you will select the Load tab (next to the Create tab) to load it. Defining facts Before we can define any rules, we first need to define the facts that the rules will be applied to. Click on the Definitions tab, this will bring up the page which summarizes all the facts defined within the current dictionary. You will see from this that the rule engine supports three types of facts: Java Facts, XML Facts, and RL Facts. The type of fact that you want to use really depends on the context in which you will be using the rules engine. For example, if you are calling the rule engine from Java, then you would work with Java Facts as this provides a more integrated way of combining the two components. As we are using the rule engine with BPEL then it makes sense to use XML Facts. Creating XML Facts The Rule Author uses XML Schemas to generate JAXB 1.0 classes, which are then imported to generate the corresponding XML Facts. For our example we will use the Leave Request schema, shown as follows for convenience: <?xml version="1.0" encoding="windows-1252"?> <xsd:schema targetNamespace="http://schemas.packtpub.com/LeaveRequest" elementFormDefault="qualified" > <xsd:element name="leaveRequest" type="tLeaveRequest"/> <xsd:complexType name="tLeaveRequest"> <xsd:sequence> <xsd:element name="employeeId" type="xsd:string"/> <xsd:element name="fullName" type="xsd:string" /> <xsd:element name="startDate" type="xsd:date" /> <xsd:element name="endDate" type="xsd:date" /> <xsd:element name="leaveType" type="xsd:string" /> <xsd:element name="leaveReason" type="xsd:string"/> <xsd:element name="requestStatus" type="xsd:string"/> </xsd:sequence> </xsd:complexType> </xsd:schema> Using JAXB, particularly when used in conjunction with BPEL, places a number of constraints on how we define our XML Schemas, including: When defining rules, the Rule Author can only work with globally defined types. This is because it's unable to introspect the properties (i.e. attributes and elements) of global elements. Within BPEL you can only define variables based on globally defined elements. The net result is that any facts we want to pass from BPEL to the rules engine (or vice versa) must be defined as global elements for BPEL and have a corresponding global type definition so that we can define rules against it. The simplest way to achieve this is to define a global type (for example tLeaveRequest in the above schema) and then define a corresponding global element based on that type (for example, leaveRequest in the above schema). Even though it is perfectly acceptable with XML Schemas to use the same name for both elements and types, it presents problems for JAXB, hence the approach taken above where we have prefixed every type definition with t as in tLeaveRequest. Fortunately this approach corresponds to best practice for XML Schema design. The final point you need to be aware of is that when creating XML facts the JAXB processor maps the type xsd:decimal to java.lang.BigDecimal and xsd:integer to java.lang.BigInteger. This means you can't use the standard operators (for example >, >=, <=, and <) within your rules to compare properties of these types. To simplify your rules, within your XML Schemas use xsd:double in place of xsd:decimal and xsd:int in place of xsd:integer. To generate XML facts, from the XML Fact Summary screen (shown previously), click Create, this will display the XML Schema Selector page as shown: Here we need to specify the location of the XML Schema, this can either be an absolute path to an xsd file containing the schema or can be a URL. Next we need to specify a temporary JAXB Class Directory in which the generated JAXB classes are to be created. Finally, for the Target Package Name we can optionally specify a unique name that will be used as the Java package name for the generated classes. If we leave this blank, the package name will be automatically generated based on the target namespace of the XML Schema using the JAXB XML-to-Java mapping rules. For example, our leave request schema has a target namespace of http://schemas.packtpub.com/LeaveRequest; this will result in a package name of com.packtpub.schemas.leaverequest. Next click on Add Schema; this will cause the Rule Author to generate the JAXB classes for our schema in the specified directory. This will update the XML Fact Summary screen to show details of the generated classes; expand the class navigation tree until you can see the list of all the generated classes, as shown in the following screenshot: Select the top level node (that is com) to specify that we want to import all the generated classes. We need to import the TLeaveRequest class as this is the one we will use to implement rules and the LeaveRequest class as we need this to pass this in as a fact from BPEL to the rules engine. The ObjectFactory class is optional, but we will need this if we need to generate new LeaveRequest facts within our rule sets. Although we don't need to do this at the moment it makes sense to import it now in case we do need it in the future. Once we have selected the classes to be imported, click Import (circled in previous screenshot) to load them into the dictionary. The Rule Author will display a message to confirm that the classes have been successfully imported. If you check the list of generated JAXB classes, you will see that the imported classes are shown in bold. In the process of importing your facts, the Rule Author will assign default aliases to each fact and a default alias to all properties that make up a fact, where a property corresponds to either an element or an attribute in the XML Schema. Using aliases Oracle Business Rules allows you to specify your own aliases for facts and properties in order to define more business friendly names which can then be used when writing rules. For XML facts if you have followed standard naming conventions when defining your XML Schemas, we typically find that the default aliases are clear enough and that if you start defining aliases it can actually cause more confusion unless applied consistently across all facts. Hiding facts and properties The Rule Author lets you hide facts and properties so that they don't appear in the drop downs within the Rule Author. For facts which have a large number of properties, hiding some of these can be worth while as it can simplify the creation of rules. Another obvious use of this might be to hide all the facts based on elements, since we won't be implementing any rules directly against these. However, any facts you hide will also be hidden from BPEL, so you won't be able to pass facts of these types from BPEL to the rules engine (or vice versa). In reality, the only fact you will typically want to hide will be the ObjectFactory (as you will have one of these per XML Schema that you import). Saving the rule dictionary As you define your business rules, it makes sense to save your work at regular intervals. To save the dictionary, click on the Save Dictionary link in the top right hand corner of the Rule Author page. This will bring up the Save Dictionary page. Here either click on the Save button to update the current version of the dictionary with your changes or, if you want to save the dictionary as a new version or under a new dictionary name, then click on the Save As link and amend the dictionary name and version as appropriate.

The Microsoft SQL Server 2008 Reporting Services Report Builder 2.0 tool can be installed from a standalone installer available at this Microsoft site, http://download.microsoft.com/download/a/f/6/af64f194-8b7e-4118-b040-4c515a7dbc46/ReportBuilder.msi. The same file is also available from a collection of download files when you access the Microsoft SQL Server 2008 Feature Pack, October 2008 at http://www.microsoft.com/downloads/details.aspx?FamilyId=228DE03F-3B5A-428A-923F-58A033D316E1&displaylang=en. Report Builder overview In the present version of SQL Server 2008 [Enterprise Evaluation edition] there  are two Report Builders available. Report Builder 1.0, which has remained as a program that can be launched from the Report Manager, and the new Report Builder 2.0, which is a stand alone report authoring tool that needs to be independently launched. Although Report Builder 1.0 can access Report Models built with Visual Studio 2008 and the Report Manager, it cannot be used to create reports using those models. It also does not work with Reports generated by Visual Studio 2008/BIDS/Report Builder 2.0. The errors can be summarized as follows: When you try to access the Report Server 2008 from the link provided on the Report Builder 1.0 interface you get the following error message: Specifying credentials in a URL is not supported When you try to open a report created using VS2008/BIDS/ReportBuilder2.0 using the Open Report… and Open File… navigational items in Report Builder 1.0 you get the following error message: System.IO.StreamReader: The Report element was not found Report Builder 1.0 allows you to access Report Models created with VS2008/BIDS/Report Manager and even allows you create a report in design view but this report cannot be processed on the Report Server. If you try to do so, you get the following error message: MemoryStream length must be non-negative and less than 2^31-1-origin. Parameter name: offset; Remote GDI stream version: ?. Expected version: 11.0.1 In this article the Report Builder 2.0 interface will be described along with the new features that are incorporated into this version. Report Builder 2.0 is admirably suited to address all items in the Report Definition Language of 2008. One of the important features of Report Builder 2.0 is the empowerment it provides business users to create ad hoc reports using the Report Models built on the databases they use. In this article you will be learning mostly about the Report Builder 2.0  interface details and working with it to create reports or modify them. It may be noted that Report Builder generates 2008 compliant RDL files as described in http://download.microsoft.com/download/6/5/7/6575f1c8-4607-48d2-941d-c69622e11c32/RDL_spec_08.pdf and therefore, cannot work with reports generated using 2005 technology. Report Builder 2.0 user interface description Report Builder is a report authoring tool and the basic procedure for authoring a report consists of the following steps: Report planning Connecting to a source of data Extracting a dataset from source Designing the report and data binding Previewing the report Although deploying the report is not included in the above, Report Builder can deploy the report as well. It is not always necessary to deploy a completed report, as any part of a report definition file can be deployed. This makes modifying a report on the server very flexible. In the following sections, the various parts of the Report Builder interface will be described starting at the very top and going to the bottom of the interface The menu for file operations Report Builder 2.0 can be accessed from Start | All Programs | Microsoft SQL Server 2008 Report Builder | Report Builder 2.0. This brings up the Report Builder Interface 2.0 as shown with the design area containing two icons: Table or Matrix and Chart. Each of these will launch a  related wizard which will step you through the various tasks. The Report Builder 2.0 interface is very similar to Office 2007. More than one instance of Report Builder can be launched. At the very top of the following screen shown you have the undo and redo controls as well as a save icon. When you click on the save icon the Save as Report window gets displayed as shown. Here you provide a name for the report. The default save extension is  *.rdl and it will be saved to the report server. It may also be persisted to a folder on your machine. Clicking on the Office Button (top left) opens a drop-down window shown in the following screenshot: In this window, you can carry out a number of tasks such as creating a new report, opening an existing report, saving a report, and saving a report with a different name. The Save button saves it to the default location seen earlier and Save as invokes the same window to save the report with a different name as seen earlier displying the report server instance as the Save to location. The Recent Documents pane shows the more recent reports created with this tool. New allows you to create a new report. When you click on Open, the following Open Report window gets displayed with the default location http://Hodentek2:8080/ReportServer_SANGAM/My Reports. You will also notice the message: This folder is not available because the My Reports feature is not enabled on the computer. Also the Open Reports window allows you look for reports with the extension .rdl. Therefore, unless the My Reports feature is enabled, this window is unusable. This is supposed to be possible from Report Manager but there are no controls in Report Manager that would do this. An alternative was suggested by one of the MSDN forum moderators (see http://social.msdn.microsoft.com/forums/en-US/sqlreportingservices/thread/6c695160-29e8-4185-be6d-5fe027a6975c/). Hands-on exercise (Part 2) will describe how you may enable My Reports. The idea of My Reports is similar to My Documents where each user can keep his reports. When the Options button (in the previous screenshot) is clicked it opens the window Report Builder Options window with two tabbed pages Settings and Resource shown as follows: Here you can view, as well as modify, Report Builder settings. The defaults are more than adequate to work with the examples in this book. Clicking on the Resources button brings up this interesting window which enables you to interact with Microsoft regarding SSRS activities, concerns, community, and so on. If you are serious about Reporting Services, these are very valuable links. The About button when clicked can provide you with Report Builder version information. The ribbon The main menu consists of Home, Insert, and View menu items which are part of the "ribbon". The ribbon introduced by Microsoft in Office 2007 is actually a container for other toolbar items. The ribbon is the replacement for the classic menus, toolbars, and is supposed to be more efficient and discoverable by the user. In fact you see a lot more on the "ribbon" than in the classic menu. Home The next figure shows the Home menu with its toolbar arranged from left to right and divided into sections. The Run toolbar item with the title Views when clicked would run the report open in the design view (in fact, even without a report open in the design view, the report can be run. The result would be the current date and time getting displayed in the center of the screen of an untitled report which has just ExecutionTime as the only item in the report). The Font, Paragraph, Border, and Number toolbar sections become enabled if parts of a report need editing. The formatting of textboxes in the report, the formatting of numbers in the report, and the alignment of components in the layout can all be independently managed using these toolbar items. Insert When you click on the Insert menu item on the "ribbon", the tabbed page for this item is displayed as shown in the following screenshot: It has four sections: Data Regions, Report Items, Subreports, and Header & Footer. These are all the normal items that are used either individually or together to make up a report. There can be more than one data region in a report. Data Regions In the Data Regions section you have both the Tablix (Table, Matrix, and List) and the graphic controls that can be bound to data—the Chart and the Gauge. Gauge is new in SQL Server Reporting Services 2008. Chart and gauge implementations are the off shoot of collaboration with Dundas (http://www.dundas.com/). Report Builder is built in such a way that the dataset must be defined before any of the data regions are added to the report body. For the purpose of describing the various data regions in this section, it is assumed (in order to get the screen shots shown here) that a dataset has been defined and the default wizards on the design surface have been removed. Table The Table is meant for displaying data retrieved from a database either all data detailed in groups or a combination (some grouped and some detailed) of both. It has a fixed number of columns which can be adjusted at design time. The table length expands to accommodate the rows. Data can be grouped by a single field or by multiple fields. Expression designer can be used in grouping as well. The grouping is carried out by creating row groups. Static rows can be added for row headings (labels) and totals. Aggregates for groups can be added. Both detailed data as well as grouped data can be hidden initially and the user can interactively reveal the data needed by drill downs. When you click on Insert | Table | Insert Table and then click on the design surface you can add a table to the design area. The table appears as shown with handles to adjust its dimensions. The table can be dragged to any other location on the design surface (the body of the report) as well. After placing the table, which by default has three columns and two rows, when you click on any other part of the design area you will see the table as shown. When you hover over the cell marked Data on the table you will see a little icon. This icon is a minimized version of the dataset fields. The grayed out feature that surrounds the table indicate the position of the rows and columns of the table. It also shows such other features as whether it is a detail, or whether it is a group. In the case of group, within a group the feature would indicate the nesting schematically as well. When you want to increase the size of a column or a row you can drag the double headed arrow that gets displayed when your cursor is placed between two columns or between two cells as shown. When you click on the dataset icon in the cell Data you get a drop-down list containing the fields in the dataset as shown. You can choose any of the fields to occupy the cell you clicked and the corresponding header will be added to the table. In this particular dataset there are nine fields and you can choose any of them to occupy the cell. When you right-click on a cell, a drop-down menu will be available. It can be used for the following: Work with the highlighted textbox (each cell of the table is a textbox) including to copy, cut, delete, and paste contents. Work with the properties of the Textbox. Populate the textbox with an expression using the expression builder. The expression builder gets displayed when fx Expression is clicked. Use Select to select the body or the Tablix. Insert a new column or a new row. Columns can be added to the right or the left of the clicked cell and rows can be added above or below the clicked cell. Delete columns and rows. Add a group. Both row and column groups can be added. When you click on the properties of the textbox, the Text Box Properties window is displayed. The textbox has several properties which are arranged on the left as a list with each item having its own page as shown. The Help button on any of the pages will take you directly to the definition of the properties and is extremely useful. In the General page, you can make changes to the elements in the Name, Value, and Sizing options page as shown. The Value is one which you choose among the column values (from the drop-down) from the dataset. You may also add a text for the ToolTip, which will display this text when the report is generated and this cell is accessed by hovering over it in the report. Alternatively you can set the Value and Tooltip using fx—the button that brings up the Expression window. In the Number page you can set the number and date data type formatting options for the cell that contains a number or a date. This is what you normally would find in most Microsoft products such as Excel and Access. In the Alignment page you can choose the vertical and horizontal alignments as well as the padding of the textbox content from the edges of the cell. Similarly the Font and Border properties are the same ones you find in most Microsoft products. The Fill property lets you add or change background color to the report as well as add a graphic element. The graphic element can be embedded, external, or originate from a database (being one of the fields accessed). Expressions can be developed to set a desired color for the Fill. The Visibility of the textbox can be any of Show, Hide, Show or Hide based on an expression. In each of these cases the visibility can be toggled when another table cell is clicked (which can be chosen). This page also gives access to the Expression window which is similar to the MS Access expression builder. The Interactive Sorting page allows you to define interactive sorting options on  the textbox. Matrix Matrix provides a similar functionality (roughly speaking rows against columns) to cross-tab reports in MS Access (http://aspalliance.com/1041_Creating_a_Crosstab_Report_in_Visual_Studio_2005_Using_Crystal_Reports.all) and Pivot Table dynamic views (http://www.aspfree.com/c/a/MS-SQL-Server/On-Accessing-Data-From-An-OLAP-Server-Using-MS-Excel/3/). The matrix should have at least one row group and one column group. The matrix can expand both ways to accommodate the data, horizontally for column groups and vertically for row groups. The matrix cells (intersection of rows and columns) display summary information (aggregates). When you click on Insert Matrix in the Insert menu and drop it on the design area of Report Builder 2.0, it gets displayed as shown in the following figure: Now if you click inside the boundary of the (2x2) empty matrix you will see more features of the matrix as shown in the following screenshot. The basic elements are the ColumnGroup (Column Groups), the RowGroup (Row Groups), and the Data. The group information is also displayed as shown by overlaid lines pointing to them. There needs to be a minimum of one group and one column for the matrix and there could be a hierarchy of column and row groups. The row and column group cells have their own properties which can be displayed when you right-click on them as shown in the next screenshot for the row group. When you right-click on the cell marked Rows, the following drop-down menu  pops up. In addition to the properties that you can set for the textbox in that cell, you have additional submenu items that work with the grouping and totaling. These are part of representing data in a matrix. Each of the Tablix for the Rows and Columns has the additional submenu items which are shown here for the Rows. Similar ones apply for the Columns as well. These are useful when you want to create nested groups. With the Matrix design interface in SQL Server 2005 this would not have been possible. Add Group Row Group Parent Group... Child Group... -------------------- Adjacent Above Adjacent Below Row Group Delete Group Group Properties Add Total Before After In addition to the above, each of the items Rows and Columns cells has the following items as well. These specify how new columns and rows are inserted with reference to the current cell as shown. The differences are due to the geometrical positions that are allowed for the new columns or rows as shown. For the "Columns" cell: Insert Column Inside Group-Left Inside Group-Right ------------------ Outside Group-Left Outside Group-Right Insert Row Inside Group-Above Inside Group-Below ------------------ Outside Group_Above For the "Rows" cell: Insert Column Inside Group-Left Inside Group-Right ------------------ Outside Group-Left Insert Row Inside Group-Above Inside Group-Below ------------------ Outside Group_Above Outside Group_Below Besides using a cell as a starting point, one could also use the rows as a whole or column as a whole to add further structure as shown in the next figure. Of course you need to use the proper submenu option to arrive at a particular matrix structure. Clicking at the indicated points would let you choose the structure you want for your matrix. If you click at the location shown for the Tablix you could choose to the delete the whole matrix. The Tablix graphical arrangement gives you the maximum flexibility in extending the matrix in 2-dimensions. List The list data region repeats for each row of data. List element provides a single container for the data which can be used to generate what are called Free Form Reports. In this kind of report there is no rigid structure such as a table for the data. You can also place a list inside another list or even a chart inside a list. You can drag a column from a dataset and drop it into the list. You can work with the list using the properties of the Rectangle it contains as well as its Tablix properties. As described earlier, the design interface is very flexible and you can leverage all features provided by the Tablix structure like displaying details and adding groups either independent, or nested. The properties pages described earlier allow you to sort and filter grouped data. When you drop a List on the design surface you will see just a single cell as shown. You can change its dimensions to suit your needs. When you click on the List you can access its handles as shown: When you add a List, there is one column and one row (just one cell). This can be extended in both directions by choosing the appropriate submenu items. These can be displayed by right-clicking on the handles as shown:

Basic Security and Firewalls An administrator installing a Scalix server in a productive environment must make some considerations before setting up his system: Is the server accessible from the Internet? Is the server accessible to untrusted users? Who must access Scalix? Who must access administration? Who must be prevented from gaining access? Which services must be accessible from where? Though this may sound theoretical, such thoughts always play an important role when you are planning any productive server. In most cases, there are only three different setups for a groupware server: There are only local users in the company's network and the server is located in the company. There are local users and remote users connecting to the Scalix server located in the company. There are both local and remote users connecting to the Scalix server located on the Internet. While the installation leaves a perfectly configured system that is stable, there are several possible precautions that should be taken when your Scalix server is accessible from the Internet — the access should be controlled by a firewall, connections should be encrypted, and users must be forced to use strong authentication mechanisms. As always, there are several ways to achieve this. Before we start, here is a list of services that have to be available for Scalix users accessing the server remotely:- SSH: TCP port 22, the standard remote administration for the admin. SMTP: TCP port 25 — Sending mail. IMAP: TCP port 143 — Retrieving mail with the IMAP protocol. POP: TCP port 110 —  Retrieving mail with the POP protocol. HTTP: TCP port 80: Accessing the Web interface. Scalix UAL uses port 5287 And as of 11.3, secure UAL connects over 5767 Linux Firewall Terminology Basically speaking, a firewall is a piece of software that controls internet connections to and from a server. SUSE's Linux systems come with a built-in firewall named SUSEfirewall that can easily be configured with YaST. On Red Hat Linux systems, there is Bastille and firewall GUIs like Shorewall, which are all good choices for any Linux system. All common Linux firewalls are based on iptables or its predecessor ipchains. Its concept is pretty simple: the administrator defines a chain of rules that are worked through by the operating system one after another for every incoming or outgoing connection or package. So-called targets define what to do with packages matching the rule specified. Targets may be, for example, Accept, Reject, Drop or Log. Furthermore, there are policies that define the default behavior for connections where no rule matches. The Linux program iptables controls these rules. A little glance on this tool may help understanding how a Linux firewall works. iptables—the Standard Linux Firewall Tool iptables (http://www.netfilter.org) is a simple command-line tool that controls the kernels' IP tables. In these tables, rules that define how network packets are treated on this system can be stored. As always, the simple commands offer the best solutions when they are combined with an abundance of options. There is a vast amount of options and extensions for iptables, so this short description is far from perfect and far from complete. The iptables syntax is very simple: iptables <rule command> <chain> <matching extensions><target> A typical rule command is A, which means Add the following rule. Since iptables use different chains (by default, INPUT, FORWARD, OUTPUT), we must declare a chain where this rule is to be added to. The following table shows three examples: Iptables Command Function: iptables -A INPUT <rule> Adds a rule to the INPUT chain, which affects all incoming packets heading for the firewall itself. iptables -A OUTPUT <rule> Adds a rule to the FORWARD chain, which affects all packets that are supposed to be forwarded by the firewall. iptables -A FORWARD <rule> Adds a rule to the OUTPUT chain, which affects all outgoing packets originating from the firewall. Another typical command is -P that sets the default policy for a chain. This should always be set to DROP, because then all packets arriving in this chain are dropped if not specified explicitly by another rule. This is the only way to make sure that only the traffic allowed by us is handled and any unspecified traffic is dropped. A typical example for this is: scalixbook:~ # iptables -P FORWARD DROPscalixbook:~ # This would prevent your system from forwarding any traffic, unless specified otherwise, later on. Then there are iptables' targets. A target can be either DROP, REJECT or ACCEPT (among others) and is invoked by the switch — j. Furthermore, so-called "matching extensions" are like a filter specifying exactly which packet is meant. Thus a rule like iptables -A INPUT <matching extension> -j DROP  means: Drop every packet that is headed for my firewall and matches the <matching extension>. Matching Extension Meaning -i <interface> The incoming interface of the datagram -o <interface> The outgoing interface of the datagram -p <protocol> The IP protocol of the datagram --dport <destination port> The destination port of the datagram --sport <source port> The source port of the datagram -s <source IP> The source IP of the sender -d <destination IP> The destination IP of the recipient There are many other matching extensions, but these here should be sufficient to understand the basics of iptables. Have a look at these lines: #!/bin/bashiptables -P INPUT DROPiptables -P OUTPUT DROPiptables -P FORWARD DROPiptables -A INPUT -i eth0 -p tcp --dport 22 -j ACCEPTiptables -A INPUT -i eth0 -p tcp --dport 25 -j ACCEPTiptables -A INPUT -i eth0 -p tcp --dport 143 -j ACCEPTiptables -A OUTPUT -o eth0 -p tcp --sport 22 -j ACCEPTiptables -A OUTPUT -o eth0 -p tcp --dport 25 -j ACCEPTiptables -A OUTPUT -o eth0 -p tcp --dport 143 -j ACCEPT(...) Do you already understand them? If you do, congratulations; if not, don't worry, it's easy. These lines represent a shell script that can be used to start a very simple firewall example. iptables is a command-line tool and therefore is simply called from a script with parameters like the following: Command Meaning iptables -P INPUT DROP Drop all incoming packets that are not specified by any other rule iptables -P OUTPUT DROP Drop all outgoing packets that are not specified by any other rule iptables -P FORWARD DROP Do not forward any packets that are not specified by any other rule iptables -A INPUT -i eth0 -p tcp --dport 22 -j ACCEPT Accept TCP connections for port 22 (SSH) coming in on network interface eth0 iptables -A INPUT -i eth0 -p tcp --dport 25 -j ACCEPT Accept TCP connections for port 25 (SMTP) coming in on network interface eth0 iptables -A INPUT -i eth0 -p tcp --dport 143 -j ACCEPT Accept TCP connections for port 143 (IMAP) coming in on network interface eth0 iptables -A OUTPUT -o eth0 -p tcp --sport 22 -j ACCEPT Accept outgoing TCP connections for port 22 going out on network interface eth0 iptables -A OUTPUT -o eth0 -p tcp --dport 25 -j ACCEPT Accept outgoing TCP connections for port 25 going out on network interface eth0 iptables -A OUTPUT -o eth0 -p tcp --dport 143 -j ACCEPT Accept outgoing TCP connections for port 143 going out on network interface eth0

We are going to add and edit a lot of information for manufacturers, vendors, and product categories. Actually, in this article, our VirtueMart shop will really take shape with products we want to sell. Catalogue management The product catalog for an online shop comprises of the products we sell in the shop. Whatever products we want to sell should be added to this product catalog first. Once products are added to the catalog, customers can browse the products and decide to buy whatever they need. Therefore, managing the catalog is one of the primary tasks of the shop owner. Products that we add to the catalog need to be organized to help customers easily find the right products. In VirtueMart, customers can sort the products by product categories and manufacturers. Therefore, before adding products to the catalog, we will look into managing manufacturers and product categories. Managing manufacturers In VirtueMart, whenever we add a product to the catalog, we also need to assign a manufacturer for that product. In reality, every product has a manufacturer, and for better management of the shop, we should be able to find products by their manufacturer. Therefore, first step will be to identify the manufacturers and enter their information in VirtueMart store. We can also categorize the manufactures as publishers, software developers, and so on. Adding a manufacturer category There is a default manufacturer category for use in VirtueMart. We can use that default category for creating a manufacturer. However, when we are selling large number of products from a large number of manufacturers, classifying them into categories will be convenient for managing the manufacturers. For adding a manufacturer, in the VirtueMart administration panel, click on Manufacturer | Add Manufacturer Category. This shows Manufacturer Category Form: In the Manufacturer Category Form, provide information for the Category Name and the Category Description fields. Once these are provided, click the Save icon in the toolbar to save the manufacturer category. In the same process, you can add as many categories as you want. Adding a manufacturer For adding a manufacturer, in the VirtueMart administration panel, select Manufacturer | Add Manufacturer. This shows Add Information screen: In the Add Information screen, type the manufacturer's name, their URL, email address, and a brief description. In the Manufacturer Category field, select the category. The drop-down list will show the manufacturer categories you created earlier. Once all the information is provided in this screen, click the Save icon in the toolbar to save the manufacturer information. Listing the manufacturer categories Once you have added the manufacturer categories, you can view the list of manufacturer categories by selecting Manufacturer | List Manufacturer Categories. This shows Manufacturer Category List screen: In the Manufacturer Category List screen, you will see all manufacturer categories you have created. From this screen, you can add a new category by clicking the New icon in the toolbar. Similarly, you can remove a category by clicking on the trash icon in Remove column, or by selecting the categories and clicking the Remove icon in the toolbar. You can edit a category by clicking on the category name. To view the list of manufacturers, click on the Manufacturer List link in the Manufacturers column, or select Manufacturer | List Manufacturers. This shows Manufacturer List screen displaying all manufacturers you have added: From the Manufacturer List screen, you can create a new manufacturer, remove one or more manufacturers, and edit any manufacturer. For editing a manufacturer, click on the manufacturer's name or the Update link in Admin column. This will bring up the Add Information screen again. You can also create a new manufacturer by clicking the New icon in the toolbar. From the Manufacturer Category List screen, you may think that clicking on the Manufacturer List link against each category will display the manufacturers added to that category only. Ideally, this should be the case. However, until VirtueMart 1.1.2, it shows the list of manufacturers from all the categories. We hope this will be fixed in the upcoming releases of VirtueMart. Managing vendors The idea of multiple vendors is something what you can see on Amazon.com. Different vendors add their products to sell, when the order is placed, the store notifies the vendor to fulfill the order. The main store usually gets a commission from the vendor for each sell made through the store. However, VirtueMart's vendors feature is still in its infancy and does not yet function properly. You can add multiple vendors in VirtueMart, and assign products to the vendors. However, adding vendors has no effect on selling any product on the VirtueMart store, except when applying different vendor-specific tax rates and shopper groups. At the moment, it also helps to identify products from different vendors. In the following sections, you will see how to add and manage vendors. Vendor category Like manufacturers, you can also create vendor categories. For creating vendor categories, go to Vendor | Add Vendor Category. This displays Vendor Category Form: In the Vendor Category Form, type the name of the category and its description. Then click the Save icon in the toolbar. You can add as many categories as you want. Before trying to add vendor categories, first plan how you are going to categorize your vendors (for example, based on the product they sell or their location). Have a full category tree on hand and then start creating categories. Adding vendor Once you have created the necessary vendor categories, you can proceed to adding vendors. For adding vendors, click on Vendor | Add Vendor. This displays the Add Information screen: CautionNote that there is a warning sign at the top of Add Information screen. It warns you about using the vendor feature as it is in the 'Alpha' or pre-mature stage. Also note that we have used Simple Layout for displaying it. If you try adding a vendor from Extended Layout, you will open up an edit screen for existing vendor information, which you already added during the initial configuration of the shop. Up until VirtueMart 1.1.2, a bug has been encountered and which will hopefully be fixed in future releases when it crosses 'Alpha' stage. The Add Information screen shows three tabs: Store, Store Information, and Contact Information. From the Store tab, add the vendor's store name, company name, logo, web site URL, minimum purchase order value, and minimum amount for free shipping. You can also configure the currency symbol, decimal points, decimal symbol, thousand separator, positive format, and negative format. In the Store Information tab (seen in the previous screenshot), you can add the address of the store, city, state/province/region, zip/postal code, phone, currency and vendor category. The vendor categories you have created earlier will be available in Vendor Category drop-down list. In the Contact Information tab (seen in the previous screenshot), you can set the contact details of the vendor, such as name, title, phone, fax, email. You can also add a brief description of the vendor which will be displayed in the vendor details page in the store. Type a brief description in the Description rich-text editing box. In the Terms of Service rich-text editing box, provide terms of service applicable for that vendor. Once information in all the three tabs are provided, click the Save icon in the toolbar to add the vendor.

Here we are! programming in a powerful language specially designed for the Web and using an IDE that promises to help us with many of the mechanical tasks involved in the coding. If you have been already programming with Rails, you probably know that if we take advantage of scaffolding we can have a simple web application for table maintenance in a matter of minutes (yes/no typo here, it really takes just a few minutes). And we are even talking about the database table creation process. If we wanted to add validations, a nice design, and some more complexity we would be talking about a few hours. Still pretty impressive, depending from which programming language (or framework) you are coming. The truth is, creating the wireframe of your application in Rails is quick and easy enough even from the command line, but we'll be learning in this article how to do it a bit more comfortably by using RadRails for creating your models, controllers, database migrations, and for starting your server and test your application. Basic Views Most of the time when working with our IDE we will be using the Editor Area. Apart from that, two of the views we will be working with more frequently are the Ruby Explorer—the enhanced equivalent of the Rails Navigator, if you were using RadRails Classic—and the Console. Both of these views are fairly easy to use, but since they will be present at almost every point of the development process, it's interesting to get familiar with them from the beginning. The Ruby Explorer View If you have already opened the Rails perspective, then you should be seeing the Ruby Explorer at the left of your workbench. This view looks like a file-tree pane. At the root level, you will find a folder for each of the projects in your workspace. By clicking on the icon to the left of the project name, you will unfold its files and folders. The Ruby files can be expanded too, displaying the modules, classes, variables, and methods defined in the selected file. By clicking on any of these elements you will be taken directly to the line in which it is defined. Before navigating through the contents of a project, we have to open it. Just right-click on its name and choose Open Project. When opening a project, Eclipse will ask you if you want to open the referenced projects. By default, your projects don't have any references and that's the most common scenario when working with a Rails application. If you want, you can include references to other projects on the workspace so you can open and close them together. To view and change the project references, you can right-click on the project name, then select Properties. Notice you can also get here from the Project menu by selecting Properties. In the properties dialog, you have to select Project References. Here you will see a list of all the available projects in the workspace. Just check or uncheck all the projects you want to reference. Once your project is open, the mechanism for navigating the contents is pretty straightforward. You can open or close any sub-folders and you can right-click on any item to get a context menu. From this menu you can perform common file operations like creating, renaming, or deleting a file. We will see more details about creating new files when talking about the Editor Area. There is also a Properties option from where you can change the encoding for a particular file, or the file attributes (read only, for example). The Properties option is also available at the project level. Also in the context menu, you can see there is a Tail option. This will work like the tail command in UNIX, displaying the contents of a file as it's changing. This option is especially useful for a quick monitoring of the log files of your application. You can also find in the context menu two options with the names Compare With and Replace With. If you select either of them, you will see a new menu in which there is an option named Local history. This functionality is really interesting. You can compare your current version against an older version of the same file, or you could replace the contents with a previous one. This can be a life-saver because when using it on a folder the local history will contain copies even of deleted files. Comparing a file against another copy is a powerful tool, which can also be used when working with repositories or to compare different files between them. Let's try it and see how it works. Open any of the files in your project tree by double-clicking on the file name. Now go to the Editor Area and add some lines with Mumbo-Jumbo text. After you are done, click on the save icon of the toolbar or select Save in the File menu. Now let's go back to the Ruby Explorer, double-click on the file name and select Compare With | Local History. You will see there are some entries here, one for each time we saved the file. If this was the first time you worked with the file, then there will be only two versions, the original and the one you just saved. Double-click on the oldest local version you have. Now a new editor will be opened. The editor is divided into three panes, the top one displaying structural differences, the bottom-left one with the code of the current version, and the bottom-right one with the old version of the code. At the top pane, you will see the structural differences between the versions being compared. For every added or deleted method or variable—at instance or class level, you will see the name of the element with an icon displaying a plus or a minus sign. If a method exists in both versions, but its content was changed, the name will be displayed without any additional icons. When reviewing the differences/changes you will see the editors at both sides are linked with a line representing the parts that are not equal between the files. When you are on a given change/difference you can select the icon for 'copying current change from right to left' (or the other way round, depending in which of the files the change is), which will override the contents of the left editor with those of the right. You can also just manually edit or copy/paste in your editor as usual. There is an interesting icon labeled 'Copy all non-conflicting changes from right to left' that will do exactly as it promises. Any changes that can be automatically merged, will be incorporated to your editor. Depending on the differences between the files, the icon could be the contrary 'Copy all non-conflicting changes from left to right'. When you finish comparing or modifying your current editor, remember to save the contents of the editor in order to keep your changes. If you just wanted to review the changes without any modifications, you can directly scroll down the editors, use the 'Previous' or 'Next' icons, or use the quick marks by the right margin. You can also compare two files instead of comparing a file against an older version. Go to the Ruby Explorer and select one of the files, then hold down the control key and select another one. With both files selected, you right-click and select Compare With and then Each Other. Once opened, the compare editor works exactly the same as when comparing with an old version of the same file.

Learning to fish Give a man a fish and you feed him for a day; teach him to use the Internet, and he won't bother you for weeks! This is going to be a real challenge for the one that wants to play with the new technology that Web services enablement brings, but is a little unsure where to start. A good number of people that are experienced NAV consultants and C/AL developers are going to need to learn some new technologies if they want to start experimenting with the new extensibility options in Dynamics NAV 2009, or even simply understand what options are available for their new solution designs or sales presentations. This article is going to be all about practical examples—real sample applications that you can create for yourself. Some of these examples start off with one set of requirements that evolve as we progress through the design process. The examples are deliberately kept this way to help you to understand that the path to your final working solution is not always the shortest. Sometimes you get an idea for an application and as you proceed with the design, you think of things that would be better or easier to use. Sometimes your initial design simply won't work when you start to try it out. It's important to realize that designs are not precious and it's OK to change your mind. There are a couple of important issues to consider: always ensure you are solving the business problem, and don't get carried away gold-plating your design. Keep it simple, and once it is working and meets the initial requirements, you can then go back and add the bells and whistles (but you'd better check with whoever is paying the bills first). If you aren't a .NET programmer, and you have never created a web site or Web service in your life, this article is not a place to tell you the best way to do these things, but instead is a place to show you that with a very limited knowledge of .NET, a web browser to do some research, and enough time, you can create pretty much anything you can imagine. First of all, let's get some theory out of the way so that we have a basic understanding of what we're dealing with. What's a Web service? Web services have been around for a few years now but they are new to NAV (well, sort of— but more on that later). A good way to distinguish between technical and non-technical NAV consultants is to ask them if NAV supports Web services and watch to see if their eyes glaze over. There's no wonder some NAV consultants struggle to understand Web services as a concept; if you're not a developer and you have never worked with Web services, learning the basics might be more than a little bit scary. Here's a typical definition you might find on the Web; don't be put off by the geek-speak. A scary geeky definition of a Web service A 'Web service' (also Web Service) is defined by the W3C as 'a software system designed to support interoperable machine-to-machine interaction over a network'. Web services are frequently just Web APIs that can be accessed over a network, such as the Internet, and executed on a remote system hosting the requested services. There are a lot of acronyms and jargon phrases to learn if you want to talk the talk, but let's take a look at what a Web service is in simple terms. To start with, let's consider a comparison between web sites, something we are all familiar with, and Web services. One might like to think that a Web service is to a computer what a web site is to a person. If you want to know what's on TV tonight, you can type the URL for a TV Listings site into a web browser and bring up a page with details. It's not going to take you long to find the required information, but what if you wanted to write a computer program to send an e-mail when your favorite TV show was about to start, how would you go about that? This is a more complex problem, we know the data is there on the web site, freely available to all humans, but we can't just tell our computer to go off and read the web site (well we can—but deciphering it may require a fair amount of clever programming). Wouldn't it be great if there was a computer-friendly version of the data on the web site that allowed computers to ask for information and get answers back? Wouldn't it be great if you could write your program to make the call to this service without the need to install any special software components on your computer? Yes, it is great, and that's why Web services came into being and have now become so popular. It's not just for the Web It's not immediately obvious why we would want to expose our precious company data that we keep locked up in our ERP system on the Web, but just because they're called Web services doesn't mean they're just for the World Wide Web. Let's consider the intranet compared to the internet. It didn't take long for companies to realize that the popularity of internet sites and the ease of use that everyone was experiencing through the world wide web could provide great benefits within the boundaries of a company's safe internal network—a kind of mini-internal-internet or intranet. For Dynamics NAV, the analogy between Web Sites and Web services works even better when we consider an intranet. What if different departments could pull data directly from the ERP system and use it in their own specialist applications? This is where the real value of Web services enablement in Dynamics NAV 2009 comes into its own. It is now possible to take any functionality from within the ERP solution and expose it to other applications as Web services; it's not just possible, it's dead easy! What can we do with them? OK, so it's easy to expose NAV functionality, so what? Well if you can call any Codeunit or Page from within NAV with pretty much any software package that you can extend, there are limitless possibilities to create fantastic productivity applications for the business. Here are just a few examples: Let staff submit their expenses from Excel, or from their mobile phone, without needing to re-key them into the finance system. Allow users to create new customer accounts from within Word or from an intranet web page. Provide a Vista Sidebar gadget that shows the number of documents requiring approval and allows the user to approve the document without needing to open the ERP. Provide a simple single-task Windows application that will let staff see where stock is. These examples are just a few that spring immediately to mind, but if you have the know-how, you can do pretty much anything. So how easy is it to expose NAV functionality as a Web service? Let's find out. Calling a NAV Web service There is a great series of articles on MSDN by Manuel Oliveira that explain how to expose NAV functionality as a Web service. If you have never read these, you may want to skim through them after reading this example to see just how easy we have it with the new version of NAV. Talking with NAV—the hard way! Visit http://msdn.microsoft.com/en-us/library/ms952182.aspx and http://msdn.microsoft.com/en-us/library/ms952079.aspx for a couple of examples that explain the multiple hoops we needed to jump through in order to access NAV functionality using Web services. That's before NAV 2009 came along! Since these early examples of NAV extensibility, the Windows Communication Framework has made things easier, and Kris Rafnsson has provided a blog posting and sample application that allows you to call NAV functionality as a Web service without using message queues. This example is pretty amazing, but there is still a fair amount of work required to get this up and running and build new solutions. Although this is a big improvement on the Message Queue approach, it is nothing compared to the simplicity and elegance of the NAV 2009 Web services enablement. You can read through Kris's post at http://blogs.msdn.com/nav/archive/2008/04/15/using-web-services-toaccess-microsoft-dynamics-nav-5-0.aspx. In Manuel's first example (although not actually a Web service), he creates a simple NAV function that will accept a text string and return the text string back but converted to upper case. This example spans 15 printed pages and uses a lot of geeky stuff. As a bare minimum, we are going to need a Codeunit to expose and a .NET program to call the thing, so let's forget about these and just compare the components that are needed to take care of the plumbing: Microsoft Message Queue Navision Communication Component XMLDOM automation control Navision Application Server A lot of complicated C/AL code using InStreams and OutStreams and XML manipulation Manuel's examples were written in 2004 and, although they're very well written, the whole thing is just too hard! After reading the articles, you'll understand why there hasn't been a glut of NAV components on the market using Web services exposed by NAV. Our example by contrast requires the following (again ignoring the Codeunit we are exposing and the .NET program needed to call it): Dynamics NAV 2009 Business Web services A new record in a table with a check in a box Creating a Web service Let's start by creating our very simple Codeunit. In this example, I have created Codeunit 50001 called NAV Codeunit, which has a single function called ConvertStrToUpperCase that takes a 50 character text field and returns a 50 character text field that has been converted to upper case. It wasn't absolutely necessary for this example, but I put some code in the OnRun() trigger of the Codeunit that will demonstrate the Codeunit working when run. Here is the output from running the Codeunit in NAV: Now we can expose this Codeunit as a Web service. In the Classic client, select Administration | IT Administration | General Setup | Web Services. This is just a regular NAV form, so fill in the details on a new record with Object Type as Codeunit, Object ID as 50001, and Service Name as NAV Codeunit. To publish the Web service, tick the Published field. I just happened to give the Web service the same name as the Codeunit, but this is not necessary, you can call it whatever you like. We have now exposed NAV functionality as a Web service—how easy was that? Calling the Web service The .NET program to call the Web service is going to be a little harder. We're going to create a simple C# console application using Microsoft Visual Studio 2008 Professional Edition. (This is installed on the Marketing Beta release of the product which all partners can download from PartnerSource.) Create a new Console Application, let's call this one SayHelloToNAV2009. The project gets created with a Program.cs file with enough code generated for you to allow the project to compile and run. There's no way I can teach you to program in C# in this article, there are whole books dedicated to the subject; instead what I'll do is give you the details you need to be able to recreate our examples for yourself. If you like what you see, maybe you'll go on to do some more .NET programming and your next book will be one on C#. The great thing about .NET languages and Visual Studio is there's a huge amount of knowledge freely available on the Web. The first thing we need to do is add our Web service to the project. To do this, right-click on the References node in the Solution Explorer window and select Add Service Reference. Visual Studio 2005 is differentThese instructions are for adding a web reference using Visual Studio 2008. In 2005, things work a little differently. Instead of selecting References | Add Service Reference | Advanced | Add Web Reference, you simply selected Add Reference | Add Web Reference. In the dialog that is displayed, click the Advanced button, and then click the Add Web Reference button. In the Add Web Reference dialog form, enter http://nav-srv-01:7047/DynamicsNAV/ws/CRONUS_International_Ltd/Services as the URL for the Web service. This will display the group of Web services that are exposed by NAV. Where do I find that URL? The format of the URL is quite straightforward. Let's break it up into chunks.

Where to Look for Log Information The first place to head whenever you have a configuration problem with FreeNAS is to the related configuration section and check that it is configured as expected. If, having double checked the settings, the problem persists, the next port of call is the log and information files in the Diagnostics: section of the web interface. Keep Diagnostics Section ExpandedBy default, the menu tree in the Diagnostics section of the web interface is collapsed, meaning the menu items aren't visible. To see the menu items, you need to click the word Diagnostics and the tree will expand. During initial setup and if you are doing lots of troubleshooting, you can save yourself a click by having the Diagnostics section permanently expanded. To set this option, go to System: Advanced and click on the Navigation - Keep diagnostics in navigation expanded tick box. The Diagnostics sections has five sections, the first two are logs and information pages about the status of the FreeNAS server. The other three are networking diagnostic tools and information. Diagnostics: Logs This section collates all the different log files that are generated by the FreeNAS server into one convenient place. There are several tabs, one for each different service to log file type. Some of the information can be very technical, especially in the System tab. However, with some key information they can become more readable. The tabs are as follows: Tab Meaning System When FreeBSD (the underlying OS of FreeNAS) boots, various log entries are recorded here about the hardware of the server and various messages about the boot process. FTP This shows the activity on the FTP server including successful logins and failed logins. RSYNC The log information for the RSYNC server is divided into three sections: Server, Client, and Local. Depending on which type of RSYNC operation you are interested, click the appropriate tab. SSHD Here you will find log entries from the SSH server including some limited startup information and records of logins and failed login attempts. SMARTD This tab logs the output of the S.M.A.R.T daemon. Daemon Any other minor system service like the built-in HTTP server, the Apple Filing Protocol server and Windows networking server (Samab) will log information to this page. UPnP The log information from the FreeNAS UPnP server called "MediaTomb" is displayed here. The logging can be quite verbose so careful attention is needed when reading it. Don't be distracted by entires such as "INFO: Config: option not found:" as this is just the server logging that it will be using a default value for that particular attribute. Settings The settings tab allows you to change how the log information is displayed including the sort order and the number of entries shown. What is a Daemon?In UNIX speak, a Daemon is a system service. It is a program that runs in the background performing certain tasks. The Daemons in FreeNAS don't work with the users in an interactive mode (via the monitor, mouse, and keyboard) and as such need a place to log the results (or problems)of their actives. The FreeNAS Daemons are launched automatically by FreeBSD when it boots and some are dependent on being enabled in the web interface. Understanding Diagnostics Logs: System The most complicated of all the log pages is the System log page. Here, FreeBSD logs information about the system, its hardware, and the startup process. At first, this page can seem intimidating but with a little help, this page can be very helpful particularly in tracking down hardware or driver related problems. 50 Log Entries Might Not be EnoughThe default number of log entries shown on the Diagnostics: Logs page is 50. For most situations, this will be sufficient but there can be times when it is not enough. For example in the Diagnostics: Logs: System tab, the total number of log entries made during the boot up process is more than 50. If you want to see how much system memory has been recognized by FreeBSD, you won't find it within the standard 50 entries. The solution is to increase the Number of log entries to show parameter on the Diagnostics: Logs: Setting tab. The best way to learn to read the Diagnostics: Logs: System page is by example, below are several different log entry examples including logs about the CPU, memory, disks, and disk controllers: kernel: FreeBSD 6.2-RELEASE-p11 #0: Wed Mar 12 18:17:49 CET 2008 This first entry shows the heritage of the FreeNAS server. It is based on FreeBSD and in this particular case, we see that this version of FreeNAS is using FreeBSD 6.2. There are plans (which may have already become reality) to use FreeBSD version 7.0 as the base for FreeNAS. kernel: CPU: Intel(R) Xeon(TM) CPU 1.70GHz (1680.52-MHz 686-class CPU) Here, the type of CPU that was detected by the FreeBSD is displayed. In this case, it is an Intel Xeon CPU running at 1.7GHz. kernel: FreeBSD/SMP: Multiprocessor System Detected: 2 CPUs If your system has more than one CPU or is a dual core machine then you will see an entry in the log file (like the one above) recognizing the second CPU. If your machine has Hyper-threading technology, then the second logical processor will be reported like this: Logical CPUs per core:2 Apr 1 11:06:00 kernel: real memory = 268435456 (256 MB)Apr 1 11:06:00 kernel: avail memory = 252907520 (241 MB) These log entries show how much memory the system has detected. The difference in size between real memory and available memory is the difference between the amount of RAM physically installed in the computer and the amount of memory left over after the FreeBSD kernel is loaded. kernel: atapci0: <Intel PIIX4 UDMA33 controller> port 0x1f0-0x1f7,0x3f6,0x170-0x177,0x376,0x1050-0x105f at device 7.1 on pci0 kernel: ata0: <ATA channel 0> on atapci0 kernel: ata1: <ATA channel 1> on atapci0 For disks to work on your FreeNAS server, a disk controller is needed and it will be either a standard ATA/IDE controller, a SATA controller or a SCSI controller. Above are the log entries for a standard ATA controller built into the motherboard. You can see that it is an Intel controller and that two channels have been seen (the primary and the secondary). kernel: atapci1: <SiS 181 SATA150 controller> irq 17 at device 5.0 on pci0kernel: ata2: <ATA channel 0> on atapci1kernel: ata3: <ATA channel 1> on atapci1 Like the ATA controller listed a moment ago, SATA controllers are all recognized at boot up. Here is a SiS 181 SATA 150 controller with two channels. They are listed as devices ata2 and ata3 as ata0 and ata1 are used by the standard ATA/IDE controller. kernel: mpt0: <LSILogic 1030 Ultra4 Adapter> irq 17 at device 16.0 on pci0 Like IDE and SATA controllers, all recognized SCSI drivers are listed in the boot up system log. Here, the controller is an LSILogic 1030 Ultra4. kernel: ad0: 476940MB <WDC WD5000AAJB-00YRA0 12.01C02> at ata0-master UDMA100kernel: ad4: 476940MB <Seagate ST3500320AS SD04> at ata2-master SATA150 Once the disk controllers are recognized by the system, FreeBSD can search to see which disks are attached. Above is an example of a Western Digital 500GB hard drive using the standard ATA100 interface at 100MB/s. There is also a 500GB Seagate drive connected using the SATA interface. acd0: CDROM <TOSHIBA CD-ROM XM-7002B/1005> at ata1 as master UDMA33 When the CDROM (which is normally attached to an ATA/IDE controller) is recognized, it will look like the above. kernel: da0 at ahd0 bus 0 target 0 lun 0kernel: da0: <MAXTOR ATLAS10K4_73WLS DFL0> Fixed Direct Access SCSI-3 devicekernel: da0: 320.000MB/s transfers (160.000MHz, offset 127, 16bit), Tagged Queueing Enabledkernel: da0: 70149MB (143666192 512 byte sectors: 255H 63S/T 8942C) SCSI addressing is a little more complicated than that of ATA/IDE. In SCSI land, you have a controller, a channel (bus), a disk (target), and the Logical Unit Number (LUN). The example above shows that a disk (which has been assigned the device name da0) is found on the controller ahd0 on bus 0, as target 0 with the LUN 0. SCSI controllers can have multiple buses and multiple targets. Further down, you can see that the disk is a MAXTOR 73GB SCSI-3 disk. kernel: da0 at umass-sim0 bus 0 target 0 lun 0kernel: da0: <Verbatim Store 'n' Go 1.30> Removable Direct Access SCSI-2 devicekernel: da0: 40.000MB/s transferskernel: da0: 963MB (1974271 512 byte sectors: 64H 32S/T 963C) If you are using a USB flash disk for storing the configuration information, it will most likely appear in the log file as a type of SCSI disk. The above example shows a 1GB Verbatim Store 'n' Go disk. kernel: lnc0: <PCNet/PCI Ethernet adapter> irq 18 at device 17.0 on pci0kernel: lnc0: Ethernet address: 00:0c:29:a5:9a:28 Another important device that needs to work correctly on your system is the network interface card. Like disk controllers and disks, it will be logged in the log file when FreeBSD recognizes it. Above is an example of an AMD Lance/PCNet-based Ethernet adapter. Each Ethernet card has a unique address know as the Ethernet address or the MAC address. It is made up of 6 numbers specified using a colon notation. Once found, FreeBSD queries the card to find its MAC address and logs the result. In the above example, it is "00:0c:29:a5:9a:28". Converting between Device Names and the Real World In the SCSI example above, the SCSI controller listed is ahd0. The trick to understanding these log entries better is to know how to interpret the device name ahd0. First of all ahd0 means it is a device using the ahd driver and it is the first one in the system (with numbering starting from 0). So what is a ahd? The first place to look is further up in the log file. There should be an entry like: kernel: ahd0: <Adaptec 39320 Ultra320 SCSI adapter> irq 11 at device 1.0 on pci2 This shows that the particular device is an Adaptec 39320 SCSI 3 controller. You can also find out more about the the ahd driver (and all FreeBSD drivers) at: http://www.freebsd.org/releases/6.2R/hardware-i386.html Search for ahd and you will find which controllers this driver supports (in this case, they are all controllers from Adaptec. If you click on the link provided, you will be taken to a specific help page about this driver. When FreeNAS moves to FreeBSD 7, then the relevant web page will be: http://www.freebsd.org/releases/7.0R/hardware.html.

Sidebar gadget A sidebar gadget is a simple single-tasked tool that sits in the sidebar on Windows Vista. If you don't have Windows Vista, you're out of luck and won't be able to run this sample. You can explore the free gadgets available for download at http://gallery.live.com/. Typical gadgets include: RSS Feed Readers News Readers Weather Reports Clocks Performance Monitoring Tools Mini Notepads Photo Slideshows Hopefully you get the idea. We're going to create a sidebar gadget that will use the Web service capabilities of Dynamics NAV 2009 to display a cue (a stack of documents similar to those shown in the RoleTailored client), based upon the document approvals features that have been available since NAV 5.0. We want to display a document stack that represents the number of documents requiring approval from the current user and will allow the user to select the type of document as a configuration setting. In our example, clicking the document stack will show a list of documents and clicking an individual document will launch the RoleTailored client. There's no reason why you can't take this example and extend it to include the ability to display the actual documents and carry out the approval, all from the comfort of your Windows Vista desktop. Design time When we start to de sign NAV solutions, we use our knowledge of the standard application to create a solution that fits nicely within the NAV paradigm. We try to emulate the way the standard application solves common business problems and use the components that are used by the product team in a consistent manner. Designing applications for .NET, or in this case for a sidebar gadget, follows the same conventions. First of all we need to understand a little bit about what makes a sidebar gadget so that we can know the constraints of our design. What are little gadgets made of? There is an excellent tutorial on MSDN Magazine's web site by Donavon West that tells you how to build a sidebar gadget for displaying MSDN Magazine articles in a news-ticker format with the ability to click an article to see more details and click another link to read the full article on the Web. We're going to use that article and the gadget provided for download as the basis for exploring what a gadget is, which will in turn help us to design our own gadget. You can read Donavon West's MSDN Magazine article at: http://msdn.microsoft.com/en-nz/magazine/cc163370(en-us).aspx You can download the Gadget from: http://gallery.live.com/liveItemDetail.aspx?li=b21af41e-b846-46d9-a873-ac12a3c65ab3 Essentially a gadget is little more than a mini web page (HTML file with some supporting resources such as images and JavaScript) and an XML definition file called gadget.xml. When we're writing a sidebar gadget for Windows Vista, the HTML page is rendered in Microsoft Internet Explorer 7, so there is no need to worry about cross-browser support. Which is nice. If you download the gadget and save it somewhere instead of installing it, you will see an icon for the gadget like this: Before we can use this gadget there is a little problem that needs to be fixed—unfortunately it is pointing to an RSS Feed URL that is not valid and therefore the gadget doesn't work correctly. Donavon explains that a sidebar gadget is simply a collection of files that are stored in a ZIP or CAB file with a .gadget extension, so we can rename the file with a .zip extension and we should be able to open it as a folder. If you open the compressed folder, or extract it, you will see the following files: There is a file called local.js that we will need to edit in order to fix the problem. Gadgets support multi-language capabilities and if your language matches the folder names shown, you are going to need to open that folder and edit the local.js thatit contains. The languages supported by this gadget are as follows:   Folder Name Language de German (Standard) es Spanish (Spain) fr French (Standard) it Italian (Standard) ja Japanese kr I don't think this is a valid language code, so we'll just ignore this. pt Portuguese (Portugal) ru Russian zh-CN Chinese (PRC) zh-TW Chinese (Taiwan) You can get a full list of language codes at http://msdn.microsoft.com/en-us/library/ms533052(VS.85).aspx According to the tutorial, whenever the sidebar tries to load a file, it searches for the file in folders in the following order: Full locale (en-us, es-us, ja-jp) Language portion of the locale (en, es, ja) Gadget root folder So what does this mean? If your locale has a language component that is one of the folders listed in the table, you are going to need to edit the local.js within that folder in order for the gadget to work correctly. When you edit the local.js file (any text editor will do), you will see the following: If you copy the feedUrl string and paste it into a web browser address bar, you will see a runtime error telling you this is not a valid address. A little bit of digging soon reveals an address that we can use for the gadget: http://msdn.microsoft.com/en-nz/magazine/rss/default(en-us).aspx?issue=1 You need to replace the old URL with the new one so that your line in the fi le looks like the following: LOCAL.feedUrl = 'http://msdn.microsoft.com/en-nz/magazine/rss/ default(en-us).aspx?issue=1'; Now we can rename the file back to a .gadget extension and install it. This is to help us examine the main components of a sidebar gadget so we can consider how we will design our own gadget. The gadget The most obvious part of a gadget is the gadget itself. This is the gadget's main HTML page that is provided in the base src property of our gadget.xml file. For us, we want this to show a single document cue that represents the number of approval entries that are awaiting action for the current user. We want the main docked gadget to look something like this: The image is meant to look like a cue from an Activities Part in a Role Center. The pencil sketch is there to give you an idea. Since the 22 approval actions could be for multiple different document types, we will have some text underneath the stack of documents that tells us how many of each of the different document types there are. It could either fade in and out, or scroll horizontal like a marquee. That takes care of the docked state of the gadget. When we undock it, we can get a larger area to play with, so it would be nice if the undocked state showed one stack of documents for each of the approval document types with the name of the document type shown underneath. This may be a little time-consuming, so maybe we'll add that to version 2. For now the undocked image will be the same as the docked image. There are a couple of other pages that need to be considered: Flyouts and Options dialog. Flyouts When you click on a part of gadget, you can activate a flyout, which is basically a web page that gets displayed at the side of the gadget. The flyout file is specified by setting System.Gadget.Flyout.file to the name of the flyout HTML file. In the case of our MSDN Ticker gadget, the flyout looks like the following: For our flyout, we are going to show a list of approval entries with the ability to click a hyperlink to open the approval entries screen. An obvious next extension to this gadget is to provide the ability to approve, reject, or delegate the approval entry directly from the gadget without needing to open the RoleTailored client. For now, we'll concentrate on making this work with our NAV Web service. After taking a quick look at the fields available on the approval entry screen, our flyout will look something like the following: It's a simple table showing the documents with a document type and number, the ID of the sender and the amount that the document is for. Options There is one more part of the gadget to consider for our design and that is the options dialog page. Let's take a look at that for the MSDN Magazine Ticker sample gadget. When I hover my mouse over the gadget, a mini tool bar appears allowing me to close the gadget, show the options, and drag the gadget to a different position. Click the spanner to show the options page. As you can see it's just another little web page with some options on it. You need to instruct the gadget to enable the options icon by setting System.Gadget.settingsUI to the name of the options HTML file, generally in the gadget initialization area of our script. Donavon's article explains how this is done, and provides sample code for how to set up a callback function for when the options dialog closes (so your gadget can read the new user preferences). For our gadget we are going to need a place where we can enter the URL for our Web service. For more advanced options, we could possibly provide the ability to specify how often the gadget will call the Web service. Our options page will look something like this: These pencil sketches are just there to convey the intended layout of the pages; it's a lot quicker to scribble something on a piece of paper (for us) than to start playing around with graphics programs and although they're a little rough, if you squint at them, you can sort of work out what's intended in the final solution. Remember it's important to get an understanding of the design at this stage but it doesn't need to look great; form follows function. The tricky bits Now that we' ve done the high-level design for our sidebar gadget, and we know that a sidebar gadget is just a series of HTML pages, we can start to look at the technical design. There are a couple of tricky bits to take care of: how are we going to call our Web service from within what is essentially a web page, and how are we going to take our list of documents requiring approval and convert them into the table and graphics we want to display. The great thing about sidebar gadgets and the way they are constructed is that you can simply rename the file and take a look at how they are doing what they do (and, of course, you can borrow ideas and code). If you search on the Web, you'll find quite a few examples of sidebar gadgets that call Web services, so there're plenty of examples to look at. Let's pick an example from Microsoft that uses the Exchange 2007 Web service to display email, calendar, and task information. You can download it from: http://www.microsoft.com/downloads/details.aspx?FamilyID=F9A0D33CC894-4EA1-AD20-4E418C715175&displaylang=en A quick search for Exchange Web services Gadget will help you locate it. Actually finding this gadget was a stroke of luck because it does pretty much everything we are after: It has a setup page with a time interval on it. It calls a Web service to find how many items there are in a folder and shows a summary. It displays a flyout with a more detailed view of the folder contents. Finding good examples on the Internet and learning from them is a key skill for doing this kind of development. Just a little bit of SOAP Calling a NAV Web service from within a Visual Studio.NET project is dead easy as we've already seen. We just add our Web service as a web reference and Visual Studio does all the hard work for us. It creates a proxy class that allows us to call the member functions and access the properties of the service as though it was a piece of code that we had written ourselves and not just some black box at the end of a URL. But how do we do this when we don't have Visual Studio? Essentially a Web service is just some text sent over the Internet that generates a response (which is also text). It just so happens that the text being sent and received is formatted as XML which is handy because there is lots of support for reading XML text. Web services typically use a protocol called Simple Object Access Protocol (or SOAP) to allow any system that can post a request to a URL (and read a response message) to call to a function exposed by the Web service. In order to do this for our sidebar gadget, we need two things: we need to know how to send and receive our request, and we need to know what the SOAP request should look like. Figuring out the HTTP call and response handling isn't too hard and you can do this by looking at the Exchange Web service gadget source code or, once again, searching the Internet. Looking at how Microsoft did it in their Exchange Web service gadget shows us we can use the native Microsoft.XMLHTTP object provided by Internet Explorer (remember that a sidebar gadget runs in Internet Explorer only, so we don't need to worry about cross-browser support) to make an HTTP post to our Web service and read the response. Finding the XML for the SOAP request that is needed to invoke a NAV Web service is going to be a little trickier. If we do a Web search for 'how to view a soap request in Visual Studio?', it doesn't take much to find a link to a freeware product called Fiddler that will allow me to inspect messages to and from my web server. Here is the URL: http://www.fiddler2.com/fiddler2/ If we use this tool on the simple example we started the chapter with, we can see the SOAP request is: And the response is: We can guess we could have worked out this request and response format by reading the WSDL (pronounced 'wiz-dal'), that we get when we type the URL to the Codeunit in our web browser; however, we can think that using Visual Studio to test calling our Web service is by far the easiest way, and using the Fiddler tool to be able to inspect and copy the SOAP Envelope XML has got to be better than thinking. Now before we get too carried away trying to create a series of Web service calls to allow us to pull data from a page type Web service, we're going to create a simple proof-of-concept web page that will make a JavaScript call to this NAV Web service with our ConvertStrToUpperCase function. An HTML page that calls a NAV Codeunit This next script is 72 lines of text. The point of the exercise is to show how easy it is to do things in the .NET world even when you don't know what you're doing. Here is the code in full; we'll go through it in detail later: <HTML> <HEAD> <TITLE>Hello NAV 2009 With JavaScript</TITLE> </HEAD> <BODY> <b>Input: </b>hello nav2009!<br/> <div id="resultContainer"><b>Output: </b></div> <FORM Name="Form1" ACTION=""> <INPUT TYPE=BUTTON VALUE="Call NAV" NAME="BtnHello" OnClick="Hello NAV2009()"> </FORM> <SCRIPT LANGUAGE="JavaScript"> <!-- function HelloNAV2009 () { var data = ""; data += '<?xml version="1.0" encoding="utf-8"?>'; data += '<soap:Envelope '; data += ' '; data += ' >'; data += ' <soap:Body>'; data += ' <ConvertStrToUpperCase '; data += ' >'; data += ' <p_Str>hello nav2009!</p_Str>'; data += ' </ConvertStrToUpperCase>'; data += ' </soap:Body>'; data += '</soap:Envelope>'; var xmlHttpRequest = new ActiveXObject("Microsoft.XMLHTTP"); var url = 'http://ds-srv-01:7047/DynamicsNAV/ws/CRONUS_ International_Ltd/Codeunit/NAV_Codeunit'; xmlHttpRequest.open("POST", url, false); xmlHttpRequest.SetRequestHeader("Content-Type", "text/xml"); xmlHttpRequest.SetRequestHeader("SOAPAction", "urn:microsoftdynamics- schemas/codeunit/NAV_Codeunit:ConvertStrToUpperCase"); xmlHttpRequest.onreadystatechange = readResponse; xmlHttpRequest.send(data); function readResponse() { if (xmlHttpRequest.readyState == 4) { var xmlDoc = new ActiveXObject("Microsoft.XMLDOM"); xmlDoc.loadXML(xmlHttpRequest.responseText); resultText = xmlDoc.getElementsByTagName("return_value")[0]. childNodes[0].nodeValue; xmlDoc = null; resultContainerElement = document.getElementById("resultContaine r"); if (resultContainerElement != null) { resultContainerElement.innerHTML = "<b>Output: </b>" + resultText; } xmlHttpRequest = null; } } } //--> </SCRIPT> </BODY> </HTML> You can download the HelloNAV2009.html file from www.teachmenav.com (or http://www.packtpub.com/support). You may need to edit the file on the line where the url variable is assigned to point to the Web service URL available on your computer. When you open the file in your browser, you will need to allow the blocked content in order for the example to run. When you click the Call NAV button, the screen updates to show the following: Wooohooo! It works! OK, let's take a look at what's going on in the code. First of all we assign our variable called data to the XML for the SOAP request body (this is found by using the Fiddler application earlier). That block of code is not included for analysis, so let's move on. This next block of code creates an instance of the Microsoft.XMLHTTP object that we are going to use to make the HTTP post and read the response. var xmlHttpRequest = new ActiveXObject("Microsoft.XMLHTTP"); var url = 'http://ds-srv-01:7047/DynamicsNAV/ws/CRONUS_International_ Ltd/Codeunit/NAV_Codeunit'; xmlHttpRequest.open("POST", url, false); xmlHttpRequest.SetRequestHeader("Content-Type", "text/xml"); xmlHttpRequest.SetRequestHeader("SOAPAction", "urn:microsoft-dynamicsschemas/Codeunit/NAV_Codeunit:ConvertStrToUpperCase"); The highlighted text in the code caused a good deal of grief. Without the SOAPAction request header, the response always contained the WSDL definition of the Web service (the XML document that is shown when you type the Web service URL into the address bar on your browser). Once again this was the missing bit if we look at the results of the Fiddler application trace of .NET application we wrote at the start of this chapter. The following code will hookup the readResponse function to the xmlHttpRequest so that the response can be read when the call is finished. I borrowed this code from the Exchange Web service gadget (although I had to wade up to my armpits in functions in order to find the code that actually did the business). xmlHttpRequest.onreadystatechange = readResponse; xmlHttpRequest.send(data); function readResponse() { if (xmlHttpRequest.readyState == 4) { var xmlDoc = new ActiveXObject("Microsoft.XMLDOM"); xmlDoc.loadXML(xmlHttpRequest.responseText); This next bit of code assigns the resultText variable to the contents of the SOAP response and it took a while to figure out. This example has been taken from the W3 schools site by searching for Microsoft.XMLDOM (http://www.w3schools.com/Xml/xml_dom.asp). resultText = xmlDoc.getElementsByTagName("return_value") [0].childNodes[0].nodeValue; The code is reading the text result from the SOAP envelope. A real example will have to do a lot more with this XML document but for now, this does the job. Finally, we dispose of some objects and then inject the result text in to the body of our HTML page using the innerHTML property for our resultContainer div class. xmlDoc = null; resultContainerElement = document.getElementById("resultContainer"); if (resultContainerElement != null) { resultContainerElement.innerHTML = "<b>Output: </b>" + resultText; } xmlHttpRequest = null; I now know that we've broken the back of the problem. We have successfully called a NAV Web service from a web page (which is essentially all a sidebar gadget is). The next tricky bit is to see how to use a page Web service to get the records back that match our documents requiring approval. We'll use the same approach of first writing the code in .NET as a console application and then after we have this working the easy way, we'll convert the code into JavaScript. After that, it's just a case of tidying everything up and making it look pretty. Hey, Good Lookin' If there's one thing you need for a sidebar gadget, it's nice graphics. Vista is a beautiful operating system and, to be honest, if a gadget doesn't look good, we don't want it on our desktop. The idea is to use a single image and position the images on top of each other and create the image by taking a document and flipping it and applying perspective. Here are the document stacks. The images were created using Photoshop (and a lot of professional skill), and the original image that the stack is built from actually has the Microsoft Dynamics NAV logo at the top (how's that for attention to detail?) Here's the image of the document: HTML is used to render these documents as a stack with the number floating over the top, and the HTML to produce the previous image can be found on the www.teachmenav.com site under the Simple Document Stack sample for this article. We would generate the HTML dynamically based upon the number of documents requiring approval. The HTML used to generate the previous image is manipulated to give 12 document stacks that will be used by the application. The largest stack is 10 images high but this would be used to represent 31 or more documents. The question mark on the final empty stack shown in the following image will be used when the gadget gets no response from the Web service or has not been properly configured. Now we have nearly everything we need to be able to put together the sidebar gadget. There's just one piece of the puzzle missing; we need to be able to call a Web service to tell us how many documents we have for approval and also return the details of those documents, the rest is just applying more of what we know and writing a lot of code. We've covered calling a page Web service in an earlier example, so I won't go into details here but we do need to know what we are calling. As you know Web services from NAV can be based on either Codeunits or Pages, so which should we use? The temptation may be to use a Page Web service as this will allow us to bring back the Approval Entry records for the current user, but we need to do far more than read the records. Our first interaction will be to get a count of the records for approval so we can display the gadget; we don't want the gadget to have a lot of work to do in order to draw its initial state, so ideally we want a quick call that will return just the number of documents and maybe the document name. If you remember from the beginning, our gadgets are meant to be simple, single-tasked applications, so we want a single document approval gadget to work for any one document type. This way our users can have multiple gadgets on their desktop if they want to be notified on multiple document types. We can achieve this by using a Codeunit type Web service and have one of the parameters an identifier of the type of document we are interested in. The following is an overview of the functions we will need.

To invoke a rule we need to go through a number of steps. First we must create a session with the rules engine, then we can assert one or more facts, before executing the rule set and finally we can retrieve the results. We do this in BPEL via a Decision Service; this is essentially a web service wrapper around a rules dictionary, which takes cares of managing the session with the rules engine as well as governing which rule set we wish to apply. The wrapper allows a BPEL process to assert one or more facts, execute a rule set against the asserted facts, retrieve the results and then reset the session. This can be done within a single invocation of an operation, or over multiple operations. Creating a Rule Engine Connection Before you can create a Decision Service you need to create a connection to the repository in which the required rule set is stored. In the Connections panel within JDeveloper, right-click on the Rule Engines folder and select New Rule Engine Connection… as shown in the following screenshot: This will launch the Create Rule Engine Connection dialogue; first you need to specify whether the connection is for a file repository or WebDAV repository. Using a file based repository If you are using a file repository, all we need to specify is the location of the actual file. Once the connection has been created, we can use this to create a decision service for any of the rule sets contained within that repository. However, it is important to realize that when you create a decision service based on this connection, JDeveloper will take a copy of the repository and copy this into the BPEL project. When you deploy the BPEL process, then the copy of this repository will be deployed with the BPEL process. This has a number of implications; first if you want to modify the rule set used by the BPEL Process you need to modify the copy of the repository deployed with the BPEL Process. To modify the rule set deployed with a BPEL Process, log onto the BPEL console, from here click on the BPEL Processes tab, and then select the process that uses the decision service. Next click on the Descriptor tab; this will list all the Partner Links for that process, including the Decision Service (for example LeaveApprovalDecisionServicePL) as shown in the following screenshot: This PartnerLink will have the property decisionServiceDetails, with the link Rule Service Details (circled in the previous screenshot); click on this and the console will display details of the decision service. From here click on the link Open Rule Author; this will open the Rule Author complete with a connection to the file based rule repository. The second implication is that if you use the same rule set within multiple BPEL Processes, each process will have its own copy of the rule set. You can work round this by either wrapping each rule set with a single BPEL process, which is then invoked by any other process wishing to use that rule set. Or once you have deployed the rule set for one process, then you can access it directly via the WSDL for the deployed rule set, for example LeaveApprovalDecisionService.wsdl in the above screenshot. Using a WebDAV repository For the reasons mentioned above, it often makes sense to use a WebDAV based repository to hold your rules. This makes it far simpler to share a rule set between multiple clients, such as BPEL and Java. Before you can create a Rule Engine Connection to a WebDAV repository, you must first define a WebDAV connection to JDeveloper, which is also created from the Connections palette. Creating a Decision Service To create a decision service within our BPEL process, select the Services page from the Component Palette and drag a Decision Service onto your process, as shown in the following screenshot: This will launch the Decision Service Wizard dialogue, as shown: Give the service a name, and then select Execute Ruleset as the invocation pattern. Next click on the flashlight next to Ruleset to launch the Rule Explorer. This allows us to browse any previously defined rule engine connection and select the rule set we wish to invoke via the decision service. For our purposes, select the LeaveApprovalRules as shown below, and click OK. This will bring us back to the Decision Service Wizard which will be updated to list the facts that we can exchange with the Rule Engine, as shown in the following screenshot: This dialogue will only list XML Facts that map to global elements in the XML Schema. Here we need to define which facts we want to assert, that is which facts we pass as inputs to the rule engine from BPEL, and which facts we want to watch, that is which facts we want to return in the output from the rules engine back to our BPEL process. For our example, we will pass in a single leave request. The rule engine will then apply the rule set we defined earlier and update the status of the request to Approved if appropriate. So we need to specify that Assert and Watch facts of type LeaveRequest. Finally, you will notice the checkbox Check here to assert all descendants from the top level element; this is important when an element contains nested elements (or facts) to ensure that nested facts are also evaluated by the rules engine. For example if we had a fact of type LeaveRequestList which contained a list of multiple LeaveRequests, if we wanted to ensure the rules engine evaluated these nested facts, then we would need to check this checkbox. Once you have specified the facts to Assert and Watch, click Next and complete the dialogue; this will then create a decision service partner link within your BPEL process. Adding a Decide activity We are now ready to invoke our rule set from within our BPEL process. From the Component Palette, drag a Decide activity onto our BPEL process (at the point before we execute the LeaveRequest Human Task). This will open up the Edit Decide window (shown in the following screenshot). Here we need to specify a Name for the activity, and select the Decision Service we want to invoke (that is the LeaveApprovalDecisionService that we just created). Once we've specified the service, we need to specify how we want to interact with it. For example, whether we want to incrementally assert a number of facts over a period of time, before executing the rule set and retrieving the result or whether we want to assert all the facts, execute the rule set and get the result within a single invocation. We specify this through the Operation attribute. For our purpose we just need to assert a single fact and run the rule set, so select the value of Assert facts, execute rule set, retrieve results. Once we have selected the operation to invoke on the decision service, the Decision Service Facts will be updated to allow you to assign input and output facts as appropriate.  

When downloading and installing the ASP.NET MVC framework SDK, a new project template is installed in Visual Studio—the ASP.NET MVC project template. This article by Maarten Balliauw describes how to use this template. We will briefly touch all aspects of ASP.NET MVC by creating a new ASP.NET MVC web application based on this Visual Studio template. Besides view, controller, and model, new concepts including ViewData—a means of transferring data between controller and view, routing—the link between a web browser URL and a specific action method inside a controller, and unit testing of a controller are also illustrated in this article. (For more resources on .NET, see here.) Creating a new ASP.NET MVC web application project Before we start creating an ASP.NET MVC web application, make sure that you have installed the ASP.NET MVC framework SDK from http://www.asp.net/mvc. After installation, open Visual Studio 2008 and select menu option File | New | Project. The following screenshot will be displayed. Make sure that you select the .NET framework 3.5 as the target framework. You will notice a new project template called ASP.NET MVC Web Application. This project template creates the default project structure for an ASP.NET MVC application. After clicking on OK, Visual Studio will ask you if you want to create a test project. This dialog offers the choice between several unit testing frameworks that can be used for testing your ASP.NET MVC application. You can decide for yourself if you want to create a unit testing project right now—you can also add a testing project later on. Letting the ASP.NET MVC project template create a test project now is convenient because it creates all of the project references, and contains an example unit test, although this is not required. For this example, continue by adding the default unit test project. What's inside the box? After the ASP.NET MVC project has been created, you will notice a default folder structure. There's a Controllers folder, a Models folder, a Views folder, as well as a Content folder and a Scripts folder. ASP.NET MVC comes with the convention that these folders (and namespaces) are used for locating the different blocks used for building the ASP.NET MVC framework. The Controllers folder obviously contains all of the controller classes; the Models folder contains the model classes; while the Views folder contains the view pages. Content will typically contain web site content such as images and stylesheet files, and Scripts will contain all of the JavaScript files used by the web application. By default, the Scripts folder contains some JavaScript files required for the use of Microsoft AJAX or jQuery. Locating the different building blocks is done in the request life cycle. One of the first steps in the ASP.NET MVC request life cycle is mapping the requested URL to the correct controller action method. This process is referred to as routing. A default route is initialized in the Global.asax file and describes to the ASP.NET MVC framework how to handle a request. Double-clicking on the Global.asax file in the MvcApplication1 project will display the following code: using System;using System.Collections.Generic;using System.Linq;using System.Web;using System.Web.Mvc;using System.Web.Routing;namespace MvcApplication1{ public class GlobalApplication : System.Web.HttpApplication { public static void RegisterRoutes(RouteCollection routes) { routes.IgnoreRoute("{resource}.axd/{*pathInfo}"); routes.MapRoute( "Default", // Route name "{controller}/{action}/{id}", // URL with parameters new { controller = "Home", action = "Index", id = "" } // Parameter defaults ); } protected void Application_Start() { RegisterRoutes(RouteTable.Routes); } }} In the Application_Start() event handler, which is fired whenever the application is compiled or the web server is restarted, a route table is registered. The default route is named Default, and responds to a URL in the form of http://www.example.com/{controller}/{action}/{id}. The variables between { and } are populated with actual values from the request URL or with the default values if no override is present in the URL. This default route will map to the Home controller and to the Index action method, according to the default routing parameters. We won't have any other action with this routing map. By default, all the possible URLs can be mapped through this default route. It is also possible to create our own routes. For example, let's map the URL http://www.example.com/Employee/Maarten to the Employee controller, the Show action, and the firstname parameter. The following code snippet can be inserted in the Global.asax file we've just opened. Because the ASP.NET MVC framework uses the first matching route, this code snippet should be inserted above the default route; otherwise the route will never be used. routes.MapRoute( "EmployeeShow", // Route name "Employee/{firstname}", // URL with parameters new { // Parameter defaults controller = "Employee", action = "Show", firstname = "" } ); Now, let's add the necessary components for this route. First of all, create a class named EmployeeController in the Controllers folder. You can do this by adding a new item to the project and selecting the MVC Controller Class template located under the Web | MVC category. Remove the Index action method, and replace it with a method or action named Show. This method accepts a firstname parameter and passes the data into the ViewData dictionary. This dictionary will be used by the view to display data. The EmployeeController class will pass an Employee object to the view. This Employee class should be added in the Models folder (right-click on this folder and then select Add | Class from the context menu). Here's the code for the Employee class: namespace MvcApplication1.Models{ public class Employee { public string FirstName { get; set; } public string LastName { get; set; } public string Email { get; set; } }} After adding the EmployeeController and Employee classes, the ASP.NET MVC project now appears as shown in the following screenshot: The EmployeeController class now looks like this: using System.Web.Mvc;using MvcApplication1.Models;namespace MvcApplication1.Controllers{ public class EmployeeController : Controller { public ActionResult Show(string firstname) { if (string.IsNullOrEmpty(firstname)) { ViewData["ErrorMessage"] = "No firstname provided!"; } else { Employee employee = new Employee { FirstName = firstname, LastName = "Example", Email = firstname + "@example.com" }; ViewData["FirstName"] = employee.FirstName; ViewData["LastName"] = employee.LastName; ViewData["Email"] = employee.Email; } return View(); } }} The action method we've just created can be requested by a user via a URL—in this case, something similar to http://www.example.com/Employee/Maarten. This URL is mapped to the action method by the route we've created before. By default, any public action method (that is, a method in a controller class) can be requested using the default routing scheme. If you want to avoid a method from being requested, simply make it private or protected, or if it has to be public, add a [NonAction] attribute to the method. Note that we are returning an ActionResult (created by the View() method), which can be a view-rendering command, a page redirect, a JSON result, a string, or any other custom class implementation inheriting the ActionResult that you want to return. Returning an ActionResult is not necessary. The controller can write content directly to the response stream if required, but this would be breaking the MVC pattern—the controller should never be responsible for the actual content of the response that is being returned. Next, create a Show.aspx page in the Views | Employee folder. You can create a view by adding a new item to the project and selecting the MVC View Content Page template, located under the Web | MVC category, as we want this view to render in a master page (located in Views | Shared). There is an alternative way to create a view related to an action method, which will be covered later in this article. In the view, you can display employee information or display an error message if an employee is not found. Add the following code to the Show.aspx page: <%@ Page Title="" Language="C#" MasterPageFile="~/Views/Shared/Site.Master" AutoEventWireup="true" Inherits=" System.Web.Mvc.ViewPage" %><asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server"> <% if (ViewData["ErrorMessage"] != null) { %> <h1><%=ViewData["ErrorMessage"]%></h1> <% } else { %> <h1><%=ViewData["FirstName"]%> <%=ViewData["LastName"]%></h1> <p> E-mail: <%=ViewData["Email"]%> </p> <% } %></asp:Content> If the ViewData, set by the controller, is given an ErrorMessage, then the ErrorMessage is displayed on the resulting web page. Otherwise, the employee details are displayed. Press the F5 button on your keyboard to start the development web server. Alter the URL in your browser to something ending in /Employee/Your_Name_Here, and see the action method and the view we've just created in action.

PHx in action Let us learn our need of PHx by building a new functionality for our site that lets us add profiles of our family members and friends. We will add a new page called 'Family and Friends' that will show the list of all the individuals that we add. Once the user clicks on an individual, it will show certain details such as name, relationship to you, occupation, web site. This is easy to implement; all we have to do is create the template variables for each of the fields, and create a template that uses these template variables. So, to display the Occupation, the template will have a code similar to the following: Occupation: [*occupation*] Though this might appear to work initially, it has a small glitch in it. When we are entering the personal details of an individual, we may not want to enter all of the values for every individual. In the case of not having a value for the variable, it looks cleaner to not show the label at all instead of leaving it blank. In our case—if we have no value for occupation—it will look cleaner to not show the label Occupation. So here comes a need for displaying certain text only if the template variable—in this case, occupation—has a value. We can do this using PHx without having to write a snippet. Installing PHx To download PHx, use the following steps: Download PHx from http://MODxcms.com/PHx-1006.html. Extract the contents of the downloaded file. Create a directory called phx in the assets/plugins folder of your MODx installation. Copy all the files within the extracted folder to the assets/plugins/phx folder. Create a new plug-in using the MODx Manager interface: Click on the Manage Resources menu item in the Resources menu Click on the Plugins tab Click on the New Plugin link Fill it with the following details: Field Name Field Value Plugin Name PHx Plugin Code Contents of the file phx.plugin.txt in the extracted folder System Events | OnParseDocument Checked      6.Click on Save. Adding Family and Friends documents Let us create a page that lists all the members from the Family or Friends group. This document will be a container that will have a document for each member that you would like to add. Hence, just as you have learned earlier, a call to the Ditto snippet can get you all the documents that a container holds. Create a page with the following details: Field Name Field Value Title Family and Friends Uses template Learning MODx default template Modify the page created in the previous step to have the following code. (Note that we need to know the ID of the created page for the code and hence, we are modifying it after creating it.) <ul> [!Ditto? &parents=`65` &tpl=`familyandfriendslist`!]</ul> Here, 65 is the ID of the created document. We give the ID of this document here as we will be adding the other documents as child documents of this document. In the above Ditto call, we have indicated that we are using a custom chunk to control the appearance of the listing. Create a chunk with the following details, to show a neat list of the documents that represent a member with the title and a link to the document. Field Name Field Value Chunk name familyandfriendslist Existing Category Learning MODx Chunk Code <li> <h3><a href="[~[+id+]~]">[+title+]</a></h3> </li>  

Using Spring Faces Module The following section shows you how to use the Spring Faces module. Overview of all tags of the Spring Faces tag library The Spring Faces module comes with a set of components, which are provided through a tag library. If you want more detailed information about the tag library, look at the following files inside the Spring Faces source distribution: spring-faces/src/main/resources/META-INF/spring-faces.tld spring-faces/src/main/resources/META-INF/springfaces.taglib.xml spring-faces/src/main/resources/META-INF/faces-config.xml If you want to see the source code of a specific tag, refer to faces-config.xml and springfaces.taglib.xml to get the name of the class of the component. The spring-faces.tld file can be used for documentation issues. The following table should give you a short description about the available tags from the Spring Faces component library: Name of the tag Description includeStyles The includeStyles tag renders the necessary CSS stylesheets which are essential for the components from Spring Faces. The usage of this tag in the head section is recommended for performance optimization. If the tag isn't included, the necessary stylesheets are rendered on the first usage of the tag. If you are using a template for your pages, it's a good pattern to include the tag in the header of that template. For more information about performance optimization, refer to the Yahoo performance guidelines, which are available at the following URL: http://developer.yahoo.com/performance. Some tags (includeStyles, resource, and resourceGroup) of the Spring Faces tag library are implementing patterns to optimize the performance on client side. resource The resource tag loads and renders a resource with ResourceServlet. You should prefer this tag instead of directly including a CSS stylesheet or a JavaScript file because ResourceServlet sets the proper response headers for caching the resource file. resourceGroup With the resourceGroup tag, it is possible to combine all resources which are inside the tag. It is important that all resources are the same type. The tag uses ResourceServlet with the appended parameter to create one resource file which is sent to the client. clientTextValidator With the clientTextValidator tag, you can validate a child inputText element. For the validation, you have an attribute called regExp where you can provide a regular expression. The validation is done on client side. clientNumberValidator With the clientNumberValidator tag, you can validate a child inputText element. With the provided validation methods, you can check whether the text is a number and check some properties for the number, e.g. range. The validation is done on client side. clientCurrencyValidator With the clientCurrencyValidator tag, you can validate a child inputText element. This tag should be used if you want to validate a currency. The validation is done on client side. clientDateValidator With the clientDateValidator tag, you can validate a child inputText element. The tag should be used to validate a date. The field displays a pop-up calendar. The validation is done on client side. validateAllOnClick With the validateAllOnClick tag, you can execute all client-side validation on the click of a specific element. That can be useful for a submit button. commandButton With the commandButton tag, it is possible to execute an arbitrary method on an instance. The method itself has to be a public method with no parameters and a java.lang.Object instance as the return value. commandLink The commandLink tag renders an AJAX link. With the processIds attribute, you can provide the ids of components which should be processed through the process. ajaxEvent The ajaxEvent tag creates a JavaScript event listener. This tag should only be used if you can ensure that the client has JavaScript enabled. A complete example After we have shown the main configuration elements and described the Spring Faces components, the following section shows a complete example in order to get a good understanding about how to work with the Spring Faces module in your own web application. The following diagram shows the screen of the sample application. With the shown screen, it is possible to create a new issue and save it to the bug database. It is not part of this example to describe the bug database or to describe how to work with databases in general. The sample uses the model classes. The diagram has three required fields. These fields are: Name: The name of the issue Description: A short description for the issue Fix until: The fixing date for the issue Additionally, there are the following two buttons: store: With a click on the store button, the system tries to create a new issue that includes the provided information cancel: With a click on the cancel button, the system ignores the data which is entered and navigates to the overview page. Now, the first step is to create the implementation of that input page. That implementation and its description are shown in the section below. Creating the input page As we described above, we use Facelets as a view handler technology. Therefore, the pages have to be defined with XHTML, with .xhtml as the file extension. The name for the input page will be add.xhtml. For the description, we separate the page into the following five parts: Header Name Description Fix until The Buttons This separation is shown in the diagram below: The Header part The first step in the header is to define that we have an XHTML page. This is done through the definition of the correct doctype. <!DOCTYPE composition PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> An XHTML page is described as an XML page. If you want to use special tags inside the XML page, you have to define a namespace for that. For a page with Facelets and Spring Faces, we have to define more than one namespace. The following table describes those namespaces: Namespace Description http://www.w3.org/1999/xhtml The namespace for XHTML itself. http://java.sun.com/jsf/facelets The Facelet defines some components (tags). These components are available under this namespace. http://java.sun.com/jsf/html The user interface components of JSF are available under this namespace. http://java.sun.com/jsf/core The core tags of JSF, for example converter, can be accessed under this namespace. http://www.springframework.org/tags/faces The namespace for the Spring Faces component library. For the header definition, we use the composition component of the Facelets components. With that component, it is possible to define a template for the layout. This is very similar to the previously mentioned Tiles framework. The following code snippet shows you the second part (after the doctype) of the header definition: A description and overview of the JSF tags is available at: http://developers.sun.com/jscreator/archive/learning/bookshelf/pearson/corejsf/standard_jsf_tags.pdf. <ui:composition template="/WEB-INF/layouts/standard.xhtml"> With the help of the template attribute, we refer to the used layout template. In our example, we refer to /WEB-INF/layouts/standard.xhtml. The following code shows the complete layout file standard.xhtml. This layout file is also described with the Facelets technology. Therefore, it is possible to use Facelets components inside that page, too. Additionally, we use Spring Faces components inside that layout page. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html > <f:view contentType="text/html"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>flow.tracR</title> <sf:includeStyles/> <sf:resourceGroup> <sf:resource path="/css-framework/css/tools.css"/> <sf:resource path="/css-framework/css/typo.css"/> <sf:resource path="/css-framework/css/forms.css"/> <sf:resource path="/css-framework/css/layout-navtop-localleft. css"/> <sf:resource path="/css-framework/css/layout.css"/> </sf:resourceGroup> <sf:resource path="/css/issue.css"/> <ui:insert name="headIncludes"/> </head> <body class="tundra spring"> <div id="page"> <div id="content"> <div id="main"> <ui:insert name="content"/> </div> </div> </div> </body> </f:view> </html> The Name part The first element in the input page is the section for the input of the name. For the description of that section, we use elements from the JSF component library. We access this library with h as the prefix, which we have defined in the header section. For the general layout, we use standard HTML elements, such as the div element. The definition is shown below. <div class="field"> <div class="label"> <h:outputLabel for="name">Name:</h:outputLabel> </div> <div class="input"> <h:inputText id="name" value="#{issue.name}" /> </div> </div> The Description part The next element in the page is the Description element. The definition is very similar to the Name part. Instead of the definition of the Name part, we use the element description inside the h:inputText element—the required attribute with true as its value. This attribute tells the JSF system that the issue.description value is mandatory. If the user does not enter a value, the validation fails. <div class="field"> <div class="label"> <h:outputLabel for="description">Description:</h:outputLabel> </div> <div class="input"> <h:inputText id="description" value="#{issue.description}" required="true"/> </div> </div> The Fix until part The last input section is the Fix until part. This field is a very common field in web applications, because there is often the need to input a date. Internally, a date is often represented through an instance of the java.util.Date class. The text which is entered by the user has to be validated and converted in order to get a valid instance. To help the user with the input, a calendar for the input is often used. The Spring Faces library offers a component which shows a calendar and adds client-side validation. The complete definition of the Fix until part is shown below. The name of the component is clientDateValidator. The clientDateValidator component is used with sf as the prefix. This prefix is defined in the namespace definition in the shown header of the add.xhtml page. <div class="field"> <div class="label"> <h:outputLabel for="checkinDate">Fix until:</h:outputLabel> </div> <div class="input"> <sf:clientDateValidator required="true" invalidMessage="pleaseinsert a correct fixing date. format: dd.MM.yyyy"promptMessage="Format: dd.MM.yyyy, example: 01.01.2020"> <h:inputText id="checkinDate" value="#{issue.fixingDate}" required="true"> <f:convertDateTime pattern="dd.MM.yyyy" timeZone="GMT"/> </h:inputText> </sf:clientDateValidator> </div> </div> In the example above, we use the promptMessage attribute to help the user with the format. The message is shown when the user sets the cursor on the input element. If the validation fails, the message of the invalidMessage attribute is used to show the user that a wrong formatted input has been entered. The Buttons part The last element in the page are the buttons. For these buttons, the commandButton component from Spring Faces is used. The definition is shown below: <div class="buttonGroup"> <sf:commandButton id="store" action="store" processIds="*" value="store"/> <sf:commandButton id="cancel" action="cancel" processIds="*" value="cancel"/> </div> It is worth mentioning that JavaServer Faces binds an action to the action method of a backing bean. Spring Web Flow binds the action to events. Handling of errors It's possible to have validation on the client side or on the server side. For the Fix until element, we use the previously mentioned clientDateValidator component of the Spring Faces library. The following figure shows how this component shows the error message to the user: Reflecting the actions of the buttons into the flow definition file Clicking the buttons executes an action that has a transition as the result. The name of the action is expressed in the action attribute of the button component which is implemented as commandButton from the Spring Faces component library. If you click on the store button, the validation is executed first. If you want to prevent that validation, you have to use the bind attribute and set it to false. This feature is used for the cancel button, because in this state it is necessary to ignore the inputs. <view-state id="add" model="issue"> <transition on="store" to="issueStore" > <evaluate expression="persistenceContext.persist(issue)"/> </transition> <transition on="cancel" to="cancelInput" bind="false"> </transition> </view-state> Showing the results To test the implemented feature, we implement an overview page. We have the choice to implement the page as a flow with one view state or implement it as a simple JSF view. Independent from that choice, we will use Facelets to implement that overview page, because Facelets does not depend on the Spring Web Flow Framework as it is a feature of JSF. The example uses a table to show the entered issues. If no issue is entered, a message is shown to the user. The figure below shows this table with one row of data. The Id is a URL. If you click on this link, the input page is shown with the data of that issue. With data, we execute an update. The indicator for that is the valid ID of the issue. If your data is available, the No issues in database message is shown to the user. This is done with a condition on the outputText component. See the code snippet below: <h:outputText id="noIssuesText" value="No Issues in the database" rendered="#{empty issueList}"/> For the table, we use the dataTable component. <h:dataTable id="issues" value="#{issueList}" var="issue"rendered="#{not empty issueList}" border="1"> <h:column> <f:facet name="header">Id</f:facet> <a href="add?id=#{issue.id}">#{issue.id}</a> </h:column> <h:column> <f:facet name="header">Name</f:facet> #{issue.name} </h:column> <h:column> <f:facet name="header">fix until</f:facet> #{issue.fixingDate} </h:column> <h:column> <f:facet name="header">creation date</f:facet> #{issue.creationDate} </h:column> <h:column> <f:facet name="header">last modified</f:facet> #{issue.lastModified} </h:column> </h:dataTable>

Defining Many-To-Many Relationship in Models In the previous article in this series on Working with Simple Associations using CakePHP, we assumed that a book can have only one author. But in real life scenario, a book may also have more than one author. In that case, the relation between authors and books is many-to-many. We are now going to see how to define associations for a many-to-many relation. We will modify our existing code-base that we were working on in the previous article to set up the associations needed to represent a many-to-many relation. Time for Action: Defining Many-To-Many Relation Empty the database tables: TRUNCATE TABLE `authors`;TRUNCATE TABLE `books`; Remove the author_id field from the books table: ALTER TABLE `books` DROP `author_id` Create a new table, authors_books:; CREATE TABLE `authors_books` (`author_id` INT NOT NULL ,`book_id` INT NOT NULL Modify the Author (/app/models/author.php) model: <?phpclass Author extends AppModel{ var $name = 'Author'; var $hasAndBelongsToMany = 'Book';}?> Modify the Book (/app/models/book.php) model: <?phpclass Book extends AppModel{ var $name = 'Book'; var $hasAndBelongsToMany = 'Author';}?> Modify the AuthorsController (/app/controllers/authors_controller.php): <?phpclass AuthorsController extends AppController { var $name = 'Authors'; var $scaffold;}?> Modify the BooksController (/app/controllers/books_controller.php): <?phpclass BooksController extends AppController { var $name = 'Books'; var $scaffold;}?> Now, visit the following URLs and add some test data into the system:http://localhost/relationship/authors/ and http://localhost/relationship/books/ What Just Happened? We first emptied the database and then dropped the field author_id from the books table. Then we added a new join table authors_books that will be used to establish a many-to-many relation between authors and books. The following diagram shows how a join table relates two tables in many-to-many relation: In a many-to-many relation, one record of any of the tables can be related to multiple records of the other table. To establish this link, a join table is used—a join table contains two fields to hold the primary-keys of both of the records in relation. CakePHP has certain conventions for naming a join table—join tables should be named after the tables in relation, in alphabetical order, with underscores in between. The join table between authors and books tables should be named authors_books, not books_authors. Also by Cake convention, the default value for the foreign keys used in the join table must be underscored, singular name of the models in relation, suffixed with _id. After creating the join table, we defined associations in the models, so that our models also know about the new relationship that they have. We added hasAndBelongsToMany (HABTM) associations in both of the models. HABTM is a special type of association used to define a many-to-many relation in models. Both the models have HABTM associations to define the many-to-many relationship from both ends. After defining the associations in the models, we created two controllers for these two models and put in scaffolding in them to see the association working. We could also use an array to set up the HABTM association in the models. Following code segment shows how to use an array for setting up an HABTM association between authors and books in the Author model: var $hasAndBelongsToMany = array( 'Book' => array( 'className' => 'Book', 'joinTable' => 'authors_books', 'foreignKey' => 'author_id', 'associationForeignKey' => 'book_id' ) ); Like, simple relationships, we can also override default association characteristics by adding/modifying key/value pairs in the associative array. The foreignKey key/value pair holds the name of the foreign-key found in the current model—default is underscored, singular name of the current model suffixed with _id. Whereas, associationForeignKey key/value pair holds the foreign-key name found in the corresponding table of the other model—default is underscored, singular name of the associated model suffixed with _id. We can also have conditions, fields, and order key/value pairs to customize the relationship in more detail. Retrieving Related Model Data in Many-To-Many Relation Like one-to-one and one-to-many relations, once the associations are defined, CakePHP will automatically fetch the related data in many-to-many relation. Time for Action: Retrieving Related Model Data Take out scaffolding from both of the controllers—AuthorsController (/app/controllers/authors_controller.php) and BooksController (/app/controllers/books_controller.php). Add an index() action inside the AuthorsController (/app/controllers/authors_controller.php), like the following: <?phpclass AuthorsController extends AppController { var $name = 'Authors'; function index() { $this->Author->recursive = 1; $authors = $this->Author->find('all'); $this->set('authors', $authors); }}?> Create a view file for the /authors/index action (/app/views/authors/index.ctp): <?php foreach($authors as $author): ?><h2><?php echo $author['Author']['name'] ?></h2><hr /><h3>Book(s):</h3><ul><?php foreach($author['Book'] as $book): ?><li><?php echo $book['title'] ?></li><?php endforeach; ?></ul><?php endforeach; ?> Write down the following code inside the BooksController (/app/controllers/books_controller.php): <?phpclass BooksController extends AppController { var $name = 'Books'; function index() { $this->Book->recursive = 1; $books = $this->Book->find('all'); $this->set('books', $books); }}?> Create a view file for the action /books/index (/app/views/books/index.ctp): <?php foreach($books as $book): ?><h2><?php echo $book['Book']['title'] ?></h2><hr /><h3>Author(s):</h3><ul><?php foreach($book['Author'] as $author): ?><li><?php echo $author['name'] ?></li><?php endforeach; ?></ul><?php endforeach; ?> Now, visit the following URLs:http://localhost/relationship/authors/http://localhost/relationship/books/ What Just Happened? In both of the models, we first set the value of $recursive attributes to 1 and then we called the respective models find('all') functions. So, these subsequent find('all') operations return all associated model data that are related directly to the respective models. These returned results of the find('all') requests are then passed to the corresponding view files. In the view files, we looped through the returned results and printed out the models and their related data. In the BooksController, this returned data from find('all') is stored in a variable $books. This find('all') returns an array of books and every element of that array contains information about one book and its related authors. Array ( [0] => Array ( [Book] => Array ( [id] => 1 [title] => Book Title ... ) [Author] => Array ( [0] => Array ( [id] => 1 [name] => Author Name ... ) [1] => Array ( [id] => 3 ... 54 54 ... ...) Same for the Author model, the returned data is an array of authors. Every element of that array contains two arrays: one contains the author information and the other contains an array of books related to this author. These arrays are very much like what we got from a find('all') call in case of the hasMany association.

Installing Elgg In addition to its impressive feature list, Elgg is an admin's dolly. In this tutorial by Mayank Sharma, we will see how Elgg can be installed in popular Linux web application rollout stack of Linux, Apache, MySQL, and PHP, fondly referred to as LAMP. As MySQL and PHP can run under Windows operating system as well, you can set up Elgg to serve your purpose for such an environment. Setting Up LAMP Let's look at setting up the Linux, Apache, MySQL, PHP web server environment. There are several reasons for the LAMP stack's popularity. While most people enjoy the freedom offered by these Open Source software, small business and non-profits will also be impressed by its procurement cost—$0. Step 1: Install Linux The critical difference between setting up Elgg under Windows or Linux is installing the operating system. The Linux distribution I'm using to set up Elgg is Ubuntu Linux ( http://www.ubuntu.com/ ).It's available as a free download and has a huge and active global community, should you run into any problems. Covering step-by-step installation of Ubuntu Linux is too much of a digression for this tutorial. Despite the fact that Ubuntu isn't too difficult to install, because of its popularity there are tons of installation and usage documentation available all over the Web. Linux.com has a set of videos that detail the procedure of installing Ubuntu ( http://www.linux.com/articles/114152 ).Ubuntu has a dedicated help section ( https://help.ubuntu.com/ ) for introduction and general usage of the distribution. Step 2: Install Apache Apache is the most popular web server used on the Internet. Reams and reams of documents have been written on installing Apache under Linux. Apache's documentation sub-project ( http://httpd.apache.org/docs-project/ ) has information on installing various versions of Apache under Linux. Ubuntu, based on another popular Linux distribution, Debian, uses a very powerful and user-friendly packaging system. It's called apt-get and can install an Apache server within minutes. All you have to do is open a terminal and write this command telling apt-get what to install: apt-get install apache2 apache2-common apache2-doc apache2-mpm-prefork apache2-utils libapr0 libexpat1 ssl-cert This will download Apache and its most essential libraries. Next, you need to enable some of Apache's most critical modules: a2enmod ssla2enmod rewritea2enmod include The rewrite module is critical to Elgg, so make sure it's enabled, else Elgg wouldn't work properly. That's it. Now, just restart Apache with: /etc/init.d/apache2 restart. Step 3: MySQL Installing MySQL isn't too much of an issue either. Again, like Ubuntu and Apache, MySQL can also boast of a strong and dedicated community. This means there's no dearth of MySQL installation or usage related documentation ( http://www.mysql.org/doc/ ). If you're using MySQL under Ubuntu, like me, installation is just a matter of giving apt-get a set of packages to install: apt-get install mysql-server mysql-client libmysqlclient12-dev Finally, set up a password for MySQL with: mysqladmin -h yourserver.example.com -u root password yourrootmysqlpassword Step 4: Install PHP Support You might think I am exaggerating things a little bit here, but I am not, PHP is one of the most popular and easy to learn languages for writing web applications. Why do you think we are setting up out Linux web server environment to execute PHP? It's because Elgg itself is written in PHP! And so are hundreds and thousands of other web applications. So I'm sure you've guessed by now that PHP has a good deal of documentation ( http://www.php.net/docs.php )as well. You've also guessed it's now time to call upon Ubuntu's apt-get package manager to set up PHP:  apt-get install libapache2-mod-php5 php5 php5-common php5-gd php5-mysql php5-mysqli As you can see, in addition to PHP, we are also installing packages that'll hook up PHP with the MySQL database and the Apache web server. That's all there is to setting up the LAMP architecture to power your Elgg network. Setting Up WAMP If you are used to Microsoft's Windows operating system or want to avoid the extra minor learning curve involved with setting up the web server on a Linux distribution, especially, if you haven't done it before, you can easily replicate the Apache, MySQL, PHP web server on a Windows machine. Cost wise, all server components the Apache web server, MySQL database, and the PHP development language have freely available Windows versions as well. But the base component of this stack, the operating system —Microsoft Windows, isn't. Versions of Apache, MySQL, and PHP for Windows are all available on the same websites mentioned above. As Windows doesn't have an apt-get kind of utility, you'll have to download and install all three components from their respective websites, but you have an easier way to set up a WAMP server. There are several pre-packaged Apache, MySQL, and PHP software bundles available for Windows(http://en.wikipedia.org/wiki/Comparison_of_WAMPs).I've successfully run Elgg on the WAMP5 bundle (http://www.en.wampserver.com/). The developer updates the bundle, time and again, to make sure it's running the latest versions of all server components included in the bundle. Note - While WAMP5 requires no configuration, make sure you have Apache's rewrite_module and PHP's php_gd2 extension enabled. They will have a bullet next to their name if they are enabled. If the bullet is missing, click on the respective entries under the Apache and PHP sub-categories and restart WAMP5. Installing Elgg Now that we have a platform ready for Elgg, let's move on to the most important step of setting up Elgg. Download the latest version of Elgg from its website. At the time of writing this tutorial, the latest version of Elgg was Elgg-0.8. Elgg is distributed as a zipped file. To uncompress under Linux: Move this zipped file to /tmp and uncompress it with the following command: $ unzip /tmp/elgg-0.8.zip To uncompress under Windows: Right-click on the ZIP file and select the Extract here option. After uncompressing the ZIP file, you should have a directory called Elgg-<version-number>, in my case, elgg-0.8/. This directory contains several sub directories and files. The INSTALL file contains detailed installation instructions. The first step is to move this uncompressed directory to your web server. Note: You can set up Elgg on your local web server that sits on the Internet or on a paid web server in a data center anywhere on the planet. The only difference between the two setups is that if you don't have access to the local web server, you'll have to contact the web service provider and ask him about the transfer options available to you. Most probably, you'll have FTP access to your web server, and you'll have to use one of the dozens of FTP clients, available for free, to transfer Elgg's files from your computer to the remote web server. Optionally, if you have "shell" access on the web server, you might want to save time by transferring just the zipped file and unzipping it on the web server itself. Contact your web server provider for this information. The web server's directory where you need to copy the contents of the Elgg directory depends upon your Apache installation and operating system. In Ubuntu Linux, the default web server directory is /var/www/. In Windows, WAMP5 asks where it should create this directory during installation. By default, it's the www directory and is created within the directory you installed WAMP5 under. Note: Another important decision you need to make while installing Elgg is how do you want your users to access your network. If you're setting up the network to be part of your existing web infrastructure, you'll need to install Elgg inside a directory. If, on the other hand, you are setting up a new site just for the Elgg-powered social network, copy the contents of the Elgg directory inside the www directory itself and not within a subdirectory. Once you have the Elgg directory within your web server's www directory, it's time to set things in motion. Start by renaming the config-dist.php file to config.php and the htaccess-dist to .htaccess. Simply right-click on the file and give it a new name or use the mv command in this format: $ mv <original-file-name> <new-file-name> Note : To rename htacces-dist to .htaccess in Windows, you'll have to open the htaccess-dist file in notepad and then go to File | Save As and specify the name as .htaccess with the quotes. Editing config.php Believe it or not, we've completed the "installation" bit of setting up Elgg. But we still need to configure it before throwing the doors open to visitors. Not surprisingly, all this involves is creating a database and editing the config.php file to our liking. Creating a Database Making an empty database in MySQL isn't difficult at all. Just enter the MySQL interactive shell using your username, password, and hostname you specified while installing MySQL. $ mysql -u root -h localhost -pEnter password: Welcome to the MySQL monitor. Commands end with ; or g.Your MySQL connection id is 9 to server version: 5.0.22-Debian_0ubuntu6.06.3-logType 'help;' or 'h' for help. Type 'c' to clear the buffer.mysql> CREATE DATABASE elgg; You can also create a MySQL database using a graphical front-end manager like PHPMyAdmin, which comes with WAMP5. Just look for a database field, enter a new name (Elgg), and hit the Create button to create an empty Elgg database. Initial Configuration Elgg has a front-end interface to set up config.php, but there are a couple of things you need to do before you can use that interface: Create a data directory outside your web server root. As described in the configuration file, this is a special directory where uploaded files will go. It's also advisable to create this directory outside your main Elgg install. This is because this directory will be writable by everyone accessing the Elgg site and having such a "world-accessible" directory under your Elgg installation is a security risk. If you call the directory Elgg-data, make it world-readable with the following command: $ chmod 777 elgg-data Setup admin username and password. Before you can access Elgg's configuration web front-end, you need an admin user and a password. For that open the config.php file in your favorite text editor and scroll down to the following variables: $CFG->adminuser = "";$CFG->adminpassword = ""; Specify your chosen admin username and password between the quotes, so that it looks something like this: $CFG->adminuser = "admin";$CFG->adminpassword = "765thyr3"; Make sure you don't forget the username and password of the admin user. Important Settings When you have created the data directory and specified an admin username and password, it's time to go ahead with the rest of the configuration. Open a web browser and point to http://<your-web-server>/<Elgg-installation>/elggadmin/ This will open up a simple web page with lots of fields. All fields have a title and a brief description of the kind of information you need to fill in that field. There are some drop-down lists as well, from which you have to select one of the listed options. Here are all the options and their descriptions: Administration panel username: Username to log in to this admin panel, in future, to change your settings. Admin password: Password to log in to this admin panel in future. Site name: Enter the name of your site here (e.g. Elgg, Apcala, University of Bogton's Social Network, etc.). Tagline: A tagline for your site (e.g. Social network for Bogton). Web root: External URL to the site (e.g. http://elgg.bogton.edu/). Elgg install root: Physical path to the files (e.g./home/Elggserver/httpdocs/). Elgg data root: This is a special directory where uploaded files will go. If possible, this should live outside your main Elgg installation? (you'll need to create it by hand). It must have world writable permissions set, and have a final slash at the end. Note: Even in Windows, where we use back slashes () to separate directories, use Unix's forward slashes (/) to specify the path to the install root, data root, and other path names. For example, if you have Elgg files under WAMP's default directory in your C drive, use this path: C:/wamp/www/elgg/. Database type: Acceptable values are mysql and postgres - MySQL is highly recommended. System administrator email: The email address your site will send emails from(e.g. elgg-admin@bogton.edu). News account initial password: The initial password for the 'news' account. This will be the first administrator user within your system, and you should change the password immediately after the first time you log in. Default locale: Country code to set language to if you have gettext installed. Public registration: Can general members of the public register for this system? Public invitations: Can users of this system invite other users? Maximum users: The maximum number of users in your system. If you set this to 0, you will have an unlimited number of users. Maximum disk space: The maximum disk space taken up by all uploaded files. Disable public comments: Set the following to true to force users to log in before they can post comments, overriding the per-user option. This is a handy sledgehammer-to-crack-a-nut tactic to protect against comment spam (although an Akismet plug-in is available from elgg.org). Email filter: Anything you enter here must be present in the email address of anyone who registers; e.g. @mycompany.com will only allow email address from mycompany.com to register. Default access: The default access level for all new items in the system. Disable user templates: If this is set, users can only choose from available templates rather than defining their own. Persistent connections: Should Elgg use persistent database connections? Debug: Set this to 2047 to get ADOdb error handling. RSS posts maximum age: Number of days for which to keep incoming RSS feed entries before deleting them. Set this to 0 if you don't want RSS posts to be removed. Community create flag: Set this to admin if you would like to restrict the ability to create communities to admin users. cURL path: Set this to the cURL executable if cURL is installed; otherwise leave blank. Note : According to Wikipedia, cURL is a command line tool for transferring files with URL syntax, supporting FTP, FTPS, HTTP, HTTPS, TFTP, SCP,SFTP, Telnet, DICT, FILE, and LDAP. The main purpose and use for cURL is to automate unattended file transfers or sequences of operations. For example, it is a good tool for simulating a user's actions at a web browser. Under Ubuntu Linux, you can install curl using the following command: apt-get install curl Templates location: The full path of your Default_Template directory. Profile location: The full path to your profile configuration file (usually, it's best to leave this in mod/profile/). Finally, when you're done, click on the Save button to save the settings. Note : The next version of Elgg, Elgg 0.9, will further simplify installation. Already an early release candidate of this version (elgg-0.9rc1) is a lot more straightforward to install and configure, for initial use. First Log In Now, it's time to let Elgg use these settings and set things up for you. Just point your browser to your main Elgg installation (http://<your-web-servergt;/<Elgg-installation>). It'll connect to the MySQL database and create some tables, then upload some basic data, before taking you to the main page. On the main page, you can use the news account and the password you specified for this account during configuration to log in to your Elgg installation.

Downloading FreeNAS Before you can install the FreeNAS server, you will need to download the latest version from the FreeNAS website (http://www.freenas.org). Go to the download section and find the latest "LiveCD" version. The LiveCD version is what is known as an ISO image file and will have the .iso file extension. An ISO image is an exact copy of the structure and data for a CD or DVD disk. Using a CD burning program, you can create a FreeNAS bootable CD. We will look at this in more detail later on. What Hardware Do I Need? In this tutorial, we will start exploring FreeNAS, so you will need a machine on which to install the FreeNAS software. At this point in time, it doesn't have to be the final machine you are going to use as the FreeNAS server. You can use a "test" machine now and having learnt all about FreeNAS, you can build, install, and deploy a production machine (or machines) later. So, what we need now is a PC with at least 96Mb of RAM (but 128Mb or more is recommended), a bootable CD-ROM drive, a network card, one or more hard disks, and either a floppy disk drive (and a blank formatted disk) or a USB flash disk (MS-DOS formatted and empty). The hard disk will be for the data that you want to store and the floppy disk or USB flash disk will be for storing the configuration information. For the installation and initialization stages, you will also need a monitor and keyboard (but not mouse) attached to the PC. You can remove the monitor later, once FreeNAS is up and running. Warning FreeNAS boots as a LiveCD, which means that it does not use the disks on the host machine during boot up. However, when you start to configure storage on the FreeNAS server (specifically, when you format drives) all the data on the disk will be LOST. Do NOT use a machine that contains important data or an operating system that you will need afterwards. Virtualization  & VMWare The average PC runs just one operating system and inside that operating system, you would run your applications like word processing and email. There is a technology (called virtualization), which allows PCs to run more than one operating system, or to be more precise, to allow a guest virtual PC to run inside your actual PC. This virtual PC is an independent software box that can run its own OS and applications as if it were a physical computer. A virtual PC behaves exactly like a physical PC and has its own virtual CPU, RAM, hard disk, and network interface card (NIC). You can install FreeNAS on a virtual PC and FreeNAS can't tell the difference between the virtual PC and any other physical machine, also, it appears on the network just as a real PC would, running FreeNAS. There are lots of virtualization products available for Windows, Linux, and Apple OS X today. You can learn more at Wikipedia http://en.wikipedia.org/wiki/Virtualization. A very popular virtualization solution is from VMWare (http://www.vmware.com). VMWare have both commercial and freeware offerings and there are pre-configured FreeNAS images available for the VMWare range of products. This makes it an ideal environment for testing the FreeNAS server. Quick Start Guide For the Impatient If you are comfortable with burning ISO images to CDs, setting your computer's BIOS to boot from CDROM, disk partitions, and TCP/IP networking then this little guide should help you get a simple version of the FreeNAS server up and running in just a few minutes. If, however, some of these things sound daunting, then skip this section and go on to the next one where we shall go through the installation process one step at a time. For this example, we will use a USB flash disk to store the configuration information. You can use a floppy but be careful that during the boot process, the PC doesn't try to boot from the floppy before it boots from the CDROM. Burning and Booting Once you have downloaded the ISO image file from the FreeNAS website, you need to burn it to a CD. Having done that, put the CD into the PC as well as the flash disk and switch it on. Make sure that the BIOS is set to boot from CD. If it isn't, you need to enter into the BIOS and configure it to boot from CD. On many modern PCs, it is possible to select the boot device at start-up by pressing a special key (which is often either F8 or F12) to show a boot device menu. You can then select the CD as the boot device. The boot process is in four distinct parts: First, the PC will go through its POST (Power On Self Test) sequence. Here, the PC will check the amount of memory installed (which you can often see being counted on the screen) and which devices are connected (like hard drives and CDROMs). It should then start to boot from the CD. Here, FreeBSD (the underlying OS of FreeNAS) will start to boot, this is recognizable by the simple spinning wheel (made up of simple text characters like | - / and , which are animated to give the appearance of spinning). The third step is the FreeNAS boot menu. This will appear for just a few seconds and you should just let it boot normally, which is the default. The final stage is when the FreeNAS logo appears and the system will boot as FreeNAS server. You can tell when the system is fully loaded because the PC speaker will make some short but melodious beeps. To enable access to the web interface, the network of the FreeNAS server must be configured. Press the SPACE bar on the keyboard and the FreeNAS logo will disappear and a simple text menu will appear.       There are two aspects to configuring the network, first, you need to choose which network card to use and second, you need to assign it an address. If you have only one network card in your machine, then the FreeNAS server should have found it and automatically assigned it to be the LAN (Local Area Network) interface. What If My Network Card Isn't Found?This probably means that the network card in your machine isn't supported by FreeNAS or more specifically, by FreeBSD. You will need to replace the card with one supported by FreeBSD. Check the FreeBSD hardware compatibility page for more information: http://www.freebsd.org/releases/6.2R/hardware-i386.html If you see something like this: then the network has been recognized and assigned automatically by FreeNAS. The default IPv4 address for FreeNAS is 192.168.1.250, if this is good for your network, then you can just leave it unchanged. However, if you need to change it then press 2 followed by ENTER. If you want the machine to get its address from DHCP (Dynamic Host Configuration Protocol), answer yes (y) to the IPv4 DHCP question, otherwise answer no (n). If you are not using DHCP, you can now enter the desired IP address. Next, you need to enter the subnet mask. For 255.255.255.0, enter 24, for 255.255.0.0 enter 16, and for 255.0.0.0, enter 8. At this point, you can now skip the default gateway and DNS questions (by just pressing ENTER). If you do want to enter a default gateway and DNS server at this point, they will usually be the IP address of your Internet router. We won't be using IPv6 so the simplest thing to do now is just answer yes to the "Do you want to use AutoConfiguration for IPv6?" question. This will cause a small delay while FreeNAS tries (and probably fails) to get the IPv6 address but it is simpler than trying to enter the IPv6 address manually! You are now ready to access the web interface. The FreeNAS web interface can be accessed from any machine on the network with a web browser (including Windows, Linux, and OS X machines). On this client machine, type the address of the FreeNAS server with http:// in front of it into your web browser. For example: http://192.168.1.250 Configuring The first time you access the FreeNAS web interface, you will be asked for the username and password. The default username is admin and the default password is freenas. You should now be in the web interface. To configure some storage space, you need to work with "Disks". The logical order of working is that disks must be added, then formatted (if need be), then mounted. Finally, access is given to the various mounted disks by configuring different system services like CIFS and FTP.     So, to add a disk, go to Disks: Management. There is a + sign in a circle on the right-hand-side of the page (it can be easy to miss first time), click on it to add a disk. On the next page, select the disk you want to add. If you click on the drop-down menu, you should see the hard disks of the machines, the CDROM, and the USB flash disk. Dis'k Names in FreeBSD'The disk naming convention in FreeBSD is:/dev/ad0: Is the IDE/ATA Primary Master /dev/ad1 : Is the IDE/ATA Primary Slave/dev/ad2 : Is the IDE/ATA Secondary Master/dev/ad3 : Is the IDE/ATA Secondary Slave/dev/acd0 : Is the first ATA CD/DVD drive detected/dev/da0: Is the first SCSI hard drive, /dev/da1 the second and so on.USB flash disks are controlled using the SCSI driver, so they will appear as /dev/daN drives as well. Make sure ad0 is selected (which it should be by default). The rest of the page you can leave alone. Click Add to add the disk to the system. You then need to click Apply in order for the changes to take effect. You will now have a table showing you the disk you have added, including its size and a description. ApplyIn FreeNAS, the majority of steps need to be applied (which saves the configuration file to disk) by clicking the Apply button. It is normally found near the top of the page before any tables or configuration information is given. If you do not apply the changes, the interface will, on the whole, remember your changes but they will not be enacted in the system. After a reboot, unapplied changes will disappear. It is possible on some pages to make multiple operations and apply them all at the end. Next, the disk needs to be formatted. In Disks: Format, select the disk ad0 (which you just added above). Leave everything else unchanged and click Format disk. The disk will then be formatted. The low level output of the format command will be displayed in a box. It should end with Done!. Now the disk needs to be mounted. Go to Disks: Mount Point. Click on the + in the circle (which I shall refer to as the "add circle" from now on). Leave the Type as Disk and select the disk ad0 again. You need to type in a name, store is as good a name as any, but feel free to use which ever descriptive name you want to. Be DescriptiveIn setting up and configuring your FreeNAS server, you will be called upon to invent various names for mount points and share names etc. Try to be as descriptive as you can without being long winded. Temp, scratch, blob, and even zob are OK for testing, but try more meaningful names like storeage1, storage60gb or backupstorage etc. Don't use spaces in the names, instead use underline and in general, the names should be no longer than 15 characters. Although filling-in the description isn't mandatory in the web interface, it is worth using. Once you have completed the form click Add and then apply the changes. Sharing with Windows Machines Now that the disk has been added, formatted, and mounted, it is time to share it on the network and give other users the ability to read and write to it. FreeNAS supports many different types of access protocol, for this start guide, we will only look at Microsoft's CIFS protocol that primarily allows Windows machines (but also Apple OS X and Linux machines) to access the storage. In Services: CIFS/SMB, tick the enable box (in the title of the configuration data table). At this point, you can just about leave everything else as is with the exception of the workgroup name. We will be leaving the authentication method as "Anonymous" here as this is the easiest to get working and provides unrestricted read/write access to everyone. To make sure that the Windows machines are able to find the shared storage, we need to set the workgroup name, on the FreeNAS server, to be the same as the workgroup name of the Windows PC that will access the share. The default workgroup name for Windows Vista is WORKGROUP but note that the default for Window XP Home Edition was MSHOME. Now click Save and Restart. This will save the changes you have made and restart the CIFS service. Go to the Shares tab and click on add circle. Enter a name for the share. Repeating the name of the mount point is probably the safest policy, so in this case, store and also add a comment. Then click ... in the Path section. This will bring up a simple file system browser. The files you are seeing are on the FreeNAS server and NOT on your local PC. Click store and /mnt/store/ will appear in the little edit box at the click. OK it and you will be taken back to the shares page. Now /mnt/store/ has been added as the path. Leave everything else as it is and click Add and then apply the changes. So now the first hard disk of the computer is formatted, mounted, and shared to the rest of the network. Now, we will access the share from a Windows Vista machine. Testing the Share You can perform this test from any machine that supports the CIFS protocol including Windows 95/98/ME, Windows 2000/XP, Apple OS X, and Linux. Here, we are going to use Windows Vista. Open the Network and Sharing Center by clicking Network on the Start menu. When the window appears, Vista will automatically scan the network for any shared network resources. When it has finished, you will see the available machines on the network including FREENAS.     Open up the FREENAS computer and you will see store, the storage area that you configured. Double click on that and you now "inside" the FreeNAS server from within your Windows machine. Try dragging and dropping a few files in to the store area. Then try deleting them again. To access the FreeNAS server without using the Network and Sharing Center, click Start, and type freenas and then press Enter. This will bring up the shares available on the FreeNAS server directly:     Detailed Overview of Installation It is time to get your hands on a working FreeNAS server and to do that, we need to boot it up onto a PC. There are several steps to this. First, you must burn a CD of the ISO image file you have downloaded. Then, you need to boot the PC from the CD; this may involve changing your computers BIOS to make it boot from the optical drive. Then, you can configure the FreeNAS server to make some storage space available on the network. When using the LiveCD to boot FreeNAS, there are two types of storage on FreeNAS: data and configuration information. The data will be held on the hard drive of the PC, but the configuration needs to be held on a floppy disk or a USB flash disk. For this example, we will use a USB flash disk to store the configuration information. Making the FreeNAS CD To boot the PC into FreeNAS, you need a CD. The ISO image file you have downloaded contains all the information needed for the CD, but it needs to be written onto a physical CD. This process is often known as burning the CD as the laser writes to the disk by heating it and marking or scorching the surface layer. You need to use a PC with a CD-RW drive and a blank CD-R disk (I recommend using a good brand name CD-R for best results). Download the FreeNAS ISO image on to that machine. The PC with the CD writer should have some CD writing software on it (for example Roxio Easy CD or Nero). If you are familiar with the CD writing software, go ahead and burn the ISO file to the CD-R disk. If you aren't familiar with the CD writing software or it doesn't have any CD writing software, then I recommend ISO Recorder. You can download it from http://isorecorder.alexfeinman.com/isorecorder.htm.     Booting from CD Put your newly made FreeNAS CD into the CD drive of the machine on which you want to install FreeNAS, and also put the USB flash disk into a USB port. The flash disk will be used to store the configuration data. (You can also use a floppy disk. If you have both a USB flash disk and a floppy inserted, FreeNAS will save the configuration on the USB device). Now, you need to switch on the PC. When a PC starts, it goes through what is known as the Power On Self Test sequence. Here, the PC will check the amount of memory installed in the PC and find the installed hard drives. After the checks, the PC will try and boot from one of the hard drives, the CDROM, the floppy disk or even a USB flash disk. Which device the PC chooses first as its boot device can be changed by a built-in setup program. The setup program lets you modify basic system configuration settings. These settings are stored in a special battery-backed area of the computer's memory that retains the settings even when the power is switched off. During the POST sequence, there is normally a message telling you how to enter into the built-in setup program. It is normally either the DEL key or F2, on some systems it is also F10. You need to enter into the setup to check and/or change the first boot device to be the CDROM so that the computer will boot into FreeNAS. Each PC has a slightly different setup program, so you will need to search around until you find what you need. The three most popular types of setup programs (also known as BIOS Basic Input Output Program) are the Phoenix setup program, the Phoenix-Award setup program, and the AMI setup program. There are many types of BIOS setup programs and each PC manufacturer modifies the setup program for their own use. The information below is really only a "rough guide" to help you feel your way around. Your BIOS setup program may be significantly different from the examples below. The best source of information is the manual that came with your PC or your motherboard. If you don't have one, most PC manufacturers have them available for download on their websites. Phoenix BIOS If your machine has a Phoenix BIOS, then normally you need to press F2 to enter the setup program. The top of the setup program has a menu that you can navigate with the left and right arrow keys, you need to select the Boot menu.     On the Boot menu page, you can move up and down the available boot devices using the up and down arrow keys. You can expand and collapse sections with the + or signs using the ENTER key. To change the boot order, you use the + and keys. You want to make sure that the CDROM is the first device in the list. After you have changed the boot order list, you need to go to the Exit menu (by pressing the right arrow key) and select Exit Saving Changes. The PC will then reboot and after the POST, it will start to boot from the FreeNAS CD.     Phoenix-Award BIOS If your PC has a Phoenix-Award BIOS, then normally, you need to press DEL to enter the setup program. Once inside, you can the up, down, left, and right keys to navigate around the menus. Go in to Advanced BIOS Features and set the First Boot Device to be CDROM by using the + and keys. You now need to save your changes and exit. Pressing ESC will bring you back to the main menu, then select Save & Exit Setup. Often, pressing F10 will have the same effect. The PC will then reboot and if you have made the changes correctly, it will boot from the FreeNAS CD. AMI BIOS The American Megatrends, Inc (AMI) BIOS normally displays a message telling you to Hit <DEL> if you want to run setup. Once inside, it is quite different to that of the setup programs for Phoenix or Award. Here, the Tab key is used to navigate and the arrow keys are used to change values. To go from one page to the next, press the ALT+P keys. This information should also be printed at the bottom of the BIOS setup page. You need to find the variable Boot Sequence and make sure that it is set to boot from the CDROM first. First Look at FreeNAS The boot process is in 4 distinct parts. First, the PC will go through its POST (Power On Self Test) sequence. Here, the PC will check the amount of memory installed (which you can often see being counted on the screen) and which devices are connected (like hard drives and CDROMs). It should then start to boot from the CD. Here, FreeBSD (the underlying OS of FreeNAS) will start to boot, this is recognizable by the simple spinning wheel (made up of simple text characters like | - / and which are animated to give the appearance of spinning). The third step is the FreeNAS boot menu. This will appear for just five seconds and you should just let it boot normally which is the default. The final stage is when the FreeNAS logo appears and the system will boot as a FreeNAS server. You can tell when the system is fully loaded because the PC speaker will make some short but melodious beeps. Configuring the Network The majority of the configuration for FreeNAS is done via a web interface, but before you can use the web interface, the FreeNAS server needs to be configured for your network. This is done via a simple text menu system using the keyboard and monitor attached to the PC with FreeNAS running on it. You probably only need to do this once, and after that this new network information will be saved on the USB flash disk (or floppy disk) and the server will boot into this configuration every time. If you press the SPACE bar on FreeNAS machine, the FreeNAS logo will disappear and a simple menu will appear.     Here, you have a number of options including options to reboot or power off the system. The first two options are about configuring the network and they reflect the two parts to configuring the network, first you need to choose which network card to use (option 1) and second you need to assign it an address (option 2). If you have only one network card in your machine then the FreeNAS server should have found it and automatically assigned it to be the LAN (Local Area Network) interface. What If My Network Card Isn't Found?This probably means that the network card in your machine isn't supported by FreeNAS or more specifically by FreeBSD. You will need to replace the card with one supported by FreeBSD. Check the FreeBSD hardware compatibility page for more information: http://www.freebsd.org/releases/6.2R/hardware-i386.html If you see something like the following screenshot:     then the network has been recognised and assigned automatically by FreeNAS. What is a LAN IP Address? IP stands for Internet Protocol and it is the basic low level language that computers use to talk to each other on the Internet. It is also used on private networks (in the office or at home) to connect different PCs and even printers to each other. An IPv4 address is made up of 4 sets of number (0 to 255) and is expressed in what is known as dot notation (meaning that each number has a dot between it). So 192.168.1.250 is an IP address, it also happens to be the default IP address for the FreeNAS server. Like email, the postal service and telephone, each destination (email account, mailbox or handset) needs a unique way of being identified. This is what IP addresses do; they allow each piece of equipment on the network to have a unique identifier so that messages can be addressed to the right place on the network. Pronouncing IP AddressesIf you need to speak to someone about an IP address, the simplest way is to speak about each digit separately, so 192.168.1.250 isn't "one hundred and ninety two dot" but rather "one nine two dot one six eight dot one dot two five zero". There are two ways in which you can obtain an IP address for the FreeNAS server. The first is to have the address assigned automatically via the DHCP service (Dynamic Host Configuration Protocol), and the second is to assign it manually. What is DHCP?The Dynamic Host Configuration Protocol (DHCP) automates the assignment of IP addresses and other IP parameters (like subnet masks and default gateway). A computer that needs an IP address will send a request to the DHCP server and the server will reply with an IP address from a pool of addresses that have been set aside for this purpose. A DHCP server can be a PC or server (running Windows, OS X or Linux) as well as small devices like modern DSL modems and firewalls. The advantage of the DHCP method is that the IP address assignment, all happens in the background and you don't need to worry about setting it yourself. The disadvantages are that first you need to have an already configured and running DHCP server on your network; and second, DHCP assigns addresses from a pool of available addresses. This means that every time the FreeNAS server boots, it is not guaranteed to have the same address as it had previously. This isn't a problem when using the CIFS protocol, however, for accessing the web interface or using protocols like FTP, it is desirable to have a stable IP address to refer to. However, for testing the FreeNAS server and learning about how it works using a DHCP assigned address could be acceptable for now. It is actually possible to assign fixed, permanent IP address to certain pieces of hardware, including a FreeNAS server over DHCP, but that requires extra advanced configuration changes in the DHCP server that cannot be covered in this tutorial. So opting for the manual IP address, you now need to obtain two pieces of information. The first is the actual IP address for the FreeNAS and the second is what is known as the subnet mask. The subnet mask will also be expressed in the dot notation and is normally something like 255.255.255.0. If you are in an office environment, you need to speak to the network administrator and he/she will be able to give you the information you need. If you are administering your own network, you need to choose an IP that isn't currently allocated to any other machine on your network (and also, isn't part of the address pool of any DHCP server on your network). Having obtained the IP address and subnet mask, you can now configure the FreeNAS server for your network. Select option 2 on the console menu. If you have chosen to have DHCP assign the address, answer yes (y) to the first question about using DHCP for IPv4. Otherwise answer no (n). If you are setting the address manually, you can now enter the address in dot notation, i.e. 192.168.1.240. Next, comes the subnet mask. If your subnet mask is 255.255.255.0: enter 24, for 255.255.0.0: enter 16, and for 255.0.0.0: enter 8. At this point, you can now skip the default gateway and DNS questions (by just pressing ENTER). We won't be using IPv6 so the simplest thing to do now is just answer yes to the "Do you want to use AutoConfiguration for IPv6?" question. This will cause a small delay while FreeNAS tries (and probably fails) to get the IPv6 address but it is simpler than trying to enter the IPv6 address manually! After you have successful set the IP address, there will be a small message on the screen inviting you to access the web interface by opening the listed URL in your web browser. If you have used DHCP, note down the URL listed. If you set the IP address manually, check that the URL listed is the same as the IP address you set with [http:// http://] in front of it. You are now ready to access the web interface. What is IPv4 and IPv6?The Internet Protocol has been around since the mid 1980's and when it was designed, the popularity of the Internet was not envisaged. The number of computers connected to the Internet is quickly growing beyond the addressing capabilities of the original protocol. As an answer to this, a new version of the IP protocol has been designed and has been given the name IP version 6 or IPv6 for short and the older version has taken the name IP version 4 or IPv4 for short. FreeNAS supports both versions of the Internet Protocol. In this tutorial, we will concentrate just on IPv4 as it still remains the most popular of the two protocols. Basic Configuration With your FreeNAS server now being up and running, it is time to access the web interface. Open a web browser on a computer on the same network as the FreeNAS server. Enter in the URL of the FreeNAS server. This should be the same as the IP address of the server with [http:// http://] in the front. The default URL is http://192.168.1.250     The first time you access the FreeNAS web interface, you will be asked for the username and password. The default username is admin and the default password is freenas. FreeNAS Web Interface You should now have the web interface in your browser. The interface is split into two main sections. Down the left-hand-side are the menus, and the right-hand-side contains the pages for configuration. The menus are split into various sections: System, Interfaces, Disks, Services, Access, Status, Diagnostics, and Advanced.     When talking about a particular menu item, we shall use the notation Subsection: Menu Item to help you find the right menu option easily. So, the Management option, which is in the Disks subsection, will be referred to as Disks: Management. System This section is for system level configuration and operations, here for example you can change the username and password, backup and restore the configuration data, and shutdown or reboot the server. Interfaces Here, you can configure the network of the FreeNAS server much like you did via the console menu. You can change the network card that is used for the web interface and assign permanent or automatic IP addresses. Be careful when you change things here as some changes won't take effect until you reboot. If you have changed any of the addressing, you will need to access the web interface with the IP address. Disks This section of the menu is for administering the disks on the server. Here, you can set up disk redundancy (RAID), control encryption, format disks, and mount the disks on the server. Services The various access protocols like CIFS, NFS, and FTP are controlled from here. Each service is administered individually and by default NONE of the services are enabled, so before you can access files stored on the FreeNAS server, you need to enable at least one of these services. Access Most of the services offered by FreeNAS use some form of list of users to control who has access and who does not. This section is for defining these users and the groups they belong to as well as connecting the FreeNAS server to other directory services. Status The status menu has several reporting tools for you to see the current state of your FreeNAS server including a general overview, memory usage, disk usage, and network usage. You can also configure emails to be sent periodically about the status of the server. Diagnostics The diagnostics menu contains different tools to help diagnose any problem with the FreeNAS server, including logs of all the important services and diagnostic information from the hard disks and other system modules. Advanced The advanced section provides some simple tools for executing commands at the operating system level and should not be used by those unfamiliar with FreeBSD.