eregistrations-js

A JavaScript library that simplifies usage of eRegistrations APIs.

Installation

From NPM Registry

# Install as dependency in your project
npm install eregistrations-js

From Bitbucket Repository

Global Installation

# Install latest version
npm install -g https://bitbucket.org/unctad/ai-tools.git

# Install specific version/tag
npm install -g https://bitbucket.org/unctad/ai-tools.git#v2.2.0

Local Installation

# Install latest version
npm install https://bitbucket.org/unctad/ai-tools.git

# Install specific version/tag
npm install https://bitbucket.org/unctad/ai-tools.git#v2.2.0

For Development (if you have repository access)

# Using SSH (requires SSH key setup)
git clone [email protected]:unctad/ai-tools.git
cd ai-tools
npm install

Configuration

Environment Variables

Create a .env file in your project root with the following variables:

# BPA API variables
BPA_API_URL=https://bpa.your-domain.com
TOKEN=your-access-token-here
SERVICE_ID=your-service-id

# GDB API variables (if using GDB functions)
GDB_API_URL=https://gdb.your-domain.com
GDB_TOKEN=your-gdb-access-token

See .env.example for a template.

Usage

This package uses CommonJS module system, so you can require it in your Node.js application:

Importing the Library

CommonJS

// CommonJS require - All functions
const eregistrations = require('eregistrations-js');

// Or import specific functions
const { 
  // BPA API functions
  getServiceDeterminants, 
  createDeterminant,
  addDeterminantToComponent,
  getServiceRegistrations, 
  getServiceFields, 
  getServiceNames, 
  getServiceBots, 
  getServiceRoles,
  getServiceForms,

  // GDB API functions
  createOrModifyDatabase,
  getDatabaseSchema,
  getList,

  // Types
  Config,
  GdbConfig
} = require('eregistrations-js');

TypeScript/ES Modules

// TypeScript import - All functions
import * as eregistrations from 'eregistrations-js';

// Or import specific functions
import { 
  // BPA API functions
  getServiceDeterminants, 
  createDeterminant,
  addDeterminantToComponent,
  getServiceRegistrations, 
  getServiceFields, 
  getServiceNames, 
  getServiceBots, 
  getServiceRoles, 
  getServiceForms,

  // GDB API functions
  createOrModifyDatabase,
  getDatabaseSchema,
  getList,

  // Types
  Config,
  GdbConfig
} from 'eregistrations-js';
import { config as loadEnv } from 'dotenv';

// Load environment variables
loadEnv();

Configuration

BPA API Configuration

const bpaConfig: Config = {
  baseApiUrl: process.env.BPA_API_URL!,
  token: process.env.TOKEN!, // Access token is required
  serviceId: process.env.SERVICE_ID
};

GDB API Configuration

const gdbConfig: GdbConfig = {
  baseApiUrl: process.env.GDB_API_URL!,
  token: process.env.GDB_TOKEN!, // Access token is required
  catalogName: 'MyDatabase',
  code: 'MDB',
  version: 1
  // Additional properties as needed
};

Authentication

Starting from version 2.0.0, this library no longer handles authentication internally. You must provide a valid access token directly in the config object for both BPA and GDB APIs. You are responsible for obtaining and refreshing the tokens as needed from your authentication provider.

BPA API

The Business Process Automation (BPA) API provides functionality for managing services, determinants, forms, and more.

BPA Examples

Getting Service Determinants

try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const determinants = await getServiceDeterminants(config);
  console.log('Service determinants:', determinants);
} catch (error) {
  console.error('Error:', error);
}

Creating a Determinant

try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!,
    determinantName: "MyTextDeterminant",
    targetFormFieldKey: "someField",
    operator: "EQUALS",
    value: "someValue",
    type: "text"
  };

  const newDeterminant = await createDeterminant(config);

  console.log('Created determinant:', newDeterminant);
} catch (error) {
  console.error('Error:', error);
}

Adding a Determinant to a Component

try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!,
    determinantId: "your-determinant-id",
    formId: "your-form-id",
    componentKey: "your-component-key"
  };

  const result = await addDeterminantToComponent(config);

  console.log('Determinant added to component:', result);
} catch (error) {
  console.error('Error:', error);
}

Getting Service Registrations

try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const registrations = await getServiceRegistrations(config);
  console.log('Service registrations:', registrations);
} catch (error) {
  console.error('Error:', error);
}

Getting Service Fields

try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const fields = await getServiceFields(config);
  console.log('Service fields:', fields);
} catch (error) {
  console.error('Error:', error);
}

Getting All Service Names

try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!
  };

  const services = await getServiceNames(config);
  console.log('All services:', services);
} catch (error) {
  console.error('Error:', error);
}

Getting Service Bots

try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const bots = await getServiceBots(config);
  console.log('Service bots:', bots);
} catch (error) {
  console.error('Error:', error);
}

Getting Service Roles

try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const roles = await getServiceRoles(config);
  console.log('Service roles:', roles);
} catch (error) {
  console.error('Error:', error);
}

Getting Service Forms

try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const forms = await getServiceForms(config);
  console.log('Service forms:', forms);
} catch (error) {
  console.error('Error:', error);
}

GDB API

The Generic Database (GDB) API provides functionality to interact with the Generic Database service, allowing you to create and manage databases.

GDB Examples

Creating or Modifying a Database

try {
  const config: GdbConfig = {
    baseApiUrl: process.env.GDB_API_URL!,
    token: process.env.GDB_TOKEN!,
    catalogName: 'MyDatabase',
    code: 'MDB',
    version: 1,
    schema: {
      type: 'object',
      properties: {
        ID: {
          type: 'string',
          triggers: [
            {
              conditions: [
                {
                  logic: '==',
                  value: '',
                  gate: '&&'
                }
              ],
              actions: [
                {
                  type: 'set-value',
                  value: '{code}{indexNoByCode}',
                  field_id: 1
                },
                {
                  type: 'upper-case',
                  field_id: 1
                }
              ]
            }
          ],
          primaryKey: true,
          readOnly: true,
          $id: 1
        },
        Name: {
          type: 'string',
          $id: 2
        }
      },
      required: ['ID', 'Name'],
      $incrementIndex: 2
    },
    schemaTags: [
      {
        name: '',
        path: '/ID',
        is_fulltext: true
      },
      {
        name: '',
        path: '/Name',
        is_fulltext: true
      }
    ],
    schemaFlags: [
      {
        name: 'unique',
        path: '/ID'
      },
      {
        name: 'mandatory',
        path: '/ID'
      },
      {
        name: 'mandatory',
        path: '/Name'
      }
    ],
    isDraft: true
  };

  const result = await createOrModifyDatabase(config);
  console.log('Database created or modified:', result);
  console.log('Database link:', result.link);
} catch (error) {
  console.error('Error:', error);
}

Getting Database Schema

try {
  const config: GdbConfig = {
    baseApiUrl: process.env.GDB_API_URL!,
    token: process.env.GDB_TOKEN!,
    databaseId: '123' // Replace with actual database ID
  };

  const schema = await getDatabaseSchema(config);
  console.log('Database schema:', schema);
  console.log('Schema structure:', schema.schema);
} catch (error) {
  console.error('Error:', error);
}

Querying Data from a Database

try {
  const config: GdbConfig = {
    baseApiUrl: process.env.GDB_API_URL!,
    token: process.env.GDB_TOKEN!,
    code: 'MyDatabaseCode', // The database code to query
    query: 'query.Name=John' // The query parameter to filter results
  };

  const results = await getList(config);
  console.log('Query results:', results);
  
  // You can access individual records if the result is an array
  if (Array.isArray(results) && results.length > 0) {
    console.log('First record:', results[0]);
  }
} catch (error) {
  console.error('Error:', error);
}

Paginated Queries with page_size

try {
  const config: GdbConfig = {
    baseApiUrl: process.env.GDB_API_URL!,
    token: process.env.GDB_TOKEN!,
    code: 'MyDatabaseCode',
    query: 'query.Status=Active', // Filter for active records
    page_size: 10 // Limit to 10 results per page
  };

  const results = await getList(config);
  console.log('Paginated results:', results);
  
  // The API may return results in a structured format with pagination info
  if (results.results && Array.isArray(results.results)) {
    console.log(`Showing ${results.results.length} of ${results.count} total records`);
    console.log('Current page:', results.currentPage);
    console.log('Has next page:', results.next !== null);
  }
} catch (error) {
  console.error('Error:', error);
}

Requirements

• Node.js >= 20.11.19

Development

1. Clone the repository
2. Install dependencies: npm install
3. Create a .env file with your configuration (see .env.example)
4. Run tests: npm test
5. Build: npm run build

Major Changes in Version 2.0.0

• Removed internal authentication handling - you must now provide a valid token directly
• Simplified the Config interface by removing authUrl, realm, and credentials properties
• Made the token property required in the Config interface
• Fixed API endpoint URLs for various services

Changes in Version 2.2.0

• Added new getDatabaseSchema function to the GDB API for retrieving database schema information
• Fixed issues with database creation and schema retrieval
• Improved test coverage for GDB functionality

Changes in Version 2.3.0

• Added new getList function to the GDB API for querying data from a database
• Enhanced GDB functionality with filtering capabilities using the query parameter

Changes in Version 2.4.0

• Enhanced getList function with pagination support through the page_size parameter
• Improved URL construction for cleaner and more efficient API requests

License

MIT