summaryrefslogtreecommitdiffstats
path: root/docs/clamp/acm/acm-participant-guide.rst
blob: b4ca885dd5bf0b6c902cd5554ba67ece16e1625f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. Copyright (c) Nordix Foundation.  All rights reserved.

.. _acm-participant-guide-label:

Participant developer guide
###########################

.. contents::
    :depth: 4

The ACM runtime delegates the user requests to the participants for performing the actual operations.
Hence the participant module in ACM is implemented adhering to a list of ACM protocols along with their own functional logic.
It works in a contract with the Participant Intermediary module for communicating with ACM-R.
This guide explains the design considerations for a new participant implementation in ACM.

Please refer the following section for a detailed understanding of Inbound and outbound messages a participant interacts with.

.. toctree::
   :maxdepth: 2

   design-impl/participants/participants

Design considerations for a participant
---------------------------------------

In ONAP, the ACM-runtime and participant modules are implemented in Java spring boot. The participant Intermediary module
which is added as a maven dependency to the participants has the default implementations available for listening the kafka
events coming in from the ACM-runtime, process them and delegate them to the appropriate handler class. Similarly the
Intermediary module also has the publisher class implementations for publishing events back from the participants to the ACM-runtime.

Hence the new participants has to have this Participant Intermediary module as a dependency and should:

* Configure SpringBoot to scan the components located into the package "org.onap.policy.clamp.acm.participant.intermediary".
* Implement the following interfaces from the Participant Intermediary.
* Provide the following mandatory properties in order to make the participant work in synchronisation with ACM-runtime.

The participant application should be provided with the following Intermediary parameter values in the application properties
and the same is configured for the 'ParticipantIntermediaryParameters' object in the code.

1. participantId - A unique participant UUID that is used by the runtime to identify the participant.
2. ReportingTimeIntervalMs - Time inertval the participant should report the status/heartbeat to the runtime.
3. clampAutomationCompositionTopics - This property takes in the kafka topic names and servers for the intermediary module to use.
   These values should be provided for both source and sink configs.
   (**Note**: In order to avoid a connection to Kafka when Unit Tests are running, set topicCommInfrastructure: NOOP in properties file for tests).
   The following example shows the topic parameters set for using Kafka.

.. code-block:: bash

    clampAutomationCompositionTopics:
          topicSources:
            -
              topic: POLICY-ACRUNTIME-PARTICIPANT
              servers:
                - ${topicServer:localhost}:9092
              topicCommInfrastructure: kafka
              fetchTimeout: 15000
          topicSinks:
            -
              topic: POLICY-ACRUNTIME-PARTICIPANT
              servers:
                - ${topicServer:localhost}:9092
              topicCommInfrastructure: kafka

4. participantSupportedElementTypes - This property takes a list of typeName and typeVersion fields to define the types of AC elements the participant deals with.
   These are user defined name and version and the same should be defined for the AC elements that are included in the TOSCA based AC definitions.

.. code-block:: bash

    participantSupportedElementTypes:
      -
        typeName: org.onap.policy.clamp.acm.PolicyAutomationCompositionElement
        typeVersion: 1.0.0

Interfaces to Implement
-----------------------
AutomationCompositionElementListener:
  Every participant should implement a handler class that implements the AutomationCompositionElementListener interface
  from the Participant Intermediary. The intermediary listener class listens for the incoming events from the ACM-runtime
  and invoke the handler class implementations for various operations. This class implements the methods for deploying,
  undeploying, locking, unlocking , deleting, updating, migrating, priming, depriming requests that are coming from the ACM-runtime.
  The methods are as follows.

.. code-block:: java

  1. void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
  2. void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
  3. void lock(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
  4. void unlock(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
  5. void delete(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
  6. void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement, InstanceElementDto instanceElementUpdated) throws PfModelException;
  7. void prime(CompositionDto composition) throws PfModelException;
  8. void deprime(CompositionDto composition) throws PfModelException;
  9. void handleRestartComposition(CompositionDto composition, AcTypeState state) throws PfModelException;
  10. void handleRestartInstance(CompositionElementDto compositionElement, InstanceElementDto instanceElement, DeployState deployState, LockState lockState) throws PfModelException;
  11. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException;

These method from the interface are implemented independently as per the user requirement. These methods after handling the
appropriate requests should also invoke the intermediary's publisher apis to notify the ACM-runtime with the acknowledgement events.

ParticipantParameters:
  Every participant should implement a properties class that contains the values of all Intermediary parameter properties.
  This class implements the method getIntermediaryParameters that returns 'ParticipantIntermediaryParameters' object. The method is as follows.

.. code-block:: java

  ParticipantIntermediaryParameters getIntermediaryParameters()

Abstract class AcElementListenerV1
----------------------------------
This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener implemented in 7.1.0 version.
So developers can decide to align to new functionality later. Any new functionality in the future will be wrapped by this class.

The Abstract class AcElementListenerV1 supports the follow methods.

.. code-block:: java

  1. void undeploy(UUID instanceId, UUID elementId) throws PfModelException;
  2. void deploy(UUID instanceId, AcElementDeploy element, Map<String, Object> inProperties) throws PfModelException;
  3. void lock(UUID instanceId, UUID elementId) throws PfModelException;
  4. void unlock(UUID instanceId, UUID elementId) throws PfModelException;
  5. void delete(UUID instanceId, UUID elementId) throws PfModelException;
  6. void update(UUID instanceId, AcElementDeploy element, Map<String, Object> inProperties) throws PfModelException;
  7. void prime(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList) throws PfModelException;
  8. void deprime(UUID compositionId) throws PfModelException;
  9. void handleRestartComposition(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList, AcTypeState state) throws PfModelException;
  10. void handleRestartInstance(UUID instanceId, AcElementDeploy element, Map<String, Object> properties, DeployState deployState, LockState lockState) throws PfModelException;
  11. void migrate(UUID instanceId, AcElementDeploy element, UUID compositionTargetId, Map<String, Object> properties) throws PfModelException;

**Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used.
Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, handleRestartComposition and handleRestartInstance.

Un example of AutomationCompositionElementHandler implemented in 7.1.0 version and how to use AcElementListenerV1 abstract class:

.. code-block:: java

  @Component
  @RequiredArgsConstructor
  public class AutomationCompositionElementHandler implements AutomationCompositionElementListener {

    private final ParticipantIntermediaryApi intermediaryApi;
    private final otherService otherService;
    ..............................
  }

  @Component
  public class AutomationCompositionElementHandler extends AcElementListenerV1 {

    private final OtherService otherService;

    public AutomationCompositionElementHandler(ParticipantIntermediaryApi intermediaryApi, OtherService otherService) {
        super(intermediaryApi);
        this.otherService = otherService;
    }
    ..............................
  }



A second example:

.. code-block:: java

  @Component
  public class AutomationCompositionElementHandler implements AutomationCompositionElementListener {

    @Autowired
    private ParticipantIntermediaryApi intermediaryApi;

    @Autowired
    private otherService otherService;
    ..............................
  }

  @Component
  public class AutomationCompositionElementHandler extends AcElementListenerV1 {

    @Autowired
    private otherService otherService;

    public AutomationCompositionElementHandler(ParticipantIntermediaryApi intermediaryApi) {
        super(intermediaryApi);
    }
    ..............................
  }

Abstract class AcElementListenerV2
----------------------------------
This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener from new releases.
Any new functionality in the future will be wrapped by this class.

**Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used.
Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, handleRestartComposition and handleRestartInstance.


Methods: deploy, undeploy, lock, unlock and delete
  compositionElement:
    ======================  =======================================
     **field**                       **description**
    ======================  =======================================
     compositionId           composition definition Id
     elementDefinitionId     composition definition element Id
     inProperties            composition definition in-properties
     outProperties           composition definition out-properties
    ======================  =======================================
  instanceElement:
    ==============================  ===========================
     **field**                       **description**
    ==============================  ===========================
     instanceId                      instance id
     elementId                       instance element id
     toscaServiceTemplateFragment    policies and policy types
     inProperties                    instance in-properties
      outProperties                  instance out-properties
    ==============================  ===========================

Method: update
  compositionElement:
    ======================  =======================================
     **field**                       **description**
    ======================  =======================================
     compositionId           composition definition Id
     elementDefinitionId     composition definition element Id
     inProperties            composition definition in-properties
     outProperties           composition definition out-properties
    ======================  =======================================
  instanceElement:
    ==============================  ================================================
     **field**                       **description**
    ==============================  ================================================
     instanceId                      instance id
     elementId                       instance element id
     toscaServiceTemplateFragment
     inProperties                    instance in-properties **(before the update)**
      outProperties                  instance out-properties
    ==============================  ================================================
  instanceElementUpdated:
    ==============================  ======================================
     **field**                       **description**
    ==============================  ======================================
     instanceId                      instance id
     elementId                       instance element id
     toscaServiceTemplateFragment
     inProperties                    instance in-properties **(updated)**
      outProperties                  instance out-properties
    ==============================  ======================================

Methods: prime, deprime
  composition:
    ======================  ===================================================================
     **field**                       **description**
    ======================  ===================================================================
     compositionId           composition definition Id
     inProperties            composition definition in-properties for each definition element
     outProperties           composition definition out-properties for each definition element
    ======================  ===================================================================

Method: migrate
  compositionElement:
    ======================  =======================================
     **field**                       **description**
    ======================  =======================================
     compositionId           composition definition Id
     elementDefinitionId     composition definition element Id
     inProperties            composition definition in-properties
     outProperties           composition definition out-properties
    ======================  =======================================
  compositionElementTarget:
    ======================  ==============================================
     **field**                       **description**
    ======================  ==============================================
     compositionId           composition definition target Id
     elementDefinitionId     composition definition target element Id
     inProperties            composition definition target in-properties
     outProperties           composition definition target out-properties
    ======================  ==============================================
  instanceElement:
    ==============================  ===================================================
     **field**                       **description**
    ==============================  ===================================================
     instanceId                      instance id
     elementId                       instance element id
     toscaServiceTemplateFragment
     inProperties                    instance in-properties **(before the migration)**
      outProperties                  instance out-properties
    ==============================  ===================================================
  instanceElementMigrate:
    ==============================  ======================================
     **field**                       **description**
    ==============================  ======================================
     instanceId                      instance id
     elementId                       instance element id
     toscaServiceTemplateFragment
     inProperties                    instance in-properties **(updated)**
      outProperties                  instance out-properties
    ==============================  ======================================

APIs to invoke
--------------
ParticipantIntermediaryApi:
  The participant intermediary api has the following methods that can be invoked from the participant for the following purposes.

  #. The requested operations are completed in the handler class and the ACM-runtime needs to be notified.
  #. Collect all instances data.
  #. Send out Properties to ACM-runtime.

  The methods are as follows:

This following methods could be invoked to fetch data during each operation in the participant.

.. code-block:: java

  1.  Map<UUID, AutomationComposition> getAutomationCompositions();
  2.  AutomationComposition getAutomationComposition(UUID instanceId);
  3.  AutomationCompositionElement getAutomationCompositionElement(UUID instanceId, UUID elementId);
  4.  Map<UUID, Map<ToscaConceptIdentifier, AutomationCompositionElementDefinition>> getAcElementsDefinitions();
  5.  Map<ToscaConceptIdentifier, AutomationCompositionElementDefinition> getAcElementsDefinitions(UUID compositionId);
  6.  AutomationCompositionElementDefinition getAcElementDefinition(UUID compositionId, ToscaConceptIdentifier elementId);

This following methods are invoked to update the outProperties during each operation in the participant.

.. code-block:: java

  1.  void sendAcDefinitionInfo(UUID compositionId, ToscaConceptIdentifier elementId, Map<String, Object> outProperties);
  2.  void sendAcElementInfo(UUID instanceId, UUID elementId, String useState, String operationalState, Map<String, Object> outProperties);

This following methods are invoked to update the AC element state or AC element definition state after each operation is completed in the participant.

.. code-block:: java

  1.  void updateAutomationCompositionElementState(UUID instanceId, UUID elementId, DeployState deployState, LockState lockState, StateChangeResult stateChangeResult, String message);
  2.  void updateCompositionState(UUID compositionId, AcTypeState state, StateChangeResult stateChangeResult, String message);

In/Out composition Properties
-----------------------------
The 'Common Properties' could be created or updated by ACM-runtime.
Participants will receive that Properties during priming and deprime events by CompositionDto class.

.. code-block:: java

  @Override
  public void prime(CompositionDto composition) throws PfModelException {
      for (var entry : composition.inPropertiesMap().entrySet()) {
          var elementDefinitionId = entry.getKey();
          var inProperties = entry.getValue();
          .......
      }
      .......
  }

Participants will receive the Properties related to the element definition by CompositionElementDto class.

.. code-block:: java

  @Override
  public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException {
      var inCompositionProperties = compositionElement.inProperties();
      .......
  }

The 'Out Properties' could be created or updated by participants. ACM-runtime will receive that Properties during ParticipantStatus event.
The participant can trigger this event using the method sendAcDefinitionInfo.

Participants will receive that outProperties during priming and deprime events by CompositionDto class.

.. code-block:: java

  @Override
  public void deprime(CompositionDto composition) throws PfModelException {
      for (var entry : composition.outPropertiesMap().entrySet()) {
          var elementDefinitionId = entry.getKey();
          var outProperties = entry.getValue();
          .......
      }
      .......
  }

Participants will receive the outProperties related to the element definition by CompositionElementDto class.

.. code-block:: java

  @Override
  public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException {
      var outCompositionProperties = compositionElement.outProperties();
      .......
  }

Is allowed to the participant to read all In/Out Properties of all compositions handled by the participant using the method getAcElementsDefinitions.
The following code is an example how to update the property 'myProperty' and send to ACM-runtime:

.. code-block:: java

  var acElement = intermediaryApi.getAcElementDefinition(compositionId, elementDefinitionId);
  var outProperties = acElement.getOutProperties();
  outProperties.put("myProperty", myProperty);
  intermediaryApi.sendAcDefinitionInfo(compositionId, elementDefinitionId, outProperties);

In/Out instance Properties
--------------------------
  The 'In/Out Properties' are stored into the instance elements, so each element has its own In/Out Properties.

  The 'In Properties' could be created or updated by ACM-runtime. Participants will receive that Properties during deploy and update events.

  The 'Out Properties' could be created or updated by participants. ACM-runtime will receive that Properties during ParticipantStatus event.
  The participant can trigger this event using the method sendAcElementInfo. The 'useState' and 'operationalState' can be used as well.
  The 'Out Properties' could be **cleaned**:

  * by the participant using the method sendAcElementInfo
  * by intermediary automatically during deleting of the instance
  * by an update when the instance is in UNDEPLOYED state (changing the elementId)

  The 'Out Properties' will be **not cleaned** by intermediary:

  * during DEPLOIYNG (Out Properties will be take from last changes matching by elementId)
  * during UNDEPLOING
  * during LOCKING/UNLOCKING
  * during UPDATING/MIGRATING

Participants will receive the in/out instance Properties related to the element by InstanceElementDto class.

.. code-block:: java

  @Override
  public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException {
      var inProperties = instanceElement.inProperties();
      var outProperties = instanceElement.outProperties();
      .......
  }

Is allowed to the participant to read all In/Out Properties and state of all instances handled by the participant using the method getAutomationCompositions.
The following code is an example how to update the property 'myProperty' and send to ACM-runtime:

.. code-block:: java

  var acElement = intermediaryApi.getAutomationCompositionElement(instanceId, elementId);
  var outProperties = acElement.getOutProperties();
  outProperties.put("myProperty", myProperty);
  intermediaryApi.sendAcElementInfo(instanceId, elementId, acElement.getUseState(), acElement.getOperationalState(), outProperties);

**Note**: In update and migrate Participants will receive the instance Properties before the merge (instanceElement) and the instance Properties merged (instanceElementUpdated / instanceElementMigrate).

Restart scenario
----------------
  Restart methods handle the scenario when participant shut down and restart.
  During RESTARTING, compositions and instances will be stored in participant memory with In/Out Properties, 'useState' and 'operationalState'.
  The method handleRestartComposition will be called for each composition and will be present the 'state' at the time the participant shut down.
  The method handleRestartInstance will be called for each instance element and will be present the 'deployState' and the 'lockState' at the time the participant shut down.

In ONAP, the following participants are already implemented in java spring boot for various requirements. The maven modules
can be referred here:

  * `HTTP participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-http>`_.
  * `Kubernetes participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-kubernetes>`_.
  * `Policy participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-policy>`_.
  * `A1PMS participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-a1pms>`_.
  * `Kserve participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-kserve>`_.

Example of Implementation
-------------------------

This following code is an example of My First Participant:
  * Application
  * Parameters
  * Handler

The Application class is configured to add the "org.onap.policy.clamp.acm.participant.intermediary" package in SpringBoot component scanning.

.. code-block:: java

  @SpringBootApplication
  @ComponentScan({
    "org.onap.policy.clamp.acm.participant.myfirstparticipant",
    "org.onap.policy.clamp.acm.participant.intermediary"
  })
  @ConfigurationPropertiesScan("org.onap.policy.clamp.acm.participant.myfirstparticipant.parameters")
  public class MyFirstParticipantApplication {

    public static void main(String[] args) {
      SpringApplication.run(Application.class, args);
    }
  }

The Participant Parameters class implements the mandatory interface ParticipantParameters.
It could contains additional parameters.

.. code-block:: java

  @Validated
  @Getter
  @Setter
  @ConfigurationProperties(prefix = "participant")
  public class ParticipantSimParameters implements ParticipantParameters {

    @NotBlank
    private String myparameter;

    @NotNull
    @Valid
    private ParticipantIntermediaryParameters intermediaryParameters;
  }

The following example shows the topic parameters and the additional 'myparameter'.

.. code-block:: bash

  participant:
    myparameter: my parameter
    intermediaryParameters:
      reportingTimeIntervalMs: 120000
      description: Participant Description
      participantId: 101c62b3-8918-41b9-a747-d21eb79c6c90
      clampAutomationCompositionTopics:
        topicSources:
          - topic: POLICY-ACRUNTIME-PARTICIPANT
            servers:
              - ${topicServer:localhost}:9092
            topicCommInfrastructure: kafka
            fetchTimeout: 15000
        topicSinks:
          - topic: POLICY-ACRUNTIME-PARTICIPANT
            servers:
              - ${topicServer:localhost}:9092
            topicCommInfrastructure: kafka
      participantSupportedElementTypes:
        -
          typeName: org.onap.policy.clamp.acm.MyFirstAutomationCompositionElement
          typeVersion: 1.0.0


The following example shows the Handler implementation and how could be the implemented the mandatory notifications.

.. code-block:: java

  @Component
  public class AutomationCompositionElementHandler extends AcElementListenerV2 {

    @Override
    public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement)
            throws PfModelException {

        // TODO deploy process

        if (isDeploySuccess()) {
            intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
                instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR,
                "Deployed");
        } else {
            intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
                instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.FAILED,
                "Deploy failed!");
        }
    }

    @Override
    public void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement)
            throws PfModelException {

        // TODO undeploy process

        if (isUndeploySuccess()) {
            intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
                instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR,
                    "Undeployed");
        } else {
            intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
                instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.FAILED,
                    "Undeploy failed!");
        }
    }

    @Override
    public void lock(CompositionElementDto compositionElement, InstanceElementDto instanceElement)
            throws PfModelException {

        // TODO lock process

        if (isLockSuccess()) {
            intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
                instanceElement.elementId(), null, LockState.LOCKED, StateChangeResult.NO_ERROR, "Locked");
        } else {
            intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
                instanceElement.elementId(), null, LockState.UNLOCKED, StateChangeResult.FAILED, "Lock failed!");
        }
    }

    @Override
    public void unlock(CompositionElementDto compositionElement, InstanceElementDto instanceElement)
            throws PfModelException {

        // TODO unlock process

        if (isUnlockSuccess()) {
            intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
                instanceElement.elementId(), null, LockState.UNLOCKED, StateChangeResult.NO_ERROR, "Unlocked");
        } else {
            intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
                instanceElement.elementId(), null, LockState.LOCKED, StateChangeResult.FAILED, "Unlock failed!");
        }
    }

    @Override
    public void delete(CompositionElementDto compositionElement, InstanceElementDto instanceElement)
            throws PfModelException {

        // TODO delete process

        if (isDeleteSuccess()) {
            intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
                instanceElement.elementId(), DeployState.DELETED, null, StateChangeResult.NO_ERROR, "Deleted");
        } else {
            intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
                instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.FAILED,
                "Delete failed!");
        }
    }

    @Override
    public void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement,
                       InstanceElementDto instanceElementUpdated) throws PfModelException {

        // TODO update process

        if (isUpdateSuccess()) {
            intermediaryApi.updateAutomationCompositionElementState(
                instanceElement.instanceId(), instanceElement.elementId(),
                DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Updated");
        } else {
            intermediaryApi.updateAutomationCompositionElementState(
                instanceElement.instanceId(), instanceElement.elementId(),
                DeployState.DEPLOYED, null, StateChangeResult.FAILED, "Update failed!");
        }
    }

    @Override
    public void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget,
                        InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate)
        throws PfModelException

        // TODO migrate process

        if (isMigrateSuccess()) {
            intermediaryApi.updateAutomationCompositionElementState(
                instanceElement.instanceId(), instanceElement.elementId(),
                DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migrated");
        } else {
            intermediaryApi.updateAutomationCompositionElementState(
                instanceElement.instanceId(), instanceElement.elementId(),
                DeployState.DEPLOYED, null, StateChangeResult.FAILED, "Migrate failed!");
        }
    }

    @Override
    public void prime(CompositionDto composition) throws PfModelException {

        // TODO prime process

        if (isPrimeSuccess()) {
            intermediaryApi.updateCompositionState(composition.compositionId(),
                AcTypeState.PRIMED, StateChangeResult.NO_ERROR, "Primed");
        } else {
            intermediaryApi.updateCompositionState(composition.compositionId(),
                AcTypeState.COMMISSIONED, StateChangeResult.FAILED, "Prime failed!");
        }
    }

    @Override
    public void deprime(CompositionDto composition) throws PfModelException {

        // TODO deprime process

        if (isDeprimeSuccess()) {
            intermediaryApi.updateCompositionState(composition.compositionId(), AcTypeState.COMMISSIONED,
                StateChangeResult.NO_ERROR, "Deprimed");
        } else {
            intermediaryApi.updateCompositionState(composition.compositionId(), AcTypeState.PRIMED,
                StateChangeResult.FAILED, "Deprime failed!");
        }
    }


    @Override
    public void handleRestartComposition(CompositionDto composition, AcTypeState state) throws PfModelException {

         // TODO restart process

        switch (state) {
            case PRIMING -> prime(composition);
            case DEPRIMING -> deprime(composition);
            default -> intermediaryApi
                .updateCompositionState(composition.compositionId(), state, StateChangeResult.NO_ERROR, "Restarted");
        }
    }

    @Override
    public void handleRestartInstance(CompositionElementDto compositionElement, InstanceElementDto instanceElement,
        DeployState deployState, LockState lockState) throws PfModelException {

         // TODO restart process

        if (DeployState.DEPLOYING.equals(deployState)) {
            deploy(compositionElement, instanceElement);
            return;
        }
        if (DeployState.UNDEPLOYING.equals(deployState)) {
            undeploy(compositionElement, instanceElement);
            return;
        }
        if (DeployState.UPDATING.equals(deployState)) {
            update(compositionElement, instanceElement, instanceElement);
            return;
        }
        if (DeployState.DELETING.equals(deployState)) {
            delete(compositionElement, instanceElement);
            return;
        }
        if (LockState.LOCKING.equals(lockState)) {
            lock(compositionElement, instanceElement);
            return;
        }
        if (LockState.UNLOCKING.equals(lockState)) {
            unlock(compositionElement, instanceElement);
            return;
        }
        intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
            instanceElement.elementId(), deployState, lockState, StateChangeResult.NO_ERROR, "Restarted");
    }


AC Element states in failure scenarios
--------------------------------------

During the execution of any state change order, there is always a possibility of failures or exceptions that can occur in the participant.
This can be tackled by the followed approaches.

The participant implementation can handle the exception and revert back the appropriate AC element state, by invoking the
'updateAutomationCompositionElementState' api from the participant intermediary.

Alternatively, the participant can simply throw a PfModelException from its implementation which will be handled by the participant intermediary.
The intermediary handles this exception and rolls back the AC element to its previous state with the appropriate stateChange Result.
Please refer the following table for the state change reversion that happens in the participant intermediary for the AC elements.

================== ==================
**Error Scenario** **State Reverted**
================== ==================
Prime fails        Commissoned

Deprime fails      Primed

Deploy fails       Undeployed

Undeploy fails     Deployed

Update fails       Deployed

Delete fails       Undeployed

Lock fails         Unlocked

Unlock fails       Locked

Migrate fails      Deployed
================== ==================

Considering the above mentioned behavior of the participant Intermediary, it is the responsibility of the developer to tackle the
error scenarios in the participant with the suitable approach.

Tips:
If the participant tries to undeploy an element which doesn’t exist in the system any more (due to various other external factors),
it could update the element state to ‘undeployed’ using the Intermediary api.