Jupyter and Command Line Interfaces

• 1: Jupyter Notebooks
• 2: Command Line
• 3: OAuth Tokens

1 - Jupyter Notebooks

Jupyter Notebooks and Jupyter Lab provide exceptional interactive capabilities to analyze, explore, explain, and report data. PlaidCloud enables use of information directly in notebooks.

Install Jupyter Notebook

This assumes you have a working Jupyter Notebook installation.

Installing a Stand-Alone Jupyter Notebook

For more information on installing a Jupyter Notebook locally you can reference Jupyter’s installation documentation.

Add to VS Code

VS Code also provides an extension that allows you to run notebooks directly in VS Code. Install the extension from the Visual Studio Marketplace

Install PlaidCloud Utilities

While PlaidCloud can be accessed using stand OAuth and JSON-RPC requests, it is recommended that you use our pre-built libraries for simplified access. In addition, the PlaidCloud utilities library includes handy data helpers for use with Pandas dataframes.

To install the PlaidCloud Utilities perform the following pip installs:

pip install plaidcloud-rpc@git+https://github.com/PlaidCloud/plaid-rpc.git@v1.1.4#egg=plaidcloud-rpc

pip install plaidcloud-utilities@git+https://github.com/PlaidCloud/plaid-utilities.git@v1.1.9#egg=plaidcloud-utilities

Obtaining an OAuth Token

See OAuth Tokens for more information on obtaining an OAuth token and how to configure the system for automated auth.

Open Jupyter Notebook User Interface

Launch your notebook server to get started.

Once you are signed into your Jupyter notebook server, create a new notebook from the UI.

This will open a blank notebook.

Create a connection to communicate with PlaidCloud through the API endpoints

from plaidcloud.utilities.connect import PlaidConnection

conn = PlaidConnection()

Establish a local table object and then query it with the results automatically placed in a Pandas dataframe.

tbl_sf_cust_master = conn.get_table('Salesforce_Customer_Master') # This gets a table object
df_sf_cust_master = conn.get_data(tbl_sf_cust_master) # This retrieves all the data into a dataframe

With that same table object you can also write more advanced queries using standard SQLAlchemy syntax.

df_sf_cust_master_w_sales = conn.get_data(
    tbl_sf_cust_master.select().with_only_columns(
        [tbl_sf_cust_master.c.Id, tbl_sf_cust_master.c.CurrencyIsoCode, tbl_sf_cust_master.c.SyDSalesRegion]
    ).where(
        tbl_sf_cust_master.c.TotalSalesPast3Years > 0
    )
)

2 - Command Line

PlaidCloud uses standard JSON-RPC requests and can be used with any application that can perform those requests.

To make things easier, a Python package is available to simplify the connection and API running process.

Required Installation

From a terminal run the following command:

pip install plaidcloud-rpc

Using the SimpleRPC Object to Make a Request

To make a request using the plaidcloud-rpc package use the SimpleRPC object.

from plaidcloud.rpc.connection.jsonrpc import SimpleRPC  
  
auth_token = "Your PlaidCloud Auth Token" # See Obtaining Token below  
endpoint_uri = "plaidcloud.com" # or plaidcloud.net  
rpc = SimpleRPC(auth_token, endpoint_uri)

Once you have the SimpleRPC object instantiated you can then issue RPC request to PlaidCloud. This example requests the meta data for a table.

table = rpc.analyze.table.table(  
            project_id=project_id,  
            table_id=table_id  
        )

What APIs are Available?

There are many APIs available for use that control nearly every aspect of PlaidCloud. All of the APIs, the inputs, and expected outputs are documented in the APIs documentation.

Obtaining an OAuth Token

See OAuth Tokens for more information on obtaining an OAuth token and how to configure the system for automated auth.

3 - OAuth Tokens

PlaidCloud uses standard JSON-RPC requests and can be used with any application that can perform those requests. Requests are secured using OAuth tokens.

Obtaining an OAuth Token

OAuth tokens are generated from the PlaidCloud app. To view the list of current OAuth tokens assigned to you and generate new ones, navigate to Analyze > Tools > Registered Systems.

Once there you can view any existing tokens or choose to create a new one.

Download OAuth PlaidCloud Config File

Select “Register a New System”.

Fill out the form and note the name you entered so you can find it in the list.

Once created, open the registered system record by clicking on the gear icon. This will display the configuration file text.

NOTE: Be sure to select the project you want to use this connection for from the drop down at the top. It will add the Project Unique Identifier to the configuration.

Copy this text into a plaid.conf file located on your system. Place this in the .plaid directory.

Create a Config File Locally

Create a directory one level up from your notebook directory or from where you plan to use command line interaction. Name the directory .plaid.

Inside the .plaid directory, create a file called plaid.conf and paste the contents you copied above into the file. Save the file and this will no allow you to connect using the PlaidCloud utilities and rpc methods.

Advanced Uses

While it is convenient to locate the .plaid folder near its usage point, it can actually be placed anywhere in the upstream directory tree. The initialization process will traverse up the directory tree until it finds the .plaid directory.

Locating the .plaid directory higher up may be useful if you have multiple operations that need access but cannot coexist in the same lower level directory structures.

Optional Paths Specification

If you are using a local Jupyter Notebook installation or operating from command line, it is possible to export data, excel files, and other data as well as reading in local data to dataframes using the helper tools. To do this, a paths.yaml file is necessary.

In addition to the plaid.conf file, create a paths.yaml file. The paths.yaml should be a sibling to the plaid.conf file inside the .plaid directory. It should contain the following path information:

paths:
 PROJECT_ROOT: '{WORKING_USER}/Documents'
 LOCAL_STORAGE: '{PROJECT_ROOT}/local_storage'
 DEBUG: '{PROJECT_ROOT}/local_storage'
 REPORTS: '{PROJECT_ROOT}/reports'
 
 create: []
 local: {}