A Virtual Entity in Flexie CRM is an entity that is not related to any of your existing entities or custom entities. We see the Virtual Entities when we create a Workflow of type Virtual Entity that is going to handle incoming data.
The data comes from the third-party applications right into Flexie CRM with the use of Dynamic Endpoints that we create.

The Dynamic Endpoints are URLs generated dynamically for you that you can copy and use in your third-party applications for the sole purpose to post data into Flexie CRM.

The coming data is of unknown structure that you will access and use to create or update records for your existing entities. The accepted data format is JSON that represents a lightweight data-interchange format. The most widely used JSON comes in the form of an object or an array.

Once the data is coming in after being posted into the Dynamic Endpoint URL, we can manipulate it within the workflow or we can transfer it into another manual workflow.

To access the data in the main workflow of type Virtual Entity we use a special keyword composed of two double underscores following with a key named data:

__data

All the posted payload is at our hand now and can be used and manipulated. Suppose we have a payload coming in the format below:

{
    "first_name": "Sara",
    "last_name": "Smith",
    "email": "sara.smith@gmail.com",
    "phone": "234-332-9999",
    "source": "website"
}

To access and use this data we use the __data special keyword and encapsulate it with the double curly brackets. For example we can access first name, email and all the other fields represented in the example above.

     {{__data.first_name}} //output "Sara"

     {{__data.last_name}} //output "Smith"

     {{__data.email}} //output "sara.smith@gmail.com"

     {{__data.phone}} //output "234-332-9999"

     {{__data.source}} //output "website"

From this we could create a known entity like a Lead or a Contact and set the field values like represented in the example above:

Access Virtual Entity data from a Manual Workflow

After using the data to create a known entity record, in Flexie CRM workflows you have the ability to push to another workflow. Usually this is done by finding the entity record that we created by a Unique Identifier field that may be an email and push it to a manual workflow.

When using the Push to Workflow action, the data is transported to the manual workflow and can be used from there. The only thing changing, is the way how you access the data.

The main keyword is still __data with the addition of another keyword __virtual that is used for you to know where the data is coming from. The access keyword composition would be:

__data.__virtual

This is the default way how to access the data when you use the Push to Workflow from a Workflow of type Virtual Entity. You could also create your own data structure by using the Show Advanced option in the Push to Workflow action and compose your key and structure.

To access and use the data in the manual workflow where you transferred it, you could use the following example:

     {{__data.__virtual.first_name}} //output "Sara"

     {{__data.__virtual.last_name}} //output "Smith"

     {{__data.__virtual.email}} //output "sara.smith@gmail.com"

     {{__data.__virtual.phone}} //output "234-332-9999"

     {{__data.__virtual.source}} //output "website"

This way we access the raw data coming from the Virtual Workflow, but if we need only some basic information then we could use our own composed key and access it.

     {{__data.clientdata.client_email}} //output "sara.smith@gmail.com"

     {{__data.clientdata.client_phone}} //output "234-332-9999"

Iterate collection and access data

Data in a Virtual Entity come in different structures. It may be an object, a collection or a collection of objects. Many times we may need to iterate and save items within a collection.

On actions like Entity Insert or Entity Update we can iterate over a collection of objects and insert/update each of them.  

An example payload is shown below and we iterate through items collection of an example order. 

{ 
  "order_id": 2321232,
  "items": 
    [ 
      {
        "item_id": "221", 
        "item_name": "Shirt XS",  
        "price": "32",
        "currency": "EUR",
        "quantity":1
      },
      {
        "item_id": "222", 
        "item_name": "Watch", 
        "price": "155",
        "currency": "EUR",
        "quantity":1
      }
    ] 
}

After setting the “Repeat Over” key to __data.items based on the example payload, we can save each of the items of the collection. Usually if you will be receiving orders from an eCommerce, some additional entities e.g Orders and Order Items should be created first.  

As we may see, after iterating a collection of objects, we access each of the objects attributes by using __index key.

To stay updated with the latest features, news and how-to articles and videos, please join our group on Facebook, Flexie CRM Academy and subscribe to our YouTube channel Flexie CRM.