• Upload JSON Schema [...] on GitHub Josef till late 19.12.2017

Derived from 2017-11-29Workshop.md protocol.

The deliverables for a 'generic model of addresses'

• in the shape of an UML class diagram (attached) by @hschmidthh till 19th Dec. '17
• in the shape of a JSON schema by @hschmidthh till 19th Dec. '17
• as conceptual elaborations for addresses (including decision processes)

The deliverables for a 'generic model of products'

• in the shape of an UML class diagram (attached) by @JosefBraeuer till 19th Dec. '17
• in the shape of a JSON schema by @JosefBraeuer till 19th Dec. '17
• as conceptual elaborations for products (including decision processes)

The use of JSONata

• Technical mapping between Snazzy Contacts & Standard Data Model - Address
• Technical mapping between Snazzy Contacts & SilvERP

Requirements

• Maschine-readable
• Transformable to JSON Schema (important for API Description)
• Open standard
• Tooling available (transformation, documentation, etc.)

Alternatives

1. JSON Schema
2. XML Schema
3. EMF

The standard model (configuration) holds subsets of data fields (grouped), actually transmitted due to business transactions. Because of backward compatibility #68 the evolution process is heavily embossed by the first version. A good starting point would be granted with a sustainable selection of verified data fields. These can be proofed at nearly realistic conditions within a runtime.

OIH 0.5 access towards addresses and products

• Challenge the standard data model, by transmitting representative aggregates
  • Invoice data as combination of contact/address and items/products

Data transmission via Standard Data Model

POC 1: Adapter (mapping via UI) <> FLOW <> Adapter (mapping via UI)
POC 2: Adapter (mapping via UI) <> FLOW <> SDM <> FLOW <> Adapter (mapping via UI)
POC 3: Adapter+Transformer <> FLOW <> SDM <> FLOW <> Transformer/Adapter

Derived from 2017-11-29Workshop.md protocol.

Current results on addresses by @hschmidthh
Current results on products by @JosefBraeuer

• Explain order.json towards third party @lashauer
• Explain shared-definitions.json towards third party @hschmidthh
• Explain products.json towards third pary @JosefBraeuer

Note: Updates may involve changes to other files - UMLs

• Upload JSON Schema on GitHub Hansjörg till late 19.12.2017

Requirements

• Open standard
• Free from 3rd party licensing
• Automatically convertible to HTML
• Focus on semantic and not syntax
• Hypertext-capable
• Maschine-readable

Alternatives

1. Markdown
2. ASCII
3. DITA

• Create consistent wording across all master data model files Hansjörg, Lutz, Josef till 21.12.2017

👍 For providing a detailed description on Identity and Access Management
👍 For using illustrations/diagrams to visualize the ideas.

Tenant and Tenant Users

The highlighted names in the example workflow are different from the notation in the illustration (e.g. Vendor1 & ACME Inc. and Tenant admin). I think we should adjust it to create maintain consistency.

Sequence Diagram

The example workflow just before the sequence diagram describes that the connector transmits this tenant specific access token to OIH but in the sequence diagram the ISV Connector returns the isv_tenantId. Are the access token and isv_tenantId the same in this scenario? Or is the described scenario not illustrated in the sequence diagram?

work in progress!

Wir definieren einen Integration flow
Im SilvERP wird die target Url mit ggf. notwendigen credentials abgelegt.
Beim speichern eines Adressdatensatzes wird der trigger ausgelöst, der den gesamten Datensatz per webhook an die target Url sendet.

Im Data Hub wird:

• der Datensatz erstens raw gespeichert
• der Datensatz in das OIH Datenmodell überführt und gespeichert (hierbei wird ein Data Hub Unique Identifier erstellt)
• eine Verbindung zu SilverERP (ersteller-) Instanz gespeichert mit dem unique identifier von SilverERP
• es wird die action zum übermitteln an jede einzelne weitere Instanz (in diesem Fall Snazzy) angestossen.
• Snazzy empfängt diesen Datensatz, erkennt am fehlenden "Snazzy-unique-identifier", dass es sich um einen neuen Datensatz handelt
• Daher wird ein neuer Datensatz in Snazzy erstellt und der erstellte Snazzy-identifier als Antwort an den Data Hub gesendet.
• Der Data-Hub merkt sich für jede Instanz die ID des Records in der Instanz und den Zeitstempel (die Version) des Datenesatzes, die erfolgreich an die Instanz übergeben wurde.

Bei einer Änderung dieses Records in einem der beiden Systeme (identisch) - exemplarisch im Snazzy wird:

• Im Snazzy beim speichern der trigger ausgelöst, der den gesamten Datensatz per webhook an die target URL des Data Hub sendet.
• Der Data Hub speichert die Raw Daten
• Der Data Hub überführt die Daten in das Data Hub format und wendet die Änderungen auf den gespeicherten Record an
• Hierbei wird der Änderungszeitstempel (ggf. Änderungs-Instanz und User) im Data Hum mit gespeichert.
• Danach wird die action zum übermitteln des Datensatzes an alle Instanzen ausgelöst (ausgenommen hier: die triggernde Instanz)
• Die Instanzen erkennen im Call, dass eine lokale (z.B. Silvererp eigene) ID enthalten ist und interpretiert den Call als update

Issues:

• Bei einer Übermittlung als State (kompletter Datensatz) muss beachtet werden, dass Änderungen überschrieben werden können, wenn eine Änderunge auf einem älteren Datensatz basiert.
  Beispiel:
  • User 1 in Instanz A lädt einen Adressdatensatzes
  • User 2 in Instanz B lädt den gleichen Adressdatensatz
  • User 2 ändert den Inhalt des Feldes Name1 und speichert
  • User 1 ändert den Inhalt des Feldes Name2 und speichert
  • Im Data Hub wird durch den letzten Speichervorgang das Feld Name1 mit dem Inhalt überschrieben, der beim Laden des Datensatzes von User 1 aktuell war.

    Die Änderung von User 2 geht verloren

Required:

• Jedes System muss einen unique Identifier im eigenen System managen.

One scope of the Open Integration Hub is to foster convenience at marketplaces, where independent SaaS integrations can be used in combinations, according to the business needs of small and medium enterprises (SMEs).

In order to prevent a scenario where access permissions have to be managed in every single app, the identity management should also cover Tenants User. Derived from that a further domain model may need to be introduced that supports to manage identities.

This requirement where discussed at the MS2 planning workshop as seen at the protocol

Derived from 2017-11-29Workshop.md protocol.

This Epic is derived from the 3rd paragraph of the MasterDataModelAdresses.md

• General requirements
• User requirements
  • Types and objects
    • UseCase: properties of organization
    • UseCase: properties of persons
  • Relations
    • UseCase: relations person to organization
    • UseCase: relations organization to others
  • Rights management
  • Data integrity
• Legal requirements
  • data protection
  • data sovereignty

Provide standardized endpoints - public. The following structure was derived in order to result in a unified documentation format #49

• Request methods: GET/POST/PUT/PATCH/DEL
  • Interface and desciption - purpose(s)
  • HEADERS/BODY/PARMS and description - test(s)
  • Status code(s) and description - response(s)

The more convenient your documentation is, the more likely third parties will integrate your app

OData 4.0 documentation / in a nutshell

Legal requirements

• Data protection
• Data sovereignty

• Exporting the final results for milestone 1 into the needed format latest 03.01.2018
• Remove TOCs
• Provide JSONs as .json

Since we convert results into PDFs, please make sure that links show the explicit file name.

• EXAMPLE Master Data Models (Definitions, Rules and Regulations) by @lashauer
• PDF links wont work for MetaModel.md by @lashauer
• /src/main/schema/addresses/shared-definitions.json by @hschmidthh
• /src/main/schema/addresses/relation.json by @hschmidthh
• /src/main/schema/addresses/organization.json by @hschmidthh
• /src/main/schema/addresses/person.json by @hschmidthh
• /src/main/schema/products/product.json by @JosefBraeuer

Mapping example of the proprietary data model towards the current standard data model.

As seen on @ealtendorf her contribution, dot notation allows to explain nested data structured in a readable form - with columns left aligned.

Regarding nested objects, a data point mapping at a two-dimensional table isn't practical.

Rather document your application's data model as JSON format via doca's web interface - suited to present nested structures. @spyanev

JSON STRUCTURE (object.json)

"definition": {
  "datapoint": {
    "type": "string",
    "description" : "Important for the semantic data point mapping"
    "example" : "An entity would look like"
    }
},
"required": ["datapoint"],
"properties": {
   "datapoint": {"$ref": "#/defintions/datapoint"},
   "NestedObject": {"$ref": "./source.json"},
   "FetchedDefinition": {"$ref": "./source.json#/definitions/datapoint"},
   "FetchedProperty": {"$ref": "./source.json#/propterties/datapoint"}
}

In this example the source.json has a proper object defined. The "$ref:" attribute is a name space - link.

User requirements

• Types of objects
• Relations
• Rights management
• Data integrity

Derived from 2017-11-29Workshop.md protocol.

Standard should be:

• Open
• Free from 3rd party licensing
• Readable by computers
• Native support for JSON

Alternatives:

• Open API Specification aka. Swagger 2.0
• RAML
• WADL

According to the 2017-12-11 Telko.md, @josef and @lashauer wanted to define the regulations. Those still need to be propagated with an official document, for the 1st milestone and the community (independent implementations).

Derived structure of the Regulations.md from our call at the 15th Dec. '17

• General regulations for generic data models @lashauer till 19th Dec. '17
• Specific regulations for the generic data model addresses @hschmidthh till 19th Dec. '17
• Specific regulations for the generic data model products @JosefBraeuer till 19th Dec. '17

According to the protocol of the MS2 planning workshop, the Adapters of Snazzy Contacts and SilverERP would correspond to the criteria of POC2, if the quality guidelines have been accomplished.

• Upload the Adapter to GitHub
  • SnazzyContacts
  • SilverERP
  • WiceCRM
• Fulfil the Adapter Checklists
• Feedback hands-on experiences with the guide - #20

Since we went over to provide scalable vectors, the products UML class diagram is missing at .svg format.

The required attributes for the standard data model (configured domain models) arise from the data which a company uses across multiple applications. The underlying business transaction determines the scope of a data set. Such an aggregate consist of nested attributes of separate domain models.

• Ask for data that need to be exchanged
• Make a list of representative business transaction
• Identify the underlying data of most frequent cases
• Create aggregates, that allow seamless data exchange
• Derive an efficient cut for the domain model configuration

As mentioned at #65, an 'ISV-N integration flow' should be convenient to create. So that third parties rather willing to invest their time in building further integrations. It is important for the Open Integration Hub acceptance to find a common API documentation format, therefore. Renat @zubairov mentioned the open data initiative in this context, as an approach for proprietary APIs.

These tasks were derived from the MS2 planning workshop protocol. Our goal is to accomplish POC1 of that roadmap. The following criteria had been found during the workshop in order to do so:

• Create a mapping table #47 / #62
• Create JSONata expression (mapping) #46 / #61
• Document which Elastic components where used and why
• Create an interface documentation #45 / #60
• Compare the documentation in order to unify them

Status

proposed

Context

Is the OIH Data Hub neccessary to enable the hub and spoke communication style within the OIH?
https://en.wikipedia.org/wiki/Hub_and_spokes_architecture

Alternatives

Alternative 1

The OIH Data Hub is not neccessary to enable the hub and spoke communication style within the OIH.
The OIH Data Hub must be an optional component. The basic OIH features like hub and spoke communication style must be usable without the Data Hub.

Decision

ND

Consequences

Individual transformations involving a central hub might be more complex.

Alternative 2

The OIH Data Hub is neccessary to enable the hub and spoke communication style within the OIH.

Decision

ND

Consequences

Without the OIH Data Hub it is neccessary to create point to point connections between applications resulting in many point to point connections if there are more than two applications share the same master data.

• Provide general regulations on basis of the preferences by WICE and YQ Lutz till late 19.12.2017

• Create consistent wording between UML and JSON Josf till late 21.12.2017

All semantic field mappings from proprietary data models towards the standard data model (model configuration) should be able to be done by hand. A third party needs to understand the usage of every single standard data field so that mismatches become less likely.

Such vulnerable implementations would harm a seamless data flow. A proper implementation needs to rely on identical mappings of all other integrations. Therefore a detailed descriptions of the standard data fields are mandatory.

• Quality criteria for the description
• Generic procedure model - later extensions
• Affect on aggregates - usage context implicit

This way we grant a snapshot version of our results - which have a chance to evolve over time.

The API controls the way addresses- and products data can be retrieved and propagated. Its design heavily affects the data flow along the standard data model (configuration). The actual data to be transmitted are pretend by the business transaction.

The transmission itself occurs in the shape of nested fields, as a context-bound collection of data fields, also known as 'aggregate' - which can hold the content of a single receipt for instance.

Consider that only with a proper permission level operations on data should be possible, according to certain company guidelines.

• Align endpoints with the OIH API design pattern - also #65
• Align aggregates towards the effective data transmissions

Add your topic suggestions for the innovation committee meeting on Monay, 16.10.2017.

Topic suggestions

• Example topic, created by @author
• ...

• Upload [...] regulations on GitHub Josef till late 19.12.2017

• Upload the UML diagram on GitHub Josef till late 19.12.2017

Create FAQ section for creation of an adapter