@elastic.io/oih-standard-library

OIH Standard Library

Table of Contents

• Actions
  • Upsert Object
  • Lookup Object (at most 1)
  • Lookup Objects (Plural)
  • Delete Object
• Triggers
  • Get New and Updated Objects Polling
  • Webhooks

Actions

Upsert Object

Create Object

Similar to upsert object but needed for the following cases:

• Objects that can be created but can not be updated after creation (e.g. Invoices)
• Cases where you want to create an object and its children
• Cases where the id of the object includes information in the object (e.g. The ID of a sales line is the sales order ID + SKU).

Example Use Case

See above.

Lookup Object (at most 1)

For implementing LookupObject action in most cases you need to extend from LookupObjectById or LookupObjectByUniqueCriteria classes. If you need completely custom behaviour you can extend from LookupObject class and override process and lookupObject method, in this case following OIH standard is your responsibility.

Lookup Object By Id

Note:

• Its your responsibility to ensure that lookupObject returns only 1 object. This implementation assume that id is unique for objectType.
• lookupObject method must return null to indicate that object hasn't been found.

1. Create Action
2. Create class that extends LookupObjectById class
3. Override lookupObject() methods. Example below.
4. Optional override getType and getId methods. Default implementation expects objectType to be present in input configuration and id in input message.
5. Create instance of your class and pass logger to constructor. const myLookupByIDImpl = new MyLookupByIdImpl(logger);
6. Export myLookupByIDImpl.process(msg, cfg, snapshot) as process method. Example below.

Example of Usage

Works in sailor > 2.4.2 Lookup Action

const { LookupById } = require('@elastic.io/oih-standard-library/lib/actions/lookupObject');

class MyLookupByIDImpl extends LookupById {


  async lookupObject(id, objectType, cfg, msg) { // In most cases you need just id, type and cfg
    const result = await lookupObjectInAPI(id,  objectType, cfg, msg); // Lookup object
    return result; // Return found object. If you return null, it will indicate no object found.
  }
  // You can also override getType and getId methods if needed
}
   

async function process(msg, cfg, snapshot = {}) {
  const lookupAction = new MyLookupByIDImpl(this.logger); // Sailor version > 2.4.2
  return lookupAction.process(msg, cfg, snapshot);
}

module.exports.process = process;

Lookup Object By Unique Criteria

Note:

• In case when lookupObject method has found more than 1 object it must return an array or throw error.
• lookupObject method must return null to indicate that object hasn't been found.

1. Create Action
2. Create class that extends LookupObjectByUniqueCriteria class
3. Override lookupObject() methods. Example below.
4. Optional override getType and getCriteria methods. Default implementation expects objectType to be present in input configuration and id in input message.
5. Create instance of your class and pass logger to constructor. const myLookupObjectByUniqueCriteriaImpl = new MyLookupObjectByUniqueCriteriaImpl(logger);
6. Export myLookupObjectByUniqueCriteriaImpl.process(msg, cfg, snapshot) as process method. Example below.

Example of Usage

Works in sailor > 2.4.2 Lookup Action

const { LookupByUniqueCriteria } = require('@elastic.io/oih-standard-library/lib/actions/lookupObject');

class  MyLookupObjectByUniqueCriteriaImpl extends  LookupByUniqueCriteria {


  async lookupObject(criteria, objectType, cfg, msg) { // In most cases you need just criteria, type and cfg
    const result = await lookupObjectInAPI(id,  objectType, cfg, msg); // Lookup object
    if (result instanceof Array) {
      // return it or throw error. If result.length > 1 error will be thrown by action  
  } 
  return result; // Return found object. If you return null, it will indicate no object found.
  }
  // You can also override getType and getCriteria methods if needed
}
   

async function process(msg, cfg, snapshot = {}) {
  const lookupAction = new MyLookupObjectByUniqueCriteriaImpl(this.logger); // Sailor version > 2.4.2
  return lookupAction.process(msg, cfg, snapshot);
}

module.exports.process = process;

Lookup Objects (Plural)

Delete Object

For implementing Delete action in most cases you need to extend from DeleteById or DeleteByUniqueCriteria classes. If you need completely custom behaviour you can extend from Delete class and override process and deleteObject method, in this case following OIH standard is your responsibility.

Delete By ID

Note:

• Its your responsibility to ensure that deleteObject deletes only 1 object. This implementation assume that id is unique for objectType.
• If deleteObject method is returning null empty object would be emitted. You can indicate with null that object hasn`t been deleted or found.

1. Create Action
2. Create class that extends DeleteById class
3. Override deleteObject() methods. Example below.
4. Optional override getType and getId methods. Default implementation expects objectType to be present in input configuration. For unique criteria: uniqueCriteria field name in input configuration and value in input message.
5. Create instance of your class and pass logger to constructor. const myDeleteByIDImpl = new MyDeleteByIdImpl(logger);
6. Export myDeleteByIDImpl.process(msg, cfg, snapshot) as process method. Example below.

Example of Usage

Works in sailor > 2.4.2 Delete Action

const { DeleteById } = require('@elastic.io/oih-standard-library/lib/actions/delete');

class MyDeleteByIDImpl extends DeleteById {


  async deleteObject(id, cfg, msg) { // In most cases you need just id, type and cfg
    const deletedID = await deleteObjectInAPI(id, cfg, msg); // Delete object
    return deletedID; // Return deleted object ID. If you return null, empty object would be emitted.
  }
  // You can also override getType and getId methods if needed
}
   

async function process(msg, cfg, snapshot = {}) {
  const deleteAction = new MyDeleteByIDImpl(this.logger); // Sailor version > 2.4.2
  return deleteAction.process(msg, cfg, snapshot);
}

module.exports.process = process;

Delete By Unique Criteria

Note:

• If more than 1 object was found with same uniqueCriteria, error would be thrown by this implementation
• If deleteObject method is returning null empty object would be emitted. You can indicate with null that object hasn`t been deleted or found.

1. Create Action
2. Create class that extends DeleteById class
3. Override findObjectByCriteria and deleteObject() methods. Example below.
4. Optional override getType and getCriteria methods. Default implementation expects objectType to be present in input configuration. For unique criteria: uniqueCriteria field name in input configuration and value in input message.
5. Create instance of your class and pass logger to constructor. const myDeleteByCriteriaImpl = new MyDeleteByCriteriaImpl(logger);
6. Export myDeleteByCriteriaImpl.process(msg, cfg, snapshot) as process method. Example below.

Example of Usage

Works in sailor > 2.4.2 Delete Action

const { DeleteByUniqueCriteria } = require('@elastic.io/oih-standard-library/lib/actions/delete');

class MyDeleteByCriteriaImpl extends DeleteByUniqueCriteria {

  async findObjectByUniqueCriteria(criteria, type, cfg, msg) { // In most cases you need just criteria, type and cfg
     // criteria sructure {
     //  uniqueCriteria: 'fieldName',
     //  value: 'fieldValue', 
     // }
     const object =  await findObjectInAPI(criteria, type, cfg, msg); // objects that match this criteria
     const numberOfObjects =  object.count; // You do not need to check or throw error in this case, action implementation will do this
     return { // return structure must contain object and numberOfObjects found
       object,
       numberOfObjects
     }
  }
  async deleteObject(object, cfg, msg) { // In most cases you need just object, type and cfg
    const deletedID = await deleteObjectInAPI(object, cfg, msg); // Delete object
    return deletedID; // Return deleted object ID if you return null, empty object would be emitted.
  }
  // You can also override getType and getId methods if needed
}
   

async function process(msg, cfg, snapshot = {}) {
  const deleteAction = new MyDeleteByCriteriaImpl(this.logger); // Sailor version > 2.4.2
  return deleteAction.process(msg, cfg, snapshot);
}

module.exports.process = process;

Triggers

Get New and Updated Objects Polling

Webhooks

Firstly, we should implement Webhook subscription handling strategy. For this purpose we must extend HandleWebhookSubscriptionByIdAbstractStrategy and implement createWebhooks & deleteWebhooks methods. Also we can define absolutely new strategy and implement interface HandleSWebhookSubscriptionAbstractStrategy.

Example of Usage

const { HandleWebhookSubscriptionByIdAbstractStrategy, Webhook, defaultProcessWebhook } = require('@elastic.io/oih-standard-library/lib/triggers/webhook');

// implementation of subscription create strategy
// in this class we must implement create/delete WebhookSubscription methods 
class HandleWebhookSubscriptionByIdStrategy extends HandleWebhookSubscriptionByIdAbstractStrategy {
 constructor(client, logger) {
   super(logger);
   this.client = client;
 }

// According to superclass definition should return array of ids;
 async createWebhooks(objectType, eventTypes) {
   const webhooks = await Promise.all(eventTypes.map(eventType => this.client.create({
     topic: eventType,
     address: process.env.ELASTICIO_FLOW_WEBHOOK_URI,
     format: 'json',
   }, WEBHOOK_OBJECT_TYPE)));
   return webhooks.map(webhook => webhook.id);
 }

 async deleteWebhooks(ids) {
   await Promise.all(ids.map(id => this.client.delete({ id }, WEBHOOK_OBJECT_TYPE)));
 }
}

// construct Webhook object using HandleWebhookSubscriptionByIdStrategy strategy
function configuredWebhook(cfg, logger) {
 const credentials = {
   apiKey: cfg.apiKey,
   shopName: cfg.shopName,
   password: cfg.password,
 };
 const client = new Client(credentials);
 const handleWebhookSubscriptionByIdStrategy = new HandleWebhookSubscriptionByIdStrategy(client, logger);
 const webhook = new Webhook(logger, handleWebhookSubscriptionByIdStrategy);
 return webhook;
}

// Export startup and shutdown functions
async function startup(cfg) {
 const webhook = await configuredWebhook(cfg, this.logger);
 return webhook.startup(cfg);
}

async function shutdown(cfg, data) {
 const webhook = await configuredWebhook(cfg, this.logger);
 await webhook.shutdown(cfg, data);
}

// Export static process function
module.exports.process = defaultProcessWebhook;
module.exports.startup = startup;
module.exports.shutdown = shutdown;