FirstIntegration.md

# Creating your First Integration

This tutorial covers the full process that a University of Madison-Wisconsin integrator will use to create their own end-to-end data integration, gaining access to several sources and targets and facilitating an automated data transfer using IICS.

## Table of Contents

- [Gaining Access to IICS](#gaining-access-to-iics)
- [Gaining Access to PersonAPI](#gaining-access-to-personapi)
- [Creating a Box Folder](#creating-a-box-folder)

## Gaining Access to IICS

You will be unable to use any practical functionality in IICS until they have an IICS account with permissions applied to it. Acquiring this account is dependent on contacting the IICS administrators. This process is outlined on our [Onboarding Page](/docs/on-boarding-to-iics.md).

If you are following along with this tutorial, you most likely will have already started the process of accessing the IICS service. The steps of this process will be hosted on this page as a quick reference, however.

1. Create a Manifest Group, and add all related personell who will be using IICS (including yourself). 
	- The Madison-Wisconsin KnowledgeBase has [Documentation on Creating Manifest Groups](https://kb.wisc.edu/page.php?id=25878) and [Documentation on Managing Group Members](https://kb.wisc.edu/page.php?id=25882).
	- Manifest Groups must be created within a folder. The KnowledgeBase has [Documentation on Folders](https://kb.wisc.edu/page.php?id=27783).
	- As an alternative to this first step, if your team already has a Manifest Group, that may be used.
		- If this Manifest Group is already used to provision access to IICS, you may skip to step 5.
2. Grant our team at uw:org:ais:ais-admins Read and View permissions to your group.
	- We will be unable to view your group or apply the automated IICS account provisioning unless you do this.
	- There is [Documentation on Managing Manifest Group Permissions](https://kb.wisc.edu/25880).
3. Contact our Team so that we can apply the correct permissions to your Manifest Group.
	- IICS automatically sets up accounts for any users in Manifest Groups with specified permissions, but those permissions must be set up by us.
	- There may be some delay on this step, although the turnaround should be no more than 1-2 business days. Our team will contact you once this step has been completed.
	- Note that gaining access to IICS involves filling out a formal request. Information on this process can be found in our [Onboarding Docs](/docs/on-boarding-to-iics.md).
5. Log in to IICS. This can easily be done from [Our Log-In Documentation](/docs//logging-in.md).
	- IICS has two orgs associated with it - test and prod. It is heavily reccomended that you log in to both, as to make sure your account exists within the system.
	- If you intend to change org on the same browser, it is heavily reccomended that you manually log out by clicking the "log out" button on the top right of the homepage or under the profile tab of the top bar on any other page. 
	- If you fail to log out, IICS will fail to change organizations when logging in using a different link.
6. Contact our Team so that we can apply correct permissions to you.
	- If you are working alongside multiple team members it is reccommended that all team members are logged in before you contact us, so we can provide permissions for everyone in one round of communication.

## Gaining Access to PersonAPI

The primary components of any integration are a Data Source (where the information you are retrieving comes from) and a Target (where you are putting the information you retrieved). For this Integration we will be using the Mock Person API as the data source.

It is highly reccommended that you pursue accessing this data source while waiting to gain access to IICS, as to minimize the amount of time spent making no progress.

1. Sign in to the API portal and register your Application.
	- Information on this process can be found at the [Person API Docs](https://developer.wisc.edu/get-started).
		- The information relevant to this specific tutorial can be found in all steps up to and including "Register an Application".
		- When creating your Application, Enable the Mock Person API. You will not need any other APIs for this specific tutorial.
		- When the Application is created, it will also be provisioned an API key. Make sure to note down the Key and Secret from this, as they will both be used multiple times
	- You must have a Wisconsin NetID in order to access this service.
2. Sign up for Postman to test your Application.
	- Postman is a free service that allows a user to make calls to APIs from an easy-to understand interface. Information and downloads can be found at the [Postman Homepage](https://www.postman.com/).
		- Note that Postman can also be used directly from a web browser, in case downloading the app is unwanted or undesireable.
	- If you are having trouble understanding Postman, you can pursue their training options. They have [A Tutorial on Sending your First Request](https://learning.postman.com/docs/getting-started/first-steps/sending-the-first-request/), as well as [A More Generalized Overview of All of Their Training Services](https://learning.postman.com/docs/introduction/overview/).
3. Set up the API call and credentials within Postman.
	- You will be sending a GET request to the url https://mock.api.wisc.edu/people.
	- Once the basic request has been set up, click the tab below the request bar that says "authentication" and scroll down to where it says "configure new token".
		- Name the token as you please.
		- Set the grant type to "Client Credentials".
		- The Access Token URL is https://api.wisc.edu/oauth/token. 
		- The Client ID is the "Key" from the API Key.
		- The Client Secret is the "Secret" from the API Key.
		- Leave the Scope Blank.
		- Client Authentication should be "Send client credentials in body".
	- Once the token has been configured, press "Get New Access Token".
		- If you are testing in multiple sessions, you will need to Get a New Access Token multiple times, as the Access Token expires after a few hours.
	 	- Note that Postman will save the information you filled out, so you will only need to press the "Get a New Access Token" button.
	- To test the API, press the blue "Send" button near the URL input bar.
		- A successful run will return a list of several people, each with unique associated information (most identifiably, a name).
		- A 401 error will represent an error with validation - either an expired token, or invalid information used in the creation of the token.

A successful test should look something like this:
![Mock API Postman Test](docs/tutorials/FirstIntegration/mockapipostmantestphoto.png "Mock API Postman Test")

## Creating a Box Folder

Box is an online file storage solution, and is free for University of Madison-Wisconsin users. More information can be found at [The UW-Madison Information Technology Department's Box Page](https://it.wisc.edu/services/box/).

This segment of the tutorial is also able to be completed without direct access to IICS.

1. Sign up for a Box account with your UW-Madison netid
	- UW Madison's offerings for Box can be found at http://uwmadison.box.com/
	- If you already have a Box account set up in UW Madison, this step is unnecessary.
2. Create a new Folder in your Box account.
	- When logging in, there will be a button labelled "New+" at the top right of the screen. Clicking this will bring up a dropdown, in which you can create a New Folder.
	- More specific documentation on creating a folder can be found in [Box's Folder and File Creation Tutorial](https://support.box.com/hc/en-us/articles/360043696394-Create-New-Files-And-Folders)

## Creating Connectors in IICS

- need to have iics access from this point forwards
- log in to TEST
- navigate from the main page to the administrator page
- navigate the left bar to the connections page
- top right new connection

BOX

- name the connection something easily identifiable and related to you
- click "type" and select "Box (Infomatica)"
- set runtime enviornment to ei.secureagent.doit.wisc.edu
- click the "get token" button next to OAuth Token
	- this will open a new window. log in to Box and follow the prompting of the new window.
- set the Box File or Folder ID to be the id of the folder you created in step one.
	- this is the end bit of the url of the folder
	- maybe this is better mentioned in that specific section?
- make sure Access Token Type is set to auto-generated
- save the connection

NAVIGATION

- NAVIGATE BACK TO THE CONNECTIONS TAB AGAIN
- CREATE A NEW CONNECTION AGAAIN

API

- once more name it
- click "type" and select "REST v2 (Informatica)"
- runtime enviornment again
- set "authentication" to OAuth 2.0-Client Credentials
- access token is https://mock.api.wisc.edu/people
- client id and secret are from the second section go back andget that shit if you didnt save it
- client auth should be "Basic Auth Header"
- swagger file path TODO TODO GET A GOOD SWAGGER FILE TODO TODO
- save