Release Infrastructure/BOSS Participant

Contents 1 BOSS Participant 1.1 What is BOSS Participant 1.2 Participant Coding Guidelines 1.2.1 Participant Naming Convention 1.2.2 Prerequisites 1.2.3 Import 1.2.4 Class definition 1.2.5 Registering BOSS Participant to server 1.3 Participant Example Code

BOSS Participant

BOSS is a workflow orchestrator, a system that can be configured to automate your workflow requirements; it interacts with the OBS and with people and systems around it to apply your workflow steps. For more BOSS related general information, see Infrastructure/BOSS.

What is BOSS Participant

BOSS Participant is the actual actor in BOSS architecture. Participant wraps other systems and services related to software development, quality assurance and integration, allowing BOSS to interact with different parties in automated way.

BOSS Participant action explained in three simple steps:

• Receive a workitem from BOSS server
• Process it, interacting with underlying (read: wrapped) system or service
• Return the filled worksheet back to BOSS server

Participant Coding Guidelines

BOSS participant is written in Python language (other bindings will be available later). Following code snippets are from Notifier Participant (see chapter Example Code). Participants run continuously as daemons. It is convenient to write an init script to wrap and manage them.

Participant Naming Convention

The participant's name should give an indication of the function it does, usually in the form noun_verb.py

Prerequisites

You need to install two libraries:

 * AIR: An RPC library used by BOSS
 * route-amqp-pyclient : The Python client library for Ruoute::AMQP

These libraries are open source and the code is published on gitorious :

 * http://meego.gitorious.org/meego-infrastructure-tools/air
 * http://meego.gitorious.org/meego-infrastructure-tools/ruote-amqp-pyclient

They are also packaged for OpenSuse ( and Debian soon ) on OBS https://build.opensuse.org/project/show?project=Maemo%3AMeeGo-Infra

Import

Once you have these libraries installed, you need to import them in your participant like this :

from  RuoteAMQP.workitem import Workitem
from  RuoteAMQP.participant import Participant

Class definition

The parent class Participant defined in participant.py of the route-amqp-pyclient package takes care of most of the details needed to create a participant. You just need to subclass it and define a "consume" member function.

The received work item is stored as an attribute, it contains the information that was passed from previous steps in the workflow. Usually you would read the work item, do some processing, and then store results in the work item.

For participants in a certain workflow to be able to communicate effectively, they need to follow the agreed upon "WID" or work item definition. The work item is just a JSON hash with the information stored in nested hashes and the WID is a namespace definition.

The WID should also be generic enough to allow for many participants storing their results in the work item without collisions. Namespacing is a good idea so for example a generic "id" hash could be troublesome, while "notification.id" is clearer.

That's all there is to it, the parent class will take care of putting the workitem back on the amqp queue.

class NotifierParticipant(Participant):
    def consume(self):
       # look at workitem
       print json.dumps(self.workitem.to_h(), indent=4)
       #get some data from it
       package = self.workitem.lookup("package")
       # do some work 
       # write some results to workitem
       self.workitem.set_field("accepted", "yes")
       self.workitem.set_result(True)

Here is an example of a workitem :

{
    "fei": {
        "engine_id": "engine",
        "expid": "0_0_2",
        "sub_wfid": null,
        "wfid": "20100905-binapoyachi"
    },
    "fields": {
        "__result__": true,
        "comment": null,
        "desc": "Another trigger!",
        "dispatched_at": "2010-09-05 13:24:44.051971 UTC",
        "dst_package": "boss-launcher-srhandler",
        "dst_project": "Meego",
        "email": "example@example.com",
        "msg": "Passes quality checks\n",
        "name": "new",
        "params": {
            "forget": false,
            "participant_options": {
                "forget": false,
                "queue": "notify"
            },
            "ref": "notify"
        },
        "project": "Meego",
        "reason": "",
        "rid": 41,
        "src_package": "boss-launcher-srhandler",
        "src_project": "Meego",
        "src_rev": "2",
        "status": "ACCEPTED",
        "when": "2010-09-05T16:20:53",
        "who": "iamer"
    },
    "participant_name": "notify"
}

Registering BOSS Participant to server

To register your participant you need to have : a queue name, amqp host, and probably usrename and password for amqp authentication.

if __name__ == "__main__":
    print "Notifier participant running"
    p = NotifierParticipant(ruote_queue="notifier", amqp_vhost="ruote-test")
    p.register("notifier", {'queue':'notifier'})
    p.run()

Participant Example Code

See following participants for example implementation: [notifier_participant.py] [build_ks_participant.py]

For a more advanced template with configuration, daemonization and packaging for Debian and opensuse look here : [ots_participant]