Other Qorus Integration Objects

Table of Contents

• Introduction
• Class Objects
  • Class Name
  • Class Version
  • Class Patch
  • Class Description
  • Class Author
  • Class Language
  • Class Source
  • Class Dependencies
  • Class Configuration Items
  • Class Connectors
    • Class Connector Name
    • Class Connector Method
    • Class Connector Type
    • Class Connector Input
    • Class Connector Output
  • Class Processor
• Library Objects
• Asynchronous Queue Objects
  • Updating Asynchronous Queue Entries
• Interface Group Objects
• Workflow Synchronization Event Objects

Back to the Developer's Guide Table of Contents

Introduction

All Qorus integration objects are described by YAML metadata produced by our IDE, which is available as a free (as in free of charge and also open source) extension to Microsoft Visual Studio Code, a multi-platform editor from Microsoft. The Qorus extension is called Qorus Developer Tools and can be installed directly from Visual Studio Code.

Class Objects

Class definition files containing YAML metadata and a reference to the source code file are used to create class objects in the Qorus schema that can then be used by other integration objects, such as workflows, services, jobs, mappers, or even other class objects.

Class objects are the fundamental building block element of Qorus; they allow their code to be instrumented with configuration that should be designed to make them generically useful for many different use cases, and enable changes to be made with configuration rather than coding.

Class definition files are parsed by the oload program, which will create class objects in the Qorus database according to the definitions in the file.

Classes have the following attributes:

• Class Name
• Class Version
• Class Patch
• Class Description
• Class Author
• Class Language
• Class Source
• Class Dependencies
• Class Configuration Items
• Class Connectors
• Class Processor

Class Name

The name of the class; the name and version together are unique identifiers for the class and are used to derive the classid (the single unique identifier for the class; it is generated from a database sequence when the class is loaded into the system via oload).

Multiple classes with the same name and different versions can exist in the system at the same time. Classes are referred to with their classid, which is derived from the name and version together (except in Library Objects, where the latest version of the class is used which is determined by the last creation date of the class object in the database, and not with a comparison of the version strings).

Class Version

The version string for the class object; the name and version together are unique identifiers for the class and are used to derive the classid (the single unique identifier for the class; it is generated from a database sequence when the class is loaded into the system via oload).

Note

Two objects with the same name but different version values are different objects

Class Patch

A string "patch" label which can be used to show that a class was updated while not affecting the classid.

Note

The patch value can be updated without affecting references to other objects; the unique ID for the object is not updated when the patch value is updated

Class Description

A description for the class; the description field supports markdown for formatted output in the UI and IDE.

Class Author

The "author" value indicates the author of the class and will be returned with the class metadata in the REST API and also is displayed in the system UI.

Class Language

The programming language for the class's source code; can be one of:

• python
• java
• qore

Class Source

The source code for the class implementation; must be in the programming language specified by Class Language

The source can use other source code; see Class Dependencies

Class Dependencies

An optional list of classes that the class depends on; these other classes are also loaded into the interface's logic container when the class is listed as a dependency; in this way a single class can encapsulate multiple class object dependencies, which can simplify dependency management for complex class hierarchies and in interconnected code.

Class Configuration Items

Configuration items are metadata describing configurable parameters that should define how the code of the class is executed at runtime.

Configuration items have a name, a description (supporting markdown), a data type, and other attributes.

Configuration item values can be set at three levels, the global level, the workflow level, and the configuration item level. The value used is the lowest-level value set.

The runtime value of a configuration item can be retrieved with the APIs in the following table:

Configuration Item Value APIs

API Type	API	Description
Python	wfapi.getConfigItemValue()	retrieves a single configuration item value
Python	wfapi.getConfigItemHash()	retrieves all configuration items
Java	WorkflowApi.getConfigItemValue()	retrieves a single configuration item value
Java	WorkflowApi.getConfigItemHash()	retrieves all configuration items
Qore	WorkflowApi::getConfigItemValue()	retrieves a single configuration item value
Qore	WorkflowApi::getConfigItemHash()	retrieves all configuration items

See also

Config Items: Code to No-Code Runtime Configuration for Your Code

Class Connectors

Class connectors are defined in class metadata and enable the class to be connected to other classes. They can also declare input and output data types to ensure type-safe processing when processing data as well.

Class connectors have the following attributes:

Class Connector Attributes

Key	Mand.?	Description
name	Y	The name of the connector; this name will be used when choosing the connector
method	Y	The name of the class method that will be called; this must correspond to a real method in the class
type	Y	The type of connector; describes how the connector can be used
input type	N	The input data type for the connector
output type	N	The output data type for the connector

Class Connector Name

The name of the connector used when choosing the connector in the IDE or displaying it in the UI.

The connector name is stored in the YAML and is used to reference the connector in other objects.

Note

Changing the connector name will break references in other objects; the best practice is to use the same connector name as the connector method and to leave it unchanged.

Class Connector Method

The name of the class method that will be called; must correspond to a real method in the class.

Connector Method Parameters

Note that the input data for a class connector is always a single value; the method should declare at most one parameter corresponding to the input type, if any.

If the class connector accepts input data but ignores the data, it should declare a single argument that accepts all values.

If the class connector does not accept input data, it should not declare a parameter.

Connector Method Return Value

The return value for a connector should correspond to its output type, if any.

Note

The best practice is to use the same connector name as the connector method and to leave it unchanged; changing the connector method name will break any code referencing the connector method.

Class Connector Type

Connector Type	Description
event	Event-based connectors provide an event source and can only be used in services
input	Input connectors can be connected to a preceding connector in a chain but provide no output data and cannot have any further connectors after them
output	Output connectors do not accept any input data and must be the first connector in a chain, as they cannot be connected to a previous connector. They can produce output data.
input-output	A generic connector that can be connected anywhere in a chain
condition	A connector that returns a boolean value, meant to be used as the logic in a state transition in a finite state machine

Event connectors

Event connectors should be declared in a class that inherits one of the following classes:

• Python / Java / Qore: Observable or DelayedObservable

When the event must be raised, call the appropriate method as follows:

• Python / Java / Qore: Observable::notifyObservers()

Class Connector Input

Input connectors can be connected to a preceding connector in a chain but provide no output data and cannot have any further connectors after them.

An input connector must be the last connector in a chain.

Input connectors may ignore their input data.

Class Connector Output

Output connectors do not accept any input data and must be the first connector in a chain, as they cannot be connected to a previous connector. They can (but do not necessarily have to) produce output data.

Class Processor

When a class declares processor compatibility, it allows the class object to be used in a data pipeline.

In this case, the class must inherit one of the following classes depending on the source language:

• Python / Qore: AbstractDataProcessor
• Java: AbstractDataProcessor

Class processors can be used to filter, generate, or transform input records in a data pipeline and can also declare their input and output record types to ensure that type safety is enforced in the pipeline.

Note

Mappers are a special form of data processor that performs data transformations based on configuration.

Example Python Processor Class

from qore.DataProvider import AbstractDataProcessor
 
class ExamplePythonProcessor(AbstractDataProcessor):
    def __init__(self):
        super(AbstractDataProcessor, self).__init__()
 
    def submitImpl(self, enqueue, data):
        UserApi.logDebug("processer called with data: %y", data)
        # pass the same hash with "x-" prepended to each key onward
        enqueue({("x-" + k): v for k, v in data.iteritems()})
 
    def supportsBulkApiImpl(self):
        return True

Example Java Processor Class

import org.qore.lang.dataprovider.AbstractDataProcessor;
 
import qore.OMQ.UserApi.UserApi;
 
import java.util.Map;
import java.util.stream.Collectors;
 
class ExampleJavaProcessor extends AbstractDataProcessor {
    protected Object submitImpl(QoreClosureMarkerImpl enqueue, Object data) throws Throwable {
        UserApi.logInfo("processer called with data: %y", data);
        Hash rec = (Hash)data;
        // pass the same hash with "x-" prepended to each key onward
        enqueue.call(rec.entrySet().stream().collect(
            Collectors.toMap(e -> "x-" + e.getKey(), Map.Entry::getValue)
        ));
    }
 
    protected boolean supportsBulkApiImpl() {
        return true;
    }
}

Example Qore Processor Class

%new-style
%strict-args
%require-types
%enable-all-warnings
 
class ExampleQoreProcessor inherits AbstractDataProcessor {
    private auto submitImpl(code enqueue, auto rec) {
        UserApi::logInfo("processer called with data: %y", rec);
        # pass the same hash with "x-" prepended to each key onward
        enqueue(map {"x-" + $1.key: $1.value}, rec.pairIterator());
    }
 
    private bool supportsBulkApiImpl() {
        return True;
    }
}

Library Objects

Library objects are code objects that are refenced by name only (meaning no version or ID) from other objects, to be loaded in to the target interface object's program container to provide additional code and configuration.

The primary type of library object is the class. Also supported for backwards compatibility are constant and function objects.

If mutiple versions of a library object are present in the system, then the last version of the object is used in interfaces that require it, whereas the last version is determined by the most recent creation date of the object in the database; no version comparison is performed.

Note

Since class objects can depend on other class objects, establishing a dependency on any given class can result in an arbitrary number of additional classes being loaded into the requiring interface program container.

Asynchronous Queue Objects

Queues provide the storage and delivery mechanism by which the results of executing an asynchronous event for an asynchronous step are delivered to the right step instance.

If a workflow has at least one asynchronous step, a queue must be defined. A single queue can be used for any number of asynchronous steps, however the keys in a queue must be unique. See the step queue attribute for more information.

Updating Asynchronous Queue Entries

When an asynchronous queue entry is updated, processing continues for the affected orders; at that time the updated queue data is sent to the waiting step's back end logic for further processing.

Queue entries for specific waiting asynchronous steps can be updated with the following APIs:

• Qorus DataProvider API: Post Async Queue
• POST /api/latest/async-queues/{queue}?action=update

Interface Group Objects

Interface group files provide the metadata for an interface group.

These groups can then be referenced by interface objects who can claim to be members of the group.

Workflow Synchronization Event Objects

Workflow synchronization event objects are required for workflow synchronization event steps.