Some JSON Journal_* methods broken

Hi all,

I am intending to use the Quickfile Journal API functions to mass-create transactions.

I have so far discovered:
Journal_Create allows me to create Journal entries.
I can create Journals with two or more entries, for as long as the debit and credit sums balance out.
They show up in the Journals part of the Web UI just fine and exactly as they are intended.

Journal_Delete doesn’t let me delete the very created journal , and fails with XML exception:

{
  "Errors": {
    "Error": [
      "3The targetNamespace parameter 'http://www.QuickFile.co.uk' should be the same value as the targetNamespace '' of the schema.",
      "1The 'http://www.QuickFile.co.uk:Journal_Delete' element is not declared.",
      "2The 'http://www.QuickFile.co.uk:Header' element is not declared.",
      "3The 'http://www.QuickFile.co.uk:MessageType' element is not declared.",
      "4The 'http://www.QuickFile.co.uk:SubmissionNumber' element is not declared.",
      "5The 'http://www.QuickFile.co.uk:Authentication' element is not declared.",
      "6The 'http://www.QuickFile.co.uk:AccNumber' element is not declared.",
      "7The 'http://www.QuickFile.co.uk:MD5Value' element is not declared.",
      "8The 'http://www.QuickFile.co.uk:ApplicationID' element is not declared.",
      "11The 'http://www.QuickFile.co.uk:Body' element is not declared.",
      "12The 'http://www.QuickFile.co.uk:JournalDetails' element is not declared.",
      "13The 'http://www.QuickFile.co.uk:JournalReference' element is not declared."
    ]
  }
}

This is irrespective of the Journal being unlocked, locked, nor does the number of journal entries (whether debit or credit) matter.

Journal_Get response fails with:
single-line (i.e. two JournalLine entries for debit and credit)

{
  "Errors": {
    "Error": [
      "Internal Error: Unexpected end of file has occurred. The following elements are not closed: Journal_Get. Line 23, position 10."
    ]
  }
}

multi-line (i.e. more than two JournalLine entries for debit and credit)

{
  "Errors": {
    "Error": [
      "Internal Error: Unexpected end of file has occurred. The following elements are not closed: Journal_Get. Line 198, position 10."
    ]
  }
}

Quite apparently this is a server side fault as the latter is a very large journal (in fact, a live system year-end journal) hence the line numbers in the error messages change according to the size of the journal.

Support, to the rescue, please! :slight_smile:

Update:
Journal_Create should however block creating journal entries that lie within a blocked timespan as they would invalidate Year End reports.

Hi @Michel

I’ve asked our development team to take a look at this. I’ll update you once I hear back from them.

1 Like

UPDATE - Journal_Create broken, too (IMHO)

Hi @QFMathew, while programmatically sending Journal_Create messages (the messages above were handcrafted using the API sandbox) I run into the following error message:

{
  "Errors": {
    "Error": [
      "15The element 'JournalLine' in namespace 'http://www.QuickFile.co.uk' has invalid child element 'ItemDebitAccount' in namespace 'http://www.QuickFile.co.uk'. List of possible elements expected: 'http://www.QuickFile.co.uk:NominalCode'.",
      "21The element 'JournalLine' in namespace 'http://www.QuickFile.co.uk' has invalid child element 'ItemCreditAccount' in namespace 'http://www.QuickFile.co.uk'. List of possible elements expected: 'http://www.QuickFile.co.uk:NominalCode'."
    ]
  }
}

The messages have the following body structure:

    "Body": {
      "JournalDate": "****",
      "JournalName": "****",
      "JournalLine": [
        {
          "ItemDebitAccount": "****",
          "NominalCode": ****,
          "ItemDescription": "****",
          "ItemNotes": "****"
        },
        {
          "ItemCreditAccount": "****",
          "NominalCode": ****,
          "ItemDescription": "****",
          "ItemNotes": "****"
        }
      ]
    }

Manually reordering the items and sending again fixes the problem. This is the same bug described here: JSON API ordering of values

The ordering of the journal line object is semantically irrelevant (certainly since the child elements are all named), and should not be enforced.

I am programming in Java, using subclasses of JournalLine for debit and credit instances, which causes the debit and credit figures to appear first. Another way of implementing this would cause proper ordering but at the cost of very bug-prone code along with too much error checking lint in my code.

Two other issues here: ItemCreditAccount and ItemDebitAccount are enforced to be Strings rather than decimal numbers - why? It doesn’t make any sense…

Thanks,
Michel

All these issues stem from the way JSON requests are proxied to the underlying XML API. The JSON requests are converted to XML and rerouted to the XML gateway, this XML is validated against a set of XSD schemas that enforce strict ordering.

We are currently working on a new version of the JSON API that will remove the strict ordering requirement and resolve the JSON array issues. It’s quite a complex job but it is something that is being worked on and should be ready very soon.

1 Like

Hi @Glenn

Why are you working on the bank holiday! :slight_smile:

I have found a way to refactor my code to enforce the ordering in the meantime - but the other Journal methods are more pressing to me to work.

1 Like

Half day only I hope :slight_smile:

Are you referring to the issue with debit and credit amounts getting returned as strings?

@Glenn

No, these are easy enough, though causing unnecessary parsing everywhere.

I am referring to the Journal_Get, Journal_Delete issues I referred to originally.

We’ll get those looked into first thing tomorrow morning, it does look like a server side issue.

The type issues will be fixed in future versions of the API.

Version 1.2 (due next week) will address element ordering and arrays
Version 1.3 (most likely mid-June) will translate types accurately rather than returning everything as string values.

1 Like

Great!

How will this be introduced to production? Versioned endpoints? Perhaps not so important for this issue, but perhaps necessary for other JSON API changes in the future?

Yes it will be versioned endpoints e.g.

https://api.quickfile.co.uk/1_2/bank/search
https://api.quickfile.co.uk/1_3/bank/search
etc
1 Like

@Michel the issues with the Journal endpoints should now be resolved although please let me know if you encounter any further difficulties.

We’re continuing to work on other aspects of the JSON API that I will inform you of in due course.

Hi @Glenn,

Well done!

I can confirm, using API version 1.2, that:

  • I can create journals with two or more lines.
  • I can search for journals (as before)
  • I can get Journal details for a specific journal ID
  • I can delete a journal.

How can I bulk-delete journals using the API? The documentation states that I can add up to 250 Journal references, but my handcrafted sandbox JSON failed.

BTW I see you are not by default using UUIDs as submission numbers in the sandbox. *thumbs up!

Excellent!

I think this should work:

"Body": {
      "JournalDetails": {
        "JournalReference": [
          "API22e1837f-3a33-43bd-b",
          "API22e1837f-3a33-43bd-c"
        ]
      }
    }

Well it’s a little tedious manually incrementing a number each time :slight_smile:

facepalm Of course - I’m still not thinking JSON enough in my head…

Re UUID, the sandbox automatically updates it whenever I select a method or ask it to copy the example to the JSON editor.

Small suggestion: Add a little trigger link next to the transaction id field (using a typical refresh icon) to have it automatically refreshed (using a little bit of JavaScript)

1 Like