Table of Contents

1. Overview
2. System Requirements
3. Set Up Instructions
   1. STEP 1: Create an Agent
      1. Start the agent and run it as a service
      2. Stopping the agent/service
      3. Re-starting the agent
      4. Delete or Uninstall the agent/service
      5. Check the status of the agent on your computer or server
   2. STEP 2: Add and Configure a Plugin 
      1. Option 1: Start from the Command Line
      2. Option 2: Start from the Data & Insights data site
      3. Reconfigure a plugin
      4. Removing a plugin

Overview

Establishing a Data & Insights Gateway connection is a two-step process:

1. Create an agent
2. Add a plugin (or plugins) to that agent

Agents are small programs that establish a secure connection to the Data & Insights data platform and act as a manager for a plugin or set of plugins.

After the agent is downloaded and set up, we’ll help you connect to your individual data sources with plugins for specific data types.

You can add as many plugins as you like to a single agent, including multiple plugins of the same type.

You can find a 60-second video on setting up an agent in Windows here. 

System Requirements

The agent requires Java 8 or newer
Find it here: OpenJDK 11

Networking
The host must be allowed to make connections to the Data & Insights platform on port 443

SSL
If you have special SSL and/or Self-Signed Certificates configured, they must be added to the Java trust store. For more information, please see: http://www.thesqlreport.com/?p=576

User Permissions
Sudo (root) or Administrator access is required to configure the service

Set Up Instructions

 

STEP 1: Create an Agent

Start the agent and run it as a service

1. From your Data & Insights data site click the “Provision Agent” button on either the:
   1. Admin/Gateway page ({Your_Domain}/admin/gateway) OR
   2. When you're choosing your data source while creating or editing a dataset
2. Follow the agent naming and download process.
3. Place the downloaded folder in a directory on the server or computer you are connecting to the Data & Insights data site (if it’s not there already). Note or copy this folder path. You’ll need it when you set up a plugin later.
4. Extract/Unzip the downloaded file.
5. Open the subfolder named “Windows”.
6. Run the agent as a service.
   1. Right-click on the “Install” Windows batch file.
   2. Choose “Run as an Administrator”.
   3. This will launch the command prompt.
   4. In the command prompt, name the Service (it will say “Enter Service Name”) and choose a name that makes sense to you.
   5. Hit “Enter”.

7. Check the status of your agent to ensure the set up was successful. A successfully connected agent is needed before you can move on to step 2 of the Gateway set up — adding and configuring a plugin.

On your Data & Insights data site you can check the agent status in the following places:

• In the “Provision Agent” set up stepper (On the “Set up instructions” page there is an “Am I connected?” widget. Clicking “refresh” will check your connection.
• On the Admin/Gateway page ({Your_Domain}/admin/gateway), it will appear in the table
• When you're choosing your data source while creating or editing a dataset it will appear in the list as “Connected”

Stopping the agent/service

Important: All plugins associated with this agent will also stop and any schedules associated with datasets created under this agent will stop.

1. From the start menu, search for and select "Services”.
2. Scroll to your Windows Service (created in the Starting Your Agent section). The description will be 'The Socrata Ingress Agent.
3. Right-click on the service and select "Stop”.

Re-starting the agent

Right-click the service and select "Start”.

Delete or Uninstall the agent/service

Locally:

1. Open command prompt as an administrator.
2. Run: sc.exe delete {the name of your service}.
   

On the Data & Insights data site:

Note: This does not delete the service from your machine. It only deletes it from appearing on the data platform.

1. Navigate to {Your_Domain}/admin/gateway
2. Choose "Delete agent" from the "Actions" menu.

Check the status of the agent on your computer or server

1. Open the Windows Services Manager.
   1. Search for Windows Service Manager OR
   2. Run services.msc from the Run box
2. Find your agent. The description will be “The Socrata Ingress Agent”.
3. Check the “Status” column

STEP 2: Add and Configure a Plugin

TIPS:

• ”PLUGIN_TYPE” is a type from a list you’ll be presented upon set up.
• “PLUGIN_NAME” is a name you select to identify this plugin on the Data & Insights platform.
• Configuration for the plugin type and plugin name are case sensitive. Please ensure you’re using the case presented at set up.
• You can add as many plugins as you like to a single agent, including multiple plugins of the same type.

Option 1: Start from the Command Line

Open the command prompt on your computer or server and navigate to the directory where the downloaded agent jar file resides.

1. To list available plugin types
   1. java -jar socrata-ingress-agent.jar --list-available-plugins
2. To install or reconfigure a plugin
   1. java -jar socrata-ingress-agent.jar --configure-plugin PLUGIN_TYPE:PLUGIN_NAME
   2. Example: java -jar socrata-ingress-agent.jar --configure-plugin csv:Finance_Risk_CSV
3. When the plugin is run it will display a window on your server asking for plugin-specific configuration and credentials (if needed). This information will not live on the Data & Insights platform.
4. Fill out the configuration information and click “OK”. Return to the data site and your plugin will then be ready to use!

Option 2: Start from the Data & Insights data site

1. Click "Add Plugin" either
   1. On the Admin/Gateway page ({Your_Domain}/admin/gateway)
   2. When you're choosing your data source while creating or editing a dataset
2. Choose your plugin.
3. Name your plugin.
   1. Naming tip: Who is responsible + Data source description + Data source type
   2. Example: Finance_Risk_CSV
   3. Non alphanumeric characters will be converted to underscores
4. Open the command prompt on your computer or server and navigate to the directory where the downloaded agent jar file resides.
5. Copy and paste the plugin command into the command prompt.
6. Run the command by hitting enter or return. This will download the plugin from the Data & Insights site, verify it, and run it on your server.
   Tip: If you get an error, try changing directories.
7. When the plugin is run it will display a window on your server asking for plugin-specific configuration and credentials (if needed). This information will not live on the Data & Insights platform.
8. Fill out the configuration information and click “OK”. Return to the data site and your plugin will then be ready to use!

Reconfigure a plugin

1. Open the command prompt on your computer or server and navigate to the directory where the downloaded agent jar file resides.
2. In the command prompt enter:
   1. java -jar socrata-ingress-agent.jar --configure-plugin PLUGIN_TYPE:PLUGIN_NAME
   2. Example: java -jar socrata-ingress-agent.jar --configure-plugin csv:Finance_Risk_CSV
3. When the plugin is run it will display a window on your server asking for plugin-specific configuration and credentials (if needed). This information will not live on the Data & Insights platform.
4. Fill out the configuration information and click “OK”. Return to the data site and your reconfigured plugin will then be ready to use!

Removing a plugin

Important: All schedules associated with the dataset(s) created under this plugin will break when you remove the plugin.

1. Find your gateway agent service in Services and stop the service

2. Open the command prompt on your computer or server and navigate to the directory where the downloaded agent jar file resides.
3. In the command prompt enter:

    java -jar socrata-ingress-agent.jar --delete-plugin PLUGIN_TYPE:PLUGIN_NAME
   
    Example: java -jar socrata-ingress-agent.jar --delete-plugin csv:Finance_Risk_CSV