Document Service - Function Reference

The functions within the Document Service plugin are distinct from the ACF language described in the ACF manual. They were developed prior to the ACF language and, as a result, these functions are called directly from FileMaker scripts. Utilizing the functions below does not require programming in ACF. However, ACF scripts can streamline certain aspects of your application's processes.

This section provides a comprehensive reference for functions available in the ACF_Plugin's Secure Document Service. These functions facilitate various aspects of working with the service, from authentication to document handling.

dsPD_Version

The dsPD_Version function retrieves version information about the installed ACF_Plugin. It offers multiple formats for version representation:

• Empty string or "short": Displays only the version number, e.g., 1.6.0.3 (current).
• "long": Presents the version information as "ACF_Plugin v 1.6.0.3".
• "platform": Indicates the platform (Mac OSX or Windows).
• "autoupdate": Provides an autoupdate version number (e.g., 01060003).

Prototype

dsPD_Version( { versionFormat } )

Parameters:

Return value:

The plugin version format string.

dsPD_Auth

The dsPD_Auth function serves a dual purpose: it registers authentication parameters for subsequent calls and verifies the authentication settings by attempting to log in to the SOAP service. While the parameters "user," "password," and "URL" are mandatory, the "key" parameter has a special role.

Upon successful authentication, the parameters are stored in the plugin for use in other functions.

Prototype

dsPD_Auth( user ; password ; key ; URL )

Parameters:

Return Value:

Lines of text:

1. Status: OK or ERROR.
2. Message.

dsPD_AuthBase64Encrypted

The dsPD_AuthBase64Encrypted function performs the same authentication tasks as dsPD_Auth, but instead of using credentials and URL, it utilizes an encrypted parameter block and an encryption key. The key can be a random string of characters typically hardcoded in the target application. For details on constructing this parameter block, refer to the examples in the "Introduction to the Document Service."

Prototype

dsPD_AuthBase64Encrypted( base64 {; key } )

Parameters:

Return Value:

Lines of text:

1. Status: OK or ERROR.
2. Message.

dsPD_GetDocument

The dsPD_GetDocument function retrieves a document from the document service. It requires specifying the FileName (the name of the file to retrieve) and the RemotePath (the relative remote path for the document). You can also provide a LocalPath (a path pointing to the directory where you want to store the retrieved document) and optionally, a LocalName if you wish to use a different name locally.

If you've supplied an encryption key either in the Auto parameter block or with the dsPD_SetDocumentEncryptionKey function, the plugin will use that key for decryption if the stored document is encrypted (ends with .encrypted). Note that you should not include the .encrypted suffix in the FileName.

Prototype

dsPD_GetDocument( FileName ; RemotePath {; LocalPath ; LocalName } )

Parameters:

Return Value:

Lines of text:

1. Status: OK or ERROR.
2. Message (On OK, the message contains lines of path info for the stored document).

dsPD_SaveDocument

The dsPD_SaveDocument function saves a local document on the server. If the document encryption key is applied, it encrypts the document before saving it on the server; otherwise, it saves the document unencrypted.

Prototype

dsPD_SaveDocument( LocalPathName ; RemotePath { ; UpdateNew ; RemoteName } )

Parameters:

Return Value:

Lines of text:

1. Status: OK or ERROR.
2. Message (On OK, the message contains lines of path info for the stored document).

dsPD_EncryptParBlock2Base64

The dsPD_EncryptParBlock2Base64 function is used to create an encrypted parameter block. It encrypts the supplied text and encodes it in BASE64. The result includes start and end signature tags that are removed during decryption. An optional description text can also be added to the top of the block.

Prototype

dsPD_EncryptParBlock2Base64( ParBlockText ; key { ; Description } )

Parameters:

Return Value:

The encrypted parameter block text.

dsPD_DecryptBase64_2ParBlock

Prototype

dsPD_DecryptBase64_2ParBlock( base64 ; key )

Retrieve the source text from the encrypted parameter block.

Parameters:

Return Value:

The decrypted parameter block text or an error message.

dsPD_SetDocumentEncryptionKey

The dsPD_SetDocumentEncryptionKey function enables the document encryption feature. The Key parameter specifies whether the key is a text string or a 64-character hex string. Use "STD" for any password string or "HEX" if it's a 64-character HEX key. The default is "STD." If the document service is authenticated using the dsPD_AuthBase64Encrypted method, with a encrypted parameter block containing a document-key, the document encryption is automatically activated, so any call to dsPD_SetDocumentEncryptionKey superfluous.

Prototype

dsPD_SetDocumentEncryptionKey( Key { ; Options } )

Parameters:

Return Value:

OK or an ERROR message.

PHP-Compatible Encryption/Decryption

Sometimes, you may need to encrypt data in FileMaker and send the encrypted object to a PHP service for decryption. Why would you do this when HTTPS already encrypts requests? Here's the answer: By encapsulating the parameters within an encrypted block and decrypting it in the web service, you can ensure that only authorized users with the encryption key can access your service.

The function provided below creates two PHP functions that you can include in your PHP web service. This allows you to encrypt the parameters for your service before calling it from FileMaker and then decrypt the block in your PHP source code. You can also encrypt the response so that your FileMaker application can decrypt the result.

By implementing this approach, your web service becomes secure and immune to tampering, enhancing overall data security.

This was developed as an answer for the difficulty one has to use encryption in FileMaker using inherent or other plugin calls, that was difficult to decrypt in PHP just because the way the encryption works in those other methods.

The methods above, dsPD_EncryptParBlock2Base64, and dsPD_DecryptBase64_2ParBlock are used on the FileMaker side to encrypt and decrypt text. It is called a parameter-block, but can of course be any text. The ecrypted BASE64 text is wrapped in a Start tag and a End-tag to make sure we have a complete encrypted object.

dsPD_GetPHPSampleEncryptDecryptCode

This function generates support code for PHP implementations to decrypt information encrypted using this plugin. It also offers a HEX mode to create a 64-character HEX encryption key from a supplied password-type key.

Example:

<?php

/*
From Filemaker: These two plugin calls will generate the code below: 

dsPD_GetPHPSampleEncryptDecryptCode( "ollalala"; "ENCRYPT" ) & 
dsPD_GetPHPSampleEncryptDecryptCode( "ollalala"; "DECRYPT" )


Result text ( PHP ):
*/

// PHP Function to encrypt
function encrypt_AES_CBC ($plaintext) {
    $method = "aes-256-cbc";
    $key = "35F7639454610A1F9B560F44C98A3211218333A4846560FE0655DC42855F96AD";
    $bkey = hex2bin($key);
    $iv = hex2bin(md5(microtime().rand()));
    $data = openssl_encrypt($plaintext, $method, $bkey, OPENSSL_RAW_DATA, $iv);
    return base64_encode($iv.$data);
}
// PHP Function to decrypt
function decrypt_AES_CBC ($encryptedText) {
    $method = "aes-256-cbc";
    $key = "35F7639454610A1F9B560F44C98A3211218333A4846560FE0655DC42855F96AD";
    $bkey = hex2bin($key);
    $decoded = base64_decode($encryptedText);
    $iv = substr($decoded, 0, 16);
    $data = substr($decoded, 16);
    return openssl_decrypt( $data, $method, $bkey, OPENSSL_RAW_DATA, $iv );
}

?>

Prototype

dsPD_GetPHPSampleEncryptDecryptCode( textkey {; ENCRYPT/DECRYPT/HEX } )

Parameters:

Return Value:

The product text of the function.

dsPD_SHA512_digestHex

Generate a SHA512 digest from the supplied parameter.

Prototype

dsPD_SHA512_digestHex( SourceString )

Parameters:

Return Value:

The SHA512 message digest as a hex value.

Utility Functions for Portal Sorting

Sorting portal rows in FileMaker can be quite challenging, often requiring complex solutions. Some approaches involve multi-tab layouts with separate portals sorted in various orders. The two functions presented below offer a more streamlined solution by utilizing a calculated field within the relevant table. This calculation leverages these functions to create a hexadecimal representation of the sorting field, which can be set using global variables.

Here's how it works: A case statement selects the sorting field as an input parameter for these functions. Depending on the chosen field for sorting, the calculation generates a hexadecimal representation of that field. For reverse sorting (descending order), we employ the dsPD_Text2HexInv function, which produces a reverse hexadecimal representation. Sorting based on this representation achieves a descending sort order.

Example:

# Calculatin in the new sorting field named Sorting
Let [
v = case ($$SortCol = 1; [OrderLines]ProductNo; 
          $$SortCol = 2;  [OrderLines]Number;
          $$SortCol = 3;  [OrderLines]Price;
          [OrderLines]ProductNo)
];
if ($$Dir = "ASC"; dsPD_Text2Hex(v); dsPD_Text2HexInv(v) );

The calculation described above produces a HEX string representing the ProductNo, Number, or Price columns, with the default being the Product Number. Sorting the portal based on this field allows you to sort by any of the selected columns. By incorporating buttons in the column headers, you can dynamically set the appropriate global variables $$SortCol and $$Dir to their intended values and then refresh the portal. This flexibility enables the same portal to be used for sorting in various orders, enhancing the user experience.

dsPD_Text2Hex

A utility function used for column sorting in portals. It converts the value to a hexadecimal string for sorting purposes. This function allows sorting a portal on any column by choosing the field to work on. For descending sort, use the corresponding function.

Prototype

dsPD_Text2Hex( SourceString )

Parameters:

Return Value:

The HEX representation of the SourceString.

dsPD_Text2HexInv

A utility function used for column sorting in portals. It converts the value to an inverse hexadecimal string for sorting purposes in descending mode. This complements the previous function for ascending sort.

Prototype

dsPD_Text2HexInv( SourceString )

Parameters:

Return Value:

The inverse HEX representation of the SourceString.