About Salto: Salto's platform helps you and your team deploy, track, and manage your NetSuite customizations effortlessly. Learn more here.

‍

Saved searches are a powerful and versatile tool in NetSuite’s SuiteAnalytics offering. One limitation of searches, however, is that the search definition is encoded. This makes it difficult to understand the configuration of a search, track changes, and/or explore the metadata to answer common questions like “Which saved search triggered that email?”. 

In this article, I’ll show you how you can leverage Salto for free to decode saved search metadata. This article is relevant for NetSuite administrators, developers, consultants, (super-)users, and anyone else actively involved in creating, deploying, and/or managing saved searches in a NetSuite environment.

‍

‍

Challenge

If you’ve ever tried to download a saved search via the XML export option in the UI or via SDF, you will notice that the output is encoded and effectively gibberish to the human eye. 

‍

‍

Take a look at the representation of the sample saved search we will be reviewing in this article. Notice that the definition is a blob of characters that one cannot decipher. 

‍

‍

It is unclear why NetSuite chose to encode saved search definitions especially given that pretty much all other artifact definitions are exported in a human-readable XML format. I suspect that this was one of the first record types to be made available for export and, at the time, there was a security/obfuscation consideration at play, which makes sense. Then again, it could also have been done to prevent curious users like me from attempting to edit searches via the XML definition! In any case, the reason for the status quo is not so relevant. What is important is that Salto decodes the base64-encoded XML definition, thus producing a human-readable format of saved search definitions! For the interested reader, the decoding logic is actually open-source.

‍

Decoded Saved Search Metadata

Here’s the same search as above pulled from NetSuite using Salto. Salto uses the NaCl format, an hcl-based declarative configuration language, with semantics purpose-built to describe the configuration of business applications. Notice that in addition to the encoded saved search definition, we have the definition in a human-readable format. This is huge (and I’ll tell you why shortly)!

‍

‍

For conciseness, I collapsed the different sections in the screenshot above. And while there is no documentation of the structure, anyone familiar with saved searches can easily map the different fields and sections to the corresponding saved search fields.

For example, here’s the available filters’ definition in the search and the corresponding NaCl. 

‍

‍

The NACL is pretty intuitive if you ask me.

‍

‍

Let’s now turn our attention to use cases that illustrate the value of having access to this metadata.

‍

A Few Use Cases For Saved Search Metadata

While there are more, let’s look at three main groups of use cases for which access to saved search metadata literally saves the day.

1. Tracking Down the Saved Search That…

You may have been in this situation before: You need to tweak the output of an email being triggered by a saved search but cannot locate the saved search. Or a user is complaining about receiving an email that they no longer need. You know it’s coming from a saved search but there’s no saved search with the email subject line. There are lots of searches in the account so checking each of them to see which one has the customized subject line that matches your email is too cumbersome. You’re distressed. While there is a known trick to address this challenge, it’s way easier to simply pull your searches into Salto and use the search bar to track down the saved search, thanks to the metadata being exposed. Finding the source of that email has not been so easy!

‍

There are several other use cases that belong to this category of “finding a search that…”, for example:

• Finding a search that uses a particular (custom) field. Again, the Salto offering is much easier than the alternatives out there.
• Finding searches that are not scheduled but send emails upon record creation/update. As illustrated below, the native option does not provide sufficient filters to identify specific flags that control saved search emails but the metadata exposes those flags.

‍

‍

2. Identifying What Changes Have Been Made to a Search

As a good NetSuite admin/developer/change manager, before deploying changes from Sandbox to Production, you need to ensure that (i) you know what changes you are about to deploy; (ii) you are deploying only what you should be deploying. Salto offers several capabilities in this regard. Access to saved search metadata makes it easier to do a “diff” between Sandbox and Production to see what has changed and assess whether it is what you expect.

Here’s a sample Salto deployment after I made some changes to my example saved search. Let’s play a quick game of “spot the difference”. Solely based on the diff from Salto below, see if you can understand/identify the changes I made…

‍

‍

‍

Easy right? I:

1. Customized the email subject line.
2. Unchecked the flag “Allow Audience to Edit” (FLAG_GLOBAL_EDIT).
3. Unchecked the public flag to restrict access.

Okay, (I) and (III) were probably easier to figure out than (II). However, as you play around with the flags, you’d recognize them faster. Moreover, it’s almost a trivial exercise to produce a mapping of the search metadata to fields in the saved search UI, if desirable.

Compare the above to the defacto approach of reviewing the audit trail:

• The audit trail is a log of all changes. Thus, if I changed something and reverted it, there will be multiple entries. Thus, using the audit trail, one has to work from top to bottom to ensure we’re looking at the latest change.
• Finding what changed via the audit trail requires multiple clicks.
• Most importantly, the same component name might be used for very different changes, making it hard to know which row to inspect!

‍

‍

Suffice it to say that using the audit trail as a means of change control is futile. On the other hand, a clear and concise “diff” like the one shown earlier that identifies what changed in a human-understandable format, is ideal.

‍

3. Recovering from “An Unexpected Error Has Occurred”

Every once in a while, saved search gets corrupted. You edit the search, get a spurious “unexpected error” message similar to the one below and then you’re unable to open the search in edit mode after that (you might still be able to view the search results though which is rather weird).

Granted, it does not happen very often but when it does, it is usually on searches with complex criteria/formulas. The few times that I encountered this, I was never able to fix the search and had to recreate it. But then, how do you remember all that complex logic in the formulas?! It was frustrating, to say the least. With the metadata in human-readable format, recovering from such unfortunate situations would be much easier as I would be able to reverse engineer the search albeit still manually. This is admittedly a more advanced use case and a rarity. However, I hope that if you ever run into it, you’d remember Salto.

‍

Limitations

I observed the following limitations based on tests.

Named recipients are not captured

Although my search included named users as illustrated below, they did not show up in the metadata. This is consistent with general NetSuite behavior where account-specific values like users are dropped. Nevertheless, I was really hoping that this would somehow get captured as it would have solved another long-standing annoyance I’ve faced when trying to detect who is receiving which search-triggered emails. I’ve come close with a complex Analytics Audit Trail saved search but there were edge cases where it failed. I hope someday to have a proper solution. I’ve reached out to the Salto team to find out if they can extend their magic to grab this information. That would be amazing!

‍

‍
Note that “Recipients from Results” are captured as illustrated below. That makes sense as these are dynamic references, not account-specific values.

‍

Highlighting is not captured

I also observed that conditional highlighting did not show up in the decoded metadata. It appears Salto has not yet implemented decoding this part of the metadata as it is present in the definition based on my tests.

‍

‍

Changes Made to the Metadata are Ignored by Salto

Wouldn’t it be great if you could change the metadata in Salto and have it deployed to your account? Practical example: During your predeployment comparison, you notice a typo in the subject line of your saved search email. Ideally, you’d just fix it and deploy. Nah! The Salto team confirmed that they do not support modifications to the metadata; the information is provided for viewing only. That kind of makes sense. Supporting edits will require being able to generate a new search definition blob that NetSuite accepts. Perhaps it is possible to do so since Salto is able to decode the blob… Looking at the bright side, at least Salto will help you detect the typo, giving you a chance to fix it in the source account, recalculate your deployment plan (read: refresh the data), and deploy. Alternatively, you might decide to deploy and fix the issue in the target account post-deployment.

‍

Coming Soon…

The Salto team is in the final stages of development of similar mechanisms for decoding NetSuite Saved Reports and Financial Layouts. If you’re interested, click here to get notified when these features are launched.

‍

‍

Conclusion

Why exactly NetSuite saved search definitions are encoded remains a mystery. However, if you'd like to decode them, Salto can do it for you—and it's even included in the free version of Salto.” (Note that while the ability to decode the search metadata is part of the free version, deploying changes between environments is a paid feature.) If you’re new to Salto, I encourage you to check it out and learn how it can make your NetSuite change management process come alive.

Have you come across any other use cases where being able to decode the saved search definition has been helpful? We’d love to learn more. Please drop a comment below and tell us about it.