Deploy

Adapter for Files (Unix/Win) application archives may be deployed directly to an appropriate Silver Fabric Engine (TIBCO Logical Machine) by calling the REST method.

In this document cURL syntax is used to show REST inputs in a generic form: 

curl -u UserName:Password \
     -X POST \
     -H "Accept:application/json" \
     -H "Content-Type: multipart/form-data" \
     -F "archiveFile=@YourArchiveName.zip" \
     -F "deploymentFile=@YourDeploymentFileName.properties" \
    [-F "LogicalAnd=false"]
     -v "http://YourSFBroker.com:<port>/livecluster/rest/v1/sf/engines/archives"
    [-F "AppName=YourDirABC/YourAppName"]
    [-F "AppSettings.element1.element2=SomeValue"]
    [-F "ArchiveSettings.element1.element2=SomeValue"]
    [-F "Archives=Archive_A,Archive_B,Archive_X"]
    [-F "configurationFile=YourConfigurationfile.xml"]
    [-F "ForceDeploy=true"]
    [-F "GV=globalVariableA=123,globalVarB=SomeString"]
    [-F "InstanceSettings.element1.element2=SomeValue"]
    [-F "NoDeploy=true"]
    [-F "NoStart=true"]
    [-F "VariableProvider=Some_PROVIDER_Name"]

Where inputs bounded by square brackets are optional; file names, elements, variable names, and any values shown in italics should be substituted by your implementation values.

Tip: In a cURL statement all values must be URL-encoded so that special characters like spaces, for example, are converted to "%20". Other special characters like forward slashes "/" must also be converted to"%2F" or their respective URL encoded values so they may be sent and received properly.

Expressions in the generic form cURL expression above were separated by line breaks to help with readability, but normally a string is submitted in the execution as in the example below:

An example cURL archives deploy statement: 

curl -u admin:admin -X POST -H "Accept:application/json" -H "Content-Type: multipart/form-data" -v http://MySFBroker.com:8080/livecluster/rest/v1/sf/engines/archives -F "archiveFile=@MyProcessOrder.ear" -F "AppName=MyOrders/MyProcOrder" -F "deploymentFile=@MyDeployCriteria.properties"

Where the user specified by -u must have Silver Fabric administrator level permissions, and the form-data fields (-F "property=value") may be specified in any order. The form-data fields (-F) are described below:

Mandatory form-data contain the files necessary for the deployment:

archiveFile
  Specifies your Adapter for Files (Unix/Win) archive file (.zip or .ear file) to upload to the Silver Fabric Broker which will then publish the archive to the appropriate Silver Fabric Engine. Multiple application archives may be deployed in a single archive ZIP or EAR file. You can deploy and run them all (default behavior) or you can selectively run a list of archives by specifying that list with the Archives form-data field. Of course, archives may also be uploaded using the Component Wizard.
deploymentFile
 Specifies the properties file that defines endpoint selection criteria described in more detail below. 
     -F "deploymentFile=@YourDeploymentFileName.properties"
LogicalAnd
(Optional) By default all criteria specified in the deployment properties file must be satisfied for deployment to an application endpoint but that can be toggled to mean any (meaning logical OR) of the deployment properties criteria by setting:  -F "LogicalAnd=false"
-v
 Specifies the target of the cURL POST execution and asks for a verbose response. The cURL -v expression should specify the appropriate Silver Fabric directory. For the default installation that expression would look like the following: 
 -v "http://YourSilverFabricBrokerName.com:<port>/livecluster/rest/v1/sf/engines/archives"

Where the default http <port> is 8080 and optional form-data fields can specify other continuous deployment behavior.

AppName
(Optional)
Specifies the directory location where the application archive(s) will be deployed and what the application will be named.

Where your archive application will deploy and what it will be called depends on what you specify with AppName. For example when you use TIBCO Designer to create an .ear file with a name like MyAppArchive, varying the AppName specification will give following behavior:

  • If the AppName form-data field is not specified, then MyAppArchive will be deployed at the top level of the Administrator directory.
  • If -F "AppName=A" is submitted in the curl request, then MyAppArchive will be renamed to A and deployed at the top level.
  • If -F "AppName=A/" is sent, then the directory folder A is used or it will be created and MyAppArchive is deployed within that sub-directory.
  • If -F "AppName=A/B" is sent, then the sub-directory A is used or created, and MyAppArchive is deployed there and renamed to B.
  • If -F "AppName=A/B/" is sent, then the folder A with a sub-folder B will be used or created and MyAppArchive will be published within sub-folder B.

The full application name is derived from the AppName directory location and the application archive name as it is deployed.

Optional form-data fields don’t need to be specified unless you want to change the default behavior. By default all archives in the archive file are deployed and started unless an archive of the same name is already deployed and started, in which case that archive is allowed to run without interruption or replacement.

AppSettings
(Optional) Specifies settings that your application will use when deployed.

All deployment configuration cURL expressions will take the form:

 -F "AppSettings.element1.element2=SomeValue"

Some examples: 

 -F "AppSettings.localRepoInstance.encoding=UTF-8"
 -F "AppSettings.description=This%20application%20deployment%20is%20for%20validation%20testing."

Where the element is one of the following (plus any subordinate element2 where applicable):

  • description - A string describing the application.
  • contact - A string to name the person responsible for the deployment.
  • maxDeploymentRevision - Specifies the default number of application revisions to keep in the revision history for each deployed application. Leave the value at -1 to keep all revisions by default.
  • localRepoInstance - For Enabler installed components and application archives installed with continuous deployment, a local file (or directory of files) is used as the deployment repository instance.
    Note: When deploying applications your domain is automatically configured to establish a local application repository managed by TIBCO Runtime Agent. This helps to ensure proper functionality of deployed applications when using Fast TLM restart and HTTP discovery.
  • encoding - Specifies encoding for the repository instance. If this element is not specified, then the encoding for the admin server is used. If the admin server is not available, then the default for this element is ISO8859-1.
    Warning: All TIBCO components working in the same domain must always use the same encoding for intercommunication.
Archives
(Optional) The Form-data parameter that specifies a comma delimited list of archives within the zip that are to be deployed. If an archives list is omitted then all archives in the application archive package will be deployed. Example: 
 -F "Archives=Archive_A,Archive_B,Archive_X"
ArchiveSettings
(Optional) The form-data parameter specifies settings for the archive.
  • enabled (true or false) - Only enabled services are deployed. Disabling a service, effectively undeploys just that service while letting all other services in the application run as normal. This can be useful when you wish to deploy an application that includes a service for which you don't have the required software. A deployment configuration cURL expressions will take the form: 
     -F "ArchiveSettings.enabled=true"
  • av - Specify values for archive runtime variables with a comma-separated string with each key value pair joined by an equals (=) sign. For example: 
    -F "ArchiveSettings.av=Deployment=T2.HTTP_GET-Tomcat,Domain=Mine"
    Tip: Refer to the Appendix of the TIBCO Runtime Agent Scripting Deployment User’s Guide for a full list of Archive Settings properties, parameters, descriptions, and usage. Not all elements and properties are supported for use by the TIBCO Silver Fabric Enabler for Adapter for Files. The following is a first attempt at listing them all.
  • ruleBases: rule bases for the archive

    ruleBase.uri: location of the rulebase file. Example syntax: 

     -F "ArchiveSettings.ruleBases.ruleBase.uri=someValue"

    ruleBase.data: Rulebase content. Do not change this setting.

  • failureEvents.failureEvent:

    failureType: ANY, FIRST, SECOND, Subsequent

    If event is used then Type must be specified.

    Example syntax: 

    -F "ArchiveSettings.failureEvents.failureEvent.failureType=ANY"

    restart: true or false. If true, the service instance is restarted upon failure.

    description: information that describes this operation.

    alertAction.performPolicy: the policy to perform. Once - Generates an alert only for the first occurrence. Always - Generates an alert for each occurrence.

    alertAction.enabled: true or false. If true, the action will occur when conditions for the action are true. If false, the action is not called.

    alertAction.level: High, Medium, Low

    alertAction.message: The message that displays when this alert is triggered.

  • failureEvents.emailAction:

    performPolicy: the policy to perform. Once - Generates an alert only for the first occurrence. Always - Generates an alert for each occurrence.

    enabled: true or false. If true, the action will occur when conditions for the action are true. If false, the action is not called.

    message: the message to send.

    to: a comma-separated list of email addresses to which the message will be sent.

    cc: a comma-separated list of email addresses to which copies of the message will be sent.

    subject: the subject of the email message.

    sMTPServer: The mail server (SMTP server) to use to send the message. Specify the host name or the host IP address.

  • failureEvent.customAction:

    performPolicy: the policy to perform. Once - Generates an alert only for the first occurrence. Always - Generates an alert for each occurrence.

    enabled: true or false. If true, the action will occur when conditions for the action are true. If false, the action is not called.

    command: specify the script to execute. Script files are highly recommended.

    arguments: the list of arguments for the command

  • suspendProcessEvents.suspendProcessEvent:

    restart: true or false. If true, the service instance is restarted upon failure.

    description: information that describes this operation.

    alertAction.performPolicy: the policy to perform. Once - Generates an alert only for the first occurrence. Always - Generates an alert for each occurrence.

    alertAction.enabled: true or false. If true, the action will occur when conditions for the action are true. If false, the action is not called.

    alertAction.level: High, Medium, Low

    alertAction.message: The message that displays when this alert is triggered.

    emailAction.performPolicy: the policy to perform. Once - Generates an alert only for the first occurrence. Always - Generates an alert for each occurrence.

    emailAction.enabled: true or false. If true, the action will occur when conditions for the action are true. If false, the action is not called.

    emailAction.message: the message to send.

    emailAction.to: a comma-separated list of email addresses to which the message will be sent.

    emailAction.cc: a comma-separated list of email addresses to which copies of the message will be sent.

    emailAction.subject: the subject of the email message.

    emailAction.sMTPServer: The mail server (SMTP server) to use to send the message. Specify the host name or the host IP address.

    customAction.performPolicy: the policy to perform. Once - Generates an alert only for the first occurrence. Always - Generates an alert for each occurrence.

    customAction.enabled: true or false. If true, the action will occur when conditions for the action are true. If false, the action is not called.

    customAction.command: specify the script to execute. Script files are highly recommended.

    customAction.arguments: the list of arguments for the command

  • logEvents.logEvent:

    restart: true or false. If true, the service instance is restarted upon failure.

    Example syntax: 

     -F "ArchiveSettings.logEvents.logEvent.restart=true"

    match: The string in the log file to match.

    description: information that describes this operation.

    alertAction.performPolicy: the policy to perform. Once - Generates an alert only for the first occurrence. Always - Generates an alert for each occurrence.

    alertAction.enabled: true or false. If true, the action will occur when conditions for the action are true. If false, the action is not called.

    alertAction.level: High, Medium, Low

    alertAction.message: The message that displays when this alert is triggered.

    emailAction.performPolicy: the policy to perform. Once - Generates an alert only for the first occurrence. Always - Generates an alert for each occurrence.

    emailAction.enabled: true or false. If true, the action will occur when conditions for the action are true. If false, the action is not called.

    emailAction.message: the message to send.

    emailAction.to: a comma-separated list of email addresses to which the message will be sent.

    emailAction.cc: a comma-separated list of email addresses to which copies of the message will be sent.

    emailAction.subject: the subject of the email message.

    emailAction.sMTPServer: The mail server (SMTP server) to use to send the message. Specify the host name or the host IP address.

    customAction.performPolicy: the policy to perform. Once - Generates an alert only for the first occurrence. Always - Generates an alert for each occurrence.

    customAction.enabled: true or false. If true, the action will occur when conditions for the action are true. If false, the action is not called.

    customAction.command: specify the script to execute. Script files are highly recommended.

    customAction.arguments: the list of arguments for the command

  • failureCount: The value in this field defines how many restarts should be attempted before resetting the error counter to 0.
  • failureInterval: The value in this field defines how much time should expire before resetting the error counter to 0.
InstanceSettings
 (Optional) Some syntax examples: 
-F "InstanceSettings.initHeapSize=64"
-F "InstanceSettings.maxHeapSize=512"
-F "InstanceSettings.threadStackSize=512"
  • description: Specify any pertinent information about the binding.
  • contact: Name the person responsible for this application instance.
  • startOnBoot: When true the service instance starts when the computer is restarted. Default value is false.
  • enableVerbose: When true, sets the Enabler for verbose tracking for service instances. Default value is false.
  • runAsNT: When set to true the service is run as a Microsoft Windows Service. You can then manage the engine as you would any other service, and you can specify that it starts automatically when the machine reboots.
  • startUpType: Specifies the instance service startup type as either: Automatic, Manual, or Disabled.
  • login: Specifies the login account for the service, if any. The domain name must be specified as well.
  • password: Sets the password for that service, if any.
  • iv : This element uses a comma-separated string with name-value pairs with each key value pair joined by an equals (=) sign. For example:
configurationFile
  (Optional) The form-data parameter used to include an XML configuration file created to modify archive properties if needed. Example syntax: 
 -F "configurationFile=YourConfigurationfile.xml"

Where your XML configuration file should use the same format as an enabler or component level configure.xml file with the outermost XML element as follows: 

 <archiveConfig name="YourArchiveName">
    ...
 </archiveConfig>
For more information on writing an archive configuration file, see the "Using the Silver Fabric SDK" chapter of the Silver Fabric Developer’s Guide.
ForceDeploy
(Optional) Redeploy, forces a stop and overwrite of a pre-existing archive or set of archives with the same name. By default ForceDeploy is set to false and so a second deployment does not overwrite a pre-existing deployment of the same name. If there is a change of the archive file then ForceDeploy should be set to true so that the new application archive is redeployed. If ForceDeploy is used with -F Archives specifying a comma delimited list, then only those archives are stopped, undeployed, and redeployed. 
 -F "ForceDeploy=true"
GV
(Optional) Sets global variables for use on the targeted application endpoint by the archive. The GV form-data field lets you define a comma delimited list of declarative name equals value statements. 
 -F "GV=globalVariableA=123,globalVarB=SomeString"

For example to change the JMS SSL and Rv Service ports: 

 -F "GV=JmsSslProviderUrl=ssl://localhost:7555,RvService=7222"

If global variables are not defined with explicit values in the cURL statement then those values you may have set in the deployment configurationFile.xml will apply.

If global variables with the same name are set by both REST statement and a specified variable provider then the value set by REST statement will overwrite and take precedence over the value set in the variable provider.

VariableProvider
(Optional) Specifies a variable provider to set global variables for applications deployed with REST. The variable provider is a Java Class extension compiled into a JAR and loaded into a Silver Fabric directory with an appropriate XML so that it may be called by REST during application deployment. 
 -F "VariableProvider=Some_PROVIDER_Name"

See Creating a Variable Provider for use by a REST call.

NoDeploy
(Optional) The default value is false which means that the archive(s) are uploaded to the Silver Fabric Broker and they are deployed to the application endpoints. When NoDeploy is set to true, the archives are uploaded with associated service Enabler bindings created in TIBCO Administrator, but the archives are not deployed to a Silver Fabric Engine and the application endpoint. 
 -F "NoDeploy=true"
NoStart
(Optional) The default value is false, meaning that the archives are both deployed and started by default. If NoStart is set to true, the application will be deployed but not started. 
 -F "NoStart=true"