Creating locations by using GraphQL

You can create locations and associate locations with assets by using the GraphQL API.

Before you begin

You need a JSON Web Token (JWT) for your API call. For more information, see API authentication

About this task

Each asset must be associated with a location object in Infohub. You use GraphQL queries to upload location objects to Infohub and provide the locationIdentifier attribute to associate each location to an asset.

The URL includes a {geo} field, which is a 2-letter code that represents the region. For example, for North America, the code is na.

Procedure

  • Create a location by sending an upsertLocation event to the GraphQL API.
    You use the same procedure to update a location. To update a location, provide the same payload and include the required updates.
    URL 
    
https://api.ibm.com/infohub/run/graph/na
    Method POST
    Body-Type GraphQL
    Body 
    mutation{
  upsertLocation(
    locationEvent: {
      tenantId: "{tenant_ID}"
      timestampEventOccurred: "2023-02-22T16:00:00Z"
      eventDetails: {
        businessObject: {
          locationIdentifier: "location-id"
          locationName: "location-name"
          locationType: "ALERT ASSET"
          city: "location-city"
          country: "location-country"
          coordinates: "lat,long"
          address1: "location address"
          postalCode: "location postal code"
          stateProvince: "location state"
          globalIdentifiers: [
            {
              name: "eis.geospatial.globalId"
              value: "location-id"
            }
          ]
          
        }
      }
    }
  )
}
    1. Include the following key pairs in the header: 
      Authorization: Bearer {{your-JWT-token}} 
x-ibm-client-id: infohub-{{your-tenant-id}}
    2. Add your tenantId.
    3. Assign a location ID to eventDetails.businessObject.globalIdentifiers.
    4. Set the location type to ALERT ASSET.
    5. Define the geographic location in coordinates.
      For example, coordinate 40.113, -99.295 is 40.113 latitude and -99.295 longitude.
  • To find a list of locations, create a query.
    1. Use the GraphQL API to fetch the list of locations.
      The following examples show a sample query and the result that was returned with the location data:
      URL 
      
https://api.ibm.com/infohub/run/graph/na
      Query criteria 
      query getLocation {
  businessObjects(
    hint: { viewId: "graph" }
    advancedFilter: {
      AND: [
        {
          EQUALS: [
            { SELECT: "globalIdentifiers.name" }
            { VALUE: "eis.geospatial.globalId" }
          ]
        }
        {
          EQUALS: [
            { SELECT: "globalIdentifiers.value" }
            { VALUE: "2a0097a2-e574-45e2-96ff-87de41864492" }
          ]
        }
      ]
    }
    simpleFilter: { type: Location, tenantId: "{tenant_ID}"
) {
    totalCount
    edges {
      object {
        ... on Location {
          locationName
          locationIdentifier
          locationType
          coordinates
        }
      }
    }
  }
}
      Query result 
      {
   "data": {
       "businessObjects": {
        "totalCount": 1,
           "edges": [
               {
                "object":{
                "locationName": "2a0097a2-e574-45e2-96ff-87de41864492",
                "locationIdentifier": "2a0097a2-e574-45e2-96ff-87de41864492",
                "locationType": "ALERT ASSET",
                "coordinates": "11.332904,77.723745"
         }
       }
      ]
    }
  }  
}
  • To delete a location, use the mutation keyword and the archiveBusinessEvent method.
    1. Use the GraphQL API to delete the location:
      URL 
      
https://api.ibm.com/infohub/run/graph/na
      Body 
      mutation {
  archiveBusinessEvent(
    archiveEvent: {
      tenantId: "{tenant_ID)"
      eventDetails: {
        businessObject: {
          type: Location
          globalIdentifiers: [
            { name: "eis.geospatial.globalId", value: "{ locationIdentifier }" }
          ]
        }
      }
    }
  )
}
    2. Include the following key value pairs in the header: 
      Authorization: Bearer {{your-JWT-token}} 
x-ibm-client-id: infohub-{{your-tenant-id}}
    3. Set eventDetails.businessObject.type to Location.
    4. In eventDetails.businessObject.globalIdentifiers, specify the locations to delete.
  • To associate a location with an asset, use the upsertAsset keyword and add the locationIdentifier to the businessObject.location attribute.
    Use the GraphQL API to associate the location with the asset:
    URL 
    
https://api.ibm.com/infohub/run/graph/na
    Body 
    mutation {
  upsertAsset(
    AssetEvent: {
      tenantId: "{tenant_ID}"
      timestampEventOccurred: "2023-02-22T16:00:00Z"
      eventDetails: {
        businessObject: {
          globalIdentifiers: [
                   {name: "eis.geospatial.globalId",
                    value: "{assetIdentifier}.STATIC"}
               ]
          assetIdentifier: "{for example, asset123}"
          assetType: "STATIC"
          currentLocationCoordinates: "{for example, 40.113, -99.295}"
          description: "{Description}"
          location: "{location-id}"
          contacts: [
            {
              globalIdentifiers:  [ 
                       {name: "eis.geospatial.globalId",
                        value: "{contact_ID}"}
                   ]
               }]
           }
       }
   })}
    1. Include the following key value pairs in the header: 
      Authorization: Bearer {{your-JWT-token}} 
x-ibm-client-id: infohub-{{your-tenant-id}}
    2. Add tenantId as a field.