So now we can write webservices with Clarive rulebooks. We call them webhooks, but they are actually inbound.


Let me explain. Let’s start with the problem at hand.

The Problem at hand

With Clarive you can write your automation as rulebook files. (You can also write them visually with Clarive EE, but that’s another story.) Rulebooks can do wonderful things, like automating your pipeline: building, testing and deploying apps. They can also be used to provision your infrastructure (think cloud instance or DB) and can be triggered by many different rules, like a topic modification or a branch being pushed. They can also be scheduled to run on a cron.

But what if you want to trigger them from an outside event? Say when a user opens an issue on your issue tracker, or someone pushes something to a repository somewhere? That’s when we wanted to trigger a rule in our rulebook. To do that you can call into Clarive. But instead of running a generic Clarive API that calls a rulebook, we wanted to expose meaningful urls that would make more sense of

What is a Rulebook

Rulebook is a file (or set of files) checked into a Git repository in your Clarive instance. It all starts with the .clarive.yml file.

Your rulebook will contain rules. Rules can be build, test, deploy, or events like topic_modify or repository_update. And then they can be webhook rules. Webhook rules are any events that start with a / slash character. The event name will become an url fragment to be called into.

Webhook rules behave like exposed webservices right into your instance, running within your repository.

Here’s an example:

/hello_world:
    - echo: running the hello world webhook

       # do some meaningful stuff here

    - web_response:
       # return something to the caller

Anatomy of a web call

When you call into a rule webhook introducing a url like this:
https://{myclariveserver}/rule/json/{MyProject}/{MyRepo}/hello_world?api_key={my_user_api_key}

It goes through the following steps:

  • Authenticates the user (users must be authenticated – via api_key).
    your API key

    This is your user API key

  • Locate your project MyProject and the repository associated MyRepo

  • Find .clarive.yml file
  • Look for a webservice defined with / and called hello_world
  • Execute the echo code and return the result in web_response

A hardcore example: provision an Azure VM

To run this example you can create an instance in our free cloud. That will give you the complete infrastructure you need.

  1. Get a free Azure account if you don’t have one already.
  2. Get your free Clarive cloud instance
  3. Once you get an email with the instructions, you can login in your Clarive.
  4. Create a new project and a git repository associated to it.
  5. Create a story from your project, and that will create automatically a new branch in your repo
    your topic

    Create a topic in Clarive

  6. Create your azure variables that you will need to login using a service principal

    Azure vars

    Your secret vars that allow to login in your Azure

  7. Clone this repo in your local workspace, checkout the actual branch and modify your .clarive.yml with the webservice.

    /create_azure_vm:
     image: 
        name: microsoft/azure-cli #docker image to run az commands
     do:
        - myoutput = shell: |
            az login --service-principal -u {{ ctx.var('az-service-principal') }} --password {{ ctx.var('az-password') }} --tenant {{ ctx.var('az-tenant') }}
            az vm create --resource-group {{ ctx.var('az-resource-group') }} --name myFirstVM --image centos --admin-username {{ ctx.var('az-vm-username') }} --admin-password {{ ctx.var('az-vm-password') }} --authentication-type password
        - if "{{ myoutput.rc == 0 }}"
        then:
           - result =: "VM created succesfully!"
        else:
           - result =:"Upps! something went wrong, review your azure instance."
        - web_response:
           body: ${result}
    
  8. Push the changes (after commiting them, obviously) into your branch, then you have to take your topic to PROD environment where your branch will be merged in master or do it manually.

  9. Your defined webservice will be available so call it with your browser or in your command line using “curl”.

    curl https://{your_instance}.clarive.io/rule/json/{your_project}/{your_repo}/create_azure_vm?api_key={your_user_api_key}
    
  10. Finally, you can see your VM created in your Azure instance.

    Your VM created in Azure with a Clarive webhook

That’s it. You’ve just created your first DevOps webservice in Clarive 🙂


Get an early start and try Clarive now. Get your custom cloud instance for free.