Search

 

Edition: Futurama Export

Module: Futurama Server

User: User Management Site, Developer

Prerequisites

- not applicable

Introduction

Overview of the Futurama Server module.

 

Description

Futurama Server is the Futurama component that is responsible for running batch jobs. Futurama Server provides a way to run tasks that take a long time in a way that allows monitoring the progress and allows the user to stop the tasks.

Futurama Server consists of the following parts:

Futurama Service

Futurama Service is a Windows Service. When the service is started (on computer startup) the service starts listening for commands on a HTTP address. This address is self-hosted without IIS. The default address the service listens on is http://localhost:8080/FuturamaService/. The WSDL for the service is available on http://localhost:8080/?singleWSDL

Futurama Service is responsible for

  • starting tasks
  • keeping track of the running tasks and their status
  • stopping tasks
  • reporting the status of the tasks to the Management site

Futurama Batch

Futurama Batch is a console application that is used to run batch jobs. It is started by the Futurama Service. As soon as a job is finished, the Futurama Batch application closes itself.

Futurama Batch runs in the same identity as the identity of Futurama Service.

The communication between Futurama Service and Futurama Batch is via a WCF connection with a WSDualHttpBinding binding. Futurama Service calls Futurama Batch to send commands. And Futurama Batch calls Futurama Service to report the status of the running job.

Futurama Batch listens for communication on port http://localhost:port/FuturamaBatch. The port number that is used is default 8081, and can be changed in the config files. If you have multiple processes running, each process uses a subsequent port number.

Futurama Vision Management site

The Management Site for Futurama. See Futurama Server Management Site for more information. This site contains pages to monitor, start and stop the running tasks. The communication from Futurama Vision Management Site to Futurama Service is via WCF with a basicHttpBinding.

The endpoint is defined in the default config as follows:

<endpoint address="http://localhost:8080/FuturamaService" binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_FuturamaService" contract="FuturamaServerReference.Service" name="BasicHttpBinding_Service"/>

Workflow

The process of running a task consists of the following actions:

  • The user clicks on the start button of a job definition in the screen in the Vision Management site.
  • The Vision Management site tells Futurama Service to start a job.
  • Futurama Service start an instance of Futurama Batch and passes the port that it will use for communication as a parameter
  • Futurama Batch starts to listen to commands on that port
  • Futurama Service sends the command to start a job to Futurama Batch. 
  • Futurama batch starts a different thread to run the job.
  • If defined in the job definition, Futurama batch reports the status of the job, to Futurama Service by calling the WCF Service.
  • When the job is finished, Futurama Batch reports the final status to Futurama Service and exits.

Steps to use Futurama Server

To use Futurama Server follow the next steps:

  1. Installation of Futurama Server
  2. Configuration Futurama Server
  3. Definition Futurama Server jobs
  4. Start Futurama Server job
  5. Monitor Futurama Server job
  6. Stop Futurama Server job
  7. Delete Futurama Server job
  8. Error handling
  9. Scheduling

Installation Futurama Server

See the support page Installation Futurama Server how to install Futurama Server. To install Futurama Server both the Futurama Service code and the Futurama Batch code has to be downloaded and installed.

Configuration Futurama Server

After the installation of both Futurama Service and Futurama Batch the configuration can be done. See the configuration paragraphs at the the support page Installation Futurama Server how to do the configuration of Futurama Service and Futurama Batch. In the release of these components default configuration files are available to be used to do the configuration.

Definition Futurama Server jobs

After the installation and configuration of Futurama Server jobs can be defined with the definition of the export process to be performed with Futurama Server. See the chapter 'Define Futurama Server jobs' how to define a Futurama Server job.

Start Futurama Server job

Futurama Server jobs can be started by using the Futurama Management Site, by a POST HTTP request to Futurama Service, or by using a Futurama Document where a Futurama Server job can be started by using an WebReference. The start of a Futurama Server jon can be scheduled. See the paragraph 'Scheduling Futurama Server job' for more information.

Futurama Management Site

After the definition of a Futurama Server job, you have to choose a file location where the XML-files with the job definition will be saved. After saving the definition of the Futurama job at this location it is possible to select this job in the Management Site and start the job. See the paragraph 'Management Site' for more information.

Futurama Service request

It is also possible to start a Futurama Server job by doing a POST HTTP request to Futurama Service. This can be used in the situation that it is preferred to start export processes automatically instead of manually within the Management Site. To start the Futurama Server job with the POST HTTP request the next parameters are important:

Definition in Futurama document

A Futurama Server job can be started using a Futurama document. Create this document in the Futurama Editor using the object WebReference. In the Properties Window of this WebReference an URL and Input (the request) has to be defined. Enter the URL of Futurama Service. The request can either be build in the Futurama Editor by using XmlBuilders (see example in the paragraph 'Example request' for the structure of the request to be build in the Futurama Editor) or by reading a file with the job definition. See the chapter 'Scheduling Futurama Server job' for a download example of a Futurama Document where the job defintion is read from a file. With this download it is also possible to schedule your Futurama Server job. 

Monitor Futurama Server job

After a Futurama Server job is started the status of this job can be viewed using the Futurama Management Site. See the paragraph Management Site for more information how to monitor the status. It is also possible to do POST HTTP request to Futurama Service to obtain the status of a Futurama Server job. To get the status of the Futurama Server job the next parameters are important:

The request of the POST HTTP request to obtain the status of the job is:

<GetJobs xmlns="http://www.ActuIT.nl/Futurama/Server"></GetJobs>

Stop Futurama Server job

After a Futurama Server job is started the job can be stopped using the Futurama Management Site. See the paragraph Management Site for more information how to stop a Futurama Server job. It is also possible to do POST HTTP request to Futurama Service to stop a Futurama Server job. To stop a Futurama Server job the next parameters are important:

The request of the POST HTTP request to stop a job is:

<StopJob xmlns="http://www.ActuIT.nl/Futurama/Server">
    <args>1</args>
</StopJob>

The value of is the ID of the job to be stopped. This ID is part of the response of the POST HTTP request to obtain the status of the job (see described above).

Delete Futurama Server job

After a Futurama Server job is stopped or completed this job can be deleted using the Futurama Management Site. See the paragraph Management Site for more information how to delete a job. It is also possible to do POST HTTP request to Futurama Service to delete a Futurama Server job. To delete a Futurama Server job the next parameters are important:

The request of the POST HTTP request to delete a job is:

<DeleteJob xmlns="http://www.ActuIT.nl/Futurama/Server">
    <args>1</args>
</DeleteJob>

The value of is the ID of the job to be deleted. This ID is part of the response of the POST HTTP request to obtain the status of the job (see described above).

Error handling

During the Futurama Server process it is possible that errors occur. See the paragraph 'Monitor Futurama Server job' how to monitor the status of a Futurama Server job. For each job executed in the Futurama Vision Management Site the number of errors are given. In the situation of a POST HTTP request to Futurama Service to obtain the status of a specified job, the number of errors is given in the response of the request.

In the configuration files of Futurama Service and Futurama Batch logging can be enabled. In these files also the logging location can be defined. See Configuration - Log how to configurate logging. When errors occur check the logging information.

Scheduling

It is possible to schedule a Futurama Server job, for instance with Windows Power Shell. Below an example of powershell script that can be used to start a Futurama Server job. After defining this powershell file, this can be scheduled.

$proxy = New-WebServiceProxy -Uri  http://localhost:8080/?WSDL
$content=Get-Content C:\FuturamaServer\Jobs\InitializeAccounts.xml
$response = $proxy.StartJob("$content")  (until Futurama 2016.11 )
$response = $proxy.StartJob2("$content","username")  (from Futurama 2016.11, username is the name of the user that runs the job)
$response.StartJobResult

First define the address of Futurama Service. Second, define a parameter in order to read the XML to be used when starting the Futurama Server job. After that the parameter can be used to start the job. Below an example of a powershell script to delete a Futurama Server job.

$proxy = New-WebServiceProxy -Uri  http://localhost:8080/?WSDL
$response = $proxy.DeleteJob("1")
$response.DeleteJobResult

With this script the job with ID=1 in the status overview list will be deleted.

Example request

To do a POST HTTP request to Futurama Service it is recommendable to first define a Futurama Server job and test whether this job can be executed correctly by starting this job from the Futurama Management Site. After this the defined job can be used to compose the HTTP request. The general structure of the request is (general structure from Futurama 16.11, until this version the username parameter is not used, and the name is StartJob instead of StartJob2):

<StartJob2 xmlns="http://www.ActuIT.nl/Futurama/Server">
    <args>Escaped job XML</args>
    <userName></userName>
</StartJob2>

The value of args is the escaped XML job definition. The username is relevant in the situation the Futurama Server job is started from the Management Site. In that situation it is possible to select only your own jobs. The username element must be used, but can be empty as mentioned in the example above. If for example the job definition is:

<Job xmlns="http://www.ActuIT.nl/FuturamaJob.xsd" name="your export process" version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <NumberOfProcesses>1</NumberOfProcesses>
    <RepeatUntilFinished>false</RepeatUntilFinished>
    <Task name="Export">
        <File>\\servername\application\export.xml</File>
       <ActionID>
            <string>285</string>
       </ActionID>
        <OutputID>612</OutputID>
        <CheckID>149</CheckID>
        <CheckInterval>10</CheckInterval>
        <Parameter>
           <TaskParameter>
                <Name>Parameter_1</Name>
                <Value>TRUE</Value>
            </TaskParameter>
        </Parameter>
    </Task>
</Job>

then this XML can be escaped. Use CDATA to escape the XML in the request:

<StartJob2 xmlns="http://www.ActuIT.nl/Futurama/Server">
    <args>
        <![CDATA[<Job xmlns="http://www.ActuIT.nl/FuturamaJob.xsd" name="your export process" version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <NumberOfProcesses>1</NumberOfProcesses>
    <RepeatUntilFinished>false</RepeatUntilFinished>
    <Task name="Export">
        <File>\\servername\application\export.xml</File>
       <ActionID>
            <string>285</string>
       </ActionID>
        <OutputID>612</OutputID>
        <CheckID>149</CheckID>
        <CheckInterval>10</CheckInterval>
        <Parameter>
           <TaskParameter>
                <Name>Parameter_1</Name>
                <Value>TRUE</Value>
            </TaskParameter>
        </Parameter>
    </Task>
</Job>]]>
    </args>
    <userName></userName>
</StartJob2>

It is also possible escaping XML without using CDATA. In that situation, first escape the XML, and use the escaped XML within the args element:

Scheduling Futurama Server job

It is possible to schedule the start of a Futurama Server job. Download the sample in order to schedule your Futurama Server job. Download files

Configuration

The sample contains two files: the Futurama Document startjob.xml and the file 'execute startjob.txt'. This last file contains the commandline parameters how to start your Futurama Server job. These command line parameters can be scheduled in order to start a Futurama Server job automatically at predefined times. The file contains the next information:

  • "\\Path to Futurama Editor\ActuIT.Futurama.Editor.exe": define the path to the location of the Futurama Editor;
  • "\\Path to Futurama Document\StartJob.xml": this is the path to the location where tje Futurama Document startjob.xml is saved;
  • Mandatory parameter JobLocation. Value: "\\Path to job definition\JobDefinition.xml": this is the path to the definition of the Futurama Server job (see also the paragraph 'Definition Futurama Server jobs' in the chapter 'Steps to use Futurama Server' how to define a Futurama Server job
  • Optional parameter JobName. Value: Name of the job. In the logging of the Futurama Editor an info message will be given with the name of the job that has started. When the job had ended also an info message will appear in the log. When this parameter is not used these messages will not be given in the log.  

Next to the configuration above additional configuration has to be done in order to define the communication between Futurama Editor and Futurama Service. First within the appSettings part of the configuration file of Futurama Editor the appSetting URL_FuturamaService has to be defined. See below for an example:


	

Here the URL of Futurama Service has to be defined. Next to this setting the binding configuration between Futurama Editor and Futurama Service has to be defined. Define this binding using the EndPointName 'FuturamaService'. See below for an example using basic Http binding:


	
		
	
	
		
			
				
			
		
	

See also the page 'Installation Futurama Vision Management Site', chapter 'Configuration' , paragraph 'FuturamaServer' for an example of an endpoint address and binding. At this page the communication between Futurama Vision Management Site and Futurama Service is described. The same is applicable to the communication beteween Futurama Editor and Futurama Service. In this example basic Http binding is used. It is possible to use different kinds of WCF-configuration (see this page for more information).

Related Topics

- Installation Futurama Server: Description how to install and configure Futurama Server

- Futurama Server - Management Site: Description how to start and monitor Futurama Server jobs

- Definition Futurama Server jobs: Description of the structure and content of Futurama Server jobs

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.

Updated: 2014-06-27