CygNet Bridge API

CygNet Bridge API is a separately available CygNet product that provides a web service to request your CygNet data over the internet, allowing you to create your own web applications to securely access your CygNet system data. CygNet Bridge API is a REST API delivering HTTP requests and responses.

Accessing the CygNet Bridge API requires the installation of CygNet Bridge software, and the Bridge API feature must be selected as an option during the CygNet Bridge installation process. CygNet Bridge maintains secure data access, allowing you to access required CygNet data without direct access to a CygNet system. You can optionally require two-factor authentication to be granted access to the CygNet Bridge API.

See Providing Two-Factor Authentication for more information. See CygNet Bridge for general information about that component.

Note: CygNet Bridge API is also used by the CygNet OPC UA Server to access CygNet data.

CygNet Bridge API License

CygNet Bridge API is licensed in conjunction with CygNet Bridge, which must be licensed separately from existing CygNet SCADA or CygNet Measurement software components. Licensing for CygNet Bridge API is provided according to license type; you can obtain Base licensing for API access, or obtain optional Alarm and/or Control licensing to gain access to additional features. For more information about obtaining and licensing the CygNet Bridge API and CygNet Bridge products, contact your Account Manager or CygNet Sales.

Features included in each license type are described in the following table.

License Type	CygNet Bridge API Features Included
Base	All CygNet Bridge APIs except those features provided with the "Alarm" or "Control" licenses See API Information Types for a list of provided types.
Alarm	All base license features plus: Acknowledge alarms Clear alarms (and optionally force clear)
Control	All base license features plus: Issue commands to a device Initiate polling of a device data group Retrieve data group element ID (DEID) values from a device Send data group element ID (DEID) values to a device Send data group transaction data to a device Set values for a point

License Type

CygNet Bridge API Features Included

Base

All CygNet Bridge APIs except those features provided with the "Alarm" or "Control" licenses

See API Information Types for a list of provided types.

Alarm

All base license features plus:

Acknowledge alarms
Clear alarms (and optionally force clear)

Control

All base license features plus:

Issue commands to a device
Initiate polling of a device data group
Retrieve data group element ID (DEID) values from a device
Send data group element ID (DEID) values to a device
Send data group transaction data to a device
Set values for a point

Note: When you install an updated CygNet license file, use the IIS Manager to recycle CygNet Bridge in the IIS Application Pools list. This will refresh your web application and pick up new functionality. Refer to Microsoft IIS (Internet Information Services) online documentation if you need more information about the recycle process.

Access CygNet Bridge API

CygNet Bridge API requires the installation of CygNet Bridge software, and must be selected as an option during the CygNet Bridge installation process.

Accessing the CygNet Bridge API includes the following steps.

Prepare your system.
See Preparing Your System for CygNet Bridge API and (optionally) Providing Two-Factor Authentication for more information.
Install CygNet Bridge, selecting the option to install CygNet Bridge API.
See Installing CygNet Bridge for more information.
Access the CygNet Bridge API.
See Accessing and Updating CygNet Bridge API for more information.

Use CygNet Bridge API

Use CygNet Bridge API in conjunction with CygNet Bridge and CygNet Software v8.5.1 or greater to access your CygNet data via the web. See the CygNet Release Documents for more information about current software version requirements and considerations appropriate for your installation and usage.

API Information Types

A variety of CygNet Bridge APIs are provided to support operations involving the following CygNet information types.

Access
Alarms
Devices
Facilities
Measurement
Groups

History
Notes
Points
Real-time
Services
Tables

Note: Some API calls require specific licensing types. See Licensing above.

The CygNet Bridge APIs are accessible to authorized users of a licensed CygNet installation who are also authorized on the web server domain. Access is granted according to configured permission levels and the features you have licensed.

Authorization depends on:

your CygNet permissions and access levels configured in the ACS.
See CygNet Bridge API Security for more information about setting up permissions in CygNet.
your permissions on the web server domain being used.
See Accessing and Updating CygNet Bridge API for more information.
Note: When the authorization token expires, CygNetBridgeAPI will return the status "401 Unauthorized" and deny authorization. If that occurs, obtain a new authorization token by calling the client login API again.

Request an authorization token via the ClientLoginAPI method in your CygNet Bridge site in IIS. Prior to calling any CygNet Bridge API methods, obtain an authorization token, using the method clientloginapi/api/login and then pass the obtained token into all CygNet Bridge API requests in a header named X-WFT-AuthToken.

Valid CygNet Bridge API requests must contain headers for the authorization token received and the CygNet domain ID, as follows.

X-WFT-AuthToken — Required: contains the user authentication token required for the request (obtained via ClientLoginAPI method)
Note: Additional requirements apply if you have opted to use two-factor authentication. See Providing Two-Factor Authentication for more information.
X-WFT-CygNetDomain — Required: contains the CygNet domain ID used for the request

CygNet Bridge API errors are logged to your Weatherford\CygNetBridge\Logs folder as CygNetBridgeApi[logfile number].csv files

CygNet Bridge API Sample Web Application

Assistance using the Bridge API is provided via a sample application. The CygNet Bridge API installation set includes the sample web application (BridgeAPISampleApp\sample folder in your CygNet Bridge source files) that contains examples for using the Bridge API to develop your customized web application, and for using two-factor authentication. See Building the CygNet Bridge API Sample Web Application for more information.

Access CygNet Bridge API User Assistance

CygNet Bridge API generates web-accessible user documents using an auto-generated interactive documentation library tool. On a deployed API system these documents provide up-to-date information to help developers with API usage including example requests / responses and details about each request. The built-in online help will deploy automatically when you install the new APIs.

Navigate to localhost/CygNet/Help to access the help documents after CygNet Bridge is installed.

Note: If you have installed CygNet Bridge with HTTPS (strongly recommended), navigate to https://[YourWebHostName]/CygNet/Help.

CygNet Bridge API Help Offline

An offline version of the CygNet Bridge API Help is provided within the CygNet Help as a reference tool. See the CygNet Bridge API Help Page.

CygNet Help

Other portions of the CygNet Help file also pertain to preparation or installation of CygNet Bridge API. The following related topics may prove helpful:

To address questions or circumstances beyond the scope of the CygNet Help, Additional CygNet Resources are available.

Preparing Your System for CygNet Bridge API

Providing Two-Factor Authentication

Accessing and Updating CygNet Bridge API

Building the CygNet Bridge API Sample Web Application

Troubleshooting CygNet Bridge API