Using vcenter Orchestrator AMQP Plug-in

Using vCenter  Orchestrator

AMQP Plug-in

Walkthrough guide

T E C H N I C A L W H I T E P A P E R

Document Title

Table of Contents

What is vCenter Orchestrator AMQP Plug-in? ... 2  

AMQP Plug-in Installation ... 2  

Configure AMQP Broker Server in AMQP Plug-in ... 2  

Send “Hello World” AMQP Message Using AMQP Plug-in ... 4  

Suspend Workflow Waiting for AMQP Message Using AMQP Plug-in ... 8  

Using AMQP Queue as a vCenter Orchestrator Policy Element ... 9  

Overview of the Scripting API ... 10  

What is vCenter Orchestrator AMQP Plug-in?

AMQP Plug-in Installation

The plug-in could be installed as any vCO.vmoapp file, by uploading it through the vCO web configurator’s Plug-ins page.

Configure AMQP Broker Server in AMQP Plug-in

In order to start using AMQP brokers in the vCenter Orchestrator you need to configure them in the AMQP plug-in. This could be easily done by using the provided by the plug-in configuration workflows.

Figure 1: AMQP Plug-in configuration workflows

To add new broker definition use the “Add broker” workflow. When started, you will be prompted to input all

the properties of the broker.

Figure 2: Add broker workflow

Some of the properties will be filled in by default (port and virtual host). After you submit the workflow your broker will be shown in the inventory.

Figure 3: AMQP broker in the inventory

Now you are ready to use this broker. If you want to update the broker properties use “Update broker”

workflow, if you want to remove it just use “Remove broker”.

The configured broker could be managed with several additional workflows provided by the plug-in. This way

you could declare/delete exchanges, queues and bindings.

Send “Hello World” AMQP Message Using AMQP Plug-in

Let’s use the already configured broker to send and receive a simple text message. As a starting point let’s declare an exchange. Start the “Declare exchange” workflow and fill in the exchange properties.

Figure 4: Declare exchange

There is no way visually to confirm that the exchange is created but if the workflow completes successfully

the exchange is created. Now that we have the exchange, let’s create a queue that we could bind to the

exchange. To do this start the “Declare queue” workflow and fill in the queue properties

Figure 5: Declare queue

Again we could not visually confirm that the queue is created but the workflow success is enough. Now it is

time to bind the queue to the exchange, for this purpose start “Declare binding” workflow and fill in the

required properties.

Figure 6: Declare binding

As we already created the necessary AMQP destinations let’s send and receive a message through it. There are two simple workflows provided by the plug-in that allows you to send and receive a text message, so let’s use them for our test message. Start the “Send text message” workflow and fill in the message properties.

Figure 7: Sending text message

The workflow should complete successfully. Now let’s read the message using the “Receive text message”

workflow.

Figure 8: Receive text message

If the workflow execution is successful we could observe the message details in the Variables tab in execution details screen.

Figure 9: Message details

To clean up the test exchange and queue that we created we could use “Delete exchange” and “Delete queue” workflows.

Suspend Workflow Waiting for AMQP Message Using AMQP Plug-in

Being able to receive a message from a queue is nice but sometimes we need to suspend the worlflow execution until a message is received. Let’s take a look how we could achieve this. The plug-in comes with an additional folder with sample workflows in /Library/AMQP Samples/. The workflow “Wait for message”

suspends its execution until a message is received on the specified queue:

Figure 10 “Waiting for message” workflow

It uses the well known “Wait Event” component to achieve execution suspension:

Figure 11 Creating triggers for waiting on a queue

Creating the trigger to pass to the “Wait Event” is the only AMQP plug-in specific part:

messageTrigger = broker.receiveAsync(queue, timeoutSeconds);

Besides the queue name you must provide a timeout (in seconds) to wait for a message. When no message

is received within the provided timeout, the workflow fails.

In case a message is received, you can access it using this snippet:

var props = broker.retrieveLostTriggerProperties(messageTrigger);

if (props != null) {

body = props.get("body");

properties = props.get("properties");

headers = props.get("headers");

}

Notice how you use the trigger as a parameter to the retrieveLostTriggerProperties() scripting method. If you do

Using AMQP Queue as a vCenter Orchestrator Policy Element

A set of AMQP can serve as policy element. You create a subscription inventory item using the “Subscribe to queue(s)” workflow

Figure 12 Create a Subscription

In this fictional scenario we subscribe to the queues “prices” and “invoices”. The queues must be created in advance otherwise the policy will fail to start.

The “Subscription” policy element has a single trigger “OnMessage”, which is activated whenever a message is received on any of the queues.

The Subscriptions are visible as children of the Broker:

Figure 13 Subscriptions shown in the inventory

It is recommended to create a Policy using the provided Policy Template in /Library/AMQP/Subscription.

Figure 14 Appling a Policy Template for a Subscription

The created Policy is automatically bound to the OnMessage trigger on the Subscription inventory object.

There is also scripting code generated as a hint how to retrieve the message:

Figure 15 Editing a Subscription based Policy

In case you need to know on which queue the message was received, you can inspect the messageProperties and find out.

Overview of the Scripting API

• Creating a broker

var broker = AMQPBrokerManager.addbroker({

host: "10.23.164.48", port: 5672,

username: "guest", password: "guest"

});

• Removing a broker broker.remove();

• Declaring an exchange

broker.declareExchange("demo-exchange", { type: "direct", // fanout, topic or headers durable: false,

autoDelete: false });

• Deleting an exchange

broker.deleteExchange(name);

• Declaring a queue

broker.declareQueue("demo-queue", { durable: false,

exclusive: false, autoDelete: false });

• Deleting a queue

broker.deleteQueue(name);

• Declaring a binding

broker.bind("demo-queue", "demo-exchange", { routingKey: "rk"

});

• Deleting a binding

broker.unbind(queueName, exchangeName, { routingKey: "rk"

});

• Sending a message

var msg = new AMQPMessage();

msg.bodyAsText = "hello world"

broker.send("demo-exchange", "rk", msg);

• Receiving a message

var msg = broker.receive("demo-queue");

if (msg != null) { // process message } else {

// no pending message in the queue

}