Odoo Await

Simple Odoo API client built with promises for async / await usage. Features CRUD, many2many field methods, and more.

Contributing

Happy to merge all useful features and bug fixes. Just start an 'issue' regarding the update, fork the repo, commit your changes, and submit a pull request.

Node version

Node 11.16+

Odoo Version

Odoo 12 +

Installation

npm install odoo-await

Usage

const Odoo = require("odoo-await");

const odoo = new Odoo({
  baseUrl: "https://yourdomain.odoo.com",
  port: undefined, // see comments below regarding port option
  db: "odoo_db",
  username: "admin",
  password: "admin",
});

await odoo.connect();

const partnerId = await odoo.create("res.partner", {
  name: "Kool Keith",
  email: "[email protected]",
});
console.log(`Partner created with ID ${partnerId}`);

// if connecting to a dev instance of odoo.sh, your config will looking something like:
const odoo = new Odoo({
  baseUrl: "https://some-database-name-5-29043948.dev.odoo.com/",
  db: "some-database-name-5-29043948",
  username: "myusername",
  password: "somepassword",
});

From version 3.x onwards the port is optional and will resolve as follows:

• port option, if provided
• port number in URL, if provided. e.g. http://example.com:8069
• default port for protocol, so 443 for https and 80 for http

Methods

odoo.connect()

Must be called before other methods.

odoo.execute_kw(model,method,params)

This method is wrapped inside the below methods. If below methods don't do what you need, you can use this method. Docs: Odoo External API

odoo.action(model, action, recordId)

Execute a server action on a record or a set of records. Oddly, the Odoo API returns false if it was successful.

await odoo.action("account.move", "action_post", [126996, 126995]);

CRUD

odoo.create(model, params, externalId)

Returns the ID of the created record. The externalId parameter is special. If supplied, will create a linked record in the ir.model.data model. See the "working with external identifiers" section below for more information.

const partnerId = await odoo.create("res.partner", { name: "Kool Keith" });

odoo.read(model, recordId, fields)

Takes an array of record ID's and fetches the record data. Returns an array. Optionally, you can specify which fields to return. This is usually a good idea, since there tends to be a lot of fields on the base models (like over 100). The record ID is always returned regardless of fields specified.

const records = await odoo.read("res.partner", [54, 1568], ["name", "email"]);
console.log(records);
// [ { id: 127362, name: 'Kool Keith', email: '[email protected] }, { id: 127883, name: 'Jack Dorsey', email: '[email protected]' } ];

odoo.update(model, recordId, params)

Returns true if successful

const updated = await odoo.update("res.partner", 54, {
  street: "334 Living Astro Blvd.",
});
console.log(updated); // true

odoo.delete(model, recordId)

Returns true if successful.

const deleted = await odoo.delete("res.partner", 54);

many2many and one2many fields

Odoo handles the related field lists in a special way. You can choose to:

1. add an existing record to the list using the record ID
2. update an existing record in the record set using ID and new values
3. create a new record on the fly and add it to the list using values
4. replace all records with other record(s) without deleting the replaced ones from database - using a list of IDs
5. delete one or multiple records from the database

In order to use any of these actions on a field, supply an object as the field value with the following parameters:

• action (required) - one of the strings from above
• id (required for actions that use id(s) ) - can usually be an array, or a single number
• value (required for actions that update or create new related records) - can usually be an single value object, or an array of value objects if creating mutliple records

Examples

// create new realted records on the fly
await odoo.update("res.partner", 278, {
  category_id: {
    action: "create",
    value: [{ name: "a new category" }, { name: "another new category" }],
  },
});

// update a related record in the set
await odoo.update("res.partner", 278, {
  category_id: {
    action: "update",
    id: 3,
    value: { name: "Updated category" },
  },
});

// add existing records to the set
await odoo.update("res.partner", 278, {
  category_id: {
    action: "add",
    id: 5, // or an array of numbers
  },
});

// remove from the set but don't delete from database
await odoo.update("res.partner", 278, {
  category_id: {
    action: "remove",
    id: 5, // or an array of numbers
  },
});

// remove record and delete from database
await odoo.update("res.partner", 278, {
  category_id: {
    action: "delete",
    id: 5, // or an array of numbers
  },
});

// clear all records from set, but don't delete
await odoo.update("res.partner", 278, {
  category_id: {
    action: "clear",
  },
});

// replace records in set with other existing records
await odoo.update("res.partner", 278, {
  category_id: {
    action: "replace",
    id: [3, 12, 6], // or a single number
  },
});

// You can also just do a regular update with an array of IDs, which will accomplish same as above
await odoo.update("res.partner", 278, {
  category_id: [3, 12, 16],
});

Other Odoo API Methods

odoo.search(model, domain)

Searches and returns record ID's for all records that match the model and domain.

const recordIds = await odoo.search(`res.partner`, {
  country_id: "United States",
});
console.log(recordIds); // [14,26,33, ... ]

// return all records of a certain model (omit domain)
const records = await odoo.searchRead(`res.partner`);

odoo.searchRead(model, domain, fields, opts)

Searches for matching records and returns record data. Provide an array of field names if you only want certain fields returned.

const records = await odoo.searchRead(
  `res.partner`,
  { country_id: "United States" },
  ["name", "city"],
  { limit: 5, offset: 10, order: "name, desc", context: { lang: "en_US" } }
);
console.log(records); // [ { id: 5, name: 'Kool Keith', city: 'Los Angeles' }, ... ]

// Empty domain or other args can be used
const records = await odoo.searchRead(`res.partner`, {}, ["name", "city"], {
  limit: 10,
  offset: 20,
});

Complex domain filters

A domain filter array can be supplied if any of the alternate domain filters are needed, such as <, >, like, =like, ilike, in etc. For a complete list check out the API Docs. You can also use the logical operators OR "|", AND "&", NOT "!". Works in both the search() and searchRead() functions.

// single domain filter array
const recordIds = await odoo.search("res.partner", ["name", "=like", "john%"]);

// or a multiple domain filter array (array of arrays)
const recordIds = await odoo.search("res.partner", [
  ["name", "=like", "john%"],
  ["sale_order_count", ">", 1],
]);

// logical operator OR
// email is "[email protected]" OR name includes "charlie"
const records = await odoo.searchRead("res.partner", [
  "|",
  ["email", "=", "[email protected]"],
  ["name", "ilike", "charlie"],
]);

odoo.getFields(model, attributes)

Returns detailed list of fields for a model, filtered by attributes. e.g., if you only want to know if fields are required you could call:

const fields = await odoo.getFields("res.partner", ["required"]);
console.log(fields);

Working With External Identifiers

External ID's can be important when using the native Odoo import feature with CSV files to sync data between systems, or updating records using your own unique identifiers instead of the Odoo database ID.

External ID's are created automatically when exporting or importing data using the Odoo user interface, but when working with the API this must be done intentionally.

External IDs are managed separately in the ir.model.data model in the database - so these methods make working with them easier.

Module names with external ID's

External ID's require a module name along with the ID. If you don't supply a module name when creating an external ID with this library, the default module name 'api' will be used. What that means is that 'some-unique-identifier' will live in the database as '__api__.some-unique-identifier'. You do not need to supply the module name when searching using externalId.

create(model, params, externalId, moduleName)

If creating a record, simply supply the external ID as the third parameter, and a module name as an optional 4th parameter. This example creates a record and an external ID in one method. (although it makes two separate create calls to the database under the hood).

const record = await odoo.create(
  "product.product",
  { name: "new product" },
  "some-unique-identifier"
);

createExternalId(model, recordId, externalId)

For records that are already created without an external ID, you can link an external ID to it.

await odoo.createExternalId("product.product", 76, "some-unique-identifier");

readByExternalId(externalId, fields);

Find a record by the external ID, and return whatever fields you want. Leave the fields parameter empty to return all fields.

const record = await odoo.readByExternalId("some-unique-identifier", [
  "name",
  "email",
]);

updateByExternalId(externalId, params)

const updated = await odoo.updateByExternalId("some-unique-identifier", {
  name: "space shoe",
  price: 65479.99,
});

Testing

The default test will run through basic CRUD functions, creating a res.partner record, updating it, reading it, and deleting it. Uses Mocha and Should as dependencies.

Pass the variables in command line with environment variables:

$ ODOO_DB=mydatabase ODOO_USER=myusername ODOO_PW=mypassword ODOO_PORT=8080 ODOO_BASE_URL=https://myodoo.com npm test

• Odoo Docs
• Odoo External API

Changelog

3.4.1

1. Fix type declarations

3.4

1. Type declarations from PR #34. thanks to @bebjakub for the contribution.

3.3.2

1. Merge PR #30 for basic auth

3.3.1

1. Update packages for bulnerabilities. option, contribution by @aharter.

3.3.0

1. Add action() method to execute specified server action on record(s).

3.2.0

1. Add support for url basic auth. Thanks to @aharter for the contribution - PR #7

3.1.0

1. Replaced deprecated querystring package with global URL.
2. Removed some tests that might fail on databases that already have records in them.

3.0.0

1. Port now defaults to protocol. So, https defaults to 443, and http defaults to 80. Port 8069 is no longer default, which makes this a breaking change. Version updated to 3.0. Thanks to @ajmas for the contribution.

2.4.0

1. Add context option to searchRead() method (thanks to @tomas-padrieza)

2.3.0

1. Add support for logical operators while searching

2.2.3

1. Update readme

2.2.2

1. Remove console log on successful connection - PR #15
2. Update dependency glob-parent
3. Updated readme

2.2.0

1. [Feature] - Now supports sorting records returned by the searchRead() function. Thanks to @tsogoo for the PR. See other API methods below.

2.1.1

1. [Bug Fix] - Fixed type casting in search methods. Issue #8.

2.1.0

1. [Feature] - Use domain filters like <, =like, in, etc. for more complex searches. See complex domain filters below.

2.0.2

1. [Bug fix] - Null values no longer throw errors.

2.0.0

Version two introduces the following major feature additions:

1. [Feature] Working with external ID's. Create, search, read, update by using an external ID instead of model name and ID. See Working with external identifiers below.
2. [Feature] Enhanced functionality when working with many2many or one2many fields. Now you can create records on the fly, update records, delete, or replace. See Many2many and one2many fields below.

License

ISC

Copyright 2020 Charlie Wettlaufer

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.