HTTP Service

Use the HTTP Service asset to call REST APIs from within your workflows. It lets you define reusable API operations—complete with authentication, request parameters, and response handling—that you can invoke from a JavaScript or Python processor.

Typical use cases:

• Fetching reference data from an external API to enrich records
• Posting processed events to a third-party system
• Triggering webhooks or callbacks

---

What You'll Configure

An HTTP Service is built from three pieces:

1. Requests — define the URL, HTTP method, and parameters for each API call
2. Responses — describe what the API returns (success and error cases)
3. Functions — bundle a Request with its possible Responses into a callable operation you use in code

---

Step 1: Name and Describe the Asset

Field	Description
Name	Asset identifier. No spaces allowed.
Description	Optional summary of what this service connects to.
Asset Usage	Shows where this asset is referenced in your project. Click to expand and jump to those locations.

In case you are deploying to a Cluster which is running (a) Reactive Engine Nodes which have (b) specific Roles configured, then you can restrict use of this Asset to those Nodes with matching roles. If you want this restriction, then enter the names of the Required Roles here. Otherwise, leave empty to match all Nodes (no restriction).

---

Step 2: Configure the Host and Authentication

Host

Enter the base URL of the API you want to call. Every request you define later will be appended to this host.

Field	Description
Default Host	Base URL, e.g. https://api.example.com. Used when no other host is specified.

Credentials

Choose how the service authenticates with the API:

Type	When to Use
None	The API requires no authentication.
User/Password	Basic HTTP authentication.
OAuth (Client Credentials)	Machine-to-machine OAuth 2.0 flows.
OAuth (Device Flow)	OAuth for input-constrained devices.

User/Password

Field	Description
Credential Type	Select User/Password.
Username	Your API username. Macros supported.
Password	Your API password. Macros supported.
Do not substitute macro terms in password	Check if your literal password contains ${...} that should not be interpreted as a macro.

OAuth (Client Credentials)

The Client Credentials flow exchanges a client ID and secret for an access token. See Auth0's documentation for a detailed explanation.

Field	Description
Authority	The OAuth token endpoint provided by the API vendor.
Client ID	ID issued by the authenticating authority.
Scopes	Space-separated list of permissions to request. Must be granted by the authority or authentication will fail.

OAuth (Device Flow)

For devices that cannot easily capture user input, this flow asks the user to authorize the device via a separate browser or phone. See Auth0's documentation.

The settings are the same as OAuth (Client Credentials) above.

---

Step 3: Define Requests

A Request describes a single API call: the path, HTTP method, and any parameters.

Requests live inside a Namespace, which groups related requests together and prevents naming conflicts.

Click + Add Request to create one.

Field	Description
Request Name	Identifier used to reference this request later.
Description	Optional summary.
Path	URL fragment appended to the Default Host. Example: host https://myhost.com + path /api/v1/customers → https://myhost.com/api/v1/customers
Method	GET, POST, PUT, or DELETE.

Request Parameters

After creating a request, add the parameters it requires.

Click + Add Parameter and fill in the table:

Column	Description
Name	Parameter identifier. Special characters [, ], and . are supported (e.g. users[0][name] or filter.user.role).
Type	Where the parameter is sent: • Path — substituted into the URL path • Query — appended as a query string • Header — added as an HTTP header • Body Simple Type — plain value in the body • Body Simple JSON — JSON object in the body
Data Type	System type of the value (e.g. System.String).
Optional	Whether the parameter can be omitted.
Description	Human-readable explanation.

Special Characters in Parameter Names

You can use brackets and dots directly in parameter names without any extra configuration. This is useful for Ruby on Rails-style APIs (users[0][name]) or nested filters (query.date.range).

JavaScript

// Bracket notation for arrays
const params = {
  "users[0][name]": "John Doe",
  "users[1][name]": "Jane Doe"
};

// Dot notation for nested fields
const filters = {
  "filter.user.role": "admin"
};

services.MyHttpService.CreateUsers(params);

Python

params = {
    "users[0][name]": "John Doe",
    "filter.user.role": "admin"
}
services.MyHttpService.CreateUsers(params)

---

Step 4: Define Responses

A Response maps an HTTP status code and content type to a data type in your workflow. You typically need at least one success response (e.g. 200) and may want error responses (e.g. 4xx).

Responses also live in a Namespace.

Click + Add Response to create one.

Field	Description
Response Name	Identifier for this response.
Status Code Pattern	Match HTTP status codes. Use x as a wildcard. Examples: 2xx (any success), 404 (not found), 4xx (any client error).
Content Type Pattern	Match the Content-Type header. Use * as a wildcard. Examples: application/json, application/xml, */* (match anything).
Data Type	Type to deserialize the body into. Use System.AnyMap for JSON objects.
Description	Human-readable explanation.

Data Dictionary

The Data Dictionary allows you to define complex data structures which can be mapped onto external data types and vice versa. This is necessary whenever an asset needs to exchange structured data with an external system — for example, when reading from or writing to a database, an HTTP API, a message queue, or any other format that carries typed fields.

Rather than hard-coding external field names and types into your Workflow, you define your own internal data types here. These internal types are then mapped to the external system's fields at the asset level. This means your Workflow scripts work with consistent, self-documenting data structures regardless of which external system the data came from.

When you need it

Whenever you configure an asset that exchanges structured data — a JDBC Service, a DynamoDB Service, an HTTP endpoint, an MQ message, a database Resource — you use the Data Dictionary to declare the types that represent:

• Request parameters — the data your Workflow sends to the external system
• Result data — the data the external system returns to your Workflow
• Intermediate structures — types that hold data during a transformation

Entity Types

The Data Dictionary is organized as a tree of typed entities. The available entity types are:

Entity	Description
Namespace	Groups related types. Optional. If you reuse a namespace name that already exists in the Project, the two namespaces merge.
Sequence	An ordered list of typed members. Members are accessed by name, e.g. MyNamespace.Customer.Name.
Enumeration	A fixed set of named integer constants.
Choice	A type that holds exactly one of several possible member types.
Array	A sequence of elements of a single contained type.

Defining Types — Step by Step

The following walkthrough shows how to build a data structure using the Data Dictionary editor. The example assumes a SQL customer table with columns id, name, and address — but the same pattern applies whenever you need to declare types for any asset.

1. Declare a new type

Click Declare Root Type in the toolbar to add a top-level entity.

2. Declare a namespace (optional)

Namespaces organize related types. To add one, right-click an existing node and select Add Sibling, then set the element type to Namespace.

• Name — The name of the namespace. If a namespace with this name already exists elsewhere in the Project, their contents merge automatically. Otherwise the name must be unique and may not contain spaces.

• Type — Pick the entity type. For a namespace, select Namespace.

• Description — Optional free-text description.

3. Declare a Sequence under the namespace

Right-click the namespace and choose Add Child to add a child element.

Click the arrow next to the namespace name and select Add child. Then fill in the element details:

• Name — The name of the element, e.g. Customer.

• Type — Select Sequence as the element type. You will add individual fields (members) in the next step.

• Extendable Sequence — When checked, layline.io can dynamically extend the sequence's member list if incoming data contains fields that are not explicitly defined. Leave unchecked if all fields are known in advance.

4. Add members to the Sequence

With the Sequence selected, click Add Child to add individual fields:

Each member maps to a column in the external data source. You can reference any member by its full path — for example, MyNamespace.Customer.Name — from your Workflow scripts.

Common Entity Fields

These fields are available on all entity types:

Field	Description
Name	Unique identifier within the namespace. Reusing a namespace name from another part of the Project merges the two.
Type	The entity kind: Namespace, Sequence, Enumeration, Choice, or Array
Description	Optional free-text description
Extendable Sequence	(Sequence only) Allows the member list to be extended dynamically at runtime
Members	(Sequence) Ordered list of typed fields — click Add Child to add each one
Elements	(Enumeration) Named integer constants making up the enumeration

Advanced Features

Inheritance and Override
Entities inherited from a parent format or resource appear in the tree in a distinct inherited style. These are read-only unless overridden. Click Reset to Parent on an overridden entity to restore the inherited definition.

Copy and Paste
Use the toolbar buttons to copy a complete entity subtree and paste it elsewhere in the tree. All members and nested entities travel with it.

Filter and Sort
Use the Filter field to search entities by name. The sort buttons order nodes ascending or descending alphabetically.

See Also

• Data Dictionary Format Asset — standalone Data Dictionary asset
• DynamoDB Service — Data Dictionary in context of a DynamoDB Service
• JDBC Service — worked example mapping Data Dictionary types to SQL columns

---

Step 5: Bundle into Functions

A Function is what you actually call from your workflow code. It ties together:

• One Request (what to send)
• One or more Responses (what might come back)

Functions are grouped in a Namespace. A common pattern is to use the domain as the namespace and the operation as the function name, e.g. Customer.Get or Customer.Create.

Click + Add Function.

Fill in the details:

Field	Description
Function Name	Name you will call in code (e.g. GetCustomerById).
Description	Optional summary.
Request Type	The request to send (defined in Step 3).
Response Types	One or more possible responses (defined in Step 4).

Select the request from the dropdown:

Then add responses by clicking + Add Response and choosing from your defined responses:

You can add as many functions as your integration requires.

---

Example: Call a REST API from JavaScript

Here is a complete example. The workflow reads a file with customer IDs (1), enriches each record by calling a REST API (2), and outputs the result.

1. Link the Service to Your Processor

Open the JavaScript processor (in this case EnrichCustomer) and assign the HTTP Service:

Field	Description
Physical Service	The HTTP Service asset you configured above.
Logical Service Name	The name you will use to call it in code. No spaces allowed.

2. Call the Service in Code

JavaScript

let httpData = null;
const customer_id = 1234;

try {
    httpData = services.MyHttpService.GetCustomerById({ id: customer_id });
} catch (error) {
    processor.logError("API call failed: " + error);
}

if (httpData && httpData.data.length > 0) {
    processor.logInfo("Name: " + httpData.data[0].Name);
    processor.logInfo("Address: " + httpData.data[0].Address);
} else {
    processor.logInfo("No customer data found for ID " + customer_id);
}

Python

http_data = None
customer_id = 1234

try:
    http_data = services.MyHttpService.GetCustomerById({ 'id': customer_id })
except Exception as error:
    processor.log_error("API call failed: " + str(error))

if http_data and http_data.data.length > 0:
    processor.log_info("Name: " + http_data.data[0].Name)
    processor.log_info("Address: " + http_data.data[0].Address)
else:
    processor.log_info("No customer data found for ID " + str(customer_id))

Service Testing

layline.io provides a test facility for testing your Services before you deploy them. In this way, you save time and effort by testing your Services without having to deploy and activate a whole Project with Workflows.

Once you have configured your Service(s), you can test them: Within your Asset Configuration tab (1), switch to the Test tab (2) to test your Service.

Test Facility Toolbar

The toolbar provides the following options:

The Testing tab provides two major views:

1. Testcase configuration: This is where you define the testcases to be executed.
2. Testcase execution: This is where you can execute the testcases and see the results.

You switch between these two views by clicking on the leftmost icon in the toolbar (1).

Let's start with the Testcase configuration view.

Testcase Configuration

The concept of the Testing is to define a set of Testcases which can be executed in a batch or individually. For this purpose, you can define multiple Testcases and configure them individually. I.e. each Testcase groups a number of indidivual tests which can be executed individually or in a batch.

Adding a Testcase

Click Add Testcase in the toolbar to add a new testcase:

A new Testcase is added. It is automatically named New<Service Asset Name>Test (3) and added to the list of Testcases (2).

• Service test name (3): You can change the name of the Testcase here.
• Service test description (4): You can add a description to the Testcase here.

Test Case Setup

Basics

In this section you define the individual tests to be executed for this Testcase.

To start, click # END in the toolbar:

A new test is added to the list of tests (1), and the test is opened for configuration (2).

Next we fill in the details:

• Test name (3): You can change the name of the Test here.

• Test description (4): You can add a description to the Test here.

• Service function to test (5): Select the Service function to test here.

  This list contains all Service functions which are defined in the Service Asset. Pick the one you want to test.

  

  Once a Service function is selected, the system will automatically create a skeleton to fill in the respective parameters for the selected Service function.

  

Service Function Input Parameters

• Service Function Input Parameters (6): Fill in the respective parameters for the selected Service function.

  In our example we have a function GetAlertsForSite which takes two parameters baseurl and riskId. If we click on Add member in the skeleton table the system will allow you to select the respective parameter from the list of available parameters:

  

  Once you have selected the parameter, the system will automatically add the respective parameter name. You then add the respective value for the parameter:

  

Service Function Evaluation Parameters

To automatically evaluate the result, you can add a script which analyzes the results.

Testcase Execution

Once you have configured your Testcases, you can execute them.

There are two ways on how to trigger execution:

• Option 1: Select Run selected test in the toolbar (1) to execute the currently selected Testcase.

  

  Executing a test this way will switch the tab to the Testcase execution view, execute the test and show the results.

• Option 2: Switch to the Testcase execution view by clicking on the leftmost icon in the toolbar (1) select the test to execute, and then hit the play button next to the test.

  

Each option will take us to the Testcase execution view:

In this view you can find the Testcase (1) and the Tests (2) we have created. If we had created additional tests for this Testcase, they would be listed here as well.

Question marks indicate that the test has not yet been executed.

We can now either execute all tests, or run them individually:

• Run all Tests (1): Click this button to execute all tests.

• Run Testcase (2): Click this button to a Testcase with all its underlying individual tests.

  

• Run individual Test (3): Click this button next to a test to execute this individual test.

  

Once a test has been executed, the question mark will be replaced by a green check mark or a red cross depending on whether the test was successful or not.

The right hand-panel will show the results of the test execution respectively:

In case of errors, the system will show the error message for further investigation.

---

Can't find what you are looking for?

Please note, that the creation of the online documentation is Work-In-Progress. It is constantly being updated. should you have questions or suggestions, please don't hesitate to contact us at [email protected] .