EFT Web Service

(Available in EFT Enterprise) The Web Service allows administrators to initiate EFT workflow from an external application such as an enterprise scheduler. The WebService interface follows the model of ASP.NET Web services, providing a page for the services definition document (WSDL) and an HTML form that can be used to test available service methods.

The procedures below provide instructions to:

Enable the Web Service in EFT

Use the attached scripts to test the Web Service

Use the Invoke Web Service Action

  • Access to Web Service requires authentication with a COM-enabled Server administrator account; without proper authentication and COM privileges, EFT returns a 401 Unauthorized HTTP error to the requestor.

  • An SSL certificate is required to use Web Service, because EFT sends the HTTP Web Services requests via HTTPS. (Specify SSL versions and ciphers before enabling SSL connections. SSL must first be enabled on EFT and the Site.)

  • The Web Service is enabled in the Site's Listener Settings area. EFT allows you to turn on Web Service without selecting the HTTPS check box, but it checks for an SSL certificate, because it will automatically redirect HTTP to HTTPS. Even when the HTTPS check box is not selected, Web Service requests are handled by the HTTPS engine (port 443 listener, by default), but other HTTPS requests will still get the 503 Service unavailable response.

  • EFT uses a template for the WSDL to construct the final WSDL. External tools can use the WSDL by pointing to the URL that deploys the WSDL file at

  • http://localhost/WebService/InvokeEventRule?wsdl, where "localhost" is the IP address, computer name, or DNS name that points to the EFT service that is hosting the web service.

  • Requests to any /WebService URL is logged to the text log and ARM system just as any other HTTP request.

  • The Web Service timeout is set to 60 seconds. You can change the timeout value with the advanced property described in https://kb.globalscape.com/KnowledgebaseArticle10553.aspx.

Requests to any /WebService URL are logged to the text log and ARM database just as any other HTTP request. A request that does not match the /WebService/InvokeEventRule URL or that does not include the required parameters, results in a 400 Bad Request HTTP error.

The /WebService page displays a list of Web services available with EFT. This page is generated from an HTML page in EFT installation folder, in a subfolder called WebService.

By default, the following files are installed in:

v8.0.4 and earlier: C:\Program Files\Globalscape\EFT\web\public\EFTClient\WebService

v8.0.5 and later: C:\Program Files (x86)\Globalscape\EFT Server Enterprise\Web\WebServices

  • \EFTWebServices_MAIN.html - Used to define the Web Services landing page; provides a link to InvokeEventRule.html.

  • \InvokeEventRule\EFTWebServices_InvokeEventRule.html - Used to define the Web interface from which you can remotely invoke Event Rules on EFT.

  • \InvokeEventRule\EFTWebServices.wsdl - Web Services Description Language (WSDL) configuration file. (For details of how WSDL files are used, refer to the World Wide Web Consortium documentation at http://www.w3.org/TR/wsdl.)

How EFT Supports the Web Service

EFT supports both POST and GET HTTP requests to "/WebService/InvokeEventRule" with two parameters "EventRuleName" and "EventParams" and triggers an Event Rule that is specified in the "EventName." The Web Service supports the REST invocation model, supporting both POST and GET methods for invocation.

  1. If an input is missing any of "EventRuleName" or "EventParams" it returns an HTTP 400 error.

  2. If both "EventRuleName" and "EventParams" are presented but:

    1. "EventRuleName" is wrong (no Event Rule exists with such name), it returns .xml with result code of -1.

    2. "EventParams" are incorrect (wrong variable names, too many, too few), EFT looks for Rule variables in the input and replaces those values with found ones. All additional variables are ignored. If a Rule variable is not found in URL then it will be set to "N/A." The result code in .xml will be the Event execution result code.

HTTP GET

The following is a sample HTTP GET request and response. Replace the placeholders with actual values.

GET /WebService/InvokeEventRule?EventRuleName=string&EventParams=string HTTP/1.1 Host: localhost

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <int xmlns="http://mydomain/ ">int</int>

HTTP POST

The following is a sample HTTP POST request and response. Replace the placeholders with actual values.

POST /WebService/InvokeEventRule HTTP/1.1 Host: localhost Content-Type: application/x-www-form-urlencoded Content-Length: length EventRuleName=string&EventParams=string

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <int xmlns="http://mudomain/ ">int</int>

 

To enable the Web service in EFT

  1. In the administration interface, connect to EFT and click the Server tab.

  2. On the Server tab, click the Site that you want to configure.

  3. In the right pane, click the Connections tab.

  4. Select the Event Rule invoke over WS/SOAP (uses HTTPS port) check box. (If this is not enabled, you will not be able to log in to the Web Service.)

  5. Click Apply to save the changes on EFT.

To use the scripts for testing Web Service

Use one of the attached scripts to test Web Service (copy into PowerShell).

  • EFT.InvokeEventRule.ps1 uses regular output -1, 0  or 1 (classic SOAP)

    • Change the various strings at the top for host, administrator username, password, and event rule name.

  • InvokeEventRule.ps1 returns all context variables from the rule (behaves a bit more REST like, even though the response is XML, not json).

    • Add the advanced property "EventWebServiceResponseAddContextVariables" to the AdvancedProperties.JSON file. You must set this property to get the payload from EFT in response showing the context variables.

    • Change the administrator username and password various strings at the top of the script.

    • Modify the Invoke-WebRequest method, including the host, event rule name, and optional parameters.

To execute an Event Rule using Web Service

  1. Open a browser and navigate to EFT URL appended with /WebService. The WebService page appears.
    (You must change the URL of the Site and the port number if you are not using "localhost" and port 443, as shown below!)

  2. A login prompt appears. Provide a COM-enabled Server administrator account login credentials. If the Event Rule invoke over WS/SOAP (uses HTTPS port) check box is not enabled on the Connections tab of the Site, you will not be able to log in to the Web Service.

    3. EFT leverages the USER https port (443 by default); however,

     WebService uses the Server administrator account login credentials,

    not USER credentials!

     

  3. The EFTWebService interface appears.

  4. Click InvokeEventRule. Another Web page, /WebService/InvokeEventRule, displays a form for invoking an Event Rule.

  5. In the EventRuleName box, type the name of the Event Rule.

  6. In the EventParams box, type one or more variables, separated by semicolons.

  7. Click Invoke. The Event Rule is executed.

    All WebService responses use the Site's domain name as the namespace for the WebService.

    For example, in the EventRuleNameValue box, type Backup and Cleanup. Leave EventParams blank, and then click Invoke. ("Backup and Cleanup" is a default Event Rule available in EFT Enterprise.) The browser returns the following string:

    <int xmlns="HTTPS://localhost:443/">1</int>

      • 0 indicates failure

      • 1 indicates success

      • -1 indicates EFT could not find the Event Rule (for example, the requested EventName does not exist or was not typed correctly.)

    For this example, you can open the /Backup/ folder and see that a backup file was created (for example, C:\ProgramData\Globalscape\EFT Enterprise\Backup).

Using Web Service Examples

Folder Monitor

EventParams=FS.PATH=C:\test\inbound\test.txt;FS.MONITOR_OPERATION=added

As you can see, the FS.MONITOR_OPERATION is part of the Condition and must be passed along with the variable of choice; in this case it is FS.PATH or any other variable that is created.

EventParams=FS.PATH=C:\test\inbound\test.txt;FS.MONITOR_OPERATION=added;FILEBOB=test.filebob.txt

As you can see above, the variable is a custom variable applied to this event rule, outside of the EFT variables.

Timer Event

EventParams=FILEBOB=test.filebob.txt

The Timer Event is the least used Event Rule in EFT to download files, move them, or to automate an AWE Script/custom command. Using the Web Services allows you to manipulate custom variables for the specific environment or file that needs to be processed. In the case above, the Timer event is being used as a transmission only, triggered by a remote process using “wget”.

Passing the URL to WebServices

As the HTTP GET states:

GET /WebService/InvokeEventRule?EventRuleName=string&EventParams=string HTTP/1.1

Based on this information, the URL should contain the following:

  • EventRuleName=ProcessTestFileName

  • EventParams=FS.PATH=C:\test\inbound\test.txt;

  • FS.MONITOR_OPERATION=added

Combine the parameters:

http://localhost/WebService/InvokeEventRule?EventRuleName=ProcessTestFileName&EventParams=FS.PATH=C:\test\inbound\test.txt;FS.MONITOR_OPERATION=added

**Note: the ampersand “&” is used to separate the EventRuleName and EventParams, but you will use the semi-colon (;) to separate more than 1 EventParams that is required to make the Event Rule work correctly.