Skip to content

Commit a2e9144

Browse files
grongieriscgrongierisc
committed
Add settings documentation and update changelog for remote migration support
1 parent eb3462d commit a2e9144

File tree

4 files changed

+261
-1
lines changed

4 files changed

+261
-1
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [3.5.2] - 2025-08-01
9+
### Added
10+
- Remote migration support, allowing importing Python IOP modules into IRIS through `http`
11+
812
## [3.5.1] - 2025-07-22
913
### Added
1014
- New IOP.Wrapper class for simplified python module import into IRIS with remote debugging support and traceback handling

‎docs/getting-started/register-component.md‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@ This file is used to store the settings of the interoperability components. It h
9494
- `CLASSES`: Stores the classes of the interoperability components.
9595
- `PRODUCTIONS`: Stores the productions of the interoperability components.
9696
- `SCHEMAS`: Stores the schemas of the interoperability components.
97+
- `REMOTE_SETTINGS`: Stores the remote settings for migration.
9798

9899
Example:
99100
```python
@@ -324,4 +325,34 @@ Example:
324325
from msg import RedditPost
325326

326327
SCHEMAS = [RedditPost]
327-
```
328+
```
329+
330+
### The `REMOTE_SETTINGS` Section
331+
332+
This section stores the remote settings for migration. It is used to configure the connection to the remote IRIS instance for importing Python IOP modules.
333+
334+
The dictionary has the following structure:
335+
- `url`: The URL of the remote IRIS instance (mandatory)
336+
- `username`: The username for authentication (optional, default is "")
337+
- `password`: The password for authentication (optional, default is "")
338+
- `namespace`: The namespace for the connection (optional, default is "USER")
339+
- `remote_folder`: The folder where the components are stored (optional, default is the routine database folder)
340+
- `package`: The package name for the components (optional, default is "python")
341+
342+
Example:
343+
```python
344+
from bo import FileOperation
345+
346+
REMOTE_SETTINGS = {
347+
"url": "http://localhost:8080",
348+
"username": "SuperUser",
349+
"password": "SYS",
350+
"namespace": "IRISAPP",
351+
}
352+
353+
CLASSES = {
354+
'Python.FileOperation': FileOperation,
355+
}
356+
```
357+
358+
This will import `FileOperation` from the `bo` module and register it under the key `'Python.FileOperation'` in the `CLASSES` dictionary.

‎docs/settings.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# Settings Configuration
2+
3+
The `settings.py` file is the central configuration file for registering your interoperability components. It defines classes, productions, schemas, and remote connection settings.
4+
5+
## Quick Start
6+
7+
Create a `settings.py` file in your project root:
8+
9+
```python
10+
import bo
11+
12+
CLASSES = {
13+
"Python.MyBusinessOperation": bo.MyBusinessOperation
14+
}
15+
```
16+
17+
Register your components:
18+
```bash
19+
iop --migrate /path/to/your/project/settings.py
20+
```
21+
22+
## Configuration Sections
23+
24+
The `settings.py` file supports four main sections:
25+
26+
| Section | Purpose | Required |
27+
|---------|---------|----------|
28+
| `CLASSES` | Define interoperability components | ✅ |
29+
| `PRODUCTIONS` | Configure production workflows | ❌ |
30+
| `SCHEMAS` | Register message schemas for DTL | ❌ |
31+
| `REMOTE_SETTINGS` | Configure remote IRIS connections | ❌ |
32+
33+
## CLASSES Section
34+
35+
Register your interoperability components (BusinessOperations, BusinessProcesses, BusinessServices).
36+
37+
### Basic Usage
38+
39+
```python
40+
import bo
41+
from bs import RedditService
42+
43+
CLASSES = {
44+
'Python.RedditService': RedditService,
45+
'Python.FileOperation': bo.FileOperation,
46+
}
47+
```
48+
49+
## PRODUCTIONS Section
50+
51+
Define complete production configurations with multiple components.
52+
53+
### Minimal Production
54+
55+
```python
56+
PRODUCTIONS = [
57+
{
58+
'MyApp.Production': {
59+
"@Name": "MyApp.Production",
60+
"Item": [
61+
{
62+
"@Name": "FileProcessor",
63+
"@ClassName": "Python.FileOperation",
64+
},
65+
{
66+
"@Name": "EmailSender",
67+
"@ClassName": "Python.EmailOperation"
68+
}
69+
]
70+
}
71+
}
72+
]
73+
```
74+
75+
### Full Production Configuration
76+
77+
```python
78+
import os
79+
from bo import FileOperation
80+
81+
PRODUCTIONS = [
82+
{
83+
'Demo.Production': {
84+
"@Name": "Demo.Production",
85+
"@TestingEnabled": "true",
86+
"@LogGeneralTraceEvents": "false",
87+
"Description": "Sample production for demonstration",
88+
"ActorPoolSize": "2",
89+
"Item": [
90+
{
91+
"@Name": "FileProcessor",
92+
"@ClassName": "Python.FileOperation",
93+
"@PoolSize": "1",
94+
"@Enabled": "true",
95+
"@LogTraceEvents": "true",
96+
"Setting": {
97+
"@Target": "Host",
98+
"@Name": "%settings",
99+
"#text": f"path={os.environ.get('DATA_PATH', '/tmp')}"
100+
}
101+
}
102+
]
103+
}
104+
}
105+
]
106+
```
107+
108+
**Production Attributes:**
109+
- `@Name`: Production display name
110+
- `@TestingEnabled`: Enable testing mode (`"true"`/`"false"`)
111+
- `@LogGeneralTraceEvents`: Enable general logging
112+
- `ActorPoolSize`: Number of concurrent actors
113+
114+
**Item Attributes:**
115+
- `@Name`: Component instance name
116+
- `@ClassName`: Class reference (from CLASSES or direct class)
117+
- `@PoolSize`: Component pool size
118+
- `@Enabled`: Enable/disable component
119+
- `@LogTraceEvents`: Enable component-specific logging
120+
- `Setting`: Component configuration settings
121+
122+
## SCHEMAS Section
123+
124+
Register message schemas for Data Transformation Language (DTL) operations.
125+
126+
```python
127+
from msg import RedditPost, UserProfile
128+
129+
SCHEMAS = [RedditPost, UserProfile]
130+
```
131+
132+
## REMOTE_SETTINGS Section
133+
134+
Configure connections to remote IRIS instances for component migration.
135+
136+
```python
137+
REMOTE_SETTINGS = {
138+
"url": "http://localhost:8080", # Required
139+
"username": "SuperUser", # Optional
140+
"password": "SYS", # Optional
141+
"namespace": "IRISAPP", # Optional (default: "USER")
142+
"remote_folder": "", # Optional (default: folder of the routine database)
143+
"package": "python" # Optional (default: "python")
144+
}
145+
```
146+
147+
**Configuration Options:**
148+
- `url`: Remote IRIS instance URL (required)
149+
- `username`: Authentication username
150+
- `password`: Authentication password
151+
- `namespace`: Target namespace for components
152+
- `remote_folder`: Remote storage folder
153+
- `package`: Package name for components
154+
155+
## Complete Example
156+
157+
```python
158+
import os
159+
import bp
160+
from bo import FileOperation, EmailOperation
161+
from bs import RedditService
162+
from msg import RedditPost
163+
164+
# Remote connection settings
165+
REMOTE_SETTINGS = {
166+
"url": "http://iris-server:8080",
167+
"username": "SuperUser",
168+
"password": "SYS",
169+
"namespace": "IRISAPP"
170+
}
171+
172+
# Component registration
173+
CLASSES = {
174+
'Python.RedditService': RedditService,
175+
'Python.FileOperation': FileOperation,
176+
'Python.EmailOperation': EmailOperation,
177+
'Python.FilterRule': bp.FilterPostRoutingRule,
178+
}
179+
180+
# Message schemas
181+
SCHEMAS = [RedditPost]
182+
183+
# Production configuration
184+
PRODUCTIONS = [
185+
{
186+
'Reddit.Production': {
187+
"@Name": "Reddit Processing Pipeline",
188+
"@TestingEnabled": "true",
189+
"ActorPoolSize": "3",
190+
"Item": [
191+
{
192+
"@Name": "RedditFeed",
193+
"@ClassName": "Python.RedditService",
194+
"@Enabled": "true",
195+
"Setting": {
196+
"@Target": "Host",
197+
"@Name": "%settings",
198+
"#text": f"limit={os.environ.get('REDDIT_LIMIT', '10')}"
199+
}
200+
},
201+
{
202+
"@Name": "PostFilter",
203+
"@ClassName": "Python.FilterRule",
204+
"@Enabled": "true"
205+
},
206+
{
207+
"@Name": "FileExporter",
208+
"@ClassName": "Python.FileOperation",
209+
"@Enabled": "true"
210+
}
211+
]
212+
}
213+
}
214+
]
215+
```
216+
217+
## Best Practices
218+
219+
1. **Use descriptive names** for components and productions
220+
2. **Import modules at the top** of your settings file
221+
3. **Use environment variables** for sensitive data and paths
222+
4. **Group related components** in the same production
223+
5. **Enable logging** during development and testing
224+
6. **Document complex productions** with clear descriptions

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ nav:
1919
- Production Settings: prod-settings.md
2020
- Venv Support: venv.md
2121
- Wrapper Support: wrapper.md
22+
- Settings: settings.md
2223
- Contributing:
2324
- Contributing: contributing.md
2425
- Code of Conduct: code-of-conduct.md

0 commit comments

Comments
 (0)