Application: Journaling
Revit Platform: All
Revit Version: 2011.0
First Released For: 9.1
Programming Language: C#
Skill Level: Medium
Category: Basics
Type: ExternalCommand

Subject: Journaling mechanism: Journal Data read and write.
Summary: 
This sample demonstrates how an external application can be incorporated into the journaling mechanism.

Classes: 
Autodesk.Revit.UI.IExternalCommand
Autodesk.Revit.DB.Document
Autodesk.Revit.DB.Element
Autodesk.Revit.DB.Creation
Autodesk.Revit.DB.Collections.StringStringMap

Project Files: 
Command.cs
This file contains the class Command that inherits from IExternalCommand. The class implements the Execute method and be used to interoperate with Revit.

Journaling.cs
This file will implement the functions: get all Wall types and all Levels; show all Wall types and Level information in a Form; read and write journal data to journal file; create a Wall according to user setting. 

JournalingForm.cs
This file contains the Form class which consists of: two ComboBox controls, one list all Wall types, the other is for all Levels; a user control to get Wall location from user’s inputting.

PointUserControl.cs
This file contains user control class which implements a user control for getting XYZ data from user input.

Description: 
This sample mostly uses StringStringMap class for implementing the functionality: read and write user data from/to journal file, the data exists in APIStringStringMapJournalData journal data section in journal file.
-	To read or write data which stored in the journal file, use StringStringMap class’s methods:  get_Item(key) and Insert(key, value).
-	The ExternalCommandData.Data property can be used to get/set the journal data (StringStringMap object).
-	To get all Wall Type in Revit project, use ActiveDocument.WallTypes.
-	To get an existing element by Id, use ActiveDocument.get_Element(ref ElementId).

Instructions: 
1.	In order to test the sample function about reading / writing journal data, firstly, user should manually execute this sample one time.
2.	Click the extern command, a dialog will be popped up; input the start and end point for new Wall, click Ok to create a new wall and then close Revit without saving.
3.	Open the latest journal file generated by Revit in Journals folder under Revit install directory(ensure there is Journals folder before run this sample), you will see the journal data (End Point, Start Point, Level Id, etc) added by API in APIStringStringMapJournalData section:
  Jrn.Data "APIStringStringMapJournalData"  _
          , 4, "End Point", "(100,0,0)" _
          , "Level Id", "30", "Start Point" _
          , "(0,0,0)", "Wall Type Name", "Curtain Wall 1"

4.	When replay this sample journal (drag the journal to Revit.exe icon directly), you will find same Wall is created successfully via reading the journal data value reserved in above steps.
5.	However, if you comment the WriteJournalData() method in method Run() of Journaling.cs file then execute step1 to step3; in step4, the JournalingForm will be popped up and blocks the execution, because there is no journal data be reserved in step1 to step3.

Note: 
1.	Because we need to write APIStringStringMapJournalData content to journal, make sure the external command uses JournalingData.UsingCommandData attribute; otherwise, no content will be dumped to journal when manually running samples.