diff --git a/README.md b/README.md index 14c5394..e634c29 100644 --- a/README.md +++ b/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 diff --git a/docs-gen/content/service_data_rule_set/basics.md b/docs-gen/content/service_data_rule_set/basics.md index b16e5b7..fdc7ef1 100644 --- a/docs-gen/content/service_data_rule_set/basics.md +++ b/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. diff --git a/docs-gen/content/service_data_rule_set/iostruct.md b/docs-gen/content/service_data_rule_set/iostruct.md index 2816db0..4af8891 100644 --- a/docs-gen/content/service_data_rule_set/iostruct.md +++ b/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. diff --git a/docs-gen/content/service_data_rule_set/iprocedure-mprocedure.md b/docs-gen/content/service_data_rule_set/iprocedure-mprocedure.md new file mode 100644 index 0000000..4e0fae8 --- /dev/null +++ b/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. diff --git a/docs-gen/content/service_data_rule_set/microservice.md b/docs-gen/content/service_data_rule_set/microservice.md deleted file mode 100644 index c0493f0..0000000 --- a/docs-gen/content/service_data_rule_set/microservice.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Microservice node" -weight: 30 ---- - -Nodes of the type `microservice` must have the following mandatory metadata: -- Name -- Type -- Scope -- Description - -An interface exposing the microservice may support not only the possibility to "invoke" it, i. e. to execute the functionality the microservice offers. -It may also, or exclusively, support the option to "monitor" the microservice, i. e. to get information about its execution by other clients invoking it. -This behavior of the microservice is set by the Scope which must have one of the following values -* invoke -* monitor -* all - -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 `microservice` node is given below. -```YAML -microserviceName: - type: microservice - scope: invoke - description: This is an example of a microservice node containing its mandatory metadata. -``` - -## Microservice State - -A `microservice` node has a mandatory datatype of uint8. As it cannot be set to any other datatype than uint8, -the datatype metadata shall not be explicitly shown in the node. -The main purpose of the state information is to provide a "percentage" state of the execution to clients. - -The microservice must set i to zero (0) at the beginning of the execution, and it must set it to hundred (100) at the end of a successful execution. -It may further update it one or more times during the execution. - -If an error occurs during execution the state shall be set to one of the predefined error values. -This error value is not replacing either a microservice specific error value which the microservice may return as an Output parameter, -nor with the error value that a transport protocol may report. diff --git a/docs-gen/static/images/microservice_tree_structure.png b/docs-gen/static/images/microservice_tree_structure.png index 48aeb1a..f770269 100644 Binary files a/docs-gen/static/images/microservice_tree_structure.png and b/docs-gen/static/images/microservice_tree_structure.png differ