Bulk edit the status of all topics in your documentation project

HelpNDoc 6.0 added support for topic status, which greatly simplifies the maintenance of documentation projects for technical authors: topics can be tagged as being “Out of Date”, “In Progress”, “Needs Review”, “Complete” or any custom status you define. You might be tempted to leverage that feature to update an old project and change the status of all your topics to “Needs Review” to start reviewing them one by one. But individually updating every topic in a big project will be time consuming. Thankfully, HelpNDoc’s scripting support can update the status of the whole documentation project in a fraction of a second. Let’s see how this can be done.

Using HelpNDoc’s script editor

When a feature is not available in HelpNDoc, simply use the script editor and leverage its scripting API to build it yourself.

The script editor can be used to automate most parts of the documentation writing and maintenance process. Here is how to use the script editor in HelpNDoc:

From the “Tools” ribbon tab, click “Script Editor”. This shows the “Script authoring and execution” window;
Enter the content of your script in the code editor. Check the documentation for available API methods to learn what is available in your custom script;
Use the “Build script” button (or SHIFT-F9 keyboard shortcut) to check that its syntax is correct;
Use the “Run script” button (or F9 keyboard shortcut) to run the script;

Writing the script

The algorithm we need to develop to update every topic to a specific status is very simple: we first need to get the unique identifier of the status, we then iterate through all topics in the project, and we set the topic’s status to the correct identifier.

1. Get the identifier of the status

Before applying the status to every topic, we need to get its unique identifier. Fortunately, HelpNDoc’s API for the HndStatus object includes the HndStatus.GetStatusByCaption() method which greatly simpifies this task. Here is a script showing how this can be done:

const
  // Name of the status
  STATUS_TO_LOOK_FOR = 'Needs Review';
var
  // ID of the status
  aStatusId: string;
begin
  // Get the unique ID of the status
  aStatusId := HndStatus.GetStatusByCaption(STATUS_TO_LOOK_FOR);
end;

2. Iterate through all topics

We now have retrieved the unique identifier of the status we’d like to apply to every topic. We can now iterate through each of them as follows:

var
  // ID of the current topic
  aTopicId: string;
begin
  // Get the first topic
  aTopicId := HndTopics.GetTopicFirst();
  // Loop through all topics
  while aTopicId <> '' do
  begin

    // ... Set the status of the topic here ...

    // Get next topic
    aTopicId := HndTopics.GetTopicNext(aTopicId);
  end;
end.

3. Set the status of the topic

We can now simply use the correct HndTopics method to set this topic’s status:

// Set its status
HndTopics.SetTopicStatusId(aTopicId, aStatusId);

The whole script

We now have all the pieces of code ready to write the full script topic status change throughout the documentation project. Let’s review the full script.

The script below will automatically change the status of all topics in the currently opened project to “Needs Review”. It can be customized if needed: simply change the value of the constant named STATUS_TO_LOOK_FOR to set another status. One can also enhance that script to only apply the status to topics meeting a condition, such as having a specific parent, help id, current status… the possibilities are endless.
The full script can be pasted into HelpNDoc’s script editor and will be included in a future version of HelpNDoc:

const
  // Name of the status
  STATUS_TO_LOOK_FOR = 'Needs Review';
var
  // ID of the status
  aStatusId: string;
var
  // ID of the current topic
  aTopicId: string;
begin
  // Get the unique ID of the status
  aStatusId := HndStatus.GetStatusByCaption(STATUS_TO_LOOK_FOR);
  // Get the first topic
  aTopicId := HndTopics.GetTopicFirst();
  // Loop through all topics
  while aTopicId <> '' do
  begin
    // Set its status
    HndTopics.SetTopicStatusId(aTopicId, aStatusId);
    // Get next topic
    aTopicId := HndTopics.GetTopicNext(aTopicId);
  end;
end.