How to use Bonita BPM 6 Web REST API in Python: create accounts

jeremy.jacquier-roux's picture
Blog Categories: 

This tutorial shows how to use the web REST API provided by Bonita BPM 6 in order to create new accounts in Python. You need to have a working Bonita BPM 6 to test the code below. This can be done with Bonita BPM Studio after deploying Bonita BPM Portal.
This example is run on a Linux distribution (Ubuntu 12.04 LTS).
The official documentation is available here
Note: I'm not a Python developer and there are always many ways to accomplish the same thing. Don't hesitate to improve this example!

Useful modules

The following Python modules will be helpful:

  • argparse
  • httplib2
  • json
  • urllib


Before going further, log in and retrieve the corresponding cookie. You can do it this way:

def portal_login(url,username,password,disable_cert_validation):<br />
            http = httplib2.Http(disable_ssl_certificate_validation=disable_cert_validation)<br />
            API="/loginservice"<br />
            URL=url+API<br />
            body={'username': username, 'password': password, 'redirect': 'false'}<br />
            headers={"Content-type":"application/x-www-form-urlencoded"}<br />
            response, content = http.request(URL,'POST',headers=headers,body=urllib.urlencode(body))<br />
            if response.status!=200:<br />
              raise Exception("HTTP STATUS: "+str(response.status))<br />
            return response['set-cookie']

If you run the Bonita BPM Portal from Studio, you can use these parameters:

disable_cert_validation should be set to false by default. It's useful only for test purposes, when we use a self-signed certificate.

Create a user

Use the following function to create a user using the previous cookie:

def create_user(url,cookie,username,password,firstname,lastname,disable_cert_validation):<br />
            http = httplib2.Http(disable_ssl_certificate_validation=disable_cert_validation)<br />
            API="/API/identity/user/"<br />
            URL=url+API<br />
            headers={"Content-type":"application/json",'Cookie': cookie}<br />
            data={"userName":username,"password":password,"firstname":firstname,"lastname":lastname, "enabled": "true"}<br />
            data = json.dumps(data)<br />
            response, content = http.request(URL, 'POST',headers=headers, body=data)<br />
            if response.status!=200:<br />
              raise Exception("HTTP STATUS: "+str(response.status)+" "+content)<br />
            else:<br />
              data = json.loads(content)<br />
              return data['id']

Add a user to a profile

Retrieve a profile id

This function return the profile id, this way we can search for both Administrator and User profile:

def get_profile_id(url,cookie,name,disable_cert_validation):<br />
            http = httplib2.Http(disable_ssl_certificate_validation=disable_cert_validation)<br />
            API="/API/userXP/profile"<br />
            params="?f=name="+str(name)<br />
            URL=url+API+params<br />
            headers={"Content-type":"application/x-www-form-urlencoded",'Cookie': cookie}<br />
            response, content = http.request(URL, 'GET',headers=headers)<br />
            data = json.loads(content)<br />
            try:<br />
              return data[0]['id']<br />
            except Exception, e:<br />
              return None

Link the user to a profile

This last function permits to link the user previously created using its id and the profile id retrieved before:

def add_user_to_profile(url,cookie,uid,pid,disable_cert_validation):<br />
            http = httplib2.Http(disable_ssl_certificate_validation=disable_cert_validation)<br />
            API="/API/userXP/profileMember/"<br />
            URL=url+API<br />
            headers={"Content-type":"application/json",'Cookie': cookie}<br />
            data={"profile_id":pid,"member_type":"USER","user_id": uid}<br />
            data = json.dumps(data)<br />
            response, content = http.request(URL, 'POST',headers=headers, body=data)<br />
            if response.status!=200:<br />
              raise Exception("HTTP STATUS: "+str(response.status)+" "+content)

Full example

You can download a full example here:

usage: --login install --password install --url<br />
                               --new_login<br />
                                        john.smith --new_password mysecret --firstname<br />
                                        John --lastname Smith [-h]<br />
                                        [--disable_ssl_certificate_validation]<br />
                                        [--is_admin]<br />
        <br />
        Create a Bonita account<br />
        <br />
        required arguments:<br />
          --login install       Account used to authenticate you on Bonita<br />
          --password install    Password used with your account<br />
          --url<br />
                                Bonita BPM url<br />
          --new_login john.smith<br />
                                New account that will be created<br />
          --new_password mysecret<br />
                                Password used for the new account<br />
          --firstname John      First name used for the new account<br />
          --lastname Smith      Last name used for the new account<br />
        <br />
        optional arguments:<br />
          -h, --help            Show this help message and exit<br />
          --disable_ssl_certificate_validation<br />
                                Used this only for tests with a self-signed<br />
                                certificate<br />
          --is_admin            Assign user to Administrator profile

To create a new account with the Administrator profile, you can launch a command like:

./ --login walter.bates --password bpm --url http://localhost:8080/bonita --new_login john.smith --new_password pass --firstname John --lastname Smith --is_admin

If you use an url in https with a self-signed certificate, it may raise this error:

httplib2.SSLHandshakeError: [Errno 1] _ssl.c:504: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

You can avoid this verification (for test only!) using the parameter "--disable_ssl_certificate_validation".


Submitted by aCordier on Thu, 01/09/2014 - 14:38

Hello and thank you,

How can we now how to properly construct the json representation for any operation we want to execute on a resource using rest API. Is there a documentation pointing to this ?

EDIT: there's no need for such a documentation, it works just fine :)


Submitted by simon.tilbrook on Sat, 04/05/2014 - 20:47

When I use the REST API to create users they are inactive until they are manually activated via the Portal. Is there any way to create new users with enabled=true using the REST API?

Submitted by simon.tilbrook on Sat, 04/05/2014 - 21:24

In fact I've found the answer myself - enabled must be set to the string value "true", e.g.: {"enabled":"true","title":"Mr","password_confirm":"......","job_title":"ADV","lastname":"Last","userName":"USER-03","firstname":"First","password":"......"}

Submitted by simon.tilbrook on Sun, 04/06/2014 - 15:02

I now have working code to create active users and add them as members of roles/groups using the REST API. I cannot however populate the professionalcontactinfo fields using a POST - I always get an HTTP 500 error. Does anyone have a working example of the JSON to pass to update the user_contactinfo table?

In case it helps, the message I've tried to send looks like this:

Sending {"phone_number":"\+9999999999","address":"99 Xxxxxxxxxxxxxxxx, Xxxxxxx","email":"","city":"London","country":"United Kingdom"} to URL : http://server:8080/bonita/API/identity/professionalcontactdata/999

And the error I get looks like this

{"exception":"class java.lang.NullPointerException","message":"","stacktrace":[" org.bonitasoft.web.toolkit.client.common.json.JSonItemReader.parseItem(JSonItemR","org.bonitasoft.web.toolkit.client.common.json.JSonItemReader.p arseItem(","org.bonitasoft.web.toolkit.client.common.jso n.JSonItemReader.parseItem(","org.bonitasoft.web.toolkit .client.common.json.JSonItemReader.parseItem(","org.boni"

Submitted by simon.tilbrook on Tue, 04/08/2014 - 11:04

in case it helps others, I found the solution to this myself too. As the user already exists, a PUT must be used to add the contact details, not a POST.