Skip to content

Commit 7799587

Browse files
ziaghamziagham
committed
Update README
#12
1 parent 1dbc80f commit 7799587

2 files changed

Lines changed: 256 additions & 40 deletions

File tree

‎README.md‎

Lines changed: 128 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,150 @@
1-
# Amazon S3 Plugin – FlowSynx Platform Integration
1+
# FlowSynx Amazon S3 Plugin
22

3-
The **Amazon S3 Plugin** is a pre-packaged, plug-and-play integration component for the FlowSynx engine. It enables secure and configurable access to Amazon S3 cloud storage as part of FlowSynx’s no-code/low-code automation workflows.
3+
The Amazon S3 Plugin is a pre-packaged, plug-and-play integration component for the FlowSynx engine. It enables interacting with Amazon S3 buckets, allowing workflows to read, write, list, and manage S3 objects securely. Designed for FlowSynx’s no-code/low-code automation workflows, this plugin simplifies cloud storage integration for data pipelines and automation tasks.
44

5-
This plugin can be installed automatically by the FlowSynx engine when selected within the platform. It is not intended for manual installation or developer use outside the FlowSynx environment.
5+
This plugin is automatically installed by the FlowSynx engine when selected within the platform. It is not intended for manual installation or standalone developer use outside the FlowSynx environment.
66

77
---
88

99
## Purpose
1010

11-
This plugin allows FlowSynx users to interact with Amazon S3 for a variety of storage-related operations—without writing code. Once installed, the plugin becomes available as a storage connector within the platform's workflow builder.
11+
The Amazon S3 Plugin allows FlowSynx users to:
12+
13+
- Upload data to Amazon S3 buckets.
14+
- Download or read data from S3 objects.
15+
- List, delete, or check the existence of S3 objects.
16+
- Purge S3 buckets when needed.
17+
- Integrate Amazon S3 operations into automation workflows without writing code.
1218

1319
---
1420

1521
## Supported Operations
1622

17-
The plugin supports the following operations, which can be selected and configured within the FlowSynx UI:
23+
- **create**: Creates a new object in the specified bucket and path.
24+
- **delete**: Deletes an object at the specified path in the bucket.
25+
- **exist**: Checks if an object exists at the specified path.
26+
- **list**: Lists objects under a specified path (prefix), with filtering and optional metadata.
27+
- **purge**: Deletes all objects under the specified path, optionally forcing deletion.
28+
- **read**: Reads and returns the contents of an object at the specified path.
29+
- **write**: Writes data to a specified path in the bucket, with support for overwrite.
30+
31+
---
32+
33+
## Plugin Specifications
34+
35+
The plugin requires the following configuration:
36+
37+
- `AccessKey` (string): **Required.** The AWS Access Key ID for authentication.
38+
- `SecretKey` (string): **Required.** The AWS Secret Access Key for authentication.
39+
- `Region` (string): **Required.** The AWS region of the S3 bucket (e.g., `us-east-1`).
40+
- `Bucket` (string): **Required.** The name of the target S3 bucket.
41+
- `SessionToken` (string): Optional. The AWS session token if using temporary credentials.
42+
43+
### Example Configuration
44+
45+
```json
46+
{
47+
"AccessKey": "AKIAEXAMPLE123456",
48+
"SecretKey": "abc123secretkeyexample",
49+
"Region": "us-east-1",
50+
"Bucket": "my-flowsynx-bucket",
51+
"SessionToken": "FQoGZXIvYXdzEJr..."
52+
}
53+
```
54+
55+
---
56+
57+
## Input Parameters
58+
59+
Each operation accepts specific parameters:
60+
61+
### Create
62+
| Parameter | Type | Required | Description |
63+
|---------------|---------|----------|------------------------------------------|
64+
| `Path` | string | Yes | The path where the new object is created.|
65+
66+
### Delete
67+
| Parameter | Type | Required | Description |
68+
|---------------|---------|----------|------------------------------------------|
69+
| `Path` | string | Yes | The path of the object to delete. |
70+
71+
### Exist
72+
| Parameter | Type | Required | Description |
73+
|---------------|---------|----------|------------------------------------------|
74+
| `Path` | string | Yes | The path of the object to check. |
75+
76+
### List
77+
| Parameter | Type | Required | Description |
78+
|--------------------|---------|----------|-----------------------------------------------------|
79+
| `Path` | string | Yes | The prefix path to list objects from. |
80+
| `Filter` | string | No | A filter pattern for object names. |
81+
| `Recurse` | bool | No | Whether to list recursively. Default: `false`. |
82+
| `CaseSensitive` | bool | No | Whether the filter is case-sensitive. Default: `false`. |
83+
| `IncludeMetadata` | bool | No | Whether to include object metadata. Default: `false`. |
84+
| `MaxResults` | int | No | Maximum number of objects to list. Default: `2147483647`. |
85+
86+
### Purge
87+
| Parameter | Type | Required | Description |
88+
|---------------|---------|----------|------------------------------------------------|
89+
| `Path` | string | Yes | The path prefix to purge. |
90+
| `Force` | bool | No | Whether to force deletion without confirmation.|
91+
92+
### Read
93+
| Parameter | Type | Required | Description |
94+
|---------------|---------|----------|------------------------------------------|
95+
| `Path` | string | Yes | The path of the object to read. |
96+
97+
### Write
98+
| Parameter | Type | Required | Description |
99+
|---------------|---------|----------|--------------------------------------------------------------|
100+
| `Path` | string | Yes | The path where data should be written. |
101+
| `Data` | object | Yes | The data to write to the S3 object. |
102+
| `Overwrite` | bool | No | Whether to overwrite if the object already exists. Default: `false`. |
103+
104+
### Example input (Write)
105+
106+
```json
107+
{
108+
"Operation": "write",
109+
"Path": "documents/report.json",
110+
"Data": {
111+
"title": "Monthly Report",
112+
"content": "This is the report content."
113+
},
114+
"Overwrite": true
115+
}
116+
```
117+
118+
---
119+
120+
## Debugging Tips
121+
122+
- Ensure `AccessKey`, `SecretKey`, and `Region` are correct and the credentials have appropriate S3 permissions.
123+
- Verify the `Bucket` exists and is accessible from the FlowSynx environment.
124+
- Use the `Exist` operation to confirm object presence before performing `Read` or `Delete`.
125+
- For large listings, adjust `MaxResults` to limit returned data.
126+
- When using temporary credentials, ensure `SessionToken` is valid and not expired.
127+
128+
---
129+
130+
## Amazon S3 Considerations
18131

19-
| Operation | Description |
20-
|----------|--------------------------------------|
21-
| `create` | Upload a new object to the S3 bucket. |
22-
| `delete` | Remove an object from the bucket. |
23-
| `exist` | Check if an object exists. |
24-
| `list` | List all objects in the bucket. |
25-
| `purge` | Remove all contents in the bucket. |
26-
| `read` | Read and return the contents of an object. |
27-
| `write` | Overwrite or write new data to an object. |
132+
- **Object Key Case Sensitivity**: S3 object keys are case-sensitive. Ensure correct casing when specifying paths.
133+
- **Eventual Consistency**: Deletions and listings may have a short delay due to eventual consistency.
134+
- **Overwrite Behavior**: The `Write` operation will fail if `Overwrite` is `false` and the object exists.
135+
- **Region Specificity**: Buckets exist within regions. Cross-region operations are not supported by this plugin.
136+
- **Large Objects**: For objects over 5 GB, consider using multipart upload (not supported directly in this plugin).
28137

29138
---
30139

31-
## Notes
140+
## Security Notes
32141

33-
- This plugin is only supported on the FlowSynx platform.
34-
- It is installed automatically by the FlowSynx engine.
35-
- All operational logic is encapsulated and executed under FlowSynx control.
36-
- Credentials are configured through platform-managed settings.
142+
- AWS credentials are used only during plugin execution and are not persisted by FlowSynx.
143+
- Access is controlled by FlowSynx platform user roles and permissions.
144+
- Always use IAM users with least privilege to limit S3 access to only required buckets and actions.
37145

38146
---
39147

40148
## License
41149

42-
© FlowSynx. All rights reserved.
150+
© FlowSynx. All rights reserved.

‎src/README.md‎

Lines changed: 128 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,150 @@
1-
# Amazon S3 Plugin – FlowSynx Platform Integration
1+
# FlowSynx Amazon S3 Plugin
22

3-
The **Amazon S3 Plugin** is a pre-packaged, plug-and-play integration component for the FlowSynx engine. It enables secure and configurable access to Amazon S3 cloud storage as part of FlowSynx’s no-code/low-code automation workflows.
3+
The Amazon S3 Plugin is a pre-packaged, plug-and-play integration component for the FlowSynx engine. It enables interacting with Amazon S3 buckets, allowing workflows to read, write, list, and manage S3 objects securely. Designed for FlowSynx’s no-code/low-code automation workflows, this plugin simplifies cloud storage integration for data pipelines and automation tasks.
44

5-
This plugin can be installed automatically by the FlowSynx engine when selected within the platform. It is not intended for manual installation or developer use outside the FlowSynx environment.
5+
This plugin is automatically installed by the FlowSynx engine when selected within the platform. It is not intended for manual installation or standalone developer use outside the FlowSynx environment.
66

77
---
88

99
## Purpose
1010

11-
This plugin allows FlowSynx users to interact with Amazon S3 for a variety of storage-related operations—without writing code. Once installed, the plugin becomes available as a storage connector within the platform's workflow builder.
11+
The Amazon S3 Plugin allows FlowSynx users to:
12+
13+
- Upload data to Amazon S3 buckets.
14+
- Download or read data from S3 objects.
15+
- List, delete, or check the existence of S3 objects.
16+
- Purge S3 buckets when needed.
17+
- Integrate Amazon S3 operations into automation workflows without writing code.
1218

1319
---
1420

1521
## Supported Operations
1622

17-
The plugin supports the following operations, which can be selected and configured within the FlowSynx UI:
23+
- **create**: Creates a new object in the specified bucket and path.
24+
- **delete**: Deletes an object at the specified path in the bucket.
25+
- **exist**: Checks if an object exists at the specified path.
26+
- **list**: Lists objects under a specified path (prefix), with filtering and optional metadata.
27+
- **purge**: Deletes all objects under the specified path, optionally forcing deletion.
28+
- **read**: Reads and returns the contents of an object at the specified path.
29+
- **write**: Writes data to a specified path in the bucket, with support for overwrite.
30+
31+
---
32+
33+
## Plugin Specifications
34+
35+
The plugin requires the following configuration:
36+
37+
- `AccessKey` (string): **Required.** The AWS Access Key ID for authentication.
38+
- `SecretKey` (string): **Required.** The AWS Secret Access Key for authentication.
39+
- `Region` (string): **Required.** The AWS region of the S3 bucket (e.g., `us-east-1`).
40+
- `Bucket` (string): **Required.** The name of the target S3 bucket.
41+
- `SessionToken` (string): Optional. The AWS session token if using temporary credentials.
42+
43+
### Example Configuration
44+
45+
```json
46+
{
47+
"AccessKey": "AKIAEXAMPLE123456",
48+
"SecretKey": "abc123secretkeyexample",
49+
"Region": "us-east-1",
50+
"Bucket": "my-flowsynx-bucket",
51+
"SessionToken": "FQoGZXIvYXdzEJr..."
52+
}
53+
```
54+
55+
---
56+
57+
## Input Parameters
58+
59+
Each operation accepts specific parameters:
60+
61+
### Create
62+
| Parameter | Type | Required | Description |
63+
|---------------|---------|----------|------------------------------------------|
64+
| `Path` | string | Yes | The path where the new object is created.|
65+
66+
### Delete
67+
| Parameter | Type | Required | Description |
68+
|---------------|---------|----------|------------------------------------------|
69+
| `Path` | string | Yes | The path of the object to delete. |
70+
71+
### Exist
72+
| Parameter | Type | Required | Description |
73+
|---------------|---------|----------|------------------------------------------|
74+
| `Path` | string | Yes | The path of the object to check. |
75+
76+
### List
77+
| Parameter | Type | Required | Description |
78+
|--------------------|---------|----------|-----------------------------------------------------|
79+
| `Path` | string | Yes | The prefix path to list objects from. |
80+
| `Filter` | string | No | A filter pattern for object names. |
81+
| `Recurse` | bool | No | Whether to list recursively. Default: `false`. |
82+
| `CaseSensitive` | bool | No | Whether the filter is case-sensitive. Default: `false`. |
83+
| `IncludeMetadata` | bool | No | Whether to include object metadata. Default: `false`. |
84+
| `MaxResults` | int | No | Maximum number of objects to list. Default: `2147483647`. |
85+
86+
### Purge
87+
| Parameter | Type | Required | Description |
88+
|---------------|---------|----------|------------------------------------------------|
89+
| `Path` | string | Yes | The path prefix to purge. |
90+
| `Force` | bool | No | Whether to force deletion without confirmation.|
91+
92+
### Read
93+
| Parameter | Type | Required | Description |
94+
|---------------|---------|----------|------------------------------------------|
95+
| `Path` | string | Yes | The path of the object to read. |
96+
97+
### Write
98+
| Parameter | Type | Required | Description |
99+
|---------------|---------|----------|--------------------------------------------------------------|
100+
| `Path` | string | Yes | The path where data should be written. |
101+
| `Data` | object | Yes | The data to write to the S3 object. |
102+
| `Overwrite` | bool | No | Whether to overwrite if the object already exists. Default: `false`. |
103+
104+
### Example input (Write)
105+
106+
```json
107+
{
108+
"Operation": "write",
109+
"Path": "documents/report.json",
110+
"Data": {
111+
"title": "Monthly Report",
112+
"content": "This is the report content."
113+
},
114+
"Overwrite": true
115+
}
116+
```
117+
118+
---
119+
120+
## Debugging Tips
121+
122+
- Ensure `AccessKey`, `SecretKey`, and `Region` are correct and the credentials have appropriate S3 permissions.
123+
- Verify the `Bucket` exists and is accessible from the FlowSynx environment.
124+
- Use the `Exist` operation to confirm object presence before performing `Read` or `Delete`.
125+
- For large listings, adjust `MaxResults` to limit returned data.
126+
- When using temporary credentials, ensure `SessionToken` is valid and not expired.
127+
128+
---
129+
130+
## Amazon S3 Considerations
18131

19-
| Operation | Description |
20-
|----------|--------------------------------------|
21-
| `create` | Upload a new object to the S3 bucket. |
22-
| `delete` | Remove an object from the bucket. |
23-
| `exist` | Check if an object exists. |
24-
| `list` | List all objects in the bucket. |
25-
| `purge` | Remove all contents in the bucket. |
26-
| `read` | Read and return the contents of an object. |
27-
| `write` | Overwrite or write new data to an object. |
132+
- **Object Key Case Sensitivity**: S3 object keys are case-sensitive. Ensure correct casing when specifying paths.
133+
- **Eventual Consistency**: Deletions and listings may have a short delay due to eventual consistency.
134+
- **Overwrite Behavior**: The `Write` operation will fail if `Overwrite` is `false` and the object exists.
135+
- **Region Specificity**: Buckets exist within regions. Cross-region operations are not supported by this plugin.
136+
- **Large Objects**: For objects over 5 GB, consider using multipart upload (not supported directly in this plugin).
28137

29138
---
30139

31-
## Notes
140+
## Security Notes
32141

33-
- This plugin is only supported on the FlowSynx platform.
34-
- It is installed automatically by the FlowSynx engine.
35-
- All operational logic is encapsulated and executed under FlowSynx control.
36-
- Credentials are configured through platform-managed settings.
142+
- AWS credentials are used only during plugin execution and are not persisted by FlowSynx.
143+
- Access is controlled by FlowSynx platform user roles and permissions.
144+
- Always use IAM users with least privilege to limit S3 access to only required buckets and actions.
37145

38146
---
39147

40148
## License
41149

42-
© FlowSynx. All rights reserved.
150+
© FlowSynx. All rights reserved.

0 commit comments

Comments
 (0)