01-getting-started-with-flowclient.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting started with FlowClient\n",
    "\n",
    "In this tutorial you will learn:\n",
    "\n",
    "- How to connect FlowClient to a FlowKit server,  \n",
    "- How to check that the connection is working,  \n",
    "- How to update the access token used by a connection."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import the flowclient library\n",
    "The first step is to import the flowclient library.\n",
    "\n",
    "To import flowclient, run the cell below. Here we import it with the name `fc`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import flowclient as fc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Connect to a FlowKit API\n",
    "\n",
    "FlowClient is a python library that you can use on your own computer, but FlowKit (typically) runs on a remote server. To communicate with a FlowKit server, FlowClient must be connected to FlowKit's API which is accessible over a http connection.\n",
    "\n",
    "To connect to a FlowKit API, you will need to know:\n",
    "\n",
    "- the URL of the API (in these tutorials, we will connect to a demo FlowKit API which is accessible at `https://api.flowcloud-ghana.flowminder.org`),  \n",
    "- the URL of the FlowAuth instance that can provide access tokens for this FlowKit server (for these tutorials, FlowAuth is available at https://auth.flowcloud-ghana.flowminder.org),  \n",
    "- your username and password for FlowAuth (you should have been provided with these).\n",
    "\n",
    "**Note:** When you start using a \"real\" FlowKit server to analyse real CDR data, the steps described in this tutorial will be the same, but the URLs for the FlowKit API and FlowAuth will be different (as will your login details for FlowAuth)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get an access token\n",
    "A connection to FlowKit requires an access token, which controls what you are allowed to access. Each token is valid for a limited period of time, and encodes the list of actions that the token bearer is allowed to access.\n",
    "\n",
    "You can use FlowAuth to generate tokens. For the demo FlowKit server we are using in these tutorials, the FlowAuth service can be accessed at https://auth.flowcloud-ghana.flowminder.org (different FlowKit deployments will have different FlowAuth servers).\n",
    "\n",
    "To add your token in this notebook:\n",
    "\n",
    "1. Follow instructions in ['Getting an access token'](01a-getting-an-access-token.ipynb) to generate a FlowKit access token.  \n",
    "2. Paste the token in the cell below, after `token = `\n",
    "3. Run the cell\n",
    "\n",
    "**Note:** Ensure that you enclose the token in quotes (`\" \"`) so that Python recognises it as a string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Paste your token from FlowAuth here, enclosed in quotes\n",
    "token = "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create a connection object\n",
    "\n",
    "The flowclient `connect` function returns a connection object, which can then be passed as a parameter to other flowclient functions that communicate with the FlowKit server. `connect` has two required arguments:\n",
    "\n",
    "- `url` is the URL of the FlowKit API,  \n",
    "- `token` is the access token you have just created.  \n",
    "\n",
    "Run the cell below to create a connection."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "conn = fc.connect(\n",
    "    url=\"https://api.flowcloud-ghana.flowminder.org\",\n",
    "    token=token,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Check that the connection works\n",
    "You can check whether the connection works by using it in a flowclient function. The simplest is `get_available_dates`, which will return a list of available dates of data for each CDR event type (calls, SMS, ...)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fc.get_available_dates(connection=conn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If your connection is working, `get_available_dates` should have returned a dictionary with 3 keys: `calls`, `sms` and `mds` (one for each available CDR event type). The value for each of these keys is a list of all the dates for which FlowKit contains CDR data for that event type. We can see that we have CDR data available from 2016-01-01 to 2016-07-04, for each of the three event types.\n",
    "\n",
    "**Note:** If `get_available_dates` raises an error with the message \"User claims verification failed\", then your token does not allow access to the `available_dates` route. If you do not have permission to create a token with `available_dates` permission, you will need to use a different function to test whether your connection works."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Update a token\n",
    "FlowKit access tokens are time-limited, so eventually a token will expire. To continue using a connection after the token has expired, you need to update the token that the connection uses.\n",
    "\n",
    "To update a connection to use a new token, use the `update_token` method:\n",
    "\n",
    "1. Create a new token in FlowAuth, following the same steps as before,\n",
    "2. Paste the token into this notebook,  \n",
    "3. Use the connection's `update_token` method to update the token."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Paste your new token here, enclosed in quotes\n",
    "new_token = \n",
    "\n",
    "# Update the connection to use this token\n",
    "conn.update_token(new_token)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "In this tutorial you have:\n",
    "\n",
    "- used FlowAuth to create an access token, which allows you to connect to a FlowKit server,  \n",
    "- used this access token to create a FlowClient connection to a FlowKit server,  \n",
    "- checked that the connection works by getting a list of available dates of CDR data,  \n",
    "- updated your connection to use a different access token.  \n",
    "\n",
    "If you're using Binder to run this tutorial, and you would like to keep a copy of this notebook with any changes you have made, don't forget to download a copy (`File`→`Download`).\n",
    "\n",
    "In the next tutorial ([Running a query](02-running-a-query.ipynb)) you will learn how to use FlowClient to get aggregated data outputs from FlowKit."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}