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'sPDA address
used to form the url to fetch the availableTools
.userToken
is the user's token used to authenticate with thePDA
.completion
is a callback function that is called when the request was successful with a type of@escaping (([HATToolsObject], String?) -> Void)
. The first parameter is an array ofHATToolsObject
. This is the structure ofTools
. More on that in the next section.The second parameter is an optional
String
, the refreshed user token that thePDA
returns.failCallBack
is a callback that is called when the request has failed. The type of the function is@escaping ((HATTableError) -> Void)
.HATTableError
is 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": "Dataswyft 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 theTool
id on theHAT
. You need this when you want to enable or disable aTool
.info
has all the information you will need to present theTool
. It is formed by 10 values:version
is the version number of theTool
.Tools
likeApplications
andData Plugs
can be updated. This will result a new version.versionReleaseDate
is the date that the latest version was pushed inISO
format.name
is the official name of theTool
.headline
is a small text to compliment thename
. Used like a subtitle.description
allows you to describe your tool better with a longer text. Also it has support for different formats of text,text
,markdown
andhtml
. Excepttext
the others are optional.termsUrl
is aURL
of the terms and conditions. Users must be able to read them if they wish.supportContact
a support email. Users will use this email to contact you.dataPreview
is actually an array ofSheFeed
structures. This is used to preview items, if any, instead of making another network request to fetch those items. Optionalgraphics
is a structure formed by 3 values:banner
is theURL
of the banner image.logo
is theURL
of the app logo image.screenshots
is theURL
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 assmall
,normal
,large
andxlarge
. Exceptnormal.
all are optional values.
dataPreviewEndpoint
is aURL
that you can use to fetch the 'feed' of theTool
. You have to form theURL
like this:"https://\(hatAddress)/api/v2.6\(dataPreviewEndpoint)"
developer
consists of some basic info about the developer. This includes:id
,name
,url
andcountry
.status
is formed by 4 values describing the state of theTool
:available
indicates if theTool
is available. ATool
can be unavailable, for example when in testing. Default value is false.enabled
indicates if theTool
is enabled by the user. Default value is false.lastExecution
is an optionalString
that has a date in anISO
format indicating the date that theTool
run for the last time.executionStarted
is an optionalString
that has a date in anISO
format indicating the date that theTool
started running for the last time.
dataBundle
is the permissions needed in order for theTool
to run.trigger
describes the frequency that theTool
will be executed.Tools
are not running all the time. The possible values are:periodic
,individual
andmanual
.
A request that has failed will look like this:
{
"error": "Not Authenticated",
"message": "Not Authenticated"
}
error
is the error that has occurredmessage
is a more descriptive message about theerror
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 theid
of the tool. It can be the same as thename
or not.userDomain
is the user'sPDA address
used to form the url to enable theTool
.userToken
is the user's token used to authenticate with thePDA
.completion
is a callback. This is called when the request is successful with a type of@escaping ((HATToolsObject, String?) -> Void)
. The first parameter is the now enabledHATToolsObject
. The second parameter is an optionalString
, the refreshed user token that thePDA
returns.failCallBack
is a callback that is called when the request has failed. The type of the function is@escaping ((HATTableError) -> Void)
.HATTableError
is 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": "Dataswyft 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 occurredmessage
is a more descriptive message about theerror
that has occurred
Disable Tool
HATToolsService.disableTool(
toolName: selectedTool.id,
userDomain: userDomain,
userToken: userToken,
completion: toolStatusChanged,
failCallBack: errorInteractingWithTool)
toolName
is theid
of the tool. It can be the same as thename
or not.userDomain
is the user'sPDA address
used to form the url to disable theTool
.userToken
is the user's token used to authenticate with thePDA
.completion
is a callback function that is called when the request is successful with a type of@escaping ((HATToolsObject, String?) -> Void)
. The first parameter is the now disabledHATToolsObject
. The second parameter is an optionalString
, the refreshed user token that theDA
returns.failCallBack
is a callback that is called when the request has failed. The type of the function is@escaping ((HATTableError) -> Void)
.HATTableError
is 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": "Dataswyft 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"
}
}
A request that has failed will look like this:
{
"error": "Not Authenticated",
"message": "Not Authenticated"
}
error
is the error that has occurredmessage
is a more descriptive message about theerror
that has occurred
Last updated
Was this helpful?