Web Service Interface

The following diagram shows the architecture for the Web Service Interface API.

NOTE:
Wake-up push notifications are part of a future extension module.

System Limits

The following limits apply when using the Web Service Interface:

• Number of concurrent sessions: 100
• Delay for notifications: <1 second
• 5’000’000 value updates / day
• 20’000 value subscriptions
• 250’000 event notifications / day
• 250’000 event-counter notifications / day
• 1’000’000 trends / min

NOTE:
The Client versions of Windows (for example, Windows 10) have intentionally feature-limited versions of IIS. One limitation is the number of concurrent connections which can be as low as 10.This especially affects the usage of push notifications with SignalRen.

Communication

The API can be accessed over HTTP or HTTPS. In a production environment it’s highly recommended to use HTTPS otherwise primary credentials are transmitted in plaintext.

Authentication

For authentication we use OAuth 2.0 Resource Owner Password Credentials Grant. In order to access a resource of the Web Service Interface the Client needs a valid access token and a valid session within the system. In case no token is presented or the token is invalid (for example, expired) or the system session is not available, the user will get a status code 401 (Unauthorized) and needs to request an access token. The access token can be requested through a dedicated resource (/token) by presenting the primary credentials. In case the credentials are provided, the system creates a new session and returns an access token.

NOTE:
The Client either needs to subscribe for notifications (for example, change of values) or needs to access the API at least once every 10 minutes otherwise its system session expires. The API provides a dedicated resource (/heartbeat) just for the sake of keeping a session alive.

Client Certificate Authentication

Optionally, a client can authenticate to the server by providing a client certificate. The Web Service Interface expects the client certificate to be provided in a header called X-ARR-ClientCert. In case the interface is accessed through a reverse proxy (almost always the case in a production environment), the reverse proxy asks the client for an optional client certificate. In this case the reverse proxy passes the client certificate to the backend server as HTTP header with the default header configured as X-ARR-ClientCert.

Subscriptions (Push Notifications with SignalR)

Optionally, for specified services the API provides not only data on request (pull) but also in case of an event determined by the respective service (push).

Any Client subscribing for any push notifications needs to support SignalR (see [2] [➙ 12]). The Client first needs to connect to a dedicated SignalR hub and can then subscribe for notifications by providing a connection ID which it gets after a connection between Client and server is established. The Client then needs to implement a function (see signature in respective service chapters) which will be called from the server in case a notification is due.

Latency Push Notification to Request-Response

In the workflow of subscription and notification it can happen that a push notification from server is received before the subscription success response. This latency will be experienced because of the network communication delay of the messages on two independent channels of SignalR hub connection for push notification and response of subscription request.

In this kind of scenario, Clients of WSI should consider received notification as a valid notification and design their solution accordingly.

Supported Client Environments

There are no Client dependencies except SignalR version 2.2.0 Client library for Clients interested in push notifications.

Deployment

The Web Service Interface will be deployed as a self-hosted component. It’s an executable and can be commanded as any other IOWA manager.

Depending on the deployment, it is likely that in a production environment, the Web Service Interface (and system) will only be accessible through a reverse proxy.

A connection with certificates between IIS and Web Service Interface is always required if both applications do not run on the same server. In that case, the IIS-Server must use https to get a certificate confirmation from the connected server. In the SMC, select the option Secured.

A connection without certificates between IIS and Web Service Interface can be established if both applications run on the same server using http. In the SMC, select the option Local.

Once the WSI extension is added to the project, during the project modification you can configure the Web Services Settings for multiple WSI instances, including the instance name, the type of communication, web services port, and the host certificate.

By default one instance is configured, and you can click Add to add a new WSI instance. The allowed maximum WSI instances to be added is 10.

• Instance Name: Change the default to modify the WSI instance name. Provide a unique name.
• Communication: Configure any of the following:
  Secured: (Recommended when working with remote IIS Server hosted on Client/FEP system). When selected, allows you to enable secure communication by configuring the web services port and host certificate.
  Local: When selected allows you to set up local communication between Server and WSI.
• Web Services Port: Modify the default by either typing the port number or increase/decrease it, using the spin control buttons.
• Host certificate: (Enabled only when you set the communication type as secured) By default, it displays the host certificate that you set as default.
  Allows you to browse for and select the host certificate, either from the Windows store or from the disk, depending on the selected certificate type.
  For a Windows store certificate type, when you click Browse, the Select Certificate dialog box displays. In the Select Certificate dialog box, in the Store Location field, either select Local machine certificates or User certificates and select the host certificate from the Personal tab.
  Make sure that the host certificate is generated from the root certificate provided and the host certificate must contain a private key and this key should be marked as exportable.
  For Windows store certificate type, a CNG certificate with ECDSA signature algorithm is not supported.
  For remote IIS Server hosted on Client/FEP system, ensure that the root of the host certificate is added in the Trusted Root Certification Authorities (TCRA) of Windows Certificate Store using SMC.
• Add: Adds a row for a WSI instance.
• Remove: Removes the selected row of a WSI instance.
• Directory Access: Creates a folder access to save the directories file in GMSProjects folder.

NOTE:
On upgrade of project to version 5.0, Unsecured communication type is replaced by Local (i.e hosting will be done on 127.0.0.1 instead of localhost), and Unsecured communication type will not work. It is recommended to configure the communication type as Secured, while working with remote IIS Server hosted on Client/FEP system. Any application (for example, Advanced Reporting) using WSI services which are mapped to localhost, should adapt to 127.0.0.1.

In the SMC tree, when you select Websites > [Website name], click and select Create Web Services Application, you can create and configure web services application using the following expanders:

Server Information Expander

This expander by default displays the Server name where you are creating the web services application. You cannot edit it.

Project Information: Web Services Communication Expander

This expander allows you to select and link a WSI instance of a Server project to the web services application.

Web Application Details Expander

This expander allow you to configure the web services application details including the Name, Path, User, and Password.

• Name: Allows you to type the name of the web services application. Provide a unique name. All names (identifiers) are case sensitive and do not use blank.
  Following special characters are not permitted in the web services application name:
  ‘\\', '/', '?', ';', ':', '@', '&', '=', '+', '$', ',', '|', ' " ', '<', '>'.
• Path: Browse for the location on the disk where you want to store the web services application. The default is [installation drive:]\[installation folder]\[Websites folder]\[Website name].
  Following special characters are not permitted in the web services application path:
  'ä', 'ö', 'ü', '$', '@', '&', '<', '>', '{', '}', '[', ']', '(', ')', ';', ':', '=', '^', '|', '*', '!',
  '/', '%', '?', ',', '\'', '"', '\t', ‘\\', '+' .
• For path specifications, consider case sensitivity and do not use blanks.
• All identifiers have to start with an alphabetic character (characters "A...Z", "a...z", "_" and the digits "0...9") or with an underline "_" and may not contain any special characters.
• The use of umlauts "ä","ö", "ü" is allowed in many cases but we recommend to avoid using them as the corresponding keys might not be available during international use. Furthermore, the display might also be problematic in case of foreign-language systems.
• User: Browse and select a web services application user using the Select User dialog box.
  NOTE 1: The web services application user should be a member of IIS_IUSRS group. If you select a user who is not a member of the IIS_IUSRS group, the SMC prompts you to add the user to that group.
  NOTE 2: You can create a web services application with a user different from the website user.
  NOTE 3: The user must also have Allow log on locally as Service right set. For more information, refer Cannot Create or Save Website in Troubleshooting Websites and Web Applications.
• Password: Type the valid password of the selected user.

NOTE:
Once the web services application is created, if you click Edit , you can modify the linked project. In case of an upgrade, of web application, if linked project is not upgraded then a message stating "Project needs to be upgraded before upgrading [web application]" displays.