Preparing and Adding Restful API Data Sources


EnOS Digital Twin Visualization can connect to external data sources data via Restful API.

Preparing the Restful API


If you need the Digital Twin Visualization to obtain data and use it, you need to use the following interface to obtain the data.

Get Category List and Get Entity List


Request


Please define the fields in the interface according to the following example.

Use key: {path} to define the interface path as the unique key. Use name: paths.{path}.get.summary to define the summary field as the page display name. Add in: "query" to paths.{path}.get.parameters to pass parameters[index].name as param key to the interface. Use parameters[index].type == "content" to define the data as content. Use parameters[index].enum = ["option1", "option2"] to define the data as dropdown options. Use format == "date-time" to define the data as a date.

Return Code


{
   key: string,
   name: string,
   options?: {key: string, name: string, type: string, mode: 'multipule', enum?:  {key: string, name: string}

}[]

Return Sample


[
  {
    key: 'teamLeftBugs',
    name: 'Legacy Bug Distribution',
    options: [ // Optionally, if parameters are required to obtain the data interface, they can be described here
      {
        key: 'week', //
        name: '时间段',
        type: 'string', // string， datetime.  string type: if there is also an enum field, it represents a select drop-down selection, otherwise it is an input.
                        // datetime is Datepicker selection, the format of the passed parameter is '2020-09-07 22:10:00'
        mode: 'multiple', // string || null, If mode is multiple then it is multiple choice, if the mode is empty then it is a single choice by default
        enum: [
          {
            key: '2020-08-31~2020-09-06',
            name: '2020-08-31~2020-09-06'
          },
          {
            key: '2020-08-24~2020-08-30',
            name: '2020-08-24~2020-08-30'
          }
        ]
      }
    ]
  },
  {
    key: 'UTTop10',
    name: 'UT Coverage TOP 10'
  }
]

Get Metadata


Request


path: /getMetadata
method: POST
cookie: Carry
body:
{
 category: 'teamLeftBugs'
}

Return


{key: string, name: string}[]

Return Sample


[
  {
    key: 'project',
    name: 'project'
  },
  {
    key: 'open',
    name: 'open'
  },
  {
    key: 'resolved',
    name: 'resolved'
  },
  {
    key: 'total',
    name: 'total'
  }
]

Get Data


Request


path: /getData
method: POST
cookie: Carry
body:
{
 category: 'teamLeftBugs',
 fields: ['project', 'open'] // This parameter can be ignored if you do not want to process
 week: '2020-08-31~2020-09-06' // (if there are options parameters)
}

Return


Object[]

Return Sample


[
                {
                    "project": "AEP",
                    "open": 35,
                    "resolved": 10,
                    "total": 45
                },
                {
                    "project": "EDP",
                    "open": 12,
                    "resolved": 7,
                    "total": 19
                },
                {
                    "project": "MF",
                    "open": 5,
                    "resolved": 0,
                    "total": 5
                }
            ]

Connecting to the Digital Twin Visualization


Add this type of external data source by following the steps

  1. Select Dashboards > Data Sources from the left navigation pane.
  2. Select the External Data Sources tab.
  3. Select New Data Source and provide the required information.
    • Type：Select Restful API
    • Name：Specify the name of the data source
    • Visibility：Specify the scope of the data source
      • Internal：For this OU only
      • Public：Available for other OUs
    • Host：Enter the database host address
    • Request Method：Select the request method (POST or GET).
    • In the Metadata Cache input box, you can specify when the DTV will clear the metadata cache.
    • In the Data Cache input box, you can specify the time when the DTV will clear the data cache.
  4. Select OK.


The configured Restful API external data source can now be selected in the Chart Settings panel.

Return Code


After selecting the Restful API data source in the widget, you need to check the return code to confirm whether the request is successful. If the return code is 0, then the data connection is successful; if other codes are returned, then the data connection fails.

Success Sample


{
"code": 0,
"message": "Success",
"data": exampledata
}

Failure Sample


{
"code": 500,
"message": "Error message"
}

Login Authentication


Restful API connection data is not authenticated, if you need to authenticate, contact the system administrator.