cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

Create custom schema (SDL/JSON) / custom endpoint

oguimard
Retired

 

The GraphQL REST API exposes in standard a subset of the full HOPEX Metamodel. This subset is organized into several endpoint represented by a schema (SDL). The split is mainly done by solution scope or technical grouping: ITPM, BPA, Audit…

 

It is possible to extend the delivered schema or to create new schema. The result of this customization will end up with a new endpoint to call by HTTP request.

 

 

How it works ?

 

General principle

 

To create a schema we need to convert the HOPEX Metamodel into a GraphQL syntax compatible. This mapping is done through a JSON file that maps the HOPEX ID with a naming convention compatible with GraphQL. From this file the system generates a GraphQL syntax. The default JSON mapping schema are installed in the CONFIG folder of the HOPEX installation. For instance in HOPEX V4 :

 

 

C:\Program Files (x86)\MEGA\HOPEX V4\DotNet\hopex.graphql\1.0.0.0\CONFIG\V3\Standard

 

 

Moreover, in the web part a key in the web.config exposes the list of available schema.

 

 

<add key="GraphQLSchemas" value="ITPM, Assessment, Audit, BPA, Data, DataPrivacy, MetaModel, Reporting, Risk, Workflow"/>
<!--      GraphQLSchema-->

 

 

 

In this example we see that there are several schema about: ITPM, Assessment, Audit…

 

Within this JSON file the metamodel in terms of MetaClass, MetaAttribute, MetaAttributesValue, MetaAssociation.

 

Here is an extract of a JSON mapping schema for ITPM :

 

 

...
"metaclass": [{
"id": "MrUiM9B5iyM0",
"name": "Application",
"description": "An application is a software component that can be deployed and provides users with a set of functionalities.",
...
"properties": [{
"id": "Z20000000D60",
"name": "Name",
"description": "Short Name of the object ...",
"constraints": {
"type": "String",
"mandatory": true,
"maxLength": "1024",
"readOnly": false,
"translatable": true,
"formattedText": false
}}],
"relationships": [
{
"id": "7ChrtiDo4vb0_YChrYpDo4ri0_MrUiM9B5iyM0",
"name": "TimePeriod",
...
"pathToTarget": [
{
	"id": "VChrYpDo4fi0",
	"name": "TimeDependentObjectTimePeriod",
	"maeName": "PeriodOfValidity",
	"maeID": "YChrYpDo4ri0",
	"metaClassName": "TimePeriod",
	"metaClassID": "7ChrtiDo4vb0",
	"multiplicity": "*"
}]}]
...

 

 

 

See attached ITPM file for full JSON.

jsonITPM.png

 

Creating/updating a schema

 

To create your own schema you can:

  • Create a totally new schema

In this situation you are free to define what is exposed and you will not be impacted by future updates of the API.

  • Extend an existing schema.

This limits the customization to be performed but you will benefit from future updates of the default delivered schema..

 

In both cases the principle is the same. You need to create a custom JSON file that you will put in the custom folder

 

 

C:\Program Files (x86)\MEGA\HOPEX V4\DotNet\hopex.graphql\1.0.0.0\CONFIG\V3\Custom

 

 

In case of a new JSON the name of the schema must be added in the web.config

 

Step 1 : Create your metamodel to expose in the REST API

 

The JSON delivered out of the box have been generated by a java program that reads a diagram of metamodel. To generate a schema JSON you can use the same tool on existing metamodel diagram or with your new metamodel diagram.

 

Custom Metamodel

  1. Open HOPEX windows desktop client
  2. In MetaStudio tab create a new Metamodel
  3. Add a new diagram for this metamodel.
  4. Put the piece of the metamodel you want.
  5. Copy and keep for later the absolute identifier of the metamodel object

metamodel.png

 

Complete default metamodel

Should you want to complete the default schema with additional MetaClass, MetaAttribute... follow the steps below :

  1. Import the MGL file located in "MGL" folder
  2. Duplicate the standard Metamodel and diagram you want to complete
  3. Put the piece of metamodel you want.
  4. Copy and keep for later the absolute identifier of the metamodel object

 

Important rules

This generator apply the following rules :

  • Only concrete metamodel is generated
  • MetaAssociation must be in the diagram to be generated, including the abstract version of the MetaAssociation.

 

Step 2 : Configure the generator

 

Download the generator from gitHub. In this example all the files will be moved to the destination folder

 

 

C:\temp\java

 

 

 

. You can adjust according to your case.

  • From folder "EXE" copy paste the files to the destination folder :
    • generatorJSONMapping.jar
    • run.bat
  • From folder "JSON" copy paste the files to the destination folder :
    • 00_OverrideName_Global.JSON
    • 00_SchemaToGenerate.json
  • Open the "00_SchemaToGenerate.json" to add your schema. Past the absolute identifier you have saved from previous step.
  • Edit the included section to false to avoid to generate the other schema.

 

Example of "00_SchemaToGenerate.json" :

 

 

{
"included": "true",
"schemaName": "ITPM",
"metaModelAbsoluteIdentifier": "TeEKeRMmSPYK",
"login": "Tibere",
"password": "Hopex",
"profile": "ITPM Functional Administrator"
},

 

 

 

  • Login, password, and profile should reflect the restriction of metamodel you want to apply to the API. If you don't know which profile put 'HOPEX Customizer'. Access right will be read at runtime.

folders.png

 

Step 3 : Run the generator

Before running the generator edit the file 'run.bat' to adjust :

  • folders location : HOPEX, log, config file
  • environment path
  • repository name
  • debug option (-d)

To run the program, execute the run.bat file. In case of success the message appears in the console.

 

Processing the request may take a while : between 30 to 45 min... Be patient! Depending on the complexity of the metamodel.

 

Example of console message in debug :

 

 

[2020-09-14 08:35:21] [CONFIG ] debug                   = true
[2020-09-14 08:35:21] [CONFIG ] verbose                 = false
[2020-09-14 08:35:21] [CONFIG ] Folder                  = c:\temp\java\
[2020-09-14 08:35:21] [CONFIG ] Log Folder              = c:\temp\java\
[2020-09-14 08:35:21] [CONFIG ] File Name Override      = 00_OverrideName_Global.JSON
[2020-09-14 08:35:21] [CONFIG ] File Name Schema        = 00_SchemaToGenerate.JSON
[2020-09-14 08:35:21] [CONFIG ] Environment             = C:\Users\Public\Documents\HOPEX V4\PRESALESV4
[2020-09-14 08:35:21] [CONFIG ] Repository              = SOHO
[2020-09-14 08:35:21] [INFOS  ] Read schema name
[2020-09-14 08:35:22] [INFOS  ] ########### Starting ###########
[2020-09-14 08:35:22] [INFOS  ] ########## Starting : Custom
[2020-09-14 08:35:22] [INFOS  ] Open HOPEX
[2020-09-14 08:35:29] [INFOS  ] Open Session
[2020-09-14 08:35:29] [INFOS  ] sAdministrator: Mega - sPassword: *****
[2020-09-14 08:35:30] [INFOS  ] Read overRideName JSON
[2020-09-14 08:35:30] [INFOS  ] Creating JSON
[2020-09-14 08:35:30] [INFOS  ] Start Metaclass
[2020-09-14 08:35:32] [INFOS  ] Size = 1
[2020-09-14 08:35:33] [INFOS  ] MetaClass = Application
[2020-09-14 08:36:01] [INFOS  ] Starting Reverse Id
[2020-09-14 08:36:01] [INFOS  ] Start Interfaces
[2020-09-14 08:36:01] [INFOS  ] Wrting filec:\temp\java\SBB.JSON
[2020-09-14 08:36:01] [INFOS  ] Write overRideName JSON
[2020-09-14 08:36:01] [INFOS  ] HOPEX Closed
[2020-09-14 08:36:01] [INFOS  ] ########### All done ###########

 

 

 

 

cmd.png

 

19 Replies

Hello,

The schema must be in english because many charecters in other language (including French) are not supported by GraphQL API.

You must ensure that all custom metamodel is then written in english are at least does not contains any special chararacters.

luc_pouech
Senior Member

Hello Olivier,

I am trying to generate a custom schema (SDL/JSON) but I face an issue concerning language. My environment is in FRENCH so the generator exits with this error:

[2023-07-12 10:34:07] [INFOS ] ########## Starting : ACOSS
[2023-07-12 10:34:07] [INFOS ] Open HOPEX
[2023-07-12 10:34:10] [INFOS ] Open Session
[2023-07-12 10:34:10] [INFOS ] sAdministrator: mega
[2023-07-12 10:34:12] [INFOS ] Language Name = Franþais
Exception in thread "main" java.lang.Exception: Expected language English (00(6wlHmk400) current value :Franþais (ID = B0SNPuLckCQ3)
at com.mega.generator.OpenHOPEX.<init>(OpenHOPEX.java:75)
at com.mega.generator.Generator.generateMetaModel(Generator.java:104)
at com.mega.generator.Generator.main(Generator.java:74)

I switched my environment to ENGLISH and the generator runs fine (a file is produced).

However, as only FRENCH names and definitions are set in the environment, some elements end up with automatic names like "1MetaAttribute48Enum". These names create an error in GraphiQL:

{
"Error": "A type name must match /^[_a-zA-Z][_a-zA-Z0-9]*$/ but '1MetaAttribute48Enum' does not.\r\nNom du paramètre : name"
}

The environment is heavily customized so adding english names for all metaclasses, metattributes, metattributesvalues, metassociationends, etc... is not really an option.

I am wondering if it would be possible to run the generator on another language than english.

Hello,

The out of the box schema can be seen here : https://github.com/mega-international/graphql-rest-api/tree/master/GeneratorMappingJSON/V3/02%20-%20...

Theses concepts are not proposed in the out-of-the-box schema.

 

 

 

jeromePE
New Contributor

Bonjour,

"The GraphQL REST API exposes in standard a subset of the full HOPEX Metamodel."

J'aimerais savoir si les zones d'urbanisme font partie du sous-ensemble et si oui, de quel "endpoint" ou solution elles relèvent ?

Merci pour votre éclairage

Hello,

Go to the HAS Console in Module Settings >> GraphQL IDE Settings   add your new schema

 

oguimard_0-1664895824910.png

 

oguimard_1-1664895842111.png

 

 

Hi Olivier,

 

The documentation in the .MD files is a little sparse.

I placed the extension file here:

C:\ProgramData\MEGA\Hopex Application Server\5002\.shadowFiles\has.custom\...\hopex.graphql\CONFIG\V5\Custom

(note there is only one environment in 5002)

 

When I go to graphiQL, the new schema is not available.

 

In V4 there was an extra step to add the name of the schema in web.config, is this what I am missing, or is it something else?

 

 

 

Hello,

 

You can reuse schema from previous V3/V4 on the V5.

 

In V5 all custom files need to be placed in the custom module; Download the module here and follow the HOW-TO instruction https://store.mega.com/modules/details/has.custom

 

Place your file here : C:\...\HOPEX Application Server\...\has.custom\...\hopex.graphql\CONFIG

 

 

 

 

dp
MEGA Partner
MEGA Partner

The documentation here, doesn't seem to be applicable for V5.

As part of an upgrade i want to move my custom Schema from V4 to V5.

However the following filepath does not exist on V5:

C:\Program Files (x86)\MEGA\HOPEX V4\DotNet\hopex.graphql\1.0.0.0\CONFIG\V3\Standard

I can't locate the web.config for GraphQL either, in order to add the schema.

-

Two questions:

1: How do I add a custom schema in V5?
2: Can i reuse a schema from V4, or would it have to be generated again in V5?

Hello,

 

How do you run the script ?

  1. by opening Powershell ISE ? You need to be careful of the folder written in the blue section of the script 
  2. right click on the file HOPEX-regserver.ps1 You need to make sure you have enough righ to execute powershell script.

oguimard_1-1661184697276.png

oguimard_0-1661184624607.png

 

alaaeid
Super Contributor

Hello Oliver, first thank you for your response man and hope you're doing well.

on the environment i'm currently testing on there are several hopex instances running  ( total count is 4 ). they are all on V5 CP3 right now, no V4 instances were ever installed on the vm if that may be relevant.

Concerning the powershell script, running it encounters an error:

"The description for Event ID 2 from source HOPEX cannot be found. Either the component that raises this event is not installed on your local computer or the installation is corrupted. You can install or repair the component on the local computer."

 

sometimes restarting the server and running it, it would work only once.