Open Beta

Create the choreography using the CLI

AMPLIFY Choreography text-based command line interface (CLI) is used to create the choreography. Choreography allows the publishing service to execute the service and publish the output without having to be aware of the subscribing services. The subscribing services listen for new publish events and receive the update.

Before you start

$ amplify ace choreography list

Objectives

Use CLI commands to create a choreography that you can then define with JSON services.

Create the choreography

CLI reference table

$ amplify ace <command> [options]

Commands:
  init          Initialize project
  step          Step configuration management
  choreography  Choreography configuration management

List available AMPLIFY Choreography services

The list command returns a list of tenant-registered AMPLIFY Choreography services, along with their service types (Native Service or Aggregation Service).

$ amplify ace step list

You can also enter amplify ace -h for help.

Add choreography

The choreography add command creates functional choreographies using available AMPLIFY Choreography services.

Note   You can also use choreo as a shortcut for choreography.
ace choreography add --f=<./filePath>
  • If the services (steps) defined in the choreograph file have not been registered, then the add command returns an error.
  • If the JSON file contains a choroeography name with spaces, then the following error is logged to the CLI: Choreography could not be added. Please verify that choreography name does not have spaces.

List choreography

The choreography list command lists choreographies uploaded by the tenant.

Note   You can also use choreo as a shortcut for choreography.
$ amplify ace choreography list

Only the ID and name of the choreography is displayed when viewing the entire list.

To view a specific choreography by id:

$ amplify ace choreography list --id=<id>

To view a specific choreography by name:

$ amplify ace choreography list --named=<name>

The choreography's JSON content is displayed when viewing by id or name.

You can also enter amplify ace -h for help.

Delete choreography

The choreography delete command deletes a previously created choreography.

Note   You can also use choreo as a shortcut for choreography.
$ amplify ace choreography delete --id=<id>

You can also enter amplify ace -h for help.

Execute choreography

The choreography run command triggers the execution of a choreography using the CLI.

Note   You can also use choreo as a shortcut for choreography.
$ amplify ace choreography run <name>

To pass an optional file containing a payload:

$ amplify ace choreography run <name> --f=<filePath>

To pass an optional reference to a file as the payload:

$ amplify ace choreography run <name> --ref=<filePath>

To pass an optional file containing a payload and associate metadata to the payload:

$ amplify ace choreography run <name> --f=<filePath> --meta=<metadata-filePath>

You can also enter amplify ace choreography run -h for help.

 

 

 

The choreography add command creates the choreography.

Note   You can also use choreo as a shortcut for choreography.

amplify ace choreography add --f=<filePath>

FilePath = the path to the JSON file where the choreography is defined.

  • If a service specified in the choreography does not exist when the choreography add command is executed, then the choreography will not be added and an error message is displayed.

Define the choreography

A choreography can contain one or more services. Services can be defined so that they run in parallel, or run in a parent / child relationship or in a combination of both.

When a choreography is executed, any payload passed in will be passed to all "parent" services. All parent services will run in parallel.

Child services do not receive the payload that is passed in when the choreography is executed; however, they do receive the output from their parent service as input.

Note   Services do not have to generate output (i.e. output is not enforced by the platform). The person creating the choreography must be familiar with the output of each service and the input needs of each service to ensure that the services are compatible.

Child services run after their parent service has completed.

JSON service examples

Single service

{
	"choreographyName": "Choreo_Single_Service",
	"stepChain": [{
		"serviceName": "ServiceName1",
		"serviceVersion": "1.0.0"
	}]
}

Two parents with no children service

{
	"choreographyName": "Choreo_2Parents_NoChildren",
	"stepChain": [{
			"serviceName": "testService1",
			"serviceVersion": "2.0.0"
		},
		{
			"serviceName": "testService2",
			"serviceVersion": "1.0.0"
		}
	]
}

One parent with one child service

{
	"choreographyName": "Choreo_OneParent_OneChild",
	"stepChain": [{
		"serviceName": "ServiceName1",
		"serviceVersion": "1.0.0",
		"child": [{
			"serviceName": "ServiceName2",
			"serviceVersion": "1.0.0",
			"child": [{
				"serviceName": "ServiceName3",
				"serviceVersion": "1.0.0"
			}]
		}]
	}]
}

One parent with two children service

{
	"choreographyName": "Choreo_OneParent_TwoChildren",
	"stepChain": [
		{
			"serviceName": "ServiceName1",
			"serviceVersion": "1.0.0",
			"child": [
				{
					"serviceName": "ServiceName2",
					"serviceVersion": "2.0.0"
				},
				{
					"serviceName": "ServiceName3",
					"serviceVersion": "3.0.0"
				}
			]
		}
	]
}

Related Links