@forge/util
2.0.12.0.1-experimental-7890858
packages/analytics-node-client/README.md~
packages/analytics-node-client/README.mdModified+135−33
Index: package/packages/analytics-node-client/README.md
===================================================================
--- package/packages/analytics-node-client/README.md
+++ package/packages/analytics-node-client/README.md
@@ -15,16 +15,25 @@
const client = analyticsClient({
env: 'prod', // prod, stg or dev
product: 'jira', // required
- subproduct: 'software' // Optional
- sendEventHook: (event) => {} // Optional callback
- perimeter: 'fedramp-moderate' // Optional. The FedRAMP perimeter level.
+ subproduct: 'software', // Optional
+ sendEventHook: (event) => {}, // Optional callback
+ perimeter: 'fedramp-moderate', // Optional. The FedRAMP perimeter level.
+ ic: 'ic-001', // Optional, defaults to undefined
+ baseUrl: 'https://as.atlassian.com/api', // Required for IC environments, optional for non-isolation context environments (regular commercial)
+ producerRole: 'server', // Optional. May be 'server' or 'client', used to qualify Track event names.
});
```
-**To send events to the FedRAMP stg-apse environment, you need to set the perimeter field to fedramp-moderate**
+`perimeter`: If you need to send events to FedRAMP environment you should use this parameter.
+`ic`: Should be set to Isolation Context (IC) identifier if applicable. The `ic` information will be added to events and used to validate IC event routing in the server. This value is validated in the backend, and having the incorrect ic set will cause events to be lost.
+
+`baseUrl`: Overrides the default URL to send analytics to. The client expects `baseUrl` to be set to an IC domain when `ic` is specified.
+
+`producerRole`: By default the Analytics Service considers the NodeJS library to be a `server` for the purposes of Track event naming. If you are using this library in a client context you can override this by setting `producerRole` to `client`.
+
#### User information
If a `userId` is specified, then a valid `userIdType` is also required. If no `userId` is specified, then `anonymousId` must be used.
@@ -35,8 +44,9 @@
* `HASHED_EMAIL`
* `OPSGENIE`
* `HALP`
* `CUSTOMER_ACCOUNT` - This type is the JSM customer account
+* `LOOM`
#### Tenant information
If a `tenantId` is specified, then a valid `tenantIdType` is also required.
@@ -44,8 +54,10 @@
We support the following `tenantIdType`s:
* `CLOUD_ID` - Atlassian Cloud
* `HALP_TEAM_ID` - Halp
+* `LOOM_ORG_ID` - Loom Org Id
+* `TRELLO_WORKSPACE_ID` - Trello Workspace Id
* `NONE` - Products without a tenant concept
#### Org information
@@ -54,8 +66,19 @@
#### Workspace information
If you specify a `workspaceId`, you can use it to provide information about the workspace
+#### Set Group (e.g. Transaction Account) information
+
+There are currently two ways to add `transactionAccountId` to your event payload:
+
+1. Use the `.setGroup()` function on the analytics client to set this to the client. Note: The event(s) sent by this client will always have the same `groups: { transactionAccountId: 'some-group-txa-id' }` payload set by `.setGroup()`
+2. (For **Track** events only for now) - Pass in `groups` at runtime to the `.sendTrackEvent()` function. This event payload will include the passed in `groups` instead of the `groups` set at the client level.
+
+#### Session ID
+
+The Node client does not natively generate a session ID, but allows the value to be set within the event payload. This supports cases where an event producer may want to synchronise a session between the node client and a front-end analytics client that generates a session ID.
+
#### Containers
The `containers` field is meant to be the new representation of the container hierarchy where the event takes place. Think something like issue -> board -> project.
Check more info about the `containers` field in this [doco](https://hello.atlassian.net/wiki/spaces/ANALYTICS/pages/463696450/DACI+Flexible+entity+hierarchy+in+analytics+events).
@@ -143,13 +166,14 @@
tenantIdType: 'cloudId',
tenantId: 'some-tenant-id',
orgId: 'some-org-id',
workspaceId: 'some-workspace-id',
+ sessionId: 'some-session-id', // optional
trackEvent: {
source: 'api', // required
action: 'testAction', // required
actionSubject: 'testActionSubject', // required
- actionSubjectId: 'my-action-subject-id'
+ actionSubjectId: 'my-action-subject-id',
attributes: {
attribute: 'my-attribute-info',
},
containers: { // optional
@@ -161,8 +185,12 @@
id: 'b5533697-c14c-442b-8773-03da44741831', // required
type: 'public' // optional
}
}
+ },
+ groups: { // optional
+ groupTypes.TRANSACTION_ACCOUNT_ID: 'example-transaction-account-id',
+ groupTypes.PRODUCT_INTEGRATIONS_VENDOR_ID: 'example-product-integrations-vendor-id'
}
});
```
@@ -176,13 +204,14 @@
tenantIdType: 'cloudId',
tenantId: 'some-tenant-id',
orgId: 'some-org-id',
workspaceId: 'some-workspace-id',
+ sessionId: 'some-session-id', // optional
trackEvent: {
source: 'api', // required
action: 'testAction', // required
actionSubject: 'testActionSubject', // required
- actionSubjectId: 'my-action-subject-id'
+ actionSubjectId: 'my-action-subject-id',
attributes: {
attribute: 'my-attribute-info',
},
containers: { // optional
@@ -213,8 +242,9 @@
tenantIdType: 'cloudId',
tenantType: 'my-tenant-type',
orgId: 'some-org-id',
workspaceId: 'some-workspace-id',
+ sessionId: 'some-session-id', // optional
uiEvent: {
source: 'api',
action: 'testAction', // required
actionSubject: 'testActionSubject', // required
@@ -246,8 +276,9 @@
tenantIdType: 'cloudId',
tenantType: 'my-tenant-type',
orgId: 'some-org-id',
workspaceId: 'some-workspace-id',
+ sessionId: 'some-session-id', // optional
name: 'some-screen-name', // required
screenEvent: {
origin: 'some-origin', // required
platform: 'some-platform', // required
@@ -278,13 +309,14 @@
tenantIdType: 'cloudId',
tenantId: 'some-tenant-id',
orgId: 'some-org-id',
workspaceId: 'some-workspace-id',
+ sessionId: 'some-session-id', // optional
operationalEvent: {
source: 'api', // required
action: 'testAction', // required
actionSubject: 'testActionSubject', // required
- actionSubjectId: 'my-action-subject-id'
+ actionSubjectId: 'my-action-subject-id',
attributes: {
attribute: 'my-attribute-info',
},
containers: { // optional
@@ -321,8 +353,9 @@
**Note** The `setAlias` and `setGroup` methods will only accept values that are in the enums `aliasTypes` and `groupTypes`. If you have a specific use case and wish to include a new enum, please get in touch with us at [#help-analytics-pipeline](https://atlassian.enterprise.slack.com/archives/CFG85MPMX).
Currently, [we support the following `groupTypes` values](https://bitbucket.org/atlassian/analytics-node-client/src/master/src/constants/group-type.js):
- `TRANSACTION_ACCOUNT_ID`
+- `PRODUCT_INTEGRATIONS_VENDOR_ID`
## Sending a TraitEvent
@@ -331,9 +364,11 @@
entityType: entityTypes.ATLASSIAN_ACCOUNT, // required
entityId: '557058:qweqwe-1793-45a0-9732-9ef656b7ab43', // required
entityTraits: { // required
'first-logged-in-to-your-service': new Date() // at least one trait required
- }
+ },
+ tenantId: 'my-tenant-id', // Optional, required if tenantIdType is set
+ tenantIdType: 'cloudId' // Optional, required if tenantId is set
});
```
## Error Handling
@@ -350,8 +385,75 @@
Likely, you don't want your process to crash when you get a 429 from GAS
(essentially creating a hard coupling from your service to GAS), so we
recommend passing this property.
+## Early Event Validation
+* Analytics Node Client supports `Early Event Validation` feature which the consumers can leverage in near real time to infer whether or not the events sent to GASv3 resulted in any validation errors.
+* As the calls from the client to GASv3 are synchronous in nature, this feature comes in handy to address potential issues / gaps with the events as early in the development cycle as possible.
+* This feature comes with 3 validationModes - `quiet`, `standard` and `complete` which can be set either at Batch SegmentContext level (or) Event SegmentContext level. For the consumers, as the events in the client are batched before being sent to GASv3, consumers can choose to specify the `validationMode` only at Event SegmentContext level, if needed due to the points outlined below.
+* By default, the `validationMode` set internally at the time of of creating the client is environment specific.
+* This environment specific `validationMode` set during client creation will be used as the default `validationMode` at Batch SegmentContext level. This means that for all the events sent in the Batch, the `validationMode` is considered
+as the one set as the default `validationMode` at Batch SegmentContext level.
+* For `prod` environment, the default `validationMode` is set as `quiet` during client creation.
+* For all other environments, the default `validationMode` is set as `complete` during client creation.
+* If `validationMode` needs to be overriden post client creation, make use of `setEventValidationMode` exposed on the client.
+* Only when the `validationMode` is set as either `standard` or `complete`, the event validation reports with errors / issues, if any from GASv3 will be exposed to the consumers.
+* When the `validationMode` is set as `quiet`, even if there are event validation reports from GASv3, they won't be exposed to the consumers.
+* For the consumers to have better control over the event validation reports, Analytics Node Client also supports
+consumer response callback.
+* By default, event validation reports are logged [if `validationMode` is set as either `standard` or `complete`] on the `Console` through a default response consumer callback which is set during client creation.
+* If the consumers want to use their own consumer response callback, it can be set on the Analytics Node Client post client construction through a setter function on the client. The callback set by the consumers overrides the default callback.
+
+```javascript
+const { analyticsClient } = require('@atlassiansox/analytics-node-client');
+
+const client = analyticsClient({
+ env: 'prod', // prod, stg or dev
+ product: 'jira', // required
+ subproduct: 'software' // Optional
+ sendEventHook: (event) => {} // Optional callback
+ ....
+ ....
+});
+
+client.setEventValidationMode('standard'); // or 'quiet' or 'complete'
+client.setResponseCallback((analyticsResponse) => { console.log('YOUR OWN CALLABACK: ', analyticsResponse); });
+```
+Example of setting `validationMode` at event level
+
+```javascript
+client.sendOperationalEvent({
+ userId: 'some-user-id',
+ anonymousId: 'some-anonymous-id',
+ userIdType: 'atlassianAccount',
+ tenantIdType: 'cloudId',
+ tenantId: 'some-tenant-id',
+ orgId: 'some-org-id',
+ workspaceId: 'some-workspace-id',
+ sessionId: 'some-session-id', // optional
+ operationalEvent: {
+ source: 'api', // required
+ action: 'testAction', // required
+ actionSubject: 'testActionSubject', // required
+ actionSubjectId: 'my-action-subject-id',
+ attributes: {
+ attribute: 'my-attribute-info',
+ },
+ containers: { // optional
+ project: {
+ id: 'b1875f21-434f-4d3f-a57c-2962b154d947', // required
+ type: 'kanban' // optional
+ },
+ board: {
+ id: 'b5533697-c14c-442b-8773-03da44741831', // required
+ type: 'public' // optional
+ }
+ }
+ },
+ validationMode: 'complete'
+});
+```
+
## Developing Locally
Setup: `npm install`
Generating Typescript Types: `npm run generateTypes`
@@ -364,48 +466,48 @@
### Writing changesets:
Changesets are an important part of the development process. Version bumping is automatic and controlled via changeset files.
-Please adhere to the [this](https://developer.atlassian.com/cloud/framework/atlassian-frontend/development/versioning/#versioning-guidelines) guideline when selecting the bump type for your package.
+Please adhere to [this](https://developer.atlassian.com/cloud/framework/atlassian-frontend/development/versioning/#versioning-guidelines) guideline when selecting the bump type for your package.
Run the command line script `npx changeset`, write changesets that users understand and can take action on and commit changes.
## Migration from v3 to v4 Guide
1. System requirements
-- Node >= 14
+ - Node >= 14
2. Changes to `flush()`
-The `flush()` function has been deprecated.
+ The `flush()` function has been deprecated.
+
+ If you don’t want to batch messages, you can turn batching off by setting the`maxEventsInBatch` setting to 1, like so:
+
+ ```
+ const client = analyticsClient({
+ ...
+ maxEventsInBatch: 1
+ });
+ ```
+
+ If you want to avoid losing events after shutting down your console. Call `.gracefulShutdown()` to stop collecting new events and flush all existing events.
+
+ ```
+ await client .gracefulShutdown()
+ ```
+
+ ***Note*** Calling `.gracefulShutdown()` will stop collecting new events.
+
+ If you need to call gracefulShudown() function and subsequently trigger new events, you should instantiate a new instance of the analytics client.
-If you don’t want to batch messages, you can turn batching off by setting the`maxEventsInBatch` setting to 1, like so:
-
-```
-const client = analyticsClient({
- ...
- maxEventsInBatch: 1
-});
-```
-
-If you want to avoid losing events after shutting down your console. Call `.gracefulShutdown()` to stop collecting new events and flush all existing events.
-
-```
-await client .gracefulShutdown()
-```
-
-***Note*** Calling `.gracefulShutdown()` will stop collecting new events.
-
-If you need to call gracefulShudown() function and subsequently trigger new events, you should instantiate a new instance of the analytics client.
-
3. Changes to `flushAt`
-The `flushAt` configuration option has been renamed to `maxEventsInBatch`.
+ The `flushAt` configuration option has been renamed to `maxEventsInBatch`.
4. Changes to `retryDelayFn`
-The `retryDelayFn` has been removed from `@segment/analytics-node`. Use `maxRetries` to configure the number of times to retry flushing a batch.
+ The `retryDelayFn` has been removed from `@segment/analytics-node`. Use `maxRetries` to configure the number of times to retry flushing a batch.
5. Changes to `timeout`
-The `timeout` option has been removed from `@segment/analytics-node`. Use `httpRequestTimeout` to configure the maximum number of milliseconds to wait for an http request.
+ The `timeout` option has been removed from `@segment/analytics-node`. Use `httpRequestTimeout` to configure the maximum number of milliseconds to wait for an http request.