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

How to replace troublesome parts of item values using scanEZ’s Diff feature and a little bit of @formula

on 11/28/17


This tooltip post is sort of adjacent to the previous one, where I ran through how to use scanEZ’s Diff function as the launchpad for modifying an item value in a bunch of documents. In truth, the Diff function is a very powerful feature that puts you in the right place to branch off into a bunch of different operations through its summarized item inventory. But there will be plenty of time to go on those different paths in future posts, this one stays in item-value-modification territory.

When I say that this is adjacent to the previous post, what I mean is that scanEZ users who found the last post useful may find this slight variation useful in much the same way.

Here’s how to replace a defined substring in the value of a specific item across multiple documents.

For those who missed the last post, this was the situation:

A bookkeeping error caused a bunch of invoice documents to have the wrong item value (the currency type). Checking and changing an item’s value across multiple documents presents an annoyance to an already busy employee, and depending on how many documents are affected, that annoyance can quickly become a headache.

Now, to be clear, IBM Notes users who 1.) don’t have scanEZ and 2.) actually like coding one-off agents, I am sure that little challenges like this add a bit of spice to their busy workday. But those who already have scanEZ, have a bunch of quick ways to change item values right at their fingertips, all without having to code any agents.

A tip, adjacent

The previous tip dealt with a flat-out modification of an entire item value. But what if those values were only partially wrong? Well, that is no problem at all! Because armed with the Diff operation and a small line of @formula we can surgically replace only a part of an item’s value across multiple documents.

I am not one to use @formula a lot but, rest assured, the formula involved in this example is minimal.

Here it is: @ReplaceSubstring(Description;”substring to remove“;”value to replace it with“).

That’s not so bad, is it?

Step 1: Know your item values.

The trick to starting this whole process is, of course, knowing that item values are or aren’t correct, as well as which part you need to modify. To do that in scanEZ is a cinch. See this short tutorial on how to change the displayed document title in the selection tree to show item values.

For this example, let’s assume that you either already know what needs to be changed or have used the above method to find out, and that the item values are only wrong because of a differing substring (see fig. 1).

Image of scanEZ's interface showing item values as document titles

Fig. 1 By changing the displayed document titles to show the values of the item suspected to have a problem, you can see the whole situation fast. These item values are wrong, but technically only a different sub-string makes them so.

Step 2: Target the item across a bunch of documents.

Armed with the knowledge of what you need to change, let’s get to changing it.

Select the category ‘Documents’ in the selection tree and click the ‘Diff’ button (see fig. 2).

Image of scanEZ's interface with the Document category focused and Diff button clicked

Fig. 2 Placing the focus on the selection tree category ‘Documents’ and clicking the ‘Diff’ button will carry out the Diff operation on all documents within the database.

In the resulting Diff panel, you’ll see a summarized inventory of all items found across all documents in the database. You’ll also see the items’ values’ statuses: you’ll see if an item is either not present in all documents, present in all documents but with varying values, or present in all documents all with the same value.

Select the item you want to concentrate on and click ‘Modify’ (see fig. 3).

Image of the scanEZ Diff panel showing an item selected and Modify clicked

Fig. 3 Select the item you want from the list of all items present across all documents, and then click ‘Modify’.

Step 3: Make your changes.

In the ‘Modify item’ dialog, check the Type and Name to make sure that you’re working on the right item and then enter the following line of formula, containing your values, in the formula input box: @ReplaceSubstring(Description;”substring to remove“;”value to replace it with“) (see fig. 4).

Important: For those of you who are more adventurous with formula: When using formula in the Modify Item window, the formula can be as simple or as complex as you need. You can write formula to set values to multiple items at once, using stuff like FIELD, @SetField, or @SetDocField. You can even use formula that isn’t normally applicable in views such as @DBLookup. What is important to remember is that whatever the complexity of your formula, what is returned is applied to the field itself.

Click ‘Apply’.

Fig. 4 Check to make sure you're working on the correct item, and then enter the formula provided (with your values plugged in) into the formula input box, and apply it.

Fig. 4 Check to make sure you’re working on the correct item, and then enter the formula provided (with your values plugged in) into the formula input box, and apply it.

Step 4: Verify your changes.

Once you have applied your formula, you’ll see a confirmation dialog that shows you the number of documents that have been tested against your formula. In this case, 24 documents (fig. 5).

Image of scanEZ's updated document dialog

Fig. 5 Once you have applied your changes, you’ll see a confirmation dialog that lets you know your documents have been checked against the formula you entered.


If that was the only substring to be changed, making all the item’s values uniform, you’ll see that reflected in the Diff panel (see fig. 6). If you need to replace more substrings in the same item, simply repeat this process from step 3, changing the values in your formula as needed.

Image of scanEZ's Diff panel showing a uniform value in the modified item

Fig. 6 Once your formula has been applied and the values are now uniform across all documents, you’ll see that reflected in the Diff panel. If you have more substrings to replace, just repeat from step 3 on.

A flexible tool for item modifications

Depending on what type of information item values contain, some changes might be more important to make than others.

In the example above, having trial periods of 60 days on record instead of 30 could end up being a bad thing. But regardless of how crucial the info is you need to replace, the Diff operation’s easy item targeting and a tiny bit of @formula lets you make quick work out of situations where you have to replace only a small but important substring in a given item across all your documents in a database.

You can find this and other tutorials in our Ytria tutorial space at www.ytria.com/howto. And if you like receiving new EZ Suite tips, don’t forget to subscribe to our newsletter to stay informed about new articles demystifying useful features in EZ Suite tools.

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]