Automating complex processes: Working with macros

eSignatureOffice offers the possibility to define macro actions. By using such macro actions, you can automate certain steps of your working procedures and then you can either combine them with signature-sets to trigger them automatically, if you want to, or you can trigger them manually by clicking on a button.

Some examples of actions, which you can combine into a macro:

• Printing
• Notifications
• Saving documents
• Sending documents per email
• Importing and exporting data from and to external applications
• Starting external applications, including the transfer of parameters to those applications
  

This chapter will show you the utilization of this feature in eSignatureOffice, while you can find a detailled step-by-step guide to a simple example macro here in the beginner's guide.

Configuring macro buttons

Open the macro button configuration dialog by clicking "Tools | Configure macro buttons" and you will see the following menu:

First of all, to configure a macro button, choose the tab of the button, you want to use or select a new tab to create a new macro. Now, you can add a caption to this button ("Text on button"). This caption is only needed, when you want to want to make this button visible to the user. Each caption is only saved for the language, which is currently chosen on the lower right side. This way, you have the possibility to create buttons with separately translated names for all usable languages in eSignatureOffice. Furthermore, it's recommended to name the macro distinctively, for example matching the corresponding document or action, which it is used for.

Triggering macro actions

Generally, macro actions can be triggered either manually or automatically. You should decide on the triggering mechanism of your macro right at the beginning of its creation, because this decision will influence certain subsequent steps.

If a macro is supposed to be triggered automatically, you have to define this in a signature-set. For this, the button does neither have to be visible not does it need a special name.

If the user is supposed to decide himself, when or if he wants to trigger the action, you have to make this button visible to him (the first checkbox in the upper left). In order to achieve useful results and to help reducing possible mistakes when using the button, you should set up limiting conditions with the drop down menus "Start:" and "End:", under which the button is either active or not.

You can use the following options as limiting conditions for the active usability of your macro button:

You can decide, if macro actions should be allowed to be triggered manually while a signature-set is processed. Go to eSignatureOffice's administration menu and in the "General" tab switch the option "Disable macro buttons while signing" on or off.

To make such manual triggering possible, the corresponding macro has to be configured to be active "On start up". Please be aware, that clicking this button will then stop your signature-set during its processing, even if there are still unsigned mandatory signing fields to complete! Then the macro action is executed, but before this happens, you will be notified of this situation with the following dialog:

Confirmation (1)

You can show the user a notification message, which he has to confirm in order to go on with the signing procedure. This can be used with manual macro triggering as well as with automatic triggering and is an elegant way to announce the action to the user or to allow him to accept or deny the macro action. You can customize the text to be shown and eSignatureOffice also offers three different kinds of confirmation button configurations (pure confirmation with only the "OK" option, or a dialog with either "OK/Cancel" or "Yes/No" to choose from). Additionally, you can also read the text from the document itself by using the dynamic processing of document content and so show always an individualized dialog, depending on the document text. 

The question mark button to the right of the drop down menu will show you a preview of the future dialog with all its current settings.

Actions (2)

Printing the document

If you activate the option "Print the document" and the macro is triggered, eSignatureOffice will print the document. Besides directly defining which printer to use, you can also activate an option to allow the user to always select the printer himself or alternatively to always use the Windows default printer. 

Save file (3)

eSignatureOffice offers varous ways to save your signed document.

For example, you can choose to not save the file via macro at all, or you can save the file to the original location, which will simply overwrite the original document with your changed version. However, you can also save the file to another saving path, with another name or even upload it directly to a FTP server.

• In case you're using a XML file and you also want to keep it as XML upon saving, please activate the option "Save and upload XML if XML was opened". If this option is not activated, the document will be saved as PDF file. You can find more information about using the XML file format in eSignatureOffice here: Input-XML.
• The second option "Show replace window" refers to the possibility to dynamically use the document's content, which will be relevant in the next paragraph "Save file as..."
  So, while this checkbox is activated and your document is scanned for your search strings, the "replace window" will show up and list all your search strings as well as their corresponding results.
•  The third option will do as it says: It will show a status window during the saving process.
  
  
  

Upon choosing any of the options "Save file as..." or "Upload file..." a new dialog will open, in which you can make further settings.

Save file as

Dynamically renaming a file when saving it

Instead of providing a static file name, you can also use the document's content to save the file with a variable file name, which might change depending on what information from the document you are using. So, for example, you can use the date, the customer's name or his unique ID or something like that. Learn more about this topic here: Dynamic processing of document content

Upload file

You can upload files either to a FTP server with the usual connection details, which you need for access to your FTP (like the IP, login, password etc). If you already created a FTP connection and saved the neccessary information (see FTP settings), you can choose to load this set in the "FTP-set selection:" drop down list. Please be aware, that this dropdown list offers only FTP-sets from the default FTP-set folder, which you can define in the administration menu in the "Internet" or "Network" tab (the name depends on your version).

Alternatively, you can also upload files via an upload form on a website. For this you have to make sure, if the target website is using the HTTP or HTTPS protocol and select the appropriate tab. In the URL of upload form field, enter the exact link to the website, which contains your upload form field. Then the "Host:" field will be filled automatically and you only have to provide the exact name of the target form field. Below the two pictures, you can see an example source code for such an upload form field.

For both possbilities to upload files, you should consult your IT administrator or department for the correct access data and in both cases, you can use the dynamic processing of document content to rename the files after their successful upload.

FTP	HTTP/HTTPS

Upload form example source code:

<?php
if(move_uploaded_file($_FILES['datei']['tmp_name'], $_FILES["datei"]["name"]))
{
   echo '<b>Upload complete!</b>';
}
else
{
 echo " StepOver-Upload:<br><br>
   <form action=\"upload.php\" method=\"post\" enctype=\"multipart/form-data\"> 
    <input type=\"file\" name=\"datei\" size=100><br><br>
    <input type=\"submit\" value=\"Upload now!\">
   </form>";
}
?>

It´s also possible to forward additional parameter with the Upload URL, for PHP pages the URL would look like:

 https://www.stepoverinfo.net/Fileupload/uploaddbg.php?additionalParmeter=123456789[fileupload]

The UploadScript whould need to collect the additional parameter as a POST Value.

<?php

if(isset($_POST['additionalParmeter']))
{
	$file = 'C:\xampp\htdocs\Fileupload\info.txt';
	// Open file and read input
	$current = file_get_contents($file);
	// Add the additionalParmeter to the existing file content
	$current .= $_POST['additionalParmeter']."\n";
	// Write of file
	file_put_contents($file, $current);
}


if(isset($_FILES['fileupload']) && move_uploaded_file($_FILES['fileupload']['tmp_name'], $_FILES["fileupload"]["name"]))
{
   echo '<b>Upload complete!</b>';
}

 echo " StepOver-Upload:<br><br>
   <form action=\"upload.php\" method=\"post\" enctype=\"multipart/form-data\">
    fileupload: <input type=\"file\" name=\"fileupload\" size=100><br><br>
    <input type=\"submit\" value=\"Upload now!\">
   </form>";

?>

Delete original file

 This option deletes the originally opened PDF file, which can be useful in combination with folder monitoring and aborting of the signature process.

E-Mail (4)

With eSignatureOffice you can also send out an email automatically. In this mail, you could send the signed document or just a simple notification text.

• With the option "Always show E-Mail preview window" you can choose, whether you just want to send the mail automatically with your default e-mail application (e.g. Outlook) or if you want to take a personal look at it after it has been prepared but before it's sent.

• With the following three text fields, you can add the receipient's mail address, a subject to be displayed and an additional text to be written in the mail body. For this, you can also use the information contained within the document itself by using the dynamic processing of document content.
  
  
• Furthermore, you can select, which file shall be attached to the mail. You can either choose to send
  
  • no attachment
  • the signed document
  • the saved document
  • or the original, unchanged file

Application (5)

eSignatureOffice also allows to start a third party application. This could be an application to post-process the document or to evaluate/interprete the return file. With the field "Application to start:" you define if and which application shall be started when the macro is triggered. By clicking the "..." button, a new window will open and you can choose your location and file, but please be aware, it has to be a file type, which can also be used in Windows (*.exe for example). With the "Parameter" field, you can either select parameters from a list to be sent or you can also write down your own parameters, which could contain useful information for the other application.

The already prepared parameters are:

• [Signed file] - The document with all of its signatures.
  
• [Saved file] - The saved document.
• [Original file] - The original, unchanged document.

With the option "State of window at start" , you can define the if the application should start, normal, minimized, maximized or hidden. It is important that the application to be started must adhere to the relevant operating system conventions for this to work.

Furthermore, you have the option to "Wait for program termination", which you can use to delay subsequent macro actions until the started application has been terminated.

After click (6)

The last setting "After click" includes various actions, which can be executed after triggering the macro button and after all other actions in this macro have been completed.

You have the following options:

• do nothing (default)
• exit eSignatureOffice
• close the document
• close the document and minimize

This is always the last action of a macro.

Language

In the lower right of your macro configuration screen, you can see a list of languages available in eSignatureOffice.

This list can be used as quick access to the other languages, in order to fill in the macro text fields for the different languages. Click on the desired language and add the text to the fields, which shall be shown in the corresponding language.   As a little help, as soon as you mouse over any language, eSignatureOffice will change the colour of all text fields to red, in which customized text could be found, but which are empty. Of course, we can't check here if your entries are correct translations; we only check, if there is any text in the fields at all. This way, you can be sure not to forget, for example, your confirmation dialog in any language. If you wish to exclude any language from the check, double-click it in the list and it will be displayed white instead of yellow.