Table of Contents
- Overview
- System Requirements
- Set Up Instructions
Overview
Establishing a Data & Insights Gateway connection is a two-step process:
Agents are small programs that establish a secure connection to Data & Insights 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 on a Mac 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
- From your Data & Insights site click the “Provision Agent” button on either the:
- Admin/Gateway page ({Your_Domain}/admin/gateway) OR
- When you're choosing your data source while creating or editing a dataset
- Follow the agent naming and download process.
- Place the downloaded folder in the Home Directory on the server or computer you are connecting to the data platform (if it’s not there already). Note or copy this folder path. You’ll need it when you set up a plugin later.
- Unzip the downloaded file.
- Run the agent as a service.
- In the downloaded folder, open the macOS folder.
- Double click on the “setup” file.
- This will open the Terminal, set up the agent to run as a service, and complete the setup.
Note: You can use this process to manually restart the agent.
-
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 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
Important: All plugins associated with this agent will also stop and any Schedules associated with datasets created under this agent will stop.
Locally:
- Navigate to the folder where the downloaded agent jar file resides.
- In the macOS folder, double click the "stop" bash file.
On the Data & Insights site:
Note: This does not delete the service from your machine. It only deletes it from appearing in the data platform.
- Navigate to {Your_Domain}/admin/gateway
- Choose "Delete agent" from the "Actions" menu.
Re-starting the agent
In the macOS folder, double click the “setup” bash file.
- First identify Gateway services registered with launchctl. In the terminal, run:
launchctl list | grep socrata
- For each service listed in Step 1, run the following:
launchctl remove com.socrata.{gateway name}
- Delete any Socrata plist files from ~/Library/LaunchAgents.
- In the terminal, navigate to the folder with the agent jar file, and run:
java -jar socrata-ingress-agent.jar --show-agent-data-dir
- Delete the directory returned in Step 4.
- Navigate to [Your site].socrata.com/admin/gateway.
- Choose "Delete agent" from the "Actions" menu.
Check the status of the agent on your computer or server
- Open the terminal on your computer or server.
- In the terminal enter:
launchctl list | grep socrata
This command will list out all of the information on services running on your system. It will list the (PID) process id, status and service label for each service. The “grep” command will filter the list of services to display only those services that include “socrata” in the name.
A sample output will display:
1550 0 com.socrata.Gateway_SQL_Agent
If there are no results returned or no PID attached to the service then you may need to run the “setup” bash file again.
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 site.
- 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 download folder
- Double click the "configure" bash script, follow the prompted instructions.
- 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.
- 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
- Click "Add Plugin" either
- On the Admin/Gateway page ({Your_Domain}/admin/gateway)
- When you're choosing your data source while creating or editing a dataset
- Choose your plugin.
- Name your plugin.
- Naming tip: Who is responsible + Data source description + Data source type
- Example: Finance_Risk_CSV
- Non alphanumeric characters will be converted to underscores
- Open the terminal on your computer or server and navigate to the directory where the downloaded agent jar file resides.
- Copy and paste the plugin command into the command prompt/terminal.
- Run the command by hitting enter or return. This will download the plugin from Data & Insights, verify it, and run it on your server.
Tip: If you get an error, try changing directories. - 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.
- 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
- From the download folder double click the "configure" bash script.
- It will ask you to enter the plugin. Choose the TYPE of plugin you want to reconfigure (Note: It’s case sensitive). Press enter [ENTER].
- It will ask you to name your plugin. Type in the name of the existing plugin you want to reconfigure (Note: It’s case sensitive). Press enter [ENTER].
- 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 paltform.
- 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.
- Open the terminal on your computer or server and navigate to the directory where the downloaded agent jar file resides.
- In the terminal 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
Comments
Article is closed for comments.