Using the SDK

SDK in Actions

To unlock the power of the app ecosystem, we can use the contrail SDK to fetch and modify entities. In this example, we are going to create an item!

To continue with the theme of our app, we are going to extend our action to create either a jacket or a shirt, depending on the local weather.

Weather Conditional

First, we will write an if statement to split between cold and hot weather. We will pick 70 degrees Fahrenheit as a sensible split between cold and hot weather.

if (jsonResponse?.current?.temperature_2m > 70) {
  await createSummerItem();
} else {
  await createWinterItem();
}

Creating an item

Now, let's define the functions that we just called! This is the fun part, because we get to work with VibeIQ entities!

Here are a few gotchas that might get in the way:

• We want to create a family to include all the summer/winter items we will create
• We do not want to create duplicate families
• We do not want to create duplicate items

To get around these gotchas, we will want to do the following:

• Check if there is an existing family
  • If one exists, use it
  • If not, create one!
• Create a new option with a unique name

Unique Items

Creating a unique name for the item option is left as an exercise

To work with VibeIQ entities, we fist create an Entities client.

import { Entities } from '@contrail/sdk';
const client = new Entities()

Now, let us fetch the families, and check if a summer family exists.

const families = await client.get({
  entityName: 'item',
  criteria: {
    roles: 'family',
  }
});
let summerFamily = families.find(family => family.name === 'Summer Shirts')
console.log('got Summer Family:', JSON.stringify(summerFamily, null, 2))

Finding Families

Note that we passed a criteria with a roles of family. Every entity has a set of criteria you can search by.

If there is no summer family, we create one.

if (!summerFamily) {
  summerFamily = await client.create({
    entityName: 'item',
    object: {
      name: 'Summer Shirts',
      roles: ['family']
    }
  })
  console.log('created summerFamily', JSON.stringify(summerFamily, null, 2))
}

Now, we are ready to finally create the item option! To ensure that the item option is part of the family, we pass itemFamilyId of the family.

const item = await client.create({
  entityName: 'item',
  object: {
    name: 'Summer Shirts',
    optionName: 'Red Summer Shirt',
    roles: ['option'],
    itemFamilyId: summerFamily.id,
    optionGroup: 'color',
  }
})
console.log('item', JSON.stringify(item, null, 2))

The full function will look like this

async function createSummerItem() {
  const client = new Entities();
    // get families
    const families = await client.get({
      entityName: 'item',
      criteria: {
        roles: 'family',
      }
    });
    let summerFamily = families.find(family => family.name === 'Summer Shirts')
    console.log('got Summer Family:', JSON.stringify(summerFamily, null, 2))

    if (!summerFamily) {
      summerFamily = await client.create({
        entityName: 'item',
        object: {
          name: 'Summer Shirts',
          roles: ['family']
        }
      })
      console.log('created summerFamily', JSON.stringify(summerFamily, null, 2))
    }

    const item = await client.create({
      entityName: 'item',
      object: {
        name: 'Summer Shirts',
        optionName: 'Red Summer Shirt',
        roles: ['option'],
        itemFamilyId: summerFamily.id,
        optionGroup: 'color',
      }
    })
    console.log('item', JSON.stringify(item, null, 2))
}

The full file of the action is available here.