This section is focused on explaining principles of using General BECS graphQL Service and its sample usage in BECS integration project, describing it in two major subsections:​​​​​​​

1 General BECS graphQL Service principle​​​​​​​
2 How to use General BECS REST API Service in the project

graphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your data. graphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.

A graphQL service is created by defining types and fields on those types, then providing functions for each field on each type. For example, a graphQL service that tells you who the logged in user is (me) as well as that user's name might look like this:

type Query {

me: User

}

typ^{​​​​​​​}e User {

id: ID

name: String

}

Along with functions for each field on each type:

function Query_me(request) {

return request.auth.user;

}

function User_name(user) {

return user.getName();

}

After a graphQL service is running (typically at a URL on a web service), it can receive graphQL queries to validate and execute. The service first checks a query to ensure it only refers to the types and fields defined, and then runs the provided functions to produce a result.

For example, the query:

{

me {

name

}

}

Could produce the following JSON result:

{

"me": {

"name": "Luke Skywalker"

}

}

BECS is open and very powerful platform used in wide range of industrial areas and business scenarios. To increase possibility of using BECS we hardly working also on adaptation of different standards for communication and keep the flexibility and power of BECS integration Visual Modeling unchanged.

General BECS graphQL Service layer was designed as another general way how to start integration via REST API call for any integration project (after adaptation of standard REST, SOAP and graphQL).

BECS graphQL Service is the layer for using graphQL queries to retrieve BECS enabled/integrated data from any BECS integration solution.

Please do not forget, that BECS is driven by integration visual projects (called BECS Integration Project or BECS IP). The major reason of adapting graphQL Service layer is to enable using of any standard BECS IP also via graphQL channel (request/response).

This will allow to integrate with any graphQL compliant system easily and use full power of BECS projects and connectors as well.

In following picture, you can see the global architecture of BECS graphQL Service and its cooperation with standard BECS IP. Schema shows standard flow for graphQL requestor:

To minimize duplicity in presenting samples will be always used endpoint:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/graphql 

​​​​​​​

1.2.3.2 Payload format

BECS graphQL Service supports both possible payload format (XML, JSON).

 

​​​​​​​1.2.3.2.1 Default format

Based on graphQL Service specification, graphQL always return json format (can be converted after by standard BECS tools):

Request: 

Response (json):

 

1.2.3.3 Metadata retrieve

1.2.3.3.1 Basic metadata

Standard graphQL syntax does not have any directive for metadata retrieve (similar to directive $metadata in OData…). There is expected that end user knows actual object syntax.

 

1.2.3.4 Data retrieve

1.2.3.4.1 Simple Data Request

As defined in graphQL standards also BECS graphQL Service returned data via simple query request:

Please be aware, that Service EndPoint depends on machine where the service is installed, so it needs to be changed to proper architecture every time!

Request:

Response:

 

1.2.3.4.2 Field selection

For retrieving only selected fields can be used list of requested columns in original query request.

Request:

query{Customers

{CompanyName

CustomerID

ContactName

Address

City

Phone

Fax}}​​​​​​​​​​​​​​

Response:

 

1.2.3.4.3 Data filtering Request

As defined in graphQL standards also BECS graphQL Service supports filtering by any column from table.

By placing filtering condition in brackets after the data object name, BECS graphQL Service will return filtered data.

Request:

query{Customers (where: {CustomerID: {eq: "ANATR"}})

{CompanyName

CustomerID

ContactName

Address

City

Phone

Fax}}

Response:

 

​​​​​​​1.2.3.4.4 Data linking Request

As defined in graphQL standards also BECS graphQL Service supports easy linkage of data objects.

For example, showing also all sales orders for selected customer (ANATR) use following query:

Request:

query{Customers

(where: {CustomerID: {eq: "ANATR"}}) 

{Orders {OrderId

                          CustomerID

                          EmployeeID

                          ShipName

                          ShipAddress

                          ShipCity

                          ShipCountry}}}

Response:

​​​​​​​

1.2.3.4.5 Sort Orders

As defined in graphQL standards also BECS graphQL Service supports ASC and DESC sort order options.

For example, let’s show the countries using operator (gt:”Spain”) with ascending countries and descending cities at the same time:

Request:

query{customers (where:{Country {gt: "Spain"}} order:{Country:ASC,City:DESC})

{Country

City 

CustomerID 

CompanyName}}​​​​​​​

Response:

 

1.2.3.4.6 Comparison operators

As defined in graphQL standards also BECS graphQL Service supports comparison operators’ usage: eq (=), lt (<), gt (>).

For example, let’s show also all customers where Customer ID is greater than “ANTON” use following query:

Request:

query{Customers (where:{ CustomerID: {gt: "ANTON"}})

{CompanyName

CustomerID

ContactName

Address

City

Phone

Fax}}​​​​​​​

Response:

 

1.2.3.4.7 Data Paging

To support records sub-selection can be used following directives:

1.2.3.4.7.1 Directive “first”

For returning only FIRST x records is possible to use directive “first” – for example return of first 4 Customers:

Request:

query{Customers(first: 4 

order:{ CustomerID: ASC})

{CompanyName   

CustomerID

ContactName

ContactTitle

City }}

Response:

 

1.2.3.4.7.2​​​​​​​ Directive “offset”

For starting from defined record is possible to use directive “offset” – for example return of top 4 Customers, but skip the first three (=start from fourth):

Request:

query{Customers (first: 4 offset: 3

order:{CustomerID: ASC}) 

{CompanyName 

CustomerID

ContactName

ContactTitle

City}}​​​​​​​

Response:

 

2 How to use General BECS REST API Service in the project

​​​​​​2.1 General intro

Based on general architecture diagram listed in chapter 1.2.2 General architecture of BECS graphQL Service is possible to call any BECS project.

 

2.2 Sample of calling

In this sample of calling, we used endpoint:

https://uks-dev-becs.bentley.com/BECS_Odata/api/graphql/V-301

For example, calling Equipment from SAP PM module via BECS we used:

(NOTE: SAP language table field is set in BECS project to English: SPRAS = ‘E’)

Request:

query{DATA_SAP_EQUI_Data

      {EQUNR

       EQTYP

       EQART

       INVNR

       GROES

       BRGEW

       GEWEI

       ANSDT

       ANSWT

       WAERS

       GWLDT

       HERST

       HERLD

       SERGE

       TYPBZ

       BAUJJ

       BAUMM

       OBJNR

       IWERK

       EQKTX

       TPLNR

       ABCKZ

       SWERK

       GSBER

       KOKRS

       BUKRS

       RUN_GUID}}

Response:

To call the same Equipment with related Work Orders from SAP PM module via BECS we used:

Request:

query{DATA_SAP_EQUI_Data{

      EQUNR

      EQTYP

      EQART

      INVNR

      GROES

      BRGEW

      GEWEI

      ANSDT

      ANSWT

      WAERS

      GWLDT

      HERST

      HERLD

      SERGE

      TYPBZ

      BAUJJ

      BAUMM

      OBJNR

      IWERK

      EQKTX

      TPLNR

      ABCKZ

      SWERK

      GSBER

      KOKRS

      BUKRS

      RUN_GUID

      ​​DATA_SAP_WorkOrderData{

ORDERID

        ORDER_TYPE

        CURRENCY

        CURRENCY_ISO

        ENTERED_BY

        ENTER_DATE

        SHORT_TEXT

        PLANT

        BUS_AREA

        ABCINDIC

        SORTFIELD

        PRIORITY

        EQUIPMENT

        PLANPLANT

        PLANGROUP

        MN_WK_CTR

        MN_WK_PLANT

        CUSTOMER

        MAINTPLANT

        FUNCLOC

        FINISH_DATE

        START_DATE

        NOTIF_NO

        EQUIDESCR

        FUNCLDESCR

        RUN_GUID

        RowID}}}

Response: