tFLOW XML automation

tFLOW

Intro

 
Easy integration of tFlow with existing MIS/ERP  is based on hotfolders with XML.
Each instance of tFlow contains a special folder located under root here “\repository\input”, and a scheduler (PostgreSQL PGAgent) is installed and configured by default to scan the folder every minute.
Once a valid XML is found, it is processed by a script, and if the data is valid, the process  is triggered.
 
At end of the operation an email is sent to the users associated to that job - approvers, managers, etc. depending upon their notification settings.
 

XML Commands

 
The XML import function supports two commands:

create_job
This command creates automatically a new job in tFlow.
A “create_job”  command can contain several jobs and as an option can contain the artwork name. In this case the pdf of the artwork must be also uploaded to hot folder together its sidecar XML files.
update_orders
The update_orders command is useful when one or more order(s)/job(s) data must be updated from MIS.
 

 

Create_Job XML format

 
Sample XML file:
 
<?xml version="1.0" encoding="UTF-8"?>
<approval secret_key="Ah5l5DfuebGJ5KDh235g59Bf6fp2DsJHcF3Gfnn1xk">
   <command type="create_job">
      <workflow_name>Approval Workflow</workflow_name>
      <client_name>Alpha LLC</client_name>
      <order_name>XML Workflow Test</order_name>
      <order_description>This is the order description and could be empty</order_description>
      <job_name>Demo XML 1</job_name>
      <description>This is the job description and could be empty</description>
      <quantity>100</quantity>
      <start_date>2015-01-19</start_date>
      <ship_date>2015-01-31</ship_date>
      <user_email>user@domain.com</user_email>
      <user_name>Dmitry Bagdanov</user_name>
      <user_password>123</user_password>
      <artwork>document.pdf</artwork>
      <artwork_size>477187</artwork_size>
      <min_width_inches>40</min_width_inches>
      <min_height_inches>30</min_height_inches>
      <min_res_ppi>100</min_res_ppi>
      <product_name>Brochure</product_name>
      <tflows>
         <tflow name="TURBINE-F-808" queue="Full Color" />
         <tflow name="TURBINE-F-808" queue="CMYK" />
      </tflows>
   </command>
   <command type="create_job">
      <workflow_name>Approval Workflow</workflow_name>
      <client_name>Alpha LLC</client_name>
      ….
   </command>
   <command type="create_job">
      <workflow_name>Approval Workflow</workflow_name>
      <client_name>Alpha LLC</client_name>
      ….
   </command>
</approval>
 
 
The supported tags are:
 
 
 
  • secret_key:                 
    mandatory, attribute of approval root must be equal to the string SECRET_KEY defined in the system
  • command type:            
    mandatory, type attribute of command node could be one of the following strings:
  • “create_job"
  • “update_Order”
  • client_name:               
    mandatory, case sensitive. Depending on system configuration this could be:
      1- equals to an existing client name in tFlow DB
      2- if not existing it will be created
  • workflow_name:         
    <workflow_name>Approval Workflow #1</workflow_name>
    not mandatory, must be unique, case sensitive, equals to an existing workflow name in tFlow DB.
  • order_name:               
    mandatory, must be unique, case sensitive, if order_name does not exists a new order is created, if exists the job will be created in the orders
  • order_description:      
    mandatory, could be empty string, useful for order creation, if order exists is ignored
  • job_name:                   
    mandatory, must be unique in the system, case sensitive, if job name does not exists in the DB then a new job is created, if it exists then a new revision is added to the job
  • description:                
    mandatory, could be empty string, description useful to better describe the job
  • quantity:
    the job printing required quantity
  • start_date:                  
    mandatory, must be in the ISO format: YYYY-MM-DD (example: 2013-05-01)
  • ship_date:                   
    mandatory, must be in the ISO format: YYYY-MM-DD (example: 2013-12-31)
  • user_email:                 
    mandatory, case sensitive. Equals to an existing and enabled user in tFlow DB, if doesn't match with the user name then the command is cancelled. If both user_name and user_email aren’t present in the DB then they are created
  • user_name:                 
    mandatory, case sensitive. Depending on system configuration this could be:
    1- equals to an existing user in tFlow DB
    2- if not existing it will be created
  • user_password:           
    not mandatory, case sensitive == assigned to new user in the case is not existing and then the system assign a default “123”
  • artwork:                     
    optional, enter the document filename. If a filename if provided then tFlow will import also the artwork PDF else and job is creating in the “Awaiting Artwork” status.
  • artwork_size:              
    optional, enter the file size in bytes of the document to upload. This is mandatory only if the artwork tag is not empty.
  • min_width_inches:       
    not mandatory  == the final artwork size in inches. This is needed when a special preflight profile that resizes the document is used. In this case the artwork will be automatically resized to this width.
  • min_height _inches:    
    not mandatory  == the final artwork height in inches. This is needed when a special preflight profile that resizes the document is used. In this case the artwork will be automatically resized to this height.
  • min_ res _ppi:              
    optional, the desired wanted resolution in ppi, if the resized document will have lower res then an error will be triggered and the job status will be changed to “On Hold”
  • product_name:                       
    optional, case sensitive, the name of the product to use. If empty then the default product is used.
  • tflows:                        
    optional, case sensitive, the name(s) of the external production system and queue defined in tFlow where to send approved jobs for production.
    If the tFlow name tag is omitted then the system will scan all the available queues and will look for a queue with that name.

 

Update_Job XML format

 
Sample XML file:
 
<?xml version="1.0" encoding="UTF-8"?>
<approval secret_key="Ah5l5DfuebGJ5KDh235g59Bf6fp2DsJHcF3Gfnn1xk">
   <command type="update_order">
      <order name="XML Import Order 1">
         <description>New order description</description>
         <name>New order name</name>
         <ship_date>2015-12-31</ship_date>
         <start_date>2015-12-31</start_date>
         <min_width_inches>55</min_width_inches>
         <min_height_inches>66</min_height_inches>
         <min_res_ppi>99</min_res_ppi>
         <product_name>Brochure</product_name>
         <jobs>
            <job name="XML_Job1">
               <description>New description</description>
               <name>New job name</name>
               <ship_date>2015-12-31</ship_date>
               <start_date>2015-12-31</start_date>
               <min_width_inches>55</min_width_inches>
               <min_height_inches>66</min_height_inches>
               <min_res_ppi>99</min_res_ppi>
               <product>Brochure</product>
            </job>
            <!-- additional jobs to update within the given order -->
         </jobs>
      </order>
      <!-- additional orders to update -->
   </command>
</approval>
 
 
The supported tags are:
command type: mandatory, type attribute of command node could be one of the following strings:
  • “create_job"
  • “update_order”

<order> tag
  • order-name:              
    mandatory, must be unique, case sensitive name of an existing order, if it does not exists then the order is skipped and processed the next one (if present)
  • description:                
    optional, new order description string.
  • name:                         
    optional, must be unique in the system, case sensitive, if name does not exists in the DB then this name will be assigned to the order else the command is cancelled.
  • start_date:                  
    optional, must be in the ISO format: YYYY-MM-DD (example: 2015-05-01)
  • ship_date:                   
    optional, must be in the ISO format: YYYY-MM-DD (example: 2015-12-31)
  • min_width_inches:       
    optional == the final artwork size in inches. This is need when a special preflight profile that resizes the document is used. In this case the artwork will be automatically resized to this width.
  • min_height_inches:    
    optional == the final artwork height in inches. This is need when a special preflight profile that resizes the document is used. In this case the artwork will be automatically resized to this height.
  • min_ res _ppi:              
    optional, the desired resolution in Points per Inch (ppi), if the resized document will have lower res then an error will be triggered and the job status will be changed to “On Hold”.
     
  • <jobs> tag: optional, this tag contains one or more tags related to the jobs inside that order that need to be updated.
     
    • Job-name:                  
      mandatory, must be unique, case sensitive name of an existing job inside the order ((or within the whole system, depending on the system settings), if it does not exists command is skipped.
    • description:                  
      optional, new job description string.
    • name:                          
      optional, must be unique in the system, case sensitive, if name does not exists in the DB then this name is assigned to the job else the command is cancelled.
    • start_date:                  
      optional, must be in the ISO format: YYYY-MM-DD (example: 2013-05-01)
    • ship_date:                   
      optional, must be in the ISO format: YYYY-MM-DD (example: 2013-12-31)
    • min_width_inches:       
      optional == the final artwork size in inches. This is needed when a special preflight profile that resizes the document is used. In this case the artwork will be automatically resized to this width.
    • min_height_inches:      
      optional == the final artwork height in inches. This is needed when a special preflight profile that resizes the document is used. In this case the artwork will be automatically resized to this height.
    • min_res_ppi:                
      optional, the desired wanted resolution in Points per Inch (ppi), if the resized document will have lower res then an error will be triggered and the job status will be changed to “On Hold”.
    • product_name:              
      optional, case sensitive, the name of the product to use. If empty then the default product is used.
    • tflows:                          
      optional, case sensitive, the name(s) of the external production system and queue defined in tFlow where to send approved jobs for production.
      If the tFlow name tag is omitted then the system will scan all the available queues and will look for a queue with that name.

 

Notes on XML format

1. File encoding
 
Important: Save XML in UTF-8 format


2. Special characters encoding
Some characters are ‘special’ because they can be confused as XML markups, therefore they need to be written differently.  If you use one of the special characters below, you should use the name entities:
 
Symbol
Name Entities
&gt;
&quot;
&apos;
&
&amp;
<                  
&lt;
 
For example, to replace the < client_name > with “Alpha & Beta LLC” then you should not do this:
   <client_name>Alpha & Beta LLC</client_name>
 
Instead, use the special character notation like below:
   <client_name>Alpha &amp;Beta LLC</client_name>
 

3. Upload order
Please always upload the artwork (PDF) if present and only when the transfer is complete upload the  sidecar XML file.


 

How it works

By default each instance of tFlow (if the plan is including this addon), contains all elements (connector and hotfolder) and all the needed settings, so there is nothing to configure.
In order to trigger the Order/Job creation, simply copy a valid formatted XML file into the hot-folder.
 
We have 2 typical scenarios:

1- tFlow is inside a LAN

 
In this case it is sufficient to share the hotfolder with necessary permissions so that the XML file can be written inside the folder.
 
 

2- tFlow is in WAN (internet)

 
If the tFlow machine is located outside the LAN and is reachable only via Internet, then the best way is to set up an FTP server with access to the XML hot-folder.
All the instances running on cloud, if the plan is including this, are providing an FTP access for the XML automation, please contact us for login details.
Note: FTP is also possible in a LAN environment.
 
 
 
When the connector detects a valid XML file, the Order is created:
 
Please download a XML sample here: