API access to the Signavio Process Manager

Signavio Process Manager offers access to the following APIs:

  1. A RESTful HTTP(S) API that allows you to integrate your systems and third-party systems with the Signavio application server.
  2. A JavaScript Mash-up API that allows you to interactively integrate the graphical representation of Signavio diagrams into other web applications’ front ends.

This section provides an overview of these APIs. For more information on common integration scenarios, see System integration scenarios.

Note

Using the Signavio Process Manager APIs requires an explicit API license. You need to purchase this license in addition to your Process Manager user licenses. This document provides an overview of the capabilities of Process Manager APIs. The full API documentation is only available for customers who purchased an API license.

The following diagram illustrates how to access Signavio Process Manager with the REST API and the Mash-up API.

../_images/system_landscape.png

Overview of the system integration landscape

The Signavio Process Manager REST API

The REST API provides access to Process Manager resources via HTTP.

A RESTful API uses HTTP methods like GET, POST, PUT and DELETE to create, access and manipulate HTTP resources. The Signavio REST API is a client-server API for creating, updating and retrieving all diagram, folder and dictionary data. Most HTTP response resource representations use the JSON format.

JSON is a lightweight, human-readable general purpose data format. All popular programing languages can process JSON, either natively or via mature third-party libraries.

We also provide a collection of requests you can import into the Postman HTTP client. With Postman, you can execute requests to get to know the API and generate code snippets to transfer them to your API development project.

REST API coverage

You can use the REST API to work with folders and diagrams. You can:

  • List folders and their contents
  • Create, rename, move and delete folders
  • Search folders and diagrams. Searching supports filtering by result type and paging search results.
  • List a diagram’s revisions
  • Fetch a specific diagram revision in JSON, BPMN 2.0 XML, SVG and PNG formats
  • Create, update, rename, move, copy, publish and delete diagrams
  • Import diagrams from BPMN 2.0
  • Check BPMN 2.0 diagram syntax

You can also use the REST API to work with the Dictionary and set-up. You can:

  • List Dictionary categories and fetch category details
  • Create, update and delete Dictionary categories
  • Search for Dictionary entries by category, initial letter of the entry name, or full text. Searching supports sorting and paging search results.
  • Fetch Dictionary entries
  • Create, update and delete Dictionary entries
  • Create custom attributes
  • Create custom data types (requires the Enterprise Plus Edition of Process Manager)

Example - generating custom reports

If your organization has specific reporting requirements, you might want to leverage the REST API to create custom spreadsheet reports or JavaScript dashboards. This section explains how to get started.

Important

Process Manager provides a comprehensive set of configurable reports by default. Before you implement a custom report that leverages the REST API, check first if the default reporting capabilities cover your organization’s needs. You can find an overview of all reports in the Process Manager user guide.

To generate a custom report, you can generally apply the following three-step approach:

  1. Retrieve the corresponding metadata.

    First, send one or more requests to the Process Manager server to retrieve an overview of the objects your report will cover. Depending on the scope of your report, either execute a search or traverse a folder. These requests return metadata about the objects your report will cover. Parse the JSON object the server returns to store object IDs and, optionally, other properties such as names.

  2. Retrieve all relevant objects.

    For each object ID you retrieve, send a GET request for the corresponding resource URL to return the full object. Transform these objects into the data structures your report will contain.

  3. Generate report in the desired format.

    Finally, transform the data into the desired business user-friendly format. For example, use a spreadsheet creation library to generate a report that end users can open as a Google Spreadsheet or Microsoft Excel document.

The example below uses the Python XlsxWriter library to generate a custom report that lists the name, ID and number of elements for each diagram in a given folder (including its sub-folders).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
import requests, xlsxwriter, json

from conf import *
from authentication.authenticate import authenticate

# ID of the folder that should be covered by the report
dir_ID = '<dir_ID>'

dir_url = base_url + '/p/directory'
diagram_url = base_url + '/p/revision'

auth_data = authenticate()

# set credentials, response format
cookies = {'JSESSIONID': auth_data['jsesssion_ID'], 'LBROUTEID': auth_data['lb_route_ID']}
headers = {'Accept': 'application/json',
           'x-signavio-id':  auth_data['auth_token']}


# recursively collects all diagrams (IDs) in a folder and its sub folders
def retrieve_diagram_meta_data(top_level_dir_id):
    diagrams = {}
    print('retrieving dir with ID {0}...'.format(top_level_dir_id))
    get_dir_request = requests.get(dir_url + '/' + top_level_dir_id,
                                   cookies=cookies,
                                   headers=headers)
    folder_json = json.loads(get_dir_request.text)
    for j_object in folder_json:
        if j_object['rel'] == 'dir':
            local_dir_id = j_object['href'].replace('/directory/', '')
            retrieve_diagram_meta_data(local_dir_id)
        elif j_object['rel'] == 'mod':
            diagram_id = j_object['rep']['revision'].replace('/revision/', '')
            diagram_name = j_object['rep']['name']
            diagrams[diagram_id] = {
                'name': diagram_name
            }

    return diagrams


# retrieve information about all diagrams with given IDs
def retrieve_diagram_info(diagrams):
    for id in diagrams:
        print('retrieving diagram with ID {0}...'.format(id))
        get_diagram_request = requests.get(
            diagram_url + '/' + id + '/json',
            cookies=cookies,
            headers=headers)
        j_diagram = json.loads(get_diagram_request.text)
        diagrams[id]['#elements'] = \
            len(j_diagram['childShapes'])


# print data to .xlsx file
def generate_report():
    print('generating report...')
    workbook = xlsxwriter.Workbook('Signavio_Process_Manager_Report.xlsx')
    bold_format = workbook.add_format({'bold': True})
    text_wrap_format = workbook.add_format({'text_wrap': True})
    worksheet = workbook.add_worksheet()
    worksheet.set_column('A:B', 30, text_wrap_format)
    worksheet.set_column('C:C', 20, text_wrap_format)
    worksheet.write('A1', 'Name', bold_format)
    worksheet.write('B1', 'ID', bold_format)
    worksheet.write('C1', 'Number of elements', bold_format)

    for index, id in enumerate(diagrams):
        print('adding diagram with id {0}...'.format(id))
        worksheet.write('A' + str(index + 2), diagrams[id]['name'])
        worksheet.write('B' + str(index + 2), id)
        worksheet.write('C' + str(index + 2), diagrams[id]['#elements'])

    workbook.close()
    print('report generated')

diagrams = retrieve_diagram_meta_data(dir_ID)
retrieve_diagram_info(diagrams)
generate_report()

The Signavio Process Manager Mash-up (JavaScript) API

The Signavio Mash-up API is a JavaScript library for embedding Signavio models in third-party web applications. It provides a configurable read-only view of diagrams and makes it possible to highlight shapes and to add custom functionality.

../_images/mash_up_example.png

Using the Mash-up API: screen shot of an embedded Signavio diagram