WebsiteGitHubSlackLogin

6. Tools

Tools

Tools are services that run on your Data. Like the Sentiment Analysis tool that tells you when your social media posts are positive, negative or neutral. There are a few Tools available but many more are to come. Working with Tools is pretty similar with the Applications and Data Plugs.

Getting Existing Tools

You can easily fetch the available tools using the following function:

HATToolsService().getAvailableTools(
            userDomain: userDomain,
            userToken: userToken,
            completion: gotAppsFromDex,
            failCallBack: errorGettingApps)

  • userDomain is the user's PDA address used to form the url to fetch the available Tools

  • userToken is the user's token to authenticate with the PDA

  • completion is a callback function that is used when the request is successful with a type of ((List<HATToolsObject>, String?) -> Unit).

    The first parameter is an array of HATToolsObject. This is the structure of Tools. More on that in the next section.

    The second parameter is an optional String, the refreshed user token that the PDA returns.

  • failCallBack is a callback that is used when the request has failed. The type of the function is ((HATError) -> Unit). HATErroris a custom object describing the errors that have occurred during the querying of the tables in the database.

A successful response will have statusCode 200 and look like this:

[
    {
        "id": "sentiment-tracker",
        "info": {
            "version": "1.0.0",
            "versionReleaseDate": "2018-01-01T12:00:00.000Z",
            "name": "Sentiment Tracker",
            "headline": "Sentiment in your words",
            "description": {
                "text": "Sentiment Tracker analyses your texts on Facebook, Twitter and Notables to work out how negative or positive your postings are."
            },
            "termsUrl": "https://hatdex.org/terms-of-service-hat-owner-agreement",
            "supportContact": "[email protected]",
            "graphics": {
                "banner": {
                    "normal": ""
                },
                "logo": {
                    "normal": "https://github.com/Hub-of-all-Things/exchange-assets/blob/master/Sentiments/logo.png?raw=true"
                },
                "screenshots": [
                    {
                        "normal": "https://github.com/Hub-of-all-Things/exchange-assets/blob/master/Sentiments/Screenshot1.jpg?raw=true"
                    },
                    {
                        "normal": "https://github.com/Hub-of-all-Things/exchange-assets/blob/master/Sentiments/Screenshot2.jpg?raw=true"
                    }
                ]
            },
            "dataPreviewEndpoint": "/she/feed/she/sentiments"
        },
        "developer": {
            "id": "hatdex",
            "name": "Dataswift Ltd",
            "url": "https://hatdex.org",
            "country": "United Kingdom"
        },
        "trigger": {
            "triggerType": "individual"
        },
        "dataBundle": {
            "name": "data-feed-counter",
            "bundle": {
                "she/insights/emotions": {
                    "endpoints": [
                        {
                            "endpoint": "she/insights/emotions",
                            "mapping": {
                                "message": "text",
                                "timestamp": "timestamp"
                            }
                        }
                    ],
                    "orderBy": "timestamp",
                    "ordering": "descending",
                    "limit": 20
                },
                "notables/feed": {
                    "endpoints": [
                        {
                            "endpoint": "rumpel/notablesv1",
                            "mapping": {
                                "message": "message",
                                "timestamp": "created_time"
                            }
                        }
                    ],
                    "orderBy": "created_time",
                    "ordering": "descending",
                    "limit": 20
                },
                "she/insights/emotions/negative": {
                    "endpoints": [
                        {
                            "endpoint": "she/insights/emotions/negative",
                            "mapping": {
                                "message": "text",
                                "timestamp": "timestamp"
                            }
                        }
                    ],
                    "orderBy": "timestamp",
                    "ordering": "descending",
                    "limit": 20
                },
                "twitter/tweets": {
                    "endpoints": [
                        {
                            "endpoint": "twitter/tweets",
                            "mapping": {
                                "message": "text",
                                "timestamp": "lastUpdated"
                            }
                        }
                    ],
                    "orderBy": "lastUpdated",
                    "ordering": "descending",
                    "limit": 20
                },
                "facebook/feed": {
                    "endpoints": [
                        {
                            "endpoint": "facebook/feed",
                            "mapping": {
                                "message": "message",
                                "timestamp": "created_time"
                            }
                        }
                    ],
                    "orderBy": "created_time",
                    "ordering": "descending",
                    "limit": 20
                },
                "she/insights/emotions/neutral": {
                    "endpoints": [
                        {
                            "endpoint": "she/insights/emotions/neutral",
                            "mapping": {
                                "message": "text",
                                "timestamp": "timestamp"
                            }
                        }
                    ],
                    "orderBy": "timestamp",
                    "ordering": "descending",
                    "limit": 20
                },
                "she/insights/emotions/positive": {
                    "endpoints": [
                        {
                            "endpoint": "she/insights/emotions/positive",
                            "mapping": {
                                "message": "text",
                                "timestamp": "timestamp"
                            }
                        }
                    ],
                    "orderBy": "timestamp",
                    "ordering": "descending",
                    "limit": 20
                }
            }
        },
        "status": {
            "available": true,
            "enabled": true,
            "lastExecution": "2018-11-12T10:29:36.724Z"
        }
    }
]

  • id is the Tool id on the PDA. You need this when you want to enable or disable a Tool.

  • info Has all the information you will need to present the Tool. It is been formed by 10 values:

    1. version is the version number of the Tool. Tools like Applications and Data Plugs can be updated. This will result a new version.

    2. versionReleaseDate is the date that the latest version was pushed in ISO format.

    3. name is the official name of the Tool.

    4. headline is a small text to compliment the name. Used like a subtitle.

    5. description allows you to describe your app better with longer text. Also, it has support for different formats of text, text, markdown and html .

    6. termsUrl is a URL of the terms and conditions. Users must be able to read them if they wish.

    7. supportContact a support email. Users will use this email to contact you.

    8. dataPreview is actually an array of SheFeed structures. This is used to preview items, if any, instead of making another network request to fetch those items. The array can be empty. Optional

    9. graphics is a structure formed by 3 values:

      1. banner is the URL of the banner image

      2. logo is the URL of the app logo image

      3. screenshots is the URL of the app's screenshots used to showcase what this app offers.

        All the above 3 values use the same structure. HAT images can be categorised as small, normal, large and xlarge. Except normal, all are optional values.

    10. dataPreviewEndpoint is a URL that you can use to fetch the 'feed' of the Tool. You have to form the URL like .this: "https://$hatAddress/api/v2.6$dataPreviewEndpoint"

  • developer consists of some basic info about the developer. This includes: id, name, url and country.

  • status is formed by 4 values describing the state of the Tool:

    1. available indicates if the Tool is available. A Tool can be unavailable, for example, when in testing. Default value is false.

    2. enabled indicates if the Tool is enabled by the user. Default value is false.

    3. lastExecution is an optional String that has a date in an ISO format indicating the date that the Tool run for the last time.

    4. executionStarted is an optional String that has a date in an ISO format indicating the date that the Tool started running for the last time.

  • dataBundle is out of the scope for this guide. Here you can find the permissions needed in order for the Tool to run.

  • trigger describes the frequency that the Tool will be executed. Tools are not running all the time. The possible values are: periodic, individual and manual.

A request that has failed will look like this:

{
  "error": "Not Authenticated",
  "message": "Not Authenticated"
}

  • error is the error that has occurred

  • message is a more descriptive message about the error that has occurred

Enabling / Disabling Tools

Enable Tool

You can easily enable a tool by using the function below:

HATToolsService().enableTool(
      toolName: selectedTool.id,
      userDomain: userDomain,
      userToken: userToken,
      completion: toolStatusChanged,
      failCallBack: errorInteractingWithTool)

  • toolName is the id of the tool. It can be the same as the name or not.

  • userDomain is the user's HAT address used to form the url to enable the Tool.

  • userToken is the user's token to authenticate with the PDA.

  • completion is a callback. It is called when the request is successful with a type of ((HATToolsObject, String?) -> Unit).

    The first parameter is the now enabled HATToolsObject. The second parameter is an optional String, the refreshed user token that the PDA returns.

  • failCallBack is a callback that is used when the request has failed. The type of the function is ((HATError) -> Unit). HATErroris a custom object describing the errors that have occurred during the querying of the tables in the database.

A successful response will have statusCode 200 and look like this:

{
    "id": "sentiment-tracker",
    "info": {
        "version": "1.0.0",
        "versionReleaseDate": "2018-01-01T12:00:00.000Z",
        "name": "Sentiment Tracker",
        "headline": "Sentiment in your words",
        "description": {
            "text": "Sentiment Tracker analyses your texts on Facebook, Twitter and Notables to work out how negative or positive your postings are."
        },
        "termsUrl": "https://hatdex.org/terms-of-service-hat-owner-agreement",
        "supportContact": "[email protected]",
        "graphics": {
            "banner": {
                "normal": ""
            },
            "logo": {
                "normal": "https://github.com/Hub-of-all-Things/exchange-assets/blob/master/Sentiments/logo.png?raw=true"
            },
            "screenshots": [
                {
                    "normal": "https://github.com/Hub-of-all-Things/exchange-assets/blob/master/Sentiments/Screenshot1.jpg?raw=true"
                },
                {
                    "normal": "https://github.com/Hub-of-all-Things/exchange-assets/blob/master/Sentiments/Screenshot2.jpg?raw=true"
                }
            ]
        },
        "dataPreviewEndpoint": "/she/feed/she/sentiments"
    },
    "developer": {
        "id": "hatdex",
        "name": "Dataswift Ltd",
        "url": "https://hatdex.org",
        "country": "United Kingdom"
    },
    "trigger": {
        "triggerType": "individual"
    },
    "dataBundle": {
        "name": "data-feed-counter",
        "bundle": {
            "she/insights/emotions": {
                "endpoints": [
                    {
                        "endpoint": "she/insights/emotions",
                        "mapping": {
                            "message": "text",
                            "timestamp": "timestamp"
                        }
                    }
                ],
                "orderBy": "timestamp",
                "ordering": "descending",
                "limit": 20
            },
            "notables/feed": {
                "endpoints": [
                    {
                        "endpoint": "rumpel/notablesv1",
                        "mapping": {
                            "message": "message",
                            "timestamp": "created_time"
                        }
                    }
                ],
                "orderBy": "created_time",
                "ordering": "descending",
                "limit": 20
            },
            "she/insights/emotions/negative": {
                "endpoints": [
                    {
                        "endpoint": "she/insights/emotions/negative",
                        "mapping": {
                            "message": "text",
                            "timestamp": "timestamp"
                        }
                    }
                ],
                "orderBy": "timestamp",
                "ordering": "descending",
                "limit": 20
            },
            "twitter/tweets": {
                "endpoints": [
                    {
                        "endpoint": "twitter/tweets",
                        "mapping": {
                            "message": "text",
                            "timestamp": "lastUpdated"
                        }
                    }
                ],
                "orderBy": "lastUpdated",
                "ordering": "descending",
                "limit": 20
            },
            "facebook/feed": {
                "endpoints": [
                    {
                        "endpoint": "facebook/feed",
                        "mapping": {
                            "message": "message",
                            "timestamp": "created_time"
                        }
                    }
                ],
                "orderBy": "created_time",
                "ordering": "descending",
                "limit": 20
            },
            "she/insights/emotions/neutral": {
                "endpoints": [
                    {
                        "endpoint": "she/insights/emotions/neutral",
                        "mapping": {
                            "message": "text",
                            "timestamp": "timestamp"
                        }
                    }
                ],
                "orderBy": "timestamp",
                "ordering": "descending",
                "limit": 20
            },
            "she/insights/emotions/positive": {
                "endpoints": [
                    {
                        "endpoint": "she/insights/emotions/positive",
                        "mapping": {
                            "message": "text",
                            "timestamp": "timestamp"
                        }
                    }
                ],
                "orderBy": "timestamp",
                "ordering": "descending",
                "limit": 20
            }
        }
    },
    "status": {
        "available": true,
        "enabled": true,
        "lastExecution": "2018-11-13T12:36:59.061Z"
    }
}

A request that has failed will look like this:

{
  "error": "Not Authenticated",
  "message": "Not Authenticated"
}

  • error is the error that has occurred

  • message is a more descriptive message about the error that has occurred

Disable Tool

HATToolsService().disableTool(
      toolName: selectedTool.id,
      userDomain: userDomain,
      userToken: userToken,
      completion: toolStatusChanged,
      failCallBack: errorInteractingWithTool)

  • toolName is the id of the tool. It can be the same as the name or not.

  • userDomain is the user's PDA address used to form the url to disable the Tool.

  • userToken is the user's token to authenticate with the PDA.

  • completion is a callback function that is used when the request was successful with a type of ((HATToolsObject, String?) -> Unit).

    The first parameter is the now disabled HATToolsObject. The second parameter is an optional String, the refreshed user token that the PDA returns.

  • failCallBack is a callback that is used when the request has failed. They type of the function is ((HATError) -> Unit). HATErroris a custom object describing the errors that have occurred during the querying of the tables in the database.

A successful response will have statusCode 200 and look like this:

{
    "id": "sentiment-tracker",
    "info": {
        "version": "1.0.0",
        "versionReleaseDate": "2018-01-01T12:00:00.000Z",
        "name": "Sentiment Tracker",
        "headline": "Sentiment in your words",
        "description": {
            "text": "Sentiment Tracker analyses your texts on Facebook, Twitter and Notables to work out how negative or positive your postings are."
        },
        "termsUrl": "https://hatdex.org/terms-of-service-hat-owner-agreement",
        "supportContact": "[email protected]",
        "graphics": {
            "banner": {
                "normal": ""
            },
            "logo": {
                "normal": "https://github.com/Hub-of-all-Things/exchange-assets/blob/master/Sentiments/logo.png?raw=true"
            },
            "screenshots": [
                {
                    "normal": "https://github.com/Hub-of-all-Things/exchange-assets/blob/master/Sentiments/Screenshot1.jpg?raw=true"
                },
                {
                    "normal": "https://github.com/Hub-of-all-Things/exchange-assets/blob/master/Sentiments/Screenshot2.jpg?raw=true"
                }
            ]
        },
        "dataPreviewEndpoint": "/she/feed/she/sentiments"
    },
    "developer": {
        "id": "hatdex",
        "name": "Dataswift Ltd",
        "url": "https://hatdex.org",
        "country": "United Kingdom"
    },
    "trigger": {
        "triggerType": "individual"
    },
    "dataBundle": {
        "name": "data-feed-counter",
        "bundle": {
            "she/insights/emotions": {
                "endpoints": [
                    {
                        "endpoint": "she/insights/emotions",
                        "mapping": {
                            "message": "text",
                            "timestamp": "timestamp"
                        }
                    }
                ],
                "orderBy": "timestamp",
                "ordering": "descending",
                "limit": 20
            },
            "notables/feed": {
                "endpoints": [
                    {
                        "endpoint": "rumpel/notablesv1",
                        "mapping": {
                            "message": "message",
                            "timestamp": "created_time"
                        }
                    }
                ],
                "orderBy": "created_time",
                "ordering": "descending",
                "limit": 20
            },
            "she/insights/emotions/negative": {
                "endpoints": [
                    {
                        "endpoint": "she/insights/emotions/negative",
                        "mapping": {
                            "message": "text",
                            "timestamp": "timestamp"
                        }
                    }
                ],
                "orderBy": "timestamp",
                "ordering": "descending",
                "limit": 20
            },
            "twitter/tweets": {
                "endpoints": [
                    {
                        "endpoint": "twitter/tweets",
                        "mapping": {
                            "message": "text",
                            "timestamp": "lastUpdated"
                        }
                    }
                ],
                "orderBy": "lastUpdated",
                "ordering": "descending",
                "limit": 20
            },
            "facebook/feed": {
                "endpoints": [
                    {
                        "endpoint": "facebook/feed",
                        "mapping": {
                            "message": "message",
                            "timestamp": "created_time"
                        }
                    }
                ],
                "orderBy": "created_time",
                "ordering": "descending",
                "limit": 20
            },
            "she/insights/emotions/neutral": {
                "endpoints": [
                    {
                        "endpoint": "she/insights/emotions/neutral",
                        "mapping": {
                            "message": "text",
                            "timestamp": "timestamp"
                        }
                    }
                ],
                "orderBy": "timestamp",
                "ordering": "descending",
                "limit": 20
            },
            "she/insights/emotions/positive": {
                "endpoints": [
                    {
                        "endpoint": "she/insights/emotions/positive",
                        "mapping": {
                            "message": "text",
                            "timestamp": "timestamp"
                        }
                    }
                ],
                "orderBy": "timestamp",
                "ordering": "descending",
                "limit": 20
            }
        }
    },
    "status": {
        "available": true,
        "enabled": false,
        "lastExecution": "2018-11-13T12:36:59.061Z"
    }
}

You can read more about the structure here.

A request that has failed will look like this:

{
  "error": "Not Authenticated",
  "message": "Not Authenticated"
}

  • error is the error that has occurred

  • message is a more descriptive message about the error that has occurred

Last updated

Was this helpful?