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.
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
- Open HOPEX windows desktop client
- In MetaStudio tab create a new Metamodel
- Add a new diagram for this metamodel.
- Put the piece of the metamodel you want.
- Copy and keep for later the absolute identifier of the metamodel object
Complete default metamodel
Should you want to complete the default schema with additional MetaClass, MetaAttribute... follow the steps below :
- Import the MGL file located in "MGL" folder
- Duplicate the standard Metamodel and diagram you want to complete
- Put the piece of metamodel you want.
- 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.
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 ###########
Hello,
I'm trying to follow the steps described here on V5 CP3. What i've done is the following :
- downloaded the generator from github and transferred the required files to "C:\temp\java".
- modified run.bat to :
- run the correct java version under .shadowfiles -> hopex.core -> etc.
- 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"
- modified the repo from SOHO to Dev
- 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.
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:
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
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
- First step create a Metamodel and a MetaModel diagram that you open.
- From the "explorer" (of the object Library in your case) you can navigate to the MetaModel behind by selecting "explore MetaConcept".
- 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
- 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
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.
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.
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)
Thanks !
Raphaël.
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
The association link: Owner Architecture Container > Building Block in Scope
