Working with Process Tasks

Working with Process Tasks

Logi Info
v12.7 - Aug 2019

Page 1

1 | 2

Logi Info includes Process definitions, a special type of definition that lets you create subroutine-like tasks that can include conditional processing, branching, error handling, and other advanced features. This document discusses Process definitions and tasks. Topics include:
 

 

About Process Definitions and Tasks

Process definitions are similar to Report definitions and they're created and managed in Logi Studio in the same way. They contain element groups called Tasks, which are created in Logi Studio using elements in a manner similar to creating a Report definition. Unlike Report definitions, tasks run at the web server and don't present anything visual in the browser.
 

In the file system, Process definition files are physically stored in your application folder, as shown above, in the _Definitions_Processes folder. They're .lgx type files and use the same XML source code found in Report definition files.

 

     

In Logi Studio, Process definitions appear in the Application panel listed under the Processes folder, as shown above. You can add a new process definition by selecting and right-clicking the Processes folder and manage them in Studio like any other definition.

Each Process definition file contains one or more tasks. So, you may decide to use multiple Process definition files in your application. You may prefer to put all of your tasks in a single definition file, or to group tasks, by function for example, in separate Process definition files. The choice is to yours; the Logi Server Engine will include all Process definition files when it runs the application.

 


     

Tasks are created in a Process definition by adding a Task element to the definition root. The example shown above includes three tasks.

  The top-to-bottom order of Task elements in a Process definition does not matter (a suggestion: alphabetical order makes them easier to find). However, within a task the position of its child elements is important because they're processed in a top-to-bottom sequence.

 


     

The example above shows some of the elements available for use in a task; they can perform a variety of operations. Some look similar to those used in Report definitions while other are unique to Procedure definitions.

Tasks can accomplish many things that cannot be done in a Report definition. For example,

  • Direct interaction with the web server file system (to save, copy, or delete folders and files)
  • Conditional processing using If-Then branching of processing flow
  • Row-by-row processing of datalayer or data table contents
  • "Write back" to databases, to insert and update records
  • Generic and error-specific error handling (including SQL errors)
  • Send email, SMS messages, and Twitter tweets
  • Save file uploads and the state of super-elements
  • Set and clear client-side cookies
  • Create and manage Logi Scheduler tasks
  • Terminate server session

and they can do many of the same things, such as exports, plug-in calls, database operations, and more.

When using Logi Security, the Task element's Security Right ID attribute provides greater security control over the running of tasks.

Tasks are essential to use of the Logi Scheduler: when the Scheduler runs a scheduled event, it calls a Process task, which then runs the desired report and manages its output. For more information about this, see our document Introducing the Logi Scheduler

You can use a Default Request Parameters element in a Process definition, as you would in a Report definition, and you can also use it within individual tasks.


Process definitions and tasks extend the capabilities of Logi Info apps in many ways, and provide with tremendous functionality. The remainder of this document provides examples of some of these capabilities in use.

  Back to top

 

Calling and Completing a Task

In order to use a task, you must call it, and when it completes, it needs to redirect processing to someplace else.
 

Calling a Task from a Report Definition

As Logi report developers, we're used to "calling" one report definition from another report definition, using links, buttons, or events. When doing that, we can pass information to the next report using Link Parameters and we know that User Input element values are POST'ed to the next report as Request variables. The same is true when calling a Process task from a report.
 

 

In the Report definition example shown above, an Action.Process element is used beneath a Label element to redirect processing to a task. The Action element's attributes identify the Process Definition File and the Task ID of the task to be called; these values can be selected from drop-down lists. A Link Parameters element can also be used beneath the Action element, if desired, to pass information to the task.

When processing is transferred to the task, the Link Parameters and any User Input element values will be available in the task as Request variables and can be used there via @Request tokens.

 

Calling a Task when a Report Loads

You can have a task run automatically when a Report definition loads. This "onLoad event" behavior allows you to set variables, run procedures, and accomplish any other initializations you might want to do, and then redirect the browser back to the report definition.
 

As shown above, the Startup Process element is added to a Report definition, and its attributes are set to identify the desired Process Definition and Task ID for the "startup task".

Any Request variables in the query string used to call the report definition will automatically be available as Request tokens in the Process task called with this element. For example, the @Request.rdReport~ token will contain the name of the report definition specified in the URL. Note that any parameters set using Default Request Parameters element are not passed to the task.

You can use a Response element at the end of the startup task to redirect the browser to a specific report definition after the task completes but this is optional. Without one, the browser will be automatically redirected back to the original report definition.

The element's Condition attribute can be used to dynamically control when the Startup Process will be called.

Multiple Startup Process elements may be used to call different process tasks; they'll be run sequentially, one after the other.
 

Calling a Task from a URL

You can also call a process task directly from a URL, using the following syntax:

    http://www.myReportSite.com/myLogiApp/rdProcess.aspx?rdProcess=myTasks&rdTaskID=taskUpdate&myParam=1

where rdProcess and rdTaskID are required and additional request variables, such as myParam, are optional.

This URL can be used, for example, with an Action.Link element, or even from an external application.
 

Calling a Task from Another Task

Under certain circumstances, you may want to transfer operations from one task directly to another task.

The Procedure.Process Task element lets you directly call another task, in the same or in a different Process definition. A child Link Parameters element can be used to pass values to the target task. This does not operate like a function - the designated task will be executed but operations will not "return" to the first task afterwards.

You can also use a more "manual" approach, with the Response.Link element:
 

In this case, you would use a Response.Link element, as shown above and, in its Target.Link child element's URL attribute, use the syntax shown in the previous section for calling a task from a URL. You can use @Request tokens right in the URL to forward request variables sent to the first task, so they'll be available in the second task, like this:

http://www.mySite.com/myApp/rdProcess.aspx?rdProcess=myTasks&rdTaskID=taskNext&myVar=@Request.myVar~

Recursion and nesting do not exist for tasks; one task just leads to another and the last task needs to handle redirection to a visible web page.
 

Calling a Task at Session Start

You can have a task run automatically when a user session begins (i.e., when the application is browsed by a user for the first time). This allows you to set variables, run procedures, and accomplish any other "startup" work you might want to do, and then redirect the browser to a report definition.
 

As shown above, the Startup Process element is added to the _Settings definition, and its attributes are set to identify the desired Process Definition and Task ID for the "startup task".

Any Request variables in the query string used to call the application will automatically be available as Request tokens in the Process task called with this element. For example, the @Request.rdReport~ token will contain the name of the report definition specified in the URL. Note that any parameters set using Default Request Parameters element are not passed to the task.

You can use a Response element at the end of the startup task to redirect the browser to a specific report definition after the task completes but this is optional. Without one, the browser will be automatically redirected to the application's default report definition.

The element's First Session Only attribute can be used to prevent the Startup Process from being called if the application is called recursively.

Multiple Startup Process elements may be used to call different process tasks; they'll be run sequentially, one after the other.
 

Completing a Task

When processing is transferred to a task and it completes, there is no "stack" to unwind, no built-in return path back to the calling Report definition. As the developer, you must explicitly transfer processing somewhere else after a task completes. If you don't, your user will be left looking at a blank browser screen!
 

Tasks use Response elements, as shown above, which end a task by redirecting processing, usually back to a Report definition. You can also redirect instead to another task, as discussed earlier. You should ultimately redirect to a visible page so the user sees something in their browser.

The Response.Raw element can be used to complete a task and gives you full control of the response. This can be especially useful when building a REST API call from a Process. Response.Raw responds with a value and optional response headers.
 

In the example above, the Response.Raw element is used to provide response values using @Procedure tokens. Its Response Header Params child element can be used to provide custom response headers and values. The Response.Raw element's attributes are:

  • Content Type - If left blank, the default content type is text/plain; charset=utf-8
  • Status Code - The HTTP response status code; if left blankt, the default value is 200
  • Status Description - The HTTP response status description; if left blank, the default value is OK
  • Value - The response value; @Procedure tokens may be used here.
     

  Back to top

 

If-Then Branching in a Task

Data validation provides a fine example of conditional branching within a task. Tasks are excellent places to do data validation if you can't, or don't want to, do it in a Report definition.
 

In the task example shown above, we introduce the Procedure.If element, which allows you to use conditional branching in your task. In the example, we want to validate a password entered by the user in a report definition. The Save button in the report calls this task and the Procedure.If element's Expression attribute uses an @Request token to access the password value. If the Expression attribute formula evaluates to True, then its child elements will be processed. If it evaluates as False, the child elements are ignored and the next sibling element down will be processed.

So, if the evaluation is True (the password is less than 8 characters long), we skip the Procedure.SQL element and run the Response.Report element. A further enhancement to this task would be to add a Link Parameters element beneath Response.Report to pass an error message back to the calling report.

If the evaluation is False, the password length is acceptable and the next sibling element, the Procedure.SQL element, is processed. Once it completes, processing goes on to the Response element at the end of the task to redirect processing elsewhere.

You can have multiple Procedure.If elements in a task and they can be nested. They're useful, of course, for many other purposes besides data validation and can be used any time you want to direct processing flow based on evaluation of an expression.

Several other elements are available for use in controlling conditional branching:

Procedure.Else - This element must be a sibling of, and immediately follow, a Procedure.If element. It identifies a conditional block of procedures that will be run if the Procedure.If element immediately above it evaluates to False. If the Else block ran, the token @Procedure.myProcedureID.rdReturnValue~ returns True, otherwise it returns False.

Procedure.Switch - This element works with one or more child Procedure.Switch Case elements to define conditional blocks of procedures to be run when a specified value matches. Use it when there are multiple conditional blocks defined and just one of them is to be run, based on the value of a variable. You can also use a child Procedure.Switch Else element, which runs its block of procedures if none of the previous Switch Case elements match the specified value.

The value to test against is specified in the Expression attribute and can be literal value, a token, or even JavaScript that evaluates to a value. The Data Type attribute ensures comparisons, especially of dates, are made correctly.

  Back to top

 

Setting Variables in a Task

In a task, you may need to have working variables that you can manipulate. For example, you may need to perform a calculation on a Request variable value. There are several ways to create these "local variables".

The Procedure.Set Procedure Vars element allows you to set variables and values that can be used for calculations, etc., within the scope of the task.
 

Variables are created using a child Procedure Parameters element, which defines name-value pairs, just like other parameters elements, as shown above. The values can be set using literals, tokens, or expressions prefaced with the "=" sign. The resulting procedure variables can be referenced anywhere in the task using this token:

    @Procedure.<Procedure.Set Procedure Vars element ID>.<variable name>~

Session variables can be also used in the same way for this purpose:
 

In the example above, a Procedure.Set Session Vars element has been added. The new session variable it creates applies the DateAdd function to a date passed as a Request variable. Now, in the Procedure.SQL element, we can use the token @Session.newStart~ to update a database table with the new date.

Session variables set in tasks are, of course, globally available and can be accessed later in report definitions and other tasks.

  Back to top

 

File System Interactions from a Task

Tasks can include Procedure elements that allow direct manipulation of files on the web server or on network-connected drives. To do this, of course, the account used by the web server to run your Logi application needs to have appropriate file access permissions. Here are the elements available for file system interactions:
 

Element

Description

Procedure.Compress File

Compresses the named file, using the .ZIP format. You must specify both the source and destination file names. Wild cards are allowed, see below. Specify a fully-qualified path and file name.

Procedure.Compress Folder

Compresses the named folder and its contents using the .ZIP format. Maintains the hierarchy of any sub-folders and files within it. You must specify both the source folder name and destination file name. Specify a fully-qualified path and folder name.

Procedure.Copy File

Copies a single file. You must specify both the source and destination file names. If it already exists, the destination file is overwritten without warning. Specify a fully-qualified path and file name.

Procedure.Create Folder

Creates a new file system folder. No error occurs if the folder already exists. Specify a fully-qualified path and folder name.

Procedure.Delete File

Deletes a file. No error occurs if the named file does not exist. Specify a fully-qualified path and file name.

Procedure.Delete Folder
 

Deletes a folder and its contents. No error occurs if the specified folder does not exist. Specify a fully-qualified path and folder name.

Procedure.File Exists

Returns True and executes its child elements if the named file is found in the web server file system. Specify a fully-qualified path and file name.

The token @Procedure.<myProcedureElementID>.rdReturnValue~ will return True or False depending on file existence.

Procedure.Folder Exists

Returns True and executes its child elements if the named folder is found in the web server file system. Specify a fully-qualified path and folder name.

The token @Procedure.<myProcedureElementID>.rdReturnValue~ will return True or False depending on folder existence.

Procedure.Run Shell Command

Executes an OS command-line command or application and optionally passes in parameters. See special section below for more information.

Procedure.Uncompress File

Expands a compressed .ZIP file. If no destination folder is specified, the files are written to the application's rdDataCache directory. Wild cards are allowed for selectively identifying files to be uncompressed, see below. You must specify a fully-qualified path and compressed file name.

Procedure.Uncompress Folder

Expands a compressed folder and its contents. Maintains the hierarchy of any sub-folders and files within it. You must specify both the source file name and the destination folder name and they must include a fully-qualified path.

Procedure.XML Modifier

Allows you to update an XML file from a Process Task. Information about using this element is available in our document Using Procedure.XML Modifier.


You can use tokens, such as @Function.AppPhysicalPath~ and @Data.FileName~, to provide the part or all of the file or folder names required in these attributes. Valid characters that can be used in file and folder names are those allowed by the web server operating system.

The wildcards characters * and ? can be used where mentioned in the descriptions above. For example, to compress all files in a folder, leave the Files To Compress attribute blank or enter *.* and to compress only XML files that start with an S, enter S*.xml.
 

Using Procedure.Run Shell Command

The Procedure.Run Shell Command element allows you to run OS shell commands or applications from a task and handle their output.

 Commands and applications launched using this element run synchronously and will block the processing of the rest of the task until they complete.

Here are the element's attributes:
 

Attribute Description

ID

(Required) Specifies a unique identifier for this element.

Error Output Filename

Specifies an method of handling error output from a shell command, as follows:

  • Leave blank to have error output included in the return values, or
  • Specify a fully-qualified file path and file name to send error output to a file, or
  • Specify "NUL" to ignore error output

If left blank, the error output can be accessed using the token @Procedure.<myProcedureID>.ErrorOutput~.

Filename

Specifies the filename of a shell or application to execute, as follows:

  • For Windows PowerShell, enter powershell and preface Shell Command Parameters with "/C".
  • For the Windows Command Line, enter cmd and preface Shell Command Parameters with "/C".
  • For Linux, enter the path to the command, such as /usr/bin/cp.
  • For applications, enter the fully-qualified path and filename of the executable file. If not located within your Logi application folder, then the account used by web server to run Logi app must have Read & Execute file access permissions for the executable file.
  • Tokens may be used here.

Shell Command Parameters

Specifies a string of parameters for the shell command. In a command line, this is the typically the part of the command that goes after the actual command name. Begin the string with "/C" if using the Windows Command line. Examples, with parameter string highlighted in yellow:

    powershell /C Test-NetConnection
    cmd
    /C COPY *.* c:\temp /Y
    /usr/bin/ps -ef

 Be sure to include any switches needed to suppress any prompts, such as "/Y" in the COPY example above. Otherwise, the task will "hang" indefinitely.

Standard Output Filename

Specifies a fully-qualified path and filename to be used to store the shell command's or application's "standard output". This is the output typically seen when running a shell command from a command prompt. Tokens may be used here.

If left blank, standard output can be accessed using @Procedure.<myProcedureID>.StandardOutput~.

Timeout

Specifies the length of time, in seconds, to wait for an action to complete before a timeout error occurs. If set to 0, then the task will wait indefinitely until the request completes. Entering a value here is a good idea, to protect against the task "hanging", but be sure to allow enough time for the shell to launch, interpret and execute the command and any parameters, and return a result. You may wish to experiment with different values and you can enter decimal values less than a whole second, such as 0.001, if appropriate.

Working Directory

Specifies the fully-qualified path to the folder to be used as the context of the shell command or application. Tokens may be used here.

 

The following tokens are available for use with Procedure.Run Shell Command:
 

Token Description

@Procedure.myProcedureID.ErrorOutput~

If the element's Error Output Filename attribute has been left blank, this token contains the shell command's or application's error output. If no error has occurred, this token will have no value.

@Procedure.myProcedureID.ExitCode~

Contains the "exit" or "return" code from the shell command or application, often 0 for success.

@Procedure.myProcedureID.StandardOutput~

If the element's Standard Output Filename attribute has been left blank, this token contains the shell command's or application's standard console output. If there is no standard output, this will have no value.

@Procedure.myProcedureID.TimedOut~

Contains True if a timeout occurred; otherwise contains False.


 

USAGE EXAMPLE: RUN A WINDOWS BATCH FILE

In this example, we'll use Procedure.Run Shell Command to run a simple Windows batch file that will "ping" a web site and display some parameters. Here's the batch file contents:

ping %1
echo %2 %3
echo

As you can see, it expects three parameters.

 

In the task definition shown above, you can see how the Procedure.Run Shell Command element's attributes are configured. Note the use of a token in the Filename value, and that there are three separate parameters, separated by a space, in the Shell Command Parameters.

Link Parameters are used in our example to pass the four related Procedure tokens to the response report.
 

The results are displayed in the response report as shown above.

 

USAGE EXAMPLE: TEST A NETWORK CONNECTION

In this example, we'll use a Windows PowerShell command to retrieve information about the network:

 

In the task definition shown above, you can see how the Procedure.Run Shell Command element's attributes are configured. Note the use of the shell invocation in the Filename value, and that "/C" is added before the shell command in the Shell Command Parameters.
 

The results are displayed in the response report as shown above.

For purposes of illustration, let's make the command invalid by adding "x" to it, so the Shell Command Parameters value is "/C Test-NetConnectionx", and re-run the task:
 

Now we can see that the Exit Code, Standard Output, and Error Output values have changed.

 

USAGE EXAMPLE: RUN A LINUX COMMAND

In this example, we'll use the Linux "ps" command to display a formatted list of active processes:
 

In the task definition shown above, you can see how the Procedure.Run Shell Command element's attributes are configured. Note the use of the Linux "ps" command in the Filename value, and the "-ef" flags in the Shell Command Parameters.
 

The results are displayed in the response report as shown above.

 

USAGE EXAMPLE: RUN A LINUX COMMAND USING TOKENS

In this example, we'll use the Linux "cp" command to copy a file:
 

In the task definition shown above, you can see how the Procedure.Run Shell Command element's attributes are configured. Note the use tokens in the Shell Command Parameters value, which in its entirety is:

    @Function.AppPhysicalPath~/test.txt @Function.AppPhysicalPath~/test.out -f
     

 The ability to run shell commands can be dangerous, so use this element with care.

  Back to top

 

Exporting from a Task

You can create tasks that include procedures that export reports or data. This is done in the task by running a "hidden instanced" of an existing Report definition and then exporting it or its data.

 There is a difference between exporting reports from a Report definition and from a Process task. An export from a Report definition is written out as a temporary file in your application's rdDownload folder and then that file is opened for viewing in the user's browser. The temporary file is automatically deleted later. An export from a Process task is saved as a file in a location, and with a filename, you specify and it's not opened automatically in the browser. It's not considered a temporary file, so it's not deleted later automatically; you may have to manage it separately.

So, exporting from a Process task is useful when you need to save a file to the web server for later use, such as:

  • Archiving data or reports
  • Creating attachments to be sent with e-mails
  • Building a custom Data Cache (XML export) that can be used later by your reports

More information about exporting can be found in our export documents.
 

As shown in the example above, an export procedure such as Procedure.Export PDF is added to a task, and its Filename attribute is set to the fully-qualified path for the export file, including the file name and extension. The account being used to run the Logi app must have Write permissions to the storage location (usually this is already in place if you're saving to any folder within your application folder), and the @Function token for the application path can be used here, as shown above.

The Target.PDF element can be used to specify the Report Definition File to be exported. If not specified, the "Current Report" definition - the one that called the task - will be exported. Why have an option? You may have created two similar definitions - one for browsing and one for exporting.

If you specify a table in the Target.PDF element's Data Table ID attribute, then just that table's data (without headers, footers, etc.) will be exported. See Logi Studio's Information Panel text for more information about other Target element attributes that are specific to different export types.

If the original report depended on Request variables to set queries, filtering, etc. then be sure to either set the Target element's Request Forwarding attribute to True, or to use Link Parameters, to ensure that the exported file is similarly configured.

The elements for exports to other formats (Word, Excel, CSV, etc.) operate in a similar fashion.

DevNet includes a sample application that demonstrates exporting using process tasks.

  Back to top

 

Using Local Data in Tasks

The Local Data element is available for use in Process definitions.
 

It operates in them in the same manner that it does when used in Report definitions and the data its datalayer retrieves can be accessed from any task in the Process definition using an @Local Data token. For a full explanation of this element, see our Introducing Datalayers document.
 

  Back to the top

1 | 2

 


© Copyright 2007-2019 Logi Analytics, Inc. All Rights Reserved