# 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.
Webhooks are a great way to receive notifications for changes to person data without having to consume an entire batch of data to find the changes yourself. This is a feature of the Person API and you can find the knowledgebase article for Webhooks [here](https://developer.wisc.edu/person-api/webhooks).
-[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
-[Here is the API Team's Webhook Documentation](https://developer.wisc.edu/docs/person-api/1/routes/people/webhooks/get) for a full overview on how to subscribe to Webhooks and receive a validation token for the Person API.
## 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 and add your username and password (Or API keypair) into the corresponding "Test With" fields on the Definition tab
7. Select the “Actions” tab and verify POST_token is selected.
8. Select the Input option and rename the Input Field as "grant_type" and add "client_credentials" in the Test With field.
9. Select “Binding” option.
- Select “Basic” as the “Authentication Type”
- In the HTTP Headers section, in Content-Type's Source field, remove "; charset=UTF-8" so that the field's entry now only says "application/x-www-form-urlencoded"
- Verify Binding Type is selected as Form
- 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
- 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
We have created a full tutorial on subscribing to Person API Webhooks and consuming them with Informatica. You can find this tutorial in Canvas in [Section 8](https://canvas.wisc.edu/courses/378847/pages/8-dot-a-introducing-webhooks) of the full [UW Integrator Training](https://canvas.wisc.edu/courses/378847).
## 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.
## References
### 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
### 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.
-[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
-[Here is the API Team's Webhook Documentation](https://developer.wisc.edu/docs/person-api/1/routes/people/webhooks/get) for a full overview on how to subscribe to Webhooks and receive a validation token for the Person API.
