FIDICtips
FIDICbot
FIDICcharts (vertical version)
Charts :: Info :: CO Diagram ::
 

NOTE

Please note that we have two types of charts:

The discussion below is for the vertical version. Discussion of the horizontal charts is available.

The coding for the vertical FIDICcharts demo is not yet optimised as we are mainly focussing on the conceptual issues related to accessing and visualising complex contractual documents.


Background

FIDIC1, the International Federation of Consulting Engineers, publishes standard forms of contracts for works projects. The most widely used are the Construction Contract for building and engineering works designed by the Client, and the Plant and Design-Build Contract for electrical and mechanical plant and for building and engineering works designed by the Contractor.

We describe here the vertical charting of FIDIC contracts. There are however other types of similar complex documents that we have charted in a similar way. These we cannot discuss.

This discussion is for charting of the contract clauses. Our horizontal charts for the same documents have so far been for procedures (the contract is viewed as a collection of procedures). One can of course design vertical charts in terms of procedures, and indeed maybe as a collection of clauses and procedures. Indeed our aim is to offer charting by both clauses (or text structure) and procedures (or more generally themes) for a given document as each approach has advantages (and disadvantages). The possibility to have combined clauses-procedures charts has to our knowledge not been explored.


Contracts charting

Focussing for now on FIDIC contracts (which presently come as a major suite of four contracts - Construction, Plant and Design-Build, EPC/Turnkey, DBO), most authorities include charts in their publications, teaching materials and presentations. However, the charts tend to be limited in scope, unlike our browser-based swimlanes that allow large charts to be browsed by "brushing" horizontally or be scanning vertically expandable charts. Links to publcations that include charts for FIDIC contracts are given in Reference2.

The main exception is the A4-sized book A new aproach to the International Civil Engineering Contract by G.P. Jones published in 1979 that has some 120 pages of charts for a predecessor to the FIDIC Construction Contract, namely the 3rd Edition of the FIDIC Works of Civil Engineering Contract. These charts aimed to flowchart the contract as a way to understand the logical structure of the contract. The used the standard flowcharting symbols (statement box, question signal, connector signal, stop/start signal) with an annotation signal and a subroutine statement box. Without going into too much detail, our horizontal procedure charts have equivalents as follows:

  • statement box (main box containing the links to pop-ups);
  • subroutine box (pop-up for associated useful information);
  • question signal ("yes/no" box);
  • connector signal (connector lines);

Annotation signals correspond to guidance. These can easily be included and they are to some extent in the demonstration version. However, the primary focus is on organising annotations (in this case sample letters).

The horizontal swimlanes include time periods, an essential feature which is not included in the conventional swimlane charts.

And once again, it must be stressed that the horizontal swimlane visualisation does not aim to analyse contract clauses but to provide a tool to organise and structure inter-related information using the techniques detailed in Concepts.

The visualisation of contracts using vertical swinlanes is the main focus of the present note.


Chart components

For charts based on procedures one simply identifies the main procedures that are involved when using a contract (for example, the determination of a claim). As described above, the elements that make up a procedure chart are more or less equivalent to the basic standard elements used for describing data processing (namely statement boxes, subroutine boxes, question signals, connector signals, annotation signals). In our case for procedure charts:

  • statements displayed as rectangles for two types of statements (clause statements and inline process statements);
  • questions displayed as rectangles with yes/no as answers (= question signal + connector signal);
  • links displayed as lines (= connectors);
  • links for pop-up tooltips for guidance and other information such as standard letters and legal cases (= annotation signals);
  • timelines displayed as lines with the period indicated.

For charts based on contract clauses, G.P. Jones has in the case of early versions of FIDIC contracts demonstrated how the same standard elements can be used to decode contract clauses into a simple, organised flowchart sequence. More importantly modern web-based visualisation allows the flowchart to be displayed in a compact format. Our chart elements for clause-based charts are therefore as follows:

  • clause statements displayed as rectangles (= statement box);
  • process statements which can be:
    • inline (rectangles arising between statements with small rectangles attached that open a popup giving a sequence of processes);
    • offline (small rectangles attached to a statement box that open a popup giving a sequence of processes).
  • questions displayed as rectangles with yes/no as answers (= question signal + connector signal);
  • links displayed as lines (= connectors);
  • links for pop-up tooltips for guidance, etc. (= annotation signals);
  • timelines displayed as lines with the period indicated.

G.P. Jones has summarised the method rules that are used for contract clauses:

  • decode a clause into clause statements and process statements;
  • organise the facts into manageable statements;
  • arrange statements into a logical sequence;
  • question each statement;
  • if a predefined process or subroutine has to be followed at a particular point in the sequence of statements, introduce a subroutine 'obey' signal;
  • add an annotation signal where needed to any statement or sub-routine.


Process statements

Process statements need some discussion as there are some subtilities that may prove to be useful.

Process statements (both inline and offline) are denoted as

  • linking in a clause to further information (we display a *** tag);
  • requiring in a clause details to be filled in (we display a ::: tag).

We are currently unsure if this type of indication is useful (it was developed originally by G.P. Jones for the FIDIC contracts).


Document-generated visualisation

In principle, one could introduce into a document tags that would allow the visualisation chart to be created programatically.

In practice it is easier to create a static visualisation framework and then use tags to create additional visual elements.

Currently we have:

  • two document tags namely >xxx< for statements and {xxx} for processes.
  • hard coded visual elements in a data file for statements, inline processes, offline processes and guidance (the elements are st, srinline, sr, and sg, respectively).

Our plan is to generate the guidance visual elements dynamically so we will add guide tags (probably [xxx]) to the document.

In the future we anticipate adding standard letters and here too we shall probably use letters tags (e.g., |xxx!) in the document.

This dynamic generation of visual elements on the charts using tags in the document simplifies considerably the creation of the data file used to set up the visual framework of statements.


Visual appeal

The original contract flowcharts developed by G.P. Jones predated the Internet era. The printed version over two A4+ sized pages for one of our demo charts (for Clause 3/4) is given below.

G.P Jones chart
G.P Jones chart

It can be seen that the printed chart is somewhat difficult to follow and to use.

Our web version is much more compact and understandable and shows clearly the sequence of statements and descision points.


Charts

Our horizontal charts are based on swimlane charts where the various components of contracts clauses or of contract procedures are assigned to the various actors (in our case for FIDIC works contracts generally the contractor, the engineer and the employer and for professional services agreements, the engineer and the client). In principle, swimlanes may be arranged either horizontally or vertically and they can include timelines to show timebars and when tasks start and end.

Horizontal interactive swimlanes3 have been implemented as web applications using the powerful d3.js4 JavaScript library. These applications can run either offline within a user's browser or online by browsing to a web site.

Interactive swimlanes3 based on contract procedures are well-suited to providing an easily visualised and compact overview of the progress of a project that visually distinguishes task sharing and responsibilities for sub-processes in using a FIDIC contract.

We are not aware of a vertical form of the d3.js swimlanes. For vertical swimlanes we use charts based on a collapsable indented tree5. This approach has several major advantages compared with horizontal swimlane charts that use panning and zooming to expose details. They are:

  • Collapsable
    Instead of relying on horizontal panning and zooming, elements can be expanded and collapsed in a verical direction to give an effect that is visually more pleasing and easier to follow.
  • Uses simple coding
    Coding of the charts is much more compact whereby, for example, the chart shown in our demo for FIDIC Works Contract 3rd Edition 1977 is coded as a json file using some 10 elements. A fairly complicated element (namely a statement with guidance nodes and subroutines as described above) for a chart with two swimlanes (both for the contractor) is given by:

    {"collapse1":1,
    "st1":"[43;3.3]:<hr>... [44;3.3]<hr>... [45;3.3]<hr>... [46;3.3]<br>... [47;3.3]",<br>
    "sn1":"43",
    "title1":"Assignment of the contract","title1a":"- shall not assign:","x1":0,"class1":"rectBlueWide",
    "children":[
    {"title1":"... the Contract", "x1":0, "class1":"rectBlueST","x2":310,"class2":"vertBlue"},
    {"title1":"... any part of the Contract", "x1":0,"class1":"rectBlueST","x2":310,"class2":"vertBlue"},
    {"title1":"... any benefit or","title1a": "... any interest", "x1":0,"class1":"rectBlueST","x2":310,"class2":"vertBlue"}]}

To apply the coding we assign a tag to each statement (either clause statement or inline process statement) and to each control and we also introduce this tag into the contract text (e.g., for Clause 1 of the FIDIC Civil Works Contract, 3rd Edition 1977, we have:

CIVIL WORKS3 1.1.a - Employer: <2>'Employer' means the party named in Part II who will employ the Contractor<2> and <3>the legal successors in title to the Employer, but not, except with the consent of the Contractor, any assignee of the Employer<3>.

This coding of the contract text allows us to ensure that the entire contract is coded into statements and subroutines with question signals.


Documentation

There are various types of documenation that can be introduced into a web-based flow chart without disturbing the visual appeal and the understanding. We have, for example:

  • Sample letters

    Sample letters, sometimes called standard letters, for FIDIC contracts are sent between the Employer, the Contractor and the Engineer.

    In preparing the sample letters, we have classified our collection of standard letters according to the letter number for a given sub-clause, i.e., SC13.2(4) corresponding to the fourth letter that relates to Sub-Clause 13.2. We then introduce a link on the relevent statement box (this facility is demonstrated for horizontal proceddures charts but not yet for the vertical clause charts). Using flowing charting with swimlanes and timelines allows the sequencing of the various letters while a contract progresses to be readily understood. Having control signals also allows one to ensure that the set of standard letters is complete since we add the coding for the standard letters into the clause text in the same way as for the statement codes described above.

  • Guidance

    Indroducing annotations giving guidance is straightforward.

  • Other documentation

    One can envisage introducing links to the following:

    • case studies;
    • guidance for particular (sometimes called 'special' conditions);
    • legal decisions;
    • sources of information;
    • upcoming events such as training courses.

The only other information that we shall introduce into charts is guidance for special conditions.


Browsers

Our swimlane charts are currently designed to be viewed with Internet Explorer, Firefox, Chrome or Opera on laptops and desktops. However, they are fully functional on tablets using Safari (iPads) and Chrome (Android tablets). Touch mode for browsers on Windows is being looked into for desktops, laptops and Surface Pro tablets, but use with Internet Explorer on Windows RT Surface tablets is unlikely to be available.

We are still debating whether we should allow charts to be automatically available in an offline version for browsing when a user is not conected to the Internet. Arranging this is straightforward.


Ease of use

In using the horizontal swimlane visualisation approach it was decided to:

  • break the contract up into its main procedures (e..g, procedures for site access, dispute resolution, etc.);
  • display the various procedure charts above a chart of the principal events of a contract as described in the introduction to the FIDIC contracts;
  • have swimlanes in each of the procedure and principal events charts corresponding to the actions taken by the employer, the contractor and the engineer;
  • allow the user to scan each chart so that a sequence of actions and events can be followed;
  • allow the user to load different procedure charts by clinking a link in the principal events chart, a dropdown menu or a search box;
  • ensure that whenever the user is taken to a position in a procedure chart the corresponding position in the principal events chart is loaded, and vice versa.

A main requirement of the sub-division into procedures was that every sample letter, guidance for particuar conditions and clause guidance could be logically associated with a procedure so that the chart provides access in a systematic way to the varous documents.

Swimlanes can obviously be developed with other strategies in mind. For example, it is envisaged that various versions will be developed to focus on particular aspects of contract and risk management.

For the vertical collapsable charts we are in the early days in exploring possibilities. Broadly speaking, the features that are available in horozontal charts will also be available in vertical charts. For contract clause-based charts, we see no need for having a principal chart linked to a more detailed chart (this can be done using the d3.js visualisation library). However, we have yet to explore the implementaion of vertical collapsable charts for procedures. In this case it might be useful to have a vertical principal events chart linked to a detailed but separate procedure chart.


Features

The main elements on the charts are boxes corresponding to actions or statements.

Horizontal procedure charts

In the case of the horizontal procedure charts, these boxes have the following elements:

  • title;
  • pop-up link (click a sub-clause number) giving the relevant text of the corresponding sub-clause in the contract (this link in fact opens a FIDICbot chat window to give the clause text, where FIDICbot's full search functionality can be accessed in a web browser or via messenging platforms at FIDICbot);
  • pop-up link (click a letter number) giving the text to the approporiate sample letter (if any);
  • pop-up link (click a grey circle) giving useful subsiduary information;
  • a link (click a numbered green circle) to a Procedure chart if the actions that follow are displayed on another chart.

There are also graphic flowchart elements for "yes/no" decisions, flowchart connector lines and period intervals that specify time limits.

At the present stage, scanning or "brushing" the charts is in a horizontal as opposed to vertical direction as this seems to be the most pleasing.

The upper "Procedures" chart can be magnified in the horizontal direction by using a mouse wheel on the darker area. This sometimes facilitates selecting the links to the sample letters and the contract sub-clauses.

Vertical clause charts

For vertical clause charts, the box elementts are similar to those for horizontal charts:

  • statment summary;
  • clicking a statement summary lists a statement or series of linked statements and opens a tooltip giving the text of the statement or link statements;
  • small square linking to the text of linked subroutine statements;
  • small circle linking to the text of linked annotations (guidance, particular contitions guidance, standard letters, etc.);
  • links in statement, subroutines and annotations to contract clauses that are displayed in a superimposed ("modal") window (we may change this to display in the FIDICbot as for the horizontal charts in order to provide access to tools to search the contract).

Ultimately, we hope to be able to include links to the procedure charts that incorporate a particular statement or set of statements.


Searching

For the horizontal procedures charts, the main types of search tools, each with with links to the relevant action items on the procedures and principal events, are:

  • search in the texts of the sample letters and contract sub-clauses;
  • dropdown lists of procedures, principal events and sample letters.

We are currently exploring the search options for the vertical clause charts. One imagines that a search in the word in the contract will list the relevant charts. Once one is selected the chart will be displayed at the relevant position in the chart.

The same procedure can be used for guidance, sample letters and other annotation documentation.

Our main difficulty is to see how searches in contract clauses can be linked to procedures.


Access

At this stage, FIDIC Charts are primarily used by the authors of the sample letters collection to manage the collection. However, a limited number of experts are being asked to comment on the viability of the swimlane approach as a contract management tool.

Anyone wishing to explore the tool is asked to contact Peter Boswell at peter@peterboswell.com for a password.


Rights Management

Interactive, offline, in-browser JavaScript-based applications have an enormous potential. However, since they are in-browser, by definition, even with the very latest obfuscation techniques, the source material, in the present case primarily the sample letters, is available to anyone with enough patience and skill to decode the application.

The swimlane application has been shown to work well with encrypted data sources - encrypted json files in this case. This is an important consideration since being able to work with encrypted files means that a non-generic viewer, individualised for each user6, can be supplied to provide some access control.

To restrict access to the sample letters, the only viable solution is to provide the application as an individualised viewer for each user who then browses the date online.

There are also intermediate solutions where for example, access to everything but the text of the sample letters is available offline (via caching in the browser) and unrestricted, but access to the letters requires an online account and an Internet connection. This is the approach that FIDICcharts has adopted.


Developments

Various developments of the basic demonstration two-chart swimlane3 are being developed as demonstrations. For instance:

  • side-by-side procedures charts with a standard principal events chart allowing, for instance:
    • comparison of two contracts (e.g., Construction and Plant);
    • comparison of different editions of the same contract (e.g., the latest - 1999 - 1st Edition of the Construction Contract with the recently published 2nd Edition);
    • modelling risk scenarios;
    • claims management;
    • critical path analysis.
  • ability to annotate charts as a tool to manage a contract (e.g., keep track of letters sent).

The opportunities seem endless.

But before getting carried away it is necessary to ensure that swimlane charting gives a reliable and convenient visualisation of a FIDIC works contract, which is a relatively complex document (for the 2017 editions, typically some 150 pages in length) with many inter-relationships between typically some 200 sub-clauses.


Proviso

The developers realize that the application is at the demonstration stage. The JavaScript code clearly needs refinement and optimisation, although the main elements are already fully workable. The application is touch-friendly for mobiles, but not fully responsive (i.e., it is unsuitable for phones and small tablets, although workable). In fact it is doubtful that the application should be fully responsive since it is likely that both horizontal and the newer and probably more attractive vertical charting will mainly target desktops, laptops and tablets.


Information

If you are interested in exploring the swimlane charts, please contact Peter Boswell. Peter is the former FIDIC General Manager and is now working as a consultant with Bricad Associates, see peterboswell.com.

Bricad Associates Sàrl, is based in Coppet on the outskirts of Geneva, Switzerland (website).

Bricad groups all its management information and user support platforms under Bricad.online.

Horizontal procedure charts will be continually updated while the collection of sample letters is being prepared for publication (the version number is indicated in at the top-right of each chart).

Vertical clause charts are being prepared for the FIDIC Civil Works Contract 3rd Edition 1977 as a pilot. We shall see if it is possible to transfer the approach to the much longer and much more procedural latest (2nd Edition 2017) editions of the the FIDIC Construction, Plant and EPC/Turnkey contracts.

At some stage we aim to chart the FIDIC professional services agreements, especially the all-important Client-Consultant Model Services Agreement.


References

1. FIDIC: fidic.org.

2. FIDIC contract charts: Malconlaw; Malconlaw; Introduction to FIDIC 1999 works contracts; Totterdill, FIDIC User's Guide; Bunni PDF. PDF; Jaeger PDF; FIDIC DBO Contract PDF.

3. d3.js based horizontal swimlane visualisations: Bunkat 2012; Bunkat 2012; Bunkat 2012; Protembla, 2012; Rengel, 2013.

4. d3.js: d3js.org

5. d3.js based vertical collapsable indented trees: Bostock 2018; Zieve 2018; Jamal 2017

6. Monocle e-book reader: Vertica.