These days, almost every company out there is trying to automate
boring sensible tasks by creating scripts and procedures, and obviously, it would not be different in the Sitecore world.
Having scheduled tasks to upgrade your Sitecore modules on Azure and scripts of all sorts which are responsible for installing, upgrading, configuring or more, is not only necessary to keep the process safe but mandatory if you want to keep your developers happy. Trust me.
Let’s be honest, who in the earth like being up at 2:00 AM to upgrade that module or change that configuration that could (but shouldn’t) put your entire website down?
Hopefully, Coveo listened to the community and built a very complete set of restful APIs with which you can interact to achieve pretty much the same you would achieve using Sitecore administrator console and/or configuration files.
In this first blog post, I will share my thoughts more precisely about the Coveo for Sitecore Configuration Service API.
The Configuration Service API
Coveo created all those services which are somehow related to your Sitecore instance configuration and that you can [and should] use to automate the Coveo package configuration, activation and more. And the best part is that it is automatically documented on your own instance using Swagger UI.
For those who are not familiar with the Swagger UI thing, you can use this auto-generated documentation interface to not only see the API sections and methods but easily call each one of them in order to be able to test their behavior on your Sitecore instance.
Note that it is 100% versioned. That’s code for 1) There is more to come in the near future. 2) You can use those methods in your scripts without the fear that a future breaking change will explode your entire instance.
The sections are almost self-explained so I won’t waste your time going through every single method. Basically, Coveo provides a few methods to check whether your Coveo for Sitecore package is already activated (which means basically that the Coveo configuration files had the .example extension removed) and properly activate it if it is not.
Before activating your Coveo for Sitecore instance, you better configure it using the PUT method you can see above, otherwise, your activation will fail. If you don’t know exactly which values pass in the body of this call, stay tuned because I have a little surprise at the end of this article for you.
Current Organization / Organizations
Use those methods to any operations related to the current organization already configured on your instance or even Coveo organizations in general, such as creating one, creating API keys for the current organization, synchronizing Cloud license with your Sitecore instance, etc.
Do I really need to say something?
Bonus Track: The Silent Install Script
All that being said, I think that we can all agree that the most obvious use case for all those methods is to automate package configuration and its activation, avoiding all those required manual steps that I show here. In the past Coveo required manual interaction during its package installation, and because of that, it was impossible to silently install its package using some cool script.
At the same time, thanks to the unstoppable #SitecoreMVP Michael West and the Sitecorian Adam Najmanowicz, PowerShell has become the law when it comes to scripting something related to Sitecore.
That’s why, ladies and gentlemen, Coveo created and provided to the community two PowerShell scripts, so you, my dear friend, don’t have to re-write something that was already written by another colleague.
function Configure-CoveoForSitecorePackage([Parameter(Mandatory=$true)] [string] $SitecoreInstanceUrl, [string] $CoveoForSitecoreApiVersion = "v1", [string] $OrganizationId, [string] $ConfigApiKey, [string] $SearchApiKey, [string] $CoveoSitecoreUsername, [string] $CoveoSitecorePassword, [string] $DocumentOptionsBodyIndexing = "Rich", [boolean] $DocumentOptionsIndexPermissions = $true, [string] $FarmName, [Parameter(Mandatory=$true)] [string] $ScriptSitecoreUsername, [Parameter(Mandatory=$true)] [string] $ScriptSitecorePassword)
function Activate-CoveoForSitecorePackage([Parameter(Mandatory=$true)] [string] $SitecoreInstanceUrl, [string] $CoveoForSitecoreApiVersion = "v1", [Parameter(Mandatory=$true)] [string] $ScriptSitecoreUsername, [Parameter(Mandatory=$true)] [string] $ScriptSitecorePassword)
You can find the entire methods and how to call them on the official documentation Coveo created on the subject. It’s really worth the read, trust me.
If you already know the Coveo Command-Center, you know how powerful this new interface is. And the good news is that for each operation you can do there, there is an API behind which can be used by you on your scripts.
The Configuration API is only one of the API Coveo provides. In the next blog post, I’ll dig deeper on the so much loved Coveo Index API Services and how you can use it to manipulate the indexed fields list without touching any configuration file. Stay tuned!
One thought on “Coveo for Sitecore 5: The Configuration Services API”