The Schedule API and Access to Schedule Data

Somehow I seem to be spending the vast majority of my time just shovelling information back and forth, preparing for conferences and trainings and answering questions. It is always a great pleasure for me to actually get in a teeny weenie bit of programming in between, so I am happy that I managed to find time to create the new little sample application described below.

One of the many exciting enhancements in the Revit 2013 API is the new Schedule API. Here is the description from the Revit API help file RevitAPI.chm What's New section:

Schedule API

Several new classes have been added to allow schedule views to be created, modified, and added to drawing sheets. Major new classes include:

• The ViewSchedule class that represents the schedule view. Its create methods are used to create new schedules.
• The ScheduleField class for the individual fields in a schedule.
• The ScheduleSheetInstance class represents schedules placed on sheets. The create method creates an instance of a schedule on a sheet.
• The ScheduleDefinition class defines the contents of a schedule view, including:
  1. Basic properties that determine the kind of schedule, such as the schedule's category.
  2. A set of fields that become the columns of the schedule.
  3. Filters that restrict the set of elements visible in the schedule.
  4. Sorting and grouping criteria.

Running API commands in Schedule Views

API commands may now be active when a Schedule is active in the current document.

Schedule export

The ViewSchedule class has been added to the API and the method ViewSchedule.Export method exports an existing schedule to a text file.

As I already mentioned, the ability to create a schedule is demonstrated by the ScheduleCreation SDK sample.

Before even dreaming of creating new schedules, however, many people are interested in simply accessing the data in existing ones.

Accessing Schedule Data

Fitting in nicely with this, a couple of queries recently came in on accessing schedule data.

The Revit API currently does not provide a method to access and cycle through the schedule data directly.

The new Revit 2013 schedule export functionality described above provides for a very simple workaround, however: you can use the ViewSchedule.Export method to export the schedule data to a text file, and then parse the resulting file to access the data.

The ViewSchedule.Export method takes a ViewScheduleExportOptions argument which provides the following properties to enable specification of various text file output settings:

• ColumnHeaders: how to export column headers. Default is MultipleRows.
• FieldDelimiter: how to delimit fields. Default is Tab.
• HeadersFootersBlanks: whether to export group headers, footers, and blank lines. Default is true.
• TextQualifier: how to qualify text fields. Default is DoubleQuote.

ScheduleData Sample Add-in

I created a sample application to demonstrate accessing the schedule data, and not just that. It also implements the following interesting additional features:

• Access and read back the schedule data from the exported text file into your application.
• Separately determine the schedule name, the column header names, and the schedule row data.
• Populate a DataTable instance with the retrieved schedule data.
• Create a new Windows form with a docked DataGridView in it programmatically, avoiding the need to define a hard-coded form in your add-in.
• Attach the form to the Revit main window, so that it is minimised and restored together with Revit.
• Populate the DataGridView from the DataTable and display the results.

I use the undocumented AdWindows assembly to determine the Revit parent window.

It returns the main window Revit handle in the static property ApplicationWindow of the ComponentManager class in the Autodesk.Windows namespace.

Here is the JtWindowHandle class that I use to convert the IntPtr returned by that property to the IWin32Window required by the Form.Show method:

  /// <summary>
  /// Wrapper class for converting 
  /// IntPtr to IWin32Window.
  /// </summary>
  public class JtWindowHandle : IWin32Window
  {
    IntPtr _hwnd;
 
    public JtWindowHandle( IntPtr h )
    {
      Debug.Assert( IntPtr.Zero != h,
        "expected non-null window handle" );
 
      _hwnd = h;
    }
 
    public IntPtr Handle
    {
      get
      {
        return _hwnd;
      }
    }
  }

Exporting the schedule data from Revit is really simple. Here is the implementation to export all schedule data in the entire model to separate text files with the filename extension TXT, defined by _ext, in a hard-coded folder, defined by _export_folder_name:

  FilteredElementCollector col
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ViewSchedule ) );
 
  ViewScheduleExportOptions opt 
    = new ViewScheduleExportOptions();
 
  foreach( ViewSchedule vs in col )
  {
    Directory.CreateDirectory( 
      _export_folder_name );
 
    vs.Export( _export_folder_name, 
      vs.Name + _ext, opt );
  }

The application then asks the user to select any one of the resulting text output files at a time to display its data in the data grid view. When the user cancels the file selection, the command is terminated:

  string filename;
 
  while( FileSelect( _export_folder_name, 
    out filename ) )
  {
    DisplayScheduleData( filename, 
      revit_window );
  }

Here is the DisplayScheduleData method that programmatically sets up a new Windows form, populates it with a docked DataGridView instance, and populates that with the schedule data retrieved from the output text files by the ScheduleDataParser class:

  void DisplayScheduleData( 
    string filename, 
    IWin32Window owner )
  {
    ScheduleDataParser parser 
      = new ScheduleDataParser( filename );
 
    System.Windows.Forms.Form form 
      = new System.Windows.Forms.Form();
    form.Size = new Size( 400, 400 );
    form.Text = _caption_prefix + parser.Name;
 
    DataGridView dg = new DataGridView();
    dg.AllowUserToAddRows = false;
    dg.AllowUserToDeleteRows = false;
    dg.AllowUserToOrderColumns = true;
    dg.Dock = System.Windows.Forms.DockStyle.Fill;
    dg.Location = new System.Drawing.Point( 0, 0 );
    dg.ReadOnly = true;
    dg.TabIndex = 0;
    dg.DataSource = parser.Table;
    dg.Parent = form;
 
    form.ShowDialog( owner );
  }

You could obviously make the form modeless instead of modal by calling Show instead of ShowDialog here. Since we are not accessing the Revit API from the form, there is no danger in leaving it open after the external command terminates. That would enable navigation and exploration of the schedule data in a modeless form in parallel with continued work in the Revit model.

Finally, here is the main point, the ScheduleDataParser class that I implemented to extract the schedule name, column headers, and schedule data from the text file and populate a DataTable instance with it:

class ScheduleDataParser
{
  /// <summary>
  /// Default schedule data file field delimiter.
  /// </summary>
  static char[] _tabs = new char[] { '\t' };
 
  /// <summary>
  /// Strip the quotes around text strings 
  /// in the schedule data file.
  /// </summary>
  static char[] _quotes = new char[] { '"' };
 
  string _name = null;
  DataTable _table = null;
 
  /// <summary>
  /// Schedule name
  /// </summary>
  public string Name 
  { 
    get { return _name; } 
  }
 
  /// <summary>
  /// Schedule columns and row data
  /// </summary>
  public DataTable Table 
  { 
    get { return _table; } 
  }
 
  public ScheduleDataParser( string filename )
  {
    StreamReader stream = File.OpenText( filename );
 
    string line;
    string[] a;
 
    while( null != ( line = stream.ReadLine() ) )
    {
      a = line
        .Split( _tabs )
        .Select<string, string>( s => s.Trim( _quotes ) )
        .ToArray();
 
      // First line of text file contains 
      // schedule name
 
      if( null == _name )
      {
        _name = a[0];
        continue;
      }
 
      // Second line of text file contains 
      // schedule column names
 
      if( null == _table )
      {
        _table = new DataTable();
 
        foreach( string column_name in a )
        {
          DataColumn column = new DataColumn();
          column.DataType = typeof( string );
          column.ColumnName = column_name;
          _table.Columns.Add( column );
        }
 
        _table.BeginLoadData();
 
        continue;
      }
 
      // Remaining lines define schedula data
 
      DataRow dr = _table.LoadDataRow( a, true );
    }
    _table.EndLoadData();
  }
}

Here is a sample schedule in Revit to test this on:

This is the resulting data grid view representation:

Here is ScheduleData.zip containing the complete source code, Visual Studio solution and add-in manifest for this add-in.

On a closely related note, here is another question that just came in:

Question: Can calculated values in schedules be transferred to a shared parameter with some API code?

Answer: Sure. Just access the schedule data as demonstrated above, and then write the relevant value to the shared parameter.

Comments

[Rudolf Honke]

Hi Jeremy,

it would be nice if we could also access the background color in schedule cells.
Think of displaying values in different ways, depending on different conditions.
We can perform the colorizing via GUI, so why not via API ?

Thanks,
Rudolf

[Jeremy Tammik]

Dear Rudolf,

Thank you, that is an absolutely brilliant idea!

Please submit an ADN DevHelp Online request for this and I will file a wish list item for you.

Cheers, Jeremy.

[Phillip Miller]

HI Jeremy.

The schedule API rocks and I have used it extensively in our new product Project Browser for creating what we call queries - .
http://revitfb.blogspot.co.nz/2012/05/project-browser-for-revit-2013-now.html

Please though allow us to access the element ID’s that are contained within the schedule, or at least allow us to schedule the elements ID values. At the moment I have to export the schedule to a txt file compare the family types and names and then back in Revit match the corresponding objects. That is pretty inefficient.

Good start though ;)

Cheers

Phillip

[Jeremy Tammik]

Dear Phillip,

Thank you very much for your appreciation, and I am very glad to hear that you are already making good use of this functionality.

Your project browser sounds like a powerful tool. Sorry that you have jump through such silly hoops to access the data you require.

My suggestion to Rudolf applies to your case as well: please submit an ADN DevHelp Online request for this and I will file a wish list item for access to the element ids for you.

Cheers, Jeremy.

[Phillip Miller]

I will do Jeremy.

The Revit 2013 API is a huge advancement. I can't wait to see what you guys have in store for next year.

[Jeremy Tammik]

Dear Phillip,

Yes, absolutely, on both counts. Unbelievably impressive factory deliverables, and can't wait to see what comes next.

Looking forward to seeing your case as well, thank you for that.

Cheers, Jeremy.

[Jemish Kava]

Hi Jeremy,

I am excited to work with schedule export but I noticed there is no easy way to reference the elements through ID or GUID when schedules are exported to a text file. Do you know if it's possible to import the exported schedule data back into Revit?

[Jeremy Tammik]

Dear Jemish,

Glad you are excited, so am I.

Yes it is, as you can see from Phillip's description below of how he achieves this very task.

It is a workaround, though, and rather kludgy. I know of no other way, though. Please file a wish list item for a future enhancement.

Cheers, Jeremy.

[Chris Heinaranta]

Hi Jeremy,
you responded through email that with some detailed testing there might be the possibility to access the revision schedule that is placed in a titleblock. I'm hoping some loyal readers could test it out (I'm by no means a programmer).

Thanks,

Chris

[Anthony Tiefenbach]

Could this be used to read Revision Schedules on a sheet? I see them in the Revit database as a ViewSchedule but your addin didn't access them directly. If we could access these dependent schedules, we could read the Revisions on Sheet.

[Raymond]

Hi Jeremy,

Very usefull your blog if you ask me ;)

Using the ScheduleDefinition.GetSchedulableFields it is possible to iterate through the available (shared) parameters and add or insert (addfield or insertfield) them to the created schedule.

However I wish to add a calculated value / calculated field to the schedule. This field does not show up in GetSchedulableFields because this field has to be added 'on the fly'. In the API there is a schedulefieldtype.formula member which suggest it may be possible to add a calculated field. Do you know how to add a calculated field because I am running out of ideas. Or is this not possible (yet)?

Thanks,
Raymond

[Jeremy Tammik]

Dear Raymond,

Thank you for your appreciation. I am glad you find it useful.

Yes, sorry, currently not possible. Revit 2013 provided a first stab at a schedule API, to be fledged out in future, e.g. to access individual values.

Cheers, Jeremy.

[Maja]

Hi Jeremy,

Do you know if it will be possible to iterate/modify data directly in schedule in Revit 2014 API? It would be far more elegant solution to write directly into schedule.

Thanks,

Maja

[Jeremy Tammik]

Dear Maja,

Yes, sure, it is. Take a look at the fourth bullet item here:

http://thebuildingcoder.typepad.com/blog/2013/03/revit-2014-api-and-room-plan-view-boundary-polygon-loops.html

Look at the presentation, recording and sample code provided there.

Look at the overview of the 'ViewSchedule changes' in the What's New in the Revit 2014 overview:

http://thebuildingcoder.typepad.com/blog/2013/04/whats-new-in-the-revit-2014-api.html

Look at the new ScheduleAutomaticFormatter, ScheduleCreation and ScheduleToHTML SDK samples.

Cheers, Jeremy.

[Rui Gavina]

Hi Jeremy!

Is it possible to populate a Schedule Key from excel, without assigning the parameters to any instance?

I would like to create a shedule key to have drop down lists, following a work a quantities map from excel. Only then i would assign the keys to the elements i choose an that way i would have an optimizes process to create and update the maps for each project.

Also i tried to install you Scheduledata sample, but i´m not getting it right. It would be nice to have it functioning to understand a little bit better the programming language needed to work around the schedules data.

I have the plug-in installed but when i run it i get the following message:

"Revit encountered a Autodesk.Revit.Exceptions.ArgumentException: Contains invalid characters
Parameter name:mane at Autodesk.Revit.DB.ViewSchedule.Export(String folder, String name, ViewScheduleExportOptions options) .... "

Any idea of what the problem is?

[Jeremy Tammik]

Dear Rui,

I am not a user so I have no idea what a schedule key is.

Ask me about extensible storage instead :-)

http://thebuildingcoder.typepad.com/blog/2013/03/cloud-mobile-extensible-storage-data-use-in-schedules.html#4

From Revit 2014 onwards, you can populate schedule data directly:

http://thebuildingcoder.typepad.com/blog/2013/04/whats-new-in-the-revit-2014-api.html > ViewSchedule changes.

I have no idea what might be causing your error.

I suggest working through the Revit API getting started material and learning to use the Visual Studio debugger to see for yourself what is going on:

http://thebuildingcoder.typepad.com/blog/about-the-author.html#2

Good luck!

Cheers, Jeremy.

[Rui Gavina]

Thanks Jeremy!

I Really have to take some of my spare time to look through that getting started info and understand more clearly the whole process.

If i run into any problems taking these steps i will bug you again ;)

Once again thank you for your support and your contribute to the Revit community!

Cheers, Rui Gavina

[Jeremy Tammik]

Dear Rui,

My pleasure entirely.

Best of luck to you!

Cheers, Jeremy.

[Alexander Skibin]

Hi Jeremy!
I try to make out Revit API as well as English language.
So, I have some questions.
Is it possible to create parameters within API? For example, I wish to get level as a parameter and to make it as a column.

Regards, Alexander.

[Jeremy Tammik]

Dear Alexander,

Yes, sure. E.g.,

http://lmgtfy.com/?q=building+coder+create+shared+parameter

Cheers, Jeremy.

[Du Nguyen phuoc]

Dear Jeremy,
We can access into table data of Schedule to get text in cell. So can we get elementIDs on row of Schedule?

Thanks.

[Manuel Alcala]

I found a way to access the scheduled items, using the schedule filters, it is useful for me

[Jeremy Tammik]

Dear Manuel,

Cool. Congratulations. Thank you for letting us know.

Cheers, Jeremy.