@elodigit/client

ELO Client for IX REST API

A simple and easy to use client for the ELO IX REST API

Features

• ✅ Typescript support

• ✅ Node.js and browser support

• ✅ Easy to use and setup with npm

• ✅ All enpoints available

• ✅ Reuse of existing browser sessions

• ✅ Async/await support

Installation

npm install @elodigit/client

Usage

Import and initialize a client using ELO login credentials.

import { Client } from "@elodigit/client";

// Initializing a client
const client = new Client({
  IX_URL: "http://playground.com/ix-Solutions",
  USERNAME: "Administrator",
  PASSWORD: "elo",
});
await client.connect();

OR reuse an existing ELO session (only available in browsers for e.g. web apps)

const client = new Client({
  IX_URL: "http://playground.com/ix-Solutions",
  USE_SESSION: true,
  REDIRECT: true,
});
await client.connect();

Make a request to any ELO API service/endpoint.

See the complete list of endpoints in the IX API Documentation

import { EditInfoC, LockC } from '@elodigit/client';

const response = await client.ix.checkoutSord({
  objId: "1",
  editInfoZ: EditInfoC.mbSord,
  lockZ: LockC.NO,
});

const sord = response.result?.sord;

Each method returns a Promise which resolves the response.

console.log(response);

{
  result: {
    sord: {
      TStamp: "2023.02.24.10.48.35",
      acl: "75PYJA",
      childCount: 0,
      doc: 33,
      guid: "(804CE708-8221-716F-7452-4FA201E7F858)",
      id: 1,
      kind: 1,
      mask: 0,
      name: "Solutions",
      ownerId: 0,
      parentId: 1,
      ...
    }
  }
}

Client options

The Client supports the following options on initialization. These options are all keys in the single constructor parameter.

Option	Default value	Type	Required	Description
IX_URL	undefined	string	true	Url to the IX service for connection e.g. https://playground.com/ix-Solutions
USERNAME	undefined	string | Resolver	false	ELO username for basic authentication. This authentication method is discouraged in the browser because there is no CSRF protection.
PASSWORD	undefined	string | Resolver	false	ELO password for basic authentication
TIMEOUT	10000	number	false	Connection timeout to ELO server in ms.
USE_SESSION	false	boolean	false	Reuses an existing session that's provided by e.g. the Java Client, Web Client, Mobile Client. This option is only available in browsers (e.g. for web apps)
REDIRECT	true	boolean	false	Redirects to the login page if session expires. Works only in combination with USE_SESSION
KEEP_ALIVE	true	boolean	false	Tries to keep the session alive by pinging the server every 60 seconds. Works only in combination with USE_SESSION or SESSION_TICKET
CLIENT_INFO	language=en country=US timezone=UTC	ClientInfo | Resolver	false	The ClientInfo object containing the users language and country
ELO_APPROVED	undefined	string | Resolver	false	CSRF token to send approved REST requests
WITH_CREDENTIALS	true	boolean	false	Option is used to include cookies in the request. Required for option USE_SESSION
SESSION_TICKET	undefined	string | Resolver	false	Session ticket that is used as Bearer-Header for authentication
HEADERS	undefined	Headers | Resolver	false	Additional custom headers for request

Resolver are async functions that can be passed instead of static values to the client. They provide the ability of resolving values at runtime.

async (options: ApiRequestOptions, config: OpenAPIConfig) => {
  return "Administrator";
};

Enable CORS

To enabled CORS add the "Access-Control-Allow-*" headers as entries in the Indexserver config.xml. At least "Access-Control-Allow-Origin" is requried. Example:

<entry key="Access-Control-Allow-Origin">*</entry>

TypeScript

This package contains type definitions for all request parameters and responses.

Constants

All ELO constants are available for e.g. endpoint requests. LockC.NO, SordC.mbAllIndex, etc.

Examples

Upload streams - Checkin a document

To upload a document/file, first upload the file to a temporary storage on the server using bUtility.upload. Then, use a subsequent checkin request to associate the temporary file with the repository object. This example can be applied to any file upload. You upload the file to a temporary storage on the server in order to get the streamId and then use it in the following steps for other actions.

Node.js example to upload a file:

import { EditInfoC } from "@elodigit/client";
import { readFileSync } from "fs";

// Path to the file we want to upload
const filePath = "/my/file/path.txt";

// Read file into buffer and convert to Blob for upload
const fileBuffer = await readFileSync(filePath);
const fileBlob = new Blob([fileBuffer]);

// Upload file to ELO and get a temporary streamId
const fileUploadResult = await client.bUtility.upload(fileBlob);
const streamId = fileUploadResult.result?.streamId;

Broser example to upload a file:

import { EditInfoC } from "@elodigit/client";

// File we want to upload
const fileInput = document.getElementById('fileInput') as HTMLInputElement;

if (!fileInput.files || fileInput.files.length === 0) {
  console.log("No file selected");
  return;
}

const file = fileInput.files[0];

// Convert to Blob for upload
const fileBlob = new Blob([fileBuffer]);

// Upload file to ELO and get a temporary streamId
const fileUploadResult = await client.bUtility.upload(fileBlob);
const streamId = fileUploadResult.result?.streamId;

Folloing applies to both Node.js and Browser:

// Create a new document in ELO (only metadata at this point)
const createDocResult = await client.ix.createDoc({
  parentId: "1",
  maskId: "0",
  editInfoZ: EditInfoC.mbSordDocAtt,
});

const sord = createDocResult.result?.sord;

if (!sord) {
  console.log("No sord found");
  return;
}

sord.name = "My Sord Name";

// Finally, attach the uploaded file to the document metadata
await client.ix.checkinDocEnd({
  sord,
  sordZ: EditInfoC.mbAll,
  document: {
    docs: [
      {
        version: "1.0",
        comment: "My Comment",
        contentType: "text/plain",
        fileData: {
          stream: {
            streamId, // <- Link to previously uploaded file
          },
        },
      },
    ],
  },
});

Create path

To create a path in ELO, you can use the checkinSordPath method. This method creates a path in the repository and returns the sord ids of the created path segments.

import { Sord, SordC } from "@elodigit/client";

const arcPath = "the/path/to/create";

// Create an array of Sord objects for each path segment
const sords: Sord[] = arcPath.split("/").map<Sord>((name) => ({
  name,
}));

// Check in the path and get the sord ids
const result = await client.ix.checkinSordPath({
  parentId: "1",
  sords,
  sordZ: SordC.mbAll,
});
const sordIds = result.result;

console.log("Sord ids", sordIds);

Execute Registered Function

Execute a registered function in ELO. The function name and parameters are passed as arguments to the executeRegisteredFunctionString method. Alternatively, you can use the executeRegisteredFunction method to pass the parameters as an Any object.

const param = {
  param1: "value1",
  param2: "value2",
};

const result = await client.ix.executeRegisteredFunctionString({
  functionName: "RF_my_demo_function",
  param: JSON.stringify(param),
});
console.log(result);

Versioning

The versioning follows the NPM standard versioning with an ELO IX version suffix structure:

<NPM_MAJOR>.<NPM_MINOR>.<NPM_PATCH>-elo<ELO_MAJOR>.<ELO_MINOR>.<ELO_PATCH>

Example for ELO IX Version 23.05.001 and your own version 1.0.0:

1.0.0-elo23.05.001

Meaning:

• 1.0.0 → Version of the generator that was used to generate the client
• -elo23.05.001 → Indicates that this client was generated using ELO IX Version 23.05.001 and is compatible with it