dbsis-rest

REST-style Node.js client and HTTP gateway for the Lithuanian DBSIS (Dokumentų valdymo bendroji informacinė sistema) SOAP API.

DBSIS exposes ~85 SOAP operations across 11 web services (RDODocumentWS, OrgStructWS, ClassifierWS, JournalWS, OfficeCaseWS, TemplateWS, TDODocumentWS, …). Calling them directly requires:

• hand-crafted SOAP 1.1 envelopes with WS-Security UsernameToken authentication,
• xsi:type annotations on every Map entry value so the server picks the right Java class,
• careful namespace bookkeeping (org:, cls:, jrl: …),
• MTOM-style base64 attachments,
• parsing the SOAP response into something usable.

This package handles all of the above and lets you call any operation as a JS function or as a JSON HTTP request:

const { createClient } = require('@aplinkosministerija/dbsis-rest');

const dbsis = createClient({
  baseUrl: process.env.DBSIS_BASE_URL,        // https://dbsis.lt/dbsis
  username: process.env.DBSIS_USERNAME,
  password: process.env.DBSIS_PASSWORD,
});

const { documentInfo } = await dbsis.documents.createDocumentFromTemplate({
  documentFromTemplateParam: {
    docAttributes: {
      entry: [
        { key: 'title', value: { $type: 'xs:string', $text: 'My title' } },
        { key: 'receivers', value: {
            $type: 'org:OrgNodeListParam',
            orgNode: { $type: 'org:OrgNodeCodeParam', code: '188774822' },
        }},
      ],
    },
    templateParam: { oid: 'inc1.188774822' },
    register: false,
    project: false,
  },
});

console.log(documentInfo.oid); // -> "c89099f0bec611e593e2d8d76fa79d4c"

Or run the bundled REST gateway and call each operation as JSON:

DBSIS_BASE_URL=https://dbsis.lt/dbsis \
DBSIS_USERNAME=integration_user \
DBSIS_PASSWORD=...                   \
npx dbsis-rest serve

curl -X POST http://localhost:3000/api/documents/getDocument \
  -H 'content-type: application/json' \
  -d '{"getDocumentParam":{"docOid":"c89099f0..."}}'

The gateway and the JS client share the same operation catalogue, so anything documented in the DBSIS spec can be invoked uniformly.

Installation

npm install @aplinkosministerija/dbsis-rest

Node.js ≥ 18 is required.

Configuration

Configuration is read from environment variables only — credentials are never hard-coded or sent over HTTP from the gateway. Copy .env.example to .env and fill in real values:

| Variable | Required | Notes | | --- | --- | --- | | DBSIS_BASE_URL | yes | e.g. https://dbsis.lt/dbsis. The package appends the per-service path (/RDODocumentsWs, /OrgStructWs, …) automatically — see Service URL mapping below. | | DBSIS_USERNAME | yes | Dedicated integration user as recommended by the DBSIS team. | | DBSIS_PASSWORD | yes | The password is sent in WS-Security UsernameToken / PasswordText form, so HTTPS is mandatory. | | DBSIS_TIMEOUT_MS | no | HTTP timeout, default 60 000 ms (matches DBSIS server-side timeout). | | PORT | no | Gateway port, default 3000. | | GATEWAY_TOKEN | no | If set, the REST gateway requires Authorization: Bearer <token> on every request. |

Recommended: do not check .env into git. The package ships with a .gitignore that excludes it.

Service URL mapping

The DBSIS guide (Priedas Nr. 1) says the SOAP URL is <base>/<ServiceName> and the WSDL list lives at <base>/ws-cxf. The package uses these defaults — override them via the servicePaths constructor option if your installation is non-standard.

| Alias | Prefix | Path | DBSIS service | | --- | --- | --- | --- | | documents | rdod | /RDODocumentsWs | RDODocumentWS — registered documents | | tasks | tdod | /TDODocumentsWs | TDODocumentWS — tasks | | contracts | cdod | /CdoDocumentsWs | Contracts (sutartys) | | subst | subs | /SubstDocumentsWs | SubstDocumentWS — pavadavimai | | org | org | /OrgStructWs | OrgStructWS | | classifiers | cls | /ClassifierWs | ClassifierWS | | journals | jrl | /JournalWs | JournalWS — registers | | officeCases | ofc | /OfficeCaseWs | OfficeCaseWS — bylos | | templates | tpl | /TemplateWs | TemplateWS | | documentSorts | dso | /DocumentSortWs | DocumentSortWS | | linkTypes | lnk | /LinkTypeWs | LinkTypeWS |

Programmatic API

const { createClient } = require('@aplinkosministerija/dbsis-rest');
const dbsis = createClient({ baseUrl, username, password });

// Each service exposes one async method per documented SOAP operation:
await dbsis.documents.getDocument({ getDocumentParam: { docOid: '...' } });
await dbsis.org.getOrgUnit({ orgName: 'org.lt.root' });
await dbsis.classifiers.getClsEntryList({ getClsEntryListParam: { className: 'clsDocPrivacy' } });

// Operation discovery:
dbsis.documents.$operations;       // [ 'createDocumentFromTemplate', 'getDocument', ... ]
dbsis.documents.$invoke(name, p);  // dynamic dispatch by string name

// Low-level escape hatch — call any SOAP operation, even one not in the
// catalogue, on any service prefix:
await dbsis.invoke({
  servicePrefix: 'rdod',
  operation: 'getDocument',
  params: { getDocumentParam: { docOid: '...' } },
  extraNamespaces: ['doc'],
});

Building request payloads

The DBSIS SOAP body uses two non-trivial XML constructs — Map entries with typed values, and namespaced child elements. The package exposes them through three special object keys:

| Key | Effect | | --- | --- | | $type | Adds xsi:type="<value>" to the element. Use a prefix that matches a known namespace (xs:string, org:OrgNodeListParam, …). The relevant xmlns: declaration is added to the envelope automatically. | | $text | Inline text content. Useful when you also need attributes. | | $attrs | Plain XML attributes (e.g. wsu:Id). |

Arrays produce repeating sibling elements — exactly what the DBSIS entry/item/receivers lists need:

{
  docAttributes: {
    entry: [
      { key: 'title', value: { $type: 'xs:string', $text: 'Hello' } },
      { key: 'note',  value: { $type: 'xs:string', $text: 'World' } },
    ],
  },
}

Buffer values are automatically base64-encoded — useful when uploading ADOC/PDF attachments via bodyAttachment.content.

null becomes xsi:nil="true". Dates become ISO-8601 strings.

Errors

Any SOAP Fault is thrown as SoapError (extends Error):

const { SoapError } = require('@aplinkosministerija/dbsis-rest');
try { ... }
catch (err) {
  if (err instanceof SoapError) {
    console.error(err.message);   // faultstring
    console.error(err.faultCode); // optional
    console.error(err.detail);    // optional <detail> contents
  }
}

HTTP-level failures (timeout, 5xx without a SOAP body, etc.) also surface as SoapError with a status and responseBody.

REST gateway

npx dbsis-rest serve
# or
node scripts/cli.js serve

| Method | Path | Body | Description | | --- | --- | --- | --- | | GET | /health | — | { ok: true } | | GET | /api/operations | — | Machine-readable catalogue of every registered operation. | | POST | /api/<service>/<operation> | JSON | Same params object as the JS API. Returns { ok: true, result: ... } or { ok: false, error, soap }. |

The <service> segment accepts both the alias (documents) and the short prefix (rdod).

If GATEWAY_TOKEN is set, every request must include Authorization: Bearer <token>.

Catalogue

Run node scripts/cli.js list to print every supported operation grouped by service — same set the gateway exposes.

Receiving DBSIS callbacks (receiveDhsEvent, receiveDhsTaskEvent)

DBSIS calls your system back when a document/task changes state. The taikymo aprašymas (§3.2) and the spec (§2.18) describe the expected ReceiveDhsEventParam / ReceiveDhsTaskEventParam payload and the ReceiveDhsEventResult shape you must return.

This package does not run a SOAP server for you — that is intentional, because the URL, port, certificates and side-effects belong to your application. A complete reference example using only the standard library is in examples/receive-dhs-event-server.js (forthcoming): parse the envelope with parseSoapResponse, do your work, and reply with a SOAP envelope containing ReceiveDhsEventResult (statusCode, errorMessage, persistentError).

Development

npm install
npm test          # node:test, no external test runner
npm run start     # runs `dbsis-rest serve` against env vars

Mapping back to the spec

Every operation in src/services/operations.js has a docSection field that points to the chapter in DBSIS_SOAP_API_20250114_v3.0.docx. If a method is missing or its body shape is unclear, that is the place to look first.

Security notes

• Credentials never leave process.env. The REST gateway never accepts SOAP credentials in the request body. If you expose the gateway externally, set GATEWAY_TOKEN and front it with TLS.
• WS-Security UsernameToken sends the password as PasswordText. DBSIS itself recommends running over HTTPS — do not call the SOAP endpoint over plain HTTP.
• Templates, sender/receiver codes, OIDs etc. are not secrets in themselves but identify documents in your tenant. Treat the JSON request bodies you log accordingly.

License

MIT.