diff --git a/docs/tutorials/PersonAPI/Webhooks.md b/docs/tutorials/PersonAPI/Webhooks.md new file mode 100644 index 0000000000000000000000000000000000000000..7e13512b684bfb62e0e1638086f68d8b937435d1 --- /dev/null +++ b/docs/tutorials/PersonAPI/Webhooks.md @@ -0,0 +1,128 @@ + +# 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. +