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

Did you run the regserver powershell script for HOPEX ? 

 

script to execute : HOPEX-regserver.ps1

Default location : C:\...\HOPEX Application Server\5000

 

  • Is there any error in the Windows Event Application Error ?
  • Was another version of HOPEX already installed ?

alaaeid
MEGA Partner
MEGA Partner

Hello,

 

I'm trying to follow the steps described here on V5 CP3. What i've done is the following :

  1. downloaded the generator from github and transferred the required files to "C:\temp\java".
  2. modified run.bat to :
    1. run the correct java version under .shadowfiles -> hopex.core -> etc. 
    2. environment paths specified to use "Hopex Application Server\Databases\<Port>\Environment\" is empty, so i used the path of the environment found on administration such as "C:\ProgramData\MEGA\Hopex Application Server\5004\Repos\BBYNEADEV"
    3. modified the repo from SOHO to Dev
  3. I had created a metamodel and used its Absolute ID in a new entry within "00_SchemaToGenerate.json"

Running the "run.bat" returns an error "java.lang.reflect.InvocationTargetException" (i've attached the cmd screenshot).

having seen that there was a nullpointerexception at com.mega.generator.openHOPEX.<init>(OpenHOPEX.java:36) i've run the regserver.bat found at the root of the environment created, but error still persists.

 

GraphQL-Error.png

Hello,

 

When generating the schema the technical user must be in english. As a consequence the JSON file and exposed API will be named in english. 

 

We do not support generation of the JSON and API naming to be in another language. This is only at generation of the schema.

 

Once generated at runtime the data can be in any language.

 

To solve your problem, in the development environment the technical user must have GUI and Data in English. After the schema being generated you can put it back to your prefered language.

 

 

 

engeh
Super Contributor

Hi Oliver

 

Thank you for your instruction post.

I'm trying to extract our custom Metamodel as a Schema and I'm getting following error: 

engeh_0-1620825712867.png

Do you now, where I can change the settings for the expected language? Because we want to keep the language for mega in german.

 

Kind regards

 

Hendrik

RGenin
Trusted Contributor

Hi Olivier,

1/
Thank you for your very detail explenation in both answers.

2/
We will investigate the different causes you pointed out.
I will also send you a private msg.

3/
Thanks !

Raphaël.

 

For your point 1 :

 

I have explained the general case and show the particular case in previous post. You have many example in all MetaModel diagram provided in the MGL. Remember just put all abstract MEtaClass, MetaAssociation and their concrete version of it in the diagram to see them appear in the JSON generated.

 

For your point 2 :

I have made the test of this example above in V4 CP1 and didn't get such error.

 

it may be cause by :

  • not well reference HOPEX in the Windows registry
  • not the right JAVA version used by the generator. I recommend that you point toward the one shipped with the tool
  • missing library (Jar) somewhere in the genrator or JVM you use.
  • badly configured 00_SchemaToGenerate.json. I recommend you remove everything your don't need or set everything to false except what you need. 
  • In your case an issue with the name of your environment as the line generating the error is about getting the name of the environment. Can you share in a private message a screenshot of the name of your environment ?

 

Four your point 3 :

The point is taken and we will adjust in future release. Please note that this diagram as given as example. The naming has no impact on the generated JSON nor the rules of the generator.

 

 

 

 

 

Hello,

 

The generator can read the abstract MetaModel and generate a concrete version of it.

 

The general rule

 

For instance, when you want to expose :

  • an "abstract" MetaAssociation
  • a concrete MetaAssociation between two abstract MetaClass you need to put them in the Diagram that the generator will use.

 

The prereuiqisite for that to work is to put in the metamodel diagram all the elements you neeed :

  • the concrete MetaAssociation
  • the concrete Metaclass : on both side
  • the abstract MetaClass when needed where the MetaAssociation is related

 

Launch the generator and you will see the path appear in both MetaClass.

 

You particular case 

 

  1. First step create a Metamodel and a MetaModel diagram that you open.
  2. From the "explorer" (of the object Library in your case) you can navigate to the MetaModel behind by selecting "explore MetaConcept".

access_metamodel_metaassociation.png

 

  • In the newly opened explorer unfold both MetaClass target of the MetaAssociation
  • Drag and drop them in the diagram (or put them in your prefered way in the diagram)
  • Add on this diagram the concrete MetaClass : Library and Org-unit
  • If the MetaAssociation was Abtract you should have place the concrete one. This is not the case in your example.

Result in your case 
diagram_metamodel.png

 

  • Dispatch your work and close HOPEX. Just keep somewhere the absolute identifier of the MetaModel you created before closing.
  • configure the generator with:
    • the absolute identifier of your Metamodel
    • All path of the file as explained in the readme of the generator
    • Give a name to the JSON to generate.
  • Launch the generator

 

config_generator.pnggenerator.png

 

 A file will be generated and will contains in this example :

  • Metaclass Library
  • MetaClass Org-Unit
  • Relationship between both
  • All MetaAttribute on both Metaclass

 

Please note that : the profile you use must see the Metaclass and Metaassociation as confidentiality and profiles rights will be applied when generated the schema.

 

In you case here is the result of the JSON generated. Attached as well the full JSON.

json_generated.png

 

 

 

 

 

 

 

 

 

RGenin
Trusted Contributor

Hi Olivier, 

 

1/ I'm interested in this as well as I have a similar question then @soemyatmyat .

 

2/ We have a problem in executing the bat file (Test Env, Hopex V4CP1HF1 (9.00.5627.5639)), downloading the last masterfile from github.

RGenin_1-1603319111656.png

 

3/ Would it be possible to standardize/ the included mrg file ?

 

00 - Web service Technical => 00 - Webservice Technical (so it matches the other 2)

00 - Web service extracat Workflow => 00 - Webservice extract Workflow

00 - Web service extract MetaModel => 00 - Webservice extract MetaModel

00 - Web service extract Reporting => 00 - Webservice extract Reporting

1 Data (web service extract) => Data (web service extract)

RGenin_2-1603319385893.png

 

 

Thanks !

Raphaël.

 

soemyatmyat
Retired

Hi Olivier,

 

Thank you for this instruction post. I was able to extend the schema to include custom attributes! Thank you!

The question I have now is for Abstract metaclass association.

For instance, there is a need to publish Org Unit > Library in the schema but Org-Unit to library is not a direct association, rather, it's the association link inherited from abstract metaclass. In such case, how do we publish this link in schema? I tried adding in the abstract metaclass in the metamodel but generator doesn't seem to be exposing abstract classes into schema. Is there any solution or workaround for this?

 

Library of Org-Unit

soemyatmyat_0-1603026549389.png

 

 

The association link: Owner Architecture Container > Building Block in Scope

soemyatmyat_1-1603026607614.png