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