Adding extension BAM

Signed-off-by: Sebastian Döll <[email protected]>

cloudevents/extensions/README.md

@@ -41,6 +41,7 @@ for more information.
 ## Known Extensions
 
 - [Auth Context](authcontext.md)
+- [BAM](bam.md)
 - [Dataref (Claim Check Pattern)](dataref.md)
 - [Distributed Tracing](distributed-tracing.md)
 - [Expiry Time](expirytime.md)

cloudevents/extensions/bam.md

@@ -0,0 +1,129 @@
+# Business Activity Monitoring (BAM) Extension
+
+Business Activity Monitoring (BAM) was originally coined by analysts at
+Gartner, and refers to the aggregation, analysis, and presentation of
+real-time information about activities inside organizations, customers,
+and partners.
+
+The activity monitoring consists of a model of a business process,
+which can consists of multiple transactions (e.g. order, payment, invoice),
+and these transactions can have multiple steps. The technical processing
+represented by a transaction instance `bamtxid` is then correlated with
+the steps in those transactions of the business process.
+
+This extension defines attributes that can be included within a CloudEvent
+to describe the business activity that the event is associated with.
+
+Producers and consumers are free to define an out-of-band agreement on the
+semantic meaning, or valid values, for the attribute.
+
+## Notational Conventions
+
+As with the main [CloudEvents specification](../spec.md), the key words "MUST",
+"MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
+"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as
+described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
+
+However, the scope of these key words is limited to when this extension is
+used. For example, an attribute being marked as "REQUIRED" does not mean
+it needs to be in all CloudEvents, rather it needs to be included only when
+this extension is being used.
+
+## Attributes
+
+### bamtxid
+
+- Type: `String`
+- Description: A unique identifer for the instance of a transaction.
+  This identifier connects the actual processing in the distributed
+  system (e.g. payment, invoice, warehouse) with the model of this process.
+- Constraints
+  - REQUIRED
+  - MUST be a non-empty string
+  - RECOMMENDED as monotonically increasing and contiguous identifier
+    that is lexicographically-sortable.
+
+### bampid
+
+- Type: `String`
+- Description: A unique identifier for the model of the business process
+  that is associated with instance of the transaction `bamtxid`.
+  A business process is a collection of transactions. These transactions
+  can run in sequence or parallel (e.g. payment, invoice, warehouse).
+- Constraints
+  - REQUIRED
+  - MUST be a non-empty string
+  - RECOMMENDED a alphanumeric string that contains non-whitespace characters
+    and only hyphens, underscores, and periods.
+
+### bamptxid
+
+- Type: `String`
+- Description: A unique identifier for the model of a transaction that
+  constructs a business process (e.g. payment, invoice, warehouse).
+- Constraints
+  - REQUIRED
+  - MUST be a non-empty string
+  - RECOMMENDED a alphanumeric string that contains non-whitespace characters
+    and only hyphens, underscores, and periods.
+
+### bamptxsid
+
+- Type: `String`
+- Description: A unique identifier for the specific step in a business process
+  transaction (e.g. start, processing, finish).
+- Constraints
+  - REQUIRED
+  - MUST be a non-empty string
+  - RECOMMENDED a alphanumeric string that contains non-whitespace characters
+    and only hyphens, underscores, and periods.
+
+### bamptxsstatus
+
+- Type: `String`
+- Description: The status of the specific step in a business process
+  transaction (e.g. success, waiting, failure).
+- Constraints
+  - OPTIONAL
+  - if present, MUST be a non-empty string
+  - RECOMMENDED a alphanumeric string that contains non-whitespace characters
+    and only hyphens, underscores, and periods.
+
+### bamptxcompleted
+
+- Type: `Boolean`
+- Description: Indicates if the instance of the transaction (`bamtxid`) has
+  actually been completed, or if the transaction has somehow failed.
+  This is a mechanism to indicate a final completion or failure that is
+  not captures by the model of the business process..
+- Constraints
+  - OPTIONAL
+  - if present, MUST be a boolean value
+
+## Usage
+
+When this extension is used, producers MUST set the value of
+the `businesstransactionid`, `businessprocessid`,
+`businessprocesstransactionid`, and `businessprocesstransactionstepid`
+attributes to the unique identifiers of the business process, transaction,
+and transaction step associated with the event.
+
+Intermediaries MUST NOT change the value of the `businesstransactionid`,
+`businessprocessid`, `businessprocesstransactionid`,
+and `businessprocesstransactionstepid` attributes.
+
+## Use cases
+
+This extension can be used in cases in which a business activity monitoring
+system is used to monitor the progress of a business process, and the events
+generated by the process are used to track the progress of the process.
+Usually these systems have their own modelling language to describe the
+business process, and the events generated by the process
+are used to track the progress of the process.
+
+## References
+
+- [Gartner Business Activity Monitoring](https://www.gartner.com/en/information-technology/glossary/bam-business-activity-monitoring)
+- [Business Activity Monitoring](https://en.wikipedia.org/wiki/Business_activity_monitoring)
+- [What is Business Activity Monitoring (BAM)?](https://www.ibm.com/topics/business-activity-monitoring)
+- [Business Activity Monitoring (BAM)](https://learn.microsoft.com/en-us/biztalk/core/business-activity-monitoring-bam)

cloudevents/languages/he/extensions/bam.md

@@ -0,0 +1,2 @@
+# Business Activity Monitoring (BAM) Extension
+מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/bam.md) לבינתיים.

cloudevents/languages/zh-CN/extensions/bam.md

@@ -0,0 +1,6 @@
+# Business Activity Monitoring (BAM) Extension
+
+本文档尚未被翻译，请先阅读英文[原版文档](../../../extensions/bam.md) 。
+
+如果您迫切地需要此文档的中文翻译，请[提交一个issue](https://github.com/cloudevents/spec/issues) ，
+我们会尽快安排专人进行翻译。