What can we help you with?

e.g. Getting Started, Build Dashboards

Top

Widget Management

Follow

List Widgets

This endpoint returns a listing of widgets of a given category
Query
GET /api/1.0/widgets?byCategory=<byCategory>
Parameter Comments
byCategory Query parameter, optional. If set, then widgets filtered by specified category
Response
HTTP Status Response
200 OK Output example: 
{
   "list":[
      {
         "id":25901,
         "name":"test5",
         "userId":10077,
         "customerId":1033,
         "datasetId":15150,
         "type":2,
         "description":null,
         "urlString":"02SscJ",
         "access":0,
         "refreshChartMillis":-1,
         "createdDate":1492282355000,
         "jsonConfig":null,
         "queryId":-1,
         "queryStr":null,
         "adhocQuery":null,
         "category":"All",
         "drilldown":false,
         "dataset":{
            "createdDate":1492282355000,
            "lastModDate":1492282355000,
            "id":15150,
            "metadataConfig":"{\"fieldNames\":[\"id_0\",\"id\",\"geometry\",\"properties\"],\"dataTypes\":{\"id_0\":\"java.lang.String\",\"id\":\"java.lang.String\",\"geometry\":\"java.util.Map\",\"properties\":\"java.util.Map\"}}",
            "mongoId":null,
            "mongoConnectUri":"localhost:27017/Some_a3PNFK",
            "customerId":1033,
            "datasetName":"test5",
            "identifier":null,
            "userId":0,
            "customer":null,
            "metaData":{
               "fieldNames":[
                  "id_0",
                  "id",
                  "geometry",
                  "properties"
               ],
               "dataTypes":{
                  "id_0":"java.lang.String",
                  "id":"java.lang.String",
                  "geometry":"java.util.Map",
                  "properties":"java.util.Map"
               }
            }
         },
         "position":{
            "chartId":25901,
            "width":-1,
            "height":-1,
            "originalScreenWidth":-1,
            "originalScreenHeight":-1,
            "col":1,
            "row":13,
            "id":25901,
            "xpos":0,
            "ypos":0,
            "size_x":12,
            "size_y":12
         },
         "associations":null,
         "queryModified":false,
         "updateFilters":false,
         "dataFields":[

         ],
         "transientChartFilters":null,
         "typeModified":false,
         "lastSyncDate":1492282355000,
         "viewOnly":false,
         "truncated":false,
         "processedName":"test5",
         "widgetConfig":null,
         "chartProperties":{
            "chart.type":"datagrid"
         },
         "statusIndColumns":[

         ],
         "gridBean":null,
         "dataRow":null,
         "text":"",
         "colNames":null,
         "dataRows":null,
         "live":false,
         "filters":null,
         "widgetType":"DATA_GRID",
         "macros":null,
         "strictFilters":null,
         "dbFields":[

         ],
         "widgetTypeStr":"datagrid",
         "filterFieldDataTypes":{
            "geometry":"java.util.Map",
            "id":"java.lang.String",
            "id_0":"java.lang.String",
            "properties":"java.util.Map"
         },
         "allFilters":[

         ],
         "processedFilters":[

         ]
      }
   ]
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" https://www.knowi.com/api/1.0/widgets/

 

List Widget Alerts

This endpoint returns a listing of widget alerts of a given widget id
Query

GET /api/1.0/widgets/<objectId>/alerts

Parameter Comments
objectId Widget id to list alerts in it
Response
HTTP Status Response
200 OK Output example: 
{
  "list": [
    {
      "createdDate": 1648134840000,
      "lastModDate": 1648134840000,
      "id": 242,
      "datasetId": 16170,
      "lastAlert": null,
      "sendToOld": null,
      "userId": 10077,
      "alertCondition": "select * where Sent > 100",
      "dataset": null,
      "alertName": "alert12",
      "alertType": 4,
      "lastDataMeta": null,
      "accessLevel": 1,
      "scheduleId": 105,
      "schedule": {
        "frequencyType": "minute",
        "frequency": 15,
        "startTime": null,
        "cronConfig": "*/15 * * * *",
        "id": 105,
        "type": 0,
        "host": null,
        "createdDate": 1648134840000,
        "lastModDate": null,
        "sync": 0,
        "nextExecutionEpoch": 1648124040,
        "nextExecutionTime": 1648124040000
      },
      "realtime": true,
      "executionReport": null,
      "firedCount": 0,
      "createdBy": null,
      "deletable": false,
      "chartId": 26908,
      "lastDataMetaObj": null,
      "properties": {
        "classVersion": 2,
        "emailOutput": {
          "classVersion": 1,
          "from": "support@knowi.com",
          "sendTo": "Some@some.com",
          "cc": "",
          "bcc": "",
          "emailSubject": "alert10",
          "emailBody": "Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%",
          "attachDataset": false,
          "attachResultsAfterCloud9ql": false
        },
        "webhookOutput": {
          "classVersion": 1,
          "selectedWebhooks": [
            200
          ]
        },
        "attachAdditionalResults": false,
        "additionalResults": {
          "additionalDatasetId": null,
          "additionalQuery": ""
        },
        "generateAlertIfNoDataDetected": false,
        "skipAlertIfDataOrLastUpdateSameAsBefore": true,
        "attachConditionalData": true,
        "frequencyMarker": "custom",
        "operator": ">",
        "metric": "Sent",
        "threshold": "100"
      }
    },
    {
      "createdDate": 1648121285000,
      "lastModDate": 1648121285000,
      "id": 240,
      "datasetId": 16170,
      "lastAlert": null,
      "sendToOld": null,
      "userId": 10077,
      "alertCondition": "select * where Sent > 100",
      "dataset": null,
      "alertName": "alert12",
      "alertType": 4,
      "lastDataMeta": null,
      "accessLevel": 1,
      "scheduleId": 103,
      "schedule": {
        "frequencyType": "minute",
        "frequency": 15,
        "startTime": null,
        "cronConfig": "*/15 * * * *",
        "id": 103,
        "type": 0,
        "host": null,
        "createdDate": 1648121285000,
        "lastModDate": null,
        "sync": 0,
        "nextExecutionEpoch": 1648110485,
        "nextExecutionTime": 1648110485000
      },
      "realtime": true,
      "executionReport": null,
      "firedCount": 0,
      "createdBy": null,
      "deletable": false,
      "chartId": 26908,
      "lastDataMetaObj": null,
      "properties": {
        "classVersion": 2,
        "emailOutput": {
          "classVersion": 1,
          "from": "support@knowi.com",
          "sendTo": "Some@some.com",
          "cc": "",
          "bcc": "",
          "emailSubject": "alert10",
          "emailBody": "Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%",
          "attachDataset": false,
          "attachResultsAfterCloud9ql": false
        },
        "webhookOutput": {
          "classVersion": 1,
          "selectedWebhooks": [
            200
          ]
        },
        "attachAdditionalResults": false,
        "additionalResults": {
          "additionalDatasetId": null,
          "additionalQuery": ""
        },
        "generateAlertIfNoDataDetected": false,
        "skipAlertIfDataOrLastUpdateSameAsBefore": true,
        "attachConditionalData": true,
        "frequencyMarker": "custom",
        "operator": ">",
        "metric": "Sent",
        "threshold": "100"
      }
    }
  ]
}
400 BAD REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to see the alerts
  • Current user is not allowed to access specified widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/widgets/26908/alerts

 

Get Widget Details by Id

This endpoint is to return the details of the widget and also includes the “filters" and “defaultFilters" fields inside "widgetConfig" in by widget id
 
Query
GET /api/1.0/widgets/<objectId>
Parameter Comments
objectId Widget id to view
Response
HTTP Status Response
200 OK Output example: 
{
 "id":25901,
 "name":"test5",
 "userId":10077,
 "customerId":1033,
 "datasetId":15150,
 "type":2,
 "description":null,
 "urlString":"02SscJ",
 "access":0,
 "refreshChartMillis":-1,
 "createdDate":1492282355000,
 "jsonConfig":null,
 "queryId":-1,
 "queryStr":null,
 "adhocQuery":null,
 "category":"All",
 "drilldown":false,
 "dataset":{
    "createdDate":1492282355000,
    "lastModDate":1492282355000,
    "id":15150,
    "metadataConfig":"{\"fieldNames\":[\"id_0\",\"id\",\"geometry\",\"properties\"],\"dataTypes\":{\"id_0\":\"java.lang.String\",\"id\":\"java.lang.String\",\"geometry\":\"java.util.Map\",\"properties\":\"java.util.Map\"}}",
    "mongoId":null,
    "mongoConnectUri":"localhost:27017/Some_a3PNFK",
    "customerId":1033,
    "datasetName":"test5",
    "identifier":null,
    "userId":0,
    "customer":null,
    "metaData":{
       "fieldNames":[
          "id_0",
          "id",
          "geometry",
          "properties"
       ],
       "dataTypes":{
          "id_0":"java.lang.String",
          "id":"java.lang.String",
          "geometry":"java.util.Map",
          "properties":"java.util.Map"
       }
    }
 },
 "position":{
    "chartId":25901,
    "width":-1,
    "height":-1,
    "originalScreenWidth":-1,
    "originalScreenHeight":-1,
    "col":1,
    "row":13,
    "id":25901,
    "xpos":0,
    "ypos":0,
    "size_x":12,
    "size_y":12
 },
 "associations":null,
 "queryModified":false,
 "updateFilters":false,
 "dataFields":[

 ],
 "transientChartFilters":null,
 "typeModified":false,
 "lastSyncDate":1492282355000,
 "viewOnly":false,
 "truncated":false,
 "processedName":"test5",
 "widgetConfig":null,
 "chartProperties":{
    "chart.type":"datagrid"
 },
 "statusIndColumns":[

 ],
 "gridBean":null,
 "dataRow":null,
 "text":"",
 "colNames":null,
 "dataRows":null,
 "live":false,
 "filters":null,
 "widgetType":"DATA_GRID",
 "macros":null,
 "strictFilters":null,
 "dbFields":[

 ],
 "widgetTypeStr":"datagrid",
 "filterFieldDataTypes":{
    "geometry":"java.util.Map",
    "id":"java.lang.String",
    "id_0":"java.lang.String",
    "properties":"java.util.Map"
 },
 "allFilters":[

 ],
 "processedFilters":[

 ]
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to see specified widget

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" https://www.knowi.com/api/1.0/widgets/10001

Generate and replace Widget Share Url

This endpoint is for generating and replace the existing widget share URL of a given widget id

POST /api/1.0/widgets/<objectId>/share/url

Parameter Comments
objectId Widget id to generate share url
contentFilters

The contentFilter is a JSON array of the field name, value, and operator of filters to be applied to the widget, which allows using of the same widget as a kind of template and generates different PDF exported report files with a different set of filters. It is optional (can be skipped or set to empty string)

Example:

[{"fieldName":"$c9_<field>$", "type": "java.lang.String", "values":["33"], "operator": "Equals"}]

Available Operators for Content Filters:

"Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.
Response
HTTP Status Response
200 OK Output example: 
{
 "shareUrl": "Zar1OtKVb7iiiiV6Ufa8VJ25Wo3jvrPI1aySdisvceplMEie?contentFilters=%5B%7B%22fieldName%22%3A%22Customer%22%2C%22values%22%3A%5B%22Facebook%22%5D%2C%22operator%22%3A%22%3D%22%7D%5D"
}

Note: To construct the full url, prepend /w/ and the “shareUrl” to the host name and port. For example: http://localhost:9090/w/Zar1OtKVb7iiiiV6UfI1aySdisvceplMEie?contentFilters=%5B%7B%22fieldName%22%3A%22Customer%22%2C%22values%Facebook%22%5D%2C%22operator%22%3A%22
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Error details:
  • Current user is not allowed to generate widget share url
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to generate widget share url
Example

curl -X POST -i http://localhost:9090/api/1.0/widgets/3528/share/url -H 'Authorization: Bearer HERE_IS_YOUR_BEARER' -H 'Content-Type: application/x-www-form-urlencoded' -d 'contentFilters=[{"fieldName":"Customer","values":["Facebook"],"operator":"="}]'

Share Widget Secure Url

 This endpoint is for sharing the widget secure URL of a given widget id

Query

POST /api/1.0/widgets/<objectId>/share/url/secure

Parameter Comments
objectId Widget id to generate secure share url
contentFilters

The contentFilter is a JSON array of the field name, value, and operator of filters to be applied to the widget, which allows using of the same widget as a kind of template and generates different PDF exported report files with a different set of filters. It is optional (can be skipped or set to empty string)

Example:

[{"fieldName":"$c9_<field>$", "type": "java.lang.String", "values":["33"], "operator": "Equals"}]

Available Operators for Content Filters:

"Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.
Response
HTTP Status Response
200 OK Output example: 
{
 "secureShareUrl": "S0jBEWZ2WLNCCe8pXQYtTbip3zrq3oaM8iplCQDzEhpEkie/dnqPwU7UF61jmT+rgIft4aEY1kWQ1B1V4FWGoIGITmZGl___n3P859PnDoJlcSiov6CIWd___8Dpvl5JH74SIhJxww=="
}

Note: To construct the full url, prepend /w-secure/ and the “secureShareUrl” to the host name and port. For example: http://localhost:9090/w-secure/S0jBEWZ2WLNCCe8pXQYtTbip3zrq3oaM8iplCQDzEhpEkie/dnqPwU7UF61jmT+rgIft4aEY1kWQ1B1V4FWGoIGITmZGl___n3P859PnDoJlcSiov6CIWd___8Dpvl5JH74SIhJxww==
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Customer token is missing, can't encrypt content filters
  • Error details:
  • Current user is not allowed to generate widget secure share url
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to generate widget secure share url
Example

curl -X POST -i http://localhost:9090/api/1.0/widgets/3528/share/url/secure -H 'Authorization: Bearer HERE_IS_YOUR_BEARER' -H 'Content-Type: application/x-www-form-urlencoded' -d 'contentFilters=[{"fieldName":"Customer","values":["Facebook"],"operator":"="}]'

 

Get Widget Dataset Query Mapper

This endpoint returns info from where the widget is created, like in UI the Data Diagram for Widget. The output field queries at position [0] will be the source query used for widget creation.

Query

GET /api/1.0/widgets/<objectId>/mapper

Parameter Comments
objectId Widget id from which to get query mapper
Response
HTTP Status Response
200 OK Output example: 
{
  "datasetId": 15848,
  "datasetName": "sendingActivity2019-06-18-11-19",
  "datasetMetadata": {
    "fields": [
      {
        "fieldName": "bounced",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "campaign_name",
        "fieldType": "java.lang.String"
      },
      {
        "fieldName": "clicks",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "conversions",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "customer",
        "fieldType": "java.lang.String"
      },
      {
        "fieldName": "date",
        "fieldType": "java.util.Date"
      },
      {
        "fieldName": "delivered",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "id",
        "fieldType": "java.lang.String"
      },
      {
        "fieldName": "message_type",
        "fieldType": "java.lang.String"
      },
      {
        "fieldName": "opened",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "sent",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "spam",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "week",
        "fieldType": "java.util.Date"
      }
    ],
    "dataTypes": {
      "bounced": "java.lang.Integer",
      "campaign_name": "java.lang.String",
      "clicks": "java.lang.Integer",
      "conversions": "java.lang.Integer",
      "customer": "java.lang.String",
      "date": "java.util.Date",
      "delivered": "java.lang.Integer",
      "id": "java.lang.String",
      "message_type": "java.lang.String",
      "opened": "java.lang.Integer",
      "sent": "java.lang.Integer",
      "spam": "java.lang.Integer",
      "week": "java.util.Date"
    },
    "fieldNames": [
      "bounced",
      "campaign_name",
      "clicks",
      "conversions",
      "customer",
      "date",
      "delivered",
      "id",
      "message_type",
      "opened",
      "sent",
      "spam",
      "week"
    ]
  },
  "queries": [
    {
      "op": 0,
      "connectorSyncStatus": 0,
      "id": 2432,
      "entityName": "sendingActivity2019-06-18-11-19",
      "datasourceId": 0,
      "userId": 0,
      "customerId": 0,
      "status": 0,
      "triggerDatasetId": 0,
      "modelId": 0,
      "accessLevel": 1,
      "categoryAccessLevel": -1,
      "autoShared": false,
      "scheduled": false,
      "direct": false,
      "directPush": false,
      "cacheDuration": 0,
      "datasetId": 0,
      "c9ExportDataset": 0,
      "my": false,
      "drafted": false,
      "triggered": false
    }
  ],
  "widgets": [
    {
      "createdDate": null,
      "lastModDate": null,
      "id": 26560,
      "name": "sendingActivity2019-06-18-11-19b",
      "userId": 0,
      "customerId": 0,
      "datasetId": 0,
      "type": 1,
      "description": null,
      "urlString": null,
      "access": 0,
      "refreshChartMillis": -1,
      "jsonConfig": null,
      "shareUrl": null,
      "accessLevel": 1,
      "dashboardAccessLevel": -1,
      "categoryAccessLevel": -1,
      "autoShared": false,
      "urlShareWhitelistDomain": null,
      "filterSettings": null,
      "chartType": null,
      "alertCount": 0,
      "queryId": -1,
      "queryStr": null,
      "adhocQuery": null,
      "categories": null,
      "userExternalAuthId": 0,
      "userSso": false,
      "drilldown": false,
      "dataset": null,
      "position": {
        "chartId": 0,
        "width": 500,
        "height": 400,
        "originalScreenWidth": 0,
        "originalScreenHeight": 0,
        "col": 0,
        "row": 0,
        "ypos": 0,
        "xpos": 0,
        "id": 0,
        "size_x": 0,
        "size_y": 0
      },
      "associations": null,
      "queryModified": false,
      "updateFilters": false,
      "dataFields": [],
      "dataFieldsTypes": {},
      "transientChartFilters": null,
      "typeModified": false,
      "lastSyncDate": null,
      "viewOnly": false,
      "truncated": null,
      "processedName": "sendingActivity2019-06-18-11-19b",
      "processedDescription": null,
      "processedFootNote": null,
      "error": null,
      "widgetConfig": null,
      "notDefaultFilter": false,
      "chartProperties": {
        "pivot.fitWidgetWidth": "false",
        "pivot.footer": "false",
        "pivot.singleRow": "false",
        "formatOptions": "{\"clicks\":[{\"mode\":\"number\",\"decimal\":\"2\",\"separator\":true}],\"opened\":[{\"mode\":\"number\",\"decimal\":\"\",\"separator\":true}],\"week\":[{\"mode\":\"date\",\"dateformat\":\"mm.dd.yyyy\"}]}",
        "chart.type": "pivot",
        "pivot.sort": "{\"id\":\"12/04/2014 11:00:00 MSK_'_12/10/2014 11:00:00 MSK_'_min_'_conversions\",\"dir\":\"desc\"}",
        "pivot.columnsSortOrder": "desc",
        "pivot.columnWidths": "{\"name\":270.25}",
        "pivot.config.access.viewers": "false",
        "pivot.autoCollapseRows": "false",
        "pivot.totalColumn": "false",
        "chart.quickpickers": "0",
        "pivot.structure": "{\"rows\":[\"customer\",\"message_type\"],\"columns\":[\"week\",\"date\"],\"values\":[{\"name\":\"clicks\",\"text\":\"clicks\",\"id\":1563138446510,\"operation\":[\"sum\"]},{\"name\":\"conversions\",\"text\":\"conversions\",\"id\":1563138446511,\"operation\":[\"min\"]}],\"filters\":[],\"columnSort\":{\"$default\":{\"dir\":\"desc\",\"_dir\":-1},\"week\":{\"dir\":\"desc\",\"_dir\":-1},\"date\":{\"dir\":\"desc\",\"_dir\":-1}}}"
      },
      "filters": [],
      "widgetAccessLevel": 1,
      "chartPropertiesNullOrEmpty": false,
      "filterFieldDataTypes": {},
      "processedFilters": [],
      "live": false,
      "strictFilters": null,
      "dataDisplayTypes": {},
      "dbFields": [],
      "ignoreVals": [],
      "widgetTypeStr": "chart",
      "filterFieldDataTypesIncludingNested": {},
      "gridBean": null
    },
    {
      "createdDate": null,
      "lastModDate": null,
      "id": 26559,
      "name": "sendingActivity2019-06-18-11-19 $c9_DataLastUpdate_${date|yyyy-MM-dd'T'HH:mm:ss}$",
      "userId": 0,
      "customerId": 0,
      "datasetId": 0,
      "type": 1,
      "description": null,
      "urlString": null,
      "access": 0,
      "refreshChartMillis": -1,
      "jsonConfig": null,
      "shareUrl": null,
      "accessLevel": 1,
      "dashboardAccessLevel": -1,
      "categoryAccessLevel": -1,
      "autoShared": false,
      "urlShareWhitelistDomain": null,
      "filterSettings": null,
      "chartType": null,
      "alertCount": 0,
      "queryId": -1,
      "queryStr": null,
      "adhocQuery": null,
      "categories": null,
      "userExternalAuthId": 0,
      "userSso": false,
      "drilldown": false,
      "dataset": null,
      "position": {
        "chartId": 0,
        "width": 500,
        "height": 400,
        "originalScreenWidth": 0,
        "originalScreenHeight": 0,
        "col": 0,
        "row": 0,
        "ypos": 0,
        "xpos": 0,
        "id": 0,
        "size_x": 0,
        "size_y": 0
      },
      "associations": null,
      "queryModified": false,
      "updateFilters": false,
      "dataFields": [],
      "dataFieldsTypes": {},
      "transientChartFilters": null,
      "typeModified": false,
      "lastSyncDate": null,
      "viewOnly": false,
      "truncated": null,
      "processedName": "sendingActivity2019-06-18-11-19 $c9_DataLastUpdate_${date|yyyy-MM-dd'T'HH:mm:ss}$",
      "processedDescription": null,
      "processedFootNote": "foot2 $c9_DataLastUpdate_${date|yyyy-MM-dd'T'HH:mm:ss}$",
      "error": null,
      "widgetConfig": null,
      "notDefaultFilter": false,
      "chartProperties": {
        "chart.historical_y_axis": "clicks",
        "chart.band_x_axis": "date",
        "widget.footnote": "foot2 $c9_DataLastUpdate_${date|yyyy-MM-dd'T'HH:mm:ss}$",
        "chart.type": "band",
        "pivot.columnWidths": "{\"name\":296.75}",
        "pivot.sort": "{\"id\":\"name\",\"dir\":\"asc\"}",
        "chartColor": "#89D4F5:clicks,#BCD759:spam,#FFBF00,#9961A7,#4891EA,#EE965B,#F284D1,#6FDBCB,#2D71C4,#EF5A5A,#609C29,#C69B06,#8A2299,#996D6C,#2F2F6C,#1C6C61",
        "prevWidgetType": "bubble",
        "chart.quickpickers": "0",
        "pivot.structure": "{\"rows\":[\"customer\",\"message_type\",\"campaign_name\"],\"columns\":[\"week\",\"date\"],\"values\":[{\"name\":\"clicks\",\"text\":\"clicks\",\"id\":1560849374643,\"operation\":[\"sum\"]},{\"name\":\"spam\",\"text\":\"spam\",\"id\":1560849374644,\"operation\":[\"sum\"]}],\"filters\":[{\"name\":\"campaign_name\",\"text\":\"campaign_name\",\"type\":\"select\",\"id\":1560849374645}],\"columnSort\":{\"$default\":{\"dir\":\"asc\",\"_dir\":1},\"date\":{\"dir\":\"asc\",\"_dir\":1},\"week\":{\"dir\":\"asc\",\"_dir\":1}}}",
        "d3.sankey.array": "[{\"from\":\"week\",\"to\":\"clicks\",\"value\":\"spam\"},{\"from\":\"customer\",\"to\":\"date\",\"value\":\"campaign_name\"}]"
      },
      "filters": [],
      "widgetAccessLevel": 1,
      "chartPropertiesNullOrEmpty": false,
      "filterFieldDataTypes": {},
      "processedFilters": [],
      "live": false,
      "strictFilters": null,
      "dataDisplayTypes": {},
      "dbFields": [],
      "ignoreVals": [
        "date",
        "campaign_name",
        "week",
        "clicks",
        "message_type",
        "spam",
        "message_type2",
        "customer"
      ],
      "widgetTypeStr": "chart",
      "filterFieldDataTypesIncludingNested": {},
      "gridBean": null
    }
  ],
  "derivedQueries": [],
  "sourceDatasets": []
}
400 BAD REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to see specified widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/widgets/26559/mapper

 

Reset User Filters to Default for Widget

This endpoint is for removing the user filters and set default filters of a given widget id
Query

GET /api/1.0/widgets/<objectId>/filter/reset

Parameter Comments
objectId Widget id in which to reset user filters to defaault filters
Response
HTTP Status Response
200 OK Output example: Output Widget entity with updated filters
400 BAD REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to edit specified widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/widgets/26559/filter/reset

Update Default Filters for Widget

This endpoint is for updating/modifying the default filters for a widget of a given widget id
Query

PUT /api/1.0/widgets/<objectId>/filter/default

Parameter Comments
objectId Widget id in which to update default filters

PUT JSON payload:

 
To get all varity of input parameters, please create filter in UI first, and then get/list it with another endpoint to investigate possible inputs. It may be changed in future versions.
Example: 
      {"filters":[{"fieldName":"clicks","visible":true,"transientFilter":false,"values":["1005"],"type":"java.lang.Integer","fieldType":"java.lang.Integer","operator":"Greater than","enabled":true}]}
Response
HTTP Status Response
200 OK Output the widget with updated default filters>
400 BAD REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
    Error details:
  • Missed Filters field
  • Wrong Filters field
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to edit specified widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"filters":[{"fieldName":"clicks","visible":true,"transientFilter":false,"values":["1005"],"type":"java.lang.Integer","fieldType":"java.lang.Integer","operator":"Greater than","enabled":true}]}'  http://localhost:9090/api/1.0/widgets/26559/filter/default

Create Widget

This endpoint is for creating a new widget
Query
POST /api/1.0/widgets/

POST JSON payload:

Parameter Comments
datasetId Id of Dataset to use to create Widget
widgetName Widget name
Response
HTTP Status Response
200 OK Return created Widget json info (same as "Get widget" command). Output example: 
{
 "id":25901,
 "name":"test5",
 "userId":10077,
 "customerId":1033,
 "datasetId":15150,
 "type":2,
 "description":null,
 "urlString":"02SscJ",
 "access":0,
 "refreshChartMillis":-1,
 "createdDate":1492282355000,
 "jsonConfig":null,
 "queryId":-1,
 "queryStr":null,
 "adhocQuery":null,
 "category":"All",
 "drilldown":false,
 "dataset":{
    "createdDate":1492282355000,
    "lastModDate":1492282355000,
    "id":15150,
    "metadataConfig":"{\"fieldNames\":[\"id_0\",\"id\",\"geometry\",\"properties\"],\"dataTypes\":{\"id_0\":\"java.lang.String\",\"id\":\"java.lang.String\",\"geometry\":\"java.util.Map\",\"properties\":\"java.util.Map\"}}",
    "mongoId":null,
    "mongoConnectUri":"localhost:27017/Some_a3PNFK",
    "customerId":1033,
    "datasetName":"test5",
    "identifier":null,
    "userId":0,
    "customer":null,
    "metaData":{
       "fieldNames":[
          "id_0",
          "id",
          "geometry",
          "properties"
       ],
       "dataTypes":{
          "id_0":"java.lang.String",
          "id":"java.lang.String",
          "geometry":"java.util.Map",
          "properties":"java.util.Map"
       }
    }
 },
 "position":{
    "chartId":25901,
    "width":-1,
    "height":-1,
    "originalScreenWidth":-1,
    "originalScreenHeight":-1,
    "col":1,
    "row":13,
    "id":25901,
    "xpos":0,
    "ypos":0,
    "size_x":12,
    "size_y":12
 },
 "associations":null,
 "queryModified":false,
 "updateFilters":false,
 "dataFields":[

 ],
 "transientChartFilters":null,
 "typeModified":false,
 "lastSyncDate":1492282355000,
 "viewOnly":false,
 "truncated":false,
 "processedName":"test5",
 "widgetConfig":null,
 "chartProperties":{
    "chart.type":"datagrid"
 },
 "statusIndColumns":[

 ],
 "gridBean":null,
 "dataRow":null,
 "text":"",
 "colNames":null,
 "dataRows":null,
 "live":false,
 "filters":null,
 "widgetType":"DATA_GRID",
 "macros":null,
 "strictFilters":null,
 "dbFields":[

 ],
 "widgetTypeStr":"datagrid",
 "filterFieldDataTypes":{
    "geometry":"java.util.Map",
    "id":"java.lang.String",
    "id_0":"java.lang.String",
    "properties":"java.util.Map"
 },
 "allFilters":[

 ],
 "processedFilters":[

 ]
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Error details:
  • Missed datasetId field
  • Missed widgetName field
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to add widget using specified dataset
  • Have no permissions to add new widget
415 UNSUPPORTED_MEDIA_TYPE Cannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d "{\"datasetId\":15134,\"widgetName\":\"newWidgetName1\"}" https://www.knowi.com/api/1.0/widgets

Delete Widget

This endpoint is for deleting a widget of a given widget id
Query
DELETE /api/1.0/widgets/<objectId>
Parameter Comments
objectId Widget id to delete
Response
HTTP Status Response
200 OK No response body
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to delete specified widget

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE https://www.knowi.com/api/1.0/widgets/25902

Edit Widget

This endpoint is for updating/modifying a widget of a given widget id
Query

PUT /api/1.0/widgets/<objectId>

Parameter Comments
objectId Widget id of Widget to edit

PUT JSON payload:

Parameter Comments
widgetName Optional string. Widget name
widgetType Optional integer. Widget type. It is works togeter with "chart.type" parameter inside chartProperties to set actual chart kind.
chartProperties Optional string. JSON with all chart properties. To get an example of this JSON you can get example of your chart properties from your existing widget (using Get Widget Details command), which contains chartProperties field.
filters Optional JSON array with filters to set to widget
Response
HTTP Status Response
200 OK Return edited Widget json info (same as "Get Widget" command). Output example: 
{
 "id":25901,
 "name":"test5",
 "userId":10077,
 "customerId":1033,
 "datasetId":15150,
 "type":2,
 "description":null,
 "urlString":"02SscJ",
 "access":0,
 "refreshChartMillis":-1,
 "createdDate":1492282355000,
 "jsonConfig":null,
 "queryId":-1,
 "queryStr":null,
 "adhocQuery":null,
 "category":"All",
 "drilldown":false,
 "dataset":{
    "createdDate":1492282355000,
    "lastModDate":1492282355000,
    "id":15150,
    "metadataConfig":"{\"fieldNames\":[\"id_0\",\"id\",\"geometry\",\"properties\"],\"dataTypes\":{\"id_0\":\"java.lang.String\",\"id\":\"java.lang.String\",\"geometry\":\"java.util.Map\",\"properties\":\"java.util.Map\"}}",
    "mongoId":null,
    "mongoConnectUri":"localhost:27017/Some_a3PNFK",
    "customerId":1033,
    "datasetName":"test5",
    "identifier":null,
    "userId":0,
    "customer":null,
    "metaData":{
       "fieldNames":[
          "id_0",
          "id",
          "geometry",
          "properties"
       ],
       "dataTypes":{
          "id_0":"java.lang.String",
          "id":"java.lang.String",
          "geometry":"java.util.Map",
          "properties":"java.util.Map"
       }
    }
 },
 "position":{
    "chartId":25901,
    "width":-1,
    "height":-1,
    "originalScreenWidth":-1,
    "originalScreenHeight":-1,
    "col":1,
    "row":13,
    "id":25901,
    "xpos":0,
    "ypos":0,
    "size_x":12,
    "size_y":12
 },
 "associations":null,
 "queryModified":false,
 "updateFilters":false,
 "dataFields":[

 ],
 "transientChartFilters":null,
 "typeModified":false,
 "lastSyncDate":1492282355000,
 "viewOnly":false,
 "truncated":false,
 "processedName":"test5",
 "widgetConfig":null,
 "chartProperties":{
    "chart.type":"datagrid"
 },
 "statusIndColumns":[

 ],
 "gridBean":null,
 "dataRow":null,
 "text":"",
 "colNames":null,
 "dataRows":null,
 "live":false,
 "filters":null,
 "widgetType":"DATA_GRID",
 "macros":null,
 "strictFilters":null,
 "dbFields":[

 ],
 "widgetTypeStr":"datagrid",
 "filterFieldDataTypes":{
    "geometry":"java.util.Map",
    "id":"java.lang.String",
    "id_0":"java.lang.String",
    "properties":"java.util.Map"
 },
 "allFilters":[

 ],
 "processedFilters":[

 ]
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Wrong chartProperties format
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to edit specified widget
415 UNSUPPORTED_MEDIA_TYPE Cannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.
Example 1
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"widgetName\":\"updatedWidgetName1\"}"  http://localhost:9090/api/1.0/widgets/123
Example 2
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"chartProperties\":{\"chart.type\":\"datagrid2\",\"font.size\":\"25\",\"grid.resetColumnWidth\":\"false\",\"grid.collapsible\":\"false\",\"chart.quickpickers\":\"0\"}}"  http://localhost:9090/api/1.0/widgets/123
Example 3 (Possible to set filters)

curl -i -H "Authorization: Bearer HEREISYOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"filters":[{"fieldName":"Bounced","values":["8888"],"operator":"Equals","type":"java.lang.Integer","enabled":true,"visible":true,"transientFilter":false,"fieldType":"java.lang.Integer"}]}' http://localhost:9090/api/1.0/widgets/26908


Clone Widget

This Endpoint is for cloning/copying a widget of a given widget id
Query
POST /api/1.0/widgets/<objectIdToClone>
Parameter Comments
objectIdToClone Widget id of Widget to clone

POST JSON payload:

Parameter Comments
widgetName New (cloned) Name of Widget
Response
HTTP Status Response
200 OK Return cloned Widget json info (same as "Get Widget" command). Output example: 
{
 "id":25901,
 "name":"test5",
 "userId":10077,
 "customerId":1033,
 "datasetId":15150,
 "type":2,
 "description":null,
 "urlString":"02SscJ",
 "access":0,
 "refreshChartMillis":-1,
 "createdDate":1492282355000,
 "jsonConfig":null,
 "queryId":-1,
 "queryStr":null,
 "adhocQuery":null,
 "category":"All",
 "drilldown":false,
 "dataset":{
    "createdDate":1492282355000,
    "lastModDate":1492282355000,
    "id":15150,
    "metadataConfig":"{\"fieldNames\":[\"id_0\",\"id\",\"geometry\",\"properties\"],\"dataTypes\":{\"id_0\":\"java.lang.String\",\"id\":\"java.lang.String\",\"geometry\":\"java.util.Map\",\"properties\":\"java.util.Map\"}}",
    "mongoId":null,
    "mongoConnectUri":"localhost:27017/Some_a3PNFK",
    "customerId":1033,
    "datasetName":"test5",
    "identifier":null,
    "userId":0,
    "customer":null,
    "metaData":{
       "fieldNames":[
          "id_0",
          "id",
          "geometry",
          "properties"
       ],
       "dataTypes":{
          "id_0":"java.lang.String",
          "id":"java.lang.String",
          "geometry":"java.util.Map",
          "properties":"java.util.Map"
       }
    }
 },
 "position":{
    "chartId":25901,
    "width":-1,
    "height":-1,
    "originalScreenWidth":-1,
    "originalScreenHeight":-1,
    "col":1,
    "row":13,
    "id":25901,
    "xpos":0,
    "ypos":0,
    "size_x":12,
    "size_y":12
 },
 "associations":null,
 "queryModified":false,
 "updateFilters":false,
 "dataFields":[

 ],
 "transientChartFilters":null,
 "typeModified":false,
 "lastSyncDate":1492282355000,
 "viewOnly":false,
 "truncated":false,
 "processedName":"test5",
 "widgetConfig":null,
 "chartProperties":{
    "chart.type":"datagrid"
 },
 "statusIndColumns":[

 ],
 "gridBean":null,
 "dataRow":null,
 "text":"",
 "colNames":null,
 "dataRows":null,
 "live":false,
 "filters":null,
 "widgetType":"DATA_GRID",
 "macros":null,
 "strictFilters":null,
 "dbFields":[

 ],
 "widgetTypeStr":"datagrid",
 "filterFieldDataTypes":{
    "geometry":"java.util.Map",
    "id":"java.lang.String",
    "id_0":"java.lang.String",
    "properties":"java.util.Map"
 },
 "allFilters":[

 ],
 "processedFilters":[

 ]
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Error details:
  • Missed widgetName field
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to clone specified widget
415 UNSUPPORTED_MEDIA_TYPE Cannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d "{\"widgetName\":\"clonedWidgetName1\"}" https://www.knowi.com/api/1.0/widgets/12345

Share Widget with Users/Groups

This endpoint is for sharing the widget to users and groups of a given widget id
Query
PUT /api/1.0/widgets/<objectId>/share
Parameter Comments
objectId Widget Id to share
sso_user Optional bool. Set to `true` if sharing to sso user

PUT JSON payload:

Parameter Comments
shareProperties Share properties json array. Available fields:
  • Type: Users, Groups.
  • access_level: 1 - Edit rights, 2 - Read-only
  • name: the name of the User to share to
  • id: group id of the Group to share to.
    Example: 
    [ 
  { 
    "type" : "Users", 
    "access_level" : 1, 
    "name" : "someUser1@host.com" 
  },
  { 
    "type" : "Groups", 
    "access_level" : 1, 
    "id" : 10001 
  } 
]
Response
HTTP Status Response
200 OK  No response body
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Missed shareProperties field
  • shareProperties missed the type field
  • shareProperties missed the access_level field
  • shareProperties has invalid the type value
  • shareProperties has invalid the access_level value
  • shareProperties missed the id field
  • shareProperties missed the name field
  • shareProperties has invalid the name field
401 UNAUTHORIZED  
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
 403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to share specified widget
415 UNSUPPORTED_MEDIA_TYPE Cannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.

Export widget to PDF

This endpoint is for exporting the PDF file format of a widget of a given widget id

Query

GET /api/1.0/dashboards/<objectId>/export/pdf?contentFilters={content_filters}

Parameter Comments
objectId Widget id to export to PDF
contentFilters

The contentFilter is a JSON array of the field name, value, and operator of filters to be applied to the widget, which allows using of the same widget as a kind of template and generates different PDF exported report files with a different set of filters. It is optional (can be skipped or set to empty string)

Example:

[{“fieldName”: “page”, “values”:[“Products”], “operator”:“=”}]

Available Operators for Content Filters:

"Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.
Response
HTTP Status Response
200 OK Output example: 
Pdf binary content.
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • The bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • The current user is not allowed to access a specified dashboard
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" "http://localhost:9090/api/1.0/widgets/10001/export/pdf?contentFilters=%5B%7B%22fieldName%22%3A%22page%22%2C%22values%22%3A%5B%22Products%22%5D%2C%22operator%22%3A%22%3D%22%7D%5D" > file1.pdf

 

 

Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles