Merge branch 'REBECCA.WHEELER-master-patch-51352' into 'master'

Webhook tutorial

See merge request !54

docs/tutorials/PersonAPI/Webhooks.md

+
+# Webhook Endpoint in IICS Cloud Application Integration
+
+This document describes how to create a Process in IICS Cloud Application Integration that can expose an HTTP endpoint which can accept a POST request to consume a Webhook event and request additional data from the Person API.
+
+[Here is IICS Documentation](https://docs.informatica.com/integration-cloud/cloud-application-integration/current-version/design/designing-processes/creating-a-process.html) for Cloud Application Integration 
+
+## Service Connector for OAuth
+In the Application Integration module perform the following to create a “Service Connector” for OAuth endpoint:
+1. Click “New…”
+2. Click “Service Connectors”
+3. Click “Service Connector from OpenAPI 3.0”
+4. Give the Service Connector a name and provide a source for the OpenAPI specification
+   - Download the specification from https://developer.wisc.edu/docs/oauth/1/overview
+5. Select the POST operation under “/token” operations for this Service Connector and proceed through the steps
+   - There might be warnings with the import which is expected.
+6. Once the Service Connector has been created, open the UI for the Service Connector and select the “Actions” tab.
+7. Select the Action for POST token and select “Binding” option
+8. Select “Basic” as the “Authentication Type”
+   - NOTE: you can add your “Client ID” and “Client Secret” here as well to test the connection and the request in the “Test Results” tab.
+
+## Process Objects for OAuth
+Once the Service Connector has been created, open the UI for the Service Connector and follow these steps to create Process:
+1. Select “Process Objects” and click the “+” sign on the right hand side of the list.
+2. Process Objects need to map to the responses for each Action that can be performed in a Service Connector.
+   - For the OAuth endpoint, create a Process Object that maps the the response here: https://developer.wisc.edu/docs/oauth/1/types/access_token
+3. Nested responses can be created by using the “Reference” data type where a property can be referenced to another Process Object.
+
+## App Connection for OAuth Service Connector
+Once the Service Connector and Process Objects have been created, we need to create an “App Connection” asset to use the Service Connector in a Process.
+1. Click “New…”
+2. Click “App Connections”
+3. Click “App Connection”
+4. Fill in the required information
+5. For “Type” select the Service Connector created above
+6. Add the “Client ID” and “Client Secret” in the Connection Properties section
+
+## Service Connector for Person API
+In the Application Integration module perform the following to create a “Service Connector” for Person API:
+1. Click “New…”
+2. Click “Service Connectors”
+3. Click “Service Connector from OpenAPI 3.0”
+4. Give the Service Connector a name and provide a source for the OpenAPI specification
+   - Find OpenAPI specifications here: https://git.doit.wisc.edu/interop/person-api/-/tree/main/apigee#openapi-spec-deployment
+   - Or download the specification from https://developer.wisc.edu/docs/person-api/1/overview
+5. Select the required Operations for this Service Connector and proceed through the steps
+   - There might be warnings with the import which is expected.
+6. Once the Service Connector has been created, open the UI for the Service Connector and select the “Actions” tab.
+7. For each of the Actions, select the “Input” option
+   - Add an “Input Field” of type Text for the OAuth Token (you can name this something that you prefer. I named it “token”) and unselect “Parameter”
+8. For each of the Actions, select the “Binding” option
+   - Select “Custom” as the Authentication Type
+   - Add an “HTTP Header” with name “Authorization” and value “Bearer {$token}” (replace with the name you chose on step 7a above.
+9. For each of the Actions, selec the “Output” option
+   - Add an “Output Field”, select “Reference” as the type and select the appropriate “Process Object”.
+10. NOTE: If you have a valid access_token, you can add it in the “Test with” field in the Input option for the action you want to test.
+
+## Process Objects for Person API
+Once the Service Connector has been created, open the UI for the Service Connector and follow these steps to create Process:
+1. Select “Process Objects” and click the “+” sign on the right hand side of the list.
+2. Process Objects need to map to the responses for each Action that can be performed in a Service Connector
+   - For Example, for the Person endpoint, create a Process Object that maps the the response here: https://developer.wisc.edu/docs/person-api/1/types/people
+3. Nested data structures can be created by using the “Reference” data type where a property can reference another Process Object.
+
+## App Connection for Person API Service Connector
+Once the Service Connector and Process Objects have been created, we need to create an “App Connection” asset to use the Service Connector in a Process.
+1. Click “New…”
+2. Click “App Connections”
+3. Click “App Connection”
+4. Fill in the required information
+5. For “Type” select the Service Connector created above
+6. Add the “Client ID” and “Client Secret” in the Connection Properties section
+
+## Process Objects for the event data structure
+We will need to create a Process Object that maps to the event data sent by the Person API Webhook.
+1. Click “New…”
+2. Click “Process Object”
+3. Create Process Objects that maps to the data structured defined in Example webhook event here: https://developer.wisc.edu/person-api/webhooks
+
+## Create a Process that can react to a POST request and return a valid HTTP response
+After all of the Assets above have been created and tested we can create a “Process” that can utilize them and react to events and perform the desired actions.
+
+### Creating a Process
+1. Click “New…”
+2. Click “Processes” > “Process” > “Create”
+
+### Configuring the “Start” step of the process
+1. Once created, click “Start” (Green circle) step
+2. In the Properties pane for the “Start” step, in the “Start” tab
+   - Select “REST/SOAP” as the “Binding”
+   - Select “Allow anonymous access”
+   - Select “Cloud Server” for “Run On”
+3. In the “Input Fields” tab, add the event Process Object created above as the input.
+4. Add any Output Fields that might be required for the Process.
+
+### Adding a “Service” step for getting an OAuth token
+1. In the Design pane, add a “Service” step
+2. In the Properties pane for this Service step, in the “Service” tab
+   - Select “Connection” as the “Service Type”
+   - Select the OAuth App Connection asset created above as the “Connection”
+   - Select POST token as the “Action”
+3. In the “Input Fields” tab add a field for “grant_type” and set the Value to Content with “client_credentials” as the value.
+
+### Adding a “Service” step for getting Person data
+1. In the Design pane, add a “Service” step
+2. In the Properties pane for this Service step, in the “Service” tab
+   - Select “Connection” as the “Service Type”
+   - Select the Person API App Connection asset created above as the “Connection”
+   - Select the “Action” you need to perform (I used the get_person action as an example)
+3. In the “Input Fields” tab, you should see “id” and “token” fields.
+   - Map the “id” field to the id value of the person in the event data
+   - Map the “token” field to the access_token value of the Response from the POST token step above.
+
+### Add additional steps to perform the action your process needs.
+
+## Pros and Cons of using IICS CAI as a webhook endpoint
+### Cons:
+1. IICS CAI has limited connector options than IICS CDI
+2. Configuring Process Objects can be time consuming 
+   - This is especially true for Person API as the data structures can be dynamic.
+3. Each process needs to be built from scratch
+4. IICS CAI does not have the ability to read headers at the start of the process. The Person API Webhook sends a token in the header that consumers can validate to make sure that the event data is coming from the correct source. This is not possible.
+   - To facilitate this validation process, changes need to be made to the Person API. Example, send the token in the request body instead.
+
+### Pros:
+1. It is easy to create an endpoint that can be used as a webhook endpoint.
+2. When used in conjunction with an API, it can provide an alternative to ETLs that perform large pulls of data.
+