HPE GreenLake Locations developer guide

Locations service enables creating and managing locations with service delivery contact and address information. The examples in this guide help you use the Locations APIs to add, update, and delete locations.

Prerequisites

Ensure that you meet the following prerequisites:

  • Locations and service delivery contact information that you want to map to existing devices.
  • Access to devices that you want to assign locations to.
  • HPE GreenLake edge-to-cloud platform administrator permissions. Contact the Administrator in your organization if you do not already have access.

Endpoints

Endpoints are the host URLs that you will submit your API requests to.

URIs

Unique Resource Identifiers (URIs) identify a server or resource used in the Locations API. A URI is a full API path ending with a specific endpoint. For example:

  • /locations/v1/locations
  • /locations/v1/locations/{id}
  • /locations/v1/locations/update/{id}
  • /locations/v1/locations/tags
  • /locations/v1/locations/tags/{id}
  • /locations/v1/locations/address/revgeocode

Access and permissions

A user with view permissions for Locations (ccs.location-management.view) is sufficient to make the following API calls:

  • GET: /locations/v1/locations
  • GET: /locations/v1/locations/{id}
  • GET: /locations/v1/locations/tags
  • GET: /locations/v1/locations/tags/{id}
  • GET: /locations/v1/locations/address/revgeocode

A user with edit permissions for Locations (ccs.location-management.edit) is required to make the following API calls:

  • POST: /locations/v1/locations
  • PATCH: /locations/v1/locations/{id}
  • DELETE: /locations/v1/locations/{id}
  • PATCH: /locations/v1/locations/update/{id}
  • PATCH: /locations/v1/locations/tags

Generating Token

You must configure API credentials and generate an access token to make API calls. HPE GreenLake APIs use OAuth-based access tokens used as an authorization bearer token.

To access this HPE GreenLake platform wellness API, proceed as follows:

  1. Connect to the HPE GreenLake edge-to-cloud platform UI workspace.
  2. Go to Manage Workspace > API > Create Credentials .
  3. Select  HPE GreenLake Platform  from the Select Service Manager  drop-down and enter a credential name in Credential Name to create the credentials and generate access tokens for HPE GreenLake platform service APIs. If you do not see HPE GreenLake Platform as an option when configuring API client credentials, see the Getting Started Guide for more information.

Making It All Work

The examples in this section provide a high-level overview of the functionality of HPE GreenLake for Location APIs. For more details and code samples, view the API reference.

Obtain a list of all locations

Locations capture addresses, contacts, and service delivery information for operations, management, and commerce. The information is used for service delivery and support, and operations. Use a GET request to retrieve a list of locations.

The endpoint:

Copy
Copied
GET https://global.api.greenlake.hpe.com/locations/v1/locations

The information included in a valid response:

  • Location Id
  • Name
  • City
  • Country
  • Pagination with page information and total count of locations

The information included in an invalid response:

  • HttpStatusCode
  • Message
  • DebugId
  • ErrorCode

Obtain specific location information

Locations capture addresses, contacts, and service delivery information for operations, management, and commerce. The information is used for service delivery and support, and operations.

Make a GET request and provide the location Id to retrieve information for the specified location.

The endpoint:

Copy
Copied
GET https://global.api.greenlake.hpe.com/locations/v1/locations/{id}

The information included in a valid response:

  • Location
  • Name
  • Type
  • Description of a location
  • Contact information
  • Name
  • Type
  • Email
  • Phone number
  • Address information
  • Id
  • Type
  • Country
  • Street_address
  • City
  • State
  • Postal code

The information included in an invalid response:

  • HttpStatusCode
  • Message
  • DebugId
  • ErrorCode

Create a location

You can create a location to assign to your devices using HPE GreenLake Locations service by making a POST request and providing a name, description, address, and contact information.

  • Name —Give the location a name that makes it easy to identify.
  • Description (optional)—Add a description of the location to help identify it.
  • Address —Provide a physical address of the location. This address can also be the shipping and receiving address or you can provide a different address for shipping and receiving.
  • Contacts —Provide the name, email, and phone number of the location contacts. You must provide only one primary contact. You can provide multiple security, shipping and receiving, and operations contacts.

The endpoint:

Copy
Copied
POST https://global.api.greenlake.hpe.com/locations/v1/locations

Payload:

Copy
Copied
{
    "name": "Test Location",
    "description": "This is a test location",
    "type": "building",
    "validated": true,
    "validationCycle": "6",
    "addresses": [
        {
            "type": "street",
            "country": "US",
            "street_address": "1701 E Mossy Oaks Rd ",
            "street_address2": "This is a test location",
            "city": "Spring",
            "state": "TX",
            "postal_code": "77389"
        }
    ],
    "contacts": [
        {
            "type": "primary",
            "name": "John Doe",
            "phoneNumber": "+1800-123-4567",
            "email": "john.doe@hpe.com"
        }
    ]
}

The information included in a valid response:

  • Location
  • Name
  • Type
  • Description of a location
  • Contact information
  • Name
  • Type
  • Email
  • Phone number
  • Address information
  • Id
  • Type
  • Country
  • Street address
  • City
  • State
  • Postal code
  • Validated
  • Validated by name
  • Validated by email
  • Validation cycle
  • Validation expired
  • Validation cycle
  • Generation
  • Created at
  • Updated at

The information included in an invalid response:

  • HttpStatusCode
  • Message
  • DebugId
  • ErrorCode

Delete a location

To delete a particular location, use a DELETE request and provide a specific location Id.

Copy
Copied
DELETE https://global.api.greenlake.hpe.com/locations/v1/locations/{id}

The information included in a valid response:

  • 204 No content response.

The information included in an invalid response:

  • HttpStatusCode
  • Message
  • DebugId
  • ErrorCode

Update location

Update location information like address, contact, name, and description for a specified location by making a PATCH request and providing a location id.

The endpoint:

Copy
Copied
PATCH https://global.api.greenlake.hpe.com/locations/v1/locations/{id}

Payload:

Copy
Copied
{
  "name": "Test Location",
  "description": "This is a test location.",
  "type": "Building"
}

The payload can also consist of contact or addresses object to be updated.

The information included in a valid response:

  • Empty response
  • Name
  • Type
  • Description of a location
  • Contact information
  • Name
  • Type
  • Email
  • Phone number
  • Address information
  • Id
  • Type
  • Country
  • Street address
  • City
  • State
  • Postal code
  • Validated
  • Validated by name
  • Validated by email
  • Validation cycle
  • Validation expired
  • Validation cycle
  • Generation
  • Created at
  • Updated at

The information included in an invalid response:

  • HttpStatusCode
  • Message
  • DebugId
  • ErrorCode

Manage location information

Update location information like with array of address and contact objects for a specified location by making a PATCH request and providing a location id.

The endpoint:

Copy
Copied
PATCH https://global.api.greenlake.hpe.com/locations/v1/locations/update/{id}

Payload:

Copy
Copied
{
  "addresses": {
    "add": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "city": "string",
        "country": "string",
        "locationId": "string",
        "postalCode": "string",
        "state": "string",
        "streetAddress": "string",
        "streetAddress2": "string",
        "type": {}
      }
    ],
    "delete": [
      "string"
    ],
    "update": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "city": "string",
        "country": "string",
        "locationId": "string",
        "postalCode": "string",
        "state": "string",
        "streetAddress": "string",
        "streetAddress2": "string",
        "type": {}
      }
    ]
  },
  "contacts": {
    "add": [
      {
        "email": "string",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "locationId": "string",
        "name": "string",
        "phoneNumber": "string",
        "type": "primary"
      }
    ],
    "delete": [
      "string"
    ]
  }
}

The payload can also consist of contact or addresses object to be updated.

The information included in a valid response:

  • Empty response
  • Name
  • Type
  • Description of a location
  • Addresses array of objects
  • Contacts array of objects
  • Id
  • Type
  • Country
  • Street address
  • City
  • State
  • Postal code
  • Validated
  • Validated by name
  • Validated by email
  • Validation cycle
  • Validation expired
  • Validation cycle
  • Generation
  • Created at
  • Updated at

The information included in an invalid response:

  • HttpStatusCode
  • Message
  • DebugId
  • ErrorCode

Obtain a list of all tags for all locations in a workspace

Tags consist of name and value pairs and are associated with locations.

Use this GET request to retrieve a list of tags for a workspace.

The endpoint:

Copy
Copied
GET https://global.api.greenlake.hpe.com/locations/v1/locations/tags

The information included in a valid response:

  • An array of objects with the tag name, tag value, and the created at timestamp.
  • Pagination with page information
  • Total count of tags for a workspace.

The information included in an invalid response:

  • HttpStatusCode
  • Message
  • DebugId
  • ErrorCode

Obtain tag information for a specific location

Tags consist of name and value and are associated with locations.

Use this GET request and provide the location ID to retrieve all the tag information for the specified location.

The endpoint:

Copy
Copied
GET https://global.api.greenlake.hpe.com/locations/v1/locations/tags/{id}

The information included in a valid response:

  • Tag objects with name and value information
  • Location ID
  • Location name

The information included in an invalid response:

  • HttpStatusCode
  • Message
  • DebugId
  • ErrorCode

Manage tags for a location

Update tag information by providing create and delete tag objects for a specified location.

Make a PATCH request and provide a location ID in the request.

The endpoint:

Copy
Copied
PATCH https://global.api.greenlake.hpe.com/locations/v1/locations/tags

Payload:

Copy
Copied
{
    "createTags": [
 
        {
            "name": "test-2001",
            "value": ""
        },
        {
            "name": "test-2002",
            "value": ""
        },
        {
            "name": "test-2003",
            "value": ""
        },
        {
            "name": "test-2004",
            "value": ""
        },
        {
            "name": "test-2005",
            "value": ""
        }
    ],
    "deleteTags": [
          {
            "name": "test-2046",
            "value": ""
        }
    ],
    "locationId": "4f94d3fa-cbcc-463d-a13d-d3e32c2d722d"
}

The payload can also include contact or address objects to update.

The information included in a valid response:

  • Empty response
  • createTag (an object with tag name and value pairs)
  • deleteTag (an object with tag name and value pairs)
  • Id
  • Type
  • Generation
  • CreatedAt
  • UpdatedAt

The information included in an invalid response:

  • HttpStatusCode
  • Message
  • DebugId
  • ErrorCode

Obtain location address using latitude and longitude

Use this endpoint to reverse geocode a location. In reverse geocoding, a location described by geographic coordinates (longitude and latitude) is converted to a human-readable address.

Make the GET request and provide the longitude and latitude as query parameters to retrieve a location's address information. Locations capture addresses, contacts, and service delivery information for operations, management, and commerce. The information is used for service delivery, support, and operations.

The endpoint:

Copy
Copied
GET https://global.api.greenlake.hpe.com/locations/v1/address/revgeocode

The information included in a valid response:

  • Label
  • Country code
  • Country
  • State code
  • State
  • County
  • City
  • Street
  • Postal code
  • Latitude
  • Longitude

The information included in an invalid response:

  • HttpStatusCode
  • Message
  • DebugId
  • ErrorCode

For example:

Copy
Copied
GET https://global.api.greenlake.hpe.com/locations/v1/address/revgeocode?latitude=48.924549&longitude=2.359627

Payload:

Copy
Copied
{
    "items": [
        {
            "label": "STADE DE FRANCE, Avenue Jules Rimet, 93210 Saint-Denis, France",
            "countryCode": "FRA",
            "countryName": "France",
            "stateCode": "IDF",
            "state": "Ile-de-France",
            "county": "Seine-Saint-Denis",
            "city": "Saint-Denis",
            "street": "Avenue Jules Rimet",
            "postalCode": "93210",
            "lat": 48.9242,
            "lng": 2.35862
        }
    ],
    "offset": 0,
    "count": 1,
    "total": 1
}

Filtering

Filters allow you to limit the resources that take part in the action of a REST call. When a REST call includes a filter, the GET or PUT action is restricted to a response that meets the filter requirements. Specify filters using the query parameter filter.

The Locations service allows you to filter using the contains function. A function is a block of reusable code that performs a single action. Filters that use the contains function take the form filter=contains(<property>, <value>).

  • Property is the name of an attribute in the requested resource type.
  • Value is the term that you want to filter by.

The Locations API supports the data type string, which is anything in 'single quotes'. For a successful matching operation, the data types must match, and the syntax determines the data type of the literals. Due to URL encoding, reserved characters ! # $ & ' ( ) * + , / : ; = ? @ [ ] in string literals must be replaced with percent-encoded equivalents.

For example:

Copy
Copied
GET <URI>?filter=contains(name,'test')'

This example checks if a location name includes the string test and returns a boolean, true or false, as appropriate.

OData filtering reference

This filtering is a subset of OData 4.0 filtering.