Build4 min read

Calling external systems with connectors

Call REST, GraphQL and SOAP services or send email straight from a service task — configured, not coded.

In short

01
Four connectors today: HTTP, GraphQL, SOAP and Email.
02
Credentials stay in a connection or secret, never in the diagram.
03
Map process variables in and response fields out.

For a simple call to another system you do not need to write a worker. A connector turns a service task into a configured call.

Process variables

Input mapping

Connector call

Output mapping

Process variables

Available connectors

Connector	Use it for	Fails the task when
HTTP	REST APIs and webhooks	The call fails or times out
GraphQL	GraphQL queries and mutations	The response contains errors
SOAP	SOAP 1.1 web services	The service returns a SOAP fault
Email	Sending mail over SMTP	The mail server rejects the message

A SQL connector is not available yet. For databases and anything else, write a job worker.

Mapping data in and out

Each connector input gets its value from one of three places.

Source	Value comes from	Use it for
Variable	A process variable	Data that changes per instance, such as an email address
Secret	A named secret, looked up when the task runs	API keys and passwords
Literal	A fixed value typed in the diagram	Constants such as a subject line

The output mapping does the reverse: it names which response fields to keep and which process variables to store them in.

<bpmn:serviceTask id="notify-approver"
    orkovia:connectorType="email"
    orkovia:connectorInputMapping='{"to": {"source": "VARIABLE", "value": "approverEmail"},
                                    "apiKey": {"source": "SECRET", "value": "smtp-credentials"}}'
    orkovia:connectorOutputMapping='{"messageId": "notificationId"}'
    orkovia:connectorRetryPolicy='{"maxAttempts": 3, "retryDelayMillis": 500}'/>

Connections

A connection stores the address and credentials of a system once, per environment. Tasks point at the connection, so the diagram stays the same between test and production. You can enable, disable and test a connection from Studio.

Testing a connection checks that it is completely configured. It does not make a live call to the other system.

Retries

Give a connector task a retry policy — a number of attempts and a delay between them. Without one, the task is tried once.

See it on your own process

Book a walkthrough with the Orkovia team.

Request a Demo

Keep reading

Build3 min read

Build without the backend: mocking service tasks

Give a service task a pretend response, delay and failure rate, so you can run the whole process before the real system or worker exists.

Read article

Build5 min read

Writing your first job worker

A worker is your code that does the work behind a service task. Here is the loop it runs, in Node.js, Python and Java.

Read article

Get started4 min read

Importing models from Camunda 8

What carries over when you open a Camunda 8 (Zeebe) BPMN model in Orkovia, and what you need to fix by hand.

Read article