You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: apps/about-apps/components/portal-extension.md
+299-8Lines changed: 299 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,16 +8,307 @@ sidebar_position: 6
8
8
9
9
<palign="center">Enhance epilot portals with custom functionality and integrations</p>
10
10
11
-
## 🚧 Documentation Coming Soon
11
+
## Configuration
12
12
13
-
We're currently developing comprehensive documentation for Portal Extensions. This section will include detailed guides on creating Links and Hooks components for both customer and installer portals.
13
+
All development is performed using the built-in configuration editor accessible from the component editor.
14
14
15
-
### Future Content
15
+
The editor provides you with autocomplete and validation of the configuration. That way you can start with the example provided in this documentation and fine-tune your portal extension without ever leaving the editor.
-**Use Cases**: Learn how Portal Extensions can solve real business needs
20
-
-**Links**: Add custom navigation and external integrations
21
-
-**Hooks**: Create responsive components that enhance the portal experience
19
+
## Links
22
20
23
-
Please check back soon, or [contact our developer support team](https://developers.epilot.cloud/contact) for early access information.
21
+
The easiest way to extend the functionality of portals is to link to a third party system.
22
+
This is possible using the "seamless link" concept.
23
+
24
+
### What are Seamless Links?
25
+
26
+
Seamless links enable portal users to access third-party systems directly without manual authentication. When a user clicks a seamless link in the portal, epilot handles the authentication process in the background according to your configured rules, then redirects the user to the specified page in the third-party system with the necessary credentials or tokens.
27
+
28
+
This provides a smooth user experience where portal users can navigate to external systems without interruption, while you maintain control over the authentication mechanism and security policies.
29
+
30
+
### How Seamless Links Work
31
+
32
+
The seamless link flow consists of two main steps:
33
+
34
+
1.**Authentication**: epilot makes a request to your authentication endpoint using the configured credentials and headers
35
+
2.**Redirect**: epilot uses the authentication response to construct a redirect URL with the necessary parameters (such as tokens) and sends the user to the target page
36
+
37
+
All of this happens automatically in the background, so the portal user experiences a seamless transition to the third-party system.
38
+
39
+
### Configuration and Example
40
+
41
+
Seamless links are configured in your app configuration. Each seamless link defines the authentication mechanism and the redirect behavior. The built-in component configuration editor will guide you through the available properties and their format. Here is an example hook configuration:
42
+
43
+
```json
44
+
{
45
+
"id": "third_party_seamless_link",
46
+
"type": "seamless",
47
+
"name": {
48
+
"en": "Dashboard",
49
+
"de": "Dashboard"
50
+
},
51
+
"description": {
52
+
"en": "Adds Third Party System as a Type for \"Seamless link\". Once configured, the system can be opened from Portal without a need to authenticate.",
53
+
"de": "Fügt Third Party System als Typ für \"Seamless Link\" hinzu. Sobald konfiguriert, kann das System von Portal aus geöffnet werden, ohne sich authentifizieren zu müssen."
54
+
},
55
+
"auth": {
56
+
"type": "token",
57
+
"url": "{{Options.api_url}}/token",
58
+
"method": "GET",
59
+
"headers": {
60
+
"API-Key": "{{Options.api_key}}",
61
+
"UID": "{{Contact.customer_number}}"
62
+
}
63
+
},
64
+
"redirect": {
65
+
"url": "{{Options.ui_url}}/dashboard",
66
+
"params": {
67
+
"token": "{{AuthResponse.data.data.token}}",
68
+
"contractId": "{{Contract.contract_number}}"
69
+
}
70
+
}
71
+
}
72
+
```
73
+
74
+
The configuration above adds a new option for quick actions like this:
75
+
76
+
77
+
78
+
### Template Variables
79
+
80
+
You can use template variables throughout your seamless link configuration to dynamically inject values from various sources. Template variables use the `{{Variable.path}}` syntax.
81
+
82
+
#### Available Variables
83
+
84
+
-**`Options.*`**: Access values from the app options configured during installation
1.**Billing Dashboard**: Redirect portal users to a third-party billing system to check details of their last bill
101
+
2.**Document Management**: Provide direct access to a document repository
102
+
3.**Service Portal**: Integrate with external service management systems
103
+
104
+
### Security Considerations
105
+
106
+
-**Credentials Storage**: Store sensitive credentials (like API keys) as app options rather than hardcoding them
107
+
-**Token Expiration**: Ensure your authentication tokens have appropriate expiration times
108
+
-**HTTPS**: Always use HTTPS URLs for authentication endpoints and redirects
109
+
-**Access Control**: Implement proper authorization checks on your authentication endpoint to ensure only authorized portal users can obtain tokens
110
+
111
+
## Hooks
112
+
113
+
Hooks allow changing or adding functionality to portals.
114
+
They typically rely on your API for the execution of any necessary logic and expect a certain response.
115
+
116
+
There are currently three groups of hooks supported based on their use:
117
+
118
+
- Time Series Data Retrieval
119
+
- Data Existence Check/Retrieval
120
+
- Data Validation
121
+
122
+
### Time Series Data Retrieval Hooks
123
+
124
+
Data retrieval hooks enable portals to fetch and display time-series data from third-party systems. These hooks are used to power data visualizations and charts in the portal interface, allowing portal users to view real-time or historical data from integrated systems.
125
+
126
+
#### Types of Data Retrieval Hooks
127
+
128
+
Portals support three types of data retrieval hooks:
129
+
130
+
1.**Price Data Retrieval** (`priceDataRetrieval`): Fetches price information over time
131
+
2.**Consumption Data Retrieval** (`consumptionDataRetrieval`): Retrieves consumption or usage data
132
+
3.**Cost Data Retrieval** (`costDataRetrieval`): Fetches cost or billing data
133
+
134
+
#### How Data Retrieval Hooks Work
135
+
136
+
Data retrieval hooks follow a three-step process:
137
+
138
+
1.**Authentication**: epilot authenticates with your third-party system to obtain a token or credentials
139
+
2.**Data Retrieval**: Using the authentication token, epilot makes a request to your data API with the requested time range and interval
140
+
3.**Data Resolution**: The response is processed and extracted using the configured data path, then displayed in the portal
141
+
142
+
The authentication step supports caching to reduce API calls and improve performance. The data retrieval supports configurable time intervals (e.g., hourly, daily) and automatically handles time range queries based on the portal user's selected view.
143
+
144
+
#### Configuration and Example
145
+
146
+
Data retrieval hooks are configured in your app configuration. Each hook defines the authentication mechanism, the data retrieval endpoint, and how to process the response.
147
+
148
+
Below are examples for all three data retrieval hook types.
149
+
All of these enable configuring users to add a Dynamic Tariff block where your integration is pickable using the "Integration" dropdown.
150
+
151
+
Data retrieval hooks support the same template variables as any other hook, plus additional scope variables:
276
+
277
+
#### Standard Variables
278
+
279
+
-**`Options.*`**: Access values from the app options configured during installation
280
+
-**`Contact.*`**: Access properties from the current portal user's contact entity
281
+
-**`AuthResponse.*`**: Access data from the authentication response
282
+
-**`Entity.*`**: Access data from the context entities like `Contract`.
283
+
284
+
#### Scope Variables (for `call.params`)
285
+
286
+
These variables are automatically provided by epilot based on the portal user's selected time range and interval:
287
+
288
+
-**`Scope.from`**: Start timestamp of the requested time range (ISO 8601 format)
289
+
-**`Scope.to`**: End timestamp of the requested time range (ISO 8601 format)
290
+
-**`Scope.interval`**: Selected time interval (ISO 8601 duration format, e.g., `"PT1H"` for hourly)
291
+
292
+
293
+
#### Best Practices
294
+
295
+
-**Caching**: Use authentication token caching to reduce API load and improve response times
296
+
-**Interval Support**: Support multiple intervals if your API allows it to give portal users flexibility
297
+
-**Error Handling**: Ensure your API returns appropriate error responses that epilot can handle gracefully
298
+
-**Time Zone Handling**: Take care when handling Time Zones and DSTs
299
+
300
+
### Data Existence Check/Retrieval
301
+
302
+
Sometimes it is desired to check against a third party system before allowing a user to register or self-assign business objects to their account.
303
+
At the same time, it might be necessary to load business entities to epilot before allowing user to proceed in cases epilot does not have all data on non-portal users.
304
+
305
+
#### Registration Hook
306
+
307
+
#### Self-Assignment Hook
308
+
309
+
### Data Validation
310
+
311
+
312
+
#### Meter Reading Plausibility
313
+
314
+
For additional help or questions about portal extensions, please [contact our developer support team](https://developers.epilot.cloud/contact).
0 commit comments