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: README.md
+63-79Lines changed: 63 additions & 79 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,25 +1,20 @@
1
1
# XML Component [](https://circleci.com/gh/elasticio/xml-component)
2
2
3
3
## Description
4
-
iPaaS component to convert between XML and JSON data.
4
+
An iPaaS component that converts data between XML and JSON formats.
5
5
6
6
### Purpose
7
-
Allows users to convert XML attachments and strings to and from JSON.
8
-
This component has 3 actions allowing users to pass in either generic but well formatted XML/JSON strings or XML attachments
9
-
and produces a generic string or attachment of the other file type. The output then can be mapped and used in other components.
7
+
This component converts XML attachments or strings to and from JSON. It exposes three actions that accept either well‑formed XML/JSON strings or XML attachments and returns the converted payload as a string or attachment. The result can be consumed by downstream components.
10
8
11
9
### Requirements and Conversion Behavior
12
-
Provided XML document (for `XML to JSON`) should be [well-formed](https://en.wikipedia.org/wiki/Well-formed_document)
13
-
in order to be parsed correctly. You will get an error otherwise.
10
+
- XML content supplied to the `XML to JSON` action must be [well-formed](https://en.wikipedia.org/wiki/Well-formed_document); invalid XML results in an error.
11
+
- JSON inputs must be objects with exactly one field, matching the single root element requirement for XML documents.
12
+
-[JSON inputs cannot contain field names that violate XML tag naming rules](https://www.w3schools.com/xml/xml_elements.asp):
13
+
- They must start with a letter or underscore.
14
+
- They cannot start with the letters `xml` (in any casing).
15
+
- They may only contain letters, digits, hyphens, underscores, and periods.
14
16
15
-
JSON inputs must be objects with exactly one field as XML documents must be contained in a single 'root' tag.
16
-
[JSON inputs can not have any field names which are not valid as XML tag names:](https://www.w3schools.com/xml/xml_elements.asp)
17
-
* They must start with a letter or underscore
18
-
* They cannot start with the letters xml (or XML, or Xml, etc)
19
-
* They must only contain letters, digits, hyphens, underscores, and periods
20
-
21
-
XML attributes on a tag can be read and set by setting an `_attr` sub-object in the JSON.
22
-
The inner-text of an XML element can also be controlled with `#` sub-object.
17
+
XML attributes on a tag can be represented with an `_attr` object, and element text content can be set with the `_` key.
23
18
24
19
For example:
25
20
```json
@@ -32,28 +27,22 @@ For example:
32
27
}
33
28
}
34
29
```
35
-
is equivalent to
30
+
31
+
is equivalent to:
36
32
```xml
37
33
<someTagid="my id">my inner text</someTag>
38
34
```
39
35
40
36
#### Environment variables
41
-
*`MAX_FILE_SIZE`: *optional* - Controls the maximum size of an attachment to be read or written in MB.
42
-
43
-
Defaults to 10 MB where 1 MB = 1024 * 1024 bytes.
44
-
*`EIO_REQUIRED_RAM_MB`: *optional* - You can increase memory usage limit for component if you going to work with big files
45
-
46
-
Defaults to 256 MB where 1 MB = 1024 * 1024 bytes.
37
+
-`MAX_FILE_SIZE` (optional): Maximum attachment size, in bytes, that can be read or written. Defaults to 10 MB (`10 * 1024 * 1024` bytes).
38
+
-`EIO_REQUIRED_RAM_MB` (optional): Memory usage limit for the component. Defaults to 256 MB.
47
39
48
40
## Actions
49
41
50
42
### XML to JSON
51
-
Takes XML string and converts it to generic JSON object.
52
-
53
-
**Limitation:**
54
-
Value inside xml tags will be converting into string only, e.g.:
43
+
Converts an XML string into a generic JSON object.
55
44
56
-
given xml
45
+
**Limitation:** Values inside XML tags are converted to strings. For example, given:
57
46
```xml
58
47
<note>
59
48
<date>2015-09-01</date>
@@ -64,7 +53,7 @@ given xml
64
53
</note>
65
54
```
66
55
67
-
will be converted into:
56
+
the output is:
68
57
```json
69
58
{
70
59
"note": {
@@ -79,73 +68,68 @@ will be converted into:
79
68
80
69
### XML Attachment to JSON
81
70
#### Configuration Fields
82
-
83
-
***Pattern** - (string, optional): RegEx for filtering files by name provided via old attachment mechanism (outside message body)
84
-
***Upload single file** - (checkbox, optional): Use this option if you want to upload a single file
71
+
-**Pattern** (string, optional): Regular expression used to filter attachments provided via the legacy attachment mechanism.
72
+
-**Upload single file** (checkbox, optional): Enable when the message contains a single attachment object.
85
73
86
74
#### Input Metadata
87
-
If `Upload single file` checked, there will be 2 fields:
88
-
***URL** - (string, required): link to file on Internet or platform
89
-
90
-
If `Upload single file` unchecked:
91
-
***Attachments** - (array, required): Collection of files to upload, each record contains object with two keys:
92
-
***URL** - (string, required): link to file on Internet or platform
93
-
94
-
If you going to use this option with static data, you need to switch to Developer mode
95
-
<details><summary>Sample</summary>
96
-
<p>
97
-
98
-
```json
99
-
{
100
-
"attachments": [
101
-
{
102
-
"url": "https://example.com/files/file1.xml"
103
-
},
104
-
{
105
-
"url": "https://example.com/files/file2.xml"
106
-
}
107
-
]
108
-
}
109
-
```
110
-
</p>
111
-
</details>
75
+
When **Upload single file** is enabled:
76
+
-**URL** (string, required): Link to the file, either public or internal (including steward/maester storage).
112
77
113
-
#### Output Metadata
78
+
When **Upload single file** is disabled:
79
+
-**Attachments** (array, required): Collection of attachment objects.
80
+
-**URL** (string, required): Link to the file on the internet or the platform.
114
81
115
-
Resulting JSON object
82
+
If you plan to use this option with static data, switch to Developer mode.
83
+
<details><summary>Sample</summary>
84
+
<p>
85
+
86
+
```json
87
+
{
88
+
"attachments": [
89
+
{
90
+
"url": "https://example.com/files/file1.xml"
91
+
},
92
+
{
93
+
"url": "https://example.com/files/file2.xml"
94
+
}
95
+
]
96
+
}
97
+
```
98
+
</p>
99
+
</details>
100
+
101
+
#### Output Metadata
102
+
A JSON object built from the parsed XML.
116
103
117
104
### JSON to XML
118
-
Provides an input where a user provides a JSONata expression that should evaluate to an object to convert to JSON.
119
-
See [Requirements & Conversion Behavior](#requirements-and-conversion-behavior) for details on conversion logic.
120
-
The following options are supported:
121
-
***Upload XML as file to attachments**: When checked, the resulting XML will be placed directly into an attachment.
122
-
The attachment information will be provided in both the message's attachments section as well as `attachmentUrl` and `attachmentSize`
123
-
will be populated. The attachment size will be described in bytes.
124
-
When this box is not checked, the resulting XML will be provided in the `xmlString` field.
125
-
***Exclude XML Header/Description**: When checked, no XML header of the form `<?xml version="1.0" encoding="UTF-8" standalone="no"?>` will be prepended to the XML output.
126
-
***Is the XML file standalone**: When checked, the xml header/description will have a value of `yes` for standalone. Otherwise, the value will be `no`. Has no effect when XML header/description is excluded.
127
-
128
-
The incoming message should have a single field `input`. When using integrator mode, this appears as the input **JSON to convert** When building mappings in developper mode, one must set the `input` property. E.g.:
105
+
Accepts a JSONata expression that must resolve to an object, then converts it to XML. See [Requirements and Conversion Behavior](#requirements-and-conversion-behavior) for more detail.
106
+
107
+
Options:
108
+
-**Upload XML as file to attachments**: When enabled, the resulting XML is stored as an attachment. `attachmentUrl` and `attachmentSize` are provided in the body and the message attachments.
109
+
-**Exclude XML Header/Description**: When enabled, the XML declaration (`<?xml version="1.0" encoding="UTF-8" standalone="no"?>`) is omitted.
110
+
-**Is the XML file standalone**: Controls the `standalone` attribute in the XML declaration (`yes` or `no`). Ignored when the header is excluded.
111
+
112
+
Incoming messages must contain a single `input` field. In integrator mode this appears as **JSON to convert**. In developer mode, set the `input` property manually. Example:
129
113
```
130
114
{
131
115
"input": {
132
-
"someTag": {
133
-
"_attr": {
134
-
"id": "my id"
135
-
},
136
-
"_": "my inner text"
137
-
}
138
-
}
116
+
"someTag": {
117
+
"_attr": {
118
+
"id": "my id"
119
+
},
120
+
"_": "my inner text"
121
+
}
122
+
}
139
123
}
140
124
```
141
125
142
126
## Known limitations
143
-
- All actions involving attachments are not supported on local agents due to current platform limitations.
144
-
- When creating XML files with invalid XML tags, the name of the potentially invalid tag will not be reported.
145
-
- When you try to retrieve sample in `XML Attachment to JSON`action and it's size is more then 500Kb, there will be generated new smaller sample with same structure as original
127
+
- Actions working with attachments are not supported on local agents due to current platform constraints.
128
+
- When creating XML files with invalid XML tags, the invalid tag name is not reported.
129
+
- If an attachment used for sampling in `XML Attachment to JSON`exceeds 500 KB, a smaller sample with the same structure is generated.
this.logger.warn('The message size exceeded the sample size limit. To match the limitation we will generate a smaller sample using the structure/schema from the original file.');
0 commit comments