API
Guide

DocMoto client API

DocMoto client API

The DocMoto client API supports extending the functionality of the base DocMoto client.

The essential principle behind the API is that it allows you to call external processes to perform tasks such OCR a document or extract attachments from an email.

The scripts can be initiated either by means of a menu item or by means of tags at the point of a document being added to the DocMoto repository.

Client Extensions

All client extension scripts MUST be in a folder called Client Extensions within the "DocMotoConfig" folder.

If the folder does not already exist simply create it.

Below is an example client extension script used to call a shell script "ExtractEmailAttachments.sh". In this case the script is also containined within the Client Extensions folder.

<dmExtension>
  <title>Unpack Email</title>
  <relevence readonly="false"
             minAny="1" maxAny="1"
             minFiles='1' maxFiles='1'
             minFolders='0' maxFolders='0'
             patterns='*.eml,*.emlx' />
  <actions>
      <action type="internal" value="get"/>
      <action type="shell"    value="~/ExtractEmailAttachments.sh" >
      </action>
      <action type="internal" value="put" />
  </actions>
</dmExtension>

  • dmExtension - The DocMoto extension tag. The high level container for any extension.

  • title - The text that will appear in the "File" menu on the DocMoto client. To create a sub menu use the forward slash (/) operator. Eg Emails/Unpack will create a parent menu Emails with sub menu Unpack.

  • relevence - The tag used to determine under which conditions the menu item is relevent. If not considered relevent the menu item will not be displayed.

    • readonly - Set "true" for relevent if the user has READ-ONLY access to the selected item. Set "false" otherwise.

    • minAny - The minimum number of folders or files that can be selected.

    • maxAny - The maximum number of folders or files that can be selected.

    • minFiles - The minimum number of files that can be selected.

    • maxFiles - The maximum number of files that can be selected.

    • minFolders - The DocMoto extension tag. The high level container for any extension.

    • maxFolders - The DocMoto extension tag. The high level container for any extension.

    • patterns - A comma separated list of relevent folder or file name patterns. Supports the wildcard charater (*).

  • actions - Container for the action list.

  • action - The operation to be performed. Actions are performed in the order they are listed.

    • type - The type of action, set "internal" for internal DocMoto operations, set "shell" to call a shell script.

    • value - The value for "type". Internal actions can be "get" to retrieve a file from DocMoto or "put" to add a file to DocMoto.

      For "shell" the path to the shell script to call. If prefixed with "~/" will look for the script in the current "Client Extension" folder. See notes below

The corresponding shell script

The shell script corresponding to the above dmExtension is listed as follows:

# Create, append a log file and write to it

OUTFILE=/tmp/docmoto_${USER}.unpack.log
echo "starting on " `date`         >> $OUTFILE

# If first argument is -d write debug info to log

DEBUG=""
if [[ "$1" == "-d" ]]; then
    echo "$0"    >> $OUTFILE

    echo "$@"    >> $OUTFILE
    DEBUG="-d"
    shift
fi

# Define a working folder to use for unpacking

FOLDER=/tmp/docmoto_${USER}/unpack/$(($$ >> 8))/$(($$ % 256))
mkdir -p $FOLDER
rm -rf $FOLDER/*

# Call the application "DocMotoUnpackFile"
# Arguements: -d (optional)
#            -f  full path of file to be processed
#              -t elma  (unpackfile allows different sorts of unpack)
#              -o destination_folder
#              2>>$OUTFILE sends messages to the log file

# by convention this returns a list of new folder and filenames for the script to work with

/Applications/DocMotoClient.app/Contents/MacOS/DocMotoUnpackFile $DEBUG -f "$1" -t emla -o $FOLDER 2>>$OUTFILE

# returns 0 if successful else an error code which it places in variable RC
RC=$?

echo "finished on " `date`  >>$OUTFILE

#now return the error code
exit $RC

Notes

Shell scripts are expect to take as input a single parameter which is the path (on the local machine) to the file to process.

Shell scripts can output anything, however only output prefixed by a single or double > followed by a space will be considered.

Use single > followed by a space for files, use a double > followed by a space for folders. eg:

>> myemail.eml_
> first_part_of_email.txt
> attachment1.doc
> last_part_of_email.txt

This will result in DocMoto creating a folder "myemail.eml_" and placing in it three files, first_part_of_email.txt, attachment1.doc and last_part_of_email.txt

Client Scripts

Client scripts are used to call external processes. Unlike Client Extensions they cannot be called through a menu item. Instead they are invoked when a file is added to DocMoto.

All client scripts MUST be in a folder called Scripts within the "DocMotoConfig" folder.

If the folder does not already exist simply create it.

Client scripts are controlled using tags. In particular they can be initiated when one or more tags are set to a particular value.

Typical uses for client scripts are to call an external process to OCR a file prior to input, or add an entry to a calendar, or rename a file.

Below is a sample script that adds an entry into a calendar.

<?xml version="1.0" standalone="no"?>
<docmoto_script>
  <rules logic="and">
      <rule field1="total-files" comparator="&lt;" field2="10" />
      <rule field1="tag:DMUSER:/iCalCalendar"  comparator="not equals" field2="string:none" />
      <rule field1="tag:DMUSER:/iCalCalendar"  comparator="not equals" field2="string:tbd" />
      <rule field1="tag:DMUSER:/iCalCalendar"  comparator="not equals" field2="string:" />
      <rule field1="tag:DMUSER:/iCal1Date"  comparator="not equals" field2="string:" />
      <rule field1="tag:DMUSER:/iCal1Status"  comparator="not equals" field2="string:OK" />
  </rules>
  <script name="iCal.sh">
      <parameter name="tag:DMUSER:/iCalCalendar" />
      <parameter name="tag:DMUSER:/iCal1RecordType" />
      <parameter name="tag:DMUSER:/iCal1Date" />
      <parameter name="x-docmoto-link" /> 
      <parameter name="tag:DMUSER:/iCal1Title" />
      <parameter name="tag:DMUSER:/iCal1Notes" />
      <parameter name="tag:DMUSER:/iCal1Attendees" />
      <parameter name="tag:DMUSER:/iCal1Alarms" />
  </script>
  <actions>
        <!-- onreturn values... 
          0 tends to mean ok... and you wouldn't normally specify a message or alerts
                                though you could do so if you wished -->
        <action scriptreturns="0" return="OK" >
            <actionstep tag="DMUSER:/iCal1Status" value="OK"/>
       </action>
        <!-- default ie no scriptreturn specified -->
       <action scriptreturns="" return="SKIP" message="Problem posting to iCal 1!">
           <alerts >
               <option prompt="Abandon" return="CANCEL" />
               <option prompt="Skip" return="SKIP" />
               <option prompt="Continue" return="OK" />
           </alerts>
           <!-- setting a tag will only make sense if the user chooses to continue -->
            <actionstep tag="DMUSER:/iCal1Status" value="FAILED"/>
    	</action>
        
        <!-- return can be OK,SKIP,CANCEL -->
        
  </actions>

</docmoto_script>

  • docmoto_script - The DocMoto script tag. The high level container for any script.

  • rules - Top level container for the rules under which a script is invoked.

    • logic - Determines how rules are evaluated. Set "and" or "or". Logic can be nested. eg:

      <rules logic="or">
	<rule field1="tag:DMUSER:/ocr" comparator="=" field2="string:Y" />
	   	<rules logic="and">
	     	<rule field1="tag:DMUSER:/scanner" comparator="=" field2="string:scanjet2" />
	     	<rule field1="username" comparator="!=" field2="string:mike" />
	 	</rules>
</rules>

  • rule - Defines each individual criteria.

    • field1 - First value for rule evalution. Can be a tag, string, date, or number.

      To delare a tag prefix "tag:", to declare a string prefix "string:". To declare a date prefix "date:". To declare a number no prefix is required.

    • comparator - Determines how field 1 and field2 are evaluated.

      Functions
      Non-string FunctionString functionMeaning
      =equalsEqual to
      !=not equalsNot equal to
      > Greater than
      >= Greater than or equals
      < Less than
      <= Less than or equals
       starts withMatches from the left
       not starts withMatches from the left
       ends withMatches from the right
       not ends withMatches from the right
       matchMatches substring
       not matchMatches substring

    • field2 - The second value to be evaluated. Can be a tag, string, date, number or fully qualified tag name.

      To delare a tag prefix "tag:", to declare a string prefix "string:". To declare a date prefix "date:". To declare a number no prefix is required.

  • script - Defines a script and contains the parameter list.

    • name - The full path to the script. If only the script name is added the script is assumed to be in the "Scripts" folder.

  • parameter - Defines a parameter that can be sent to a script. Pararmeters are passed to the script in the order they are listed.

    • name - Used to declare the value passed to the script. Can be a tag value, a string or a DocMoto username. Tags are prefixed with "tag:", strings with "string:", usernames require no prefix.

  • actions - Container element for the "action" elements. Actions handle any return values from the script.

    • action - Defines the behavior for a given return value from the script.

      • scriptreturns - The return value from the script. Leave as an empty string for no return.

      • return - The return value passed to DocMoto, possible values are OK,SKIP or CANCEL.

        • OK - Tells DocMoto to check the current file in and continue and process the next file.

        • SKIP - Tells DocMoto to not check in the current file and continue and process the next file.

        • CANCEL - Tells DocMoto to stop processing any further files.

      • message - A message returned to the user through the DocMoto interface.

    • actionstep - Defines a value that can be entered against a tag in the event of a given "action".

      • tag - The name of the tag to modify.

      • value - The value to enter for "tag".

    • alerts - A container for "options". Used to define buttons displayed back to the DocMoto user interface as part of the pop-up. The warning message will be "message" as defined above.

      • tag - The name of the tag to modify.

      • value - The value to enter for "tag".

    • option - Defines buttons displayed back to the DocMoto user interface as part of the pop-up.

      • prompt - Text displayed to the user in the form of a button.

      • return - The pre-defined action to take is response to the user selection that "option". Possible values are "OK", "SKIP" or "CANCEL".

Support Centre

Still have a question?

If you still can't find the answer to your question or need more information, please contact the DocMoto team on +44 (0)1242 225230 or email us

We value your privacy

We use Cookies to make using our website easy and meaningful for you, and to better understand how it is used by our customers. By using our website, you are agreeing to our privacy policy.

I agree