Entities


Defining entities and topology

Entities and their definitions are a close equivalent to an obect model defined in a UML class diagram but with built in persistence and create, read, and update functionality. They are similar to entities in an object oriented database and somewhat like a relational database where a schema is designed for tables and relationships between them.


Creating an entity model

Before you use the fsoc commands to add entities to your solution, it’s often helpful to model your entities in a diagram first, to define what the entity names will be, their required attributes, and the relationships between the entities.

The model on the right was created in about ten minutes and helps you visualize and adjust the model before you start creating the json files that represent the model.

image

Modeling your entities in a diagram first will save you from a lot of unexpected headaches during your solution development. You can get more details about the json structure of entity definitions, including the supported relationship types here:


  Add five entities to our UgottaRide solution by executing the fsoc commands shown below.

fsoc command to add a new entity
Command Format: fsoc solution extend --add-entity <entity_name>
Command Help: fsoc solution extend -h


Windows Example Commands:

cd C:\fsoc_projects\my_tenant\ugottaride

fsoc solution extend --add-entity ride

fsoc solution extend --add-entity rider

fsoc solution extend --add-entity ride_assign

fsoc solution extend --add-entity driver

fsoc solution extend --add-entity vehicle

Unix-Mac Example Commands:

cd /fsoc_projects/my_tenant/ugottaride

fsoc solution extend --add-entity ride

fsoc solution extend --add-entity rider

fsoc solution extend --add-entity ride_assign

fsoc solution extend --add-entity driver

fsoc solution extend --add-entity vehicle

image

What did these fsoc commands do?

  • Created new subdirectories under /fsoc_projects/my_tenant/ugottaride
  • Created five entity definition files under /fsoc_projects/my_tenant/ugottaride/objects/model/entities
    • ride.json
    • rider.json
    • ride_assign.json
    • driver.json
    • vehicle.json
  • Updated the manifest.json file to reference the directory and files it created

  Let’s take a look at our “ride.json” entity definition file.

/fsoc_projects/my_tenant/ugottaride/objects/model/entities/ride.json

Notice the default values in minutes for “purgeTtlInMinutes” and “retentionTtlInMinutes”. Let’s go ahead and change these to 200 and 116 respectively in all four entity json files, since we don’t want our entites living too long during development when we may be changing the entity definitions, metrics, etc., quite often.

image


Add attributes to entities

  Now let’s add some attributes to our entities, starting with the “rider” entity.

  1. You should always have at least one attribute that is required for your enity and it should be an attribute that will have a unique value across all your entity instances for your type of entity, in this case the “rider” entity. You may have an entity that doesn’t have a single attribute that is unique across all your instances so in that scenario, you should have multiple required attributes such that the combination of the required attributes will be unique for a specific entity instance (much like a compound primary key in a database table).
  2. You define your entity attributes here with a name, type, and description. An attribute “type” can be one of (string, double, or long).

In the rider entity json file, you will update the attributeDefinitions section as seen on lines between the <start> and <end> tags.

/fsoc_projects/my_tenant/ugottaride/objects/model/entities/rider.json

{
    "namespace": {
        "name": "ugottaride",
        "version": 1
    },
    "kind": "entity",
    "name": "rider",
    "displayName": "rider",

<start>    

    "attributeDefinitions": {
        "required": [
            "riderid"
        ],
        "optimized": [ "riderid", "first_name", "last_name", "display_name" ],
        "attributes": {
            "riderid": {
                "type": "string",
                "description": "The unique identifier of the rider"
            },
            "first_name": {
                "type": "string",
                "description": "The first name of the rider"
            },
            "last_name": {
                "type": "string",
                "description": "The last name of the rider"
            },
            "display_name": {
                "type": "string",
                "description": "The name of the rider to display to the driver"
            }                                    
        }
    },

<end>   

    "lifecycleConfiguration": {
        "purgeTtlInMinutes": 200,
        "retentionTtlInMinutes": 160
    }
}


/fsoc_projects/my_tenant/ugottaride/objects/model/entities/ride.json

    "attributeDefinitions": {
        "required": [
            "rideid"
        ],
        "optimized": [ "rideid", "ride_status", "ride_category" ],
        "attributes": {
            "rideid": {
                "type": "string",
                "description": "The unique identifier of the ride"
            },
            "ride_status": {
                "type": "string",
                "description": "The current status of the ride (requested, confirmed, cancelled, picking_up, enroute, completed)"
            },
            "ride_category": {
                "type": "string",
                "description": "The category of the ride (cheapo, regulo, luxo, blimpo)"
            },            
            "travel_time_minutes": {
                "type": "long",
                "description": "The total travel time in minutes for this ride"
            }                     
        }
    }


/fsoc_projects/my_tenant/ugottaride/objects/model/entities/ride_assign.json

    "attributeDefinitions": {
        "required": [
            "assignid", "rideid", "driverid", "vin"
        ],
        "optimized": ["assignid", "rideid", "driverid", "vin", "assign_status"],
        "attributes": {
            "assignid": {
                "type": "string",
                "description": "The unique identifier for the ride_assign"
            },
            "rideid": {
                "type": "string",
                "description": "The unique identifier of the ride"
            },
            "driverid": {
                "type": "string",
                "description": "The unique identifier of the driver"
            },
            "vin": {
                "type": "string",
                "description": "The  unique vehicle identification number"
            },
            "assign_status": {
                "type": "string",
                "description": "The current status of the ride assignment (requested, confirmed, cancelled)"
            }                                                
        }
    }


/fsoc_projects/my_tenant/ugottaride/objects/model/entities/driver.json

    "attributeDefinitions": {
        "required": [
            "driverid"
        ],
        "optimized": [ "driverid", "first_name", "last_name" ],
        "attributes": {
            "driverid": {
                "type": "string",
                "description": "The unique identifier of the driver"
            },
            "first_name": {
                "type": "string",
                "description": "The first name of the driver"
            },
            "last_name": {
                "type": "string",
                "description": "The last name of the driver"
            },
            "display_name": {
                "type": "string",
                "description": "The name of the driver to display to the rider"
            }                        
        }
    }


/fsoc_projects/my_tenant/ugottaride/objects/model/entities/vehicle.json

    "attributeDefinitions": {
        "required": [
            "vin"
        ],
        "optimized": [ "vin", "plate_number", "exterior_color", "make_model" ],
        "attributes": {
            "vin": {
                "type": "string",
                "description": "The  unique vehicle identification number"
            },
            "plate_number": {
                "type": "string",
                "description": "The license plate number of the vehicle"
            },
            "exterior_color": {
                "type": "string",
                "description": "The exterior color of the vehicle"
            },
            "make_model": {
                "type": "string",
                "description": "The description of the vehicle that includes the make and model"
            }                             
        }
    }


Add resourceMappings for entities

An OTLP packet’s resource map (metadata) is a list of key-value pairs. Depending on what data type is in the OTLP packet’s payload, you must map that data to attributes in a specific entity type. You must declare this mapping for every entity in your solution, otherwise, the Platform cannot properly represent the entities in your domain.

There are two different approaches to resource mapping definitions.

  • Use “attributeNameMappings” listing each individual attribute
    • default approach when using fsoc to generate the resource mappings
  • Use “mappings” with “resourceAttributes.stream()”
    • has more caveats than the other approach

Using the mappings approach

When using the mappings approach please be aware that while it alleviates the need to spell out each attribute in the mappings section, it still requires that the scopeFilter contains all the required attributes for your entity.

Using the attributeNameMappings approach

When you create your resourceMapping using the fsoc command seen below, it uses the attributeNameMapping approach that lists all the attributes that are defined for the entity.


  Dev Tip You’ll save time if you define all the attributes for your entity before you create its resource mapping. If you create your resource mapping for an entity and then add new attributes to that entity, be sure to go back and regenerate your resource mapping to account for your new attributes on your entity or adjust your resource mapping manually to add your new attributes.

You can get more details about the json structure of resource mappings here:

https://developer.cisco.com/docs/fso/#!fmmresourcemapping/fmmresourcemapping


  Now that we have added our attributes to our entities, let’s use the commands below to add our resource mappings.

fsoc command to add a resourceMapping for an entity
Command Format: fsoc solution extend --add-resourceMapping <entity_name>
Command Help: fsoc solution extend -h

Windows Example Commands:

cd C:\fsoc_projects\my_tenant\ugottaride

fsoc solution extend --add-resourceMapping ride

fsoc solution extend --add-resourceMapping rider

fsoc solution extend --add-resourceMapping ride_assign

fsoc solution extend --add-resourceMapping driver

fsoc solution extend --add-resourceMapping vehicle

Unix-Mac Example Commands:

cd /fsoc_projects/my_tenant/ugottaride

fsoc solution extend --add-resourceMapping ride

fsoc solution extend --add-resourceMapping rider

fsoc solution extend --add-resourceMapping ride_assign

fsoc solution extend --add-resourceMapping driver

fsoc solution extend --add-resourceMapping vehicle

image

What did these fsoc commands do?

  • Created new subdirectories under /fsoc_projects/my_tenant/ugottaride/objects/model
  • Created five resource mapping files under /fsoc_projects/my_tenant/ugottaride/objects/model/entities/resource-mappings
    • ride-resourceMapping.json
    • rider-resourceMapping.json
    • driver-resourceMapping.json
    • vehicle-resourceMapping.json
  • Updated the manifest.json file to reference the directory and files it created

Let’s take a look at our “ride-resourceMapping.json” entity definition file. Notice that the scopeFilter only contains the required attribute(s), while the attributeNameMappings lists all of the attributes of the entity.

/fsoc_projects/my_tenant/ugottaride/objects/model/entities/resource-mappings/ride-resourceMapping.json

{
    "namespace": {
        "name": "ugottaride",
        "version": 1
    },
    "kind": "resourceMapping",
    "name": "ugottaride_ride_entity_mapping",
    "displayName": "Resource mapping configuration for the ugottaride:ride entity",
    "entityType": "ugottaride:ride",
    "scopeFilter": "containsAll(resourceAttributes, ['ugottaride.ride.rideid'])",
    "attributeNameMappings": {
        "ride_category": "ugottaride.ride.ride_category",
        "ride_status": "ugottaride.ride.ride_status",
        "rideid": "ugottaride.ride.rideid",
        "travel_time_minutes": "ugottaride.ride.travel_time_minutes"
    }
}


Next Steps  

We’ll add some metrics to our solution.

Click here to continue