Getting Started

Home/Getting Started

Getting Started

The PlaidLink Agent works in conjunction with PlaidCloud service. The PlaidLink Agent enables remote operations for extracting, loading, and sourcing data along with interacting with an SAP Profitability and Cost Management (PCM) system if PCM is installed.

Create an Agent on PlaidCloud #

PlaidLink Agent management takes place within the Analyze tab of PlaidCloud. The first step is to create a new PlaidLink Agent instance on PlaidCloud.

To create a new PlaidLink Agent:

  1. Select the Analyze tab
  2. Select the tools menu from the top
  3. Click PlaidLink Agents
  4. Create a new Agent with an appropriate name for the environment or server that it will be installed on for remote operations

To view the Agent public and private keys:

  1. Click on the edit icon to view the form
  2. At the bottom of the form you will find the public and private keys that were randomly generated during the Agent creation process
    • Remember these keys, as they will be used in the agent configuration on the remote server.

To randomly generate new keys:

  1. Click on the Regenerate icon for the Agent record
  2. Once the keys are regenerated, don’t forget to update the agent configuration file with the new keys on the remote server.

Note: Retain the public and private keys for configuring the remote agent in the next step.

Document Account Access #

If the agent will need to have access to a Document account for uploading or downloading files, it must be granted permission to access the Document account.

To grant account access:

  1. In the Document tab select Manage Accounts
  2. Once the table of accounts appears, click on the agent icon for the account which the new Agent should have upload/download rights
  3. Drag the new agent into the Assigned Agents column
  4. Save the access control form.

Note: Agents can only upload and download files if the agent has been granted access to one or more Document accounts.

Data Connection Access #

If the agent will need to have access to a data connection such as a database, it must be granted permission to access the external data connection information.

To grant connection access:

  1. In the Analyze tab select the Tools menu
  2. Click External Data Connections
  3. Once the table of data connections appears, click on the agent icon for the connection, which the new Agent should have usage rights
  4. Drag the new agent into the Assigned Agents column and save the access control form.

Note: Agent data connection credentials are managed in the External Data Connections.

Installation #

The PlaidLink Agent handles initiating all contact with PlaidCloud and does not require opening any ports in the firewall for performing operations. The connection occurs over an encrypted communication channel at all times. Standard HTTPS connections or secure websocket connections are used.

Installing Python (Use Web Browser) #

  1. Download the Anaconda python [installer](https://www.continuum.io/downloads#all “Anaconda Python Installer”) for the latest version of Python 2.7.x
  2. Install it

Install Git (Use Web Browser) #

  1. Download the [Git](http://git-scm.com/download/win “Git”) installer
  2. Run the installation.

Note: Allowing Git use from both git bash and the Windows command line is recommended, but overwriting Windows CLI tools with Unix tools IS NOT recommended.

Generate SSH Keys (Use Git Bash) #

  1. From the Start menu, open the newly installed Git Bash application.
  2. At the command prompt type the following (or copy/paste): mkdir ~/.ssh/ ssh-keygen -t rsa -b 4096 -N “”

Send Contents to Tartan Solutions (Windows Explorer and Email) #

From the .ssh directory copy the id_rsa.pub file and email to your Tartan Solutions contact for addition to the installer access list. This key will be registered for the specific server being installed.

Installing Packages not in Anaconda (Use Windows Command Line) #

Note: If you cannot use a direct or proxy connection to perform conda or pip install operations, please scroll to the bottom of the installation guide below for a manual installation process.

  1. From the Start Menu, open the Windows Command Line application as an Administrator
  2. You must manually install the pyodbc package using conda: conda install pyodbc conda install workerpool

If http connections require passing through an authenticated proxy, you will need to set up the .condarc file in the user’s home directory. The file should have the following lines: proxy_servers: ` http: http://user:pass@corp.com:8080` ` https: https://user:pass@corp.com:8080`

The following should be installed using pip: pip install websocket-client pip install gitpython

If you need to use a proxy server for the pip installs then they should follow this syntax instead: pip install –proxy http://user:pass@corp.com:8080 websocket-client pip install –proxy http://user:pass@corp.com:8080 gitpython

Installing PlaidLink (Use Git Bash) #

Once you receive a confirmation response from Tartan Solutions that your id_rsa.pub key has been added to the access list, you can proceed with this next step.

  1. Change to the root of the user working directory.
    • cd ~
  2. Make sure you are in the base user directory before proceeding
    • pip install -e git+ssh://git@github.com/PlaidCloud/profitagent.git#egg=profitagent

Note: If http connections require passing through an authenticated proxy, you will need to use the proxy switch in the pip command pip install and proxy http://user:pass@corp.com:8080 -e git+ssh://git@github.com/PlaidCloud/profitagent.git#egg=profitagent

This will create a src/profitagent directory with respect to your current working directory.

Update the Config File (Use Windows Explorer and Notepad) #

An initial configuration file is included in the package, named config-dist.json. Make a sibling copy to edit:

This will be in the following directory relative to the user base directory: src/profitagent/profitagent cp config-dist.json config.json

Copy the agent settings from PlaidCloud into the configuration file. Also set any proxy information required to make an external connection.

Set Up a Windows Service (Use Windows Command Line) #

To install a Windows service, you must have administrative privileges.

The new Windows service should now appear in the list of services on the server. It will be listed as PlaidCloud Agent in the services. The Windows application logs will list the reporting application as PlaidCloudAgent.

Manual Install #

If there are network settings that prevent the use of direct connections or proxied connections to perform Conda and PIP installations, a manual process must be followed. This process will manually install the following packages:

  • pyodbc
  • workerpool
  • websocket-client
  • gitpython
  • profitagent

For each of the installations above, the first step is download the package via a web browser and place it in the user directory where the PlaidLink service will operate.

Once all zip files are downloaded they should be unzipped into the same parent directory. For example: c:usersagentpython_packages

PIP Install Supporting Packages #

Now that all the packages are present on the server locally, the next step is to PIP install them so they are properly registered with the system Python process.

  1. Navigate to the directory where all the supporting python packages are present:
    • For example: c:usersagentpython_packages
  2. Now run each of the following commands in Git Bash:
    • ‘pip install ./pyodbc’ ‘pip install ./workerpool’ ‘pip install ./websocket-client’ ‘pip install ./GitPython’

Install the PlaidLink Package Provided #

The PlaidLink zip file must be provided by a Tartan Solutions contact since direct access is not authorized except through the automated installation process. If the Tartan Solutions contact has not already provided the installation package, please contact them.

  1. Unzip the PlaidLink installation files into the user’s home directory where the service will operate under in a directory called src/
    • For example: c:usersagentsrc
  2. Navigate to the directory that contains the PlaidLink package
  3. Run the following command in Git Bash: ‘pip install -e ./profitagent’

Resume Configuration and Registration #

Now follow the instructions for updating the config file and registering the process as a Windows Service, as described in the two sections before this Manual Install section.

Go to Top