openDias - project portal

openDIAS - API.

controlAccess

Purpose:
Code mapping: controlAccess -> pageRender::controlAccess
Called from: openDias.saveDetails.js :: anonymous()
Inputs:
- action: fixed string 'controlAccess'
- submethod: The type of access controls being updated
- location:
- role:

Outputs;

<Response>
  </DeleteDoc>
    status - indication of the update process - currently a static string 'OK'
  </DeleteDoc>
</Response>

deleteDoc

Purpose: Removes a document from the database and scanned images store.
Code mapping: deleteDoc -> docEditor::doDelete
Called from: openDias.saveDetails.js :: anonymous()
Inputs:
- action: fixed string 'deleteDoc'
- docid: the documents id

Outputs;

<Response>
  </DeleteDoc>
    status - indication of the update process - currently a static string 'OK'
  </DeleteDoc>
</Response>

docFilter

Purpose: Get a list of documents that fit a specific set of cryteria
Code mapping: filter -> pageRender::docFilter
Called from: openDias.filter.js :: anonymous()
Inputs:
- action: fixed string 'docFilter'
- subaction: Get all details or just the count of matching docs ['count','fullList']
- textSearch: Text that a document must match (title or ocr text)
- isActionRequired: If 'true' return only records that are marked as 'action required'.
- startDate: The first date that a document could fit into
- endDate: The last date that a document could fit into
- tags: Comma delimited list of tagnames
- page: [optional] The number of 'range' offsets to apply before the first returned row.
- range: [optional] The number of records to return in a single request.
- sortfield*: [optional] Order the results by column
- sortorder: [optional] present results in acending/decending order ['0','1']

Outputs;

<?xml version='1.0' encoding='iso-8859-1'?>
<Response>
  <DocFilter>
    count - The count of matching documents
    page - The required page
    <Results>
      <Rows>
        docid - the document id of a found document
        actionrequired - indicator flag
        title - the user defined title of the found document
        type* - the style of document
        date - the user defined date of the found document
      </Rows>
    </Results>
  </DocFilter>
</Response>

doScan

Purpose: Starts a scanning process.
Code mapping: doScan -> pageRender::doScan()
Called from: openDias.acquire.js :: anonymous()
Inputs:
- action: fixed string "doScan",
- deviceid: The sane device id, as provided by getScannerList : Response.ScannerList.Devices.Device.name
- format: The format to use for scannsing, one of getScanningList : Response.ScanningList.Devices.Device.Formats.format
- pages: The number of pages that make up the document,
- resolution: The resolution to set the scanner to, between Response.ScannerList.Devices.Device.min and Response.ScannerList.Devices.Device.max,
- ocr*: Flag to indicate if an OCR process should be performed and in what language,
- pagelength: The length of the page to scan, Percent, in relation to the maximum available by the scanner.

Outputs;

<?xml version='1.0' encoding='iso-8859-1'?>
</Response>
  </DoScan>
    scanuuid - The application uniq id for the scanning process.
  </DoScan>
</Response>

getAccessDetails

Purpose: Get a list of specific grants that have been setup
Code mapping: getAccessDetails -> pageRender::getAccessDetails
Called from: openDias.getAccessDetails.js :: anonymous()
Inputs:
- action: fixed string 'getAccessDetails'

Outputs;

<?xml version='1.0' encoding='iso-8859-1'?>
<Response>
  <AccessDetails>
    <LocationAccess>
      <Access>
        location - network address that's linked to a role
        role - the priverlage assigned by this access
      </Access>
      ...
    </LocationAccess>
    <UserAccess>
      <Access>
        user - username that's linked to a role
        role - the priverlage assigned by this access
      </Access>
      ...
    </UserAccess>
  </AccessDetails>
</Response>

getAudio

Purpose: Get the web accessable filename that contains the read OCR
Code mapping: getAudio -> [stump - not currently implemented]
Called from: openDias.loadDetails.js :: anonymous()
Inputs:
- action: fixed string 'getAudio'
- docid: the documents id

Outputs;

<?xml version='1.0' encoding='iso-8859-1'?>
<Response>
  <Audio>
    filename - the filename that contains the audio of the selected doc 
  </Audio>
</Response>

getDocDetails

Purpose: Get all the current information about a document
Code mapping: getDocDetail -> docEditor::getDocDetail
Called from: openDias.loadDetails.js :: anonymous()
Inputs:
- action: fixed string 'getDocDetail'
- docid: the documents id

Outputs;

<?xml version='1.0' encoding='iso-8859-1'?>
<Response>
  <DocDetail>
    docid - the docid of the selected doc
    title - the user defined title of the selected doc
    extractedText - the OCR text of the selected doc
    docDate - the user defined date of the selected doc
    scanDate - the date that the document was added to the application.
    type* - the style of document
    pages - the number of pages used by the document
    actionrequired - a flag indicating if the document has been marked as requiring further action
    x - the number of horizontal pizel required by the document
    y - the number of lines required by the document
    <Taqs>
      <tag>
        tagname - the name of the assigned tag
      </tag>
      ...
    </Tags>
  </DocDetail>
</Response>

getScannerList

Purpose: Get a list of scanners (and their usage parameters) that the application can use.
Code mapping: getScannerList -> pageRender::getScannerList()
Called from: openDias.acquire.js :: anonymous()
Inputs:
- action: fixed string 'getScannerList'

Outputs;

<?xml version='1.0' encoding='iso-8859-1'?>
<Response>
  <ScannerList>
    <Devices>
      <Device>
        <Formats>
          format - the format that a scan can be performed in. currently only fixed string 'grey scale'
          ...
        </Formats>
        type - sane text that describes the scanning device (eg 'flat bed')
        vendor - sane text that names the scanning device
        model - sane text that names the scanning device
        host - text representation of the location of the scanner
        name - the machine id for the scanning device
        default - the default resolution
        min - the minimum resolution allowed by the scanning decice
        max - the maximum resolution allowed by the scanning device
      </Device>
      ...
    </Devices>
  </ScannerList>
</Response>

getScanningProgress

Purpose: Read the state of an asyncronouse scan.
Code mapping: getScanningProgress -> pageRender::getScanningProgress()
Called from: openDias.acquire.js :: getScanningProgress()
Inputs:
- action: fixed string 'getScanningProgress'
- scanprogressid: The uuid of the scanning process (as returned by 'doScan')

Outputs:

<?xml version='1.0' encoding='iso-8859-1'?>
<Response>
  <ScanningProgress>
    status* - the current action being done by the system
    value - representation of how far along the action being done, is.
  </ScanningProgress>
</Response>

moveTag

Purpose: Updates links between documents and tags
Code mapping: moveTag -> docEditor::updateTagLinkage
Called from: openDias.saveDetails.js :: anonymous()
Inputs:
- action: fixed string 'moveTag'
- docid: the documents id
- tag: the tag that is being (un)linked
- subaction: flag to indicate if the tag should be added or removed ['addTag','removeTag']

Outputs;

<Response>
  </MoveTag>
    status - indication of the update process - currently a static string 'OK'
  </MoveTag>
</Response>

nextPageReady

Purpose: Signal to the application that the user has correctly placed the next page for scanning.
Code mapping: nextPageReady -> pageRender::nextPageReady()
Called from: openDias.acquire.js :: anonymous()
Inputs:
- action: fixed string 'nextPageReady'
- scanprogressid: The uuid of the scanning process (as returned by 'doScan')

Outputs;

<?xml version='1.0' encoding='iso-8859-1'?>
<Response>
  <NextPageReady>
    result - indication if the next page command was accepted, currently a fixed string 'ok'
  </NextPageReady>
</Response>

updateDocDetails

Purpose: Update a documents field with a specific value.
Code mapping: updateDocDetails -> docEditor::updateDocDetails
Called from: openDias.saveDetails.js :: anonymous()
Inputs:
- action: fixed string 'updateDocDetails'
- docid: the documents id
- kkey: the name of the field that is being updated
- vvalue: the new value to set the field to

Outputs;

<?xml version='1.0' encoding='iso-8859-1'?>
<Response>
  <UpdateDocDetails>
    status - indication of the update process - currently a static string 'OK'
  </UpdateDocDetails>
</Response>

tagsAutoComplete

Purpose: Complete a tagname from the start of the name.
Code mapping: tagsAutoComplete -> pageRender::tagsAutoComplete
Called from: openDias.loadDetails.js :: autocomplete function()
Inputs:
- startsWith: the beginning of the tags to return.
- docid: the documents id
Outputs; JSON as required by JQuery autocomplete methods.

Definision

status

0 - SCAN_IDLE,
1 - SCAN_INTERNAL_ERROR,
2 - SCAN_DB_WORKING,
3 - SCAN_DB_ERROR, // DB error code
4 - SCAN_WAITING_ON_SCANNER,
5 - SCAN_ERRO_FROM_SCANNER, // SANE error code
6 - SCAN_SCANNING, // Current progress
7 - SCAN_WAITING_ON_NEW_PAGE, // Waiting for page [x]
8 - SCAN_TIMEOUT_WAITING_ON_NEW_PAGE,
9 - SCAN_CONVERTING_FORMAT,
10 - SCAN_ERROR_CONVERTING_FORMAT, // FreeImage error code
11 - SCAN_PERFORMING_OCR,
12 - SCAN_ERROR_PERFORMING_OCR, // xxxxxx error code
13 - SCAN_RESERVED_3, // Used to be FIXING_SKEW,
14 - SCAN_RESERVED_1,
15 - SCAN_RESERVED_2,
16 - SCAN_FINISHED // id of the saved doc

Type

1 - ODF Document
2 - Scanned Document
3 - PDF Document
4 - Imported Image

ocr - Language

eng - International English
deu - German
fra - French
spa - Spanish
ita - Italian
nld - Dutch
por - Brasilian Portuguese
vie - Vietnamese

sortfield

0 - docid
1 - title
2 - doc type
3 - date

Request method

Any of the API calls can be make invoken by making an HTTP POST request to the "/opendias/dynamic" entry point, over the port that the application is running on.

Usually this would be done via an AJAX call on a webpage, but could just as easily be make from any application. eg, this is a call to invoke a new scanning operation from bash.

telnet localhost 8988 <<__endjob
POST /opendias/dynamic HTTP/1.1
Host: localhost:8988
User-Agent: Mozilla/5.0
Accept: application/xml, text/xml, */*
Accept-Language: en-gb,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 115
Connection: keep-alive
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Requested-With: XMLHttpRequest
Referer: http://localhost:8988/opendias/acquire.html
Content-Length: 100
Pragma: no-cache
Cache-Control: no-cache

action=doScan&deviceid=test%3A0&format=Grey+Scale&pages=1&resolution=300&ocr=-&pagelength=100
__endjob

Error Response

Any of the API calls could return an error message. Fontends should check for this error and take appropriate action. Outputs:

<?xml version='1.0' encoding='iso-8859-1'?>
<Response>
  error - a message describing the problem
</Response>

Recent Changes

0.7.2
- Removed 'skew' from the inputs of 'doScan'