Managing Connectors in Coreflux: Command Guide

In Coreflux, connectors are managed through a series of commands. This guide provides a comprehensive overview of these commands and their functionalities.

Authentication and Listing

Login to Coreflux Cloud:
```
-L | --login <amazingUser> <lamePassword>
```
Use this command to log in to the Coreflux cloud using the provided username and password.
List All Connectors:
```
-l | --list
```
Once logged in, you can list all available connectors using this command.
Help Information:
```
-h | --help
```
If you need assistance with the available commands, use this option to display help information.

Connector Installation and Removal

Install a Connector:
```
-I | --install <theConnectorType>
```
After logging in, you should list all available connectors to determine the type of connector you want to install. Once you've identified the connector type, you can use this command to install it.

Example

Suppose you've logged :

-L myname@mydomain.com password

And listed the connectors.

-l

Among the list, you find a connector type named coreflux_mssqlmqtt which represents the MS SQL Connector. To install this connector, you would use the following command:

-I coreflux_mssqlmqtt

Uninstall a Connector:
```
-U | --uninstall <theConnectorGuid|ConnectorName>
```
To remove a connector, use this command with the connector's unique GUID or its name. For example: -U DEADBEEF-CAFE-BABE-BEEF-0123456789AB or -U Machine1.

Connector Configuration

Connector Help:
```
-assetHelp <theConnectorGuid|ConnectorName>
```
Each connector has its own help documentation. After installation, this command provides feedback on how to configure the connector, both by command and JSON configuration. For example: -assetHelp DEADBEEF-CAFE-BABE-BEEF-0123456789AB or -assetHelp Machine1.
Reset Connector Configuration to Default:
```
-assetDefaultConfig <theConnectorGuid|ConnectorName>
```
Use this command with caution. It resets the connector's configuration to its default settings. For example: -assetDefaultConfig DEADBEEF-CAFE-BABE-BEEF-0123456789AB or -assetDefaultConfig Machine1.
Load Connector Configuration:
```
-assetConfigLoad <theConnectorGuid|ConnectorName>
```
This command displays the stored configuration of the connector in JSON format. For example: -assetConfigLoad DEADBEEF-CAFE-BABE-BEEF-0123456789AB or -assetConfigLoad Machine1.
Save Connector Configuration:
```
-assetConfigSave <theConnectorGuid|ConnectorName> <json>
```
To modify a connector's configuration, first run the assetHelp command to obtain the default JSON. After making your desired changes to the JSON, use this command with the connector's GUID or name and the modified JSON to save the new configuration. For example: -assetConfigSave DEADBEEF-CAFE-BABE-BEEF-0123456789AB {'myjsonelement': 42} or -assetConfigSave Machine1 {'myjsonelement': 42}.

Pratical Example of Save Config

To modify a connector's configuration, first run the assetHelp command to obtain the default JSON. After making your desired changes to the JSON, use this command with the connector's GUID or name and the modified JSON to save the new configuration.

For example, if you're configuring the MS SQL Connector:

-assetConfigSave MSSQLConnector {
"MQTTParameters": {
   "Port": 1883,
   "Address": "127.0.0.1",
   "IsAnonymous": true,
   "Username": "",
   "Password": "",
   "EnableTLS": true,
   "EnableDebugTopic": true,
   "DebugTopic": "test/debugtopic"
},
"MSSQLParameters": {
   "ServerAddress": "192.168.20.19",
   "DatabaseName": "MyDB",
   "Username": "admin",
   "Password": "pass",
   "QueryTimeoutInSeconds": 0
},
"Tags": [
   {
      "Name": "Test",
      "WriteDirection": 1,
      "MQTTTriggerTopic": "sqlasset/triggerTopicDirectSQL",
      "MQTTFeedbackTopic": "feedback/topic",
      "MQTTFeedbackQoS": 0,
      "MQTTFeedbackRetain": false,
         "Query": "INSERT INTO {value.json.table} (CustomerID,CustomerName, ContactName, Country) VALUES ({value.json.data.CustomerID},{value.json.data.CustomerName}, {value.json.data.ContactName}, {value.json.data.Country});",
      "ResultInJsonFormat": true
   }
 ]
}

Connector Operations

Run a Connector:
```
-R <theConnectorGuid|ConnectorName>
```
Use this command to start a specific connector. Always verify the connector's state in the Connectors topic after execution. For example: -R DEADBEEF-CAFE-BABE-BEEF-0123456789AB or -R Machine1.
Stop a Connector:
```
-S <theConnectorGuid|ConnectorName>
```
To halt a connector's operations, use this command and ensure you verify the connector's state in the Connectors topic afterward. For example: -S DEADBEEF-CAFE-BABE-BEEF-0123456789AB or -S Machine1.
Set Connector Restart Policy:
```
-assetPolicySet <theConnectorGuid|ConnectorName> <policy>
```
This command allows you to modify the restart behavior of a connector. The <policy> can be one of the following: 'Always', 'OnFailure', 'OnFailureWithMaxRetries', or 'Never'. For instance, to set the policy to 'Always', use the command as shown in the example.
Set Connector Name:
```
-assetNameSet <theConnectorGuid|ConnectorName> <NewName>
```
This command allows you to change the connector's name to a more readable format. For example: -assetNameSet DEADBEEF-CAFE-BABE-BEEF-0123456789AB NewMachineName or -assetNameSet OldMachineName NewMachineName.

Connector Restart Policies in Coreflux

Coreflux provides various restart policies to control the behavior of connectors, especially when they encounter errors or stop running. These policies determine how and when a connector should be restarted.

Always: This policy ensures that the connector is always restarted, regardless of whether it was stopped due to an error or other reasons.
OnFailure: With this policy, the connector is restarted only if it stops due to an error. If the connector is stopped manually or for reasons other than an error, it will not be restarted.
OnFailureWithMaxRetries: This policy is similar to the OnFailure policy, but with an added constraint. The connector will be restarted upon failure, but only up to a specified maximum number of retries. After reaching this limit, the connector will not be restarted again.
Never: As the name suggests, with this policy, the connector will never be restarted, irrespective of why it was stopped.

graph TD
    A[Connector Stops] --> B{Reason?}
    B -->|Error| C[OnFailure]
    B -->|Max Retries Reached| D[OnFailureWithMaxRetries]
    B -->|Any Reason| E[Always]
    B -->|Manual/Other| F[Never]
    C --> G[Restart Connector]
    D -->|Retry Count < Max| G
    D -->|Retry Count = Max| H[Do Not Restart]
    E --> G
    F --> H

This diagram visually represents the flow of how each restart policy behaves when a connector stops. Depending on the reason for the connector's stoppage and the set policy, the connector might either be restarted or left in its stopped state.

Conclusion

Coreflux provides a robust and intuitive platform for managing connectors. With the hubless solution, users can directly interact with the MQTT Broker, offering a streamlined experience. Whether you're adding new connectors, configuring them, or monitoring their performance, Coreflux ensures that you have all the tools necessary for efficient connector management.