In this blog, I’ll be telling on how to add more attributes to already implemented action types so that it becomes easy to filter out the JSON results that we are getting by calling various APIs.

What are actions?

Actions are a set of defined functionality that how Susi works for special JSON return type from some API endpoint. These include table, pie chart, rss, web search etc. These action types are implemented and defined at the backend(on server). The definition contains several attributes and their data types.

Current action types and their attributes:

• table : {columns, length}
• piechart : {total, key, value, unit}
• rss : (title, description, link)
• websearch : {query}
• map : {latitude, longitude, zoom}

* Please see that these are as of the date of publish of this blog. These are subject to change. Also keep in mind that these are optional attributes.

Need for new attributes:

There are millions of open APIs out there and hence their JSON response structure also varies. Some return a JSON Array and some return a single JSON object. Some might return JSON Array inside a JSONObject. They all varies. So to give proper filters, we may need new action types.

In this blog, we’ll take up the example of how “length” attribute was added. Similarly you can add more attributes to any of the action types.

Some APIs return few as 5 elements in a JSON Array and some give out 100s of elements. So the power of limiting the rows in a particular skill is given to Susi-skill developers only with addition of length parameter.

First things first.. Identify the action type in which you want to add parameters. Browse to SusiMind.java and SusiAction.java files. These are the main files where Susi looks for attributes while evaluating  a dream or a skill.

In SusiAction.java file, find the corresponding public action method which is returning a JSONObject. Currently the method looks like this:

public static JSONObject tableAction(JSONObject cols) {
        JSONObject json = new JSONObject(true)
            .put("type", RenderType.table.name())
            .put("columns", cols);
        return json;
    }

Add a parameter of corresponding data type (attribute you are adding) in argument list. Following this, put that variable in in JSONObject variable (that is json) which also being returned at the end. After changes, the method will look like this:

public static JSONObject tableAction(JSONObject cols, int length) {
        JSONObject json = new JSONObject(true)
            .put("type", RenderType.table.name())
            .put("columns", cols)
            .put("length", length);
        return json;
    }

In SusiMind.java file, find the if condition where other attributes of the corresponding action type are being checked. (sticking to length attribute in table action type, following is what you have to do).

if (type.equals(SusiAction.RenderType.table.toString()) && boa.has("columns")) {                                                                     actions.put(SusiAction.tableAction(boa.getJSONObject("columns"));
}

Now depending on the need, add the conditions in the code, make the changes. The demand of this action type is : if columns attribute is present, then the user may or may not put the length parameter, but if the columns are absent, length will have no value. So now the code gets modified and looks like this :

if (type.equals(SusiAction.RenderType.table.toString()) && boa.has("columns")) {                                                                                                      actions.put(SusiAction.tableAction(boa.getJSONObject("columns"),
         		boa.has("length") ?boa.getInt("length") : -1));
}

But wait.. To see these changes up on Susi, open an issue on the server repo and on all the client repos as well.

Server | ios client | android client | web chat client

Once you are sure things are working as expected, send a pull request to server after making the changes(follow the pull request practices followed at FOSSASIA).