SARTORIUS Mfcs 4 Sim Api User Guide

SARTORIUS Mfcs 4 Sim Api

Product Usage Instructions

Prerequisites

To use the SimApi, ensure that your computer has the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 installed. If not installed, download and install the latest version from the official Microsoft website.

Installation and Setup

• Configuring SimApi Settings
  • Configure the SimApi settings according to your requirements. Pay special attention to the ‘Maximum concurrent requests’ setting.
• When to change ‘Maximum concurrent requests’:
  • Follow guidelines provided in the user manual to determine when it is necessary to adjust this setting.
• Starting the SIMCA-online Server
  • Initiate the SIMCA-online server to begin using the SimApi.
• Testing the SimApi in SIMCA-online
  • Verify the functionality of the SimApi within SIMCA-online by testing various features.
• Testing in the SIMCA-online Client
  • Perform specific tests within the SIMCA-online client interface to ensure proper operation.
• Troubleshoot SimApi Problems
  • If issues arise, refer to the SimApi log file for troubleshooting guidance.

Support

• For any additional support or inquiries, refer to the support section in the user manual.

Introduction

• This document is the user guide for the MFCS 4 SimApi from Sartorius Stedim Data Analytics AB.
• A SimApi is the connection between the Umetrics Suite and external data sources.
• The MFCS 4 SimApi described in this document connects to a BioPAT® MFCS 4 System.
• For a detailed list of changes in different versions of this SimApi, see the Version Info.txt file that comes with the installation.
• For more information on SimApis, see sartorius.com/umetrics-simapi.

Features

The SimApi implements the following SimApi features; Refer to sartorius.com/umetrics-simapi to learn more about the general SimApi features.

• Connect to an MFCS 4 server of version 4.9 or later (using its web api). The latest version of MFCS server is recommended. Does not work with a MFCS/win 3 server (for that, use the MFCS Access SimApi).
• Exposes each Unit configured in MFCS as a node with its control module properties available as tags (screenshot below).
• A special tag $BatchID is added to each unit. It holds the name of the batch active in that unit for each timepoint. It is used in SIMCA-online as a batch identifier tag in a project configuration.
• Current and historical process data can be read.
• Exposes a node called Batches with batch context node functionality (batch names, start- and end-times).
• Multiple instances of the SimApi can be run on the same SIMCA-online server

Here is how the MFCS 4 server looks like through the SimApi from SIMCA-online:

The remainder of this document will show you how to setup and configure the SimApi.

Limitations

The tags in the units are from the currently configured control modules in MFCS. There is no history. You cannot go back in time and read data for control modules that might have existed previously for earlier batches.

Prerequisites

To use the SimApi on a computer, it must have the following software installed:

The Microsoft Visual C++ Redistributable for Visual Studio 2015-2022. Often these are already installed on a computer (for example, they are installed automatically by SIMCA or SIMCA-online), but if the SimApi fails to start because of this, download and install the latest version from https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-cdownloads

BioPAT® MFCS 4 requirements

A BioPAT® MFCS 4 server or client/server installation version 4.9 or later is required.

Version 4.10.2 added support for the $BatchID tag which holds the batch name for each observation and fixed a bug that required a workaround for the server time zone. This workaround should be turned off in the SimApi settings for version 4.10.2 and later.

Verify network connectivity between SimApi and the MFCS 4 server

A networking firewall between the SimApi running in SIMCA, or SIMCA-online server and the MFCS 4 server can restrict network traffic so that the SimApi doesn’t work. The TCP port used by the MFCS 4 server needs to be open on the MFCS server computer so that traffic from the SimApi can reach the MFCS 4 server. Test connectivity on the computer running the SimApi in a browser by pasting the URL to the server. Your browser should be able to connect and receive the following error message (the message is expected and can be ignored). This shows that the connection to the MFCS 4 server works.

Configuring the MFCS 4 web api timeout

The MFCS 4 server has a timeout, which defaults to 60 seconds. If a request for data takes longer than that, it will time out, causing no data to be returned. This is visible in the SimApi log file as [Error] “Response status code does not indicate success: 500 (Internal Server Error)”. If this happens,s you can increase the timeout by editing the file C:\Program Files\Sartorius\BioPAT_MFCS\Web Services\Settings\sim-api.json on the MFCS server computer. Look for the row “SqlTimeout”: “60”. Restart the service ‘Sartorius.Sscada.Hosting.ServiceHost’ after changing.

Installation and setup

Refer to the SimApi Guide located at sartorius.com/umetrics-simapi for general step by step instructions that apply when installing a SimApi. Specifically, chapter 5 on how to install the SimApi.

Configuring SimApi settings

To change settings for the SimApi in SIMCA-online; launch the Server Options utility, and on the SimApi tab, click Configure… for the SimApi instance you want to configure. The same guidelines apply to SIMCA, although all screenshots and examples below are for SIMCA-online. The following dialog is displayed. Configure the settings for your environment. After saving and exiting, the SIMCA-online server service needs to be restarted for the changes to be effective.

As you can see there are very few settings:

As you can see there are very few settings:

Setting Explanation

• MFCS 4 Server Address The MFCS 4 server address of the form http://server.domain.com:16669/. Change the default TCP port 16669 if your MFCS server uses another port.
• Maximum concurrent requests, The maximum number of requests made in parallel by the SimApi to obtain data from the MFCS4 server. Too high a number can impact the performance of the MFCS server.
• Enable MFCS 4.9.x server workaround Enables a workaround for servers that incorrectly interpret time points as local time and as a result fails to find batches at expected times when the ‘Batches’ nodes in the SimApi is used. Do not use enable this for MFCS server version 4.10.2 and later.
• MFCS server time zone The time zone is used by the SimApi to adjust time points before they are sent to the MFCS 4 server to compensate for a bug in the server. Only required when the above workaround is enabled.
• Log Level Controls how much information is written to the log file. (Debug, Information, Warning, Error, Critical). Debug is helpful for troubleshooting issues with the SimApi.
• Log Max Size (MB) Controls the max size of the log file before creating a new one. Setting this to 0 means infinite size.

In the picture above, you can see an example of a configuration:

• We have one server, de01wsmfcs19, which uses tcp port 16669
• The SimApi will use up to 10 concurrent data requests to the MFCS server to optimize performance (learn more below)
• The workaround for MFCS servers before 4.10.2 is disabled because we are using a fixed MFCS server version.
• The Log Level is set to “Debug”, so debug entries will be written into the log file. Tip: use Debug when configuring the SimApi
• initially but change it to Information if the log file grows too quickly when you use the SimApi in production.

When to change ‘Maximum concurrent requests’

The SimApi performs many requests to the MFCS server concurrently to ensure a short response time. For short queries, a single request is made, but for longer duration,s the SimApi can use as many requests as specified ithe n Maximum concurrent requests.

• A higher value results in quicker response time but adds additional load on the MFCS server during the SimApi calls.
• Specifically, the SQL server will use more memory and CPU.
• If you find the SimApi calls take too long or time out, you can try increasing the number of concurrent requests.
• If you find that the MFCS server performance suffers, you can reduce this value.
• You can use Extract in SIMCA-online to test the SimApi with various values for Maximum concurrent requests (see below on how to use Extract).

Starting the SIMCA-online server

• Start the SIMCA-online server to use your newly configured SimApi. Once the SIMCA-online server has been started successfully, you can test your SimApi in SIMCA-online (if the server does not start, see below).

Testing the SimApi in SIMCA-online

• Here is some information on how to test the SimApi, borrowed from the SimApi Guide, chapter 6. sartorius.com/umetricssimapi

Testing in the SIMCA-online client

• Log in to the server in the SIMCA-online client, and navigate to Extract on the File tab. Extract helps you test the SimApi by obtaining data through it:
• The nodes (“folders”) of the SimApi are displayed in the top-left box. Tags for the selected node are displayed top-right.
• Current data can be tested quickly, simply by clicking < Click to view> on tags that provide continuous
• process data (see the screenshot)
• Right-click on the Batches node and do Find batches within a time range. This show batches in your MFCS server that are running in anv of its units:
• Select tags in Extract and click Next, and then finish the wizard to obtain data using the different modes of data retrieval that are supported: current data and historical data. Compare the extracted data with what you see in your data source tools.

Troubleshoot SimApi problems using the SimApi log file

• If the server does not start, the SimApi doesn’t work as expected or extract fails, you need to consult the SimApi log file, which tells you what the problem is. Copy and paste %programdata%\Umetrics\SimApi to Windows File Explorer to find the log file.
  • Tip: enable Debug-level logging in the SimApi configuration (if not already set) log to get full details.

Support

This SimApi is developed by Sartorius Data Analytics. For support, please visit sartorius.com/umetrics-support

FAQs

• Q: What are the limitations of the SimApi?
  • A: The tags in the units are from the currently configured control modules in MFCS. There is no history available, and you cannot retrieve data for control modules from earlier batches.