Docs update for Enrich 4.1.0 (#777)

* Docs for Cross Navigation Enrichment * Multiple JS enrichment and passing params to JS enrichment * Remove Enrich jar file sections * Bump Enrich to 4.1.0 * Remove reusable/enrichment-list
snowplow · Feb 23, 2024 · a43575c · a43575c
1 parent 9f937b8
commit a43575c
Show file tree

Hide file tree

Showing 19 changed files with 95 additions and 61 deletions.
diff --git a/.../enriching-your-data/available-enrichments/cookie-extractor-enrichment/index.md b/.../enriching-your-data/available-enrichments/cookie-extractor-enrichment/index.md
@@ -1,6 +1,6 @@
 ---
 title: "Cookie extractor enrichment"
-sidebar_position: 6
+sidebar_position: 7
 sidebar_label: Cookie extractor
 ---
 

diff --git a/.../enriching-your-data/available-enrichments/cross-navigation-enrichment/index.md b/.../enriching-your-data/available-enrichments/cross-navigation-enrichment/index.md
@@ -0,0 +1,37 @@
+---
+title: "Cross Navigation Enrichment"
+sidebar_position: 5
+sidebar_label: Cross Navigation
+---
+
+This enrichment parses the extended cross navigation format in `_sp` querystring parameter and attaches the `cross_navigation` context to an event.
+
+The `_sp` parameter can be attached by our Web ([see cross-domain tracking](/docs/collecting-data/collecting-from-own-applications/javascript-trackers/web-tracker/cross-domain-tracking/index.md)) and [mobile trackers](/docs/collecting-data/collecting-from-own-applications/mobile-trackers/tracking-events/session-tracking/index.md#decorating-outgoing-links-using-cross-navigation-tracking) and contains user, session and app identifiers (e.g., domain user and session IDs, business user ID, source app ID). The information to include in the parameters is configurable in the trackers. This is useful for tracking the movement of users across different apps and platforms.
+
+The extended cross navigation format can be described by `_sp={domainUserId}.{timestamp}.{sessionId}.{subjectUserId}.{sourceId}.{platform}.{reason}`
+
+If this enrichment isn't enabled, Enrich parses `_sp` querystring parameter according to the old format, `_sp={domainUserId}.{timestamp}`
+
+## Configuration
+
+- [Schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow.enrichments/cross_navigation_config/jsonschema/1-0-0)
+- [Example](https://github.com/snowplow/enrich/blob/master/config/enrichments/cross_navigation_config.json)
+
+```mdx-code-block
+import TestingWithMicro from "@site/docs/reusable/test-enrichment-with-micro/_index.md"
+
+<TestingWithMicro/>
+```
+
+## Input
+
+This enrichment extracts `_sp` querystring parameter from the following inputs:
+
+- The `page_url` field from the Snowplow event
+- The referer uri extracted from corresponding HTTP header in the raw event
+
+## Output
+
+This enrichment adds a new derived context to the enriched event with [this schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/cross_navigation/jsonschema/1-0-0).
+
+Also, it continues to populate `refr_domain_userid` and `refr_dvce_tstamp` enriched event fields as before.
diff --git a/...nriching-your-data/available-enrichments/custom-api-request-enrichment/index.md b/...nriching-your-data/available-enrichments/custom-api-request-enrichment/index.md
@@ -1,6 +1,6 @@
 ---
 title: "Custom API Request enrichment"
-sidebar_position: 12
+sidebar_position: 13
 sidebar_label: Custom API Request
 ---
 

diff --git a/...enriching-your-data/available-enrichments/custom-javascript-enrichment/index.md b/...enriching-your-data/available-enrichments/custom-javascript-enrichment/index.md
@@ -1,6 +1,6 @@
 ---
 title: "Custom JavaScript enrichment"
-sidebar_position: 10
+sidebar_position: 11
 sidebar_label: Custom JavaScript
 ---
 
@@ -11,7 +11,7 @@ With this enrichment, you can write a JavaScript function to be executed for eac
 
 ## Configuration
 
-- [schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/javascript_script_config/jsonschema/1-0-0)
+- [schema](https://github.com/snowplow/iglu-central/blob/master/schemas/com.snowplowanalytics.snowplow/javascript_script_config/jsonschema/1-0-1)
 - [example](https://github.com/snowplow/enrich/blob/master/config/enrichments/javascript_script_enrichment.json)
 
 :::note base64 encoding

diff --git a/...g-your-data/available-enrichments/custom-javascript-enrichment/writing/index.md b/...g-your-data/available-enrichments/custom-javascript-enrichment/writing/index.md
@@ -19,7 +19,9 @@ function process(event) {
 }
 ```
 
-Remember that you can only have _one_ JavaScript enrichment, and hence a single `process` function for your pipeline. However, you can split more complex logic into multiple helper functions and variables as you see fit, as long as you comply with the above interface.
+Starting with Enrich 4.1.0, it is possible to have multiple JavaScript enrichments. (Currently, the order in which they would run is not defined.)
+
+With versions prior to 4.1.0, you can only have _one_ JavaScript enrichment, and hence a single `process` function for your pipeline. However, you can split more complex logic into multiple helper functions and variables as you see fit, as long as you comply with the above interface.
 
 :::tip JavaScript Language Features
 
@@ -277,3 +279,44 @@ function process(event) {
   ...
 }
 ```
+
+## Passing an object of parameters
+
+Starting with Enrich 4.1.0, it is possible to pass an object of parameters to the JS enrichment.
+
+You can pass these parameters in the enrichment configuration, for example:
+
+```json
+{
+	"schema": "iglu:com.snowplowanalytics.snowplow/javascript_script_config/jsonschema/1-0-1",
+
+	"data": {
+
+		"vendor": "com.snowplowanalytics.snowplow",
+		"name": "javascript_script_config",
+		"enabled": true,
+		"parameters": {
+			"script": "script",
+			"config": {
+				"foo": 3,
+				"nested": {
+					"bar": "test"
+				}
+			}
+		}
+	}
+}
+```
+
+The parameter object can be accessed in JavaScript enrichment code via the second parameter of the `process` function, for example:
+
+```js
+function process(event, params) {
+  event.setApp_id(params.nested.bar);
+  return [];
+}
+```
+
+:::tip
+This is useful when you want to quickly reconfigure the enrichment without updating the JavaScript code.
+:::
diff --git a/docs/enriching-your-data/available-enrichments/custom-sql-enrichment/index.md b/docs/enriching-your-data/available-enrichments/custom-sql-enrichment/index.md
@@ -1,6 +1,6 @@
 ---
 title: "Custom SQL enrichment"
-sidebar_position: 11
+sidebar_position: 12
 sidebar_label: Custom SQL
 ---
 

diff --git a/...enriching-your-data/available-enrichments/event-fingerprint-enrichment/index.md b/...enriching-your-data/available-enrichments/event-fingerprint-enrichment/index.md
@@ -1,6 +1,6 @@
 ---
 title: "Event fingerprint enrichment"
-sidebar_position: 5
+sidebar_position: 6
 sidebar_label: Event fingerprint
 ---
 

diff --git a/...ching-your-data/available-enrichments/http-header-extractor-enrichment/index.md b/...ching-your-data/available-enrichments/http-header-extractor-enrichment/index.md
@@ -1,6 +1,6 @@
 ---
 title: "HTTP header extractor enrichment"
-sidebar_position: 7
+sidebar_position: 8
 sidebar_label: HTTP header extractor
 ---
 

diff --git a/docs/enriching-your-data/available-enrichments/index.md b/docs/enriching-your-data/available-enrichments/index.md
@@ -10,7 +10,7 @@ The order of enrichments is hard-coded and cannot be changed, the below table li
 
 :::note
 
-Currently, it’s not possible to configure more than one instance of the same enrichment. This is particularly relevant for the JavaScript, SQL Query and API Request enrichments — you can only configure one of each.
+It’s not possible to configure more than one instance of the same enrichment except JavaScript enrichment starting with Enrich 4.1.0. It is possible to have multiple JavaScript enrichments starting with Enrich 4.1.0. For all other enrichments, you can still only configure one of each including SQL Query and API Request enrichments.
 
 :::
 
@@ -23,6 +23,7 @@ Currently, it’s not possible to configure more than one instance of the same e
 | [Currency Conversion](/docs/enriching-your-data/available-enrichments/currency-conversion-enrichment/index.md)     | Convert the values of all transactions to a specified base currency using Open Exchange Rates API. *(Please note the [limitations](/docs/enriching-your-data/available-enrichments/currency-conversion-enrichment/index.md).)* |
 | [Referer Parser](/docs/enriching-your-data/available-enrichments/referrer-parser-enrichment/index.md)              | Extracts attribution data from referer URLs.                                                                                                                                                                                   |
 | [Campaign Attribution](/docs/enriching-your-data/available-enrichments/campaign-attribution-enrichment/index.md)   | Choose which querystring parameters will be used to generate the marketing campaign fields. *If you do not enable the campaign_attribution enrichment, those fields will not be populated.*                                    |
+| [Cross Navigation Enrichment](/docs/enriching-your-data/available-enrichments/cross-navigation-enrichment/index.md)   | Parse the extended cross navigation format in _sp querystring parameter and attach the cross_navigation context to an event. (>= Enrich 4.1.0)                                                                                                                                       |
 | [Event Fingerprint](/docs/enriching-your-data/available-enrichments/event-fingerprint-enrichment/index.md)         | Generate a fingerprint for the event using a hash of client-set fields. Helpful for deduplicating events.                                                                                                                      |
 | [Cookie Extractor](/docs/enriching-your-data/available-enrichments/cookie-extractor-enrichment/index.md)           | Specify cookies that you want to extract if found.                                                                                                                                                                             |
 | [HTTP Header Extractor](/docs/enriching-your-data/available-enrichments/http-header-extractor-enrichment/index.md) | Specify headers that you want to extract via a regex pattern, if found each extracted header will be attached to your event.                                                                                                   |

diff --git a/.../enriching-your-data/available-enrichments/ip-anonymization-enrichment/index.md b/.../enriching-your-data/available-enrichments/ip-anonymization-enrichment/index.md
@@ -1,6 +1,6 @@
 ---
 title: "IP anonymization enrichment"
-sidebar_position: 13
+sidebar_position: 14
 sidebar_label: IP anonymization
 ---
 

diff --git a/docs/enriching-your-data/available-enrichments/ip-lookup-enrichment/index.md b/docs/enriching-your-data/available-enrichments/ip-lookup-enrichment/index.md
@@ -1,6 +1,6 @@
 ---
 title: "IP Lookup enrichment"
-sidebar_position: 9
+sidebar_position: 10
 sidebar_label: IP Lookup 
 ---
 

diff --git a/...iching-your-data/available-enrichments/pii-pseudonymization-enrichment/index.md b/...iching-your-data/available-enrichments/pii-pseudonymization-enrichment/index.md
@@ -1,6 +1,6 @@
 ---
 title: "PII pseudonymization enrichment"
-sidebar_position: 14
+sidebar_position: 15
 sidebar_label: PII pseudonymization
 ---
 

diff --git a/docs/enriching-your-data/available-enrichments/yauaa-enrichment/index.md b/docs/enriching-your-data/available-enrichments/yauaa-enrichment/index.md
@@ -1,6 +1,6 @@
 ---
 title: "YAUAA enrichment"
-sidebar_position: 8
+sidebar_position: 9
 sidebar_label: YAUAA
 ---
 

diff --git a/...ipeline-components-and-applications/enrichment-components/enrich-kafka/index.md b/...ipeline-components-and-applications/enrichment-components/enrich-kafka/index.md
@@ -33,15 +33,6 @@ Above assumes that you have following directory structure:
 
 It is possible to use environment variables in all of the above (for Iglu and enrichments starting from `3.7.0` only).
 
-Alternatively, you can download and run [a jar file from the github release](https://github.com/snowplow/enrich/releases).
-
-<CodeBlock language="bash">{
-`java -jar snowplow-enrich-kafka-${versions.enrich}.jar \\
-  --enrichments /snowplow/enrichments \\
-  --iglu-config /snowplow/resolver.json \\
-  --config /snowplow/config.hocon
-`}</CodeBlock>
-
 Configuration guide can be found on [this page](/docs/pipeline-components-and-applications/enrichment-components/configuration-reference/index.md) and information about the monitoring on [this one](/docs/pipeline-components-and-applications/enrichment-components/monitoring/index.md).
 
 ```mdx-code-block

diff --git a/...eline-components-and-applications/enrichment-components/enrich-kinesis/index.md b/...eline-components-and-applications/enrichment-components/enrich-kinesis/index.md
@@ -35,15 +35,6 @@ It is possible to use environment variables in all of the above (for Iglu and en
 
 Depending on where the app runs, `AWS_ACCESS_KEY` and `AWS_SECRET_KEY` might not be required.
 
-Alternatively, you can download and run [a jar file from the github release](https://github.com/snowplow/enrich/releases).
-
-<CodeBlock language="bash">{
-`java -jar snowplow-enrich-kinesis-${versions.enrich}.jar \\
-  --enrichments /snowplow/enrichments \\
-  --iglu-config /snowplow/resolver.json \\
-  --config /snowplow/config.hocon
-`}</CodeBlock>
-
 Configuration guide can be found on [this page](/docs/pipeline-components-and-applications/enrichment-components/configuration-reference/index.md) and information about the monitoring on [this one](/docs/pipeline-components-and-applications/enrichment-components/monitoring/index.md).
 
 ```mdx-code-block

diff --git a/.../pipeline-components-and-applications/enrichment-components/enrich-nsq/index.md b/.../pipeline-components-and-applications/enrichment-components/enrich-nsq/index.md
@@ -32,15 +32,6 @@ Above assumes that you have following directory structure:
 
 It is possible to use environment variables in all of the above.
 
-Alternatively, you can download and run [a jar file from the github release](https://github.com/snowplow/enrich/releases).
-
-<CodeBlock language="bash">{
-`java -jar snowplow-enrich-nsq-${versions.enrich}.jar \\
-  --enrichments /snowplow/enrichments \\
-  --iglu-config /snowplow/resolver.json \\
-  --config /snowplow/config.hocon
-`}</CodeBlock>
-
 Configuration guide can be found on [this page](/docs/pipeline-components-and-applications/enrichment-components/configuration-reference/index.md) and information about the monitoring on [this one](/docs/pipeline-components-and-applications/enrichment-components/monitoring/index.md).
 
 ```mdx-code-block

diff --git a/...peline-components-and-applications/enrichment-components/enrich-pubsub/index.md b/...peline-components-and-applications/enrichment-components/enrich-pubsub/index.md
@@ -34,15 +34,6 @@ Above assumes that you have following directory structure:
 
 It is possible to use environment variables in all of the above (for Iglu and enrichments starting from `3.7.0` only).
 
-Alternatively, you can download and run [a jar file from the github release](https://github.com/snowplow/enrich/releases).
-
-<CodeBlock language="bash">{
-`java -jar snowplow-enrich-pubsub-${versions.enrich}.jar \\
-  --enrichments /snowplow/enrichments \\
-  --iglu-config /snowplow/resolver.json \\
-  --config /snowplow/config.hocon
-`}</CodeBlock>
-
 Configuration guide can be found on [this page](/docs/pipeline-components-and-applications/enrichment-components/configuration-reference/index.md) and information about the monitoring on [this one](/docs/pipeline-components-and-applications/enrichment-components/monitoring/index.md).
 
 ```mdx-code-block

diff --git a/docs/reusable/enrichment-list/_index.md b/docs/reusable/enrichment-list/_index.md
diff --git a/src/componentVersions.js b/src/componentVersions.js
@@ -23,7 +23,7 @@ export const versions = {
 
   // Core pipeline
   collector: '3.1.0',
-  enrich: '4.0.0',
+  enrich: '4.1.0',
   sqs2kinesis: '1.0.4',
   dataflowRunner: '0.7.4',
   snowbridge: '2.2.2',