1. Home
  2. Docs
  3. Developers
  4. Develop custom packages
  5. System Entities

System Entities

If you wish to provide entities in your package, first implement \Convo\Core\Intent\ISystemEntityRepository in your package. This interface defines two methods, findPlatformEntity($name, $platformId) and getEntity($name). These are implemented in the AsbtractRepositoryPackageDefinition class, but you may optionally override them.

In your package class, override the _initEntities() method. In the body of the method, you will create an associative array of strings mapped to \Convo\Core\Intent\SystemEntity. Give the system entity a name that you will use in your services.

Next, for each platform you mean to make the entity available on, e.g. Amazon and Dialogflow, call the method setPlatformModel($platformId, $entityModel). Here is where things diverge.

If the entity you wish to create is already built-in on the platform of your choice, for example Amazon’s number entity (AMAZON.NUMBER), then for the entity model argument simply instantiate a new EntityModel, and for the desired platform ID, give it the name of the entity on that platform, and set the second parameter to true, indicating that it is a system entity. Going off the AMAZON.NUMBER example, here is what the number entity defined in the core package looks like:
$entities[‘number’]->setPlatformModel(‘amazon’, new EntityModel( ‘AMAZON.NUMBER’, true));

If you want to create a custom entity, things are slightly different. Each custom entity needs a name, and a list of values. Here is an example of a value list for a demo entity. Note that synonyms for each entry are optional.

Now that you have your values, create a freestanding EntityModel. After you do so, call the load() method and pass it the associative array of values.

After that, simply create a system entity and add it to the original associative array of string => entity, and set the platform model how you normally would. Here is how it all looks tied together.

You might wonder why we didn’t enable .json like definition like for system intents. The reason is that we expect in future to extend system entity definition with ability to implement some parsing or formatting logic. That will be something you have to implement and in in that case json definition would not be acceptable.