logo: Ytria - Essential Tools for IBM Notes and Domino (Lotus)
Ytria Tech Lab
Articles, Tips, and Code for IBM Notes and Domino Administrators & Developers

Renaming 80 rooms across 3000 mail files in one click

on 9/19/17

main-renaming-rooms

We recently finished a successful customer project using Ytria XML Automation capabilities and we wanted to share how it went.

What’s in a name?

The idea of renaming resource rooms in your organization may not sound particularly complicated. Just change the name in the resource reservations database and everyone will catch on, right? Well, no. First, it’s important to remember that when we say “resource rooms,” we mean conference rooms and the like, but we could just as easily be talking about business equipment and other resources that everyone in your company needs to have access to.

But what happens if you need to rename the resource? In a growing company, there may come a time when you need to review your room naming strategy. This means you’ll need to change “Conference Room 1″ to something else to distinguish it from “Conference Room” in your Toronto or Hong Kong office.

A burden on the meeting owner

This is a problem one of our existing customers was dealing with. They were using the IBM Domino rooms and resources feature extensively, and had over 80 rooms across several sites and decided to change their room naming nomenclature.

Although the process of renaming is somewhat supported by the IBM platform (you can rename rooms directly from there, see fig. 1), the changes are not automatically applied in meetings across user mail files. Only the meeting owner receives a mail with a button and it is exclusively up to them to click to apply the changes on their meetings (and not those of invitees). That puts a lot of pressure on them, and if they forget it could cause confusion in other areas of the business.

roomsrename_1

Fig. 1 Renaming rooms directly in Notes.

 

 

Analyzing the challenge

The customer asked us if our tools could help go through their 3000+ email files, and rename all future meeting room information to reflect the room name changes.

To determine whether we could help, we did some analysis on how room information is stored in the organization’s document management system, and found that what we needed to do was:

– Locate any documents using the “Appointment” or “Notice” forms where the StartDate item value was in the future, and the “Room” item’s value corresponded to one of the old room names.

– Perform a Search & Replace on the room name, including the site information (see fig. 2).

An issue that we encountered during our preliminary tests had to do with recurring meetings: The way these were managed in the back-end was a problem. There was only one meeting document with a date/time item called “StartDateTime” which contained all dates and times a meeting was to repeat. The calendar view would then display the same document as multiple entries, according to the StartDateTime item values.

And since we were initially looking for meetings in the future only, these repeating meetings were missed.

Re-adjusting the formula to include these meetings, the formula we used to find them was:

@IsMember(Form;"Appointment":"Notice") & ( @Elements(StartDateTime)>1 | StartDate>@Today ) & @Contains(Room;"Meeting");
search_replace

Fig. 2 Searching by formula any documents using the “Appointment” or “Notice”, and executing a search & replace on the room name.

Creating the Automation XML

To create an automation file, notably because of the volume of databases and search strings, we first needed to figure out the best way to perform the task using scanEZ manually, which was by using the following steps:

1.)    Open scanEZ on the mail file.

2.)    Perform a Search by Formula using the above formula.

3.)    Put all matching documents into a MySelection folder with the name of the room that was to be renamed.

4.)    Highlight the MySelection folder and perform a Search & Replace on the “Room” item.

5.)    Do this again for the next room names.

Going from manual to automatic

Since scanEZ can easily do this on a given database, the XML Automation API let us create an XML file that instructs the tool to perform all these required steps. We then used databaseEZ to select the mail files that needed to be processed, and had scanEZ go through all these mail files to perform the changes (see fig. 3).

<ytriaAutomation Application="scanEZ" ApplicationVersion="16.5">
<!--This will set the scripts behavior when encountering an error. In this case, it will continue.-->
<onerror continue="true" />

<!-- Define Room List to scan mail files for. It's best to use the entire Room name in the 'Roomname' variable, and a short but unique Alias as 'Alias': this is for the report only. 
Simply copy and paste lines to define more rooms to scan, the loop afterwards processes it all sequentially.  --> 
<list name="RoomsList" Action="setVar" RoomName="Montreal Meeting Room 1" Alias="Mtl MeetingRoom" NewName="Montreal Conference Room"/>

<!-- Start Processing list --> 
<loop list="RoomsList" OnError="Next">
  <ExecuteListAction/>
  <SetVar vSearchFormula="@IsMember(Form;&quot;Appointment&quot;:&quot;Notice&quot;) &amp;( @Elements(StartDateTime)>1 | StartDate>@Today ) &amp; @Contains(Room;&quot;{%RoomName%}&quot;);"/>
  
  <!-- Start with searching for the first room --> 
  <SearchBy Type="Formula">
    <Setparam Field="SetFormula" Value="{%vSearchFormula%}"/>
    <Setparam Field="SearchDocuments" Value="true"/>
    <Setparam Field="SearchDesigns" Value="false"/>
    <Setparam Field="PutSearchInSelCreateName" Value="{%Alias%}"/>
  </SearchBy>
  
  <!-- The following Focus line will place the focus on the newly created My Selection folder named "All Docs Found".-->
  <Focus Target="Tree" Category="{%Alias%}"/>
  
  <!-- The following If condition declares that If the My Selection exists (i.e. something has been found), 
    the nested child actions will be carried out.-->
  <if Target="Tree" Test="FocusRoot" Mode="NotEquals" Value="True">
    <!-- This will set the displayed document titles to the current database name, for reference in the resulting report.-->
    <ChangeDocumentTitle>
        <Setparam Field="TitleOptionType" Value="Formula"/>
        <Setparam Field="TitleOptionFormula" Value="@Implode(@DbName;&quot;!!&quot;)"/>
    </ChangeDocumentTitle>
    
    <!-- Get to values for first export --> 
    <Values KeepAlive="False"> 
      <ShowTypeColumns value="false"/>
      <SetParam Field="AddItem" value="Form"/>
      <SetParam Field="AddItem" value="InviteeName"/>
      <SetParam Field="AddItem" value="Principal"/>
      <SetParam Field="AddItem" value="ResourceName"/>
      <SetParam Field="AddItem" value="Room"/>
      
      <!-- Add this column to explain what the document in question represents --> 
      <AddCustomColumn name="Document Type">
        <SetParam field="TitleOptionType" Value="Formula"/>
        <SetParam field="TitleOptionFormula" Value="@If(Form=&quot;Notice&quot;&amp;NoticeType=&quot;I&quot;;&quot;Not Accepted Invite&quot;;Form=&quot;Notice&quot;&amp;NoticeType=&quot;A&quot;;&quot;Acceptance notice from participant&quot;;Form=&quot;Appointment&quot;&amp;Chair=$BusyName;&quot;Meeting Chair's appointment(hasnt clicked rename)&quot;;&quot;Invitee Appointment to update&quot;)"/>
      </AddCustomColumn>
      
      <!-- And this adds a custom column where the UNID will be displayed.-->
      <AddCustomColumn name="UNID">
        <SetParam field="TitleOptionType" Value="System"/>
        <SetParam field="TitleOptionSystem" Value="UNID"/>
      </AddCustomColumn>
            
      <!-- Add this column to display whether this export is 'before change' or after change' -->
      <AddCustomColumn name="Status">
        <SetParam field="TitleOptionType" Value="Formula"/>
        <SetParam field="TitleOptionFormula" Value="&quot;Before Change&quot;"/>
      </AddCustomColumn>
      
            <!-- Add a column so we can track how long it took -->
            <AddCustomColumn name="Time of retrieval">
                <SetParam field="TitleOptionType" Value="Formula"/>
                <SetParam field="TitleOptionFormula" Value="@Text(@Now)"/>
            </AddCustomColumn>
            
            <!-- Evaluate custom columns -->
            <Evaluate/>
      
      <!-- Lets do the export --> 
      <Export>
        <SetParam field="FilePath" value="MeetingRoomScan"/>
        <SetParam field="SelectedRowsOnly" value="false"/>
        <SetParam field="ExportType" value="Excel"/>
        <SetParam field="Mode" value="AppendRows"/>
        <SetParam field="ExcelSheetName" value="{%Alias%}"/>
        <SetParam field="OpenFileOnceGenerated" value="False"/>
      </Export>
    </Values> 
    
      <!-- Perform the search & Replace --> 
    <Focus Target="Tree" Category="{%Alias%}"/>
      <SearchAndReplace keepalive="False">
        <SetParam field="Source" value="SelectedFields"/>
        <SetParam field="Fields" value="Room;From;InviteeName;Principal;ResourceName"/>
        <SetParam field="RegexSearch" value="{%RoomName%}"/>
        <SetParam field="TextReplace" value="{%NewName%}"/>
        <SetParam field="Action" value="Apply"/>
      </SearchAndReplace>
      
      <!-- Do another values + export --> 
    <Values KeepAlive="False"> 
      <ShowTypeColumns value="false"/>
      <SetParam Field="AddItem" value="Form"/>
      <SetParam Field="AddItem" value="InviteeName"/>
      <SetParam Field="AddItem" value="Principal"/>
      <SetParam Field="AddItem" value="ResourceName"/>
      <SetParam Field="AddItem" value="Room"/>
      
      <!-- Add this column to explain what the document in question represents --> 
      <AddCustomColumn name="Document Type">
        <SetParam field="TitleOptionType" Value="Formula"/>
        <SetParam field="TitleOptionFormula" Value="@If(Form=&quot;Notice&quot;&amp;NoticeType=&quot;I&quot;;&quot;Not Accepted Invite&quot;;Form=&quot;Notice&quot;&amp;NoticeType=&quot;A&quot;;&quot;Acceptance notice from participant&quot;;Form=&quot;Appointment&quot;&amp;Chair=$BusyName;&quot;Meeting Chair's appointment(hasnt clicked rename)&quot;;&quot;Invitee Appointment to update&quot;)"/>
      </AddCustomColumn>
      
      <!-- And this adds a custom column where the UNID will be displayed.-->
      <AddCustomColumn name="UNID">
        <SetParam field="TitleOptionType" Value="System"/>
        <SetParam field="TitleOptionSystem" Value="UNID"/>
      </AddCustomColumn>
            
      <!-- Add this column to display whether this export is 'before change' or after change' -->
      <AddCustomColumn name="Status">
        <SetParam field="TitleOptionType" Value="Formula"/>
        <SetParam field="TitleOptionFormula" Value="&quot;After Change&quot;"/>
      </AddCustomColumn>
            
            <!-- Add a column so we can track how long it took -->
            <AddCustomColumn name="Time of retrieval">
                <SetParam field="TitleOptionType" Value="Formula"/>
                <SetParam field="TitleOptionFormula" Value="@Text(@Now)"/>
            </AddCustomColumn>
            
            <!-- Evaluate custom columns -->
            <Evaluate/>
      
      <!-- Let's do the export --> 
      <Export>
        <SetParam field="FilePath" value="MeetingRoomScan"/>
        <SetParam field="SelectedRowsOnly" value="false"/>
        <SetParam field="ExportType" value="Excel"/>
        <SetParam field="Mode" value="AppendRows"/>
        <SetParam field="ExcelSheetName" value="{%Alias%}"/>
        <SetParam field="OpenFileOnceGenerated" value="False"/>
      </Export>
    </Values> 	
  </if> 
  </loop>
</ytriaAutomation>

 

By using our solutions, our customer finished the renaming project in just a couple of days, running the automation XML across 5 Virtual Machines, performing the Search & Replace procedure for 5 rooms per VM. Using the Ytria tools drastically reduced the tedium of the job so their team could focus on work of higher value. They also avoided potential confusion and other issues that might have caused downtime.

 

automation
Fig. 3 Automating the process whereby scanEZ goes through all mail files in each database.

Future steps with scanEZ

With all rooms correctly renamed across meeting documents and over 3000 files, the next challenge was to remove the old meeting room names from each user’s “Preferred Rooms” list—this is an item in each mail file’s CalendarProfile, and can also be done using a scanEZ automation script. Stay tuned for our follow-up blogpost on how we did it.

If you are interested in automation or have a specific requirement we might be able to help with, or to find out more about Ytria XML Automation API, contact us today!

 

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Print Friendly, PDF & Email

Leave a Comment

To diplay code in your comment, put the code between these brackets: [cc]your code[/cc]. You can also put inline code by using these: [cci]your inline code[/cci]