TROIA Web Service Guide: Understanding Session, callService, Encryption, and Response

TROIA Web Service is a small but critical integration layer. This guide clarifies the session model, callService flow, XML parameters, and how to read responses with encryption/compression in mind.

Quick overview

The flow is simple: login creates a session, callService runs a TROIA class method, and CaniasResponse returns the data. The traps are in the details.

login() opens the session; work happens in callService().
Every call carries SessionId and SecurityKey.
Responses are wrapped in CaniasResponse, not a single string.
Encryption/compression are optional and must be handled consistently.

login(): session and security keys

A successful login returns SessionId and SecurityKey; encrypted sessions also return EncryptionKey.

Persist SessionId and SecurityKey for each call.
Send Encrypted=true only if you will actually encrypt.
Handle EncryptionKey as UTF-8 bytes before use.

callService(): the core invocation

callService executes a registered TROIA class method. ServiceId and Parameters are where most mistakes happen.

ServiceId selects the registered method.
Parameters is an XML string payload.
Compressed and Permanent flags change behavior.
ExtraVariables and RequestId are helpful for tracking.

Parameters XML: primitive, base64, CDATA

Parameters are passed as <PARAMETERS> with <PARAM> entries. encoding="base64" is supported; CDATA helps for special chars.

Primitive values need no type attribute.
Base64 is decoded to UTF-8 on the server.
CDATA avoids parser issues for special characters.

Table and vector payloads

Use TYPE="TABLE" or TYPE="VECTOR" to send structured data. The server converts the XML into symbols.

Tables are sent as rows/columns.
Vectors use name/type/value items.
Keep the XML hierarchy intact to avoid parse errors.

Reading CaniasResponse

Response, SYSStatus, Messages, and ExtraVariables must be read together, especially when compression is used.

Response is StringResponse with Value + Compressed flag.
SYSStatus and SYSStatusError provide execution state.
Messages and ExtraVariables are XML payloads.
RequestId echoes the call for correlation.

Encryption vs compression

Encryption is opt-in; compression is applied based on size and is not used for encrypted data.

Encrypted connections use AES/CBC/PKCS7/128.
Compression happens beyond the size threshold.
If both are used, follow the documented order.

Cheat sheet

A quick list of the fields and flags that cause the most confusion.

login response: Success, SessionId, SecurityKey, EncryptionKey.
callService input: SessionId, SecurityKey, ServiceId, Parameters, Compressed, Permanent, ExtraVariables, RequestId.
CaniasResponse: Response, SYSStatus, SYSStatusError, Messages, ExtraVariables, RequestId.

Related pages: