Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The CLAMP Control Loop Automation Composition Participant protocol is an asynchronous protocol that is used by the CLAMP runtime to coordinate life cycle lifecycle management of Control Loop Automation Composition instances. The protocol supports the functions described in the sections below.

Table of Contents

Protocol Dialogues

The protocol supports the dialogues described below.

Participant Registration and De-Registration

Registration when a participant comes up and update of participant with control loop Automation Composition type information and common parameter values for its control loop Automation Composition types.


PlantUML Macro
@startuml
activate Participant
Participant -> Participant: Start Participant
deactivate Participant
Participant -> CLAMP_Runtime: Participant Registration
Participant <- CLAMP_Runtime: Participant Registration Ack
activate CLAMP_Runtime
loop over ControlAutomation LoopComposition Type Definitions
	CLAMP_Runtime -> CLAMP_Runtime: Collect ControlAutomation LoopComposition Element Type Definitions and\nCommon Property Values for\nParticipant Type of this Participant
end
deactivate CLAMP_Runtime
Participant <- CLAMP_Runtime: Participant Update\n[ControlAutomation LoopComposition Element Type Definitions and\nCommon Property Values for\nParticipant Type of Participant]
activate Participant
Participant -> Participant: Store ControlAutomation LoopComposition Element Type Definitions and\nCommon Property Values
Participant -> CLAMP_Runtime: Participant Update Ack
deactivate Participant

...

PlantUML Macro
@startuml
Participant -> CLAMP_Runtime: Participant Deregistration
Participant <- CLAMP_Runtime: Participant Deregistration Ack
Participant -> Participant: Shutdown Participant

...

Automation Composition Priming and De-Priming

When a control loop an Automation Composition is primed, the portion of the Control Loop Automation Composition Type Definition and Common Property values for the participants of each participant type mentioned in the Control Loop Automation Composition Definition are sent to the participants.

...

PlantUML Macro
@startuml
Commissioning_REST -> CLAMP_Runtime: Prime ControlAutomation LoopComposition Type Defintions and\nset values of Common Properties
activate CLAMP_Runtime
loop over Participant Types in ControlAutomation LoopComposition Type Definition
	CLAMP_Runtime -> CLAMP_Runtime: Collect ControlAutomation LoopComposition Element Type Definitions and\nCommon Property Values for Participant Type
end
Participant <- CLAMP_Runtime: Participant Update\n[ControlAutomation LoopComposition Element Type Definitions and\nCommon Property Values for Participant Types]
deactivate CLAMP_Runtime
activate Participant
Participant -> Participant: Store ControlAutomation LoopComposition Element Type Definitions and\nCommon Property Values
Participant -> CLAMP_Runtime: Participant Update Ack\n[from each Participant mentioned in Participant Update message]
deactivate Participant


When a control loop an Automation Composition is de-primed, the portion of the Control Loop Automation Composition Type Definition and Common Property values for the participants of each participant type mentioned in the Control Loop Automation Composition Definition are deleted on participants.

...

PlantUML Macro
@startuml
Commissioning_REST -> CLAMP_Runtime: De-Prime ControlAutomation LoopComposition Type Definition
alt ControlAutomation LoopComposition Instances exist for ControlAutomation LoopComposition Type
	Commissioning_REST <- CLAMP_Runtime: Cannot decommission ControlAutomation LoopComposition Type Definition
else No ControlAutomation LoopComposition Instances exist for ControlAutomation LoopComposition Type
	Participant <- CLAMP_Runtime: Participant Update\n[Remove ControlAutomation LoopComposition Element Definitions\nfrom Participants in ControlAutomation LoopComposition]
	activate Participant
	Participant -> Participant: Delete ControlAutomation LoopComposition Element\nType Definitions and\nCommon Property Values
	Participant -> CLAMP_Runtime: Participant Update Ack [from each Participant mentioned in Participant Update message]
	deactivate Participant
end

...

Automation Composition Update

Control Loop Automation Composition Update handles creation, change, and deletion of control loops Automation Compositions on participants. Change of control loops Automation Compositions uses a semantic versioning approach and follow follows the semantics described on the page TOSCA Defined Control LoopsAutomation Compositions: Architecture and Design#4.1ControlLoopVersionManagement1ACMVersionManagement.


PlantUML Macro
@startuml
Participant <- CLAMP_Runtime: ControlAutomation LoopComposition Update\n[to all Participants in ControlAutomation LoopComposition]
Participant -> CLAMP_Runtime: ControlAutomation LoopComposition Update Ack [from each Participant in ControlAutomation LoopComposition]


The handling of a ControlLoopUpdate an ACMUpdate message in each participant is as shown below.

...

PlantUML Macro
@startuml

(*) --> "Process Update Message"

if "All ControlAutomation LoopComposition Elements with my Participant ID processed?" then
  --> [yes] "Send Update Ack Message"
  --> (*)
else
  --> [no] "Process next ControlAutomation LoopComposition Element with my ID"
  if "New ControlAutomation LoopComposition Element?" then
	--> [yes] "Create ControlAutomation LoopComposition Element"
	--> "Set ControlAutomation LoopComposition Element to state UNINITIALISED"
	--> "Order Initiation of ControlAutomation LoopComposition Element"
	--> "Pass Parameters to ControlAutomation LoopComposition Element"
	--> "Wait for Initiation to complete"
	if "ControlAutomation LoopComposition Element Initiation?" then
      --> [success] "Record Success for Update Ack message"
      --> "Process Update Message"
    else
      --> [fail] "Delete ControlAutomation LoopComposition Element"
      --> "Record Error for Update Ack message"
      --> "Process Update Message"
    endif
  else
  	--> [no] "Check ControlAutomation LoopComposition Element State"
  endif
  if "RUNNING and ControlAutomation LoopComposition Version change != patch?" then
	--> [true] "Record Error for Update Ack message"
    --> "Process Update Message"
  else
  	[false] if "PASSIVE and ControlAutomation LoopComposition Version change == major?" then
      --> [true] "Record Error for Update Ack message"
      --> "Process Update Message"
  else
	--> [false] "Pass Changed Parameters to ControlAutomation LoopComposition Element"
	--> "Wait for reconfiguration to complete"
    if "ControlAutomation LoopComposition Element Reconfiguration?" then
      --> [success] "Record Success for Update Ack message"
      --> "Process Update Message"
    else
      --> [fail] "Roll back reconfiguration"
      --> "Record Error for Update Ack message"
      --> "Process Update Message"
    endif
  endif
endif

@enduml

...

Automation Composition State Change

This dialogue is used to change the state of Control Loops Automation Compositions and their Control Loop Automation Composition Elements. the CLAMP Runtime sends a Control Loop an Automation Composition State Change message on the control loop Automation Composition to all participants. Participants that have Control Loop Automation Composition Elements in that Control Loop Automation Composition attempt an update on the state of the control loop Automation Composition elements they have for that control loopAutomation Composition, and report the result back.

The startPhase in the Definition of TOSCA fundamental Control Loop Automation Composition Types is particularly important in control loop Automation Composition state changes because sometime sometimes the user wishes to control the order in which the state changes in Control Loop Automation Composition Elements in a control loopan Automation Composition. In-state changes from UNITITIALISED → PASSIVE and from PASSIVE → RUNNING, control loop Automation Composition elements are started in increasing order of their startPhase. In-state changes from RUNNING → PASSIVE and from PASSIVE → UNITITIALISED, control loop Automation Composition elements are started in decreasing order of their startPhase.

The CLAMP runtime controls the state change process described in the diagram below. The CLAMP runtime sends a Control Loop an Automation Composition State Change message on DMaaP to all participants in a particular Start Phase so, in each state change multiple Control Loop Automation Composition State Change messages are sent, one for each Start Phase in the control loopAutomation Composition. If more than one Control Loop Automation Composition Element has the same Start Phase, those Control Loop Automation Composition Elements receive the same Control Loop Automation Composition State Change message from DMaaP and start in parallel.

The Participant reads each State Change Message it sees on DMaaP. If the Start Phase on the Control Loop Automation Composition State Change message matches the Start Phase of the Control Loop Automation Composition Element, the participant processes the State Change message. Otherwise, the participant ignores the message.

...

PlantUML Macro
@startuml
activate CLAMP_Runtime
CLAMP_Runtime -> CLAMP_Runtime: Build an ordered list of the Start Phases in the ControlAutomation LoopComposition Instance
deactivate CLAMP_Runtime

alt "State Change UNITIALISED_to_PASSIVE or PASSIVE_to_RUNNING"
  loop over Start Phases list in increasing order 
    CLAMP_Runtime -> Participant: ControlAutomation LoopComposition State Change\n[to all Participants in ControlAutomation LoopComposition with this Start Phase]
    CLAMP_Runtime -> CLAMP_Runtime: Asynchronously wait for answers from Participants
    CLAMP_Runtime <- Participant: ControlAutomation LoopComposition State Change Ack [from each Participant in this Start Phase of ControlAutomation LoopComposition]
    alt "State Change Ack reports success"
      CLAMP_Runtime -> CLAMP_Runtime: Log success
    else "State Change Ack reports an error"
      CLAMP_Runtime -> CLAMP_Runtime: Log error
      CLAMP_Runtime -> CLAMP_Runtime: Reset state of ControlAutomation Loop
Composition         CLAMP_Runtime -> CLAMP_Runtime: Abort State Change operation
    end 
  end
else "State Change RUNNING_to_PASSIVE or PASSIVE_to_UNITIALISED"
 loop over Start Phases list in decreasing order
    CLAMP_Runtime -> Participant: ControlAutomation LoopComposition State Change\n[to all Participants in ControlAutomation LoopComposition with this Start Phase]
    CLAMP_Runtime -> CLAMP_Runtime: Asynchronously wait for answers from Participants
    CLAMP_Runtime <- Participant: ControlAutomation LoopComposition State Change Ack [from each Participant in this Start Phase of ControlAutomation LoopComposition]
    alt "State Change Ack reports success"
      CLAMP_Runtime -> CLAMP_Runtime: Log success
    else "State Change Ack reports an error"
      CLAMP_Runtime -> CLAMP_Runtime: Log error
      CLAMP_Runtime -> CLAMP_Runtime: Reset state of ControlAutomation Loop
Composition         CLAMP_Runtime -> CLAMP_Runtime: Abort State Change operation
    end 
  end
end

CLAMP_Runtime -> CLAMP_Runtime: Set overall state of Automation ControlComposition Loop
@enduml


The handling of a ControlLoopStateChange an ACMStateChange message in each participant is as shown below.

...

PlantUML Macro
@startuml

(*) --> "Process State Change Message"

if "All ControlAutomation LoopComposition Elements with my Participant ID processed?" then
  --> [yes] "Send State Change Ack Message"
  --> (*)
else
  --> [no] "Process next ControlAutomation LoopComposition Element with my ID"
  if "State Change Message Start Phase equals ControlAutomation LoopComposition Element start phase" then
    [true] if "Current State is RUNNING?" then
      [true] if "Change to PASSIVE?" then
      --> [true] "Change ControlAutomation LoopComposition Element to state PASSIVE"
      --> "Wait for RUNNING->PASSIVE State Change to complete"
      if "State Change?" then
        --> [success] "Record Success for State Change Ack message"
        --> "Process State Change Message"
      else
        --> [fail] "Record Error for State Change Ack message"
        --> "Process State Change Message"
      endif
      else
        --> [false] "Record Error for State Change Ack message"
        --> "Process State Change Message"
      endif
    else
      [false] if "Current State is PASSIVE?" then
        [true] if "Change to RUNNING?" then
          --> [true] "Change ControlAutomation LoopComposition Element to state RUNNING"
          --> "Wait for PASSIVE->RUNNING State Change to complete"
          if "State Change?" then
            --> [success] "Record Success for State Change Ack message"
            --> "Process State Change Message"
          else
            --> [fail] "Record Error for State Change Ack message"
            --> "Process State Change Message"
          endif
        else
          --> [false] "Record Error for State Change Ack message"
          --> "Process State Change Message"
        endif
      else
        --> [false] "Record Error for State Change Ack message"
        --> "Process State Change Message"
      endif
    endif
  else
    --> [false] "Skip ControlAutomation LoopComposition Element"
    --> "Process State Change Message"
endif

@enduml

...

Automation Composition Monitoring and Reporting

This dialogue is used as a heartbeat mechanism for participants, to monitor the status of Control Loop Automation Composition Elements, and to gather statistics on control loopsAutomation Compositions. The ParticipantStatus message is sent periodically by each participant. The reporting interval for sending the message is configurable.

...

PlantUML Macro
@startuml
Participant -> CLAMP_Runtime: Participant Status [periodically from each Participant in all ControlAutomation LoopsCompositions]

Messages

The CLAMP Control Loop Automation Composition Participant Protocol uses the following messages. The descriptions below give an overview of each message. For the precise definition of the messages, see the CLAMP code at: https://github.com/onap/policy-clamp/tree/master/models/src/main/java/org/onap/policy/clamp/controlloopACM/models/messages/dmaap/participant. All messages are carried on DMaaP.

MessageSourceTargetPurposeImportant FieldsField Descriptions
ParticipantRegisterParticipantCLAMP RuntimeParticipant registers with the CLAMP runtimeParticipantIdThe ID of this participant




ParticipantTypeThe type of the participant, ; maps to the capabilities of the participant in Control Loop Automation Composition Type Definitions

ParticipantRegisterAck

CLAMP RuntimeParticipantAcknowledgement Acknowledgment of Participant Registration

ParticipantIdThe ID of this participant
ParticipantTypeThe type of the participant, ; maps to the capabilities of the participant in Control Loop Automation Composition Type Definitions
ResultSuccess/Fail
MessageMessage A message indicating the reason for failure

ParticipantUpdateCLAMP RuntimeParticipantCLAMP Runtime sends Control Loop Automation Composition Element Definitions and Common Parameter Values to ParticipantsParticipantDefinitionUpdateMap

Map with Participant ID as its key, each value on the map is ControlLoopElementDefintionMapan ACMElementDefintionMap


ControlLoopElementDefintionMapACMElementDefintionMapList of ControlLoopElementDefinition ACMElementDefinition values for a particular participant, keyed by its Control Loop Automation Composition Element Definition ID
ControlLoopElementDefinitionACMElementDefinitionA ControlLoopElementToscaServiceTemplate An ACMElementToscaServiceTemplate containing the definition of the Control Loop Automation Composition Element and a CommonPropertiesMap with the values of the common property values for Control Loop Automation Composition Elements of this type
ControlLoopElementToscaServiceTemplateACMElementToscaServiceTemplateThe definition of the Control Loop Automation Composition Element in TOSCA
CommonPropertiesMapA <String, String> map indexed by the property name. Each map entry is the serialized value of the property, which can be deserialized into an instance of the type of the property.

ParticipantUpdateAck


Participant


CLAMP Runtime


Acknowledgement Acknowledgment of Participant Update


ParticipantIdThe ID of this participant
ParticipantTypeThe type of the participant, ; maps to the capabilities of the participant in Control Loop Automation Composition Type Definitions
ResultSuccess/Fail
MessageMessage A message indicating the reason for failure

ParticipantDeregisterParticipantCLAMP RuntimeParticipant deregisters with the CLAMP runtimeParticipantIdThe ID of this participant




ParticipantTypeThe type of the participant, ; maps to the capabilities of the participant in Control Loop Automation Composition Type Definitions

ParticipantDeregisterAck

CLAMP RuntimeParticipantAcknowledgement Acknowledgment of Participant DeegistrationDeregistration

ParticipantIdThe ID of this participant
ParticipantTypeThe type of the participant, ; maps to the capabilities of the participant in Control Loop Automation Composition Type Definitions
ResultSuccess/Fail
MessageMessage A message indicating the reason for failure

ControlLoopUpdateACMUpdateCLAMP RuntimeParticipantCLAMP Runtime sends Control Loop Automation Composition Element instances and Instance Specific Parameter Values for a Control Loop an Automation Composition Instance to ParticipantsControlLoopIdACMIdThe name and version of the Control LoopAutomation Composition
ParticipantUpdateMap

Map with Participant ID as its key, each value on the map is ControlLoopElementListan ACMElementList

ControlLoopElementListACMElementListList of ControlLoopElement ACMElement values for the Control LoopAutomation Composition
ControlLoopElementACMElementA ControlLoopElementAn ACMElement, which contains among other things a PropertiesMap with the values of the the property values for this Control Loop Automation Composition Element instance and a ToscaServiceTemplateFragment with extra concept definitions and instances that a participant may need.
PropertiesMapA <String, String> map indexed by the property name. Each map entry is the serialized value of the property, which can be deserialized into an instance of the type of the property.
ToscaServiceTemplateFragmentA well-formed TOSCA service template containing extra concept definitions and instances that a participant may need. For example, the Policy Participant may need policy type definitions or policy instances to be provided if they are not already stored in the Policy Framework.

ControlLoopUpdateACMUpdateAck

ParticipantCLAMP RuntimeAcknowledgement Acknowledgment of Control Loop Automation Composition Update

ParticipantIdThe ID of this participant
ParticipantTypeThe type of the participant, ; maps to the capabilities of the participant in Control Loop Automation Composition Type Definitions
ControlLoopIdACMIdThe name and version of the Control LoopAutomation Composition
ControlLoopResultACMResultHolds a Result and Message for the overall operation on the participant and a map of Result and Message fields for each Control Loop Automation Composition Element of the control loop Automation Composition on this participant
ResultSuccess/Fail
MessageMessage A message indicating the reason for failure

ControlLoopStateChangeACMStateChangeCLAMP RuntimeParticipantCLAMP Runtime asks Participants to change the state of a Control Loopan Automation CompositionACMIdControlLoopId

The name and version of the Control LoopAutomation Composition


currentStateThe current state of the Control LoopAutomation Composition
orderedStateThe state that the Control Loop Automation Composition should transition to
startPhaseThe start phase to which this ControLoopStateChange message applies

ControlLoopStateChangeACMStateChangeAck

ParticipantCLAMP RuntimeAcknowledgement Acknowledgment of Control Loop Automation Composition State Change

ParticipantIdThe ID of this participant
ParticipantTypeThe type of the participant, ; maps to the capabilities of the participant in Control Loop Automation Composition Type Definitions
ControlLoopIdACMIdThe name and version of the Control LoopAutomation Composition
startPhaseThe start phase to which this ControLoopStateChangeAck message applies
ControlLoopResultACMResultHolds a Result and Message for the overall operation on the participant and a map of Result and Message fields for each Control Loop Automation Composition Element of the control loop Automation Composition on this participant
ResultSuccess/Fail
MessageMessage A message indicating the reason for failure

ParticipantStatusReqCLAMP RuntimeParticipant



Request that the specified participants return a ParticipantStatus message immediatelyParticipantIdThe ID of this participant, if not specified, all participants respond.

ParticipantStatus






Participant






CLAMP Runtime






Periodic or on-demand report for heartbeat, Participant Status, Control Loop Automation Composition Status, and Control Loop Automation Composition Statistics






ParticipantId
The ID of this participant
ParticipantType
The type of the participant, ; maps to the capabilities of the participant in Control Loop Automation Composition Type Definitions
ParticipantDefinitionUpdateMap (returned in repsonse to ParticipantStatusReq only)
See ParticipantUpdate message above for the definition of this field
ParticipantStatus The current status of the participant for monitoring
ParticipantStatistics
Statistics on the participant such as up timeuptime, or messages processed. Can include participant specific data in a string blob that is opaque to CLAMP
ControlLoopInfoMapACMInfoMapA map of ControlLoopInfo ACMInfo types indexed by ControlLoopId ACMId, one entry for each control loop Automation Composition running on the participant
ControlLoopInfoACMInfoThe ControlLoopStatus ACMStatus and ControlLoopStatistics ACMStatistics for a given control loopAutomation Composition
ControlLoopStatusACMStatusThe current status of the control loop Automation Composition for monitoring
ACMStatisticsControlLoopStatistics
Statistics on the control loop Automation Composition such as up timeuptime, or messages processed. Can include participant specific data in a string blob that is opaque to CLAMP

...