netconfcentral logo

yumaworks-sil-sa

HTML

yumaworks-sil-sa@2019-10-11



  module yumaworks-sil-sa {

    yang-version 1;

    namespace
      "http://yumaworks.com/ns/yumaworks-sil-sa";

    prefix ysil;

    import yuma-types {
      prefix yt;
    }
    import yumaworks-ycontrol {
      prefix yctl;
    }
    import yumaworks-agt-profile {
      prefix yprof;
    }

    organization "YumaWorks, Inc.";

    contact
      "Support <support at yumaworks.com>";

    description
      "YumaPro SIL Sub-Agent message definitions.

       Copyright (c) 2014 - 2019 YumaWorks, Inc. All rights reserved.

       Redistribution and use in source and binary forms, with or
       without modification, is permitted pursuant to, and subject
       to the license terms contained in, the BSD 3-Clause License
       http://opensource.org/licenses/BSD-3-Clause";

    revision "2019-10-11" {
      description
        "Add with-origin flag for NMDA support";
    }

    revision "2019-08-18" {
      description
        "Add stream-name to notification message.
           Add client-addr to transaction messages to support
           sil_sa_get_client_addr function";
    }

    revision "2019-07-02" {
      description
        "Added HOOKS support:
          * Add following leafs to register-request message:
            - Add transaction-start boolean leaf
            - Add transaction-complete boolean leaf
          * Add trans-start-hook message
          * Add trans-complete-hook message";
    }

    revision "2019-04-20" {
      description
        "Added ACTION support:
          * Add action-path to register-request message
          * Add action-request message
          * Add action-response message";
    }

    revision "2019-01-31" {
      description
        "Added user-id-obj grouping used by start-transaction,
           get-request and rpc-request messages";
    }

    revision "2019-01-20" {
      description
        "Add deviation parm to config-response message.";
    }

    revision "2018-12-05" {
      description
        "Add load-config parameter to start-transaction message";
    }

    revision "2018-10-03" {
      description
        "Add bundle parameter to register-request message";
    }

    revision "2018-06-03" {
      description
        "Add rpc-request and rpc-response messages";
    }

    revision "2017-09-19" {
      description
        "Fix broken augment statement for payload";
    }

    revision "2015-11-01" {
      description
        "Added support for GETBULK to get-response message.";
    }

    revision "2015-08-17" {
      description
        "Added 'select' node support to get2 SIL-SA get-request
           message";
    }

    revision "2015-04-17" {
      description
        "Updated notification container for release";
    }

    revision "2015-01-15" {
      description
        "Add get and notification support";
    }

    revision "2014-11-18" {
      description
        "Fix module type, supposed to be NcModuleNameSpec
           to allow foo@2000-01-01, not just foo.
           Add bundle-module leaf-list to register msg
           Add bundle-load-event to inform server of any modules
           loaded from a SIL-SA bundle; Remove shutdown-event.";
    }

    revision "2014-09-06" {
      description
        "Add agt-profile container to config-parms grouping
           used in the <config-response> from server to subsystem.";
    }

    revision "2014-08-01" {
      description "Initial version.";
    }


    grouping bundle-module-parm {
      leaf-list bundle-module {
        type yt:NcModuleSpec;
        description
          "Module parameters that were loaded as a result of
           any bundle parameters. They will be returned in the
           form modname@revision-date.";
      }
    }  // grouping bundle-module-parm

    grouping bundle-parm {
      leaf-list bundle {
        type yt:NcxName;
        description
          "Bundle names that were loaded as a result of
           any bundle parameters.";
      }
    }  // grouping bundle-parm

    grouping path-parm {
      leaf path {
        type string;
        mandatory true;
        description
          "Object identifier string:

            * matches 'path' in the register-request message
              for an EDIT callback
            * matches 'get-path' in the register-request message
              for a GET2 callback
            * matches 'action-path' in the register-request message
              for an ACTION callback

           The path string is generated with YANG prefixes using
           the obj_gen_object_id_prefix function in ncx/obj.h
          ";
      }
    }  // grouping path-parm

    augment /yctl:ycontrol/yctl:message-payload/yctl:payload/yctl:payload {
      container sil-sa {
        description
          "Server Instrumentation Library Sub-Agent API Messages

           SIL-SA Protocol Initialization:

           1) subsys sends a <config-request> subsys-request msg
           2) server replies with <config-response> server-response
              msg with the agt_profile data
           3) subsys sends a <register-request> subsys-request msg
              with modules and object path-expressions to register.
              Any bundle and bundle-module info is also sent
           4) server sends <ok> server-response
           5) subsys sends a <trigger-replay> subsys-event;
              if any config for this subsystem, server will send
              a <start-transaction> server-request with a config-replay
              transaction

           SIL-SA Protocol Edit Operation:

           1) the server sends a <start-transaction> server-request msg
              with the edit list
           2) the subsys validates the request and sends an
              <ok> subsys-response (or error)
           3) the server sends a <continue-transaction> for the apply
              phase
           4) the subsys applies the request and sends an
              <ok> subsys-response (or error)
           5) the server sends a <continue-transaction> for the commit
              phase
           6) the subsys commits the request and sends an
              <ok> subsys-response (or error).

           If the server does not get to step (5) because of an error,
           a <continue-transaction> server-request msg will be sent
           for the rollback phase.

           If the server does not get to step (3) because of an error,
           it will send a <cancel-transaction> server-event msg so
           the subsystem can release any saved state.

           RPC Operation:

           1) the server sends an <rpc-request> with the input parameters
           2) the subsystem performs VALIDATE and INVOKE phases
           3) the subsystem returns <rpc-ok> or <rpc-data>.
              YControl error is used for any errors

           ACTION Operation:

           1) the server sends an <action-request> with the input parameters
           2) the subsystem performs VALIDATE and INVOKE phases
           3) the subsystem returns <action-ok> or <action-data>.
              YControl error is used for any errors

           HOOKS Support:

            Transaction Start Hooks:
               1) the server send trans-start-hook request
               2) the subsys validates the request, invoke callbacks, and
                  sends an <ok> subsys-response (or error)

            Transaction Complete Hooks:
               1) the server send trans-complete-hook event msg so subsystem
                  can invoke Transaction Complete Callbacks
          ";
        grouping operation-parms {
          leaf operation {
            type enumeration {
              enum "merge" {
                value 0;
              }
              enum "replace" {
                value 1;
              }
              enum "create" {
                value 2;
              }
              enum "delete" {
                value 3;
              }
              enum "load" {
                value 4;
              }
              enum "commit" {
                value 5;
              }
            }
            mandatory true;
            description
              "Operation matching op_editop_t enumeration list.";
          }
        }  // grouping operation-parms

        grouping transaction-id-obj {
          leaf transaction-id {
            type string;
            mandatory true;
            description
              "Server specific transaction identifier.";
          }
        }  // grouping transaction-id-obj

        grouping user-id-obj {
          leaf user-id {
            type string;
            description
              "Identifies the user that initiated this transaction.";
          }
        }  // grouping user-id-obj

        grouping client-addr-obj {
          leaf client-addr {
            type string;
            description
              "Identifies the address of the client that initiated
               this transaction.";
          }
        }  // grouping client-addr-obj

        grouping config-parms {
          uses yprof:agt-profile;

          leaf-list bundle {
            type yt:NcxName;
            description
              "Bundle SIL SA libraries to load";
          }

          leaf-list module {
            type yt:NcModuleSpec;
            description
              "Module SIL SA libraries to load";
          }

          leaf-list deviation {
            type yt:NcModuleSpec;
            description
              "Deviations and annotations to load";
          }
        }  // grouping config-parms
        choice message-type {
          mandatory true;
          leaf config-request {
            type empty;
            description
              "Message type: subsys-request;
              Purpose: register the service with the server
              and request the service configuration from server.
              Expected Response Message: config-response";
          }
          container config-response {
            description
              "Message type: server-reply;
              Purpose: server will send this element containing the
              requested sub-system configuration.
              Expected Response Message: none";
            uses config-parms;
          }  // container config-response
          container register-request {
            description
              "Message type: subsys-request;
              Purpose: register the SIL-SA callback functions
              for this sub-system.
              Expected Response Message: ok";
            uses bundle-parm;

            uses bundle-module-parm;

            list register {
              key "module";
              description
                "Specifies the path strings of all the objects
                 in each module that is supported by the subsystem.";
              leaf module {
                type yt:NcxName;
                description
                  "Module name for the target object.";
              }

              leaf-list path {
                type string;
                description
                  "Path string for object for an EDIT callback";
              }

              leaf-list get-path {
                type string;
                description
                  "Path string for object for a GET callback";
              }

              leaf-list rpc-name {
                type yt:NcxName;
                description
                  "Name of the RPC operation callback";
              }

              leaf-list action-path {
                type string;
                description
                  "Path string for object for an ACTION callback";
              }
            }  // list register

            leaf transaction-start {
              type boolean;
              description
                "The leaf specifies if there is a Transaction
                 Start Callbacks to register";
            }

            leaf transaction-complete {
              type boolean;
              description
                "The leaf specifies if there is a Transaction
                 Complete Callbacks to register";
            }
          }  // container register-request
          container start-transaction {
            description
              "Message type: server-request;
              Purpose: Start an edit transaction which may require the
              SIL-SA callback functions on the subsystem to be invoked.

              This message requests that a new edit transaction be
              started on the subsystem.  Only 1 transaction can be in
              progress at a time.

              If this transaction is for a validate operation then
              there will not be any followup messages.  Otherwise,
              the subsystem will retain this message until a
              cancel-transaction message has been received with the
              same transaction-id value, or a continue-transaction
              message has been received with the same transaction-id
              value for the 'rollback' or 'commit' phase.

              Expected Response Message: ok or error";
            uses transaction-id-obj;

            uses user-id-obj {
              refine user-id {
                mandatory true;
              }
            }

            uses client-addr-obj;

            leaf target {
              type string;
              mandatory true;
              description
                "Identifies the target datastore being edited.
                 The values 'candidate' and 'running' are supported.";
            }

            leaf validate {
              type boolean;
              default 'false';
              description
                "If 'true' then this start-transaction is for a validate
                 operation or edit that is not on the running
                 configuration datastore, so there will not be
                 any followup messages at all for this message.
                 The subsystem will release this info instead of caching it,
                 and not expect any more messages for the same value of
                 'transaction-id'.

                 If 'false' then this is a normal edit operation and
                 the apply and commit/rollback followup messages
                 will be sent. The subsystem will cache this data
                 until the transaction is cancelled or completed.";
            }

            leaf reverse-edit {
              type boolean;
              default 'false';
              description
                "If 'true' then this start-transaction is for a
                 reverse-edit operation.  All the phases should
                 be invoked in sequence for the provided edit-list.
                 The transaction can be discarded after sending
                 a response, like the 'validate=true' flag.
                 If 'false' then this is a normal edit operation.";
            }

            leaf load-config {
              type boolean;
              default 'false';
              description
                "If 'true' then this start-transaction is for a
                 <trigger-replay> operation. If 'false' then this is
                 a normal edit operation, probably caused by
                 a client <edit-config> operation.";
            }

            list edit {
              key "id";
              leaf id {
                type uint32;
                description
                  "Arbitrary edit identifier.";
              }

              uses operation-parms;

              uses path-parm;

              anyxml newval {
                description
                  "Represents the new value, if any.
                   Should be present if operation is 'merge'
                   'replace', 'create', or 'load'.";
              }

              anyxml curval {
                description
                  "Represents the current value, if any.
                   Should be present if operation is 'replace',
                   'delete', or 'commit'";
              }

              anyxml keys {
                description
                  "List of all ancestor or self key values for the
                   object being edited, identified by the 'path' value.
                   There will be one child leaf for each key in each list.";
              }
            }  // list edit
          }  // container start-transaction
          container continue-transaction {
            description
              "Message type: server-request;
              Purpose: Invoke a callback phase for an edit transaction
              in progress.


              Expected Response Message: ok or error";
            uses transaction-id-obj;

            leaf phase {
              type enumeration {
                enum "apply" {
                  value 0;
                  description
                    "Apply the curent transaction.
                     Resources can be reserved that will be
                     used in the commit phase.";
                }
                enum "commit" {
                  value 1;
                  description
                    "Commit the current transaction.";
                }
                enum "rollback" {
                  value 2;
                  description
                    "Rollback the current transaction.";
                }
              }
              mandatory true;
              description
                "The SIL-SA callback phase in progress.";
            }
          }  // container continue-transaction
          container cancel-transaction {
            description
              "Message type: server-event;
              Purpose: Cancel an edit transaction in progress.
              Expected Response Message: none";
            uses transaction-id-obj;
          }  // container cancel-transaction
          leaf trigger-replay {
            type empty;
            description
              "Message type: subsys-event;
              Purpose: Trigger a configueration replay to load
                 the running config data into the SIL-SA
                 instrumentation.
              Expected Response Message: none; server will send
                 a <start-transaction> if there is any
                 config for the SIL-SA functions registered
                 by the subsystem.";
          }
          container load-event {
            description
              "Message type: server-event;
              Purpose: A module or bundle has been loaded or
                 unloaded at run-time. Subsys wil load SIL-SA code.
                 and trigger a register event for any SIL calls
                 registered.
              Expected Response Message: none";
            leaf load {
              type boolean;
              default 'true';
              description
                "Set to 'true' if this is a load event.
                 Set to 'false' if this is an unload event.";
            }

            uses config-parms;
          }  // container load-event
          container bundle-load-event {
            description
              "Message type: subsys-event;
              Purpose: A SIL-SA bundle has been loaded with
               a load-event sent from the server.  This has
               caused some modules to be loaded on the subsystem,
               that need to be reported back to the main server
               so the datastore validation, agt_state, and other
               system book-keeping can be done.
              Expected Response Message: none";
            uses bundle-parm;

            uses bundle-module-parm;
          }  // container bundle-load-event
          container get-request {
            description
              "Composite retrieval request to support NETCONF
               and RESTCONF get operations.
               Type: server-request
               Expected Response Message: subsys-response
                                   (get-response or error)";
            uses transaction-id-obj;

            uses user-id-obj;

            uses client-addr-obj;

            leaf flags {
              type bits {
                bit keys {
                  position 0;
                  description
                    "Return only the key values";
                }
                bit config {
                  position 1;
                  description
                    "Return config=true data nodes";
                }
                bit oper {
                  position 2;
                  description
                    "Return config=false data nodes";
                }
                bit getnext {
                  position 3;
                  description
                    "This is a get-next request instead of a
                    get request";
                }
                bit withdef {
                  position 4;
                  description
                    "Return default values for missing nodes";
                }
                bit select {
                  position 5;
                  description
                    "Return only the select nodes and any key leafs.
                     Ignore the config, oper, withdef flags if this
                     bit is set.";
                }
                bit with-origin {
                  position 6;
                  description
                    "This is a <get-data> operation and the
                     with-origin parameter is selected.";
                }
              }
              default "";
              description
                "Set of get request modifier flags";
            }

            leaf max-entries {
              type uint32;
              description
                "Max number of entries requested.
                 The default is '0' == all for leaf-list and
                 '1' for all other node types.";
            }

            uses path-parm;

            anyxml keys {
              description
                "List of all ancestor or self key values for the
                 object being retrieved, identified by the 'path'
                 value. There will be one child leaf for each key
                 in each list.";
            }

            anyxml matches {
              description
                "Represents any content-match child leafs for the
                 request. All leafs in this container must match the
                 corresponding child nodes in an instance of the
                 requested list or container, for that instance to
                 be returned.

                 Any content-match nodes must match in addition
                 to any key leafs specified in the 'keys' container.";
            }

            container select-nodes {
              list select-node {
                key "objname";
                description
                  "Only requesting these nodes be returned. If no
                   entries and the 'select' bit is set in the flags
                   leaf, then no objects except list keys are
                   returned.";
                leaf objname {
                  type string;
                  description
                    "Object name of the select node";
                }

                leaf modname {
                  type string;
                  description
                    "Module name of the select node; If missing then
                     use the module-name of the path target object.";
                }
              }  // list select-node
            }  // container select-nodes
          }  // container get-request
          container get-response {
            description
              "Composite retrieval response to support NETCONF
               and RESTCONF get operations.
               Type: subsys-response
               Expected Response Message: none";
            grouping return-val {
              anyxml return-keys {
                description
                  "List of all ancestor or self key values for the
                   object being retrieved, identified by the 'path'
                   value. There will be one child leaf for each key
                   in each list.";
              }

              anyxml values {
                description
                  "Represents the retrieved values, if any.
                   There will be one child node for each returned
                   value.";
              }
            }  // grouping return-val
            uses transaction-id-obj;

            leaf more-data {
              type boolean;
              default 'false';
              description
                "Indicates if the GET callback has more data to send";
            }

            leaf match-test-done {
              type boolean;
              default 'false';
              description
                "Indicates if the requested content-match tests have
                 be performed. Ignored if the 'matches' parameter
                 is missing or empty.";
            }

            leaf active-case-modname {
              type string;
              description
                "Module name of the active case if there is one.
                 Only applies if the GET2 object callback is for
                 a YANG choice-stmt.";
            }

            leaf active-case {
              type string;
              description
                "Name of the active case if there is one.
                 Only applies if the GET2 object callback is for
                 a YANG choice-stmt.";
            }

            leaf origin {
              type string;
              description
                "The NMDA origin value for this object.
                 Only applies for config=true list and
                 presence containers.";
            }

            choice return-choice {
              case return-one {
                description
                  "For all objects except YANG list, one entry
                   will be returned.  This can also be used
                   for YANG list, except in GETBULK mode.";
                uses return-val;
              }  // case return-one

              case return-getbulk {
                description
                  "For YANG list GETBULK mode.  There will be one entry
                   for each list instance that met the search criteria.
                   If the max_entries parameter was greater than zero,
                   there the number of instances of 'entry' should not
                   exceed this value.";
                list entry {
                  uses return-val;
                }  // list entry
              }  // case return-getbulk
            }  // choice return-choice
          }  // container get-response
          container notification {
            description
              "Subsystem generated YANG notification event
               for NETCONF and RESTCONF streams.
               Type: subsys-event
               Expected Response Message: none";
            leaf module-name {
              type string;
              mandatory true;
              description
                "Module name containing the notification definition";
            }

            leaf event-name {
              type string;
              mandatory true;
              description
                "Notification statement name";
            }

            leaf event-time {
              type string;
              mandatory true;
              description
                "Notification creation timestamp";
            }

            leaf stream-name {
              type yt:NcxName;
              default "NETCONF";
              description
                "Stream name for this notification";
            }

            anyxml parms {
              description
                "List of all parameters that this notification
                 is sending in the payload.";
            }
          }  // container notification
          container rpc-request {
            description
              "Message type: server-request;
              Purpose: Start an RPC transaction which may require the
              SIL-SA callback functions on the subsystem to be invoked.

              This message requests that a new remote procedure
              call be validated and invoked on the subsystem.

              If there are input parameters the subsystem
              must validate them.

              If not valid or if the operation cannot be performed,
              the subsystem must return an error.

              Expected Response Message: rpc-response";
            uses transaction-id-obj;

            uses user-id-obj;

            uses client-addr-obj;

            leaf rpc-module {
              type yt:NcxName;
              mandatory true;
              description
                "Identifies the module name of the RPC definition.";
            }

            leaf rpc-name {
              type yt:NcxName;
              mandatory true;
              description
                "Identifies the name of the RPC definition.";
            }

            anyxml rpc-input {
              description
                "Contains the RPC input data (if any).";
            }
          }  // container rpc-request
          container rpc-response {
            description
              "Message type: subsys-response
              Purpose: Return RPC data or status
              Expected Response Message: none";
            uses transaction-id-obj;

            choice response-type {
              leaf rpc-ok {
                type empty;
                description
                  "RPC successfully invoked";
              }
              anyxml rpc-output {
                description
                  "Contains the RPC output data (if any).";
              }
            }  // choice response-type
          }  // container rpc-response
          container action-request {
            description
              "Message type: server-request;
              Purpose: Start an ACTION transaction which may require the
              SIL-SA callback functions on the subsystem to be invoked.

              This message requests that a new action call be validated
              and invoked on the subsystem.

              If there are input parameters the subsystem
              must validate them.

              If not valid or if the operation cannot be performed,
              the subsystem must return an error.

              Expected Response Message: action-response";
            uses transaction-id-obj;

            uses user-id-obj;

            uses client-addr-obj;

            uses path-parm;

            anyxml keys {
              description
                "List of all ancestor key values for the
                 action being invoked, identified by the 'path' value.
                 There will be one child leaf for each key in each list.";
            }

            anyxml action-input {
              description
                "Contains the ACTION input data (if any).";
            }
          }  // container action-request
          container action-response {
            description
              "Message type: subsys-response
              Purpose: Return ACTION data or status
              Expected Response Message: none";
            uses transaction-id-obj;

            choice response-type {
              leaf action-ok {
                type empty;
                description
                  "ACTION successfully invoked";
              }
              anyxml action-output {
                description
                  "Contains the ACTION output data (if any).";
              }
            }  // choice response-type
          }  // container action-response
          container trans-start-hook {
            description
              "Message type: server-request;
              Purpose: Send a request which may require the
              SIL-SA callback functions on the subsystem to be invoked;
              Expected Response Message: <ok> or <error>.

              This message requests that Transaction Start Hook callbacks
              should be invoked on the subsystem.";
            uses transaction-id-obj;

            uses user-id-obj;

            uses client-addr-obj;

            leaf isvalidate {
              type boolean;
              description
                "Specifies whether this is a <validate> operation or not.
                TRUE if this is a validate operation transaction";
            }

            leaf isrollback {
              type boolean;
              description
                "Specifies whether this is a confirmed commit timeout
                or a cancel-confirmed-commit operation.
                FALSE if this is some other type of transaction";
            }

            leaf isrunning {
              type boolean;
              description
                "Specifies whether this is transaction for running datastore.
                TRUE if this is a running datastore transaction";
            }
          }  // container trans-start-hook
          container trans-complete-hook {
            description
              "Message type: server-event;
              Purpose: Send an event which may require the
                SIL-SA callback functions on the subsystem to be invoked;
              Expected Response Message: none";
            uses transaction-id-obj;
          }  // container trans-complete-hook
        }  // choice message-type
      }  // container sil-sa
    }
  }  // module yumaworks-sil-sa

Summary

  
  
Organization YumaWorks, Inc.
  
Module yumaworks-sil-sa
Version 2019-10-11
File yumaworks-sil-sa.yang
  
Prefix ysil
Namespace http://yumaworks.com/ns/yumaworks-sil-sa
  
Cooked /cookedmodules/yumaworks-sil-sa/2019-10-11
YANG /src/yumaworks-sil-sa@2019-10-11.yang
XSD /xsd/yumaworks-sil-sa@2019-10-11.xsd
  
Abstract YumaPro SIL Sub-Agent message definitions. Copyright (c) 2014 - 2019 YumaWorks, Inc. All rights reserved. Redistribution and u...
  
Contact
Support <support at yumaworks.com>

Description

 
YumaPro SIL Sub-Agent message definitions.

Copyright (c) 2014 - 2019 YumaWorks, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the BSD 3-Clause License
http://opensource.org/licenses/BSD-3-Clause

Groupings

Grouping Objects Abstract
bundle-module-parm bundle-module
bundle-parm bundle
path-parm path