Deploy and instantiate

Deploy

In TQL, Model development is a three step process -

1. Definition
2. Deploy (compilation)
3. Queries (instantiation, update, delete, subscription)

See also lifecycle of models.

In this section Deploy and Query (which includes Instantiation or Create) is discussed. Deploy and Query is the the runtime phase of the model development. In order to deploy the models you would need a running instance of A-Stack. A-Stack can be downloaded from your TQLStudio Account page and installed to the environment of your choice.

The deployment unit for A-Stack is Package, which has contains definition of all the capabilities (Facets) required as part of the package.

Package File (<Package Name>.mqp.xml) has following structure and it gets created by the system at the time of deploying a project by using TQLConsole.

A-Stack Package Definition

Package is like a container for all runtime artifacts against the definition provided within the NewPackage XML element.

Package contains instances for Facet Types and give the unique Id as fid-<FacerID>. fid-<Facet ID> is used to refer to this instance both from inside the engine from other models and from outside of the engine.

#
NewPackage(Name: "Some-Name-for-the-package"): 
	# List of A-Stack Capabilities to deploy using FacetScript
 	NewFacetInstance(Name: "..", fid: "..", Type: "..."):
		#...

Package Definition File Naming

Package definitions are defined in a file and given and extension of "mqp.xml". The file is normally placed in the "deploy" folder subdirectory.

A-Stack Capabilities

Package definition contains instances of capabilities that are offered by A-Stack. Below is the list of the A-Stack Capabilities:

When a package definition is created you are defining the list of A-Stack capability instances that you would like to get started with. The capability instances are defined using FacetScript Language. Please refer to Facescript Introduction Section for more details on using FacetScript.

There are two ways to deploy the models:

1. TQLStudio ThingSpaces
2. A-Stack Management API against your running copy of A-Stack on your local machine (Gateway, MicroController, Laptop).

Deploying Project using TQLStudio ThingSpaces

Once the models are defined using Model Editor as part of your project, you can deploy the models by clicking "Deploy" as part of ThingSpaces. The models get deployed to the default A-Stack provided by Atomiton in the cloud. You can overwrite the destination engine by updating Host, where your engine is running.

When you run the A-Stack on your machine, there is default administration UI, which can be accessed through http://<Hostname>:<Port>/fid-TQLConsole/app/index.html. The project can be exported from cloud Studio and imported in the local engine by using this admin UI. The default username and password for this local engine is <TQLEngine@atomiton.com> and password is <tql123>.

Content of Package Definition when deploying using TQLStudio ThingSpaces

Once the project is deployed from ThingSpaces in TQLStudio (or A-Stack UI) default Package Layout is deployed as part of your project. The rational behind default package layout is to provide a instance of every A-Stack with standard capability to start with. Here we list the package definition snippets:

Runtime Parameters Section

Top section of the default package definition maintains all the reusable reference names. As developer, you can extend this list with your own names, which can be referred later.

#
RuntimeParams:
	DbmLocation(Comment: "Name of the model file"): Model.Location
    ThingFacetLocation(Comment: "Folder for all the Facet definitions"): TF.Location
    MacroLocation(Comment: "Folder for all the macro definitions"): Macros.Location
    SpacesLocation(Comment: "Folder for all instances definition"): Spaces.Location
    TypesLocation(Comment: "Folder for all type definitions"): Types.Location
    WSFacetIDName(Comment: "WebSocket Facet Id for TQL subscriptions"): TQL.FacetWS
    FacetIDName(Comment: "Http Facte Id for TQL Queries"): TQL.Facet
    TQLCacheName(Comment: "Storage name for the current package"): TQL.CacheName
    TopicFacetIDName(Comment: "???"): TQLGenericTopic
    MacroFacetID(Comment: "???"): Macro.Location
    SequenceFacetIDName(Comment: "Unique name for the Sequence Facet Instance"): TQLSequenceFacet
    WdlFacetIDName(Comment: "Unique name for the Workflow Facet Instance"): TQLWdlFacet
    TQLOutputFormat(Comment: "???"): XML
    ProjectSettings_EnforceKey(Comment: "???"): False
    ProjectSettings_ProjectKey(Comment: "???"): TQLStudio.ProjectKey

Workflow - Standalone Use of Workflow using Workflow Definition Language (WDL)

Workflow is one of the basic capability in the engine. It is used in the Thing and App Models by default to support actions. In addition, you can add this capability in the engine by writing new facet Instance of type SffWdlFacet. This means now you can write Facet Script containing workflow definitions, which will be processed by engine at the time of deployment. By linking this to Http Server Facet, workflow can receive inputs on Http Channel and generate response on this channel as well.

#
NewFacetInstance(fid: "[:RuntimeParams.WdlFacetIDName:]", Name: "wdl", Type: "SffWdlFacet"):
	OnActivate:
    	ImportFacet: [:RuntimeParams.MacroFacetID:]
    OnOpen(ModifyPipeline="HttpServerExtensionArgs"):
		#...

Topic - Standalone Use of Subscription and Notifications of Model changes. 

In A-Stack, every model artifact (model, attribute, instance) is defaulted to a topic in itself. Means clients can subscribe to any part of the model and start getting update events. In addition to model based subscriptions, independent pub-sub capability can be added in the engine, by writing SffTopicFacet Facet instance.

#
NewFacetInstance(fid: "[:RuntimeParams.TopicFacetIDName:]", name: "TQLGenericTopic", type: "SffTopicFacet"):
  OnActivate:
    DoRequest:
      Process:
        Message(type: "CDM"):
            Value:
              Subscribe(sid: "GenericTopicID", topic: "TQL.*"):
                Action:
                  logInfo: "CacheUpdate -> [:[:@Log:]$Request:]"
    OnOpen(ModifyPipeline: "HttpServerExtensionArgs"):
      #...

Sequence - Standalone Use of Scheduled jobs/task (Model code snippet)

Sequence provides the time based triggering, which can be against fixed time, delayed time, constant frequency, constant time intervals, etc.

#
NewFacetInstance(fid: "[:RuntimeParams.SequenceFacetIDName:]", name: "seq", type: "SffSequenceFacet"):
  OnActivate:
    OnActivate:
      #...
    OnOpen ModifyPipeline: "HttpServerExtensionArgs")
      #...

TQL - Thing Query Language Usage over an WebSocket Transport

All models provide subscription capability on websocket and that is achieved by adding TQLFacet and connecting it with the websocket pipeline. Note that your model file(s) created using Model Editor is referenced in this section.

#
NewFacetInstance(fid: "[:RuntimeParams.WSFacetIDName:]", Name: "TQL", Type: "SffTqlFacet"):
    OnActivate:
      NewFacetInstance(name: "tqlwfws", type: "SffWdlFacet"):
      TopicFacet: TQLGenericTopic
      ImportFacet: [:RuntimeParams.MacroFacetID:]
      Process:
        Storage(Name: "[:RuntimeParams.TQLCacheName:]", Type: "SqlSff"):
           Comment: "[:RuntimeParams.TQLCacheName:] Database SFF Unstructured SQL database"
        Namespace: # Your Model file is referenced here
          TQLStudio.DbmLocation

    OnOpen(ModifyPipeline: "WsServerExtensionArgs")

    OnRequest:
      DoRequest:
        Process(Return: "CMD_NOP"):
          Message:
            Value:
              Include: $Request.Message.Value
      DoResponse:
        Process:
          Message(type: "[:RuntimeParams.TQLOutputFormat:]"):
            Value:
              Include:$Response.Message.Value

TQL - Thing Query Language Usage over an HTTP Transport

Normal queries are posted on http channel and to achieve this capability, TQLFacet is created with http pipeline extension.

• Note that your model file(s) created using Model Editor is referenced in this section.
• In this section there is a default FacetScript code to perform enforcing usage of Project Keys (if set in Project Settings Menu).
  
  

#
NewFacetInstance(fid: "[:RuntimeParams.FacetIDName:]", Name: "TQL", Type: "SffTqlFacet"):
    OnActivate:
      Include: [:GetProjectModelsMacro:]
      Include: [:InstantiateModelMacro:]
      
      NewFacetInstance(name: "tqlwf", type: "SffWdlFacet"):
      TopicFacet: TQLGenericTopic
      ImportFacet: [:RuntimeParams.MacroFacetID:]
      Process:
        Storage(Name: "[:RuntimeParams.TQLCacheName:]", Type: "SqlSff"):
          Comment: "[:RuntimeParams.TQLCacheName:] Database SFF Unstructured SQL database"
        Namespace: TQLStudio.DbmLocation
        
    OnOpen(ModifyPipeline: "HttpServerExtensionArgs");
    
    OnRequest:
      SetContextData(key: "projectKey", value: "[:$Request.Arguments.x-atomiton-project-key:]")
      SetContextData(key: "projectSysId", value: "[:$Request.Arguments.x-atomiton-project-id:]")
      
      if("[:RuntimeParams.ProjectSettings_EnforceKey:]" == "true"):
        if($ContextData/projectKey == "[:RuntimeParams.ProjectSettings_ProjectKey:]"):        
              DoRequest:
                Process(Return: "CMD_NOP"):
                  Message:
                    Value:
                      Include: $Request.Message.Value
        else:
          SetResponse:
            Message(type: "[:RuntimeParams.TQLOutputFormat:]"):
              Value:
                Status: Failed
                Message: "Invalid Project Key"
      else:
        DoRequest:
          Process(Return: "CMD_NOP"):
            Message:
              Value:
                Include: $Request.Message.Value
                
      DoResponse:
        Process:
          Include: RESTHeaders
          Message(type: "[:RuntimeParams.TQLOutputFormat:]"):
            Value:
              Include: $Response.Message.Value

Note: The process of deploying Imported projects in A-Stack using User Interface (UI) is same as that of TQLStudio ThingSpaces.

For deployment directly to A-Stack using command line (without UI), see /wiki/spaces/TQLDocs/pages/1179774 in the Advanced Topics Section.

Instantiate

The final phase of Model development is actually using the Model using Queries. In some cases Models (Especially Thing / App Models) needs to be initialized to kick-start the whole process of interacting with Things or external application. In TQL, we use the term "Instantiate" to define the process of creating new instances on models. Model Instances can be created using either

• Create TQL Query
• Save TQL Query

Instantiate does the following tasks:

• It creates an instance, or instances of a Model
• It initialize the values of the model instances' attributes
• If any of the attributes is an actionable attribute, the associated Action will be triggered (provided the attribute value is initialized)

For example - Here is the Instantiate Query to start the Phidget Servo Motor Thing Model. Since the Pidget Servo Motor Thing Model is combined with PhidgetServoFacet Thing Facet, and there is a action on ServoAngle attribute waiting for event (create/update) to occur, therefore creating an instance results in triggering of the Action. 

#
Query:
	Create:
    	PhidgetServoModel:
      		ServoProtocolURL: 
				phid: "..."
      	PhidgetDeviceType: "PhidgetAdvancedServer"
      	DeviceInterfaceIndex: 0
      	ServoAngle: 110

You can instantiate in two ways.

(1) Instantiate by writing Save or Create TQL Queries in Query Editor.

(2) Instantiate using ThingSpace

ThingSpace provided easier way to instantiate the models. There are two ways to instantiate in ThingSpaces

a) Manual Entry of values

Once the model is instantiated using ThingSpaces it creates a file with Save Query automatically in Spaces folder of your project.

#
Query:
	Save:
    	VendorInfo(instantiated: true):
      		vendorName: Phidget
      		vendorTitle: SensorProvider

b) Import Instantiate data using CSV file format.

CSV file need to have the columns in order, in which the definition is provided. If no value, you can leave the column empty. If no values for trailing attributes, you don't have to create columns.