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

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.

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")

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).

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).

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).

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")

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’.

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).

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.

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.