Skip to content

Commit 80510c8

Browse files
pcnfernandopcnfernando
authored
Merge pull request #64 from SachinAkash01/main
Add quick deploy guide for file integration
2 parents 7943a54 + 14107e9 commit 80510c8

File tree

1 file changed

+181
-0
lines changed

1 file changed

+181
-0
lines changed

Diff for: ‎en/docs/quick-start-guides/deploy-your-first-file-integration.md

+181
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Deploy Your First File Integration
2+
3+
## Overview
4+
5+
In this guide, you will:
6+
7+
- Create a FTP listener that fetches recent weather data.
8+
- Use Ballerina Integrator to develop the File integration.
9+
- Push the File Integration to Devant from Ballerina Integrator, which will automatically build and deploy it into the development environment.
10+
- Test the File Integration.
11+
- Promote it to the production environment and use it as an API.
12+
13+
## Prerequisites
14+
15+
1. GitHub account: [Create a GitHub account](https://github.com/signup) if you don't have one already.
16+
2. If signing in to Devant for the first time, create an organization:
17+
1. Go to [https://console.devant.dev/](https://console.devant.dev/) and sign in using Google, GitHub, or Microsoft account.
18+
2. Enter a unique organization name. For example, `Stark Industries`.
19+
3. Read and accept the privacy policy and terms of use and click **Create**.
20+
3. VS Code: [Install VS Code](https://code.visualstudio.com/download) if you don't have it installed already.
21+
22+
## Step 1: Attach a Git repository
23+
1. Go to [https://console.devant.dev/new](https://console.devant.dev/new) and sign in. This opens the new integration page.
24+
2. On the new integration page, click **Attach a Git Repository**.
25+
26+
!!! tip
27+
If you're using a public Git repository, you can skip ahead to sub-step 8. Click **Use a Third-Party Public Git Repository** and enter the repository URL.
28+
29+
3. Click **Authorize with GitHub** to connect Devant to your GitHub account. If you haven't connected your GitHub repository to Devant, authorize the WSO2 cloud app with your GitHub account [WSO2 Cloud App](https://github.com/marketplace/choreo-apps).
30+
4. Under the **Organization** dropdown click **+ Add**. This redirects you to the **Install WSO2 Cloud App** page.
31+
5. Select your GitHub account and install [WSO2 Cloud App](https://github.com/marketplace/choreo-apps)
32+
33+
!!! note
34+
The **WSO2 Cloud App** requires:
35+
36+
- Read and write access to code and pull requests.
37+
- Read access to issues and metadata.
38+
39+
You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) at any time. Write access is used to push changes directly to your repository.
40+
41+
6. Under the **Organization** dropdown, select your organization. If it is still not listed, click the Refetch button.
42+
7. Select a repository to save your integration.
43+
8. Select a **Branch** and a **Path** of the selected repository to save your integration.
44+
9. **Name** and **Identifier** fields are automatically populated. Additionally, you can edit them to your preference.
45+
10. Select the **Technology** as `Ballerina Integrator`.
46+
11. Choose the **Integration Type** as `File Integration` and Click **Create**.
47+
48+
This redirects you to the overview page of the File Integration. Now, let's develop the File Integration.
49+
50+
## Step 2: Install the Ballerina Integrator extension
51+
52+
1. Click **Install Ballerina Integrator extension** on the overview page. This opens the VS Code extensions page.
53+
2. Click **Install** to install the extension. This installs both **Ballerina Integrator** and **Ballerina** extensions on VS Code.
54+
55+
## Step 3: Set up Ballerina Integrator for the first time
56+
1. Click the Ballerina Integrator icon on the sidebar.
57+
58+
<a href="{{base_path}}/assets/img/get-started/bi-icon.png"><img src="{{base_path}}/assets/img/get-started/bi-icon.png" alt="Ballerina Integrator Icon" width="80%"></a>
59+
60+
2. Click **`Set Up Ballerina Integrator`**. The setup wizard installs and configures the [Ballerina](https://ballerina.io/) distribution required for the Ballerina Integrator.
61+
3. Click **`Restart VS Code`** to complete the setup.
62+
63+
<a href="{{base_path}}/assets/img/get-started/bi-setup.gif"><img src="{{base_path}}/assets/img/get-started/bi-setup.gif" alt="Ballerina Integrator Setup" width="80%"></a>
64+
65+
!!! note
66+
If you already have the integration logic configured or want to immediately push your existing changes to Devant, you can
67+
skip directly to [Step 5: Push to Devant](#step-5-push-to-devant)
68+
69+
- You can find a ready-made file integration example here:
70+
[weather-data-listener](https://github.com/wso2/integration-samples/tree/main/ballerina-integrator/weather-data-listener)
71+
72+
Otherwise, continue with the steps below to build the FTP-based file integration flow from scratch.
73+
74+
## Step 4: Develop File Integration in VS Code
75+
1. Go to the Overview page of the integration you have created and click **Develop in Ballerina Integrator**. This will clone your project and open it in Ballerina Integrator.
76+
2. In the Ballerina Integrator design view, click **Add Artifact**.
77+
3. Select **FTP Service** from the Constructs menu. Choosing the **File Integration** from the Devant console disables the other options.
78+
4. From the left side panel, click **+** on the **Configurations**, and add the following configurables,
79+
80+
| Configurable | Type | Default |
81+
|---------------------|------------|------------------------|
82+
| `ftpUser` | `string` | `"anonymous"` |
83+
| `ftpPassword` | `string` | `""` |
84+
| `ftpHost` | `string` | `"tgftp.nws.noaa.gov"` |
85+
86+
5. Provide the name of the **Listener Configuration** as `WeatherListener`.
87+
88+
6. Then expand the **Advanced Configurations** and enter the following configurables:
89+
90+
| Field | Value |
91+
|-------------------------|----------------------------------------------------------------|
92+
| **Protocol** | `ftp:FTP` |
93+
| **Host** | `ftpHost` |
94+
| **Port** | `21` |
95+
| **Auth** | `{ credentials: { username: ftpUser, password: ftpPassword }}` |
96+
| **Path** | `"/data/observations/metar/decoded/"` |
97+
| **FileNamePattern** | `"(.*).TXT"` |
98+
| **PollingInterval** | `10` |
99+
100+
7. Click **Next**.
101+
8. Then enter the **Service Configuration** name as `WeatherListener` and click on **Create**. It will redirect you to the
102+
**Service Designer** view.
103+
9. Click the `+ Function` button on top right corner in the **Service Designer** view.
104+
10. Select the `onFileChange` as the **Available Function** and click **Save**.
105+
11. Then go to the **Design** view by clicking the Home icon on top left corner of the **Service Designer** view.
106+
12. In the **Design** view, click the `onFileChange` function box. It will redirect you to the flow diagram view.
107+
13. Click the plus icon after the **Start** node to open the node panel.
108+
14. Select **Foreach** and enter the following values in relevant fields:
109+
110+
| Field | Value |
111+
|---------------------|--------------------|
112+
| **Variable Name** | `addedFile` |
113+
| **Variable Type** | `ftp:FileInfo` |
114+
| **Collection** | `event.addedFiles` |
115+
116+
15. Under the **Foreach** node, add a **Declare Variable** node with the following values:
117+
118+
| Field | Value |
119+
|----------------|----------------------------------------|
120+
| **Name** | `fileStream` |
121+
| **Type** | `stream<byte[] & readonly, io:Error?>` |
122+
| **Expression** | `caller->get(addedFile.pathDecoded)` |
123+
124+
16. Add another **Declare Variable** node with:
125+
126+
| Field | Value |
127+
|----------------|-----------------------------------|
128+
| **Name** | `content` |
129+
| **Type** | `record {\|byte[] value;\|}\|()` |
130+
| **Expression** | `check fileStream.next()` |
131+
132+
17. Add an **If** node with the following condition: `content is record {| byte[] value; |}` Also,
133+
click **+ Add Else Block** to define an alternative execution path.
134+
18. The same way, select the **Call Function** from the node panel and search for `fromBytes` and select it.
135+
19. Enter the following values in relevant fields and save it:
136+
137+
| Field | Value |
138+
|---------------------|-----------------|
139+
| **Variable Name** | `fileContent` |
140+
| **Variable Type** | `string` |
141+
| **Bytes** | `content.value` |
142+
143+
20. Next, select **Declare Variable** from the node panel and enter the following values:
144+
145+
| Field | Value |
146+
|----------------|-----------------------------|
147+
| **Name** | `firstLineIndex` |
148+
| **Type** | `int\|()` |
149+
| **Expression** | `fileContent.indexOf("\n")` |
150+
151+
21. Add another **If** node with the condition: `firstLineIndex is int`.
152+
22. Inside the if block (where the condition is `firstLineIndex is int`), add a **Declare Variable** node with
153+
the following properties:
154+
155+
| Field | Value |
156+
|----------------|--------------------------------------------|
157+
| **Name** | `location` |
158+
| **Type** | `string` |
159+
| **Expression** | `fileContent.substring(0, firstLineIndex)` |
160+
161+
23. Add a **Log Info** node below the location variable. Set the **Msg** to: `"Received weather information from: " + location`.
162+
24. In the else block of the first if condition (which checks content is `record {| byte[] value; |}`), add a **Log Error** node. Set the **Msg** to: `"Failed to read weather content"`.
163+
164+
## Step 5: Push to Devant
165+
1. Click the **Source Control** icon on the sidebar.
166+
2. Click **+** to stage all changes.
167+
3. Add an appropriate commit message and commit.
168+
4. Click **Sync Changes** to push the changes to remote.
169+
5. Go back to the **Design** view using the back arrow in the top left corner.
170+
6. From the right side panel, click the **View in Devant** to view this integration in Devant.
171+
172+
## Step 6: Test File Integration
173+
1. Once you push the changes, the overview page of the Devant File Integration will automatically refresh and show you the **Latest Commit** and automatically builds and shows the **Build Status**.
174+
175+
!!! note
176+
The build process may take some time. Once complete, the build status changes to **Success**. You can see the Build History by clicking **Build** in the left navigation.
177+
178+
2. Once the **Build Status** shows `Build completed`, it will be automatically deployed into the development card.
179+
3. Once the deployment is successful, you can view the logs printed by the weather listener in the development card. If no logs are visible, try clicking the refresh button.
180+
4. After successfully testing, you can promote your File Integration to production by clicking the **Promote** button.
181+
5. Once deployed to production, you can access your File Integration through the API endpoints and embed it in your applications.

0 commit comments

Comments
 (0)