Skip to content

Commit bc44050

Browse files
author
Sean Rowe
committed
Add OIE Plugin Guide documentation
Closes OpenIntegrationEngine/engine#238 - Add plugin installation guide - Cover UI and manual install methods - Include Docker container install options - Link to plugin development resources
1 parent 2bb4576 commit bc44050

File tree

2 files changed

+245
-0
lines changed

2 files changed

+245
-0
lines changed

‎.vitepress/config.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ export default defineConfig({
4444
collapsed: false,
4545
items: [
4646
{ text: 'Overview', link: 'engine' },
47+
{ text: 'Plugin Guide', link: 'engine/plugins' },
4748
{ text: 'Contributing', link: 'engine/contributing' },
4849
]
4950
},

‎docs/engine/plugins.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# OIE Plugin Guide
2+
3+
Plugins extend the functionality of Open Integration Engine (OIE), allowing you to add custom features, connectors, and capabilities. This guide covers everything you need to know about installing, managing, and troubleshooting plugins. Resources are provided for developing custom plugins.
4+
5+
## Overview
6+
7+
Open Integration Engine supports a plugin architecture that enables:
8+
9+
- Custom connectors and protocols
10+
- Extended transformers and filters
11+
- Additional data types and formats
12+
- Custom UI components in the Administrator
13+
14+
## Accessing the Extensions/Plugins Section
15+
16+
To manage plugins in Open Integration Engine:
17+
18+
1. Open the **OIE Administrator** application
19+
2. Navigate to **Settings** from the main menu
20+
3. Select **Extensions** from the left sidebar
21+
4. You will see a list of all installed plugins along with their status and other details.
22+
23+
## Installing Plugins
24+
25+
### Installing via the Administrator UI
26+
27+
The easiest way to install a plugin is through the Administrator interface:
28+
29+
1. Download the plugin `.zip` file from a trusted source
30+
2. Open the **OIE Administrator** and navigate to **Settings** → **Extensions**
31+
3. Click the **Install Extension** button
32+
4. Browse to and select the plugin `.zip` file
33+
5. Click **Open** to begin the installation
34+
6. Review the plugin information and click **Install**
35+
7. **Restart** the OIE Server for the plugin to take effect
36+
37+
::: info
38+
Always restart the OIE Server after installing or uninstalling plugins to ensure changes take effect.
39+
:::
40+
41+
### Manual Installation
42+
43+
For environments where UI-based installation is not feasible, you can install plugins manually:
44+
45+
1. Stop the OIE Server
46+
2. Extract the plugin `.zip` file
47+
3. Copy the extracted plugin folder to the `extensions/` directory in your OIE installation:
48+
::: code-group
49+
```bash [Linux/macOS]
50+
cp -r my-plugin /opt/oie/extensions/
51+
```
52+
```powershell [Windows]
53+
Copy-Item -Recurse my-plugin "C:\Program Files\OIE\extensions\"
54+
```
55+
:::
56+
4. **(Linux/macOS only)** Ensure proper file permissions so the OIE process can read the plugin files. The plugin files should be owned by the same user that runs OIE:
57+
::: code-group
58+
```bash [Linux/macOS]
59+
# Replace 'oie' with the user account that runs the OIE Server
60+
chown -R oie:oie /opt/oie/extensions/my-plugin
61+
```
62+
:::
63+
::: tip
64+
OIE does not create a dedicated system user during installation. It runs as the user who starts the service. Check which user owns your OIE installation directory or runs the OIE process.
65+
:::
66+
5. Start the OIE Server
67+
68+
### Installing in the OIE Docker Container
69+
70+
When running OIE in a Docker container, you have several options for installing plugins:
71+
72+
#### Option 1: Volume Mount (Recommended)
73+
74+
Mount a host directory containing plugins to the container's extensions directory:
75+
76+
```bash
77+
docker run -d \
78+
-v /path/to/local/extensions:/opt/oie/extensions \
79+
openintegrationengine/engine:latest
80+
```
81+
82+
#### Option 2: Custom Dockerfile
83+
84+
Create a custom Docker image with plugins pre-installed:
85+
86+
```dockerfile
87+
FROM openintegrationengine/engine:latest
88+
89+
COPY my-plugin.zip /tmp/
90+
RUN unzip /tmp/my-plugin.zip -d /opt/oie/extensions/ && \
91+
rm /tmp/my-plugin.zip
92+
```
93+
94+
Build and run:
95+
96+
```bash
97+
docker build -t oie-with-plugins .
98+
docker run -d oie-with-plugins
99+
```
100+
101+
#### Option 3: Docker Compose
102+
103+
Using Docker Compose with volume mounts:
104+
105+
```yaml
106+
version: '3.8'
107+
services:
108+
oie:
109+
image: openintegrationengine/engine:latest
110+
volumes:
111+
- ./extensions:/opt/oie/extensions
112+
ports:
113+
- "8080:8080"
114+
- "8443:8443"
115+
```
116+
117+
## Uninstalling Plugins
118+
119+
### Via the Administrator UI
120+
121+
1. Navigate to **Settings** → **Extensions**
122+
2. Locate the plugin you want to remove
123+
3. Click the **Uninstall** button next to the plugin
124+
4. Confirm the uninstallation when prompted
125+
5. **Restart** the OIE Server
126+
127+
### Manual Uninstallation
128+
129+
1. Stop the OIE Server
130+
2. Navigate to the `extensions/` directory
131+
3. Remove the plugin folder:
132+
::: code-group
133+
```bash [Linux/macOS]
134+
rm -rf /opt/oie/extensions/my-plugin
135+
```
136+
```powershell [Windows]
137+
Remove-Item -Recurse -Force "C:\Program Files\OIE\extensions\my-plugin"
138+
```
139+
:::
140+
4. Start the OIE Server
141+
142+
## Enabling and Disabling Plugins
143+
144+
You can temporarily disable plugins without uninstalling them:
145+
146+
### To Disable a Plugin
147+
148+
1. Navigate to **Settings** → **Extensions**
149+
2. Find the plugin in the list
150+
3. Toggle the **Enabled** switch to **Off**
151+
4. **Restart** the OIE Server
152+
153+
### To Enable a Plugin
154+
155+
1. Navigate to **Settings** → **Extensions**
156+
2. Find the disabled plugin in the list
157+
3. Toggle the **Enabled** switch to **On**
158+
4. **Restart** the OIE Server
159+
160+
::: tip
161+
Disabling plugins is useful for troubleshooting. If you suspect a plugin is causing issues, disable it and restart the server to confirm.
162+
:::
163+
164+
## Plugin Compatibility and Version Requirements
165+
166+
### Checking Compatibility
167+
168+
Before installing a plugin, verify:
169+
170+
1. **OIE Version**: Check the plugin documentation for supported OIE versions
171+
2. **Java Version**: Some plugins may require specific Java versions
172+
3. **Dependencies**: Review any additional dependencies the plugin requires
173+
174+
::: info
175+
Plugin authors must specify compatible versions in their plugin. Currently, plugins cannot support a range of versions.
176+
:::
177+
178+
## Troubleshooting Common Issues
179+
180+
### Plugin Not Appearing After Installation
181+
182+
**Possible causes and solutions:**
183+
184+
1. **Server not restarted**: Restart the OIE Server after installation
185+
2. **Incorrect directory**: Verify the plugin is in the correct `extensions/` folder
186+
3. **File permissions**: Ensure the OIE process has read access to the plugin files
187+
4. **Corrupted archive**: Re-download and reinstall the plugin
188+
189+
### Plugin Causing Server Startup Failures
190+
191+
If the server fails to start after installing a plugin:
192+
193+
1. Check the server logs in `logs/oie-server.log` for error messages
194+
2. Try starting the server with the plugin disabled:
195+
::: code-group
196+
```bash [Linux/macOS]
197+
# Temporarily move the plugin out of extensions
198+
mv /opt/oie/extensions/problem-plugin /tmp/
199+
```
200+
```powershell [Windows]
201+
# Temporarily move the plugin out of extensions
202+
Move-Item "C:\Program Files\OIE\extensions\problem-plugin" "C:\Temp\"
203+
```
204+
:::
205+
3. If the server starts successfully, the plugin is likely incompatible
206+
207+
### Plugin Features Not Working
208+
209+
1. Verify the plugin is **enabled** in Settings → Extensions
210+
2. Check for JavaScript console errors in the Administrator
211+
3. Review server logs for runtime errors
212+
4. Ensure all plugin dependencies are installed
213+
214+
### Common Error Messages
215+
216+
| Error | Cause | Solution |
217+
|-------|-------|----------|
218+
| `ClassNotFoundException` | Missing dependency | Install required dependencies |
219+
| `NoSuchMethodError` | Version mismatch | Use compatible plugin version |
220+
| `SecurityException` | Permission denied | Check file permissions |
221+
222+
## Plugin Development Resources
223+
224+
For those interested in developing plugins for Open Integration Engine:
225+
226+
### Key Resources
227+
228+
- **Plugin Author's Guide**: [mirth-plugin-guide](https://github.com/kpalang/mirth-plugin-guide) - Comprehensive guide for plugin development on OIE, Mirth Connect (Open Source Versions) and BridgeLink.
229+
- **Sample Plugin**: [mirth-sample-plugin](https://github.com/kpalang/mirth-sample-plugin) - A working example plugin to use as a template for OIE, Mirth Connect (Open Source Versions) and BridgeLink.
230+
231+
## Best Practices
232+
233+
1. **Always backup** your OIE configuration before installing new plugins
234+
2. **Test in non-production** environments first
235+
3. **Keep plugins updated** to receive bug fixes and security patches
236+
4. **Review plugin source code** when possible, especially for plugins handling sensitive data
237+
5. **Document installed plugins** for your team and disaster recovery procedures
238+
6. **Monitor server logs** after installing new plugins for any issues
239+
240+
## See Also
241+
242+
- [Contributing to Open Integration Engine](./contributing.md)
243+
- [OIE Docker Hub](https://hub.docker.com/u/openintegrationengine)
244+
- [OIE GitHub Repository](https://github.com/OpenIntegrationEngine/engine)

0 commit comments

Comments
 (0)