Getting Started

As you will see, is very easy to deploy and run your first business process.

Get start

First of all you need do make your business process flow using your favorite bpmn editor. For a list of compatible BPMN editors, see this. To see examples of BPMN flow files, see this.

PS: This is the process flow used on the examples below.

Deploy your business process

After design your business process flow you need to deploy it. To do that you just need to post the content of your business process file (*.bpmn file) to /process/deploy API. This content should be a plain text in xml format:

url:

POST https://api.inovabpm.com.br/v1/process/deploy

headers:

x-api-key: <REPLACE_WITH_YOUR_API_KEY>
Content-Type: text/xml;charset=UTF-8

body:

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" targetNamespace="examples">
  <process id="Process_1" name="My first process" isExecutable="true">
    <startEvent id="StartEvent_1" />
    <sequenceFlow id="SequenceFlow_1" sourceRef="StartEvent_1" targetRef="UserTask_1" />
    <userTask id="UserTask_1" name="Do something" />
    <sequenceFlow id="SequenceFlow_2" sourceRef="UserTask_1" targetRef="EndEvent_1" />
    <endEvent id="EndEvent_1" />
  </process>
</definitions>

response:

HTTP 1.1 201 OK
{
    "revision": 1529723042403,
    "date": "2018-06-23",
    "project": "examples",
    "release": "0.7.8",
    "tag": "v1",
    "stage": "dev",
    "owner": null,
    "changelog": null,
    "schema": "/process/deployed/v1",
    "hash": "5bfa59b8f1de4d82fef597434508bede"
}

This response with status http 201 means that the process with id Process_1 was deployed successfully. Remember the id, we will need it to start the process.

Tip: The majority of bpmn editors save file as .bpm, .bpmn or .xml. Using curl you can also pass the name of your business process file (*.bpmn), this should work too:

curl -i -X POST \
-H "x-api-key: <REPLACE_WITH_YOUR_API_KEY>" \
-H "Content-Type: text/xml;charset=UTF-8" \
--data-binary "@<REPLACE_WITH_YOUR_PROCESS_FLOW_FILE_NAME>.bpmn" \
"https://api.inovabpm.com.br/v1/process/deploy"

Pay attention to the content-type, it should be "text/xml".

Running your process

Now the process should be ready to start, you just need to post to /process/start API with process id and a body in json format. Every time you start the process, you can pass arbitrary data body related to your application:

url:

POST https://api.inovabpm.com.br/v1/process/start/<REPLACE_WITH_PROCESS_ID>

headers:

x-api-key: <REPLACE_WITH_YOUR_API_KEY>
Content-Type: application/json;charset=UTF-8

body:

{ "myfield": "xyz", "myfield2": 123 }

response:

HTTP 1.1 200 OK
{
    "process": {
        "id": "Process_1",
        "uid": "77dd5ae2-83e9-4367-8a52-142462ba1d38"
    },
    "created": "2018-06-23T03:14:19.125Z",
    "release": {
        "project": "examples",
        "stage": "dev",
        "tag": "v1",
        "version": "0.7.8",
        "date": "2018-06-23",
        "schema": "https://schemas.bpmn.com.br/task/created/json"
    },
    "name": "Do something",
    "id": "UserTask_1",
    "type": "bpmn:UserTask",
    "hash": "c39d45812098f5bbd51e5df71a3aa3d8",
    "revision": 1529723042403,
    "document": {
        "myfield": "xyz",
        "myfield2": 123
    },
    "uid": "03d452c5-2f39-4dd2-9099-fffc721dc0e9",
    "state": "created",
    "timestamp": 1529723659178
}

PS: As you can see in the response the yours arbitrary data was stored in a field called document. Later we will see how this field works.

Also important to note that based on values of the response fields type='bpmn:UserTask', id='UserTask_1' and state='created' the process was started successfully but it's waiting the task "do something" be completed to move on and reach the end.

Tip: To start your fist process using curl you need to pass at least the process id and an empty json object:

curl -i -X POST \
-H "x-api-key: <REPLACE_WITH_YOUR_API_KEY>" \
-H "Content-Type: application/json;charset=UTF-8" \
--data "{ }" \
"https://api.inovabpm.com.br/v1/process/start/<REPLACE_WITH_PROCESS_ID>"

Pay attention to the content-type, it should be "application/json".

Complete the user task

If you reached to this point, your first business process is running successfully. If was used the example above, the process was started and is waiting for task UserTask_1 to be completed to continue on the flow. This task represents a user input, like a form that needs to be filled or something that need to be completed by user before process can continue until the next task or reach the end.

Important: to complete this task you will need the unique identifier, this uid was provided in the response above, in the field of same name, in this case "03d452c5-2f39-4dd2-9099-fffc721dc0e9"

To completed the task UserTask_1 and make process reach the end you just need to send a post request to the endpoint /task/complete, like this:

url:

POST https://api.inovabpm.com.br/v1/task/complete/<REPLACE_WITH_USER_TASK_UID>

headers:

x-api-key: <REPLACE_WITH_YOUR_API_KEY>
Content-Type: application/json;charset=UTF-8

body:

{
    "my_form_field1": "abc",
    "my_form_field2": "xpto"
}

response:

HTTP 1.1 200 OK
{
    "created": "2018-06-23T03:14:18.978Z",
    "release": {
        "project": "examples",
        "stage": "dev",
        "tag": "v1",
        "version": "0.7.8",
        "date": "2018-06-23",
        "schema": "https://schemas.bpmn.com.br/process/completed/json"
    },
    "document": {
        "myfield": "xyz",
        "myfield2": 123,
        "my_form_field1": "abc",
        "my_form_field2": "xpto"
    },
    "type": "bpmn:Process",
    "executable": true,
    "enabled": true,
    "revision": 1529723042403,
    "uid": "77dd5ae2-83e9-4367-8a52-142462ba1d38",
    "name": "My first process",
    "id": "Process_1",
    "state": "completed",
    "hash": "289e688220b48fb6fc095fffa7af1f25",
    "timestamp": 1529727012932,
    "completed": "2018-06-23T04:10:12.931Z",
    "status": {
        "type": "success"
    }
}

Based on the response fields, like type=bpmn:Process, id=Process_1 and state=completed, means that this process execution reached the end successfully.

PS: As you can see the body used to complete the task, in this case, an arbitrary json object, representing a form filled, was merged with content of the process body, in the same field called document. This is the default behaviour of the data flow during the process execution.

Congratulations

You reached to the end of process execution with success. What will determine if the process will run from beginning to the end or will stop in the next step that needs user input, like a user task, depends on the bpmn elements that you use in your business process flow.

Next we will take a look into this bpmn elements and the behaviour of each of that.