Pursuing my series of blog posts on Dataverse Custom API features, this one will be ‘short and sweet’ and explores the usage of the IsPrivate attribute that can be found on the Custom API Table.
The ability to set an API as a Private message is a unique feature of the Custom API model and does not exist for classic Workflow Custom Actions.
🚨The IsPrivate Attribute is (currently) not available/editable using the out-of-the-box Custom API authoring experience (Model-Driven form). That’s a very good reason to try my Custom API manager tool for XrmToolBox where the attribute can be set easily. 😏
Keep It For Yourself
As per Microsoft documentation, a Custom API with IsPrivate set to true will be hidden (ghosted) from metadata and documentation. Meaning it will not be discoverable by metadata queries running against the Dataverse environment.
A good use case for this functionality is for an ISV scenario. For instance, If you develop and ship products/extensions that are installed on your customer’s Dataverse environments, you may want to leverage the power of Custom APIs for the internal operations of your product.
Now, for obvious functional and IP reasons, you don’t necessarily want to expose your Custom APIs signature to other users/developers of the environments where your product is installed. That is where the IsPrivate attribute might come useful.
However, It’s important to understand that even if a Custom API is hidden, anyone who knows the existence and the signature (inputs/outputs) of a private message will be able to use it like any other (public) Custom APIs. So if you really want to completely lock your Custom API from ‘nosy’ 👃 developers, you will have to implement some kind of authorization mechanism. (out of the scope of this blog post)
Tooling in a Private Message context
Setting a Custom API as private also has side-effects on any tooling that uses metadata queries. For example, tools like crmsvcutil will skip Private Messages when generating ‘early bound’ classes.
If you really need to generate early bound classes for a Private Message, here is a workaround.
1- Uncheck the IsPrivate attribute temporarily
Using the Custom API Manager tool for XrmToolBox, you can set the IsPrivate attribute to False
2- Generate Early Bound Classes
Generate your early bound classes like you would normally do. I’m using Daryl Labar EarlyBound Generator for XrmToolBox in the example below, which is a wrapper around the crmsvcutil tool. You can see that when I generate classes for the Actions, my Custom API gets picked-up by the tool.
You can then use the generated early bound class of your Custom API in your other plugins assemblies or external programs.
3- Put back the IsPrivate flag on the API
Now you can set the IsPrivate attrtibute back to true and ship your Private Custom API to end-users.
Extending Private Messages
One thing I noticed while playing around with the feature is that even if you set your API to be extendable by 3rd parties (AllowCustomProcessingStep = SyncAndAsync) (see my previous blog post on that matter) and your API is marked as Private, you will not be able to attach a plugin step on the message using the plugin registration tool.
This makes sense since the plugin registration tool needs to make a metadata query to show available messages where you can attach a plugin step.
Summary
There is not much more to say, the name of the IsPrivate attribute speaks by itself. It gives Dataverse developers a way to hide Custom API messages by making them impossible to discover. It’s a feature that is unique to the Custom API model and it can have a real business value in certain scenarios.
Happy API‘ing!
Links
Post Image by PublicDomainPictures from Pixabay
❤️