Monthly Archives: June 2016

Produce DWGs Like It’s 2016: Teigha For Architecture


In this article, I will introduce you to Teigha, a library that provides an alternative way of handling DWG files and ACA objects. We’ll write a small piece of code that creates a house out of ACA objects.

If you want to handle DWG files and AutoCAD objects programmatically, the only platform options areObjectARX and Teigha. All third-party components and applications that can read and write DWG files use Teigha as a base.

Produce DWGs Like It's 2016: Teigha For Architecture

Accelerate Your DWG Production With Teigha Architecture

Teigha Architecture is a set of libraries that enable you to read, write, and handle objects of the original AutoCAD and its derivatives like ACA. The libraries also provide many auxiliary mechanisms to help you handle AutoCAD objects and rendering devices to render the DWG database.

Teigha’s main features are:

  • Support DWG, DXF, BDXF, DGN file formats
  • Render drawing files using GDI, OpenGL, or DirectX with the ability to select entities.
  • Edit and manipulate CAD data programmatically, including:
  • Explode an entity into a set of simpler entities.
  • Apply a transformation to an entity.
  • Modify arbitrary properties of database objects.
  • Clone a database object.
  • Export to SVG, PDF, DWF, BMP, STL, DAE (Collada).
  • Import DWF/DAE/DGN files into a .dwg database.
  • Support custom objects — members can create custom objects that are usable within any Teigha host application (compatible with .dwg files only).
  • Support ACIS/Parasolid data internally, including rendering (wireframe and shaded) for embedded 3D solids and access to the underlying boundary representation data.
  • Implement custom commands.

Why Should Designers Consider Teigha?

AutoCAD saves its data to .dwg file format. DWG is a proprietary binary file format used for storing two and three-dimensional design data and metadata. DWG is an industrial standard. Thousands and thousands of DWG drawings exist and need to be supported. Besides AutoCAD, there is only one library which can load\save and manipulate objects stored as a DWG file: Teigha.

There are several reasons to use Teigha rather than AutoCAD ObjectARX:

  • Cost: If you develop an application that works with information stored as a .dwg file, you have two options: develop an AutoCAD plugin or develop your application based on Teigha. Developing AutoCAD plugin means that all of your customers have to own an AutoCAD license, which cost a fortune. Teigha pricing is very affordable.
  • Flexibility: Based on Teigha you can develop your own CAD application from scratch designed to fulfill your customer’s certain needs. You are not bound to AutoCAD core and GUI. You can develop your own particular GUI for your CAD application. Or, if you need a CAD-like GUI, you can use one of the Teigha-based cheap CAD applications available on the market ( like BricsCAD, ZWCad ) as a host to your plugin.
  • Many supported platforms: for example, you can build a standalone CAD application for Mobile platforms like IOS and Android, which is very demanded in certain areas.
  • Source code access: Teigha sources are available for founding members. If you need a specific functionality which is not provided or change existing functionality for your needs – you can buy Teigha sources and change anything you need.

Autodesk offers RealDWG – a software library that allows C++ and .NET developers to read and write AutoCAD® software DWG and DXF files. But again, it is much more expensive, has annual fees and provides only load\save functionality for DWG files, while Teigha provides rendering devices and other useful API for building your own CAD application.

Produce DWGs Like It's 2016: Teigha For Architecture

An Alternative to AutoCAD and ObjectARX

For starters, let’s load and render a DWG drawing. We can use the standard sample from Teigha’s distribution package:

Produce DWGs Like It's 2016: Teigha For Architecture

We’ve successfully loaded and rendered the DWG file. (By the way, the picture that you could see in the beginning of this article is the result of rendering a different file.) The standard sample is a windowed C++ application. It allows you to load, view, and edit DWG files without using AutoCAD. I should also mention that the API of AutoCAD objects is almost identical to the API of Teigha objects, so you can easily modify an existing ObjectARX plugin to support Teigha-based applications.

Most alternatives to AutoCAD, such as BricsCAD, ZWCad, and IntelliCAD, use Teigha to handle the DWG format and ACAD objects.

The Peculiarities of AutoCAD Architecture Objects

Now I will introduce you to architectural objects and how to handle them. AutoCAD Architecture handles special high-level objects intended for architectural design: walls, doors, windows, roofs, etc. The objects are viewport dependent, that is, they can be rendered differently depending on the camera direction. Objects are style based. A certain style is assigned to each object. If you change the style, all objects with that style will change. Every object consists of components, and every component has its own visual settings: color, line type, material, and scale. For example, a 3D door may consist of a frame, a door panel, and a sheet of glass. For different view modes, the object is rendered using different geometries, so the number and settings of components are different for different presentations.

Teigha for Architecture (TA)

To handle architectural objects, you can use ACA and its open API that enables you to create plugins. Alternatively, you can use Teigha for Architecture, a library developed by the Open Design Alliance.

Teigha Architecture is a С++ class library that implements all basic primitives of ACA, such as walls, windows, doors, roofs, beams, openings, etc. The library allows you to load these objects from any version of the DWG format and write (convert) to the latest DWG version. TA can render any primitives in different views and configurations. ACA objects interact with each other, so TA also supports ACA’s auxiliary classes and mechanisms, such as anchor, display manager, property sets, relation graph, etc.

Starting with Teigha Architecture API

I’ve already described Teigha’s main features. Let’s take a closer look at Teigha and write our first command, a very simple one. I’ll be using Visual Studio 2005, which is obviously outdated, but the Teigha libraries are multi-platform, and the distribution package includes a solution generator for all Visual Studio versions up to 2015. Depending on your license type, you will have access to the complete code of the whole library, or only to the pre-built binary files and header files.

The set of TA libraries looks like this:

Produce DWGs Like It's 2016: Teigha For Architecture

Basically, these are regular Windows DLL files (you can also build them for other platforms: iOS, Linux, UNIX, etc.). You can find LIB files for them in a separate folder. In addition to TA, we will need the Teigha Core libraries, because TA is an extension on top of the Core objects. Core implements the main mechanisms and objects of the original AutoCAD.

Initializing Тeigha Architecture

To initialize the library, we need a class that performs platform-specific operations on files.

class MyServices : public ExSystemServices, public ExHostAppServices
{
protected:
  ODRX_USING_HEAP_OPERATORS(ExSystemServices);
};

The distribution package includes two ready-made extensions for Windows, ExSystemServices and ExHostAppServices, which we can use in this case. Then we need to initialize the library and the graphics subsystem:

OdStaticRxObject<MyServices> svcs;
odInitialize( &svcs );
odgsInitialize();

_OdStaticRxObject_ adds the _addRef/Release_ logic to an object. The library saves the reference to the MyServices object and uses that object for platform-specific operations.

Let’s initialize the ТА libraries:

  // Loading of all public Teigha Architecture DRX modules.
        // Note that not all calls are necessary for some of them depend on others
        // but here we list all of them.
        //
        // If a program uses TD doesn't modify or create binary files
        // it may not load any of DRX modules on start because they will be loaded automatically. 
        // But if a program modifies or creates binary files then it is highly recommended
        // to load all DRX modules program uses.
        ::odrxDynamicLinker()->loadApp( OD_T("AecBase") );
        ::odrxDynamicLinker()->loadApp( OD_T("AecArchBase") );
        ::odrxDynamicLinker()->loadApp( OD_T("AecArchDACHBase") );
        ::odrxDynamicLinker()->loadApp( OD_T("AecScheduleData") );
        ::odrxDynamicLinker()->loadApp( OD_T("AecSchedule") );
        ::odrxDynamicLinker()->loadApp( OD_T("AecStructureBase") );

AecBase, AecArchBase, etc. are the TX modules (that is, DLL libraries) shown in the screenshot above. They have already been linked using LIB files, but that is not enough. We also need to initialize them as modules. What does it mean? At runtime, the memory contains a dictionary of loaded classes. The dictionary allows you to cast references between different types of TA objects and create instances of TA classes by using a centralized pseudo-constructor mechanism.

For example, when the command ::odrxDynamicLinker()->loadApp( OD_T("AecArchBase") ) is being executed, the function AECArchBase::initApp() will be called in the framework. Basically, initApp() will register all classes of the library in the global dictionary by calling the static function rxInit() for each of them:

…
AECDbSpaceBoundary::rxInit();
AECDbStair::rxInit();
AECDbWall::rxInit();
AECDbZone::rxInit();
…

After that, the object creation mechanism will be available. We will be able to create, for example, a wall by calling _AECDbWallPtr pWall = AECDbWall::CreateAECObject()_. Otherwise, an exception will be thrown if we try to create an object of the TA class.

Let’s create an empty DWG database by calling


OdDbDatabasePtr pDatabase = svcs.createDatabase();

This database is a central object. It is an object database that is saved to and loaded from a DWG file. We are going to add all architectural objects that we create to that database. When we are finished, we will save the database to a DWG file by calling:


OdWrFileBuf cBuffer( strFilename );
pDatabase->writeFile( &cBuffer, OdDb::kDwg, OdDb::kDHL_CURRENT );

Now let’s initialize some more loaded libraries and the display manager:


AECArchDACHBaseDatabase( pDatabase ).Init();
AECScheduleDatabase( pDatabase ).Init();
AECStructureBaseDatabase( pDatabase ).Init();
  
init_display_system( pDatabase );

An AEC dictionary is created in the database. That dictionary contains the default measurement units for length, area, volume, and angle, as well as print settings. Display representations implemented in the modules are registered.

The initialization is complete. If you have skipped some steps, the result will depend on which step you skipped: Objects will not be created or will not be rendered (you will see an empty screen), or there may be other glitches.

So far, the complete code looks as follows:


class MyServices : public ExSystemServices, public ExHostAppServices
{
protected:
  ODRX_USING_HEAP_OPERATORS(ExSystemServices);
};

int wmain(int argc, wchar_t* argv[])
{ 
  // Initialize TD with system services.
  // And create single instance of hostapp services
  // for TD database creation.
  OdStaticRxObject<MyServices> svcs;
  odInitialize( &svcs );
  odgsInitialize();


  // Loading of all public Teigha Architecture DRX modules.
  // Note that not all calls are necessary for some of them depend on others
  // but here we list all of them.
  //
  // If a program uses TD doesn't modify or create binary files
  // it may not load any of DRX modules on start because they will be loaded automatically. 
  // But if a program modifies or creates binary files then it is highly recommended
  // to load all DRX modules program uses.
  ::odrxDynamicLinker()->loadApp( OD_T("AecBase") );
  ::odrxDynamicLinker()->loadApp( OD_T("AecArchBase") );
  ::odrxDynamicLinker()->loadApp( OD_T("AecArchDACHBase") );
  ::odrxDynamicLinker()->loadApp( OD_T("AecScheduleData") );
  ::odrxDynamicLinker()->loadApp( OD_T("AecSchedule") );
  ::odrxDynamicLinker()->loadApp( OD_T("AecStructureBase") );

  // Create empty TD database.
  OdDbDatabasePtr pDatabase = svcs.createDatabase();;
  
  // Initialize database with default Teigha Architecture content.
  AECArchDACHBaseDatabase( pDatabase ).Init();
  AECScheduleDatabase( pDatabase ).Init();
  AECStructureBaseDatabase( pDatabase ).Init();


  init_display_system( pDatabase );

    
  // do something here with TA objects


  // Perform "zoom extents" on model space.
  {
    OdDbViewportTablePtr pVT =
      pDatabase->getViewportTableId().openObject( OdDb::kForRead );
    OdDbViewportTableRecordPtr pV =
      pVT->getActiveViewportId().openObject( OdDb::kForWrite );
    pV->zoomExtents();
  }

  OdWrFileBuf cBuffer( "H:\\TA_test.dwg" );
  pDatabase->writeFile( &cBuffer, OdDb::kDwg, OdDb::kDHL_CURRENT );
  
  odgsUninitialize();
  odUninitialize();

  return 0;
}

I’ve added the “zoom extents” command, so that when we open the created file, we can instantly see the objects added to it and the symmetrical deinitialization of the library. To make things simpler, I removed error checking and the try/catch constructs around the main actions.

Now the program will create an empty DWG file, which we can open and view in AutoCAD.

Handling objects

To show you how to work with the TA classes, I’m going to create a house consisting of a floor/foundation, walls, windows, a door, and a roof. Let’s begin with the walls.

For starters, we’ll add one wall to our drawing. To create the wall, we need to create a style for it first. Let’s write the add_wall_style function:


OdDbObjectId add_wall_style( OdDbDatabasePtr pDatabase )
{
  OdDbObjectId idResult =
    AECDbWallStyle::CreateAECObject( pDatabase, OD_T("Wall Style Created By Teigha(R) Architecture") );

  AECDbWallStylePtr pWallStyle =
    idResult.openObject( OdDb::kForWrite );

  pWallStyle->SetDescription( OD_T("Wall Style Description") );
  pWallStyle->SetDictRecordDescription( OD_T("Dialog caption") );

  pWallStyle->SetWallWidth( 4 );
  pWallStyle->SetWallWidthUsed( true );

  pWallStyle->SetBaseHeight( 110 );
  pWallStyle->SetBaseHeightUsed( true );

  pWallStyle->SetJustification( AECDefs::ewjLeft );
  pWallStyle->SetJustificationUsed( true );

  pWallStyle->SetAutomaticCleanups( true );
  pWallStyle->SetAutomaticCleanupsUsed( true );

  pWallStyle->SetCleanupRadius( 4 );
  pWallStyle->SetCleanupRadiusUsed( true );

  pWallStyle->SetFloorLineOffset( 3 );
  pWallStyle->SetFloorLineOffsetUsed( false );

  pWallStyle->SetRoofLineOffset( -3 );
  pWallStyle->SetRoofLineOffsetUsed( false );

  AECDisplayManager cDM( pDatabase );
  AECDbDispPropsWallModelPtr pOverrideModel =
    AECDbDispPropsWallModel::cast( pWallStyle->OverrideDispProps(
    cDM.UpdateDisplayRepresentation( AECDbDispRepWallModel::desc() ) ).openObject( OdDb::kForWrite ) );
  if ( !pOverrideModel.isNull() )
  {
    pOverrideModel->SetIsDisplayOpeningEndcaps( false );
    pOverrideModel->GetBoundaryCompByIndex( 0 )->SetColor( colorAt( 4 ) );
  }

  AECDbDispPropsWallPtr pOverridePlan =
    AECDbDispPropsWall::cast( pWallStyle->OverrideDispProps(
    cDM.UpdateDisplayRepresentation( AECDbDispRepWallPlan::desc() ) ).openObject( OdDb::kForWrite ) );
  if ( !pOverridePlan.isNull() )
  {
    pOverridePlan->GetBoundaryCompByIndex( 0 )->SetColor( colorAt( 4 ) );
  }

  return( pWallStyle->objectId() );
}

The function creates the AECDbWallStyle object and sets some of its parameters. Then it calls the display manager and changes the colors for the plan display representation (2D top view) and the model display representation (3D view).


AECDisplayManager cDM( pDatabase );
  AECDbDispPropsWallModelPtr pOverrideModel =
    AECDbDispPropsWallModel::cast( pWallStyle->OverrideDispProps(
    cDM.UpdateDisplayRepresentation( AECDbDispRepWallModel::desc() ) ).openObject( OdDb::kForWrite ) );
  if ( !pOverrideModel.isNull() )
  {
    pOverrideModel->SetIsDisplayOpeningEndcaps( false );
    pOverrideModel->GetBoundaryCompByIndex( 0 )->SetColor( colorAt( 2 ) );
  }

In this case, we’ve set the yellow color for the wall in the 3D view. It looks complicated, but there is a reason for that: The display representations and display manager mechanism in ACA work this way. The mechanism is flexible and has many capabilities, but its logic is not obvious and takes some learning on your part.

OdDbObjectId: The Runtime Reference

Database objects reference other database objects using ObjectId objects, and a database object pointer can always be obtained from a valid ObjectId objects. The effect of this mechanism is that database objects do not have to reside in memory unless they are explicitly being examined or modified by the user.

The user must explicitly open an object before reading or writing to it, and should release it when the operation is completed. This functionality allows Teigha to support partial loading of a database, where ObjectId objects exist for all objects in the database, but the actual database objects need not be loaded until they are accessed. It also allows database objects that are not in use to be swapped out of memory, and loaded back in when they are accessed.

If you need to preserve references to objects between program launches, use OdDbHandle.

For example, the add_wall_style function has returned idWallStyle. In this case, the style has just been created explicitly by calling AECDbWallStyle::CreateAECObject(), and idWallStyle contains the pointer to the actual object in the memory. To get write access to the style object, we need to perform this operation:


AECDbWallStylePtr pWallStyle = idResult.openObject( OdDb::kForWrite );

As a result, ‘openObject()’ will return the actual pointer to the object, which we can use.

Instead of the regular С++ pointers, the library uses the OdSmartPtr smart pointers:


typedef OdSmartPtr<AECDbWallStyle> AECDbWallStylePtr

The smart pointer’s destructor will notify the framework if the object has been closed. As a result, the related objects may be recalculated, notifications sent, etc.

Now we can add the wall by this call:


OdDbObjectId idWall1 = add_wall( pDatabase, idWallStyle, OdGePoint2d( 0,     0 ), OdGePoint2d(   0, 110 ) );

The add_wall Listing

OdDbObjectId add_wall( OdDbDatabasePtr pDatabase, const OdDbObjectId& idStyle,
                      const OdGePoint2d& ptStart, const OdGePoint2d& ptEnd, double dBulge = 0 )
{
  AECDbWallPtr pWall =
    AECDbWall::CreateAECObject( pDatabase->getModelSpaceId(), idStyle );

  pWall->Set( ptStart, ptEnd, dBulge );
  pWall->SetDescription( OD_T("A Wall") );

  return( pWall->objectId() );
}

As you can see, add_wall doesn’t do anything special. It simply creates the AECDbWall object with the style that we created earlier. The AECDbWall object is added to the model space of the database. In simple terms, the model space is a special dictionary that contains all objects to be rendered when we render the database.

Then the start point, the end point, and curvature are defined for the wall. Note that a wall doesn’t have to be flat. If you wish, you can make it convex.

If we did everything right, we will get a DWG file with one yellow rectangular wall. I’m using the code sample from the Teigha distribution package to view the file, but it will be rendered in exactly the same way in ACA.

Actually, I’ve manually rotated the camera in the 3D view. By default, you will have the top view.

Now let’s add 4 walls, including one convex wall:


OdDbObjectId idWall1 = add_wall( pDatabase, idWallStyle,
    OdGePoint2d( 0,     0 ), OdGePoint2d(   0, 110 ) );
  OdDbObjectId idWall2 = add_wall( pDatabase, idWallStyle,
    OdGePoint2d( 0,   110 ), OdGePoint2d( 110, 110 ) );
  OdDbObjectId idWall3 = add_wall( pDatabase, idWallStyle,
    OdGePoint2d( 110, 110 ), OdGePoint2d( 110,   0 ) );
  OdDbObjectId idWall4 = add_wall( pDatabase, idWallStyle,
    OdGePoint2d( 110,   0 ), OdGePoint2d(   0,   0 ), -1 );

We’ve got the basic structure of our house:

As you can see, the walls were not simply rendered as separate objects. Instead, smooth junctions were added automatically. It is one of TA’s automatic functions known as “cleanup.”

Adding windows

Now let’s add windows to our house. We can handle windows just like doors: We need to create a style for the windows that we want to add to the drawing, and then add the window objects with that style.


OdDbObjectId idWindowStyle =  add_window_style( pDatabase );

OdDbObjectId add_window_style( OdDbDatabasePtr pDatabase )
{
  OdDbObjectId idWStyle =
    AECDbWindowStyle::CreateAECObject( pDatabase, OD_T("Window Style Created By Teigha(R) Architecture") );

  AECDbWindowStylePtr pWindowStyle = idWStyle.openObject( OdDb::kForWrite );

  pWindowStyle->SetDescription( OD_T("Window Style Description") );
  pWindowStyle->SetDictRecordDescription( OD_T("Dialog caption") );
  pWindowStyle->SetAutoAdjustToWidthOfWall( true );
  pWindowStyle->SetFrameWidth( 2 );
  pWindowStyle->SetFrameDepth( 5 );
  pWindowStyle->SetSashWidth( 2 );
  pWindowStyle->SetSashDepth( 3 );
  pWindowStyle->SetGlassThickness( 1 );
  pWindowStyle->SetWindowType( AECDefs::ewtGlider );
  pWindowStyle->SetWindowShape( AECDefs::esRectangular );

  AECDisplayManager cDM( pDatabase );
  AECDbDispPropsWindowPtr pOverrideModel =
    AECDbDispPropsWindow::cast( pWindowStyle->OverrideDispProps(
    cDM.UpdateDisplayRepresentation( AECDbDispRepWindowModel::desc() ) ).openObject( OdDb::kForWrite ) );
  if ( !pOverrideModel.isNull() )
  {
    pOverrideModel->GetFrameComp()->SetColor( colorAt( 1 ) );
    pOverrideModel->GetSashComp()->SetColor( colorAt( 2 ) );
    pOverrideModel->GetGlassComp()->SetColor( colorAt( 3 ) );
  }

  AECDbDispPropsWindowPtr pOverridePlan =
    AECDbDispPropsWindow::cast( pWindowStyle->OverrideDispProps(
    cDM.UpdateDisplayRepresentation( AECDbDispRepWindowPlan::desc() ) ).openObject( OdDb::kForWrite ) );
  if ( !pOverridePlan.isNull() )
  {
    pOverridePlan->GetFrameComp()->SetColor( colorAt( 1 ) );
    pOverridePlan->GetSashComp()->SetColor( colorAt( 2 ) );
    pOverridePlan->GetGlassComp()->SetColor( colorAt( 3 ) );
  }

  return( pWindowStyle->objectId() );
}

As you can see in the code, the AECDbWindowStyle object is created and added to the database. Then some settings are set for the style (though we could have used the default ones). After that, colors for a few components are redefined for the 2D view and the 3D view. In this case, the components are physical parts of a window: a frame, a sash, and a sheet of glass.

Let’s add a window to the first wall by calling the add_window function:


OdDbObjectId idWindow01 = add_window( pDatabase, idWindowStyle, idWall1, 10, 10 );

// Inserts a window into a database using the specified window style.
// If idWall parameter is not null it also attaches the window to the wall.
// Returns Object ID of newly created window.
OdDbObjectId add_window( OdDbDatabasePtr pDatabase, const OdDbObjectId& idStyle, const OdDbObjectId& idWall,
                        double dOffsetAlongX, double dOffsetAlongZ )
{
  AECDbWindowPtr pWindow = AECDbWindow::CreateAECObject( pDatabase->getModelSpaceId(), idStyle );

  pWindow->SetRise( 10 );
  pWindow->SetWidth( 40 );
  pWindow->SetHeight( 40 );

  pWindow->SetOpenPercent( 60 );
  pWindow->SetMeasureTo( AECDefs::eomtOutsideFrame );
  pWindow->SetLeaf( 10 );

  if ( !idWall.isNull() )
  {
    pWindow->AttachWallAnchor( idWall );

    AECDbAnchorEntToCurvePtr pAnchor = pWindow->GetAnchor().openObject( OdDb::kForWrite );
    pAnchor->GetXParams()->SetOffset( dOffsetAlongX );       
    pAnchor->GetZParams()->SetOffset( dOffsetAlongZ );
  }

  return( pWindow->objectId() );
}

The add_window() function is similar to add_wall(), but there is a difference: It uses the anchor object.

We create the AECDbWindow object and add it to the model space of the database. Then we set some settings for that specific instance of AECDbWindow. After that, we put the window into the wall. A special object derived from AECDbAnchorEntToCurve attaches the window to the wall.

That object contains the offsets along the X, Y, and Z axes from the origin of the coordinate system of the wall to the origin of the coordinate system of the window. When we call AttachWallAnchor(), an instance of that object is created and added to the database. The wall itself doesn’t know if it has any windows. Creating an anchor involves another basic mechanism, the relation graph, which contains relations between objects: Who is attached to whom, who includes whom, and who owns whom. If you modify the wall, the relation graph will be notified that the AECDbWall object has changed. It will check all relations and trigger the updating of the related objects. In this case, AECDbWindow will be updated. For example, if you move the wall, the windows in it will move automatically, because they will be notified by the relation graph. You can get access to the relation graph and request relations for a specific object. Actually, a window knows to which object it is attached, because each window contains a reference to the anchor created.

Let’s take a look at the result:

I’ve changed the color of the walls so that you can see the window more clearly. (The code creates blue walls, I just picked colors while writing this article.) TA contains lots of predefined window styles and types, which you can use through enumeration:


enum WindowType
    {
        ewtPicture          =  1,
        ewtSingleHung       =  2,
        ewtDoubleHung       =  3,
        ewtAwningTransom    =  4,
        ewtDoubleCasement   =  5,
        ewtGlider           =  6,
        ewtHopperTransom    =  7,
        ewtPassThrough      =  8,
        ewtSingleCasement   =  9,
        ewtSingleHopper     = 10,
        ewtSingleAwning     = 11,
        ewtVerticalPivot    = 12,
        ewtHorizontalPivot  = 13,
        ewtUnevenSingleHung = 14,
        ewtUnevenDoubleHung = 15
    };
enum Shape
    {
        esRectangular       =  0,
        esRound             =  1,
        esHalfRound         =  2,
        esQuarterRound      =  3,
        esOval              =  4,
        esArch              =  5,
        esTrapezoid         =  6,
        esGothic            =  7,
        esIsoscelesTriangle =  8,
        esRightTriangle     =  9,
        esPeakPentagon      = 10,
        esOctagon           = 11,
        esHexagon           = 12,
        esCustom            = 13
    };

I’ve selected AECDefs::ewtGlider and AECDefs::esRectangular. As you can see, a lot of other shapes are available, too. By using these and other settings, you can create a very complex window type, with multiple sashes and an internal pattern on the glass sheets. The best thing is that you don’t have to create it piece by piece manually or implement everything programmatically. All you need to do is set a few parameters for the existing object or style.

Actually, all Teigha Architecture objects are pretty complex and have a lot of settings. Thanks to that, Teigha for Architecture provides massive opportunities “out of the box.”

Let’s add windows to all flat walls:


OdDbObjectId idWindow01 = add_window( pDatabase, idWindowStyle, idWall1, 10, 10 );
  OdDbObjectId idWindow02 = add_window( pDatabase, idWindowStyle, idWall1, 60, 10 );
  OdDbObjectId idWindow03 = add_window( pDatabase, idWindowStyle, idWall1, 10, 60 );
  OdDbObjectId idWindow04 = add_window( pDatabase, idWindowStyle, idWall1, 60, 60 );

  OdDbObjectId idWindow05 = add_window( pDatabase, idWindowStyle, idWall2, 10, 10 );
  OdDbObjectId idWindow06 = add_window( pDatabase, idWindowStyle, idWall2, 60, 10 );
  OdDbObjectId idWindow07 = add_window( pDatabase, idWindowStyle, idWall2, 10, 60 );
  OdDbObjectId idWindow08 = add_window( pDatabase, idWindowStyle, idWall2, 60, 60 );

  OdDbObjectId idWindow09 = add_window( pDatabase, idWindowStyle, idWall3, 10, 10 );
  OdDbObjectId idWindow10 = add_window( pDatabase, idWindowStyle, idWall3, 60, 10 );
  OdDbObjectId idWindow11 = add_window( pDatabase, idWindowStyle, idWall3, 10, 60 );
  OdDbObjectId idWindow12 = add_window( pDatabase, idWindowStyle, idWall3, 60, 60 );

I didn’t bother to complete the code, but you can handle each window separately: change its opening percentage, color, etc. If you change the style, the change will be applied to all windows with that style at once.

Adding doors to the drawing

To complete the picture, let’s add a door. First, we’ll create a 2D profile for the door panel (a door leaf with a window hole). Then we’ll create a style with that profile. Finally, we’ll be able to create door objects with that style. Alternatively, we could use the default styles. Just like windows (or any other openings), doors are attached to walls with an anchor. The add_profile_def, add_door_style, and add_door listing.


// Inserts profile definition into a database.
// Returns Object ID of newly created profile definition.
OdDbObjectId add_profile_def( OdDbDatabasePtr pDatabase )
{
  OdDbObjectId idProfDef =
    AECDbProfileDef::CreateAECObject( pDatabase, OD_T("Profile Definition Created By Teigha(R) Architecture") );

  AECDbProfileDefPtr pProfileDefinition = idProfDef.openObject( OdDb::kForWrite );

  AECGe::Profile2D cProfile;
  cProfile.resize( 2 );

  cProfile[ 0 ].appendVertex( OdGePoint2d( 0, 0 ) );
  cProfile[ 0 ].appendVertex( OdGePoint2d( 1, 0 ) );
  cProfile[ 0 ].appendVertex( OdGePoint2d( 1, 1 ) );
  cProfile[ 0 ].appendVertex( OdGePoint2d( 0, 1 ) );
  cProfile[ 0 ].setClosed();

  // Forces the contour to be counter-clockwise.
  // So if the contour is already ccw this call is not needed.
  cProfile[ 0 ].makeCCW();

  cProfile[ 1 ].appendVertex( OdGePoint2d( 0.2, 0.2 ) );
  cProfile[ 1 ].appendVertex( OdGePoint2d( 0.2, 0.8 ) );
  cProfile[ 1 ].appendVertex( OdGePoint2d( 0.8, 0.8 ) );
  cProfile[ 1 ].appendVertex( OdGePoint2d( 0.8, 0.2 ) );
  cProfile[ 1 ].setClosed();

  cProfile[ 1 ].makeCCW( false );

  pProfileDefinition->GetProfile()->Init( cProfile );

  return( pProfileDefinition->objectId() );
}

// Inserts a door style into a database.
// Returns Object ID of newly created door style.
OdDbObjectId add_door_style( OdDbDatabasePtr pDatabase, const OdDbObjectId& idProfile )
{
  OdDbObjectId idDoorStyle =
    AECDbDoorStyle::CreateAECObject( pDatabase, OD_T("Door Style Created By Teigha(R) Architecture") );
  AECDbDoorStylePtr pDoorStyle = idDoorStyle.openObject( OdDb::kForWrite );

  pDoorStyle->SetDescription( OD_T("Door Style Description") );
  pDoorStyle->SetDictRecordDescription( OD_T("Dialog caption") );
  pDoorStyle->SetAutoAdjustToWidthOfWall( true );
  pDoorStyle->SetFrameWidth( 2 );
  pDoorStyle->SetFrameDepth( 5 );
  pDoorStyle->SetStopWidth( 2 );
  pDoorStyle->SetStopDepth( 3 );
  pDoorStyle->SetShapeAndType( AECDefs::esCustom, AECDefs::edtSingle );
  pDoorStyle->SetProfile( idProfile );
  pDoorStyle->SetGlassThickness( 1 );

  AECDisplayManager cDM( pDatabase );
  AECDbDispPropsDoorPtr pOverrideModel =
    AECDbDispPropsDoor::cast( pDoorStyle->OverrideDispProps(
    cDM.UpdateDisplayRepresentation( AECDbDispRepDoorModel::desc() ) ).openObject( OdDb::kForWrite ) );
  if ( !pOverrideModel.isNull() )
  {
    pOverrideModel->GetPanelComp()->SetColor( colorAt( 1 ) );
    pOverrideModel->GetFrameComp()->SetColor( colorAt( 2 ) );
    pOverrideModel->GetStopComp()->SetColor( colorAt( 3 ) );
    pOverrideModel->GetSwingComp()->SetColor( colorAt( 4 ) );
    pOverrideModel->GetGlassComp()->SetColor( colorAt( 5 ) );
  }

  AECDbDispPropsDoorPtr pOverridePlan =
    AECDbDispPropsDoor::cast( pDoorStyle->OverrideDispProps(
    cDM.UpdateDisplayRepresentation( AECDbDispRepDoorPlan::desc() ) ).openObject( OdDb::kForWrite ) );
  if ( !pOverridePlan.isNull() )
  {
    pOverridePlan->GetPanelComp()->SetColor( colorAt( 1 ) );
    pOverridePlan->GetFrameComp()->SetColor( colorAt( 2 ) );
    pOverridePlan->GetStopComp()->SetColor( colorAt( 3 ) );
    pOverridePlan->GetSwingComp()->SetColor( colorAt( 4 ) );
    pOverridePlan->GetDirectionComp()->SetColor( colorAt( 5 ) );
  }

  return( pDoorStyle->objectId() );
}


// Inserts a door into a database using the specified door style.
// If idWall parameter is not null it also attaches the door to the wall.
// Returns Object ID of newly created door.
OdDbObjectId add_door( OdDbDatabasePtr pDatabase, const OdDbObjectId& idStyle, const OdDbObjectId& idWall,
                      double dOffsetAlongX, double dOffsetAlongZ )
{
  AECDbDoorPtr pDoor = AECDbDoor::CreateAECObject( pDatabase->getModelSpaceId(), idStyle );

  pDoor->SetRise( 10 );
  pDoor->SetWidth( 40 );
  pDoor->SetHeight( 50 );

  pDoor->SetOpenPercent( 20 );
  pDoor->SetMeasureTo( AECDefs::eomtOutsideFrame );
  pDoor->SetLeaf( 10 );

  if ( !idWall.isNull() )
  {
    pDoor->AttachWallAnchor( idWall );

    AECDbAnchorEntToCurvePtr pAnchor = pDoor->GetAnchor().openObject( OdDb::kForWrite );
    pAnchor->GetXParams()->SetOffset( dOffsetAlongX );
    pAnchor->GetZParams()->SetOffset( dOffsetAlongZ );
  }

  return( pDoor->objectId() );
}

Let’s add the following code to main:


AECDbWallPtr pWall = idWall4.openObject( OdDb::kForRead );
  double dLength = pWall->GetLength();
  double dOWidth = 40;
  double dL1 = 10;
  double dL3 = dLength - dOWidth - 10;
  double dL2 = dL1 + dOWidth + (dL3 - (dL1 + 2 * dOWidth)) / 2;

  OdDbObjectId idDoor     = add_door   ( pDatabase, idDoorStyle,   idWall4, dL2, 0  );

There is a difference, though: We open a wall with the read access and get its length in order to calculate the offset.

As a result, we’ve put a door in the convex wall:

Let’s also add windows to the convex wall:


OdDbObjectId idWindow13 = add_window ( pDatabase, idWindowStyle, idWall4, dL1, 10 );
  OdDbObjectId idWindow14 = add_window ( pDatabase, idWindowStyle, idWall4, dL3, 10 );
  OdDbObjectId idWindow15 = add_window ( pDatabase, idWindowStyle, idWall4, dL1, 60 );
  OdDbObjectId idWindow16 = add_window ( pDatabase, idWindowStyle, idWall4, dL2, 60 );
  OdDbObjectId idOpening  = add_window ( pDatabase, idWindowStyle, idWall4, dL3, 60 );

The result is a house without any roof or floor:

Let’s write the ‘add_roof()’ function.


void add_roof( OdDbDatabasePtr pDatabase )
{
  AECGe::Profile2D cProfile;
  cProfile.resize( 1 );
  cProfile.front().appendVertex( OdGePoint2d( 0,   0   )    );
  cProfile.front().appendVertex( OdGePoint2d( 0, 110   )    );
  cProfile.front().appendVertex( OdGePoint2d( 110, 110   )    );
  cProfile.front().appendVertex( OdGePoint2d( 110, 0 ), -1   );
  cProfile.front().setClosed();
  cProfile.front().makeCCW();
  
  AECDbRoofPtr pRoof =
    AECDbRoof::CreateAECObject( pDatabase->getModelSpaceId() );

  // Initialize roof profile.
  // By default all edges of Roof Profile have single slope of 45 degrees.
  pRoof->GetProfile()->Init( cProfile );

  pRoof->SetThickness( 2 );

  //// Manually modify Roof Segments.
  AECGeRingSubPtr pRoofLoop = pRoof->GetProfile()->GetRingByIndex( 0 );
  if ( !pRoofLoop.isNull() )
  {
    OdUInt32 i, iSize = pRoofLoop->GetSegmentCount();
    for ( i = 0; i < iSize; i++ )
    {
      AECGeRoofSegmentSubPtr pSeg = pRoofLoop->GetSegments()->GetAt( i );
      pSeg->SetFaceCount(1);
      pSeg->SetFaceHeightByIndex(0, 110);
      pSeg->SetBaseHeight(0);
      pSeg->SetOverhang(10.0);
      pSeg->SetFaceSlopeByIndex(0, OdaPI4);
      pSeg->SetSegmentCount(10);
    }
  }

  pRoof->setColorIndex( 3 );  
}

The roof is created based on a 2D profile whose direction of traversal is counterclockwise. Calling makeCCW()changes the direction of traversal if it was clockwise. It is important to do because the algorithm expects a profile whose direction of traversal is counterclockwise, otherwise it won’t work.

The profile coincides with the central line of the walls. Then we need to set the slope angle for each segment of the profile, the number of faces in the roof, the elevation (Z coordinate) of the top point of each face above the XY plane (SetFaceHeightByIndex), and the overhang. SetSegmentCount() works only with segments that have a curvature. This parameter sets the approximation accuracy, that is, the number of line segments that approximate an arc.

Here’s our roof:

There are lots of roof settings, so you can create a roof of almost any form: a gable roof, a hip roof, a hip-and-valley roof, you name it. Each face is a separate RoofSlab object which you can edit manually.

Adding a floor to the drawing

Now we need to add at least a very basic floor/foundation. To do it, we can use the slab object. Let’s write the add_slab function.

void add_slab( OdDbDatabasePtr pDatabase )
{
  OdDbObjectId idStyle =
    AECDbSlabStyle::GetAECObject( pDatabase, OD_T("Slab Style") );
  if ( idStyle.isNull() )
  {
    idStyle = AECDbSlabStyle::CreateAECObject( pDatabase, OD_T("Slab Style") );
  }

  AECDbSlabStylePtr pStyle =
    idStyle.openObject( OdDb::kForWrite );
  if ( !pStyle.isNull() )
  {
    pStyle->GetComponents()->Clear();

    AECSlabStyleCompPtr pCmp = AECSlabStyleComp::createObject();
    pCmp->SetName( OD_T("Base") );
    pCmp->GetPosition()->GetThickness()->SetUseBaseValue( false );
    pCmp->GetPosition()->GetThickness()->SetBaseValue( 6 );
    pCmp->GetPosition()->GetThicknessOffset()->SetUseBaseValue( false );
    pCmp->GetPosition()->GetThicknessOffset()->SetBaseValue( - 6 );
    pStyle->GetComponents()->Insert( pCmp );
  }

  AECDbSlabPtr pSlab =
    AECDbSlab::CreateAECObject( pDatabase->getModelSpaceId(), idStyle );

  {
    AECGe::Profile2D cBase;
    cBase.resize( 1 );
    cBase.front().appendVertex( OdGePoint2d( -5,   -5   ), 1 );
    cBase.front().appendVertex( OdGePoint2d( 115, -5   ) );
    cBase.front().appendVertex( OdGePoint2d( 115, 115 ) );
    cBase.front().appendVertex( OdGePoint2d( -5,   115 ) );
    cBase.front().setClosed();
    cBase.front().makeCCW();

    pSlab->GetSlabFace()->Init( cBase );
  }

  pSlab->SetThickness( 5 );

  pSlab->SetVerticalOffset( 0 );
  pSlab->SetHorizontalOffset( 0 );

  pSlab->SetPivotPoint( OdGePoint3d::kOrigin );

  AECDisplayManager cDM( pDatabase );
  AECDbDispPropsSlabPtr pOverrideModel =
    AECDbDispPropsSlab::cast( pSlab->OverrideDispProps(
    cDM.UpdateDisplayRepresentation( AECDbDispRepSlabModel::desc() ) ).openObject( OdDb::kForWrite ) );
  if ( !pOverrideModel.isNull() )
  {
    pOverrideModel->GetBoundaryCompByIndex( 0 )->SetColor( colorAt( 1 ) );
    pOverrideModel->GetBaselineComp()->SetColor( colorAt( 4 ) );
    pOverrideModel->GetPivotPointComp()->SetColor( colorAt( 5 ) );
    pOverrideModel->GetFasciaComp()->SetColor( colorAt( 6 ) );
    pOverrideModel->GetSoffitComp()->SetColor( colorAt( 7 ) );
    pOverrideModel->GetShrinkWrapBodyComp()->SetColor( colorAt( 8 ) );
  }

  AECDbDispPropsSlabPlanPtr pOverridePlan =
    AECDbDispPropsSlabPlan::cast( pSlab->OverrideDispProps(
    cDM.UpdateDisplayRepresentation( AECDbDispRepSlabPlan::desc() ) ).openObject( OdDb::kForWrite ) );
  if ( !pOverridePlan.isNull() )
  {
    pOverridePlan->SetIsOverrideCutPlane( false );
    pOverridePlan->GetHatchComp()->SetColor( colorAt( 1 ) );
    pOverridePlan->GetBelowCutPlaneBodyComp()->SetColor( colorAt( 2 ) );
    pOverridePlan->GetAboveCutPlaneBodyComp()->SetColor( colorAt( 3 ) );
    pOverridePlan->GetBelowCutPlaneOutlineComp()->SetColor( colorAt( 4 ) );
    pOverridePlan->GetAboveCutPlaneOutlineComp()->SetColor( colorAt( 5 ) );
  }
}

In this case, we create a new floor style, and then add components to it. A component is a floor piece that contains such parameters as thickness, elevation above the XY plane, name, material, index, etc. A floor can consist of several components with different settings. For example, if they have different elevations above the XY plane, you can use one floor object of that style to render all the floors and ceilings in a multistory building.

Style settings are applied to a specific object that contains the shape of the floor. In this case, we create a slab and initialize its profile with the same contour as the bottom part of the walls, only with a small offset at the edges. Then we use the display manager to redefine the colors of different components of the floor.

At last, we’ve created a house that looks like this:

Just to be sure, let’s try to load the resulting DWG file in Autodesk ACA:

That’s our house loaded in AutoCAD Architecture. It looks even better here, doesn’t it?

Conclusion

Using Teigha, we’ve created an empty database, initialized it for handling architectural objects, created a few commonly-used object types, and successfully saved all of them to a DWG file of the latest format.

Of course, I’ve simplified many things and described them in a cursory manner. But the purpose of this article is to demonstrate the capabilities of Teigha Architecture and give you a general idea of Teigha as an alternative solution for handling DWG files and AutoCAD objects.

This article was written by Aleksey Abramovsky, a Toptal C++ developer.

The Ultimate Introduction To Agile Project Management


The Brief

You’re in charge of delivering your company’s latest and greatest initiative that’s going to change the face of “Widgets International” forever. It’s a software project that’ll engage and enthrall your customers, make your colleague’s lives easier, and make the company millions in revenue. There’s a great deal of anticipation, fervour, excitement, and expectation. You need to get it done as quickly as possible, so your business can start to reap the benefits. The future success of the company depends on you. All eyes are on you. You cannot fail.

Agile project management

At first, you’re thinking to yourself “awesome, I’m up for the challenge. Let’s get this thing done!”. You pause for a moment, step back, and think to yourself “okay, so how do we do this?”. You start to talk to your colleagues and peers. You spend time searching for best practice software development and project management techniques, but the options and approaches are countless. There are acronyms and methodologies aplenty. Notable ones rise to the top. Doubt creeps in. Which one should we use? How can I guarantee success? What if I make the wrong decisions?

When it comes to managing software projects, there’s a heady mix of options supported by a myriad of opinion. Voices from the corners of the room whisper “try doing it this way”, others shout “this is the only way to do it”, and the rest just whimper “don’t manage it at all, just get on with it”. In reality, all those voices speak some truth. But what’s important is working out what’s right for your needs, your team, your business, and your customers.

Setting the Scene

There was a time when software project management sat squarely in one of three camps. There were the heavy frameworks that let you make decisions on how you execute and deliver, while offering a structure to maintain control and governance. There were prescriptive sequential methodologies like waterfall that forced you to plan lengthy projects, understand and commit to all your requirements, design and sign off complex systems, write lots of code, and then test (all before your customer gets to see it for the first time). And finally, the less prescriptive but iterative software development life cycles (SDLC) that encourage rapid prototyping or larger systems to be designed, built, and delivered in incremental steps, each building on top of the other.

Agile software development and Agile project management were born out of the inadequacies of the waterfall and the benefits of the iterative approaches to software delivery. They can trace their roots to the 1950’s, thought leadership in the 70’s, maturity in the 90’s and adoption through the 00’s. In 2001, a group of practitioners and experts created the agile manifesto, aimed at defining 4 values and 12 guiding principles that seek to embody the spirit of Agile software development and to encourage its evolution. And it has definitely evolved.

Now, simply calling something Agile isn’t particularly helpful. The word, even in a software context, means different things to different people or organizations. There are many facets, definitions, implementations, and interpretations. Each body that embraces agile tends to try to give it its own definition.

Simply calling something Agile isn’t particularly helpful.

Suffice to say that Agile software development and project management are a group of related behaviours, frameworks, techniques, and concepts that fundamentally favor the delivery of the right working software as early and as frequently as realistically possible.

I mentioned earlier that Agile, as applied to software development or project management, are different things. In a nutshell, Agile software development takes care of developing great software in a business as usual (BAU) or project context. Agile project management, on the other hand, takes care of the governance and control required to deliver complex projects including but not limited to software.

There are many Agile software development methods available, such as Scrum, Kanban, XP, and Lean Software Development. But just as the game of rugby is about more than the scrum, so is Agile. In isolation, these Agile paradigms do not address the full lifecycle of project management required in complex projects such as governance, resourcing, financial, explicit risk management, and many other important project management concepts. For these, you might want to consider PMI Agile or PRINCE2 Agile – think of it as “Governed Agility”.

Scrum and agile project management

Why Do We Need To Be Agile?

Long ago, we roamed the land to gather food and shelter to survive. They were simple needs, but pretty agile. Some time later, countries and economies grew and prospered on the back of the Industrial Revolution. This was the birth of management and control and the loss of agility. Now we’re in the Information Age or Revolution, where businesses employ knowledge workers. Knowledge workers are you, your partners, your colleagues and peers that endeavor to create great solutions to customer, business, social, economic and world problems. Knowledge workers apply analysis, knowledge, reasoning, understanding, expertise, and skills to often loosely defined and changing needs. These businesses and workers need methods and techniques that cannot be met by old Industrial Age processes and procedures. Agile supports interactions.

Virtually no software project can confidently set out at the beginning and know all that it needs in order to deliver valuable working software without change. Change presents both opportunities and risks to the success of a project. Unmanaged opportunities can mean the difference between a great company and an awesome company. Unmanaged risk spells disaster and ruin. Agile manages change.

Adopting agile allows you to be responsive to changing or new requirements. It empowers development teams to be the experts and make decisions supported by an engaged, trusting, and informed business. It enables you to deliver to customers what they really want. Ultimately, it puts you and your organization in control of delivering high quality valuable software that delivers on customer need and expectations whilst extracting a return on your investment dollars as early as possible. Agile creates value.

There is a cost to adopting agile. It doesn’t come for free. Transforming to an agile approach for software delivery can be a hard path to follow. However, if you internalize the agile philosophy, tread carefully, engage the right team with the right attitude, break things down, make it achievable and realistic and respond to feedback, you will reap rewards. Agile emphasizes collaboration.

The following lists some benefits you can expect:

  • Speed to market
  • Earlier revenue generation
  • Regular delivery of real value
  • Protection for your investment
  • Data, data, data
  • Better product quality
  • Manageable expectations
  • Greater customer satisfaction
  • Higher performing teams
  • Improved visibility on progress
  • Predictability, transparency, and confidence
  • Manageable risk

“Success is not final, failure is not fatal: it is the courage to continue that counts.”

Winston Churchill may never have actually said this, but I think it’s a pretty good summation of Agile. We know Agile is the best foot forward for most projects. It encourages you to strive for success, but we always iterate and keep building on it. Agile will encourage you to fail, but fail early and move on. Having the courage to continue and to build the right solution based on insight informed by your customer is what brings the reward.

The thing to keep in mind is you can tailor Agile to your needs. Use the method and governance that is right for your business. Wherever you start, be true to the content, context, and spirit of the method you use – keep it vanilla. If you’re just starting out – Learn. If you’ve been doing it for a while – Understand. If you’re becoming awesome – Apply. Finally, if your business and your projects are complex and interdependent – Govern. Over time, you and your teams will figure out what works best for your business.

Feasibility

So now you’re thinking “okay, I get it. How do I start? Where do I start?”. Well, with all good things, we start at the beginning. And with Agile, it’s by asking yourself “What business value do I want to deliver?”. After all, that’s why we undertake projects, to generate business value. In order to establish if the project is worth undertaking to derive the business value, you need to understand whether it is feasible.

Vision

Is your project projected to increase revenue, enter a new market, acquire more customers, improve customer perception, or make life easier for a given problem you’ve identified? With this in mind, you can state your “Vision”.

  • Your vision may come from different sources – your own bold startup to fix a common problem, business management strategy, your CEO’s pet project, a specific product team, or even your customer’s needs.
  • Try to take a step back from your own shoes and “see” what the future looks like with your new product or service in the hands of your customers.
  • Engage your stakeholders – the CEO, product guy, and customers. Workshop it, don’t attempt this in isolation. Challenge assumptions and validate arguments.
  • Write it down, keep it short. Focus on the business value.
  • Refine it until you all agree the vision resonates with everybody and meets a common interpretation that states where you’re heading.
  • Your vision, if valid, rarely changes. How you get there most certainly will.

People don’t buy what you do, or how you do it. They buy the “why” you do it. This is what creates the emotional connection between your business and your customers. The vision will help illustrate this.

Is it feasible?

Feasibility comes in at least a couple of shades. Typically, you’ll want to understand if your vision of a brighter future for your business and customers is both technically feasible and that it’s feasible for your business to make it happen.

  • If your vision is to make travel to anywhere across the world in under an hour, you may have a problem with the technical feasibility. Since science, physics, and technology haven’t quite caught up with that dream yet, your technical solution may not be viable in anything other than theory. In addition, if your solution was new, this would go well beyond the idea of a Minimal Viable Product (MVP).
  • To test the technical feasibility of your product, consider either exploring it further in a Discovery prototype project or by running a spike in the early stages of the project. You’ll know which method to use by thinking about the scale or complexity of the solution you have in mind.

    “Some of the best knowledge my teams have gained in understanding technical feasibility have come from performing a spike. And often, it’s the simplest solution that wins out!”

  • The second shade of feasibility to consider is whether you, your team or business has the skills and motivation to make it work. Using an example, if you’re great at baking cakes at home for your kids birthday, that’s sweet. But if you want to turn this into a business selling the finest cakes to the world, you need to understand if you can make it scale, handle the business as well as the production, manage distribution and fulfillment, and take care of customer service.
  • This type of vision might be achievable in the long run. But for now, possibly not. So scale it back, think small, take a small chunk that looks realistic and concentrate on delivering the best but smaller aspiration you can. If that manages to engage and delight your customers, get them coming back for more and telling their friends, then scale it up from there using your customer feedback as your guide and compass.
  • Also, you need to know if your project is feasible in terms of budget and timeframe. Can your business afford to deliver this project ? Is the timeframe achievable? Time and money are two of the three constraints in an Agile project that are fixed. We aim to deliver within a given fixed time and within a given fixed budget.
  • The quality of a product refers to the end product that your customers use and the engineering practices your team uses to deliver great, robust, and reliable software. Quality is also something we don’t short change on. Quality criteria, on the other hand, can change. If you’re not setting out to build a Ferrari, the product may not have a high quality perception. If you’re not building space rockets, then the tolerances attained in production terms may be much higher. Set the appropriate tone and expectation early on.

So now you’ve confirmed your dream is more than chocolate fancy, set about testing your assumptions, and proving to people that this endeavor is worth investing in.

Justification

Now depending on your circumstances, justification will come in different forms. But essentially, you want to prove that this project will satisfy customer success criteria, has a chance of success, will deliver value, and is affordable.

  • State your assumptions based on your customer need, then validate them. The Lean Startup gives great guidance on identifying and proving that your product is needed by your customers and will create value.
  • Write, test, and validate your business plan. Now this looks nothing like the ones your bank or Business and Finance major told you to produce. Don’t use them, they will be out of date before the ink is dry. Instead, check out the Business Model Canvas. This is essentially a short form business plan that keeps your focus on your value proposition, your customers, revenue, and costs. Use it to validate if you have a business that will work.

    “I ignored this advice once and spent a long time writing a lengthy traditional 50 page business plan. It got me nowhere. All the assumptions I had made were unfounded, and all the projections I made couldn’t be validated. It was a painful and expensive experience that taught me to never do it again.”

  • If you’re in a mature business with portfolios of projects being delivered in a complex environment, then financial modeling may be necessary. If you must, do this only after you’ve proven the above.
  • Once you’ve built your MVP, there may be a case for creating a more traditional business plan. For example, if you have to go for funding or selection within your company’s portfolio of competing projects and resources. But this will be a business plan based on and informed by the tools used above. It will be lighter too.
  • In any case, use these tools as living, breathing artifacts. Use them as your guide and bellwether. They are never static. Refer to them and revise them as your project or business evolves.

Once you have your justification and all your stakeholders are onboard, you’ll be on fire.

The Feasibility phase is typically performed once in the life of your project. You may find you revisit the vision and feasibility of the project, especially if your data, customers, market or business indicate so. At the very least, they will be your guiding lights throughout.

Initiation

Awesome. The decision has been made, the project has the green light and you’re ready to build. Well, nearly. I know you’re thinking, “c’mon already, really? If we don’t do this now we never will. Let’s get this show on the road!”. But consider this – Agile is nothing if not about delivering value early and often whilst delighting your customers along the way. Taking some time to figure out the best way to deliver your project is the best laid foundation for success.

The Team

In sport, by thinking about your favorite team game you’ll be able to recognise key roles that enable the team to perform as they do. Traditionally you’ll find a manager, a captain, and the rest of the squad. Outside of that, you’ll find coaches, physios, nutritionists, and an assortment of supporting staff. But if we look at the game of rugby, there’s a team within a team. The players that make up the scrum. This pack is made up of designated players whose job it is to win the ball back and continue play. When a scrum is in play, the players from each side then work, with no leader, as a single unit as collaboratively, communicatively, and efficiently as possible to get the ball back in possession. It is the game of rugby that inspired Jeff Sutherland to name his software development methodology, Scrum.

  • Scrum is not the only software development method in the Agile playbook. But it is the one that best describes the Agile concept and behaviors of working as a team, motivating individuals, creating trusting relationships, self-organization, servant-leadership, communication, transparency, and collaboration.
  • Your team will be formed largely by the circumstances you find yourself in. You may have developersavailable to you, some, none, or all of them may be familiar with Agile to varying degrees. You may want to hire a new team or partner with a 3rd party.
  • Other roles will be required too, but we’ll discuss those later.
  • It has been said that if your form your development team, then you’ve chosen your technology. As depending on where you bring your team together from, they’ll come with certain skill sets. So, think carefully how you form your development team and whether you need to perform a technical evaluation before you get to this point in your journey.
  • This brings us to cross functional teams. Teams work best when they work together, when individuals pitch in to get the job done regardless of their “title”. Try to build a team that is self sufficient and individuals that take on more than one role.
  • Build an environment, culture, and relationship center. A place where the team can deliver, unencumbered by constraints or restrictions. Give the team the tools, people, resources, and space to be effective and performant.
  • Keep team sizes to no more than 7 or 8. If you have a need for many more developers, break the teams down. Each team might then be responsible for a given functional area. If you you have multiple teams in multiple locations, consider holding a Scrum of Scrums. And where these are numerous in complex environments, use Agile project management.
  • Ensure that the team, business, stakeholders, and even customers have access to each other. Ensure they communicate and collaborate, and remove anything that gets in the way of progress. Daily communication is the best cure for project ailments. When people speak, they get stuff done.

There are many ways a team can be put together to deliver software.

Project Brief

In Feasibility, you figured out the “why” of your project and either built your confidence to forge ahead with your startup or got backing to proceed. The project brief is the living document that brings together the “why” with the “what” and “when” and “who”. It’s living, because as you progress from hence forward your knowledge, understanding, and path may change. To leave this document once written and never to return to it, just consign your thoughts to a point in time. In an Agile world, your point in time reference may change weekly or even daily early on, so it’s important to keep this fresh.

  • A great tool for encapsulating and maintaining your project brief is something that Jonathan Rasmusson calls the “Inception Deck” in his book “The Agile Samurai”. Here you’ll find great advice on ensuring that everybody that is interested in, affected by, or involved with your project is on the same page.
  • The greatest enemy to delivering projects is in having an unclear, inconsistent, or just plain different understanding of what the project is and what “requirements” are to be satisfied. If even one important stakeholder has a different understanding or view of what you’re doing, the consequences can be substantial.
  • A good project brief communicates:
    1. A common and agreed expectation between stakeholders and team members.
    2. An understanding of the project, with the same understanding across all parties.
    3. The goal, vision, objective, scope, and project context.
  • You’ll have a lot of good information for the brief gathered from Feasibility. The project brief will help you define and find the answers to searching questions. It will bring together stakeholders, your raison d’etre, high level scope, risks, target solution, budget, timeline, expectations, and your priorities.

“A colleague stopped me in a corridor once and asked me where he could get the project brief for the project. I quipped ‘We don’t need a brief, we’re Agile’. He looked confused, as if he was questioning my sanity or authority. He was right to do so.”

Before you proceed, ensure you’ve got everybody on the same page, workshop it, ask the difficult questions, and nail it somewhere where people can stop, read it, comment on it, and help revise it.

Culture and Ways of Working

You know the way your business works and its culture, the way it likes to get stuff done. Agile, by its very nature, may challenge some of these ways of working that your business has cultivated over the years. Don’t expect Agile to be implemented and for everybody to lovingly adopt it from the outset. Some people may find it confusing and view it only with dread and fear. Some people may openly refuse to engage in it. These are challenges and perceptions you must overcome. But in your early days, don’t go around waving the Agile stick beating anyone that won’t listen with it. That won’t build trust, adoption, or engagement.

“I was a fan of waving big proverbial sticks once, and it earned me a lot of negative press. I turned it around, but not before suffering considerable pain first.”

As you set out on your path of adoption, tread carefully, respectfully, and with empathy. If you’re in a creaking old traditional business, perhaps it won’t be the best approach to get the whole business aligned. Start small and incrementally earn respect and recognition. Start with your team only. Once you start delivering quicker software with better quality than ever before, people will start to notice and will want to come play your game. When they do, offer them the ball, take them out for a coffee, and ease them into your new world. Help them.

With your team, now that they know what the project is about and your plans for Agile adoption agreed, let the team decide how they wish to behave and operate as a team.

  • Guide your team to identify the Agile concepts, techniques, behaviors, and frameworks that you feel fits your collective needs.
  • Take requests from your team members as to what requirements they have to help them perform as best they can. Some of these requests you’ll be able to resolve immediately. Others, you may need to get budget or outside help. Do what you can to make it happen.
  • These are your first steps to becoming a true servant-leader.
  • Consider organizing some appropriate training in the concepts and techniques your team are choosing to adopt. This is the best way to ensure all of your team, even stakeholders, are on the same page and get the same message. Work with a supplier organization that can tailor their offering to your needs.
  • Be prudent. Nobody will be an Agile ninja after a few days in a workshop learning how to become Agile. Your path will be long. The word “become” is quite defining. Only when you truly embrace Agile will you see its value. It should excite you. If it excites you, then go excite others too.
  • Now that your team has agreed the concepts and techniques, had their wishes fulfilled and in Agile training, turn your team’s attention to themselves and what they expect from you, the business, and each other.
  • Define some Ways of Working (WoW) within and by the team helps build trust, relationship, and expectations. The WoW is no War and Peace. It should be short and to the point, between 7 and 10 bullet pointed sentences. These sentences state clearly how people behave, communicate, collaborate, support, deliver, and perform together. It should also state what the team expect from the business.

  • Agile is as much a mindset as it is guiding principles and concepts. It helps you develop in the way you behave, think, negotiate, interact, communicate, perform, and improve. It relies on motivated individuals supporting each other to reach a common aim, together as one. There is an African proverb:
If you want to go quickly, go alone. If you want to go far, go together.

By now your team should be super excited, energized and motivated. Now engage them further with your backlog of User Stories.

Backlog

Have no doubt in your mind that there’s uncertainty involved in your project. You can’t possibly know exactly what it will take to build the right product for your customers so early in its life. You cannot gaze wistfully into a crystal ball and predict the future.

The “backlog” or “product backlog” is where your requirements live. Agile favors the writing of short pithy statements that capture the essence of a “requirement”. The backlog is simply a long list of entries, each entry defining a single, discrete “requirement” as a User Story. And from now on, we’ll be using the word User Story, and not “requirement”. You’re probably asking “why?”. That’s a good question. For life eternal, stating the features or facets needed in a software project by a customer, have always been referred to as a “requirement” (ah, i used it again! Last time. Promise) That word has an interpretation that has no value in Agile. The Oxford dictionary defines it as:

“A thing that is needed or wanted.” Or, “A thing that is compulsory; a necessary condition”.

And unfortunately, if we set out defining what our solution should be, stating that things are “compulsory”, we will end up in trouble. It’s too easy to say that all these User Stories are compulsory. If we take that view, we run the risk of running over schedule and over budget in the attempt to deliver all of a given scope. It’s not a problem to say that, for this product these stories are needed for the solution to be viable, we just want to avoid the interpretation of that particular word.

  • Always write stories from the perspective of a persona. A persona represents a user or stakeholder of the solution. It’s a good idea to develop these persona before you start a backlog.
  • At this stage, only write short simple statements that basically suggest a reminder to have a deeper conversation about the User Story when the time is right.
  • Real people think in terms of tasks that they need to get done to achieve a goal. Write your stories from the persona perspective and in terms of what they need to get done.
  • You don’t need to write the full backlog, just write as much as you can imagine your customers will need for your product to be viable.
  • You’ll discover later on through the life of the product that User Stories will change, become more or less important, or can be deleted completely. Releasing often, getting feedback, and assessing what’s a priority will inform this behavior.
  • Don’t write stories in isolation. Engage your team, stakeholders, even your customers. Stories can be updated at any time in the life of a project, but should avoid being changed once development work has started on them.
  • Some of your stories may be considered as “Epics”. These are large stories that cover a lot, and will be broken down closer to the time of delivery into smaller stories.
  • Consider using the INVEST model, a checklist for validating the quality of a good User Story.
  • Anybody can add a story to the backlog. It should be placed at the bottom, or in a specially created “Parking Lot”. This added story serves as a prompt to discuss with the team and the business. If the business and team support it, it can then be estimated and prioritized
  • You may also consider those parts of the system that are most risky. If you have a User Story or feature that is complex, new, or technically unknown, prioritize these to the top of you backlog. This way you won’t be attempting to deliver the challenging and critical parts of your product just weeks before your first release.

Once you have a backlog that fulfills your needs, you can estimate the stories in it, rank them in order of priority, and build a release plan.

Hi Level Estimation and Prioritization

Hi Level Estimation is the process of sizing your backlog. How “big” is the project, and what value does it deliver? Prioritization is the process of deciding which stories are most important to you, the viability of the product, and the interests of your customers. We want to deliver the highest value items earliest to deliver the most value to the business, get feedback from the customer, and to not sweat the small stuff. The output will be an ordered backlog that is ranked in priority and sized.

  • Stories at the top are considered most valuable. We want to deliver the most valuable items as early as possible.
  • There are many techniques for sizing and estimating, but at this point you just want to get a good indicative feel of the size of a story.
    • Use t-shirt sizes, relative sizing, ideal days, or story points.
  • You won’t have all the available information at this point either, and that’s okay. Just run with it.
  • Engage your business stakeholders or product manager if you have one, and the team that will be doing the work.
  • We want those that will be designing, developing, and testing the work to size it, because the best people to estimate are the experts.
  • The team may start to break stories down into smaller parts. If this happens, write stories that are more granular but discrete.
  • The team may also start to rank some stories, as naturally some things have to get delivered before others to support the technology or a given user journey.
  • Between you and the team, you may also start to find holes in the backlog that need to be filled. Just fill those holes with new stories and estimate and prioritize as appropriate.
  • Prioritization is most easily performed using a MoSCoW analysis. MoSCoW is a simple technique that helps you decide which stories are “must haves” for your product to be successful.
  • You may do a prioritization pass before estimation begins. However, the sizing of certain elements may also determine a decision on priority and real business value. So play estimation and prioritization off of each other, but don’t squabble over it!
  • No two stories can be as important as the other. The story at rank 1 is more important or valuable than the story at rank 2.
  • A great way to demonstrate the importance or value of a story is it to add a monetary value to it. If for example, story A is thought to bring in $5000 of extra revenue, and story B might attract $100, then story A is more valuable. Equally, if story C saves the business more than story D, story C is more valuable.
  • Once you’ve sized your backlog, you’ll be left with a number. When we come to release planning, that number will help us understand how much can be delivered by our team within a given timeframe.

Remember that you don’t need to know all your user stories up front. Also, remember that it’s not necessary to deliver all of your stories before a customer sees your product. You want to remain Agile – and that means only creating what you need to when you need to, wasting as little as possible, and responding to changes in customer needs and market conditions. A roadmap will help you lay out your product and plan your objectives for the next 3, 6, 9, and 12 months.

Roadmap and Storymaps

A roadmap is exactly as it sounds, it offers the same as a roadmap of a country. It details the relative position of cities (or in your case, features) to each other and the routes that can be taken to get from city A to city B, or feature X and feature Z. It doesn’t tell you which route you should take, or how you should get there. It doesn’t tell you which mode of transport to use, but it might illustrate options to take the Highway or the train.

In a city, there are many roads, buildings, parks, services, and facilities. All features of a city. This is also true of the roadmap for your product. At this level, your roadmap shows major goals or milestones to be achieved. A goal is a logical grouping of themes, features, and User Stories rolled up in a consumable view that demonstrates tangible value. The roadmap of a software product shares this view and communicates your intent. It doesn’t necessarily show you how or when features will be delivered, only the relative value of the goals and features to you and your business.

One great way to demonstrate a roadmap is to generate a story map. This tool indicates customer valued prioritization. It lays out the backbone, or essential building blocks of your product. The walking skeleton hangs off the backbone and illustrates the features that make it a MVP. All the other features are what add further value and importance to the system. The story map lays features in relative position to each other and is an awesome visual tool.

It’s worth noting that after carrying out a story mapping exercise, your backlog may need to be refined. This will be apparent where stories have been split into multiple stories, identified as redundant, newly created, or as a higher or lower priority than previously thought. The story map is another artifact that is continually revisited and revised.

The Initiation phase is typically performed once in the life of your project. However, many of the tools and documents you created will be revisited and revised throughout the project.

Release Planning

“At last”, I hear you cry, “finally some planning”. Well, you have essentially been planning all through the Feasibility and Initiation stages, we just didn’t call it as such. This is evidence of iterative or adaptive planning – the art of only planning enough to achieve your immediate and most valuable goals. We’ll see later more about adaptive planning, but for now release planning is our focus.

Your release plan may well be determined by external events. Perhaps there is a trade show you want to demonstrate your app at, or your customers will get most benefit using your app on the run up to Christmas. These are timeline events that your goals may be aligned with. You would most likely plan to deliver user stories or features that make the most sense to facilitate these events. If there are no external dates that you need to consider, then you can just go with feature prioritization and delivering earliest what makes most sense and delivers the most value to your customers.

  • If you created a story map in Initiation, this will help guide your release plan. Use it to identify your MVP, the minimum feature set that will get your product in the hands of your customers, start earning revenue, get feedback, and acquire more customers.
  • The story map will help you carve out future releases too. But keep in mind that as you learn, get feedback, inspect and adapt, future releases may change. So don’t plan in great detail.
  • You may have from 2 – 4 releases in a 12 month period. Don’t do less because your first release is your MVP and gets your foot in your door, after which you’ll want to iterate and release more features and fix bugs in a regular cycle. Don’t do more unless you’re performing well and have plenty of Agile techniques and tools in place to manage continuous delivery.
  • Each release is a timebox which is broken down into smaller iterations. An iteration is a timebox. The timebox is one of the most important control measures in Agile.
  • To size your release:
    • Divide your release timebox by 2. This will give you how many iterations you have. So if you have a release of 12 weeks, you get 6 two week iterations.
    • Then remove two iterations – you’ll reserve one for a “Sprint 0” iteration and another for a “Release Iteration”. This leaves you with 4 development iterations.
    • Work with your team and product owner to fill each iteration with stories, starting from the top of the backlog and working down. When the team thinks they’ve filled an iteration with enough stories they can realistically achieve based on their capacity in the 2 week time frame, repeat for the next iteration(s). Use the release plan and story map to guide what goes into each iteration.
    • Do not plan the next release yet. You’ll do that as you near the end of the current release.
    • Take the user stories from each of your iterations and add up the story sizes. So if your iteration 1 has 25 story points, but iterations 2, 3, and 4 have 10, 45, and 65 points respectively, you will need to refactor. Target an equal number of story points in each iteration. This becomes your anticipated velocity – the amount of valuable “stuff” completed for each iteration.
  • The team may not have worked together before. They are almost certainly working on a new problem or product. They will not perform at their best from day one. For this reason, your velocity may be volatile in the first few sprints. But as the team settles down, it should stabilize. Use this data to refactor your release planning which in turn helps you plan your product with a known velocity and confidence.
  • If necessary, break stories into smaller chunks and resize.
  • Your release plan, especially early in the life of a project and a new team, is only ever a guide. Do not treat it as a commitment or guarantee that all or these exact stories will get delivered as planned. As your team matures, work gets done and trust and confidence builds, so will the accuracy of your plans.
  • Never force your team to “commit” to more than they are comfortable with. Trust their judgement and their expertise.
  • Future release planning exercises will be simpler, because you’ll take the release size, multiply the number of iterations by your team’s velocity, and fill the release plan with the stories that add up to velocity x number of iterations.

Consider this as an example. If you go to a restaurant to eat, you wouldn’t go ahead and order all the items on the menu and expect to eat it all in one sitting. You’d never be able to eat it all, you might not afford the cost, you’ll be sick of food, and the restaurant may close whilst you’re eating the 5th of 19 courses! You may not leave a happy customer, the restaurant may not find you to be a great customer, and the experience will be bad all round. More likely, if you love the restaurant, it’ll be because you enjoyed a lovely meal there once. You’ll decide to go back and enjoy a different meal. You’ll tell your friends, you’ll go there often. The moral of the story is:

  • Plan your releases in small chunks.
  • Consider your capacity.
  • Don’t take on more than you can realistically achieve.
  • Revisit the plan often to see what you can change and improve.
  • Plan, Execute, Inspect, Learn, Adapt – Repeat.

Release planning takes place often in a software project. Each new release requires a release plan. The release plan can also be refactored at any time during a project. Just take care to not overdo it and fall into zombified planning psychosis. At the end of release planning, you’ll want to prepare for the first iteration, which is where we’re happily going next!

Product Iterations

Your team is in place, they’re motivated, you have an engaged business, your initial planning is done – you’re now ready to build your dreams.

We’ve talked earlier about some of the tools, techniques, and concepts that Agile subscribes to. There are many resources already available that do a great job at laying the foundations for delivering an Agile software project. Pick one, keep it vanilla, and grow into your Agile journey. To help shorten the trauma in deciding the right Agile software development methodology to start with, I’d recommend Scrum. And only Scrum. The temptation will be there to use elements of other methodologies. Don’t do it yet. Save that kind of change until you have lived and breathed Scrum for 6 or 12 months. Then, if either you’ve determined it alone does not work for you or you want to mature as a team, steadily introduce new methods, techniques, or frameworks.

I choose Scrum as the recommended approach for new team’s adopting Agile because it has all the basics built in. It’s very popular and has many good quality communities and resources online, in books, or in the training room. It will serve you well, even for the smallest of teams. The rest of this post is dedicated to discussing some important aspects of software delivery that you, your team, and stakeholders should always keep in mind.

Adaptive Planning

Planning in an Agile project is an ongoing process. We do some initial planning up front, just enough to understand what we know at a given point. Our initial plans will be loosely defined and flawed. And then we iterate our planning, adapting to new information, planning in greater detail just before we enter into delivery, responding to changing scope. This is one way of minimizing waste – only putting effort into planning when we need to.

  • The team and the business, or its informed and authorized representative such as a product manager, actively plan together. The team because they are the experts that will deliver, the product manager because he is the expert who can guide the needs of the business.
  • Estimates for user stories will be less accurate the further out they are from being developed. For example, epics will attract high level estimates that will be based on a lot of unknowns. Well defined granular user stories that are estimated just before a sprint starts will be much more accurate.
  • There are many estimation “scales” you can use. Use the technique that feels most right for your team and the right stage of planning – wide band delphi, planning poker, ideal time, relative sizing, story points, or t-shirt sizes.

  • When sizing a story, one size really does fit all. All stories should be sized using the same technique and encompass all elements such as design, development, testing, refactoring. When you come to do iteration planning for a sprint, certain tasks can be created which all contribute to the completion of the story.
  • Always factor risk, unknowns, outside influences, your team’s capacity, and ever improving velocity in planning.
  • If user stories that were taken into a sprint were not completed, we do not extend the timebox. These unfinished or unstarted items are put back to the top of the backlog and taken into the next sprint.
  • Always plan to deliver the least amount required to achieve a given goal. Identify techniques to prune features. Reduce waste, find the real value that can be realistically delivered with your time constrained resources.

Story Creation

Stories get elaborated upon when you need them. You don’t need full story explanations for features that are 6 months away from being delivered. Writing them at the beginning may be wasted effort, when that need disappears from scope. Write your stories at most 2 iterations before they are needed. Reducing that timeframe to 1 sprint is preferable.

Let’s take your time in Sprint 0 to set the scene. In two weeks you’ll start development. It’s now time to take enough of the stories from the top of the backlog that could potentially get delivered on sprint 1. You might take 10 or 15 percent more if you’re unsure on your velocity. These one liners can now be expanded into truly valuable documents with scenarios, acceptance criteria, and wireframes. If the wireframes haven’t been created yet, now’s the time to do so. You might find as you review these candidate stories that they need to be broken down. Perhaps they were Epics that couldn’t possibly be completed in a sprint. If you break stories down, re-estimate them with the team.

A good story follows the following rules: – Written in a common format, e.g. AS A I WANT SO THAT . – Includes acceptance criteria that the story must meet to be considered acceptable to the business for sign off. – Uses language that the business and your customers understand. – Follows the INVEST model. – Includes all supporting documents to inform the developer, designer and tester: wireframes, technical design overview, other assets. – Meets your standard Definition of Done criteria.

Sprinting

Whether you call it a sprint, an iteration or a timebox, each incremental delivery of your Agile project is time constrained. The timebox doesn’t shorten and it doesn’t lengthen. Focus on 2 week iterations at the beginning. You might find that 1, 3 or 4 weeks suits your business model better. Once you choose a length, don’t change it. You want to maintain a regular cadence, or a sustainable pace. This means the team and business focus delivering regular software without mad dash overtime being employed to get the job done and releasing potentially shippable increments every two weeks.

  • Working in small increments has a huge benefit. It means you’re only focusing on the immediate future of delivery; and with new input, feedback and learning, you can respond to change within a short iterative cycle.
  • At the beginning of a release, perform a sprint 0. This lets the team, the business, and your project release get geared up and sets the mindset for successful delivery. Draw out the base technical framework and architecture that will support the foundation for the release. Setup environments, accounts, and tools. Perform spikes to understand difficult or unknown problems. Elaborate your user stories in readiness for sprint 1. Sprint 0 is about getting prepared.
  • During a release, keep refining the backlog. As you understand more or learn something new, your priorities may change, new requirements may unfold, and what you previously thought was a great feature may get removed entirely.
  • Don’t start work that has no chance of completing within a sprint. If it can’t, break it down into smaller chunks. And don’t start new work when previously started work has not been completed. You create no value by starting lots of things that can’t be considered complete. Further, avoid context-switching. This is the activity of starting one task, getting disturbed, starting another, and at it’s most problematic not completing either.
  • Limit the amount of work that is in progress by the team at any one time. For example, if you have 3 developers and 1 tester, you may put a WIP limit on the developers and on the tester.
  • Never add more work to a sprint after it has been planned. Never stop a sprint part way through. The exceptions to this are:
    • If you performed faster than expected, consider taking the next story from the top of the backlog, as long as it is suitably prepared.
    • If the sprint is performing so badly that it will not complete. This usually only happens where there has been a catastrophe of some description.
    • If the sprint objective can no longer be supported due to immediate changing needs of the business.
  • If you do cancel a sprint, do it gracefully, take time to refocus, and start a new sprint as you would any other.
  • Toward the end of a release, consider a final release sprint. No new features are written, some bugs can be cleaned up, and preparations can be made to actually release a new version of your product to your customers. That’s not to say you can’t make incremental customer releases in the meantime – it’s just that this is a controlled, measured, and sustainable release mechanism.
  • At the end of a release you might consider a one week sprint. In this sprint, you might work with the team to breakdown some new ideas, figure out some new technology. These are great tools that benefit the business and it gives the team some briefing space to think and be creative. It’s not for goofing off, it will still create value. Equally, everyone needs a break. Taking a vacation at this time helps keep your cadence and velocity in good shape when you’re mid-release.

Defining Done

Defining what “done” really means is very important. There are many versions of “done” within the life of your project – what it means to be “done” with a story, release, or whole project. It all boils down to what you, your team, and business will consider as complete to the right level of quality to satisfy readiness to ship.

For your team, the definition of a “done” story will be something like all code complete, peer reviewed, meets the defined acceptance criteria, unit tested, UAT’ed, and pushed to your code repository. To enable the passing of a story from designer to developer to tester, will have definitions of “done” to be accepted by the next person in the chain. Your product owner will have expectations as to what this means to her in order to release the product increment to your customers. In any case, everybody must be aware of what “done” means and be a responsible party in ensuring it’s meaning is met. Define your definition of “done”, communicate it, agree upon it and, evolve it. Done done.

Continuous Measurement

If you can’t measure it, you can’t manage it. The same goes for improvements. The need to gather empirical data in an Agile project is almost as vital as having blood course through your veins! How do you know what needs managing, correcting or improving if there’s no data? Well, simply put, you’ll be relying on gut feel and unsubstantiated guess work. Which falls apart pretty quickly under scrutiny. And depending on who’s doing the scrutinizing, this can be a rather uncomfortable place to be. So from the outset of your project, ensure you know how you are going to demonstrate progress and by what measures others are going to view your success.

Fortunately, Agile comes loaded with useful tools and techniques. The first thing to do is go back to the Agile Manifesto, type the following words into your favourite word processor, blow them up to 96pt, print, and apply to the wall for all to see :

Working software is the primary measure of progress.

Your greatest demonstrable power in delivering software is to show it to people working, doing what it’s supposed to do. Not only will this make your customers happy, it will earn your team great respect and grease the wheels for greater adoption through the business.

Here are some other tools:

  • The daily standup: There are a few variations of this ceremony, but the essence is to have all team members talk to each other face to face, keep it short, keep it focused, and keep it light. If anything needs discussion at great length, park it for a longer conversation between those needed after the standup. If impediments are raised, write them up like a story, add them to your backlog, and get them addressed asap. Anything that is impeding your team slows their progress and will be demonstrable in reduced velocity and software that does not meet expectations.
  • Velocity: Is a historical tool. It’s a little like those financial warnings you get that says past performance is no guarantee of future performance. But in Agile’s case, we do hope to achieve a team velocity that is largely smooth. It’s velocity that allows us to project future performance and confidence in our plans. There may be influences outside your control which might lower the number of story points output for a given sprint. If this happens, you’ll probably be able to recover. Never use velocity as a stick to beat your team with, it will win you no favors. One thing for sure is that velocity will be erratic for the first 2 – 4 sprints. Somewhere in that timeframe thought you should start to see consistency and stability. If your velocity is wavering from one extreme to another, you’ve got a problem which you’ll need to fix with your team.

  • The burndown chart: Now this measure of progress is a thorny one. For that reason, I haven’t given a link to go find out more, you’ll have to do your own research and agree as a team and business which works for you. The reason it’s thorny? Well, not one resource out there tells the same story! One thing agreed is that it will show how, within a sprint or a release, how you’re performing against your timebox. If maintained daily, it will show if you’re on track or deviating. Some teams use it to represent how much value is left to be created, more often than not, others use it to show how much work is left to be completed. The former is a celebration of success and value generation, the latter is less inspiring and motivating.
  • The burnup chart: If you must show work completion rates, use the burndown chart for that. But using the burn-up chart allows you to show how much value has been created and how much more value you’re planning to create by the end of the sprint. A much more motivating tool for a team to both demonstrate to the business what has been done (or little if things aren’t going so well…), and what they still have their sights set on. In any case, use the charts to spot where progress is not tracking as expected, look for patterns or deviations and get on top of them to fix the underlying problem as soon as possible. Update them daily for sprints and once at the end of a sprint for release version charts.
  • Task boards: These are great visual radiators for demonstrating value being created. When updated daily, or at any point in the day, they immediately show progress being made. If combined with Kanban, they’re also great tools for visualising flow and blockages in the system. If you can see that loads of development is completed, but testing is not as productive, you can see the problem happening and respond appropriately and swiftly.

Other tools to consider are Agile Earned Value, cycle time, and Cumulative Flow Diagrams (CFD’s).

Keep these measures, charts, and other tools visible, preferably loud and proud on a wall for all to see. The team, stakeholders, and other interested parties can immediately see the status of a project. It’s transparent and serves as a valuable communication tool. If you can’t put these artifacts on a wall, use tools that are sharable and collaborative and make sure those that want access have it.

Continuous Improvement

Throughout your Agile life, seek to identify and learn where improvements can be made. Lessons are not captured and learned at the end of a project. It’s like passing your driving test and tentatively taking your first drive without an instructor. You’ll know what works and what you’re supposed to do, but over time you’ll tailor your driving skill and capabilities, learning new techniques. You’ll even pick up bad habits. Look for them, understand them and find ways to improve.

There are many opportunities for identifying what does not work and applying remedies. The built-in approach to this in Agile is the retrospective. This is the primary tool for reflection and adjustment. At the end of every sprint, take time with the team to improve how work gets done, how quality is delivered, how efficiency can be maximized, how waste can be minimized and how capacity is increased. When you identify measures for improvement, don’t be tempted to fix all your problems right away. Identify the ones that will have most impact and can be implemented in the next sprint. Measure and observe. If it had the desired impact, lock it up, write it up into your ways of working and definitions of done. If it doesn’t work, think again. Any lessons learned that don’t get put into the upcoming sprint can be parked and prioritized for attention in the next sprint.

Tailor the process. Remove anything that does not work. Remove impediments. Your maturity as an Agile team will know no bounds if you let it.

Beyond Agile Project Management

It’s important to know what happens after the project is delivered. Support & maintenance are key to ensuring that once the project is in customer’s hands it remains performant, customer feedback can be factored into future releases, and customer issues are dealt with appropriately. A project is a unique, time constrained endeavour. The product it delivers has a life after the project team has been disbanded. Ensure you are capable of supporting the product once it is live.

Agile projects co-exist with more traditional approaches. Balancing the requirements for budgetary control and stakeholder visibility with the Agile aims of flexibility and responsiveness.

A governance framework or Agile governance model is used in conjunction with a standard Agile processes, such as Scrum. They work in two specific ways:

  • They provide a wrapper for an Agile project by clarifying the processes that occur outside of development iterations (sprints). This includes providing clear criteria for the successful completion of project initiation and proper validation of the decisions and plan.
  • They shift the emphasis of specific parts of the standard Agile process and highlight particular principles and techniques that need governance or support governance.

In today’s ever-changing world, organizations and businesses are keen to adopt a more flexible approach to delivering projects, and want to become more Agile. However, for organizations delivering projects and programmes, and where existing formal project management processes already exist, the informality of many of the agile approaches is daunting and is sometimes perceived as too risky. These project-focused organizations need a mature agile approach – agility within the concept of project delivery – Agile Project Management.

Learn and grow with your adoption of Agile. Only ever do what your team is comfortable with, ensure their voice is heard, and act on their requests. Encourage your team to adopt new and more valuable techniques when the time is right. Negotiate with the business and encourage them to understand what it means to be an Agile organization.

Enjoy the journey.

This article was written by PAUL BARNES, Toptal’s Head of Projects.

MySQL Master-Slave Replication on the Same Machine


MySQL replication is a process that enables data from one MySQL database server (the master) to be copied automatically to one or more MySQL database servers (the slaves). It is usually used to spread read access on multiple servers for scalability, although it can also be used for other purposes such as for failover, or analyzing data on the slave in order not to overload the master.

As the master-slave replication is a one-way replication (from master to slave), only the master database is used for the write operations, while read operations may be spread on multiple slave databases. What this means is that if master-slave replication is used as the scale-out solution, you need to have at least two data sources defined, one for write operations and the second for read operations.

MySQL master-slave replication

MySQL developers usually work on only one machine and tend to have their whole development environment on that one machine, with the logic that they are not dependent on a network or internet connection. If a master-slave replication is needed because, for example, they need to test replication in a development environment before deploying changes elsewhere, they have to create it on the same machine. While the setup of a single MySQL instance is fairly simple, we need to make some extra effort to setup a second, and then a master-slave replication.

For this step-by-step tutorial, I’ve chosen Ubuntu Linux as the host operating system, and the provided commands are for that operating system. If you want to setup your MySQL master-slave replication on some other operating system, you will need to make modifications for its specific commands. However, general principles of setting up the MySQL master-slave replication on the same machine are the same for all operating systems.

MySQL master-slave replication

Installation of the first MySQL instance

If you already have one instance of MySQL database installed on your machine, you can skip this step.

The easiest way to install MySQL on the Ubuntu is to run the following command from a terminal prompt:

sudo apt-get install mysql-server

During the installation process, you will be prompted to set a password for the MySQL root user.

Setting up mysqld_multi

In order to manage two MySQL instances on the same machine efficiently, we need to use mysqld_multi.

First step in setting up mysqld_multi is the creation of two separate [mysqld] groups in the existing my.cnffile. Default location of my.cnf file on the Ubuntu is /etc/mysql/. So, open my.cnf file with your favorite text editor, and rename existing [mysqld] group to [mysqld1]. This renamed group will be used for the configuration of the first MySQL instance and will be also configured as a master instance. As in MySQL master-slave replication each instance must have its own unique server-id, add the following line in [mysqld1] group:

server-id = 1

Since we need a separate [mysqld] group for the second MySQL instance, copy the [mysqld1] group with all current configurations, and paste it below in the same my.cnf file. Now, rename the copied group to [mysqld2], and make the following changes in the configuration for the slave:

server-id           = 2
port                = 3307
socket              = /var/run/mysqld/mysqld_slave.sock
pid-file            = /var/run/mysqld/mysqld_slave.pid
datadir             = /var/lib/mysql_slave
log_error           = /var/log/mysql_slave/error_slave.log
relay-log           = /var/log/mysql_slave/relay-bin
relay-log-index     = /var/log/mysql_slave/relay-bin.index
master-info-file    = /var/log/mysql_slave/master.info
relay-log-info-file = /var/log/mysql_slave/relay-log.info
read_only           = 1

To setup the second MySQL instance as a slave, set server-id to 2, as it must be different to the master’s server-id.

Since both instances will run on the same machine, set port for the second instance to 3307since it has to be different from the port used for the first instance, which is 3306 by default.

In order to enable this second instance to use the same MySQL binaries, we need to set different values for socket, pid-file, datadir and log_error.

We also need to enable relay-log in order to use the second instance as a slave (parameters relay-log, relay-log-index and relay-log-info-file), as well as to set master-info-file.

Finally, in order to make the slave instance read-only, parameter read_only is set to 1. You should be careful with this option since it doesn’t completely prevent changes on the slave. Even when the read_only is set to 1, updates will be permitted only from users who have the SUPER privilege. MySQL has recently introduced the new parameter super_read_only to prevent SUPER users making changes. This option is available with version 5.7.8.

Apart from the [mysqld1] and [mysqld2] groups, we also need to add a new group [mysqld_multi] to the my.cnf file:

[mysqld_multi]
mysqld     = /usr/bin/mysqld_safe
mysqladmin = /usr/bin/mysqladmin
user       = multi_admin
password   = multipass

Once we install the second MySQL instance, and we start up both, we will give appropriate privileges to the multi_admin user in order to be able to shut down MySQL instances.

Create new folders for the second MySQL instance

In the previous step we prepared the configuration file for the second MySQL instance. In that configuration file two new folders are used. The following Linux commands should be used in order to create those folders with appropriate privileges:

mkdir -p /var/lib/mysql_slave
chmod --reference /var/lib/mysql /var/lib/mysql_slave
chown --reference /var/lib/mysql /var/lib/mysql_slave
 
mkdir -p /var/log/mysql_slave
chmod --reference /var/log/mysql /var/log/mysql_slave
chown --reference /var/log/mysql /var/log/mysql_slave

Additional security settings in AppArmor

In some Linux environments, AppArmor security settings are needed in order to run the second MySQL instance. At least, they are required on Ubuntu.

To properly set-up AppArmor, edit /etc/apparmor.d/usr.sbin.mysqld file with your favorite text editor, add the following lines:

/var/lib/mysql_slave/ r,
/var/lib/mysql_slave/** rwk,
/var/log/mysql_slave/ r,
/var/log/mysql_slave/* rw,
/var/run/mysqld/mysqld_slave.pid rw,
/var/run/mysqld/mysqld_slave.sock w,
/run/mysqld/mysqld_slave.pid rw,
/run/mysqld/mysqld_slave.sock w,

After you save the file, reboot the machine in order for these changes to take effect.

Installation of the second MySQL instance

Several different approaches may be followed for the installation of the second MySQL instance. The approach presented in this tutorial uses the same MySQL binaries as the first, with separate data files necessary for the second installation.

Since we have already prepared the configuration file and the necessary folders and security changes in the previous steps, the final installation step of the second MySQL instance is the initialization of the MySQL data directory.

Execute the following command in order to initialize new MySQL data directory:

mysql_install_db --user=mysql --datadir=/var/lib/mysql_slave

Once MySQL data directory is initialized, you can start both MySQL instances using the mysqld_multi service:

mysqld_multi start

Set the root password for the second MySQL instance by using the mysqladmin with the appropriate host and port. Keep in mind, if host and port are not specified, mysqladmin will connect to the first MySQL instance by the default:

mysqladmin --host=127.0.0.1 --port=3307 -u root password rootpwd

In the example above I set the password to “rootpwd”, but using a more secure password is recommended.

Additional configuration of mysqld_multi

At the end of the “Setting up mysqld_multi” section, I wrote that we will give appropriate privileges to the multi_admin user later on, so now is the time for that. We need to give this user appropriate privileges in both instances, so let’s first connect to the first instance:

mysql --host=127.0.0.1 --port=3306 -uroot -p

Once logged in, execute the following two commands:

mysql> GRANT SHUTDOWN ON *.* TO 'multi_admin'@'localhost' IDENTIFIED BY 'multipass';
mysql> FLUSH PRIVILEGES;

Exit from the MySQL client, and connect to the second instance:

mysql --host=127.0.0.1 --port=3307 -uroot -p

Once logged in, execute the same two commands as above:

mysql> GRANT SHUTDOWN ON *.* TO 'multi_admin'@'localhost' IDENTIFIED BY 'multipass';
mysql> FLUSH PRIVILEGES;

Exit from the MySQL client.

Start both MySQL instances automatically on boot

The final step of setting up mysqld_multi is the installation of the automatic boot script in the init.d.

To do that, create new file named mysqld_multi in /etc/init.d, and give it appropriate privileges:

cd /etc/init.d
touch mysqld_multi
chmod +x /etc/init.d/mysqld_multi

Open this new file with your favorite text editor, and copy the following script:

#!/bin/sh

### BEGIN INIT INFO
# Provides:      	scriptname
# Required-Start:	$remote_fs $syslog
# Required-Stop: 	$remote_fs $syslog
# Default-Start: 	2 3 4 5
# Default-Stop:  	0 1 6
# Short-Description: Start daemon at boot time
# Description:   	Enable service provided by daemon.
### END INIT INFO
 
bindir=/usr/bin
 
if test -x $bindir/mysqld_multi
then
    mysqld_multi="$bindir/mysqld_multi";
else
    echo "Can't execute $bindir/mysqld_multi";
    exit;
fi
 
case "$1" in
    'start' )
   	 "$mysqld_multi" start $2
   	 ;;
    'stop' )
   	 "$mysqld_multi" stop $2
   	 ;;
    'report' )
   	 "$mysqld_multi" report $2
   	 ;;
    'restart' )
   	 "$mysqld_multi" stop $2
   	 "$mysqld_multi" start $2
   	 ;;
    *)
   	 echo "Usage: $0 {start|stop|report|restart}" >&2
   	 ;;
esac

Add mysqld_multi service to the default runlevels with the following command:

update-rc.d mysqld_multi defaults

Reboot your machine, and check that both MySQL instances are running by using the following command:

mysqld_multi report

Setup master-slave replication

Now, when we have two MySQL instances running on the same machine, we will setup the first instance as a master, and the second as a slave.

One part of the configuration was already performed in the chapter “Setting up mysqld_multi”. The only remaining change in the my.cnf file is to set binary logging on the master. To do this, edit my.cnf file with the following changes and additions in the [mysqld1] group:

log_bin                    	= /var/log/mysql/mysql-bin.log
innodb_flush_log_at_trx_commit  = 1
sync_binlog                	= 1
binlog-format              	= ROW

Restart the master MySQL instance in order for these changes to take effect:

mysqld_multi stop 1
mysqld_multi start 1

In order for the slave to connect to the master with the correct replication privileges, a new user should be created on the master. Connect to the master instance using the MySQL client with the appropriate host and port:

mysql -uroot -p --host=127.0.0.1 --port=3306

Create a new user for replication:

mysql> CREATE USER 'replication'@'%' IDENTIFIED BY 'replication';
mysql> GRANT REPLICATION SLAVE ON *.* TO 'replication'@'%';

Exit from the MySQL client.

Execute the following command in order to create a dump of the master data:

mysqldump -uroot -p --host=127.0.0.1 --port=3306 --all-databases --master-data=2 > replicationdump.sql

Here we use the option --master-data=2 in order to have a comment containing a CHANGE MASTER statement inside the backup file. That comment indicates the replication coordinates at the time of the backup, and we will need those coordinates later for the update of master information in the slave instance. Here is the example of that comment:

--
-- Position to start replication or point-in-time recovery from
--

-- CHANGE MASTER TO MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=349;

Import the dump you created in the previous step into the slave instance:

mysql -uroot -p --host=127.0.0.1 --port=3307 < replicationdump.sql

Finally, in order for slave instance to connect to the master instance, the master information on the slave needs to be updated with the appropriate connection parameters.

Connect to the slave instance using the MySQL client with the appropriate host and port:

mysql -uroot -p --host=127.0.0.1 --port=3307

Execute the following command in order to update the master information (take the replication coordinates from the dump file replicationdump.sql, as explained above):

mysql> CHANGE MASTER TO
	-> MASTER_HOST='127.0.0.1',
	-> MASTER_USER='replication',
	-> MASTER_PASSWORD='replication',
	-> MASTER_LOG_FILE='mysql-bin.000001',
	-> MASTER_LOG_POS=349;

Execute the following command in order to start the slave:

mysql> START SLAVE;

Execute the following command in order to verify the replication is up and running:

mysql> SHOW SLAVE STATUS \G

Congratulations. Your MySQL master-slave replication on the same machine is now successfully set up.

MySQL master-slave replication

Wrap Up

Having a master-slave replication configured in your development environment is useful if you need it for a scale-out solution in the production environment. This way, you will also have separate data sources configured for write and read operations so you can test locally that everything works as expected before further deployment.

Additionally, you may want to have several slave instances configured on the same machine to test the load balancer that distributes the read operations to several slaves. In that case, you may use this same manual to setup other slave instances by repeating all the same steps.

This article was written by IVAN BOJOVIC, a Toptal SQL developer.