File Sending via HTTP(S)

While working on your Solution, you may need to send files from the FNZ Studio Platform to a target system via HTTPS. The file is locally present on the Platform server file system and the target system exposes a RESTful-like interface, capable of receiving a file passed in the request body. The target system endpoint can be called only by authenticated clients, and the supported authentication mechanism is client certificate (mutual SSL).

To do so, follow these steps:

1. Install the client certificate in the Keystore using this function:

   Copy

       String $alias := 'myClientCertAlias';
       String $keyfilepath := 'tmp/nameOfTheClientCertFile.pfx';
       String $password := 'pwdToExtractTheKetFromThePfxFile';
       AddPrivateKey($alias, $keyfilepath, $password)
   

   Remember the alias name specified above as it will be required to configure the SSL communication properly.

2. Edit the following configuration property for the Mutual Authentication feature (at System Configuration > Configuration Properties):

   Copy

   nm.security.ssl.serverAliasMappings=target.server.url:myClientCertAlias
   

3. Once the certificates are properly set up, use the code below to test the call to the endpoint:

   Copy

       // URL to be called
       String $url := 'https://target.server.url/context/document/upload?documentName=myTestContract.pdf&documentType=PDF&otherBusinessAtribute=1234';
       String $respFile := ABSOLUTEPATH(JOIN('work/tmp/restservice/', UID(),   '.json'));
       // path of the file to be sent
       String $pdfFile := ABSOLUTEPATH('myLocalDocs/myTestContract.pdf');
       Integer $timeoutInSeconds:= 60;
       Named Any $data := NewNamed(Any);
       Named String $headers := NewNamed(String);
       $headers['Content-Type'] := 'multipart/form-data';
       $headers['Accept']:= 'application/json';
       $data['PostRequestHeaders']:= $headers;
       HttpFileUpload $uploadFile:= new HttpFileUpload;
       $uploadFile.filePath:= $pdfFile;
       $data['uploadFile']:= $uploadFile;
       // the alias below might be explicitly set in the HTTPPOST call; if the hostname mapping config above is correct, setting this additional parameter might be skipped
       String $clientCertAlias:= 'myClientCertAlias';
       Local Integer $code := HTTPPOST($url, $data, $respFile, null, null, $timeoutInSeconds, null, null, null, null, $clientCertAlias);
       PRINTLN(JOIN('RespCode:', TOSTRING($code)));
       PRINTLN(READTEXTFILE($respFile));
   

   The code above sends the file via Multipart MIME upload. This approach works if the receiving endpoint supports Multipart MIME uploads, and it gets executed whenever an HttpFileUpload-typed element is set in the data payload of the HTTPPOST request:

   Copy

   
   
       HttpFileUpload $upload := new HttpFileUpload;
   
   
       $upload.contentType := 'application/json';
   
   
       $upload.filePath := ABSOLUTEPATH('myLocalDocs/myTestContract.pdf');
   
   
       Named Any $data := NewNamed(Any);
   
   
       $data.setElement('myJsonFile', $upload);
   
   
   

Note: More information about this approach can be found in the HTTP POST section of the Mutual Authentication documentation.

For an alternative way to execute the same operation, use the script below, where the data is sent in binary format as an octet stream: String $url := 'https://target.server.url/context/document/upload?documentName=myTestContract.pdf&documentType=PDF&otherBusinessAtribute=1234'; String $respFile := ABSOLUTEPATH(JOIN('work/tmp/restservice/', UID(), '.json')); // path of the file to be sent String $pdfFile := ABSOLUTEPATH('myLocalDocs/myTestContract.pdf'); Integer $timeoutInSeconds := 60; Named Any $data := NewNamed(Any); Named String $headers := NewNamed(String); $headers['Content-Type'] := 'application/octet-stream;charset=iso8859-1'; $headers['Accept'] := 'application/json'; $data['PostRequestHeaders'] := $headers; $data['PostBodyFile'] := $pdfFile; String $clientCertAlias := 'myClientCertAlias'; Local Integer $code := HTTPPOST($url, $data, $respFile, null, null, $timeoutInSeconds, null, null, null, null, null, $clientCertAlias); PRINTLN(JOIN('RespCode:', TOSTRING($code))); PRINTLN(READTEXTFILE($respFile));