Phone800.366.3472 SupportGet Support DocumentationDocumentation Resource CenterResource Center
search
close
Open Menu

Synergex Blog


Elevate Your Endpoints

By Liz Wilson, Posted on July 14, 2021 at 12:55 pm

Liz Wilson

If you’ve checked out our GitHub documentation, attended an office hours session, or watched a web services–related video on our YouTube channel, you may know that OData is a critical layer of the tech stack that makes up our open-source Harmony Core solution.1 There are several reasons for this: OData is standards-based, it supports query validation (so you can choose the data available to users in a given context), and the learning curve is minimal. Developers can look at a sample OData request and immediately get a sense of what is being asked for, and our implementation of OData emits JSON, a standards-based data format that other programming languages can parse with ease.  

OData is easy to work with, but it’s important to know how to make the most of Harmony Core’s API functionality, beyond just the basics. Here are some tips for maximizing the readability and performance of the APIs that you will be generating via Harmony Core’s OData services. 

Use Meaningful Names 

Harmony Core OData services rely partially on data structures and files from Repository. That said, where appropriate, it’s a good idea to have meaningful names for data structures, as these will be turned into URLs. For example, “CustomerNumber” would be better than “CSTNBR.” 

vs.

Don’t Skimp on Data 

It might seem odd to buck a “less is more” approach to exposing your data, but in the world of Harmony Core, the better setup will likely be one in which most of your data is initially made available to developers, and the specificity of who gets what is determined when these developers create URLs, like the one below, to extract the exact information they need:  

To do this, you can configure your Harmony Core environment to enable the entity collection endpoints feature. This will generate a new GET method in each of your controller classes that exposes their respective collections (e.g., all customers, all products, etc.). You can access the GET method through an HTTP GET request without parameters.  

Plan Ahead 

The more planning you do in terms of the data you’d like to query for, the more specific you can make your endpoints. The more specific the endpoint is, the faster your query will be, as asking for a smaller amount of data takes less time than requesting a large collection.  

If you have access to an entity’s primary key, you can adjust your environment configuration to enable single entity endpoints. This will allow you to whittle down your results with a URL that incorporates the item’s unique key, thereby reducing load time. To illustrate, our sample Harmony Core service provides testable queries for all customer data, as well as for a single customer.  

When I tracked how long it took to load each page, I noticed that the “all customers” collection took 114 milliseconds, while the single customer query took about half that time—52 milliseconds. 

vs.

If you’re able to map things out in advance and narrow your data needs further, you can specify an entity’s discrete properties. For example, rather than retrieving the entire data set for an individual customer, you can query for the customer’s phone number, name, or website. To do this, check out the instructions for enabling individual property endpoints on GitHub.   

Get Familiar with Third-Party Tools 

Our documentation references two useful API-related platforms: Postman and Swagger. Postman was created as client for testing API requests and responses and has grown to include functionality for building APIs, creating reports, and generating documentation automatically. You can find more information on Postman in Harmony Core tutorial two in Github

While documentation generation was a recent addition to Postman’s suite of API tools, Swagger has focused on API visualization from the very beginning. In a Harmony Core environment, you will have automatic access to Swagger-generated documentation for your endpoints, but you may have a use case for one of the other tools listed on their website

There are plenty of additional tips scattered  
throughout the Harmony Core tutorials on GitHub
so we encourage you to check them out! If you have  
questions on getting started with or furthering your use  
of web services, be sure to talk to your account executive  
or join us for a session of Harmony Core Office Hours.  
We have more best practices to share from previous  
Harmony Core implementations


1 Under the hood, Entity Framework Core translates OData queries into Synergy Select class operations.


CodeGen 5.7.3 Released

By Steve Ives, Posted on July 9, 2021 at 6:47 pm

Steve Ives

There’s a new version of CodeGen out there, so if you’re using it, here’s what’s changed in this version:

  • We added a new special structure expression token <STRUCTURE_HAS_FIELD_name> that allows you to detect the presence or absence of a named field within the structure.
  • We improved the logic used when processing unique key loops and unique alternate key loops and made a slight change to the way that the unique alternate key loops operate. Previously the loop would not compare alternate key segments with the primary key, but now it does. So the loop now processes any alternate keys that do not have identical key segments to the primary key or any previous alternate keys.
  • We fixed a problem with the implementation of the -pa command line option that would cause CodeGen to fail when used with an input file containing multiple structures.
  • We fixed a problem with the implementation of the -tweaks option which could result in a null reference exception in some rare circumstances.
  • We reviewed and updated all sample templates that ship with CodeGen to ensure they use the latest capabilities such as taking advantage of complex expressions to simplify template complexity resulting from nested expressions.
  • This version of CodeGen was built with Synergy/DE 11.1.1g and requires a minimum of version 10.1.1 to operate.

As always, this new release is backward compatible with earlier releases, so we recommend that everyone download the new version as soon as possible.


SQL Replication Enhancements

By Steve Ives, Posted on December 4, 2020 at 3:21 pm

Steve Ives

For several years now, Synergex has maintained an open-source example that provides an example of how to implement the replication of a Synergy applications data to a Microsoft SQL Server database, in near-to-real-time. The example environment makes considerable use of CodeGen to generate the bulk of the code needed to implement the interaction with the SQL Server database, and much of the remaining required code can be used out-of-the-box, requiring very little, if any change to the original Synergy application to enable the data replication to take place. The example environment has been used as a template by many customers, and our Professional Services team has assisted many others by delivering either proof of concept examples, or full-scale implementations.

As technologies and product capabilities evolve, we periodically revisit the code to ensure that it is taking advantage of the latest features and adhering to best practices. Good performance is also of critical importance in products like this, so we frequently revisit the code looking for opportunities to make improvements in throughput.

We have just completed the latest review of the code, and on this occasion, we did make some changes, which are briefly described below.

  • We now generate an additional function that returns the key number of the first unique key for each ISAM structure. This allows us to avoid the need for code that previously detected the first unique key number at runtime; that code required that the replicator had an open channel to each data file being replicated.
  • We also generate an additional function that, when passed a record containing data, returns the key value of the first unique key. Previously, the code used the Synergy routine %KEYVAL for this purpose, but it also requires that the replicator has an open channel to every data file replicated.
  • Because of the previous two changes, we were able to remove the replicator’s requirement to open the underlying data files that are being replicated. The only files that the replicator now opens are the instruction queue file and log file.
  • We added code to make the replicator more resilient to interruptions to network connections when using xfServer to access the instruction queue file on a remote system. If a network problem is detected, the replicator now closes the instruction queue file and then attempts to re-open it on a new channel. If this operation fails, it will retry several times with a delay between attempts. The number of retries and the delay between retries are both configurable via command-line options or environment variables.

If you already have a SQL Replication environment based on our sample environment, then you might consider checking out the latest version and applying the changes to your own codebase, and if you’d like some help with that, then our Professional Services team will be happy to assist. And if you haven’t yet implemented a SQL Replication environment but are interested in doing so, get in touch with your Synergex account rep and ask them to set up a demo.


SQL Replication – Significant New Features

By Steve Ives, Posted on January 16, 2020 at 8:10 pm

Steve Ives

In recent weeks we have been working on making improvements to our SQL Replication environment, which demonstrates how to easily replicate your Synergy data to a SQL Server database. Some of these changes were undertaken in collaboration with a customer that uses the environment extensively, and we thank them for their input and support. Other changes have been on our road-map for some time and we think you’ll be excited about what has been achieved. Here’s a summary of the changes:

  • Synergy 11 introduced a new SQL Connection API capability which calls the ODBC API function SQLDescribeParam behind the scenes to improve performance and avoid excessive cache memory thrashing for SQL statements that have I/O parameters when accessing SQL Server (VTX12_SQLNATIVE). Synergex recommend setting SSQL_PERFORMANCE_SQL to yes (or setting the SQLPERFORMANCESQL environment variable. We have updated the environment to do this, which should result in improved performance when running in Synergy 11 or higher environments.
  • We have added the ability to run multiple instances of the replicator process side-by-side, within a single data set, and to divide up the replication of different files between these multiple replicator instances. Each instance is assigned a unique instance name and has its own associated instruction queue file, the name of which includes the instance name, as does the log file produced by each instance. In a multi-instance environment developers can chose on a file-by-file bases which data files are replicated via which queue file, and therefor via which replicator instance. It is important to understand that in this scenario there is no synchronization of the sequence in which changes are applied to the underlying SQL database between the multiple instances of the replicator.
  • We have added the ability to exclude certain fields in a record from being appearing in and being replicated to the associated SQL Server database table. It is important that fields associated with keys not be excluded, unless those keys are also excluded (see the next item). Generally the fewer fields/columns that are replicated the faster the replication will be.
  • We have added the ability to exclude certain keys from processing, so that matching database indexes will not be created in the associated database tables. Generally the fewer indexes that exist on a table the faster the replication will be.
  • We have added the ability for the replicator to detect some kinds of database failure, caused by network errors, or the database being shut down or otherwise unavailable, and allow it to gracefully disconnect, and then attempt to reconnect, with a configurable number of retries and retry interval. This should make the replicator processes more robust.
  • We have added the ability to change the database datatypes of fields. The main use case envisaged is transforming decimal fields into implied decimal fields (adding decimal places in the database data), but there may be other use cases, such as transforming Y/N fields into Boolean true/false fields, etc.
  • We have also corrected an issue that could occur if replicator encountered an unexpected error and was configured to use BATCH COMMIT mode. Is some circumstances, if there were uncommitted changes at the time on an error any uncommitted changes could be lost because the change records were deleted from the instruction queue one by one before the batch was committed. Now any instructions related to uncommitted changes remain in the queue file until the batch is committed, and are then all deleted. When the replicator is restarted it will then attempt to reply the changes to the database again. This should help prevent the database getting out of sync if there is a replicator failure.

We’re excited about these new features in our SQL Replication offering and looking forward to hearing your feedback. By the way, many of these new features rely on using the latest and greatest version of CodeGen (5.4.8) which was also released today. If you’re already using an earlier version of the SQL Replication environment, or if you are interested in getting started and would like some assistance, don’t hesitate to contact us through your Synergex Account Representative.


Synergy DBL and Visual Studio Code

By Steve Ives, Posted on October 10, 2019 at 2:52 pm

Steve Ives

Some time ago a customer posted in the Synergy/DE Ideas forum suggesting that a Synergy DBL language plug-in should be created for the increasingly popular Visual Studio Code editor. Over course of the next few months the post received a significant number of votes, and we also started hearing the same request from others.

Later we heard from the original customer that they had started to define some basic language integration themselves, offered to share that initial code, and agreed that it could be open sourced.

At this time we are pleased to announce that initial support for DBL in VS Code is live! We have developed this functionality as an open source project on GitHub (https://github.com/Synergex/vscode-synergydbl) and welcome your feedback and your contributions.

If you just want to try the extension you can search for “Synergy” in the extension marketplace inside of VS Code, or download and install the VSIX from the GitHub Releases page. If you do try the extension out, and have questions or problems, please use the GitHub Issues page to let us know.

The initial scope of the extension is fairly limited, but we have been using the colorization locally for a while now and it makes a huge difference when you just need to do a quick edit to a source file. We are looking forward to seeing what everyone else has to contribute.


Don't miss a post!

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Recent Posts Categories Tag Cloud Archives