# NuPMES

The nodes in this package include different functionalities to connect machines via a Node-RED workflow to a running NuP MES. In the following the different nodes are explained.

*!!! INFO: This version contains breaking changes. Flows with older versions can still be used, but mes nodes must be updated!*

***1. Configuration nodes***
- NuPMesServer
- NuPMesOPCUAServer

***2. Generic nodes***
- NuPMesRequest
- NuPMesHub

***3. Business nodes***
- NuPMesCounter
- NuPMesGetIO
- NuPMesSetIO
- NuPMesSetParameterMessage

***4. Analysis nodes***
- NuPMesPareto
- NuPMesOee

***5. Auth nodes***
- NuPMesAuthentication

***6. IOT nodes***
- NuPMesOPCUA

----
# 1. Configuration nodes

## NuPMESServer 

The NupMESServer node is a config node. It saves the URL and Name of a server to make it accessible for the flow.

### Configuration

**Name:** name of the server configuration

**Url:** server url to access

**Use auth:** enables to set an auth configuration for the given server

**Auth-protocoll:** technical protocoll for server authentication

| Setting             | Effect |
|:--------------------|:-------------|
| ***NTLM:***         | for windows authentication based configurations (default) |

**Username:** username for server authentication

**Password:** password for server authentication

## NuPMESOPUAServer 

The NuPMESOPUAServer node is a very simple config node. It saves the URL and Name of a opcua server to make it accessible for the flow.
***Important: It is not possible to configurate authentication***

### Configuration

**Name:** name of the server configuration

**Url:** server url to access (e.g. opc.tcp://localhost:12345)

----
# 2. Generic nodes

## NuPMESRquest

This Node-RED node is generic and enables any rest request to the mes interface. The request can be specified in the configurations. Write requests should be used with queues. The response of the mes server request is in the message payload of outgoing messages


### Configurations

**Name:** Name of the current node.

**Server:** References a configured server node

**Url:** relative path to rest interface

**Method:** HTTP Method for Rest request 

**Body:** Request json body (will pass by url if the request reads content) 

**Use queue:** enables to control write request with queues

**Queue ticks:** Intervall for execute Queue entries 

Especially it is possible to set simple placeholders in json body of the request configuration. This placeholders will replaced if the underlying data exists. 
```json
// Example jsonbody
{
    "example": "msg.payload",         // any payload 
    "example2": "msg.timestamp",      // any message parameter
    "example3": "global.authtoken",   // any global context parameter
}
```

### Input
If the option "Use queue" is selected, this node provides a set of keywords to control the node. Incoming messages could contain any values which are required by the request configuration. this message payloads should send from a seperated node and will pushed in a the request queue. 
You can also configurate the tick intervall for queue in the node (queue ticks)


**queue control node**
```javascript
// to consume the next queue item and send the request. 
// This should be triggered periodically.
msg.payload = "tick";

// to free the lock variable. 
// Should not be necessary in normal scenarios.
msg.payload = "unlock";

// to remove the next request from the queue. 
// May be necessary if an invalid request is on top of the queue.
msg.payload = "delete";

// to clear the queue from all requests.
msg.payload = "reset";

// to receive an info message about the status of the node's sending queue.
msg.payload = "status";

```
**value node**
```javascript
// Example value
msg.payload = 1;
```

### Output
The output message payload contains the server response of the request.

----

## NuPMESHub

This Node-RED node is generic and enables any signalR based request to the mes hub interface. The request can be specified in the configurations. 

In the following example you can see the message that needs to be sent so to the node.
```json
// this example sets the machine with machineId 1 to production
{
  "payload": {
    "hubFunction": "SetFailure",  // the function to be called in the MesHub
    "hubArgs": [                  // the arguments for the function
      { "id": 1 }, 
      { "no": "0" }
    ]
  }
}
```

### Configurations

**Server:** References a configured server node

**Name:** Name of the current node.

**Connection strategie:** strategie for connecting to the MES hub

| Setting             | Effect |
|:--------------------|:-------------|
| ***on input:***         | the conntection will established on input (default) |
| ***auto:***         | the conntection will established automatically on startup und remains open |

### Input
The input message payload should contains a hub function and hub args

```javascript
// Example input
msg.payload.hubFunction = "GetServerTime";
msg.payload.hubArgs = "";
```

### Output
The output message payload contains the return value of hub function.

----
# 3. Business nodes

## NuPMESGetIO

The NuPMESGetIO node returns the state value of an io address in NuPMES. To form a complete GET request, the node attributes "server", "deviceName" and "ioName" need to be specified. 

### Configurations

**Server:** References a configured server node

**Name:** Name of the current node.

**Device:** Name of the device. This can be left empty if you set 'deviceName' in the message.

**IO name:** Name of the target IO Address. This can be left empty if you set 'ioName' in the message.

### Input
This node needs just a trigger for excution. The payload of message is not relevant

### Output
When triggered by an arbitrary message, a request of the form is sent to the server. If the response contains a key named "state", its value is then propagated to the next node. The output message payload contains the IO state value for the configured IO and Device. 

```javascript
//Example
let ioStateValue = msg.payload;
```
----

## NuPMESSetIO

The NupMESSetIO node sets values of an IO address in the nup MES. It produces HTTP PUT requests from parameters and input values and adds them to the node's context variable "queue". The NupMESRequestQueue consumes a (global) HTTP request queue and sends its items to their destination.
To actually send the requests, the node also needs to be triggered periodically with an arbitrary 'tick' message to consume the queue.

### Configurations

**Server:** References a configured server node

**Name:** Name of the current node.

**Device:** Name of the device. This can be left empty if you set 'deviceName' in the message.

**IO name:** Name of the target IO Adress. This can be left empty if you set 'ioName' in the message.

**Queue ticks:** Intervall for execute Queue entries 

### Input
This node provides a set of keywords to control the node. Incoming messages could triggered by mes counter nodes or any other values which are required by the IO configuration. this message payloads should send from a seperated node and will pushed in a the request queue. 
You can also configurate the tick intervall for queue in the node (queue ticks)

**queue control node**
```javascript
// to consume the next queue item and send the request. 
// This should be triggered periodically.
msg.payload = "tick";

// to free the lock variable. 
// Should not be necessary in normal scenarios.
msg.payload = "unlock";

// to remove the next request from the queue. 
// May be necessary if an invalid request is on top of the queue.
msg.payload = "delete";

// to clear the queue from all requests.
msg.payload = "reset";

// to receive an info message about the status of the node's sending queue.
msg.payload = "status";

```
**value node**
```javascript
// Example value
msg.payload = 1;

```

Important: Without a periodic 'tick' message, no requests will actually be send!


### Output
This node has no output. The result of the request is visible MES Terminal

----
## NuPMESCounter

The NuPMESCounter functional node which stores an internal counter variable and sends its current state if triggered. In the context of a MES, this behaviour can for instance be used for production monitoring.

### Configurations

**Name:** Name of the current node.

**Typ:** Type of the counter (8, 16, 32 or 64 bit integer)

**Increment:** Value for counter increment (have to be smaller then the counter max value)

### Input
Incoming messages are extended and forwarded. The input can be a number. If is not set any input, the counter increments 1. To reset the counter, the payload must be a string equal to "reset":

```javascript
//default count
msg.payload = "";

//increase counter
msg.payload = 1;

//reset the counter
msg.payload = "reset";
```
### Output
The output message payload contains the counter value and can be used in a subsequent node:

```javascript
//Example
let counter = msg.payload;
```
----

## NuPMESSetParameterMessage

This Node-RED node generates a rest request to the mes interface, inserting a new entry into the table parameter_messages. Machine ID and Parameter ID must be specified, incoming messages must contain the parameter value and optionally a timestamp. It produces HTTP PUT requests from parameters and input values and adds them to the context variable "queue".
The sending and control of the request queue works the same as in the NuPMESSetIO node. Without a periodic 'tick', no requests will actually be send.


### Configurations

**Server:** References a configured server node

**Machine ID:** identification of a mchine

**Parameter ID:** identification of a parameter message

**Queue ticks:** Intervall for execute Queue entries 

### Input
This node provides a set of keywords to control the node. Incoming messages could contain any values which are required by the parameter configuration. this message payloads should send from a seperated node and will pushed in a the request queue. 
You can also configurate the tick intervall for queue in the node (queue ticks)

**queue control node**
```javascript
// to consume the next queue item and send the request. 
// This should be triggered periodically.
msg.payload = "tick";

// to free the lock variable. 
// Should not be necessary in normal scenarios.
msg.payload = "unlock";

// to remove the next request from the queue. 
// May be necessary if an invalid request is on top of the queue.
msg.payload = "delete";

// to clear the queue from all requests.
msg.payload = "reset";

// to receive an info message about the status of the node's sending queue.
msg.payload = "status";

```
**value node**
```javascript
// Example value
msg.payload = {
  value: 1,
  timestamp: ""
};
```

### Output
This node has no output. The result of the request is visible MES Terminal.

----
# 4. Analysis nodes

## NuPMESPareto
NuPMESPareto can be used to request a pareto analysis, given the Server URL and the Time Interval of interest. Start and End time need to follow the ISO 8601 representation (e.g. 2018-05-31T22:00:00.000Z).

### Configurations

**Server:** References a configured server node

### Input
there are diffenrent possibillities to request the pareto node:

```javascript
//request from any start date to now
msg.payload = "2020-05-31T22:00:00.000Z";
msg.topic = "startDate";

//request to any end date from from 24 hours before
msg.payload = "2020-05-31T22:00:00.000Z";
msg.topic = "endDate";

//request from any start date to any end date
msg.startDate = "2020-05-31T22:00:00.000Z";
msg.endDate = "2021-05-31T22:00:00.000Z";

//request from 00:00 am to 23:59 pm for given day of the passed date 
msg.payload = "2020-05-31T22:00:00.000Z" | timestamp;
msg.topic = "today";

//request to the passed date from last hour before for given hour
msg.payload = "2020-05-31T22:00:00.000Z" | timestamp;
msg.topic = "lasthour";
```

*Info: The Start and End time are no longer be set via a separate input.

### Output
The output message contains the server response of the pareto request

```javascript
/*
Example pareto object
{
  failureId: 2,
  failure: "kein Arbeitsgang angemeldet",
  duration: 20795122,
  percent: 42.56,
  cumulative: 42.56,
  color: "#808080"
}
*/

let peretorObjectList = msg.payload;
```
----

## NuPMESOee
NuPMESOee can be used to request a oee analysis, given the Server URL and the Time Interval of interest. Start and End time need to follow the ISO 8601 representation (e.g. 2018-05-31T22:00:00.000Z).

### Configurations

**Server:** References a configured server node

**Oee type:** type of the oee 

| Setting             | Effect |
|:--------------------|:-------------|
| ***0:***         | Overall (default) |
| ***1:***         | MachineGroup |
| ***2:***         | Machine |
| ***3:***         | Item |
| ***4:***         | Operation |

### Input
there are diffenrent possibillities to request the oee node:

```javascript
//request from any start date to now
msg.payload = "2020-05-31T22:00:00.000Z";
msg.topic = "startDate";

//request to any end date from from 24 hours before
msg.payload = "2020-05-31T22:00:00.000Z";
msg.topic = "endDate";

//request from any start date to any end date
msg.startDate = "2020-05-31T22:00:00.000Z";
msg.endDate = "2021-05-31T22:00:00.000Z";

//request from 00:00 am to 23:59 pm for given day of the passed date 
msg.payload = "2020-05-31T22:00:00.000Z" | timestamp;
msg.topic = "today";

//request to the passed date from last hour before for given hour
msg.payload = "2020-05-31T22:00:00.000Z" | timestamp;
msg.topic = "lasthour";
```

### Output
The output message contains the server response of the oee request

```javascript
/*
Example oee object
{
  id: 0,
  title: 0,
  amount: 0,
  scrap: 0,
  targetPieceTime: 0,
  actualPieceTime: 0,
  gpz: 0,
  oee: 0,
  availability: 0,
  effectivity: 0,
  qualityRate: 0,
  setupGrade: 0,
  scrapRate: 0
}
*/

let oeeObjectList = msg.payload;
```


----
# 5. Auth nodes

## NuPMESAuthentication
NuPMESAuthentication is a node that requests a login token, which is necessary for different requests to the MES interface. It requests a token with a POST request and stores the response in the global authtoken variable if it was accepted. 

### Configurations

**Server:** References a configured server node

**Username:** username for MES user

**Password:** password for MES user

### Input
Incoming messages are extended and forwarded.

### Output
The output message payload contains the server response and can be used in a subsequent node:
```javascript
/*
Example response
{
  "error": false,
  "userName": ""
}
*/

var hasError = msg.payload.error;
var userName = msg.payload.userName;

```

## NuPMESWinauthRequest
NuPMESWinauthRequest is a node that can be used to send Rest request to any endpoint that requires Windows authentication.

### Configurations

**Name:** Name of the current node.

**Url:** The Rest Endpoint

**Username:** Windows Domain Username

**Password:** Password for the User

**Domain:** The Windows Domain

**Method:** The Rest Method (GET,POST, PUT, DELETE, PATCH)

### Input
The incoming message can be added with additional settings.

| Setting             | Effect       |
|:--------------------|:-------------|
| payload             | the body information that will be send to the endpoint |
| headers             | the headers that are need by the endpoint. It need to be an JSON object. |
| url                 | Instead of setting the Url in the node, you use the message to set the Url |
| method              | Instead of setting the Method in the node, you use the message to set the Method. GET,POST, PUT, DELETE and PATCH can be used. |

```javascript
{
  "payload": `<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
                <soap:Body>
                  <dbInsert xmlns="http://tempuri.org/">
                    <aTable>item</aTable>
                    <aRecord><![CDATA[<row><item>0815</item></row>]]></aRecord>
                  </dbInsert>
                </soap:Body>
              </soap:Envelope>`,
  "headers": {
    "Content-Type": "text/xml; charset=utf-8",
    "Host": "localhost",
    "SOAPAction": "CoolAction"
  },
  "url": "https://awesome/rest/endpoint".
  "method": "POST"
}

```

### Output
The output message payload contains the server response and can be used in a subsequent node.

| Setting             | Effect       |
|:--------------------|:-------------|
| payload             | the body data coming from the endpoint |
| statusCode          | the HTTP status code. It can be used to see if the Request was successful. |

```javascript
{
  "payload": "OK",
  "statusCode": 200
}

```

----
# 6. IOT nodes

## NuPMesOPCUA
NuPMesOPCUA is a node that requests to OPCUA Servers. This node is a very simple implementation without any espacialy configurations. You can use it to simmulate machine signals. 
***Important: It is recommended to use this node just in local environments, if other OPCUA nodes not working***

### Configurations

**Server:** References a configured opcua server node

**Item Id:** Id for any opcua items (e.g. ns=1;s=Signal)

**Data type:** type of the item value

**Access:** Read or write Access to the item

### Input
Values for write request must given in the payload.

### Output
For read requests the output message payload contains the opcua item value:
```javascript
/*
Example response
"true"
*/


```