catalog

The OLP CLI supports the following:

• list all visible catalogs
• create a catalog
• update a catalog
• show a catalog
• delete a catalog
• list dependencies of a catalog
• list permissions on a catalog across all organizations
• grant permissions on a catalog
• revoke permissions on a catalog
• delete versions of a catalog
• inspect a catalog

catalog list

Lists all catalogs that you can access and returns a catalog name on a separate line. The list of catalogs that are shown are dependent on the scope of the request:

• If the request contains no scope, the response will include all catalogs you can access, including catalogs inside all projects that you can access.
• If the request contains a project HRN as a scope, the response will only include catalogs that are part of that project.

To get more information about a catalog, see the show command.

olp catalog list [filter] [command options]

Optional parameters:

• [filter] Freeform text used to filter the catalog list. The filter checks if the catalog HRN contains the filter string.
• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --json Displays the command result in JSON format.
• --quiet Displays catalog HRNs, each on a new line.
• --scope <project HRN> Specifies the project HRN to use as the scope in the request. The value specified with --scope overrides any value for here.token.scope provided in the credentials file used for the command.

For more information on using credentials and profiles, see Credentials setup.

Example with filtering:

olp catalog list "first-catalog-example-id" --json

Output:

{"results": {"items": [
    {"hrn": "hrn:here-cn:data::org:first-catalog-example-id"}
]}}

Example without filtering:

olp catalog list --json

Output:

{"results": {"items": [
    {"hrn": "hrn:here-cn:data::org:first-catalog-example-id"},
    {"hrn": "hrn:here-cn:data::org:second-catalog-example-id"}
]}}

catalog create

Creates an empty catalog in the platform. Access to the created catalog depends on the scope of the request:

• If the request contains no scope, the calling App will be granted full access to the catalog, including the ability to share with others.
• If the request contains a project HRN as a scope, the catalog will be created inside of the project and access to it will be automatically available to all users and apps that have access to the project.

olp catalog create <catalog ID> <catalog name> --summary <catalog summary> [command options]

Required parameters:

• <catalog ID> The ID of the catalog that the platform uses to generate the catalog HRN.
• <catalog name> The human-readable name of the catalog. Overrides any values provided with the --config parameter through the command line.
• --description <catalog description> A detailed description of the catalog and its contents. Enclose the description in quotes.
• --summary <catalog summary> A one-line summary of the catalog contents. Overrides any values provided with the --config parameter through the command line.

Optional parameters:

• --config <path to config file> The path to a local file that contains configuration for a new catalog.

• --tags <tag1 tag2 ...> Catalog keywords used for search discovery.
• --notifications If set to true, a notification is written to the notification stream layer each time the catalog’s version changes. The default value is false.
• --skip-sharing-with-user Prevents sharing catalog permissions with the associated user account. The default value is false, as the CLI shares permissions with the user account. This option may be used to prevent associated user accounts from reaching the limit of resources they are allowed to create. If a scope is provided in the request, this option is required to be true and assumed to be a value of true. A value of false is ignored.
• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --json Displays the catalog HRN in JSON format.
• --quiet Displays the catalog HRN.
• --scope <project HRN> Specifies the project HRN to use as the scope in the request. The value specified with --scope overrides any value for here.token.scope provided in the credentials file used for the command.

• --replication Space-separated list of supported replication regions. The first value is the primary region and the second value, if passed, is the secondary replication region. This parameter is optional, however, if passed, the primary region must be provided. If specified, the secondary region should not be the same as primary. For more information about multi-region support, see Data Security and Durability.

  Note

  If --replication parameter is not passed, the catalog is created with the replication configuration from the JSON file passed with the --config <config file> parameter.

  Sample JSON file with the replication property:

  {
    . . .
    "replication": {
      "regions": [
        {
          "role": "primary",
          "id": "us-oregon"
        },
        {
          "role": "secondary",
          "id": "eu-ireland"
        }
      ]
    },
    . . .
  }
  

• --auto-version-deletion <number of latest versions to keep> Defines the maximum number of catalog versions to keep at a time. If this maximum is reached and a new version is created, the oldest catalog version is automatically deleted. By default, automatic version deletion for catalogs is disabled. <number of latest versions to keep> must be of type long. Overrides any values provided with the --config parameter through the command line.

  Note

  This parameter is applicable only with the --config <config file> parameter in case the <config file> contains definition for at least one versioned layer.

  To disable automatic version deletion see catalog update commands.

• --retry <number of retries> Defines a number of retries if catalog creation failed with the 403 status code and the These credentials do not authorize access error. The default value is 0, which means no retries. The timeout before the first retry is 5 seconds. For each next retry, the timeout value will be doubled: 5 seconds, 10 seconds, 20 seconds, 40 seconds and so on.

Example:

The command below creates the empty catalog first-catalog-example on the platform, and displays the catalog's HRN in the output.

olp catalog create first-catalog-example-id first-catalog-example --summary "A new summary"

To pass multiple arguments to a parameter that accepts them, separate the arguments with spaces.

Example:

The command below creates an empty catalog second-catalog-example with two tags (tag1 and tag2) in the platform and displays the catalog's HRN in the console output.

olp catalog create second-catalog-example-id second-catalog-example --tags tag1 tag2 --summary "A new summary"

Example:

The command below creates an empty catalog third-catalog-example with a primary replication region:

olp catalog create third-catalog-example-id third-catalog-example --replication eu-ireland --summary "A new summary"

Example:

The command below creates an empty catalog fourth-catalog-example with primary and secondary replication regions:

olp catalog create fourth-catalog-example-id fourth-catalog-example --replication eu-ireland us-oregon --summary "A new summary"

Note that in the examples above, catalog names first-catalog-example and similar serve as placeholders where you should pass the names of your own catalogs.

For more information on using credentials and profiles, see Credentials setup.

catalog update

Updates an existing catalog in the platform with the configuration specified in a configuration file.

olp catalog update <catalog HRN> [command options]

Required parameters:

• <catalog HRN> The HRN of the catalog.

Optional parameters:

• --config <path to config file> The path of the file with the updated configuration.
• --name <catalog name> The human-readable name of the catalog. Overrides values provided with --config through the command line.
• --summary <catalog summary> A one-line summary of the catalog contents. Overrides values provided with --config through the command line.
• --description <catalog description> A detailed description of the catalog and its contents. Enclose the description in quotes.
• --tags <tag1 tag2 ...> Catalog keywords used for search discovery. To unset tags, use --tags [].
• --notifications If set to true, a notification is written to the notification stream layer each time the catalog’s version changes. The default value is false.
• --marketplace-ready <true|false> If set to true, the catalog is marked as Ready for Marketplace. If set to false, the catalog is not marked as Ready for Marketplace.
• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --quiet Displays empty output with no additional information.
• --scope <project HRN> Specifies the project HRN to use as the scope in the request. The value specified with --scope overrides any value for here.token.scope provided in the credentials file used for the command.
• --auto-version-deletion <number of latest versions to keep | off> Defines the maximum number of catalog versions to keep at a time. If this maximum is reached and a new version is created, the oldest catalog version is automatically deleted. By default, automatic version deletion for catalogs is disabled. <number of latest versions to keep | off> can be of type long or key word off to remove automatic version deletion from a catalog. Overrides any values provided with the --config parameter through the command line.

For more information on using credentials and profiles, see Credentials setup.

Example:

olp catalog update hrn:here-cn:data::org:first-catalog-example-id --config path/to/config.json

Example configuration for a catalog with a volatile layer:

{
  "name": "volatile-volatile-catalog",
  "summary": "A short summary",
  "description": "A longer description about what the catalog contains",
  "tags": [
    "tag1",
    "tag2"
  ],
  "layers": [
    {
      "id": "volatile-layer",
      "name": "volatile-layer",
      "summary": "A short summary",
      "description": "A longer description about what the layer contains",
      "layerType": "volatile",
      "partitioningScheme": "generic",
      "partitioning": {
          "scheme": "generic"
      },
      "volume": {
         "volumeType": "volatile"
      },
      "contentType": "application/x-protobuf"
    }
  ]
}

Example configuration for a catalog with a versioned layer:

{
  "name": "versioned-durable-catalog",
  "summary": "A short summary",
  "description": "A longer description about what the catalog contains",
  "tags": [
    "tag1",
    "tag2"
  ],
  "layers": [
    {
      "id": "versioned-layer",
      "name": "versioned-layer",
      "summary": "A short summary",
      "description": "A longer description about what the layer contains",
      "layerType": "versioned",
      "partitioningScheme": "generic",
      "partitioning": {
          "scheme": "generic"
      },
      "volume": {
          "volumeType": "durable"
      },
      "contentType": "application/x-protobuf",
      "crc": "CRC-32C",
      "digest": "MD5"
    }
  ]
}

Example configuration for a catalog with a stream layer:

{
  "name": "stream-durable-catalog",
  "summary": "A short summary",
  "description": "A longer description about what the catalog contains",
  "tags": [
    "tag1",
    "tag2"
  ],
  "layers": [
    {
      "id": "stream-layer",
      "name": "stream-layer",
      "summary": "A short summary",
      "description": "A longer description about what the layer contains",
      "layerType": "stream",
      "partitioningScheme": "generic",
      "partitioning": {
          "scheme": "generic"
      },
      "volume": {
          "volumeType": "durable"
      },
      "contentType": "application/x-protobuf"
    }
  ]
}

Example configuration for a catalog with an interactive map layer:

{
    "name": "interactive-map-catalog",
    "summary": "A short summary",
    "description": "A longer description about what the catalog contains",
    "tags": [
        "tag1",
        "tag2"
    ],
    "layers": [
        {
            "id": "interactive-map-layer",
            "name": "interactive-map-layer",
            "summary": "A short summary",
            "description": "A longer description about what the layer contains",
            "layerType": "interactivemap",
            "volume": {
                "volumeType": "durable"
            },
            "contentType": "application/geo+json",
            "partitioning": {},
            "interactiveMapProperties": {
                "searchableProperties": [
                    "property-1",
                    "property-2"
                ]
            }
        }
    ]
}

Example with additional parameters:

olp catalog update hrn:here-cn:data::org:first-catalog-example-id --name first-catalog-example-updated \
 --summary "Updated summary" --description "Updated description"

olp catalog update hrn:here-cn:data::org:first-catalog-example-id --name first-catalog-example-updated ^
--summary "Updated summary" --description "Updated description"

Example with a catalog automatic version deletion removal:

olp catalog update hrn:here-cn:data::org:first-catalog-example-id --auto-version-deletion off

olp catalog update hrn:here-cn:data::org:first-catalog-example-id --auto-version-deletion off

For more information on catalog configurations, see Data API.

catalog show

Shows the catalog configuration.

olp catalog show <catalog HRN> [command options]

Required parameters:

• <catalog HRN> The HRN of the catalog

Optional parameters:

• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --json Displays the command result in JSON format.
• --quiet Displays catalog's layer types and layer IDs, separated by space.
• --scope <project HRN> Specifies the project HRN to use as the scope in the request. The value specified with --scope overrides any value for here.token.scope provided in the credentials file used for the command.

For more information on using credentials and profiles, see Credentials setup.

Example:

olp catalog show hrn:here-cn:data::org:first-catalog-example-id --json

The output contains the configuration of the catalog in JSON format:

{
    "summary": "",
    "owner": {
        "creator": {"id": "mzLcb1rL8nskvDQpCFEF"},
        "organisation": {"id": "org"}
    },
    "billingTags": [],
    "hrn": "hrn:here-cn:data::org:first-catalog-example-id",
    "created": "2018-03-02T10:41:09.309Z",
    "name": "first-catalog-example",
    "layers": [
        {
            "summary": "Summary",
            "volume": {"volumeType": "durable"},
            "layerType": "versioned",
            "billingTags": [],
            "crc": "CRC-32C",
            "name": "Test Layer",
            "contentEncoding": "gzip",
            "description": "some description",
            "partitioningScheme": "generic",
            "partitioning": {"scheme": "generic"},
            "id": "test-layer",
            "contentType": "application/octet-stream",
            "digest": "SHA-1",
            "tags": []
        },
        {
            "summary": "Summary",
            "volume": {"volumeType": "durable"},
            "layerType": "versioned",
            "billingTags": [],
            "crc": "CRC-32C",
            "name": "Test Layer1",
            "description": "some description",
            "partitioningScheme": "generic",
            "partitioning": {"scheme": "generic"},
            "id": "test-layer1",
            "contentType": "application/octet-stream",
            "tags": []
        }
    ],
    "description": "",
    "notifications": {
        "enabled": false
    },
    "marketplaceReady": false,
    "automaticVersionDeletion": {"numberOfVersionsToKeep": 100},
    "id": "first-catalog-example-id",
    "version": 4,
    "metadataVersion": 21
    "metadataMinimumVersion": 0
    "tags": []
}

catalog delete

Deletes a catalog from the platform.

olp catalog delete <catalog HRN> [command options]

Required parameters:

• <catalog HRN> The HRN of the catalog.

Optional parameters:

• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --quiet Displays empty output with no additional information.
• --scope <project HRN> Specifies the project HRN to use as the scope in the request. The value specified with --scope overrides any value for here.token.scope provided in the credentials file used for the command.

Example:

olp catalog delete hrn:here-cn:data::org:first-catalog-example-id

For more information on using credentials and profiles, see Credentials setup.

catalog dependency list

Lists all catalog dependencies for a specific version.

olp catalog dependency list <catalog HRN>

Required parameters:

• <catalog HRN> The HRN of the catalog.

Optional parameters:

• --version <catalog version> The catalog version. The default value is the latest version.
• --direct-only When enabled, only direct dependencies are displayed. When disabled, both direct and indirect dependencies are displayed. Disabled by default.
• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --json Displays the command result in JSON format.
• --quiet Displays HRNs of catalog dependencies, each on a new line.
• --scope <project HRN> Specifies the project HRN to use as the scope in the request. The value specified with --scope overrides any value for here.token.scope provided in the credentials file used for the command.

For more information on using credentials and profiles, see Credentials setup.

Example:

The command below lists all direct dependencies for the hrn:here-cn:data::org:first-catalog-example-id catalog in JSON format.

olp catalog dependency list hrn:here-cn:data::org:first-catalog-example-id --direct-only --json

catalog permission list

List the permissions of users, apps, and groups across all organizations associated with a catalog.

olp catalog permission list <catalog HRN> [command options]

Required parameters:

• <catalog HRN> The HRN of the catalog.

Optional parameters:

• --type <app|group|user> Specifies the type of entity to list.
• --limit <max number of entities> Specifies the maximum number of entities to be returned in the result (100 by default).
• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --json Displays the command result in JSON format.
• --quiet Displays the entities' HRNs, each on a new line.

For more information on using credentials and profiles, see Credentials setup.

Example:

olp catalog permission list hrn:here-cn:data::org:first-catalog-example-id \
    --json

olp catalog permission list hrn:here-cn:data::org:first-catalog-example-id ^
    --json

Output:

{"entityGrants": [
    {
      "entityId": {
        "id": "HERE-05966c89-aaf1-4ae2-b0e4-3676b3f8b8c3",
        "hrn": "hrn:here-cn:account::org:user/HERE-05966c89-aaf1-4ae2-b0e4-3676b3f8b8c3",
        "realmHrn": "hrn:here-cn:account::org:realm/org",
        "type": "user"
      },
      "permissions": [
        {
          "id": "PERM-7heTYzsR05VR_p3IeyaZKDdlVPb1zJJUmzLI9JUEDcc",
          "action": "read",
          "effect": "allow",
          "resource": "hrn:here-cn:data::org:first-catalog-example-id",
          "serviceId": "SERVICE-b9acbead-4666-487e-88b0-cfb64ed0ac6a"
        },
        {
            "id": "PERM-7heTYzsR0RV5_p3IeyaZKDdlVPb1zJJUmzLI9JUDEbb",
            "action": "write",
            "effect": "allow",
            "resource": "hrn:here-cn:data::org:first-catalog-example-id",
            "serviceId": "SERVICE-b9acbead-4666-487e-88b0-cfb64ed0ac6a"
        }
      ]
    },
    {
      "entityId": {
        "id": "my-app-1234",
        "hrn": "hrn:here-cn:account::org:app/my-app-1234",
        "realmHrn": "hrn:here-cn:account::org:realm/org",
        "type": "app"
      },
      "permissions": [
        {
          "id": "PERM-7heTYzsR05VR_p3IeyaZKDdlVPb1zJJUmzKJ9JUECdd",
          "action": "manage",
          "effect": "allow",
          "resource": "hrn:here-cn:data::org:first-catalog-example-id",
          "serviceId": "SERVICE-b9acbead-4666-487e-88b0-cfb64ed0ac6a"
        }
      ]
    }
  ]
}

catalog permission grant

Grants permission to perform specified actions on a catalog for users, apps, or groups.

olp catalog permission grant <catalog HRN> [command options]

Required parameters:

• <catalog HRN> The HRN of the catalog.
• Either of the following recipients:
  • --group <groupID1 groupID2 ...> The list of group IDs you want to grant catalog access to, separated by space.
  • --user <userID1 userID2 ...> The list of user IDs you want to grant catalog access to, separated by space. This information can be found in the .here/credentials.properties file, in the user's home directory, or via your profile.
  • --app <appID1 appID2 ...> The list of application IDs you want to grant catalog access to, separated by space.
• Either of the following permissions:
  • --manage Grants manage and share access to the catalog.
  • --read Grants read access to the catalog.
  • --write Grants write access to the catalog.
  • --share Grants share access to the catalog.

Optional parameters:

• --cross-realm A flag that allows granting catalog permissions (--read, --write, --manage, --share) to users, apps, or groups from different realms.
• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --quiet Displays empty output with no additional information.

For more information on using credentials and profiles, see Credentials setup.

Example:

olp catalog permission grant hrn:here-cn:data::org:first-catalog-example-id --group \
 GROUP-example-group-id --read --write --manage --share

olp catalog permission grant hrn:here-cn:data::org:first-catalog-example-id --group ^
GROUP-example-group-id --read --write --manage --share

Response:

Granted read, write, manage, share access for a group GROUP-example-group-id to the catalog hrn:here-cn:data::org:first-catalog-example-id

catalog permission revoke

Revokes permissions to perform specified actions on a catalog for users, apps, or groups.

olp catalog permission revoke <catalog HRN> [command options]

Required parameters:

• <catalog HRN> The HRN of the catalog.
• Either of the following recipients:
  • --app <appID1 appID2 ...> The list of application IDs you want to revoke catalog access from, separated by space.
  • --user <userID1 userID2 ...> The list of user IDs you want to revoke catalog access from, separated by space. This information can be found in the .here/credentials.properties file, in the user's home directory, or via your profile.
  • --group <groupID1 groupID2 ...> The list of group IDs you want to revoke catalog access from, separated by space.
• Either of the following permissions:
  • --manage Revokes manage and share access to the catalog.
  • --read Revokes read access to the catalog.
  • --write Revokes write access to the catalog.
  • --share Revokes share access to the catalog.

Optional parameters:

• --cross-realm A flag that allows revoking catalog permissions (--read, --write, --manage, --share) from users, apps, or groups from different realms.

  Note

  The catalog permission revoke command does not accept any of the --read|--write|--manage|--share flags if --cross-realm is passed.

• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --quiet Displays empty output with no additional information.

For more information on using credentials and profiles, see Credentials setup.

Example:

olp catalog permission revoke hrn:here-cn:data::org:first-catalog-example-id \
 --group GROUP-example-group-id --read --write --manage --share

olp catalog permission revoke hrn:here-cn:data::org:first-catalog-example-id ^
--group GROUP-example-group-id --read --write --manage --share

Response:

Revoked read, write, manage, share access for a group GROUP-example-group-id to the catalog hrn:here-cn:data::org:first-catalog-example-id

catalog version delete

Deletes those catalog versions that are less than the specified one and sets a new minimum version. To check the current minimum version, refer to the values for metadataMinimumVersion in JSON output and metadata minimum version in verbose output of the olp catalog show command.

olp catalog version delete <catalog HRN> <version> [command options]

Required parameters:

• <catalog HRN> The HRN of the catalog.
• <version> The earliest catalog version that will not be deleted.

Optional parameters:

• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --quiet Displays empty output with no additional information.
• --scope <project HRN> Specifies the project HRN to use as the scope in the request. The value specified with --scope overrides any value for here.token.scope provided in the credentials file used for the command.

Example:

olp catalog version delete hrn:here-cn:data::org:first-catalog-example-id 4

Response:

Successfully deleted catalog versions less than 4

catalog inspect

Opens an external browser and navigates to the catalog overview page in the platform portal. The command fails if you cannot access the catalog.

To inspect a specific layer, see the olp catalog layer inspect command.

olp catalog inspect <catalog HRN> [command options]

Optional parameters:

• --credentials <path to credentials file> The name of a credentials file to use with the command. Credentials files are downloaded separately from the platform portal.
• --profile <profile name> The name of the credentials profile to use from the olpcli.ini file.
• --quiet Displays empty output with no additional information.
• --scope <project HRN> Specifies the project HRN to use as the scope in the request. The value specified with --scope overrides any value for here.token.scope provided in the credentials file used for the command.

For more information on using credentials and profiles, see Credentials setup.