Managing knowledge objects

This section shows some typical use cases for managing objects in the REST API. Use these examples to learn how to perform operations such as moving an object to a different app or changing the permissions of an object.

You can also use the servicesNS endpoints to access resources within a user/app context called the namespace. For more information about using namespaces, see Namespace in the REST API User Manual.

Create a new object for a specific context

Create a saved search for the user Alice that is available from the app, myapp. This saved search is private to Alice.

curl -k -u alice:pass https://localhost:8089/servicesNS/alice/myapp/saved/searches/  \
        -d name=mysearch \
        -d search=*

Edit an object

Change the above search created for Alice.

Because this search is private to Alice, she can edit the search.

curl -k -u alice:pass https://localhost:8089/servicesNS/alice/myapp/saved/searches/mysearch \
        -d search="index=mai*"

Share an object to an app, modify its permissions, and edit it

In general, use the REST handler associated with a knowledge object to programmatically modify it. The search macros and transactions types of knowledge objects, however, do not have an associated REST handler. For these types of knowledge objects, modify them by manipulating the configuration file directly with the /configs endpoint. For more information about the /configs endpoint, see Configuration endpoint descriptions in the REST API Reference Manual.

In either case, modify permissions for knowledge objects with the Access Control List (ACL) endpoints. For more information about the ACL endpoints, see Access Control List in the REST API User Manual.

Consult the following table to determine which method to use for each type of knowledge object. For detailed descriptions of each endpoint, see the REST API Reference Manual.

Knowledge object type	Modification method	REST API endpoint
Data models	REST handler	/datamodel/model/{name}
Event types	REST handler	/saved/eventtypes/{name}
Field extractions	REST handler	/data/transforms/extractions/ or /data/props/extractions/{name}
Fields	REST handler	/search/fields/{name}
Lookups	REST handler	/data/props/lookups/{name}
Navigation	REST handler	/services/directory/{name}
Panels	REST handler	/data/ui/panels
Saved searches	REST handler	/saved/searches/{name}
Search macros	configuration file	/services/configs/conf-macros/{name}
Tags	REST handler	/search/tags/
Transactions	configuration file	/services/configs/conf-transactiontypes/{name}
Views	REST handler	/data/ui/views

Modify an object's permissions with the REST handler

For example, you can make Alice's saved search, mysearch, available through the app, myapp, by using the saved/searches/mysearch REST handler. The following command grants all users permissions to read the saved search.

curl -k -u admin:pass https://localhost:8089/servicesNS/alice/myapp/saved/searches/mysearch/acl  \
        -d perms.read=* \
        -d owner=alice \
        -d sharing=app

Edit the search at the shared location. Because the search is now a shared resource, use <nobody> for the <user> context.

curl -k -u alice:pass https://localhost:8089/servicesNS/nobody/myapp/saved/searches/mysearch  \
        -d search="index=main"

Modify an object's permissions by editing configuration files

Similarly, you can make Bob's macro, mymacro, available globally by editing the macros configuration file. The following command shares mymacro globally and grants write permissions for admin and power roles.

curl -k -u bob:pass https://localhost:8089/services/configs/conf-macros/mymacro/acl 
        -d "sharing=global&owner=nobody"

After you run the command, the macro is available in the main search app.

The following command modifies permissions so that mymacro can still be read by everyone, but is owned and can be written only by users with the admin role.

curl -k -u bob:pass https://localhost:8089/services/configs/conf-macros/mymacro/acl 
        -d "perms.read=*&perms.write=admin&owner=admin&sharing=global"

Move an object to a different app

The saved search that was previously available to all in the context of myapp is now only available in the context of otherapp.

curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/myapp/saved/searches/mysearch/move  \
        -d user=nobody \
        -d app=otherapp

Access objects available in all user/app contexts

Using wildcards, access all saved searches that you have permission to view.

For an admin user, this includes other user's private saved searches.

For a non-admin user, you retrieve only saved searches you have permission to view.

curl -k -u admin:pass https://localhost:8089/servicesNS/-/-/saved/searches

curl -k -u alice:pw https://localhost:8089/servicesNS/-/-/saved/searches