Data Sources

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

---

A Custom Data Source is one that employs a script acts as a source of data to fill fields and to fill data from any service that has an API or from other libraries.

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

Lifecycle of a custom data source

1. A user types text in the field of an Entry Edit card.
2. Entered text is passed to the custom data source 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 arguments of the objects written into the entry field according to data load rules.
6. If a function is returned as a result of the script, the function is executed and the result is loaded into the field.

Step 1 — Adding a data source for autofill

1. Open the Library Edit screen. Click on tab Autofill, and click +.
2. The user selects the type of search — By Name or By Barcode.
3. The user selects Custom source.
4. The user selects the field to be used for data search within the source.
5. The user is presented with an Autofill Rules edit card. The user selects 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, extrafun)

Function to return the result of the script.

Arguments

objects

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

extrafun

Optional function for additional data optional argument. This function is executed 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 a function.

Example — Filling data from another library

insert script here

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 arguments 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. Point out 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 — 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 are available in the script repository at github.com: insert URL This library can be connected using scripted data source editor:

1. Open scripted data source editor.
2. Click Add JavaAcript 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 objained 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).