wiki:Handbook/NabuBot

[ User Observation | Handbook ]

The Nabu Protocol

Users can interact with Nabu via the Nabu Bot. The Nabu Bot is a server component listening to user commands.

Using the Nabu Bot, you can

To use the Nabu-Bot, you have to add it to your contact list. Read here for instructions. When the Bot appears in your roster you can send requests to the user as described below. For a detailed description of the responses, read the response reference in the reference section.

Basic Commands

LogPresence

Syntax: LOGPRESENCE ON|OFF|STATUS ON/OFF enables/disables the logging of presence changes. If enabled, all presence changes of the user are logged by Nabu, otherwise Nabu ignores them. By default, presence logging is disabled. STATUS returns whether presence logging is enabled or disabled.

Returns responses 200, 250, 251

LogMessages

Syntax: LOGMESSAGES ON|OFF|STATUS

ON/OFF enables/disables logging of message changes. If enabled, all message sent by the user are logged by Nabu, otherwise Nabu ignores them. By default, message logging is disabled. STATUS returns whether message logging is enabled or disabled.

Possible responses: 201 (status of message logging), 252 (message logging enabled), 253 (message logging disabled)

DeleteMessage

Syntax: DELETEMESSAGE <uri>

Deletes a message. The message must be sent by the message sender, so every user is allowed to delete his own messages, giving him the possibility to remove sensitive information from the server.

Possible responses: 280 (message deleted), 401 (permission denied), 441 (resource not found)

Queries

Query

Syntax: QUERY SPARQL|SEARCHMSG <query>

Queries the user-visible part of the Nabu model. You can either

  • start a simple query using SEARCHMSG: "QUERY SEARCHMSG Nabu" returns all messages whose body contains the string "Nabu" (search is case-insensitive, it also matches "NABU", "NaBu", ...). This is a simple way to query the archive without constructing complex queries.
  • use SPARQL: "QUERY SPARQL <queryString>" executes a query using the SPARQL query language. You can use all types of SPARQL queries: Ask, Select, Describe and Construct. For more information and examples see the 'Searching the Archive' section.

Possible Responses: 210 (query result), 420 (Wrong query syntax)

Model

Syntax: MODEL

Returns the Nabu model as RDF/XML. Resources (and their CBD) not visible by the requesting user are omitted.

Possible Responses: 211 (model as RDF)

ShowCBD

Syntax: SHOWCBD <uri>

returns the CBD of a given URI as RDF/XML. The CBD contains reifications (such as annotations) and left links (links to the resource). If the resource is not accessible by the requesting user, 401 is returned.

Possible Responses: 211 (model as RDF), 401 (permission denied), 441 (resource not found)

Annotations

CreateStatement

Syntax: CREATESTATEMENT LITERAL|RESOURCE <subject> <predicate> <object>

Adds an RDF statement to the graph. The statement is reified and has a property "statedBy" (see Ontology section for details), linking to the account who made the statement. The second token LITERAL|RESOURCE indicates if the object is a literal or a resource URI. For literals, everything after the predicate is considered as the literal string. Possible Responses: 270 (statement created), 401 (permission denied)

DeleteStatement

Syntax: DELETESTATEMENT LITERAL|RESOURCE <subject> <predicate> <object>

Removes all the user's <S, P, O> statements from the model. Statements of other users are not affected. The second token LITERAL|RESOURCE indicates if the object is a literal or a resource URI.

Possible Responses: 271 (Statement deleted), 442 (Statement not found)

Privacy Settings

ListGroups

Syntax: LISTGROUPS

Returns a list of groups defined by the user. The reponse has the format <n> [<groupURI> <groupName>]n where n is the number of user-defined groups

Possible Responses: 230 (group list)

CreateGroup

Syntax: CREATEGROUP <groupName>

creates a group with a given group name. <groupName> may be an arbitrary Unicode string without spaces. group names must be unique per user.

Example: createGroup family

Possible Responses: 265 (group created), 432 (group already exists)

DeleteGroup

Syntax: DELETEGROUP <groupName>

deletes a user-defined group. The group is removed from all policies.

Possible Responses: 266 (group deleted), 433 (group not found)

EditGroup

Syntax: EDITGROUP <groupName> (ADD|REMOVE <accountURI>)| SETPOLICY policyName

Edits a user-defined group. The user can add or remove group members, or set a privacy policy for the member list.

Examples:

'EDITGROUP friends ADD http://foo/Accounts/myserver/alice' adds alice@myserver to the group 'friends'.

'EDITGROUP friends REMOVE http://foo/Accounts/myserver/alice' removes her again.

'EDITGROUP friends SETPOLICY friendsOnly' sets policy 'friendsonly', which might restrict access to the member list to the group members.

Possible Responses: 267 (group edited), 433 (group not found), 441 (account not found), 431 (policy not found)

ListPolicies

Syntax: LISTPOLICIES

lists the names of the user's policies. The format is

<n> [<policyName>]n

Possible responses: 220 (policy list)

CreatePolicy

Syntax: CREATEPOLICY <policyName>

Creates a policy with a given name. The policyName is an arbitrary utf8 string but must not contain any spaces. The new policy is initially empty, i.e. access is denied for everyone except the policy owner. If the policy already exists, an error is returned.

Example: 'CREATEPOLICY friendsOnly' Possible Responses: 260 (policy created), 430 (policy already exists)

DeletePolicy

Syntax: DELETEPOLICY <policyName> <newPolicyName>

Deletes policy <policyName>. All occurences of <policyName> are replaced by the <newPolicyName>.

Example: 'DELETEPOLICY friendsOnly topSecret' deletes policy 'friendsOnly' and sets policy 'topSecret' for all resources that were using policy 'friendsOnly' before.

Possible responses: 262 (policy deleted), 431 (policy not found)

EditPolicy

Syntax: EDITPOLICY <policyName> ADD|REMOVE ALLOWACCOUNT|DENYACCOUNT|ALLOWGROUP|DENYGROUP <uri>

Allows the user to edit his policies. He can add or remove rules, allowing or denying access for groups or single accounts. (Deny, Allow) semantics are used: Access is denied by default and must be explicitely granted using ALLOWACCOUNT or ALLOWGROUP. DENY rules have higher priority: For instance, if Bob is member of group 'friends' and two rules 'ALLOWGROUP friends' and 'DENYACCOUNT bob' exist, access is denied for Bob. The explicit denial has higher priority than the ALLOWGROUP.

Examples:

'EDITPOLICY friendsOnly ADD ALLOWACCOUNT http://foo/Accounts/myserver/bob' adds a rule to allow access for bob@myserver.

'EDITPOLICY friendsOnly REMOVE ALLOWACCOUNT http://foo/Accounts/myserver/bob' removes the rule again.

'EDITPOLICY friendsOnly ADD ALLOWGROUP http://foo/Groups/myserver/bob/BestFriends' allows access for all members in the group 'best friends'.

Possible responses: 263 (policy edited), 431 (policy not found)

ShowPolicy

SHOWPOLICY <policyName>

Returns a description of policy <policyName>, listing all rules.

Possible responses: 221 (policy description), 431 (policy not found)

ShowActivePolicy

Syntax: SHOWACTIVEPOLICY

Like ShowPolicy, but desccribes the currently active policy.

Possible responses: 221 (policy description)

SetActivePolicy

Syntax: SETACTIVEPOLICY <policyName>

Activates policy <policyName>. The currently set policy is attached to sent messages.

Possible responses: 261 (policy set), 431 (policy not found)

ChangePolicy

Syntax: CHANGEPOLICY <URI> <newpolicyName>

Changes the policy for a given resource to <newPolicyName>. The resource must already have a policy owned by the user.

Possible responses: 264 (policy changed), 401 (permission denied), 431 (policy not found), 441 (resource not found)

User Observation

ObserveMessages

Syntax: OBSERVEMESSAGES (ON|OFF resource)|STATUS

enables/disables the user observation. "OBSERVEMESSAGES ON someResource" registers the resource someResource as user observer. All messages from or to foo@bar are notified to foo@bar/someResource. STATUS returns a list of the observing resources.

Possible responses: 202 (obervation status), 254 (user observation enabled), 255 (user observation disabled)

For details see User Observation.

[ User Observation | Handbook ]

Last modified 12 years ago Last modified on 08/04/05 10:13:00