With GraphQL you are able to make query or mutation on object of the repository. When syncing with an external tool you may want to use the identifier of the other tool to create or connect object.
GraphQL provide 3 types of identifier :
- Absolute Identifier: this is the ID generated by HOPEX when a new object is created. The value cannot be set by the API. IT can be used when doing query to get the HOPEX unique identifier global.
- This field cannot be blank or null.
- This field is composed of 12 characters composed of letter and digit and special characters.
- This field is invariant overtime.
- External Identifier: this is an ID that can be given when a new object is created. The uniqueness is limited to the MetaClass for which you are creating an object. This ID is used when importing data from another system to be able to retrieve, at a later stage, the object created from this system.
- This field can be blank or null
- This field as a maximum length of 1024 characters
- This field is not invariant overtime
- Temporary Identifier: this is the same principal as the External Identifier. The main difference is that the validity of this ID is limited to the mutation you are doing. The information will not be store in the database and cannot be reused at a later stage.
Doing Query
Query can only be done on the Absolute Identifier shortly called "id" or the External Identifier shortly called "externalId". As the Temporary identifier is not physically stored it cannot be queried.
These 2 identifiers can be used to :
- Filter query
- Ensure that the retrieve object is the expected one
Sample query
- Example with a result that contains the identifiers
- Example with a query that contains a filter on the external identifier
| Query 1 |
Result 1 |
query AppID {
application {
id
externalId
name
}
}
|
{
"data": {
"application": [
{"id": "IubjeRlyFfT1", "externalId": "My ID App1", "name": "Account Management"},
{"id": "iSS7AQY6NrgU","externalId": "My ID App2","name": "Account Payable"
}
]
}
}
|
| Query 2 |
Result 2 |
query AppID {
application
(filter:{externalId_contains:"My ID"}) {
id
externalId
name
}
}
|
{
"data": {
"application": [
{"id": "IubjeRlyFfT1", "externalId": "My ID App1", "name": "Account Management"},
{"id": "iSS7AQY6NrgU","externalId": "My ID App2","name": "Account Payable"
}
]
}
}
|
Doing Mutation
Creation without an Identifier
The default behavior is to let the system give an absolute identifier to an object. The identifier is unique to the whole database of HOPEX. If you create several objects, even with the same characteristics, the identifier will be unique each time.
| Query |
Result |
mutation basicCreation {
createApplication(application:{
name:"my new app"
}) {
id
name
}
}
|
{
"data": {
"createApplication": {
"id": "magoMpShXLDE",
"name": "my new app"
}
}
}
|
Creation with an External Identifier
The only way to control the identifier is to use the External Identifier. When the object is created you can specify the value. This value is unique but limited to the MetaClass object you are creating. Moreover this external identifier is not invariant so you can modify it after the object was created.
CAUTION: the profile you use must be granted to right to read and write this MetaAttribute. This is not always the default right in standard HOPEX profile in V3 or V4.
| Query |
Result |
mutation basicCreation {
createApplication(id:"My ID App3"
idType:EXTERNAL
application:{
name:"my new app 3"
}) {
id
externalId
name
}
}
|
{
"data": {
"createApplication": {
"id": "RcgoRyShXXFE",
"externalId": "My ID App3",
"name": "my new app 3"
}
}
}
|
Should you want to update the External Identifier you need to first query the object with the Absolute Identifier.
| Query |
Result |
mutation updateExtId {
updateApplication(id:"RcgoRyShXXFE"
idType:INTERNAL
application:{
externalId:"my new app 3 -updated "
}) {
id
externalId
name
}
}
|
{
"data": {
"updateApplication": {
"id": "RcgoRyShXXFE",
"externalId": "my new app 3 -updated ",
"name": "my new app 3"
}
}
}
|
If you do several mutation in a row you can use this External Identifier as a mean to connect object together.
For Example: In the mutation below we do the follwing
- Create a New Application
- Create a new Busines Process
- Connect the 2 newly created objects
| Query |
Result |
mutation multiple {
createApplication(id:"MyAPPID5" idType:EXTERNAL
application:{name:"Application 5"}) {
name
}
createBusinessProcess(id:"My Process 5" idType:EXTERNAL
businessProcess:{name:"Process 5"
application:{
action:ADD
list:[{id:"MyAPPID5" idType:EXTERNAL}]
}
}) {
name
application {
name
externalId
}
}
}
|
{
"data": {
"createApplication": {
"name": "Application 5"
},
"createBusinessProcess": {
"name": "Process 5",
"application": [
{
"name": "Application 5",
"externalId": "MyAPPID5"
}
]
}
}
}
|
Creation with an Temporary Identifier
The temporary Identifier works as the external identifier. The only difference is that the value of this identifier will not be stored in the database.
