API migration guides

Templates migration guide

Version 2 (Investigate 13.3.0)

To migrate a version 1 template script to version 2, follow these steps:

Function context.registerTemplate has been renamed. Search and replace it with context.registerPerspectives.

Migrate the recordView function

Rename the registered recordView function to render and move it inside a view.<choose a view name> object.
Move the data fetching logic to a function called enrich and keep only the rendering logic in function render. When enrich is defined Investigate calls the render function periodically to update the view. The render function must not be async.
Store computed data inside input object computedData. Create a function called initialData to initialize the computedData object with values before enrich is called.

Example

// Version 1
context.registerTemplate({
  async recordView(input) {
    const { render } = input;

    const recordData = { value: 'loading' };
    const timerId = setInterval(() => render(reactView(recordData)), 200);

    try {
      await fetchRecordData(input, recordData);
    } finally {
      clearInterval(timerId); // Clean up automatic updates before quitting
    }

    return reactView(recordData);
  }
});


// Version 2
context.registerPerspectives({
  view: {
    'My View': {
      initialData() {
        return { value: loading };
      },

      async enrich(input) {
        await fetchRecordData(input, input.computedData);
      },

      render({ computedData }) {
        return reactView(computedData);
      }
    }
  }
});

Migrate download functions

Rename registered object download to binary.
Replace calls to sirenapi.Reporting with returning a binary output object.

Example

// Version 1
context.registerTemplate({
  download: {
    async pdf() {
      await sirenapi.Reporting.download(templateId, { value: 'value' }, 'report.pdf');
    },

    async txt() {
      await sirenapi.Reporting.downloadString('Report content here', 'report.txt');
    }
  }
});

// Version 2
context.registerPerspectives({
  binary: {
    'My pdf export': {
      render() {
        return { filename: 'report.pdf', templateId, data: { value: 'value' } };
      }
    },

    'My txt export': {
      render() {
        return { filename: 'report.txt', content: 'Report content here' };
      }
    }
  }
});

Elasticsearch client migration guide

Since Investigate 15.1, the sirenapi.es Elasticsearch client has been deprecated in favor of a new client that provides better access to modern Elasticsearch features: sirenapi.elasticsearch

The syntax has changed from a JavaScript object-based approach to a syntax that more closely aligns with Elasticsearch’s REST API.

Old: sirenapi.es

await sirenapi.es.search({
  index: 'my-index',
  body: {
    query: {
      match: { field: 'value' }
    }
  }
});
// {took: 9, timed_out: false, _shards: {…}, hits: {…}}

New: sirenapi.elasticsearch

await sirenapi.elasticsearch.post('/my-index/_search', {
  query: {
    match: { field: 'value' }
  }
});
// {took: 9, timed_out: false, _shards: {…}, hits: {…}, _response: {…}}

The response structure remains mostly unchanged, with the addition of a _response field that contains metadata about the HTTP request and response.