fm-data-api v1.0.5

A Javascript wrapper based on "myFMApiLibrary for Javascript" by Lesterius (Claris) and using axios library to perform REST request to the FileMaker Data Api

Presentation

Description

This library is a rework of this very good library. The addition of this present library is to use axios in order to generate Promises. It is also available on npm

You will be able to use every functions like it's documented in your FileMaker server Data Api documentation (accessible via https://[your server domain]/fmi/data/apidoc). General Claris document on the Data API is available here

Installation

The recommended way to install it is with :

npm install fm-data-api

After installing, you can call this javascript library by adding:

import DataApi from 'fm-data-api'

In your Javascript application.

Usage

Prepare your FileMaker solution

1. Enable the FileMaker Data API option on your FileMaker server admin console.
2. Create a specific user in your FileMaker database with the 'fmrest' privilege
3. Define records & layouts access for this user

Use the library

Login

Login with credentials:

let options = {
        'apiUrl': 'https://test.fmconnection.com/fmi/data',
        'databaseName' : 'MyDatabase',
        'login' : 'filemaker api user',
        'password' : 'filemaker api password'
    };

let api = new DataApi(options);

Login with oauth:

let options = {
        'apiUrl': 'https://test.fmconnection.com/fmi/data',
        'databaseName' : 'MyDatabase',
        'oAuthRequestId' : 'oAuthIdentifier',
        'oAuthIdentifier' : 'oAuthIdentifier'
    };

let api = new DataApi(options);

Use only generated token:

let options = {
        'apiUrl': 'https://test.fmconnection.com/fmi/data',
        'databaseName' : 'MyDatabase',
        'token' : 'generated token'
    };

let api = new DataApi(options);

To re generate a token, use 'login' function.

/!\ Not available with 'Login with token' method, use 'setApiToken' function.

Logout

dataApi.logout();

Validate Session

dataApi.validateSession();

Create record

let data = {
    'FirstName'         : 'John',
    'LastName'          : 'Doe',
    'email'             : 'johndoe@acme.inc'
};

let scripts = [
    {
        'name'  : 'ValidateUser',
        'param' : 'johndoe@acme.inc',
        'type'  : SCRIPT_PREREQUEST
    },
    {
        'name'  : 'SendEmail',
        'param' : 'johndoe@acme.inc',
        'type'  : SCRIPT_POSTREQUEST
    }
];

let portalData = {
  'portalName or OccurenceName' : [
      {
          "Occurence::PortalField 1" : "Value",
          "Occurence::PortalField 2" : "Value",
      }
  ]
 };

dataApi.createRecord('layout name', data, scripts, portalData).then((recordId) => {
    console.log(recordId)
    // display the recordId's new record.
});

Delete record

dataApi.deleteRecord('layout name', recordId, script);

Edit record

  dataApi.editRecord('layout name', recordId, data, lastModificationId, portalData, scripts).then((recordId) => {
    console.log(recordId)
    // display the recordId's edit record.
});

Duplicate record

  dataApi.duplicateRecord('layout name', recordId, scripts).then((recordId) => {
    console.log(recordId)
    // display the recordId's new record.
});

Get record

let portals = [
    {
        'name'  : 'Portal1',
        'limit' : 10
    },
    { 
        'name'   : 'Portal2',
        'offset' : 3
    }
];

dataApi.getRecord('layout name', recordId, portals, scripts).then((record) => {
    console.log(record)
    // display the wished record.
});

Get records

let sort = [
    {
        'fieldName' : 'FirstName',
        'sortOrder' : 'ascend'
    },
    {
        'fieldName' : 'City',
        'sortOrder' : 'descend'
    }
];

dataApi.getRecords('layout name', sort, offset, limit, portals, scripts).then((record) =>{
    console.log(record)
    // display the wished records.
});

Find records

let query1 = [
    {
        'fields'  : [
            { fieldname : 'd_firstName', fieldvalue : '==Jean'},
            { fieldname : 'd_lastName', fieldvalue : '==Dupond'},
            { fieldname : 'd_age', fieldvalue : '30'},
            { fieldname : 'd_height', fieldvalue : '160...180'},
            { fieldname : 'd_sex', fieldvalue : 'male'},
        ]
    }
];

dataApi.findRecords('layout name', query1, sort, offset, limit, portals, scripts, dataInfo, responseLayout).then((record) => {
    console.log(record)
    // display the wished record.
});

let query2 = [
    {
        'fields'  : [
            { fieldname : 'd_firstName', fieldvalue : '==Jean'},
            { fieldname : 'd_lastName', fieldvalue : '==Dupond'},
            { fieldname : 'd_age', fieldvalue : '30'},
            { fieldname : 'd_height', fieldvalue : '160...180'},
            { fieldname : 'd_sex', fieldvalue : 'male'},
            { omit : true }
        ]
    }
];

dataApi.findRecords('layout name', query2, sort, offset, limit, portals, scripts, dataInfo, responseLayout).then((record) => {
    console.log(record)
    // display the wished record.
});

let query3 = [
    {
        'fields'  : [
            { fieldname : 'd_firstName', fieldvalue : '==Marie'},
            { fieldname : 'd_age', fieldvalue : '20...30'},
        ]
    },
    {
        'fields'  : [
            { fieldname : 'd_firstName', fieldvalue : '==Ernest'},
            { fieldname : 'd_height', fieldvalue : '150...180'},
            { fieldname : 'd_sex', fieldvalue : 'male'},
        ]
    }
];

dataApi.findRecords('layout name', query3, sort, offset, limit, portals, scripts, dataInfo, responseLayout).then((record) => {
    console.log(record)
    // display the wished record.
});

In this example of request query1 will find people named Jean Dupond AND who are 30 years old AND with an height between 160 and 180 cm AND who are male.

query2 will find all the people who don't match these criteria

query3 will find people named Marie AND who are between 20 and 30 years old, OR people named Ernest AND with an height between 150 and 180 cm AND who are male.

The dataInfo option is by default on false, on true it will provide the records on this form :

{
    "response": {
        "dataInfo": {
            "database": "XXXXX",
            "layout": "XXXXX",
            "table": "XXXXX",
            "totalRecordCount": 29,
            "foundCount": 29,
            "returnedCount": 9
        },
        "data": [{
            "fieldData": {
                "d_descriptif": "zzzzz",
                "d_prix": "zzzzz",
                .
                .
                .
            },
            "portalData": {},
            "recordId": "35",
            "modId": "0"
        }, {
            "fieldData": {
                "d_descriptif": "zzzzz",
                "d_prix": "zzzzz",
                .
                .
                .
            },
            "portalData": {},
            "recordId": "32",
            "modId": "2"
        },
        .
        .
        .
        ]
    },
    "messages": [{
        "code": "0",
        "message": "OK"
    }]
}

which bring the data foundCount, for example. By default the data form is :

[
        {
            "fieldData": {
                "d_descriptif": "zzzzz",
                "d_prix": "zzzzz",
                .
                .
                .
            },
            "portalData": {},
            "recordId": "35",
            "modId": "0"
        }, {
            "fieldData": {
                "d_descriptif": "zzzzz",
                "d_prix": "zzzzz",
                .
                .
                .
            },
            "portalData": {},
            "recordId": "32",
            "modId": "2"
        },
        .
        .
        .
]

Set global fields

let data = {
  'FieldName1'	: 'value',
  'FieldName2'	: 'value'
};

dataApi.setGlobalFields('layout name', data);

Execute script

dataApi.executeScript('script name', scriptsParams).then((result) => {
    console.log(result)
    // display the script result.
});

Upload file to container

dataApi.uploadToContainer('layout name', recordId, containerFieldName, containerFieldRepetition, file);

Metadata Info

Product Info

dataApi.getProductInfo();

Database Names

/!\ Not available with 'Login with token' method

dataApi.getDatabaseNames();

Layout Names

dataApi.getLayoutNames();

Script Names

dataApi.getScriptNames();

Layout Metadata

dataApi.getLayoutMetadata('layout name', recordId);