Data Sources

« Page as of 2017-02-25, editions Mobile 4.3.0, Desktop 1.1.0 »

---

The Autofill facility in Memento allows users to look up information from data sources on the Web, in Memento libraries, or from other data sources. Certain Web data sources are included by default in the Memento application for the convenience of users. For other lookups, a custom data source is needed.

A Custom Data Source is one in which a script acts as a source of data to fill fields with data from any service that has an API, from other libraries, or from other sources.

To add a custom data source for a library, edit the library, press the Autofill tab, and select Custom Source.

Lifecycle of an Autofill from a custom data source

1. A user types text in a field in an Entry Edit card for use as a key to look up information.
2. The entered text is passed to the custom data source script in the form of the global variable query.
3. The data source script is executed.
4. The user is presented with a list of objects found by the script.
5. The user selects an object, and its properties are written to the mapped entry fields according to data load rules.
6. If a function is returned as a result of the script, the script function is called with the selected object's id property as the argument, and the returned object's properties are loaded into mapped fields according to data load rules.

Adding a custom data source

Step 1 — Adding a data source for autofill

1. Open the Library Edit screen. Click on the Autofill tab, and then click +.
2. Select the type of search — By Name or By Barcode.
3. Select Custom source.
4. Select the field to be used for data search within the source.
5. You are presented with an Autofill Rules edit card. Select the field to use as the search key for the custom data source.

Step 2 — Script writing

The script is executed in the context of the library or entry, so it can use the same functions and objects as a trigger.
A script has the same security parameters as a trigger.
The result of the script should be returned as an array object.

result(objects, getDetailsFunction)

Function to return the initial result of the script — an array of objects representing the search results and a function to be called for details.

Arguments

objects

List of objects which will be presented to the user for selection

getDetailsFunction

Optional argument — function to fetch detailed data. This function is called when one of the objects is selected.

Objects sent to the result function can have the following standard properties. When present, these properties will be displayed to the user for selection:

Properties

title

Name of the object

desc

Additional text shown under the name of the object

thumb

Reference to the image of the object

id

Object identifier. Used if the result() is called with a second argument.

Example — Filling data from another library

Example under development & likely wrong -- check back again soon

function getDetails(ent) {
   var org = {};
   org["Type"] = ent.field("Type");
   org["Address"] = ent.field("Address");
   org["Phone"] = ent.field("Telephone");
   org["Email"] = ent.field("Email address");
   return org;
   }

var lib = libByName("Organizations"); // Need permission for this
if (lib == null) {
   message('Library "Organizations" not found');
   exit();
   }
var entries = lib.entries();
var e, orgs = [];
for (var ex in entries) {
   e = entries[ex];
   if (e.field("Name") == query) {
      var org = {};
      org["title"] = e["Name"];
      org ["desc"] = e["Industry"];
      org["thumb"] = e["Image"];
      org["id"] = e;
      push(orgs, org);
      }
   }

result(orgs, getDetails);
exit();

Additional data load

Many services (APIs) return general information without details as a result of a search. To extract complete detailed information, an additional API request is needed. In this case, a function for additional data load should be used. The argument for this function is the identifier of the object selected by the user. The function returns an object whose parameters will be loaded into the fields of the entry according to autofill rules. As an example, let's use an API with two methods:

1. http://api.example.com/search?q='search query' — This API does a search for an object and returns only identifiers and names of the objects. The result is a JSON array of objects. Each object has a title and an id properties.
2. http://api.example.com/get?id=123 — Receive the detail information of the object based on the id. The result is a JSON object.

Scipted data source can be as follows:

insert code

Step 3 — Settings for autofill rules

After the script is written, it is necessary to map the properties of the returned object to the fields of the library:

1. Close the script edit card and click +.
2. This will open the card for creation of autofill rules.
3. Identify the object property returned by the script.
4. Select the library field to receive the data.
5. Create rules for the remaining object properties.

Example — Web data source

Let's consider service http://www.discogs.com/ — Provides information about music albums. This service has an API documented as http://www.discogs.com/developers.

The example of JavaScript library that provides request to this service is available in the script repository at github.com: insert URL. This library can be connected using the custom data source editor:

1. Open custom data source editor.
2. Click Add JavaScript libraries.
3. Click on tab Repositories.
4. Select repository github.com/mementodatabase/script/data-sources.
5. Select discogs.js.

Script example of using this library:

insert script

• Consumer key and consumer secret are the keys required to execute the request. They may be obtained at http://discogs.com/settings/developers.
• After the script is written, it is necessary to map the object properties to the fields of the library. Available object properties are documented in diskogs API. See an example of a response to a successful request at insert URL.
• If the search in the data source is done by barcode, use discogs.barcode(query) instead of discogs.search(query).