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

GraphQL REST API

Highlighted
MEGA

GraphQL REST API

Extend HOPEX with REST API based on the GraphQL framework to query the repository.

 

Download latest release Add to my SaaS Instance

 

This add-on expose a catalog of REST API that can be queried following the GraphQL specification framework. The call to the API are made using JSON that contains the query to execute (query or mutation). The result of the call to the REST API is a JSON containing the data requested. With this add-on you can read and write data in the HOPEX repository.

When properly authenticated (UAS bearer) you will be able to get, for instance, the list of applications, business process, capabilities...and their fields and relationships. To ease navigation, different schemas are provided by solutions : ITPM, GDPR, Audit, BPA...

 

 

All the documentation of GraphQL is here : https://community.mega.com/t5/REST-API/bd-p/api

 

Example of query :

JSON Query JSON Response
query {
application {
id
name
}
}

{
"data": {
"application": [
{
"id": "rnRV)xNbQXB6",
"name": "Web portal"
}

] } }

 

 

Latest release date:

2020/06/22

Use for:

Production Platform

Lifecycle status: 

Under active development

Platform compatibility:

HOPEX V3 CP4 minimum

SaaS tickets : 

50

 

Dependencies:

.Net Framework 4.7 minimum

 

Licensing:

Free

 

Requirements:

You need to have functional licenses on the solution you want to query the REST API

 

Latest release notes:

  • Allow basics queries and mutations
  • support of cluster deployment
  • manage filter, order and pagination

 

Installation procedure:

  • Download the MSI
  • Launch and configure
    • URL (SSP and UAS)
    • Hopex Security Key
  • You can (optionally) enable GraphiQL to build query
    • set the environment, repository, profil, user and password
  • Verify it work by making your first query

 

Product Owner: @oguimard 

1 Reply
Highlighted
MEGA

Prerequisite :

  • UAS must be enabled and working
    • Test by connecting in the web front end with a user and ensure the URL goes through UAS.
  • The user must be HOPEX identified (login/password). It will not work with user in SSO
  • .Net Framework 4.7 minimum is required.

 

Most commonly seen issues of installation of GraphQL add-on on HOPEX V3 in order of appearance

 

.Net Framework is not correctly installed

Reason

    • The wrong version is installed
    • There is a conflict of .Net Framework version between Runtime and Developer version.

      

Symptoms :

    • The call to the API return a 500 error
    • The macro of the API cannot be launched
    • There is no log file “Macro” in folder Programdata\mega\logs

 

How to check :

  • Go in Windows control panel and check installed component.

 

How to fix :

  • Reinstalled .Net Framework

 

The application pool password of HOPEXAPIMWAS is not set correctly

 

Reason

    • The default MSI in V3 contains a bug that do not set properly the password.

 

       Symptoms :

  • The API return an 500 error
  • The application pool is automatically stopped after the first call to the API

 

How to check :

  • Go in IIS and check HOPEXAPIMWAS. If it is stopped that is the problem

oguimard_0-1595575015439.png

 

How to fix :

  • Set the Identity user again with the right password.

 

HOPEXGraphQL folder is IIS has not been converted to an application

 

Reason

    • Previous version of the setup did not convert in an IIS application.

 

       Symptoms :

  • The URL to call the API does not respond
  • A timeout error occurs when calling the API

 

How to check :

  • Go in IIS and check HOPEXAPIMWAS. If it is stopped that is the problem

oguimard_1-1595575015443.png

 

How to fix :

  • Convert to application the folder HOPEXGraphQL

 

I can login to HOPEX web front end after using the API

 

Reason

    • UAS url in web.config are case sensitive.
    • V2 and V3 setup do not set properly the UAS URL.

      

Symptoms :

    • Unable to login in web to HOPEX web front end

 

How to check :

  • Open all web.config located in wwwroot folder and ensure UAS is in capital letter.
  • Open MegaSite.ini and ensure UAS is in capital letter

 

How to fix :

  • Update UAS URL and restart all

 

HOPEX version is not compatible

 

Reason

    • Compatibility is limited to V3 CP4 onward and V4 onward
    • STS version are not supported.

 

       Symptoms :

  • The API return 500 error
  • Mutation in GraphQL are not saved

 

How to check :

  • Check HOPEX version in Administration.exe

 

How to fix :

  • Use only supported version

 

Impersonification user has not enough privilege to access the database or to launched the process

 

Reason

    • Client may set impersonification user with limited rights..

 

       Symptoms :

  • A 500 error occurs when calling the API
  • HOPEX process are not launched : spro, mwasapi

 

How to check :

  • In windows tasks manager check that the process : mgwmapp, mgwspro, mwgmwas are laucnhed with the personification user

 

How to fix :

  • Give the same right to bother impersonification users used for HOPEX and HOPEXAPI

 

Web.config of HOPEXGraphQL is not properly defined and prevent GraphiQL to work

 

Reason

    • The web config must be configured for :
      • Security key and URL
      • To use use GraphiQL

 

       Symptoms :

  • GraphiQL web front end does not work :
      • Either with a message
      • Either with an error and impossibility to display the page

 

How to check :

  • Go to web.config and ensure all parameters are properly set

 

How to fix :

  • Ensure the security key value is the same as in the web.config of HOPEX folder

 

  • To enable GraphQL ensure the following value is “true”. By default it is false.

    <add key="EnableTestingWebService" value="false" />

 

 

  • To enable GraphQL ensure all the ID are properly defined.

    <add key="ClientId" value="HopexAPI" />

    <!--      Client Id (used for basic authentication)-->

    <add key="ClientSecret" value="secret" />

    <!--      Client Secret (used for basic authentication)-->

    <add key="Scopes" value="hopex openid read write" />

    <!--      Scopes (used for basic authentication)-->

    <add key="EnvironmentId" value="EnvironmentIdAbs" />

    <!--      EnvironmentId-->

    <add key="RepositoryId" value="RepositoryIdAbs" />

    <!--      RepositoryId-->

    <add key="ProfileId" value="ProfileIdAbs" />

    <!--      ProfileId-->

    <add key="Login" value="HopexUser" />

    <!--      Login-->

    <add key="Password" value="HopexPassword" />

    <!--      Password-->

 

 

Getting a bearer works but I get a message a error as occured

 

Reason

Version of graphQL add-on issue in 2020 require the 2 following prerequisite :

  • The user must be in the highest level in the graph of data reading access. If your environment as Data Reading access enabled (not the case by default).
  • The following option must be set in the megaenv.ini

[Filter-Available]

rfDd5x976f30=1

 

       Symptoms :

  • A 500 error occurs when calling the API
  • The message say an error as occured
  • There is no log in the program data logs

 

How to fix :

  • add the key in the megaenv.ini
  • ensure the user is highest level Administrator and not standard which is the default

 

Commonly asked question :

 

  • Can the add-on work on HOPEX V2R1, V3.1 and V3.2 ?

No. It is compatible only with V3 CP4, CP5, CP6 and V4 onward

 

  • Can I secured the API with an API Key ?

No. The API is secured with

       ClientId and Client Secret

        Login/password/profile

 

  • Can The API work in cluster ?

Yes, only if UAS is properly configured in this deployment.