-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' of https://github.com/Axway/amplify-integration-labs
- Loading branch information
Showing
53 changed files
with
290 additions
and
185 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,55 +2,55 @@ | |
|
|
||
| ## Introduction | ||
|
|
||
| In these labs, we'll create a set of integrations that will enable us to discover new and modified invoices and send notifications to stakeholders via MS Teams. The data will pass through Kafka. | ||
| In these labs, we'll create a set of integrations that will enable us to discover new and modified invoices and send notifications to stakeholders via MS Teams. The data will pass through RabbitMQ. | ||
|
|
||
| A demo is shown below: | ||
|
|
||
|  | ||
|
|
||
| The flows are described below: | ||
|
|
||
| * Kafka Publisher | ||
| * RabbitMQ Publisher | ||
| * Poll Zoho Invoice for new and modified invoices | ||
| * Loop over the invoices and publish to Kafka | ||
| * Kafka Consumer | ||
| * Consume Kafka message | ||
| * Loop over the invoices and publish to RabbitMQ | ||
| * RabbitMQ Consumer | ||
| * Consume RabbitMQ message | ||
| * Parse message | ||
| * Send Notification to MS Teams | ||
| * Send Notification to MS Teams channel | ||
|
|
||
| This entire data flow is illustrated below: | ||
|
|
||
|  | ||
|  | ||
|
|
||
| In this set of labs, you will learn the following: | ||
|
|
||
| * How to create a Kafka Connection | ||
| * How to publish to a Kafka Topic | ||
| * How to consume a Kafka topic | ||
| * How to create a RabbitMQ Connection | ||
| * How to publish to in a RabbitMQ queue | ||
| * How to consume from a RabbitMQ queue | ||
| * How to create a Zoho Invoice OpenAPI Connection | ||
| * How to use the Zoho Invoice OpenAPI Component to query Zoho Invoice for new and modified records | ||
| * How to create an HTTP/S Client Connection to integrate with MS Teams | ||
| * How to use an HTTP/S Client Post component to send a notification to MS Teams | ||
|
|
||
| The final integrations are shown below: | ||
|
|
||
| * Kafka Publisher | ||
|  | ||
| * Kafka Consumer | ||
|  | ||
| * RabbitMQ Publisher | ||
|  | ||
| * RabbitMQ Consumer | ||
|  | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| * Access to Amplify Integration | ||
| > If you do not have an account and need one, please send an email to **[[email protected]](mailto:[email protected]?subject=Amplify%20Integration%20-%20Training%20Environment%20Access%20Request&body=Hi%2C%0D%0A%0D%0ACould%20you%20provide%20me%20with%20access%20to%20an%20environment%20where%20I%20can%20practice%20the%20Amplify%20Integration%20e-Learning%20labs%20%3F%0D%0A%0D%0ABest%20Regards.%0D%0A)** with the subject line `Amplify Integration Training Environment Access Request` | ||
| * A free [**Zoho Invoice**](https://www.zoho.com/invoice/) account | ||
| * A Kafka instance and the ability to create topics and publish on the topic. [**Upstash**](https://upstash.com/) have free tiers and is recommanded for this lab. Alternatively, you also sign up for [**CloudKarafka**](https://www.cloudkarafka.com/) for free. | ||
| * Access to **Microsoft Teams** and the ability to install an Microsoft Teams incoming webbook connector | ||
| * A CloudAMQ RabbitMQ instance and the ability to create queues and publish on the queue. [**CloudAMQ**](https://www.cloudamqp.com/) have free tiers and is recommended for this lab. Follow this tutorial to create an instance and get access [**RabbitMQ tutorial**](assets/rabbitmq-instructions.md) | ||
| * Access to **Microsoft Teams** and the ability to install an Microsoft Teams incoming Webhook connector | ||
| > If you don't use Teams or don't have the webhook capability, you can use a test webhook online app like [Webhook.site](https://webhook.site) instead for this lab. | ||
| ## Lab 1 | ||
|
|
||
| In this lab, we'll create the first flow that will poll Zoho Invoice for updated invoices and publish each as a Kafka message. | ||
| In this lab, we'll create the first flow that will poll Zoho Invoice for updated invoices and publish each as a RabbitMQ message. | ||
|
|
||
| * Create an integration (e.g. InvoiceHandler) | ||
| * Click on the Event button and select the Scheduler Component and configure for 60 seconds | ||
|
|
@@ -73,43 +73,45 @@ In this lab, we'll create the first flow that will poll Zoho Invoice for updated | |
| * Drag a line from `LastRunDt-formatted` on the left to `last_modified_time` and click on Save | ||
|
|
||
|  | ||
| * Now let's loop over the modified invoices and publish each to Kafka | ||
| * Now let's loop over the modified invoices and publish each to RabbitMQ | ||
| * Add a For-each component, expand it and click on Config and select `GetInvoicesOutput->response->invoices` to specify the array to loop over | ||
|  | ||
| * Inside the For-each add an Apache Kafka Publish Component and expand the bottom panel | ||
| * Click on Add next to Connection to create a new Kafka Connection and give it a name and description | ||
| * Review your Upstash Kafka Details and get your Endpoint, Username and Password | ||
|  | ||
| * Inside the For-each add an RabbitMQ Publish Component and expand the bottom panel | ||
| * Click on Add next to Connection to create a new RabbitMQ Connection and give it a name and description | ||
| * Review your RabbitMQ details and get your **Cluster** host, **User & Vhost**, **Password** and **port** | ||
|  | ||
| * In the Amplify Integration Connection screen | ||
| * Enter the Upstash Endpoint for Bootstrap Servers | ||
| * Select "SASL SCRAM with SSL" for Authentication. | ||
| * Enter the Upstash username and password | ||
| * Select for SCRAM_SHA_256 Encryption Type | ||
| * Enter the protocol (here, AMQP) | ||
| * Enter CloudAMQ host and port | ||
| * Enter CloudAMQ Virtual Host | ||
| * Select Basic for Client Authentication | ||
| * Enter CloudAMQ username and password | ||
| * Click on save/update and press Test | ||
|  | ||
| * Return to the Apache Kafka Publish component in the integration and click refresh in the Connection picker and select our newly created Kafka Connection | ||
| * Expand the `ApacheKafkaPublishInput->messages` to expose the messages parameters and drag a line from the `GetInvoicesOutput->response->invoices` in the left hand panel to `ApacheKafkaPublishInput->messages->value` | ||
| * Right click on `ApacheKafkaPublishInput->topicName` and select SetValue and paste in a Topic name that you should create in your Upstash Kafka instance (e.g. invoice) and press Save | ||
|  | ||
|  | ||
|  | ||
| * Return to the RabbitMQ Publish component in the integration and click refresh in the Connection picker and select our newly created RabbitMQ Connection | ||
| * Expand the `RabbitMQPublishInput->messages` to expose the messages parameters and drag a line from the `GetInvoicesOutput->response->invoices` in the left hand panel to `RabbitMQPublishInput->messages->payload` | ||
|  | ||
| * Right click on `RabbitMQPublishInput->exchange` and select SetValue and paste in an exchange name from your CloudAMQ RabbitMQ instance (e.g. amq.topic) | ||
| * Right click on `RabbitMQPublishInput->routingKey` and select SetValue and paste in a routing key that you should create in your CloudAMQ RabbitMQ instance (e.g. invoicesKey) and press Save | ||
|  | ||
| * This is what your final integration should look like: | ||
|  | ||
|  | ||
| * Let's test it by adding an invoice to Zoho Invoice and then pressing the Test button in your integration (no need to enable the integration) | ||
| * A new browser tab will open showing the transaction. You should see that one invoice was detected by looking at the For-each step | ||
|  | ||
| * Click the `+` sign next to For-each and again and see the Apache Publish step and click on it and expand both sides to see that your invoice was published | ||
|  | ||
|  | ||
| * Click the `+` sign next to For-each and again and see the RabbitMQ Publish step and click on it and expand both sides to see that your invoice was published | ||
|  | ||
|
|
||
| Now that we can publish an updated invoice to Kafka, let's create a Kafka Consumer integration to consume the Kafka message and send a notification to Microsoft Teams | ||
| Now that we can publish an updated invoice to RabbitMQ queue, let's create a RabbitMQ Consumer integration to consume the RabbitMQ message and send a notification to Microsoft Teams | ||
|
|
||
| ## Lab 2 | ||
|
|
||
| In this lab, we'll consume a Kafka message from the `invoice` topic and send a notification with some invoice details to Microsoft Teams. | ||
| In this lab, we'll consume a RabbitMQ message from the `invoices` queue and send a notification with some invoice details to Microsoft Teams. | ||
|
|
||
| * Create an integration (e.g. InvoiceNotifier) | ||
| * Click on the Event button and select the Apache Kafka Consume Component and select the Kafka connector used in the first integration and enter the topic name (e.g. invoice) and press save | ||
|  | ||
| * Add a Map component to parse the Kafka message and expand the bottom panel | ||
| * Click on the Event button and select the RabbitMQ Consume Component and select the RabbitMQ connector used in the first integration and enter the queue name (e.g. invoices) and press save | ||
|  | ||
| * Add a Map component to parse the RabbitMQ message and expand the bottom panel | ||
| * Right click on any variable on the right hand side and select Extract and paste in the following invoice payload sample and click Copy Node | ||
|
|
||
| ```json | ||
|
|
@@ -190,77 +192,68 @@ In this lab, we'll consume a Kafka message from the `invoice` topic and send a n | |
| ``` | ||
|
|
||
| * Right click on any variable on the right hand side and select Paste and give your extract variable a name (e.g. invoiceJson) | ||
| * Expand the `ApacheKafkaConsumeOutput` variable on the left panel to expose the `recordValue` and drag a line from it to the `invoiceJson` variable | ||
|  | ||
| * Expand the `RabbitMQConsumeOutput` variable on the left panel to expose the `message -> payload` and drag a line from it to the `invoiceJson` variable | ||
|  | ||
|
|
||
| In the next few steps, we'll post a message to MS Teams with some details from the invoice. | ||
|
|
||
| We'll use the MS Teams Incoming Webhook Connector so that we can Post a message to a MS Teams channel using an HTTP/S Client Post component. | ||
|
|
||
| * Follow the instructions [**here**](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook) to get a URL to a MS Teams channel | ||
| * Follow the instructions [**here**](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498) to get a URL to a MS Teams channel | ||
| * Add an HTTP/S Client Post Connection component to your integration and expand the bottom panel | ||
| * Click Add next to Connection so we can create an HTTP/S Client Connection to the MS Teams Incoming Webhook Connector URL and give the connection a name and description and do the following: | ||
| * Select HTTPS for Protocol | ||
| * Select HTTP/2 for HTTP Version | ||
| * Enter the MS Teams Incoming Webhook Connector URL (without the https://) and press Update | ||
|  | ||
|  | ||
| * Return the HTTP/S Client Post Connection component in your integration, click refresh and select the MS Teams Connection | ||
|  | ||
|  | ||
| * In the ACTION PROPERTIES section, expand `HTTPSPostInput` to expose the `body` and right click on `body` and select SetValue | ||
| * Enter the following: | ||
|
|
||
| ```json | ||
| { | ||
| "Text": "Invoice #{invoice_number} for customer '{company_name}', total value: {currency_symbol}{total} {currency_code} is now {status}" | ||
| "type": "message", | ||
| "attachments": [ | ||
| { | ||
| "contentType": "application/vnd.microsoft.card.adaptive", | ||
| "content": { | ||
| "type": "AdaptiveCard", | ||
| "body": [ | ||
| { | ||
| "type": "TextBlock", | ||
| "text": "Invoice #{invoice_number} for customer '{customer_name}', total value: {currency_symbol}{total} {currency_code} is now {status}", | ||
| "wrap": true | ||
| } | ||
| ], | ||
| "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", | ||
| "version": "1.0", | ||
| "msteams": { | ||
| "entities": [] | ||
| } | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| * Replace the variables (e.g. {...}) by deleting them and clicking the `+` button and selecting the appropriate variable from there and click Save and then Save again | ||
|  | ||
|  | ||
|
|
||
| * in headers, add two new strings attributes : | ||
| * Accept=application/json | ||
| * Content-Type=application/json | ||
|  | ||
|  | ||
|
|
||
| * Now we're ready to test our integration which should look like this: | ||
|  | ||
|  | ||
| * Enable your integration and you should see a message in MS Teams. This is the message we published at the end of the previous lab | ||
|  | ||
| * Make sure the other integration is enabled and modify an invoice or create a new invoice in Zoho Invoice and see that you get a new message in MS Teams once the scheduler is triggered. For updating a invoice you can mark an invoice as sent and/or record a payment to change its status | ||
| * Disable both integrations (to avoid polling) when not in use | ||
|
|
||
| ## Lab 3 - Challenge yourself! | ||
|
|
||
| Use the following MS Teams card sample and modify it to make a nicer MS Teams card for your invoice and send it as the body of your HTTPS Client Post to MS Teams: | ||
|
|
||
|  | ||
|
|
||
| ```json | ||
| { | ||
| "@type": "MessageCard", | ||
| "@context": "http://schema.org/extensions", | ||
| "themeColor": "0076D7", | ||
| "summary": "Summary", | ||
| "sections": [ | ||
| { | ||
| "activityTitle": "Title", | ||
| "activitySubtitle": "Subtitle", | ||
| "activityImage": "https://adaptivecards.io/content/atbot-logo.png", | ||
| "facts": [ | ||
| { | ||
| "name": "Description", | ||
| "value": "This is a **sample *message* card**" | ||
| }, | ||
| { | ||
| "name": "Value", | ||
| "value": 29672 | ||
| }, | ||
| { | ||
| "name": "Date", | ||
| "value": "March 4, 2024" | ||
| }, | ||
| { | ||
| "name": "URL", | ||
| "value": "[More samples](https://adaptivecards.io/samples)" | ||
| } | ||
| ], | ||
| "markdown": true | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| Review adaptive card samples [here](https://adaptivecards.io/samples/) and try to make you card look nicer like this: | ||
|  | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| # RabbitMQ Invoice API integration guide | ||
|
|
||
| ## Create a RabbitMQ instance on CloudAMQ | ||
|
|
||
| 1. Start from <https://www.cloudamqp.com/> by clicking on **Get Started**\ | ||
|  | ||
|
|
||
| 2. Create an account with your email or choose Github/Google sign-up | ||
|  | ||
|
|
||
| 3. Once your account is created and you first login, you have to create a team : | ||
| - Put a team name, | ||
| - Accept tems of services, | ||
| - Decline GDPR | ||
| - Click on **Create team** | ||
|  | ||
|
|
||
| 4. Then, create a new instance by clicking on **+ Create New Instance** | ||
|  | ||
|
|
||
| 5. Put an instance name, choose `Little Lemur (Free)` plan and click **Select Region** button | ||
|  | ||
|
|
||
| 6. Select a **region** (*example AWS*) and a **data center** where your RabbitMQ instance will be deployed and click on **Review** button | ||
|  | ||
|
|
||
| 7. Review your instance information and click on **Create Instance** button | ||
|  | ||
|
|
||
| 8. Once your instance is created, you should be able to see it and access it | ||
|  | ||
|
|
||
| 9. Click on your instance name to display details like URL and credentials | ||
|  | ||
|
|
||
| 10. In order to configure an Amplify Fusion Connection, copy the following information: | ||
| - From **General** | ||
| - Cluster | ||
| - From **AMQP details** | ||
| - User & Vhost | ||
| - Password | ||
| - Port (non TLS) | ||
|
|
||
| ## Create a RabbitMQ queue and a routing rule | ||
| To publish a message in RabbitMQ, you need to create a queue and a routing rule. You can read about CloudAMQP RabbitMQ Exchanges and a Routing Keys [here](https://www.cloudamqp.com/blog/part4-rabbitmq-for-beginners-exchanges-routing-keys-bindings.html). | ||
|
|
||
| 1. Click the RabbitMQ Manager button in your CloudAMQP cluster Overview page | ||
|  | ||
|
|
||
| 2. Click on the `Queues and Streams` tab and add a new queue. | ||
| Enter a **Name** and click on **Add queue** button | ||
|  | ||
|  | ||
|
|
||
| 3. One your queue is created, click on your queue name, then go to `Bindings` section. | ||
| - Set **amq.topic** in `From exchange` | ||
| - Set **invoiceKey** in `Routing key` | ||
| - Click on `Bind` button to save. | ||
|  |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.