Merge pull request #14 from UlfBj/master

Data service model update

README.md

@@ -31,7 +31,7 @@ Another ambition of HIM s that it shall support definition of taxonomies of diff
 and not only the type here called "resource data".
 HIM currently supports the following "information types":
 - Resource data: Information defining the data that a resource produces or consumes.
-- Service data: Information defining the details of a "service" in the form of a procedure (name, iput, output).
+- Service data: Information defining the details of a "service" in the form of a procedure (name, input, output).
 - Type definition data: Information defining complex/composite data types that are used by the other information types.
 
 HIM also provides a rule set for the definition of a "configuration file" that can be used by a HIM enabled data server in its management of

docs-gen/content/service_data_rule_set/basics.md

@@ -33,18 +33,35 @@ The general structure of how a microservice is represented in a HIM tree is show
 ![HIM microservice tree structure](/hierarchical_information_model/images/microservice_tree_structure.png?width=50pc)
 *Figure x. HIM microservice tree structure
 
-- The name of the procedure is the name of the node of `microservice` type.
+- The name of the procedure is the name of the node of one f the types `iprocedure` or `mprocedure`, see more about the types below.
 - The input and output parameters are respectively represented by a  node of type `iostruct` that must have the names 'Input' and 'Output', respectively.
 - An input/output parameter is represented by a node of type `property` or `symlink`.
 
 Any Input/Output nodes, and their associated children, are only present if the procedure has at least one parameter of the respective Input/Output.
 
+## Node types iprocedure and mprocedure
+The typical pattern for invoking a procedure by a client is that the logic implementing the procedure is actuated, and this atuation is controlled by the procedure input parameters.
+In a multi-client environment there might also be a need for clients to monitor the state and outputs of a procedure that might be invoked by other clients.
+The procedure may not have exactly the same input and output parameters for these two cases.
+A call for monitoring of the procedure should not include input parameters that are used in controlling its actuation as the procedure in this case is not actuated.
+The output may also contain other parameters for improving the observability of its state than when it is called for actuation of it.
+
+To realize these different cases, two different node types representing the procedure exist, the iprocedure (invoke procedure) node type and the mprocedure (monitor procedure) node type.
+The node names of these two nodes shall have the same procedure name, prefixe with "i" for the iprocedure node type and "m" for the mprocedure node type.
+The iprocedure node type MUST be defined for a procedure, the mprocedure node type MUST NOT be defined if there is not also an iprocedure definition.
+
+An interface implementing the HIM service data model is expected to support the two flavors of procedure calls.
+It may choose to support only the invoke flavor.
+
 ## Microservice state
 
 A microservice may have a temporal duration from it is started and until it completes.
-It is therefore desireable that the state of the microservice can be observed,
-as it may be the case that an ongoing microservice execution does not allow new microservice actuations to be started.
-The state of a HIM microservice is represented by a uint8 datatype value that all `microservice` nodes have as a mandatory metadata.
+It may therefore desireable that the state of the microservice can be observed,
+as e. g. it may be the case that an ongoing microservice execution does not allow new microservice actuations to be started.
+If an observable microservice state is desired, then the designer of this HIM service domain must create such an output parameter of the microservice.
+The characteristics of this output parameter can be freely chosen, but below is a proposal that if widely used may help to improvve interoperability.
+
+The state of the HIM microservice is represented by a uint8 datatype value.
 
 The allowed values of the microservice state are:
 - 0-99 : ongoing
@@ -54,7 +71,7 @@ The allowed values of the microservice state are:
 
 The rules for how a microservice shall update the state value follows below:
 
-- A fully functioning that is not ongoing shall have the value 100.
+- A fully functioning microservice that is not ongoing shall have the value 100.
 - When a valid microservice request is received the state shall be set to zero (0).
 - The microservice may update the state value as the microservice execution proceeds.
 - When the microservice execution successfully terminates the state value must be set to 100.

docs-gen/content/service_data_rule_set/iostruct.md

@@ -25,7 +25,7 @@ Besides the mandatory metadata mentioned above, the following optional metadata
 For more information, please see the [Common Rule Set: Optional Metadata](/hierarchical_information_model/common_rule_set/basics#optional-metadata).
 
 - A leaf node cannot have the `iostruct` node type.
-- A parent must be of the node type `microservice`.
+- A parent must be of one of the node types `iprocedure` or `mprocedure`.
 - Children must be of the node types `property` or `symlink`.
 - It must have at least one child.
 

docs-gen/content/service_data_rule_set/iprocedure-mprocedure.md

@@ -0,0 +1,30 @@
+---
+title: "iprocedure and mprocedure nodes"
+weight: 30
+---
+
+As described in the [Service Data Model](https://covesa.github.io/hierarchical_information_model/service_data_rule_set/basics#node-types-iprocedure-and-mprocedure) chapter
+there are two types of nodes that can be used to represent microservices.
+
+Nodes of the types `iprocedure` or `mprocedure` must have the following mandatory metadata:
+- Name
+- Type
+- Description
+
+For more information, see the [Common Rule Set: Mandatory Metadata](/hierarchical_information_model/common_rule_set/basics#mandatory-metadata).
+
+Besides the mandatory metadata mentioned above, the following optional metadata may be used
+- Comment
+
+For more information, please see the [Common Rule Set: Optional Metadata](/hierarchical_information_model/common_rule_set/basics#optional-metadata).
+
+- A parent must be of the node type `branch`.
+- Children, if any, must be of the node type `iostruct`.
+
+An example of the specification of a `iprocedure` node is given below. Please observe that the microserviceName should be prefixed with the letter i.
+```YAML
+imicroserviceName:
+  type: iprocedure
+  description: This is an example of a microservice iprocedure node containing its mandatory metadata.
+```
+Changing the type to `mprocedure` and the microserviceName prefix to the letter m would then represent the monitor flavor of the microservice specification.