Skip to content
This repository has been archived by the owner on Jun 13, 2022. It is now read-only.

Latest commit

 

History

History
56 lines (30 loc) · 4.86 KB

onboarding-skill.md

File metadata and controls

56 lines (30 loc) · 4.86 KB
Raw

onboarding-skill

Running

  • To start: npm run dev from this directory

The big picture

This component is shown as "Onboarding - CAR". The big picture

The state machine

This component uses xstate. The modelled state machine is shown below: The state machine

The machine is defined here.

From each state, invalid messages will be responded to (as long as they are parsable and contain a proper sender) with notUnderstood.

Developer's notes

How it works

A message is received via the message broker (AMQPClient -> MessageInterpreter) and converted into an event, which is then passed on to the main domain class AssetRepositoryOnboardingSkill. This loads a state from persistent storage, (according to the conversation id), into the state machine and applies the event to it, writing the state back to persistent store. The transition of the state machine causes messages to be sent. This mapping is specified in SkillStateMachineSpecification.

Tests

Unit Tests

  • Run unit tests using npm run test
  • Run unit tests with coverage with npm run coverage

Including integration tests

Test setup can be done with source ./integration-test-setup.

  • To run integration tests as well: npm run test-with-integration
  • To run coverage with integration tests: npm run coverage-with-integration

Test cleanup: ./integration-test-teardown

Writing your own skill

You may use the onboarding skill as a template to write your own skill.

  • The first thing to do is to create a state chart as above.

    About the notation: The state chart notation is described in this paper: States are shown as rectangles with rounded edges, final states have double borders. Transistions are shown by arrows. The notation on the arrows is: event-to-move-out-of-state (condition-under-which-to-execute-transition)/transition-action-to-be-executed-while-transitioning. Actions can also be triggered on entering or exiting states. This is indicated in them being written inside the state "rectangle" in small font. Events received from other parties are concatenated as following: {message type}FROM{sender role} (all caps). When an external rest service is called it needs to be modelled as a service with its own sub-states.

  • Understand how the above diagram maps to its skill state machine specification created using xstate. This way you create your own MySkillStateMachineSpecification.ts, replacing the one for the onboarding skill in the corresponding folder.

  • Create a MySkillActionMap.ts containing the code for actions to be performed when the state machine moves through the states. These actions can be messages sent to other parties in an AAS interaction or the invocation of external services. The methods you provide here depend on your scenario. This class should make use of a MyExternalRestServiceCaller.ts to make the actual calls to the external services as well as a MyAasMessageDispatcher.ts that uses the message sender to send messages via the message broker. MyAasMessageDispatcher.ts needs to implement at least the interface IAasMessageDispatcher. You may have a look at the corresponding files for the onboarding skill and replace them.

  • Finally, provide a MyInitializer.ts that provides these two communication classes and a configuration object that is later placed in the context for your state machine to use. This configuration object contains configuration properties your state machine requires. You may have a look at the corresponding file for the onboarding skill and replace it.

Please note that the state machine is an interation state machine. It deals with events (incoming messages or results of REST calls) and performs actions (sending messages, making REST calls) thereby moving to a new state. It does not know about business logic unrelated to messaging. Only model the interaction in it. If you have a scenario with multiple AAS services (with skills in them) communicating with each other you will need to perform this process for all involved parties. Each will result in a microservice that is deployed as a skill in each instance of the AAS services involved in the interaction.