8.13 wsCurl

Purpose

With wscurl(), you can transfer data from WS scripts to external URLs.

The wsCurl library is used with the load command to transfer data from a WS script to an external URL, such as Google Translate. This is particularly useful for foreign-language users who wish to input text in a non-Western language and then use a service such as Google Translate to change the text into English or some other language.

Desktop Implementations

To add the wsCurl functionality to an existing WS Desktop implementation, please do the following:

1. Obtain the wscurl.dll library from Synactive.
2. Place the wscurl.dll library in the following directory: C:\Program Files\SAP\FrontEnd\SAPgui.
3. Any scripts will be in the WS script folder. The default path is: C:\guixt.

Liquid UI Server Implementations

To add the wsCurl functionality to an existing Liquid UI Server implementation, please do the following:

1. Obtain the wscurl.dll library from Synactive.
2. Place the wscurl.dll library in the same directory as the sapproxy.exe file. This directory is usually found in the following location: C:\Program Files\Synactive Inc\GuiXTServer.
3. Any scripts will be in the WS script folder. The default path is: C:\guixt.

Offline Implementations

To add the wsCurl functionality to an existing Offline implementation, please do the following:

1. Obtain the wscurl.dll library from Synactive.
2. Place the wscurl.dll library in the Offline directory.
3. Any scripts will be in the Synscript folder.

Using wsCurl

The wsCurl feature is built using the Curl project. The syntax for this is as follows:

load('wscurl');
var ch = new wscurl(query_string);
ch->setopt(CURLOPT_HEADER, false);
var response = ch->exec()
ch->close();
ch = nil;

Please see the examples in Accessing Google Translate with wsCurl and Sending Webmail with wsCurl for examples on using wsCurl in WS scripts.

Examples

Sending Webmail with wsCurl

In the following example, we will demonstrate how to use the wsCurl functionality in WS to send Web mail.

1. Open the script file you will use to build the wsCurl function. You can create a new script file to call from the original script file if necessary.
2. Load the wsCurl files as shown in the following example:

   load('wscurl.dll');

3. Create a function. In our example, we will name the function 'translate'. All the code will be contained in this function. An example is shown below:

   function sendmail()
   { }

4. Set the applicable variables and identifiers as shown in the following list.

   Initialize the wscurl object

   var wsCurl = new Curl();

   Set Mailserver URL

   In this step, we will set the URL for the mail server. Note that in our example, we are using port 587 as opposed to the normal SMTP port 25. We are using 587 because we are using secure mail submission as defined in RFC4403. However, you should set your port to match the port on your mail server. The code is as follows:

   wsCurl.setopt(Curl.CURLOPT_URL, "smtp://smtp.gmail.com:587");

   Upgrade Connection to TLS

   In this step, we will upgrade the connection from plain text to Transport Layer Security (TLS). To do this, we will use the STARTTLS command.

   Note: We recommend using Curl.USESSL_ALL as shown below, not Curl.USESSL_TRY. This is because if the TLS upgrade fails, the transfer will proceed.

   wsCurl.setopt(Curl.CURLOPT_USE_SSL,Curl.USESSL_ALL);

   Disable Peer and Host Verification

   There may be times when your server does not have a valid certificate. IN these cases, you can disable part of the TLS protection by using the following code to set the CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST options to 0.

   wsCurl.setopt(Curl.CURLOPT_SSL_VERIFYPEER, 0);
   wsCurl.setopt(Curl.CURLOPT_SSL_VERIFYPEER,0);

   Note: We do not recommend disabling any part of your security, but having partial security is better than sending details in plain text. However, we recommend adding the issuer certificate (or the host certificate if the server certificate is self-signed), to the libcurl using the CURLOPT_CAINFO option.

   To add the certificate to libcurl, use the following code:

   wsCurl.setopt(Curl.CURLOPT_CAINFO,"/path/to/certificate.pem");

   Set Password and Username

   The most common reason to have transport security is to protect your users'login credentials from theft. Use the following code to set user names and passwords.

   wsCurl.setopt(CURLOPT_USERNAME,"user@example.com");
    wsCurl.setopt(CURLOPT_PASSWORD,"Password");

   Set Envelope Reverse Path

   Use the following code to set the envelope reverse path for the email. Please note that you must use brackets around the email address as shown in the example below. .

   var translateLangIdentifier = "&target=";

   Set

   Set the target language code itself. This will be a two-digit code and in our example, we will use English. A complete list of available language codes can be found in the Language Code Reference.

   var translateLang = "en";

   Build the URL

   The following code will create the complete URL that we will use to make the call for a translation request. This is demonstrated as follows:

   var completeURL = baseURL + textToConvert + sourceLangIdentifier + sourceLang + translateLangIdentifier + translateLang;

   Make a Translation Request

   Now that you have the complete URL, you can make a request for translation as shown in the below example:

   Note: This example is for requests that return a JSON object in a string.

   wsCurl.setopt(Curl.CURLOPT_URL,completeURL);

   Call the Execute function

   The final step in the process is to call the execute function. This will dispatch a response to your request. An example is shown below:

   Note: You can check the return value for errors with the error codes that are explained in the Error Codes section. A return value of 0 means the operation succeeded.

   var response = wsCurl.exec();

    Response

   In this example, the response will be in JSON, although you can set the response to be in HTML as well. A sample response based on the example iss shown below:

                     {
     "data": {
       "translations": [
         {
           "translatedText": "Bonjour tout le monde"
           }
         ]
       }
     }
                   

   Close wsCurl

   To close the HTTP connection for wsCurl, use the following code:

   wsCurl.close();

   Remove References

   Your last step will be to remove any references for the garbage collection as shown below:

   wsCurl=NULL;

5. Save your changes and call your new function from your script file.
6. The translated text should be returned to the calling function.

Language Identifiers

Available language identifiers for the wscurl command.

Available language identifiers for the wscurl command.

wsCurl.setopt(Curl.<CURL_OPTIONS>,parameter);

var response = wsCurl.exec();

println(wsCurl.error);

wsCurl.close();

wsCurl.slist_append("<recipient_email@company.com>");

wsCurl.slist_free_all();