How to view updates and additions to the available APIs
The release of Ephesoft Transact 2020.1 includes updates and additions to the available APIs. You can view a comprehensive list in one of two ways. Ephesoft’s Documentation includes the Web Services Explorer here:
If you have access to an Ephesoft instance, you can access documents by adding your information in to this link: https://{machine name or localhost}:{portnumber}/dcma/rest/swagger-ui.html#/. These pages will show you all the available APIs. The documentation local to an Ephesoft instance allows you to test the APIs and view the ones specific to your version. You may have to use the drop-down menu at the top to navigate through all the options.
Image 1: Sample of drop-down menu to navigate through the API versions available
Many of these APIs seem to be made for use with the Global Batch Class (Ephesoft Global Batch Class and Why It’s Useful) that also came with the 2020.1 release. In short, the Global Batch Class is meant for storing the Document Types that are reused in many locations. This ensures consistency throughout the environment.
Some of the APIs added in the 2020.1 release
- Delete batch class serialization file (/rest/v3/batchClasses/{batchClassName}/files/{fileType})
This API is a quick way to delete the serialized file, the Batch Class cache, after updating Batch Class configurations. This will force Ephesoft to create a new serialized file which will make sure those changes to a Batch Class are in newly executed Batch Instances.
- Get document types (/rest/v3/batchClasses/{batchClassName}/documentTypes)
This list of details provides information on what is used in a given Batch Class and whether the information comes from a Global Batch Class. The only thing this set of APIs is lacking is getting details for everywhere a Global Document Type is being used. However, that can be accomplished by running calls for all the Batch Classes and checking the results since XML is easy to digest, search, and compare.
- Import Global Document Type (/rest/v3/batchClasses/globalBatchClass/documentTypes), Update Document Types (/rest/v3/batchClasses/{batchClassName}/documentTypes), and Delete Document Types (/rest/v3/batchClasses/{batchClassName}/documentTypes/{documentTypeName})
Moving Document Types from the Global Batch Class around to other Batch Classes
Moving Document Types from the Global Batch Class around to other Batch Classes is another way that these new APIs could be applied. For many customers of Ephesoft who are transitioning to using the Global Batch Class (Ephesoft Global Batch Class and Why It’s Useful), these API additions allow for mass deletion of duplicate or near duplicate Document Types and easy addition of the (newly) created Global Document Type into the relevant Batch Classes (importDocumentType).
- Update index fields
- Delete index fields
- Create index fields
- Copy KV extraction rules
- Copy validation rules
- Get batch instance (/rest/v3/batchInstances/{batchInstanceId})
The APIs are easily digestible and searchable as they are in JSON format. A few of these could be helpful for doing a fast and unofficial audit on what is where and when. The /rest/v3/batchInstances/{batchInstanceId} API is an alternative to checking database records around a batch instance without needing to make a database query. The info included is: Batch Class Id, number of batch retries, creation date, current user, custom columns, description, encryption algorithm, executed modules, executing server, identifier, is suspended, last modified date, local folder, lock owner IP, name, priority, resuming server, review operator name, server IP, status, UNC subfolder, validation operator name, workflow start time.
Other uses for APIs
In addition, many APIs can be used for the configuration management of development, UAT, and production Batch Classes or Document Types. For both instances, these APIs can be used to move info (such as extraction and validation rules) from one Batch Class or Document Type to another without overwriting or deleting anything else. This is especially useful with the Global Batch Class and Document Types. Since you cannot upload Batch Instances to be processed by the Global Batch Class, large scale testing must be done using another Batch Class.
In order to maintain the integrity of other Batch Classes that are using the Document types, we recommend that you use local copies of the Document Types when changing rules within them. When this is done, the APIs allow for an easy way to move those rules from the local testing Document Types to the Global Document type in a large batch, rather than manually having to do it in the UI.
A few caveats
A few caveats are worth mentioning. Many of these operations are for Document Level Fields only. In the case of updating, name changes will have to be done manually through the UI. If an update command has updates to multiple locations, it will successfully complete them one by one. If one is incorrect or has an error, that will be the only part that fails. Even with these slight limitations, these APIs make doing large groups of changes much simpler than doing them manually in the UI. Overall, these APIs seem geared towards making many changes at once. This saves time across a lot of uses.
There are a few APIs that are not covered in this article. Much like the rest, they are ideal for migrating current content from existing Batch Classes.