What we are talking about...
A common task when transporting portal content from one portal to another - during upgrade transports or transporting content and definitions through the stages of one landscape for example - is to transport the index definitions which are normally to be seen under "System Administration" - "System Configuration" - "Knowledge Management" - "Index Administration".
So the scenario is: You have defined several indexes at that place and want to create the same situation on a different portal.
The issue is: There is no official way to do so.
The good news is: It is possible nevertheless; anyhow, for transporting permissions on indexes, we need to create some component to do so, as this is not possible by standard means.
Transport TREX indexes or portal index definitions?
When talking about "transporting indexes", we have to be clear of which side we are talking - the portal side or TREX side. If we have two portals and two TREX instances with the same indexes defined on the portal and created on the corresponding TREX side, the mechanism to transport the content of the index - technically that is the index itself - is a basic task within the TREX administration; it is well documented at Exporting and Importing Indexes - Search and Classification TREX - SAP Library (especially when you follow the Link to Data Backup (Online) and Restore - Search and Classification TREX - SAP Library).
But that doesn't help with the task we are talking about. When someone created let's say 100 index definitions on portal side, he/she won't be lucky to do the same on the next stage or do it again when an upgrade (through a fresh installation and transporting the old content) is planned. But to get a clue which objects have to be transported to fulfill this task, we should have a basic understanding of how the index definition and creation works.
Some basic understanding of how the index definitions are used on portal and TREX side
What happens if you create an index via the portal administrative UI?! On the one hand, within the config framework, there are entries created for the new index. Technically, within the config framework, they are to be found under "cm" - "services" - "indexes" (there: differentiated between TrexIndex, PcdIndex and maybe your own implementation) and under the subfolders "index_folders" and "taxonomies" (also see Lorcal Bouchier's answer in Create/Delete of Index through TREX Administrat... | SCN). Within the standard mode of the config framework, you won't see these entries when navigating to "Content Management" - "Global Services" (which are the UI names for "cm" - "services"). But if you activate the export mode (via "Actions" - "Export" - "Start"), you can see these! We will return to this point later; the UI where you can watch this looks like this - during export mode:
But first, we have to realize that there is another mirror of the configuration. If you call /irj/go/km/navigation/indexmanagement (expecting that the /irj/go/km mimic is activated, otherwise use /irj/servlet/prt/portal/prtroot/com.sap.km.cm.navigation/indexmanagement), you will be surprised to see your index definitions again, here as RDF files (see https://en.wikipedia.org/wiki/RDF/XML).
The indexamanagement repository manager definition is also not to be seen in the config framework in standard mode. Anyhow, in export mode you can see the existence and the configuration under "Content Management" - "Repository Managers" - "Indexmanagement Repository":
The "Hide in Root Folder" setting is the reason why you might never have seen it before. Now, "almost everything" of an index defintion can be seen when exporting the config items or watching the RDF files - but beneath the index definition parameters (like "ID", "Name", "Group", etc) one also can define permissions on an index, which according to my experience is used seldom, but sometimes very efficiently. In such a situation, transporting "all but permissions" does not really help sooo much, as (re)defining permissions on 100 indexes is almost as much fun as creating the indexes completely by hand. We will come back to this, too...
The last technical step when creating an index (better: creating an index definition) on portal side is of course creating the corresponding "real" technical index on TREX side; or to be even a bit more precise: Creating one corresponding queue and one corresponding index on TREX side.
So if we create an index via the portal admin UI, we create different things on different systems. Sometimes one might get some trouble if the information is not synchronized between the systems, i.e. if the portal has different settings than TREX. Let's not get into the details of such corner cases, but one: You have created an index via the portal admin UI, by this also created the queue and the index on TREX side, and now you delete both elements on TREX side without having the information deleted on portal side. The good thing is: If you now reindex this index via the portal admin UI, the queue and the index automatically get re-created on TREX side. And that's why a transport just of the portal data is sufficient!
Transport index definitions without permission settings
To transport the index definitions, you can just export the indexes as described above: Activate the CM export, go to "Content Management" - "Global Services" - "Indexes" - "Trex Index", mark all, export, and (important!) mark "Include referenced configuration objects"; that way, also at least the corresponding "index_folders" (the datasource metadata from the config framework) gets exported.
If you transport such a package, you can "reindex" these indexes (on a clean TREX instance) on the target system and the queues and indexes automatically get created on TREX side. So far, this blog is just a deeper version of Loran's anwer referenced above or my short summaries in Portal Index Transportation, Transporting KM documents and TREX indexes | SCN, or how to transport portal index | SCN.
Transport permissions of the RDF files in /indexmanagement
OK, the last part now are the permissions. If you have some experience with transporting KM content (Transporting KM Content - Content Administration - SAP Library), one might think that maybe it is possible to transport the indexmanagement content, too (and that would be: including ACLs). What in fact is possible is to export the content by standard means. The normal export mechanism allows not only to choose the to-be-exported RID via the KM UI, but also just to fill in the RID itself, in this case "/indexmanagement".
Anyhow, don't think too much about it. The indexmanagement repository is not writable, so importing the content will just lead to error messages. The only thing we can do is to export the ACLs and import them - luckily, if you remember the screenshot from above, the repository comes with an AclSecurityManager, well known to KM developers. And that in fact is the place where the index permissions are persisted.
I have created an EAR file (7.3) with two components, one export and one import component, source code included. These components have been created within project work for one-time-usage and come very minimalistic. The export component can be called and returns pure XML (watch the http-answer's "html" source, copy and save the content as XML), the import component expects the (exported) metadata as "IndexPermissions.xml" within the project itself (at the root of com.dbeutner.km.trex.securitytransportcore.jar, where an empty placeholder can be found in the attached EAR). Please, don't complain about the missing UI, code beauty etc pp - if you want to polish and/or extend the stuff, feel free to use it! Also, if you want to get some general idea about how to transport / work with ACLs, a look at the source code might help, too!
You should know what you do...
If you plan to transport indexes, not to mention if you plan to transport indexes including permissions, you really should know what you do; if you are using the EAR provided, you should be a developer with at least some basic KM dev experience. The complete scenario is nothing which is supported by SAP, so if you run into trouble, you will have to help yourself (and no, I don't plan to offer general support for this via blog comments, as usually I don't have the time).
As always: Hope it helps somebody... Happy transporting!
- SAP Managed Tags:
