Registering an Intent Handler on the Intents Api

Registering an intent handler means to share some functionality of an application with other applications.

Before registering a handler, refer to the following frequently asked questions:

What is the /type/sub-type of my expected data?

The /type/sub-type of an intent handler specifies the required data schema of your intent. When defining an intent handler, if public utilization of your application is desired, utilize a community-driven /type/sub-type path.

If your intent use is private to your applications, utilize /application/vnd.{uniqueName}, where {uniqueName} is some dot-separated unique name for your application (ex. com.ozp.intentExample).

Documentation on /type/sub-type paths are developed based on community support. As the IWC is in its infant years of community use, if you can't find documentation on your desired data type, it is very well possible you are the first to use it. Open an issue with the data type/subtype, proposed schema, and a description. The IWC Community Intent Book is a community driven set of data type documents used as a centralized resource for developers.

What is action my function handles?

The action is the verb of the handler, it should be a single word describing what the intent handler does (print, graph, map, ect). As stated above, check the Community Intent Book for community-driven formatting and actions.

What if the /type/sub-type/action I want to use is already in the Community Intent Book?

This is ideal! If your desired /type/sub-type/action exists in the Community Intent Book, this does not mean your application isn't desired. This means the functionality you would like to produce has been developed by others, if their functionality doesn't meet your needs or you would like your own version as long as you maintain the defined data schema developers and users can use your application interchangeably.

Don't agree with a defined format? If you have supporting reason to modify the schema open an issue. If there is enough community support we will consider the modification. This will push the new data type to a versioned name (ex. /json/location would become /json/location;version=2).

Accessing Intents Api

To register a function, a reference to the Intents Api from the client is needed. This follows the same format as the Data Api, the intents reference can come from the same client object as data.

var client = new ozpIwc.Client({peerUrl: "http://ozoneplatform.github.io/ozp-iwc"});
var intents = client.intents();

Register: sharing a function

Parameters

Options.entity

Returns

A promise that resolves with a response object upon handling of the request:

Callback

The callback receives 2 parameters: 1. reply: contains various information about an intent. For the introductory purposes of intent registrations, only reply.entity is covered here, other properties will be covered for more advanced intents in a later tutorial. 2. done: A function to call to stop handling intent requests. Useful for conditionally stopping intent handling.

The return value of the callback is returned to the intent invoker. This means when developing an application, if there is some complex computation an application can do that other applications may also need (complex sorting for example), returning the value of the intent handling means other applications can leverage the functionality.

Invoking: calling an intent function

Invoking an intent function across the IWC is done with the invoke action. It is covered in its own tutorial. For purpose of seeing the above code snippet work, click the button on the example below.