In a recent blogpost, you got a walkthrough of one of Ytria’s recent customer cases where we helped out with a massive (and successful!) renaming operation. Renaming 80 meeting rooms across 3000+ mail files is no small job, but we got it done using Ytria’s XML automation API.
But, there was another part of that job that was deliberately left out of the post: once the rename was completed, we needed to modify all the users’ calendar profiles to remove the old rooms names from their preferred lists. Why? Because it’s an important step that seemed worthy of a separate article. But beyond that, it involves another subject our customers ask about quite often: mass-reading/editing profile documents.
On their own, scanEZ’s profile document management capabilities offer a number of advantages over the native tools. First, we’ll take a look at what can be done on a single database and how because that forms the basis of everything done through Ytria automation: the principle of our XML Automation API is that most UI actions can be recorded, coded and repeated across multiple databases and or servers using a simple XML automation file. Once we have that down, we’ll move on to its large-scale application.
Working with profile documents in a single database
If you’re already a Ytria user, chances are you’ve used scanEZ to work with profile documents before. It’s tempting because the interface really is intuitive and offers a great deal of flexibility: administrators and developers can basically work with profile documents as if they were regular Notes documents.
Just open scanEZ on a database, and expand the ‘Profile Documents’ section in the selection tree on the right-hand side of your session screen. Click the profile document you want to view, and you’ll see all the information your selected profile document contains in the items grid (see fig. 1).
Now, what can you do with profile documents in scanEZ? And how?
1) Create a new profile document directly in the back end. Just go to the ‘Document’ menu and select ‘New/Get Profile Document…’, or use Ctrl + Shift + N (see fig. 2).
2) Edit profile documents. Open your desired profile document and right-click in the items grid. From the context menu, you can choose to add new items, modify item values, or delete items. Once you’ve reviewed your changes, save them to make them final (fig. 3).
3) Delete profile documents. In the selection tree (on the left-hand side of your session screen), right-click on the profile document to delete and select ‘Delete’ from the context menu. Or, just select the document and use the Del key (see fig. 4).
Moving beyond single-database work using Ytria’s automation API
Now that we’ve briefly covered what sort of profile-related capabilities scanEZ offers and how we use them, let’s see how you can extend these capabilities to multiple databases, or even across different servers.
See our API documentation for a full list of tag definitions and detailed information about their uses.
To run our script over multiple databases, there are two options: 1.) manually run the script on each database in scanEZ or 2.) use databaseEZ’s ‘Execute Automation File on…’ option to run the script of a current selection of databases. Let’s choose the second option.
Note: In order for a script to be executable in this way, the script must include an IF statement that allows the script to be run over a list of databases. See the detailed comments in the scripts provided for more information.
The following are the basic steps required to get to the point where your specified profile documents are isolated and ready to be worked on. You’ll notice that they are present in all the scripts provided here. See the script comments for more information about each of these basic steps.
- Expand the section ‘Profile Documents’. (Make sure nothing is selected yet.)
- Place the focus on the same category.
- With focus on the category ‘Profile Documents’, perform a ‘Select by Regex’ using the name of the profile document (specified in the list). This will make a checkbox selection of the profile documents in question.
- Add any selected profile documents to a My Selection folder. If none are selected, you can move on to the next name. If there are no remaining names, you’re done.
- Set the focus to the new My Selection folder.
Now, let’s look at what you can do from this point.
Processing profiles across multiple databases
The following are a few different example scenarios that involve working with profile documents on a large scale. You can use the scripts provided as is, or tweak them to meet your own needs. Simply copy/paste them into any text editor, make your modifications, and then save them in XML format.
1) The burning question from the beginning of this post: How did we remove all preferred rooms from each users’ calendar profile document—a task that spans over 3000 mail files? Here’s how.
The underlying method that used to accomplish this is to open each database in scanEZ, and expand the ‘Profile Documents’ selection tree node. Then do a regex search for a profile containing “calendarprofile” (keep in mind that a simple regex, as written here in the script, will find any profile whose name contains “calendarprofile”) within that section and, once found, select it and add it to a new My Selection folder. After that, navigate to that newly created virtual folder, select the profile document, and remove the item called “PrefRoomsList”.
Important: This will not work on Personal Profile documents, as these are stored in a different way, and thus require a different method to find and select them.
On its own, this script only carries out the above actions on a single database. That’s where databaseEZ comes in.
Open databaseEZ and load the folder where the mail files you want to modify are located. Then select all the mail files in databaseEZ’s main grid, and from the context menu select ‘Execute Automation File on… > scanEZ’. When prompted to select an automation file to run, select the proper XML file (see fig. 5).
2) An XML script to export all mail related profile document contents from multiple mail files.
Over the years, we’ve learned that getting a handle on mail profiles is extremely important to anyone looking to migrate their mail from Notes (or to Notes, in which case this would be a good diagnostic to run after the migration). When we say this, we mean extracting archive settings, determining out of office status, and more. But how can you do this without having to build a robust framework and a set of LotusScript agents? Well, with scanEZ, databaseEZ, and automation.
You’ll need to provide the names of the profile documents to process and these names must match what you would see in the scanEZ selection tree exactly. The script below to ‘Scan Profile Documents’ uses a List to define these names. Once you have the list, you can change out names fast, and even add names to the list by just copy/pasting a new line in.
Once you’ve specified the names, all you need to do is describe the same steps that you would use in the UI.
You can remove profile documents, or add more as needed. If you need to add in more lines, just copy/paste and follow the pattern.
If they are any of the profile documents specified are present, they will be found, and their contents exported (see fig. 6).
3) Creating a report of all your users’ mail rules
A need that we hear about from a lot of users, is that of getting a better overview of users’ mail rules. Because these mail rules are set for each database individually, there is no central interface to manage them. There may be times where you need to figure out if, for example, any mail rules are set to forward emails to external addresses—among other things.
How can automation help? Back in this article we explained that mail rules are stored in both the calendar profile, and documents. So, you could go about scanning these using a process like the one used for profile documents. But because of the way mail rule data is structured in the calendarprofile, it’s best to approach this via actual mail rule documents.
The following script runs a formula search using the formula SELECT Form=”Mailrule” & Enable=”1”.
You’ll notice that formulas can’t simply be copied and pasted as plain text. Characters like quotes and ampersands need to be “translated”—escaped—so that they can be interpreted correctly in XML. If you’re interested in modifying formulas, read more about escaping characters in XML: https://stackoverflow.com/questions/1091945/what-characters-do-i-need-to-escape-in-xml-documents
Once the documents are in a new My Selection folder, the script will grab a few item values such as the ActionList item which provides a nice description of the action performed and … voila (see fig. 7)!
As you can see, the basis of all Ytria automation scripts is defined by what you can do in the UI. Once you know what you need to do manually, just follow the steps to build your the script. And once you can process one database with scanEZ, you’re only a few steps away from being able to extend that to multiple databases, even across an entire server.
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!