API

This section outlines the APIs available for developing an application and their specific functions. See the Swagger UI for details about API endpoints.

Application Creation

The APIs described below help a developer to define an application and create data points for the app. There are two types of data points in HCC2: Config and General. Each type has three APIs available:

• Read the value of the defined data point.
• Create a new data point.
• Delete an existing data point.

Initialize Application

To define an application, the first step is to initialize the application.

To initialize the application, use the following API:

PUT   /api/v1/app-creator/{appName}/defaults

Note: Read the detailed API description in the Swagger UI. The application name must follow a naming convention and it will be the name used in further endpoint calls in the tar.gz definition process. It is also the name of the application in the HCC2 and becomes part of a data point's fully qualified name.

Next, you create data points for the application. The following sections describe the Configuration data point and General data point in detail.

Config Data Point

The Configuration data point type and associated endpoints define configuration parameters for your app.

When you create a data point, you will provide a short, easily recognized name (topic), and you will receive the FQN (fully qualified name) (Fully Qualified Name) in the response. You will use the FQN in any business logic calls to interact with data point values. Unlike Configuration data point, these general data point values do not persist between restarts/power-cycles.

The format of the configuration data point FQN is:

liveValue.postvalidConfig.this.<app name>.0.<topic>.

For example, if your application's name is app1 and a configuration parameter is cfg1, then the FQN for the message will be liveValue.postvalidConfig.this.app1.0.cfg1..

For logical separation, you can punctuate your data point name with a "." (period). E.g., if your application requires a cycle time data point and you would like to define an "on" and "off" time as a configuration parameter, a period will provide the required separation. The following table displays example FQNs. Note the use of camelCase in the name.

Use the following APIs to perform these tasks:

• PUT   /api/v1/app-creator/{appName}/datapoint/config
  • Creates a new configuration data point
• GET   /api/v1/app-creator/{appName}/datapoint/config
  • Returns configuration data points for the app
• DELETE   /api/v1/app-creator/{appName}/datapoint/config
  • Deletes a specific data point

Note: See the Swagger UI for details about API endpoints.

Note: Before you define your data points, you must initialize the application via the endpoint call.

Note: When all data points are defined, you must perform registration and provisioning before you can read/write on the message of the defined data points.
Please refer to the Workflow section for details.

General Data Point

The General data point and associated endpoints define non-configuration (general) parameters for your applications. General data points are used to store intermediate or final calculation results. These may be used by other applications inside the HCC2, reported to other systems like Avalon, or to any other SCADA using HCC2 available channels and protocols. These General data points have a unique FQN format to differentiate them from Configuration data points.

When you create the data point you will provide a short, easily recognized name (topic) and you will receive the FQN in the response. You will use the FQN in any business logic calls to interact with data point values. Unlike Configuration data points, these General data point values do not persist between restarts/power-cycles.

The format of the General data point FQN is:

liveValue.<tag sub class>.this.<app name>.0.<topic>.

Current supported tag sub classes are:

• production
• diagnostics
• state

For example, if your application's name is app1 and a general parameter is gen1 under the tag sub class of diagnostics then the FQN for the message will be liveValue.diagnostics.this.app1.0.gen1..

For logical separation, you can punctuate your data point name with a "." (period). E.g., if your application needs to output some calculation of gas and oil, a period will provide the required separation, as shown below.

Depending on your application behaviour it may be more suitable to put a corrected gas volume under a production datapoint, see data point naming for more information

Use the following APIs to perform these tasks:

• PUT   /api/v1/app-creator/{appName}/datapoint/general
  • Creates a new general data point
• GET   /api/v1/app-creator/{appName}/datapoint/general
  • Returns general data points for the app
• DELETE   /api/v1/app-creator/{appName}/datapoint/general
  • Deletes a specific general data point

Note: See the Swagger UI for details about API endpoints.

Note: Before you define your data points, you must initialize the application via the endpoint call.

Note: When all data points are defined, you must perform registration and provisioning before you can read/write on the message of the defined data points.
Please refer to the Workflow section for details.

User Forms

The endpoints for creating new data points (Config or General) have a complex and lengthy payload in the form of JSON. While the JSON is a great format when developing programmatically or via scripts, it is error prone when edited manually.

To mitigate this hardship, the HCC2 offers an alternative "form" endpoint (shown below) especially for human use.

Use the following APIs to perform these tasks: - PUT   /api/v1/form/app-creator/{appName}/datapoint/config - Creates a new configuration data point - PUT   /api/v1/form/app-creator/{appName}/datapoint/general - Creates a new general data point

Note: See the Swagger UI for details about API endpoints.

Registration

When your app and all data points are defined (using either REST APIs or ACE), you must register your app with the HCC2. Before registration, the app exists only in the buffers and is not known to the rest of the HCC2.

While registration is required at each startup of the application (production), registration during development is also beneficial as it allows you to define an app and do read/write operations on data points before writing code. See below for details.

Development

In development, before you start writing code for your application, you can define the app and its data points using the REST APIs described above.

Then, you can use the following API to register it with the HCC2:

POST   /api/v1/app-registration/{appName}

Do not provide the 'tar.gz. file'. The REST server will take all the data points defined (via previous sections ) from its internal buffer and will perform the registration.

Once the registration is successful, you can read and write on the application's data points using appropriate message APIS (described in separate section below)

You can define an application and its data points and perform a read/write operation on them without writing a single line of code, using the Swagger UI or any REST client (like Postman).

Production

Note: In the section, "production" refers to running an application in an operational HCC2 (in production) and is unrelated to the production datapoint subclass.

Every time an application starts, the app must perform a registration. This is done in production. See the Workflow section for details.

In production, it is not viable to create each data point and do registration at every startup. Instead, you can prepare a tarball (.tar.gz file) of the app's data point definition and register it during every bootup.

To prepare a tarball, you can use REST API (see the Application Tarball Handling section) or ACE.

Once the tarball is available, use the following API to do the registration.

POST   /api/v1/app-registration/{appName}

This is the same API that is used in the development route. However, to register using the tarball, this time you must provide the tarball.

Application Removal (deregistration)

In any case, (specially in development) if you need to remove your application from the HCC2 then use the following API to deregister the app.

DELETE   /api/v1/app-registration/{appName}

Application Tarball Handling

The APIs in this section help you to save, open, and register an application's tarball that contains data point definitions.

The following APIs save an existing definition into the tarball and then load the tarball into the REST server buffers. Basically, it is equivalent to File Open and Save.

• POST   /api/v1/app-creator/{appName}
  • This API opens or loads the tarball into the internal buffer of the REST server. Once loaded, you can add more data points or delete existing ones.
• GET   /api/v1/app-creator/{appName}/targz
  • This API acts like a save or extract function. It takes all the defined data points of the app and prepares the tarball for download.

Note: Read the details of API in the Swagger UI.

This tarball is interoperable between ACE and the REST server. This tarball can be used in the registration too.

Run Time Configuration (Provisioning)

The APIs in this section help you to get a new configuration at run time. The process of getting a new configuration is called provisioning. There are two type of provisioning as described below. An app selects the type of provisioning during registration.

Simple Provisioning

In Simple provisioning, the app is not responsible for verifying and acknowledging user configuration. The REST server does the acknowledge on behalf of the app. The app gets its new configuration by just reading the data point and messages.

This type of provisioning is recommended for apps which have comparatively simple and straight- forward configuration that can be statically validated by the validator.js (defined via ACE).

Also, selecting the simple provisioning implies that the app does not need a user configuration file.

Use the following APIs to perform this operation:

• GET   /api/v1/app-provision/{appName}
  • Provides an indication of new configuration availability.
• POST   /api/v1/app-provision/{appName}
  • Acknowledge that the new configuration notification is received and resets the flag in the REST server.

Note: Read the details of API in the Swagger UI.

Note: See the section Simple Reconfiguration/Deployment for steps.

Advanced Provisioning

In Advanced provisioning, the app needs to ask for the user configuration, verify it, and provide acknowledgement in 15 Seconds. The REST server acts as a medium and does not act on its own.

This type of provisioning is recommended for apps with a complex configuration, such as when the data points validation depends on another data point or other state of the application, or when the app needs to receive a file (e.g., database or CSV) as a part of the user configuration.

In this provisioning, the app receives the user configuration in the form of a tarball. The tarball contains a JSON file, named parameters_this_0.json, that contains user-configured values of all the data points defined by the app. In addition, the tarball contains any other file that the user supplied as the part of the configuration.

Use the following APIs to perform this operation:

• GET   /api/v1/app-provision/{appName}
  • Provides an indication of new configuration availability.
• GET   /api/v1/app-provision/{appName}/targz
  • Retrieves user configuration in tarball.
• POST   /api/v1/app-provision/{appName}
  • Acknowledge that the new configuration is read and it is a valid configuration. It also resets internal flag.

Note: Read the details of API in the Swagger UI.

Note: See the section Simple Reconfiguration/Deployment for steps.

Message

The APIs in this section enable reading and writing of messages in the HCC2. The two categories of messages supported are described below.

Simple Messages

A Simple message has only one value and is represented with just a top level message topic. This type of message does not have any nesting and is atomic in nature.
E.g., EU value of AI - 1. It is a single value and does not bind with any other other message. Its structure appears as follows:

{
    "topic": "liveValue.diagnostics.this.io.0.analogIn.eu.ch1.",
    "value": 0.012631179
}

Note: Read the details of API in the Swagger UI.

Advanced (Complex) Message

In the HCC2, many messages are complex (i.e., the message contains nested data points or the value is itself, an array). Similarly, an app can also define an advanced message.

Messages that contain values as arrays are still single data point messages.

Some messages have more than one data point under a single message. For these messages, topics end with |. (pipe & dot) and each data point has its own name. In addition, each data point consists of VQT (i.e., value, quality, and timestamp). See the architecture section on complex messages for more information.

The following examples demonstrate this type of message:

For the information related to Time of the HCC2

{
    "topic": "liveValue.diagnostics.this.core.0.timeStatus|.",
    "msgSource": "core",
    "datapoints": [
        {
            "dataPointName": "timezone.",
            "quality": 192,
            "timeStamps": ["1734419132635207"],
            "values": ["Coordinated Universal Time"]
        },
        {
            "dataPointName": "localtime.",
            "quality": 192,
            "timeStamps": ["1734419132635207"],
            "values": ["17-Dec-2024 07:05:32"]
        },
        {
            "dataPointName": "utc.",
            "quality": 192,
            "timeStamps": ["1734419132635207"],
            "values": ["17-Dec-2024 07:05:32"]
        },
        {
            "dataPointName": "timeSource.",
            "quality": 192,
            "timeStamps": ["1734419132635207"],
            "values": []
        },
        {
            "dataPointName": "manualSyncTime.",
            "quality": 192,
            "timeStamps": ["1734419132635207"],
            "values": [""]
        },
        {
            "dataPointName": "ntpServer.",
            "quality": 192,
            "timeStamps": ["1734419132635207"],
            "values": ["No Remote Source - Local Only"]
        }
    ]
}

To operate on an Advanced (complex) message, you can use these advanced read-write APIs:

• POST /api/v1/message/read-advanced
  • Reads advanced (complex) messages
• POST /api/v1/message/write-advanced
  • Writes advanced (complex) messages

Event Management

Alarms can be created within the HCC2. Use the ACE application to define a system event and alarm group within a targz.

Alarms defined within the targz will be enabled when the application registers with the configuration manager. The user application can then disable and enable alarm groups at runtime using the REST endpoint. This is useful if the application has various operating states for which different alarm groups are relevant.

• PUT /api/v1/event/enableState/{groupID}
  • Updates the state of a event group

Data Logger

You can log any data point published within the system, including those produced by ISaGRAF, integrated IO, protocols, or an edge application installed on the HCC2. Use the ACE application to define a data logger group within a targz.

Data point logs defined within the targz will be configured to be enabled or disabled when the application registers with the configuration manager. The user application can then disable and enable logging groups at runtime using the REST endpoint. This is useful if the application has various operating states for which different data point logging groups are relevant or require different logging rates and priorities.

• PUT /api/v1/datalogger/enableState/{groupID}
  • Updates the state of a data logger tag group

Note: Access the Swagger UI to see further details.