We use cookies to help our site work and to understand how it is used. By continuing to browse the site you're agreeing to our use of cookies.
Menu

Import from other sources with NodeJS

We released an NPM package to make it easy to programmatically read/create/edit/destroy DatoCMS records. Install the datocms-client package in your application:

$ npm install --save-dev datocms-client

Or, if you're using Yarn as package manager:

$ yarn add datocms-client

Warning: due to historical reasons and backward compatibility, the API exposes some different naming compared to the rest of the product: Models are called Item Types, while Records are called Items. Keep that in mind!

The first step is to require the DatoCMS package, and initialize the client with the read-write API token you can find under the Admin area > API tokens section. Let's create an import.js file with the following content:

require('babel-polyfill');
const SiteClient = require('datocms-client').SiteClient;

const client = new SiteClient('YOUR_API_READWRITE_TOKEN');

Now, suppose we have an administrative area with an Article model, and we want to import a list of articles ie. from a JSON file:

foo

The first thing to know is the ID of the model itself. Let's add the following line to pretty print the existing models:

require('babel-polyfill');
const SiteClient = require('datocms-client').SiteClient;

const client = new SiteClient('YOUR_API_READWRITE_TOKEN');

client.itemTypes.all()
.then((models) => console.log(models));

As you can see client.itemTypes.all() method returns a promise. Here's the output when we execute the script:

$ node import.js
[ 
  { 
    id: '7149',
    name: 'Article',
    singleton: false,
    sortable: false,
    apiKey: 'article',
    fields: [ '27669', '27667', '27668' ] 
  }
]

We can also inspect the fields contained in the model:

// obtain all the fields of the model
client.fields.all("7149")
.then((fields) => console.log(fields));

// Output:
//
// [ { id: '27667',
//     label: 'Title',
//     fieldType: 'string',
//     apiKey: 'title',
//     hint: null,
//     localized: false,
//     validators: {},
//     position: 2,
//     appeareance: { type: 'title' },
//     itemType: '7149' },
//   { id: '27668',
//     label: 'Content',
//     fieldType: 'text',
//     apiKey: 'content',
//     hint: null,
//     localized: false,
//     validators: {},
//     position: 3,
//     appeareance: { type: 'wysiwyg' },
//     itemType: '7149' },
//   { id: '27669',
//     label: 'Cover image',
//     fieldType: 'image',
//     apiKey: 'cover_image',
//     hint: null,
//     localized: false,
//     validators: {},
//     position: 1,
//     appeareance: {},
//     itemType: '7149' } ] ]

Great, here there are our three fields. Let's create our article:

// create a new Article record
client.uploadImage('http://i.giphy.com/NXOF5rlaSXdAc.gif')
.then((image) => {
  return client.items.create({
    itemType: '7149',
    title: 'My first article!',
    content: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod.',
    coverImage: image
  })
})
.then(record => console.log(record));

// Output:
// { id: '43858',
//   updatedAt: '2017-03-20T14:34:30.249Z',
//   isValid: true,
//   title: 'My first article!',
//   content: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod.',
//   coverImage: '1834832',
//   itemType: '7149' }

As you can see, we use the helper method client.uploadImage to pass DatoCMS the metadata of the image to associate to the record.

Retrieving records

To retrieve the stored records:

client.items.all({}, { allPages: true })
.then((records) => console.log(records));

If you want to retrieve just the records of a specific model (ie. article):

client.items.all({ 'filter[type]': 'article' }, { allPages: true })
.then((records) => console.log(records));

You can also pass the model ID instead of the model API identifier.

Linking records

If you have a record with some a link field (ie. an article linked to its category), during the creation you need to pass the ID of the linked record:

client.items.create({
  itemType: '7150',
  name: 'My category',
})
.then((category) => {
  return client.items.create({
    itemType: '7149',
    title: 'My first article!',
    content: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod.',
    category: category.id,
  });
})
.then((record) => console.log(record));

If you have a "multiple links" field, then you need to pass the array of IDs:

client.items.create({
  itemType: '7150',
  name: 'My category',
})
.then((category) => {
  return client.items.create({
    itemType: '7149',
    title: 'My first article!',
    content: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod.',
    categories: [category.id]
  });
})
.then((record) => console.log(record));

Multi-language fields

If localization is enabled on some field, the format of the payload changes a little bit, as you need to pass an hash representing the value of the field for each of the locales you setup in your administrative area:

// create a new Article record
client.uploadImage('http://i.giphy.com/NXOF5rlaSXdAc.gif')
.then((image) => {
  return client.items.create({
    itemType: '7149',
    title: {
      en: 'My first article!',
      it: 'Il mio primo articolo!'
    },
    content: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod.',
    coverImage: image
  })
})
.then(record => console.log(record));