Installing and Configuring the Haystack Adapter

Scenario: You want to connect Desigo CC to the Haystack subsystem.

 

Reference: For background information, see the related reference section.

 

Workflow diagram:

 

 

Prerequisites:

  • The Haystack extension was installed and included in the active Desigo CC project.
  • The Haystack_Adapter.msi is available at the following path: GMSMainProject > AddSW > Haystack.
  • You know the IP addresses of the Haystack subsystems and user names to access them.

 

Steps:

1 – Configure Haystack User in the Credential Manager
  • A user account must exist and be enabled in the Haystack subsystem that can be used to connect the Haystack adapter (Haystack user account). A user security configuration is required in the Credential Manager of the computer where the Haystack adapter will be installed.
    NOTE: You can install the Haystack adapter software on any networked computer that can connect to the Haystack subsystem and to Desigo CC. Typically, you want to install it on the Desigo CC server station.
  1. Press the Windows key on the keyboard or click the Windows Start icon or open the Windows Control Panel.
  1. Start typing (in Control Panel, search for) credential manager, and select the Credential Manager icon .
  • The Credential Manager window displays.
  1. If multiple credential vault icons display, make sure to select WindowsVault:
  1. Select Add a generic credential.
  1. In the Add a Generic Credential page, do one of the following:
  • In the Internet or network address field, enter the User name, then enter User name (again) and Password of the Haystack user account, and click OK.
    NOTE: Indicating the user name in the Internet or network address field results in the same account being used for all Haystack subsystems (which must all be configured to allow connection from the same user account).
  • In the Internet or network address field, enter the full network path of the haystack project (for instance https://192.168.1.100/api/demo), then enter User name and Password of the Haystack user account, and click OK.
    NOTE: Indicating a specific Haystack subsystem in the Internet or network address field results in the account being used for that Haystack subsystem only. This individual setting overrides the previous broad setting that you may also add as an additional credential, for example, if a you have a number of Haystack subsystems with the same user name and password and one that requires a different user name and/or password.
  1. Close the Credential Manager window.

 

2 – Install the Haystack Adapter
  1. On the computer where you want to install the Haystack adapter, run Haystack_Adapter.msi.
  1. Follow the installation instructions.
  1. Open the installation folder and run the batch file StartAdapter_Configuration.bat.
  • When running for the first time in console mode, the adapter creates the Adapter.config file and opens it in a new window with Notepad.
    NOTE: in all .config files, blank lines and lines starting with # are comments.
  1. In the Notepad window, configure the Adapter.config file by specifying the default Haystack tags to use for Site, Equipment, and Point entities when imported in the Desigo CC Name and Description in System Browser. Any missing tag will be replaced by the id identifier (default tag):
    Sites: <Haystack Tag for Name>, <Haystack Tag for Description>
    Equipments: <Haystack Tag for Name>, <Haystack Tag for Description>
    Points: <Haystack Tag for Name>, <Haystack Tag for Description>
    NOTE:     Using id for the name is always recommended.

    For example:


  1. Select File > Save and then File > Exit.
    NOTE: To change this setting in future, run again StartAdapter_Configuration.bat.
  1. In the adapter console window, press Enter to continue.
  • When running for the first time in console mode, the adapter starts the HaystackAdapterConfigurator tool.

 

3 – Configure the Haystack Adapter

  1. If not already open, start the HaystackAdapterConfigurator tool from the installation folder.
  • The Haystack Configuration Tool window displays.
  1. On the upper side of the window, click Subsystem Configuration.

  1. If you have already prepared a configuration that you want to modify, proceed as follows:
  • On the top right corner of the window, click Browse.
  • Locate and select the SubsystemConnections.config file.
  • Select Open.
  • The list of configured Haystack subsystems displays on the right-hand side of the window formatted as a two-column table.
  1. To add a new subsystem:
  • Enter the Device Name (a label).
  • Enter the subsystem URL.
  • Enter the Generic Credential (Username or URL) to access the subsystem, as defined above.
    NOTE: The list of credentials displays in the bottom part of the window, organized in a single-column table. Click Generic Credentialavailable to access and configure the Generic Credentials in Windows.
  • Click Add.
  • The new subsystem is appended to the list.
  1. To remove a subsystem:
  • Select the subsystem in the list and click Remove.
  1. To modify a subsystem:
  • Select it and modify the parameters as necessary.
  • Click Add to append a new entry.
  • Click Remove to delete the old entry.
  1. Click Save As… to save the configuration into the SubsystemConnections.config file.
  1. Optionally (for expert users), click Subsystems to open the output file with Notepad. Each configured subsystem has a section that includes URL and User, as configured in the tool, and the monitoring polling frequency, which you can customize here (default is 15 sec).
    [Haystack Connection x]
    URL: < http://<path> or < https://<path>
    User: <user name>
    WatcherPolling: <seconds>

    For example:


  1. Select File > Save and then File > Exit.
    NOTE: To change the configuration in future, modify the SubsystemConnections.config file and then stop and start the adapter again.
  1. In the adapter console window, press Enter to continue.
  • The adapter starts and tries connecting to the configured Haystack subsystems and query for Sites and Equipments. Points are queried as configured in the HaystackConfiguration.csv file (see below). Connection errors are reported on the console window with a message in red (check the related settings). Successful connections result in messages being displayed in white (Discovery and then Watcher).

 

4 – Configure the Haystack Discovery Rules
  • You can configure a set of filtering and mapping rules to control the acquisition of Haystack entities into System Browser.
  • The HaystackAdapterConfigurator tool is open.

  1. On the upper side of the window, click Haystack CSV Configuration.
  • Two data sections display:
  • Functions and Descriptions section
  • Import section
  • The two sections define two corresponding groups of rules that enable you to:
    - Control the configuration of Description and Functions for specific Haystack entities (Site, Equip, Bool, Number, Str) in Desigo CC.
    - Filter in or out specific Haystack entities.
    For more information, see Haystack Discovery Rules and CSV Format.
  1. Configure the rules as necessary and click Save As… to save the configuration into the HaystackConfiguration.csv file.
  • The adapter takes into account the new configuration and updates the Haystack objects in System Browser.
  1. Check the new System Browser configuration. If necessary, repeat the steps above to refine the configuration.

 

5 – Start the Haystack Adapter as a Service
  • Once the configuration is in place, you can start the Haystack adapter as a service and let it run in the background. Note that connection faults are reported in Desigo CC Event List.
  1. If still open, close the Haystack adapter console window.
  1. From the adapter installation folder, run one of the following batch files:
  • Install_AdapterAsService_HTTP, to run the HTTP service on port 8080
  • Install_AdapterAsService_HTTPS, to run the HTTPS service on port 443
    NOTE: HTTP or HTTPS refers to the protocol applied between Desigo CC and the Haystack adapter.
  • The adapter service starts with the new configuration.
    NOTE: You can run Uninstall_AdapterAsService.bat to remove the service. You can also run the adapter in console mode with the following batch files:
    - StartAdapter_HTTP.bat
    - StartAdapter_HTTPS.bat