Repository Setup
Before code can be generated for a Harmony Core web service, you must have a Synergy repository that describes record layouts and files for your data. CodeGen uses information in the repository to generate web service code. The repository must contain the following:
-
STRUCTURE definitions (record layouts) associated with the data files that your API will expose. See Defining Structures below for more information, and make sure the following are defined for each structure
- Field definitions. See Defining Fields below.
- Key definitions (ISAM files only). See Defining Keys below.
- Relation definitions (ISAM files only). See Defining Relations below. These are optional, but they enable OData expansion support.
- Tag definitions (for ISAM files with multiple record types). See Defining Tags below.
-
FILE definitions for all data files to be exposed via your API. See Defining Files below, and note that each file definition must include a file specification (open filename), which generally includes a logical to determine the location of the file.
If your repository is set up for xfODBC access, it may be nearly ready for Harmony Core. See Setting up a repository in the Synergy/DE documentation for basic setup information.
Structures for data that will be exposed via Harmony Core must be declared as type DBL ISAM or RELATIVE. (Structures defined as ASCII or USER DEFINED are not currently supported.)
Each ISAM structure must have a primary key. Relative structures will automatically have virtual keys named RecordNumber (int) defined in generated data model classes.
For information on defining structures, see Defining a new structure in the Synergy/DE documentation.
By default, enabled operation endpoints are available for all structures exposed via Harmony Core. (Operation endpoints are enabled/disabled by setting options in regent.bat; see Code Generation Batch File (regen.bat).) For example, if the POST operation is enabled (via ENABLE_POST in regen.bat), all exposed structures will have a POST endpoint.
You can override this behavior for a specific structure by adding one or more of the following tokens to the structure’s user-defined text string or long description:
NO_ALTERNATE_KEY_ENDPOINTS
NO_DELETE_ENDPOINT
NO_GET_ENDPOINT
NO_GET_ALL_ENDPOINT
NO_PATCH_ENDPOINT
NO_POST_ENDPOINT
NO_PROPERTY_ENDPOINTS
NO_PUT_ENDPOINT
This causes the specified type of endpoint to be excluded from the controller that is generated for the structure, or in some cases (e.g. for property endpoints) prevents the generation of certain additional partial controller class source files.
Note that there is no mechanism for suppressing partial key endpoints on a structure-by-structure basis, because those endpoints must be explicitly enabled on a structure-by-structure basis.
S/DE Repository supports a large amount of field metadata, but most of it applies only to UI Toolkit applications. For Harmony Core, you need to define only the following field attributes:
- Field name and description
- Data type and size, as well as precision for implied decimal fields
- Array dimensions for array fields
- Required flag if you want the field to be required for POST and PUSH operations—i.e., if you want the corresponding property to be attributed with
{Required}(see Microsoft’s documentation for the RequiredAttribute class for System.ComponentModel.dataannotations) - Read-only flag (optional), which causes the set method for the corresponding property to throw an exception if used
See Working with fields in the Synergy/DE documentation for more information on specifying these field attributes.
By default, CodeGen excludes overlay fields when processing structures. So by default only non-overlay fields are exposed as data model class properties, and only real fields are usable as key segments.
If a structure includes overlay fields that must be exposed as model class properties, or if overlay fields are used to define key segments, remove the comment (rem) from the ENABLE_OVERLAYS option in regen.bat to include overlay fields in generated model and metadata classes. See Code Generation Batch File (regen.bat) for more information.
NOTE: Use the ENABLE_OVERLAYS option only when necessary. Exposing overlays exposes parts of the underlying record in more than one property, which is not a good practice. Before enabling overlays, consider reorganizing structures so that overlays are not necessary.
If you wish to prevent a particular field from being exposed via Harmony Core endpoints, add the text HARMONY_EXCLUDE to the field's long description.
NOTE: Do not exclude fields that are used as key segments.
If a decimal or implied decimal field has a display format string, you can expose the field as a formatted string property instead of the actual numeric value by adding the text HARMONY_AS_STRING to the field's long description.
If you intend to enable user authentication or authorization for your API, you can restrict the visibility of individual fields:
- Enable the
ENABLE_AUTHENTICATIONandENABLE_FIELD_SECURITYcode generation options regen.bat. (See Code Generation Batch File (regen.bat).) Field visibility restrictions are effective only if bothENABLE_AUTHENTICATIONandENABLE_FIELD_SECURITYare enabled. - Do one of the following:
- To restrict the visibility of a field to only authenticated users, add the text
HARMONY_AUTHENTICATEto the field's long description. - To restrict the visibility of a field to only authenticated users who are members of one or more roles, add the text
HARMONY_ROLES=role1,role2;to the field's long description.
- To restrict the visibility of a field to only authenticated users, add the text
See Field Security for details on Harmony Core's support for this.
You can add example data that will be used when generating Postman tests for your Harmony Core API. To do this, add the following to the field's long description.
SAMLE_DATA=some_data;
where some_data is the data you want to be used in Postman as example data for the field.
Key definitions in repository structures must be defined in the correct sequence. See Defining keys in the Synergy/DE documentation, and note the following:
-
Define all access keys before defining any foreign keys. Define the primary key first and then the first alternate key, the second alternate key, and so forth.
-
Specify the key of reference for each key.
-
Do not use an overlay to define multiple segments.
-
For segments, provide segment type and order information.
Keep in mind that key names are used when naming relationships, so use meaningful names.
When tags are used (to identify different records in files with multiple record types), the key targeted in the "to" structure typically includes the tag as the first field in the key, but the source key in the "from" structure typically does not include the tag character. If this is the case in your repository, you must add a foreign key to enable Harmony Core to traverse these structures in both directions. This foreign key must include the tag value as a literal segment followed by the segment(s) of the key being targeted in the "to" structure. There are two recommended naming conventions for this:
-
Name the foreign key "FK_" followed by the name of the access key related to the same segment(s) in the "from" structure.
-
Name the foreign key "FK_" followed by any arbitrary name. Then enter the name of the associated access key in the description field for the foreign key.
Once you’ve created the foreign key, create relations for each direction. (See Defining Relations below.)
Imagine an ORDER file where the primary key is the literal value "O" followed by a D8 order number. Items for the order are stored in an ORDER_LINE file where the primary key is the literal value "L" followed by a D8 order number and a D3 line item number. Additionally, assume the following:
- The primary key on the ORDER structure is named ORDER_NUMBER and has two segments: an A1 field representing the tag value "O" for each record, and a D8 field representing the order number.
- The primary key in the ORDER_LINE structure is named ORDER_LINE and is similarly defined, but with three segments: an A1 field containing the tag value "L" for each record, a D8 field representing the order number, and a D3 field representing the line item number.
Despite the fact that keys are present in both structures in this example, the tag prefix fields prevents these keys from being used for both relations between the structures (from ORDER to ORDER_LINE and from ORDER_LINE to ORDER).
To resolve this for Harmony Core, we would define two foreign keys, one in each structure:
- We could name the foreign key in the ORDER structure FK_ORDER_NUMBER because the access key is named ORDER_NUMBER. It would contain two segments: a literal value "L" and a D8 field representing the order number. This key would provide for a one-to-many partial key match in the ORDER_LINE file that identifies all ORDER_LINE records for a single ORDER record.
- We could name the foreign key in the ORDER_LINE structure FK_ORDER_LINE (because the access key is named ORDER_LINE). It would contain two segments: a literal value "O" and a D8 field representing the order number. This key would provide for a one-to-one key match in the ORDER file that identifies the ORDER record associated with each ORDER_LINE record.
We would then use these foreign keys to define relations between the two structures.
For Harmony Core, this becomes a “one to many to one” relationship, which is a type D relationship (see Harmony Core Relation Types below). One ORDER can have multiple ORDER_LINE records, each of which has one associated ORDER record.
By default, when attempting to assign multiple structures to a single file definition repository compares individual key segments and looks for an exact match in the number and size of key segments, as well as a match in the overall length of the key.
In some cases developers define structures with the same overall key length, but with different structures. By default repository will not allow such differing structures to be assigned to a single file definition.
In Synergy 11 a work-around to this situation was implemented in Repository. By setting the undocumented (until now) environment variable RPS_DONT_COMPARE_SEGS to any value, repository will then only consider the overall length of keys.
Defining relations is not mandatory for Harmony Core, but much of the power of OData queries depends on the ability to "drill down" into related data, and this feature is available only if relationships are defined in the repository. For example, with the sample data included in the HarmonyCore project template, relations are required to retrieve a list of customers and their orders.
A relation is defined by associating a key in one structure with a key in another structure. If there is a logical relationship in your data but a key required to define the relation is missing, add a foreign key. A foreign key is a virtual key that exists only to define a relationship to a key in another structure (i.e., there is no corresponding key in the data file). See Defining keys in the Synergy/DE documentation for more information.
Note the following:
- For information on defining relations, see Defining relations between structures in the Synergy/DE documentation.
- If you define foreign keys, make sure they are defined after any real (access) keys are defined.
- When defining relations, keep in mind which structures are used for code generation. For a relation to be usable, the structure that the relation targets must also be used for code generation, and the code must be generated at the same time (in the same run of CodeGen). If you split code generation into multiple CodeGen tasks, make sure all structures with relationships are processed at the same time. The CodeGen templates for Harmony Core are configured so that a relation will be ignored if code is not currently being generated for the structure it targets.
- You can customize relation names, types, and backlinks by specifying them in the HarmonyCoreCustomization.json file. Settings in this file override repository settings. See Harmony Core Customization File.
- For information on creating relations for structures with tags, see Defining Keys When Tags Are Present above.
With Harmony Core, there are five types of relationships between data structures. In comments in generated model files (.dbl), these types are represented by letters. For example, the letter A is used for “many to one to many” relationships.
Many records in the "from" file are associated with a single record in the "to" file and vice versa.
Each record in the "from” file is associated with one record in the "to” file and vice versa.
Each record in the "from” file is associated with one record in the "to” file, but there is no reverse relationship.
Each record in the "from” file is associated with one or more records in the "to” file and vice versa.
Each record in the "from" file is associated with one or more records in the "to" file, but there is no reverse relationship.
Tags distinguish structures in files with multiple record types. If you have a file with multiple record types, you must define a separate structure for each record type, and each structure must include a tag expression. In most cases, there is a field that is common to all the structures, and that field's value identifies the record type. The following is a typical tag expression:
RECORD_TYPE .EQ. "A"
For more information, see Defining tags in the Synergy/DE documentation.
As with fields, only minimal information is needed for file definitions for Harmony Core. You must provide a name, a description, and the "open filename", which is the file specification of the Synergy data file to be opened. See Defining files in the Synergy/DE documentation for more information.
It is important that “open filename” contain a full file specification. This generally includes a logical name that defines the location of the file. For example:
DAT:customer.ism
If your repository does not contain actual file specifications (perhaps because you have multiple data sets and need to determine the actual file specification at runtime), you will need to provide custom code to resolve “open filename”, and you will need to implement support for multitenancy. See Custom File Specs and Multitenancy for more information.
Next topic: SSL Certificate