Concerns: Vision Management Site
Edition: Futurama Export
Module: Futurama Server
User: User Management Site
- installation Futurama Server
Description how to use the Futurama Vision Management Site to start Futurama Server jobs
The Futurama Export edition consists of 2 modules: Futurama Console and Futurama Server. Futurama Server is an optional module of this edition. Using this module it is possible to define Futurama Server jobs. Futurama Server jobs are tasks that define which export process has to be run and which parameters have to be used for this process. The Futurama Vision Management Site can be used to run these jobs and monitor the status of the jobs. In this page the Futurama Server specific parts of the Futurama Vision Management Site are explained. Furthermore the definition of a Futurama Server job is explained.
If you have a license for the Futurama Server module, the Server menu in the Futurama Vision Management Site can be viewed. This menu does have two submenu's. The first submenu lists all the jobs that are defined. One of the defined jobs can be selected and executed. The second submenu displays the status of the jobs that have runned. See below for more information regarding these menu's.
This submenu displays all the Futurama Server jobs that are defined (see the paragraph 'Define Futurama Server jobs' for more information how to define a Futurama Server job). First of all the location of the Futurama Server jobs (XML-files) has to be defined. Within the section of the web.config of the Futurama Vision Management Site the key 'ActuIT_FuturamaServer_JobsDirectory' can be defined:
<add value="path" key="ActuIT_FuturamaServer_JobsDirectory"></add>
The value of ActuIT_FuturamaServer_JobsDirectory determines the default path to the Futurama Server jobs.
Note: make sure that that the identity of the application pool of Futurama Vision Management Site has read permissions to the location specified.
Press the start button to start a Futurama Server job. The export process defined in the specific Futurama Server job will be executed. The status of the job can be monitored in the next submenu.
The status of Futurama Server jobs can be monitored in this submenu. For each job that is started the next information is available:
Name: the name of the Futurama Server job. Corresponds with the name of the job in the previous menu.
Status: the status of the job. The job gets the status Completed when the job is finished. Press the refresh button to refresh the status
Progress: the progress of the export job. See the paragraph 'Define Futurama Server jobs' how to define the progress of a job
# Errors: the number of errors that have occurred during the export. More information about the errors can be found in the logfiles of Futurama Service and Futurama Batch. See Installation Futurama Server
for more information.
If a job consists of subjobs (see the paragraph 'Define Futurama Server jobs') the status of these subjobs can be viewed by pressing the '>'. Jobs that are started can be stopped by pressing the 'Stop' button. To delete jobs in this menu press the 'Delete' button'. Note that only the status of the job will be deleted. The job itself will remain. Stopped jobs can be restarted by pressing the "restart" button [from Futurama 2016_11]
It's possible to filter the list so only your own jobs are visible. By unchecking the checkbox "show only my own jobs", the jobs of other Vision users become visible. [From Futurama 2016_11]
By default only recent runs of individual jobs are shown, so when a job has been restarted multiple times, only the most recent run is shown. To show all executions of that particular job, you can uncheck the checkbox "show only recent jobs" [From Futurama 6.0+]
Should both the checkboxes be checked, then the user will be shown both the most recent execution for each job (regardless of creator). If the last execution is not a job started by the user, then the most recent execution of other users will be shown as well .
After execution a Futurama Server job a clickable link to the LogViewer is shown for each job. After clicking at this link the LogViewer will be opened and analyzing of the logfile is possible (from Futurama 2016_12).
Define Futurama Server jobs
As described previously Futurama Server jobs are tasks that define which export process has to be run and which parameters have to be used for this process. In this paragraph an example of a Futurama Server job is given, and the relevant parameters are explained.
Mentioned below an example of a Futurama Server job. The definition of this job is in an XML-file:
<!--?xml version="1.0" encoding="utf-8"?-->
<Job name="Testrun" xmlns="http://www.ActuIT.nl/FuturamaJob.xsd" version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Task name="Create Documents">
In the example mentioned above a number of parameters/settings are given. Below an explanation of each of these settings:
- with the attribute 'Name' the name of the Futurama Server job is defined. This name will be shown in the menu where all the jobs are listed;
- the element defines the job to be executed. Within each tasks can be defined. Each task is defined within a element. Within this element is defined which tasks has to be executed. Executing a job actually means the executing of the consecutive tasks. The element also has an attribute 'Name'. This is the name of the task within the job;
- the parameter NumberOfProcesses defines how many parallel processes are started to execute a task. Dependable on the number of processors available at the server where the job is executed the value of NumberOfProcesses can be chosen. If NumberOfProcesses>1 then Futurama Server will start more Futurama instances to execute the job. This implies that the job will be executed faster;
- the value of the parameter RepeatUntilFinished is relevant only when both NumberOfProcesses equals 1 and within a task subtasks are defined (see the paragraph 'Subtasks' for an explanation about defining subtasks). If in that situation RepeatUntilFinished is True, then automatically the next subtask is executed when the previous one is completed. This process ends at the moment of the stop condition (see the paragraph 'Status' for more information). If the value of RepeatUntilFinished is False only one subtask will be executed. In the situation that NumberOfProcesses is greater then 1, the value of RepeatUntilFinished will be ignored. After completing one subtask the next one will be executed until the moment of the stop condition.
Within a task the next settings have to be made:
- File: the name of the Futurama document with the definition of the actions that have to be made for the job to be executed. It is possible to either give the entire path to the Futurama document or only the name of the Futurama document. In that situation it is important to define in which directory this document is saved. This can be configured in the configuration file of Futurama Batch. In the Configuration-Mapping section of the futuramaSettings the rootpath property has to be used;
- ActionID: the ID of the Action within the Futurama document to be executed;
- OutputID: the OutputID is the ID of the XmlBuilder in the Futurama document where the status of a job is defined (see the paragraph 'Status' for more information);
- CheckID: the CheckID is the ID of the Futurama Object (i.e. the XMLBuilder or Action) that is used to do the iterations of the action that is executed. This is the object where the values RepeatData and RepeatTarget are used. For example when for a memberset a document has to be created, the value of the CheckID is the number of documents (i.e. the number of members for which a document is created) that has been created at any moment. This setting is optional. However, when it is not used, the progress of the server job won’t be shown in the Management Site;
- CheckInterval: the value of CheckInterval determines how many iterations (determined by the value of CheckID) will take place before the value of the status is adjusted. Suppose that the value of CheckInterval equals 10. In that situation the status will be adjusted every 10 iterations (determined by the value of CheckID). Note that the status is not explicitly adjusted when refreshing the website, either manually or automatically. Therefore if the website is refreshed before the number of iterations stated by CheckInterval have been performed, the value of status will remain the same.;
- Parameter: within the element 'Parameter' several TaskParameters can be defined. These TaskParameters can be used in the Futurama document with the defintions of the export process. The value of a TaskParameter can be read by using the Futurama formula Read.RequestParameter. In the example job mentioned above for example the TaskParameter 'createpdf' is defined. In the Futurama document the value of this parameter can be read. Then, for example, only when the value is 'True', for each member a PDF has to be created. These TaskParameters can be used during the development to first test the export process for a small group of members, before executing the entire export process. In the example a parameter BatchSize is used in order to restrict the export for the first 100 members.
As mentioned above in the defintion of a Futurama Server job the OutputID is important. This is the ID of the XmlBuilder in the Futurama document where the status of a job is defined. Using this XmlBuilder it is possible to display the actual status of a job in the Futurama Vision Management Site. In order to display this status properly the XmlBuilder must have the next content (i.e. elements in the XML):
- completed: 'completed' is the number of iterations (for example the number of documents created) for each (sub)task that is executed. The value of CheckID can be used to calculate this number. In the Futurama Vision Management Site the value of 'completed' will be used to give information about the progress of the export process;
- total: 'total' is the number of iterations (for example the number of documents to be created) that will we executed. If the job is divided into subtasks (see the paragraph 'SubTasks') 'total' displays the total iterations for each subtask. If the job doesn't have subtasks, 'total' displays the total number of iterations to be executed for the entire job;
- JobTotal: 'JobTotal' is only applicable when using subtasks. If no subtasks are used this parameter will be ignored. If subtasks are used, 'JobTotal' is the total number of iterations that will be executed for the entire job. This actually is the sum of 'total' for all the subtasks;
- LastJob: 'LastJob' is only applicable when using subtasks. 'LastJob' is a Boolean and has either value 'True' or 'False'. This parameter is the stop condition for the job to be executed. When 'LastJob' gets the value 'True' the subtasks that is executed at that moment will be the last subtask. This means that no new subtask will be executed when the current is completed. To determine when 'LastJob' must get the value 'True' define Futurama formulas to count the total number of iterations to be made, the total iterations already made and the number of iterations to be executed for each subtask. If the remaining number of iterations to be made is less the the number of iterations in one subtask, then 'LastJob' must get the value 'True'. In that situation after executing the subtask all the iterations are done.
The actual value of the status of a task can be seen any time by pressing the refresh button. By itself, the website will automatically refresh every 5 seconds. Refreshing means that Futurama Server does a request for the actual status of a job. A refresh will not cause an automatic adjustment of the value of the status itself. Only when during the time between two refreshes more iterations have taken place than CheckInterval, the status will show a new value. If less iterations than CheckInterval have taken place, the value of status will remain the same.
Important: the names of the elements within the XmlBuilder must be exactly the same as defined above. This is also case sensitive.
Within a job a task is defined. For example to create a number of documents in a filefolder. The task to create these documents will be divided into subtasks in the next two situations:
- the NumberOfProcesses>1. In that situation the execution of the task will be divided over different processors. Actually the total task will be divided into batches. Each batch will be assigned to a 'free' processor. After completing a batch, the processor will get the next batch to process as long as 'LastJob' gets the value 'True'. In the Futurama document has to be defined what the size of the batch is to be processed by each processor);
- the NumberOfProcesses=1 and RepeatUntilFinished=True. In that situation the processor will execute the batch size that is defined in the Futurama document until all the documents are created (the 'LastJob' gets value 'True' at that moment).
Above is defined in which situation for the export process subtasks are used. In order to know which subtask is executed (and to know for which members in the next subtask an export has to be made) the SubJobID is relevant:
Subtasks can be identified by the parameter SubJobID. The value of this parameter gives the index nummer of the subtask. So for the 5th subtask to be executed the SubJobID equals 5. This information can be used in the Futurama document with the defintion of the export process. The Futurama formula ReadRequestParameter can be used to read the value of the SubJobID. This information can be used to divide the whole member set in batches and define which batch is the next in the row to be processed.
Defining batch size subtask
Using subtasks it is important to determine the batch size for each subtask. Recommendable is to define this batch size in the job definition file (like the example that is given at this page). The value of the batch size can be read in the Futurama document by using the ReadRequestParameter formula. With the combination of the batch size and the SubJobID the set of members can be selected for which the export process in the next subtask has to be executed.
In this example a server job is created, which creates 10 XML files. Within this server job, only the OutputID is used. The CheckID is not used here.
Download the files used for Server job example1.
- Install version 17.12 of Futurama Server and Futurama Batch (see Installation Futurama Server).
- Extract the zip file and place the Xml file "Execute_Job1.xml" within the folder that is defined in the configuration file of the Management Site (see the paragraph "List jobs").
- For this example the directory "C:\FuturamaServer\Server jobs" is used. Create this directory and place the folder "Job 1" within this directory.
- Within the folder "Job 1", a Futurama application is available. Next to this, a folder "Output" is available. After the job is executed, the created XML files will be saved here.
- Open the file "Execute_Job1.xml". Note that the directory mentioned above is configured within this file.
- Within this file the Action that is executed and the OutputID are defined. Within this example, the CheckID isn't defined within the server job. Because only 10 files are created, the progress of the job isn't important.
- Execute this server job within the Futurama Management Site.
- When the Status is "Completed", the server job is finished. Note that the Progress is still "0 of 0 completed". This is because the CheckID is not defined, thus the server job doesn't know how many files will be created.
- Navigate to the directory "C:\FuturamaServer\Server jobs\Job 1\Output". Within this directory, 10 XML files are created.
In this example a server job is created, which creates 100 XML files. Both the OutputID and CheckID are used for this server job.
Download the files used for Server job example2.
- Install version 17.12 of Futurama Server and Futurama Batch (see Installation Futurama Server).
- Extract the zip file and place the Xml file "Execute_Job2.xml" within the folder that is defined within the configuration file of the Management Site (see the paragraph "List jobs").
- For this example the directory "C:\FuturamaServer\Server jobs" is used. Create this directory and place the folder "Job 2" within this directory.
- Within the folder "Job 2", a Futurama application is available. Next to this, a folder "Output" is available. After the job is executed, the created XML files will be saved here.
- Open the file "Execute_Job2.xml". Note that the directory mentioned above is configured within this file.
- Within this file the Action that is executed and the OutputID are defined. Within this example, the CheckID is also defined within the server job.
- Execute this server job within the Futurama Management Site.
- When the Status is "Completed", the server job is finished. Within the header 'Progress', the status "100 of 100 completed" is now visible. Within this example the CheckID is defined, so the server job knows the number of files that is created and the current number that is executed.
- Within the file "Execute_Job2.xml", the Action that is executed and the Action that is used for the CheckID are different. However, these parameters can also be linked to the same Action. When the ActionID is changed to value '3', the server job will still work. When executed, only the UserVariable "Total created" won't be set to 0 at the start of the job. Because the default value of this UserVariable is already 0, this step is not necessary.
- Navigate to the directory "C:\FuturamaServer\Server jobs\Job 1\Output". Within this directory, 100 XML files are created.
If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.