Skip to content

Commit b97ef3f

Browse files
krystofkomaneckrystofkomanec
authored
Merge pull request #244 from codevence/hotfix/add-integration-migration-explanation
Hotfix/add integration migration explanation
2 parents c52f203 + 0523afd commit b97ef3f

File tree

3 files changed

+123
-2
lines changed

3 files changed

+123
-2
lines changed

‎docs/more/development/integration-questions/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,5 @@ There are two ways of how we can connect |project_name| to these services:
2121
:maxdepth: 1
2222

2323
API<integration-api>
24+
Migration<migration>
2425
Widget<integration-widget>

‎docs/more/development/integration-questions/integration-api.rst‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _integration-api:
2+
13
Integration Question - API
24
**************************
35

@@ -24,6 +26,8 @@ If we want to connect an external service using the API there are certain requir
2426
- The response must be JSON so |project_name| can parse it
2527
- There needs to be a JSON list where all the items matching the search query are
2628

29+
.. _integration-api-configuration:
30+
2731
Configuration
2832
=============
2933

@@ -35,7 +39,7 @@ Watch this video to learn the basic API Integration setup:
3539

3640

3741
The configuration is done in the :ref:`knowledge model editor<knowledge-model-editor>`. First of all, we need to create a new integration and choose its **Type** to be **API**. Then we need to fill the integration **Name**.
38-
42+
3943
Advanced Integration Configuration
4044
----------------------------------
4145

@@ -177,7 +181,7 @@ Secrets and Other Properties (Legacy)
177181

178182
Sometimes, we might need to use some secrets (for example for authentication token), additional properties (such as API URL if we want to use different one for testing and production), or basically any information that we do not want to include in the knowledge model. In that case, we can define some properties in the instance settings.
179183

180-
We need to navigate to :guilabel:`Administration → Settings → Knowledge Models` and there is a field called **Integration Config**. It is a YAML organized by the **Integration ID** at the top level and key value pairs for each property.
184+
We need to navigate to :guilabel:`Administration → Settings → knowledge models` and there is a field called **Integration Config**. It is a YAML organized by the **Integration ID** at the top level and key value pairs for each property.
181185

182186
We can fill some properties in. So, for example, if the **Integration ID** of our integration is *ourIntegration* we can write:
183187

‎docs/more/development/integration-questions/migration.rst‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
.. _integration-migration:
2+
3+
Migration from Legacy API Integration
4+
*************************************
5+
6+
To migrate a knowledge model from API Integration Legacy to API Integration v2, we need to recreate the integration and connect it to the respective questions. To do that, open the knowledge model Editor. There, navigate to the existing integrations. The best practice is to create the integration from scratch. You can follow this :ref:`configuration guide<integration-api-configuration>`.
7+
8+
We recommend recreating the integration to keep the original one as a reference. This allows you to copy the configuration from it and identify which questions are using the legacy integration so you can connect them to the new one.
9+
10+
Once the new API Integration v2 instances are successfully created and the integration questions are connected to them, you can delete the old integrations and release the knowledge model. Then you can migrate projects.
11+
12+
.. NOTE::
13+
14+
If you somehow manage to lose the content of the integrations before they are recreated, you can always create a new knowledge model editor.
15+
16+
During the migration from API Integration Legacy to API Integration v2, the existing integration replies in projects are migrated automatically. However, there are differences in how the data is stored. The following sections describe how the data is handled in each state:
17+
- Legacy API Integration
18+
- Migrated to API Integration v2 (legacy data)
19+
- New API Integration v2 with “raw = HTTP response”
20+
21+
**State A — Legacy API Integration (ApiLegacyIntegration)**
22+
23+
This is how API Integration Legacy stores the data.
24+
25+
**What is stored:**
26+
27+
- an ``id`` (the selected item identifier)
28+
- a ``type``: ``IntegrationLegacyType``
29+
- a ``value`` (the rendered markdown or text displayed in the UI)
30+
31+
.. code:: json
32+
33+
{
34+
"type": "IntegrationReply",
35+
"value": {
36+
"id": "0000-0003-3856-1682",
37+
"type": "IntegrationLegacyType",
38+
"value": "**Kryštof** **Komanec** \nORCID: **0000-0003-3856-1682** \n\n\n*Czech Technical University in Prague* \n*Prague University of Economics and Business* \n "
39+
}
40+
}
41+
42+
43+
**State B — Migrated to API Integration v2 (existing data)**
44+
45+
After migrating to API Integration v2, the existing data is stored differently.
46+
47+
**What changes compared to Legacy:**
48+
49+
- ``id`` is **removed**
50+
- ``raw`` is introduced but remains empty: ``"raw": {}``
51+
- ``type`` becomes ``IntegrationType`` instead of ``IntegrationLegacyType``
52+
- ``value`` remains the same (the markdown reply rendered in the UI)
53+
54+
.. code:: json
55+
56+
{
57+
"type": "IntegrationReply",
58+
"value": {
59+
"raw": {},
60+
"type": "IntegrationType",
61+
"value": "**Kryštof** **Komanec** \nORCID: **0000-0003-3856-1682** \n\n\n*Czech Technical University in Prague* \n*Prague University of Economics and Business* \n "
62+
}
63+
}
64+
65+
66+
**State C — New API Integration v2 with IntegrationType reply**
67+
68+
If you delete the old answer and provide a new one, or if you answer a new integration question using API Integration v2, the data is stored differently. The semantics of the stored data also change. The ``raw`` field now contains the raw HTTP response from the API, which can be used in the answer template.
69+
70+
**What is stored:**
71+
72+
- ``raw`` = the actual integration HTTP response item or body, which serves as the source of truth
73+
- ``type`` = ``IntegrationType``
74+
- ``value`` = custom text entered by the user or rendered template output, generated from the ``raw`` data using the answer template
75+
76+
.. code:: json
77+
78+
{
79+
"type": "IntegrationReply",
80+
"value": {
81+
"raw": {
82+
"credit-name": null,
83+
"email": [],
84+
"family-names": "Komanec",
85+
"given-names": "Kryštof",
86+
"institution-name": [
87+
"Czech Technical University in Prague",
88+
"Prague University of Economics and Business"
89+
],
90+
"orcid-id": "0000-0003-3856-1682",
91+
"other-name": []
92+
},
93+
"type": "IntegrationType",
94+
"value": "**Kryštof** **Komanec** \nORCID: [**0000-0003-3856-1682**](https://orcid.org/0000-0003-3856-1682)\n\n"
95+
}
96+
}
97+
98+
99+
**State D - New API Integration v2 with PlainType reply**
100+
101+
If custom reply is enabled in the integration configuration, the answer to an integration question can also be a plain text. In that case, the data is stored as follows.
102+
103+
**What is stored:**
104+
105+
- ``type`` = ``PlainType``
106+
- ``value`` = the plain text answer provided by the user.
107+
108+
.. code:: json
109+
110+
{
111+
"type": "IntegrationReply",
112+
"value": {
113+
"type": "PlainType",
114+
"value": "https://orcid.org/0000-0003-3856-1682"
115+
}
116+
}

0 commit comments

Comments
 (0)