FirstIntegration.md

# Creating your First Integration

Explain that this is specifically for a Madison Wisconsin use case here (but all subtle-like)

Do table of contents here

## 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). 
	- For documentation on how to create a Manifest Group, click [Here](https://kb.wisc.edu/page.php?id=25878). TODO make links that say "Here" say something actually readable
	- For documentation on how to add users to a Manifest Group, click [Here](https://kb.wisc.edu/page.php?id=25882).
	- Manifest Groups must be created within a folder. For documentation on the process of creating a folder, click [Here](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.
	- For documentation on this process, click [Here](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 the process of gaining access to IICS involves filling out a formal request. Information on this process can be found [Here](/docs/on-boarding-to-iics.md).
5. Log in to IICS. Information on how to log in can be found [Here](/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. A tutorial on sending a basic request can be found [At this Webpage](https://learning.postman.com/docs/getting-started/first-steps/sending-the-first-request/), and an overview of all their training documentation can be found [At this Webpage](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.
4. Test the API
	- TODO write something cool here
	- TODO include cool screenshots
	- yeah