Command Reference

Command Reference

Supported commands (or operations) enable the user for managing the gateway configuration as standard bundles. Though the operations look independent, they can be batched for solving the variety of problems. Commands are customizable using global options. If interested, code extensions can be leveraged for advanced use-cases.

Running the client with no arguments will show the list of supported commands.

graphman

Each individual command(operation) is self-discoverable using --help option.

graphman <operation> --help

Command Categories

Configuration Management

Command	Description
config	Initialize and manage Graphman home directory
version	Display version and system information
schema	View GraphQL schema and entity types
describe	List and describe available queries

Gateway Operations

Command	Description
export	Export Gateway configuration as bundles
import	Import bundles to Gateway
diff	Compare configurations and generate differences
renew	Refresh bundle with latest Gateway details

Bundle Manipulation

Command	Description
combine	Merge multiple bundles into one
slice	Extract specific sections from a bundle
explode	Break bundle into multiple files
implode	Combine files back into a bundle

Bundle Processing

Command	Description
mappings	Define entity mapping instructions
revise	Update bundle to conform to schema changes
validate	Validate bundle entities and policy code

Common Workflows

Environment Synchronization

# 1. Compare environments
graphman diff --input-source @dev --input-target @prod --output sync.json

# 2. Review differences
cat sync.diff-report.json

# 3. Apply changes
graphman import --input sync.json --gateway prod

Configuration Backup

# Export complete configuration
graphman export --gateway prod --output backup-$(date +%Y%m%d).json

# Explode for version control
graphman explode --input backup.json --output config/ --options.level 2

Selective Deployment

# Export from dev
graphman export --gateway dev --output dev-config.json

# Extract services and policies
graphman slice --input dev-config.json --sections services policies --output deployment.json

# Deploy to production
graphman import --input deployment.json --gateway prod

Cross-Environment Migration

# Export from source
graphman export --gateway source --output source-config.json

# Prepare for target (remove GOIDs)
graphman revise --input source-config.json --output portable.json \
  --options.normalize true \
  --options.excludeGoids true

# Import to target
graphman import --input portable.json --gateway target

Version Control Integration

# Export configuration
graphman export --gateway dev --output temp.json

# Explode for Git
graphman explode --input temp.json --output repo/config/ --options.level 2
rm temp.json

# Commit to Git
git add repo/config/
git commit -m "Updated configuration"
git push

Quick Reference

Export Examples

# Export all
graphman export --gateway prod --output all.json

# Export specific service
graphman export --using serviceByName --variables.name "MyService" --gateway prod --output service.json

# Export with filter
graphman export --using services --filter.services.folderPath.eq /APIs --gateway prod --output apis.json

Import Examples

# Basic import
graphman import --input bundle.json --gateway prod

# Import with mappings
graphman import --input bundle.json --gateway prod --options.bundleDefaultAction NEW_OR_UPDATE

# Delete entities
graphman import --using delete-bundle --input bundle.json --gateway dev --options.forceDelete true

Bundle Manipulation

# Combine bundles
graphman combine --inputs bundle1.json bundle2.json --output combined.json

# Slice sections
graphman slice --input bundle.json --sections services policies --output subset.json

# Explode bundle
graphman explode --input bundle.json --output exploded/ --options.level 2

# Implode directory
graphman implode --input exploded/ --output bundle.json

Using export command

The Graphman export command lets you create a bundle for specific entities based on a query targetting those entities. The queries folder contains a number of sample queries that can be used for this purpose. The query to use is provided to the command using the --using argument. Here are some examples and how to use them.

all

This query lets you package the entire configuration of a gateway. No input parameters are needed for this one:

graphman.sh export --gateway <source-gateway> --using all --output mybundle.json

• specify --options.policyCodeFormat <format> to choose one of the supported policy code formats (xml|json|yaml|code) for export
• specify --options.keyFormat <format> to choose one of the supported key formats (p12|pem) for export
• use --options.includePolicyRevisions flag to include policy revisions along with the policies and services for export
• use --options.includeMultipartFields flag to include multipart fields (filePartName) so that server module file will be fully exported
• NOTE: Above options are applicable to the export operation irrespective of the query being used.

all:summary

This query lets you know the summary of the entire gateway configuration. One of the main use of this is to quickly identify what is missing or modified. FYI, diff operation uses this query.

graphman.sh export --gateway <source-gateway> --using all:summary --output mybundle.json

folder

This sample query packages a combination of all policies and services that are at a specific folder path location as well as in children sub-folders.

To export all policies and services from a folder /hello/world and all its sub-folders:

graphman.sh export --gateway <source-gateway> --using folder --variables.folderPath /hello/world --output hello-world.json

service

This query lets you package a particular published service from the source gateway. You identify which service to pull by providing the command the resolution path defined for this service.

To export a service with the /hello-world resolution path:

graphman.sh export --gateway <source-gateway> --using service --variables.resolutionPath /hello-world --output hello-world.json

encass

This query lets you package a particular encapsulated assertion from the source gateway. To export an encapsulated assertion with the hello-world name:

graphman.sh export --gateway <source-gateway> --using encass --variables.name hello-world --output hello-world.json

policy

This query lets you package a particular policy from the source gateway. To export a policy with the hello-world name:

graphman.sh export --gateway <source-gateway> --using policy --variables.name hello-world --output hello-world.json

Tip

To include the dependencies while using above queries, choose either of the below option

using the query suffix

<folder|service|encass|policy>:full

using the additional parameter

--variables.includeAllDependencies

Note

Sometimes, complex query execution might get aborted due to the limits imposed for protection. Please adjust the allowed query max depth and complexity using the gateway's system properties. For more information, please check the system properties section of the graphman page.

Get to know about the in-built queries

Every field level method defined in the schema can be used for querying the gateway configuration. For example, you can export a policy by guid as the schema defines policyByGuid field method.

graphman.sh export --gateway <source-gateway> --using policyByGuid --variables.guid <guid>

Please refer to the describe command how to discover the available queries.

Creating your own queries

The folder queries contains other queries you can use. Each query is defined in a .gql file and corresponding .json files to wrap the query and its variables. You will notice some of the .gql files contain raw graphql syntax (such as the example policy.gql) whereas others leverage a metadata mechanism that centralizes the definition of which properties to use per entity type.

You can add your own queries by creating your own combo .gql and .json files. The .gql can contain any GraphQL syntax that you paste from Postman for example.

For example, let's create a customized query to export all the internal services.

• create two files in the queries folder with a common name as internal-services.
• internal-services.json

  {
    "query": "{{internal-services.gql}}",
    "variables": {}
  }
  

• internal-services.gql

  query internalServices($includeSoap: Boolean = false) {
    servicesByType1: servicesByType(serviceType: INTERNAL_SOAP) @include(if: $includeSoap) {
      goid
      guid
      name
      resolutionPath
      checksum
    }
    servicesByType2: servicesByType(serviceType: INTERNAL_WEB_API) {
      goid
      guid
      name
      resolutionPath
      checksum
    }
  }
  

• Now, try using it at export command
  • graphman.sh export --using internal-services
  • graphman.sh export --using internal-services --variables.includeSoap
• When you want to specify all the fields, there's an alternative way of describing the fields for simplicity. You just need to specify the GraphQL entity type name so that it will be expanded to the fields.
  • internal-services.gql

  query internalServices($includeSoap: Boolean = false) {
    servicesByType1: servicesByType(serviceType: INTERNAL_SOAP) @include(if: $includeSoap) {
      {{L7Service}}
    }
    servicesByType2: servicesByType(serviceType: INTERNAL_WEB_API) {
      {{L7Service}}
    }
  }
  

Using schema command

This command let you know the available GraphQL entity types.

graphman.sh schema

Output from the command is useful to know about the supported GraphQL entity types. For example, cluster properties are one of the gateway configuration entities.

• ClusterProperty is the GraphQL entity type, whereas clusterProperties is the reference name.
• GraphQL type names are used in writing queries. These names are in PascalCasing, singular form.
• Whereas, reference names are used in bundles and CLI arguments. These names are in CamelCasing, plural form.
• Bundle groups the similar entities by their type, in which these reference names are used to refer the group.

Using describe command

Use this command to discover the available queries and their arguments.

Below command displays all the available queries

graphman.sh describe

Use --query argument with wild-card pattern to look for the interested queries

graphman.sh describe --query service*

Use --query argument with a specific query name to get to know more about it

graphman.sh describe --query serviceByResolversAndRevision

Using import command

Use this command to import a specified gateway configuration bundle to a target gateway.

graphman.sh import --gateway <target-gateway> --input hello-world.json

You can specify the policy revision comment when you import bundles.

graphman.sh import --gateway <target-gateway> --input hello-world.json --options.comment "hellow-world patch v1.2.34"

It is recommended to install/delete bundles using the standard bundle operations. Standard mutation operations cover all the supported entity types and take care of their mutations in their order of dependency. Of course, the default mutation-based query is install-bundle.

graphman.sh import --gateway <target-gateway> --using install-bundle --input hello-world.json

graphman.sh import --gateway <target-gateway> --using delete-bundle --input hello-world.json

By default, mutation action is NEW_OR_UPDATE. You can override this using --bundleDefaultAction option.

graphman.sh import --gateway <target-gateway> --input hello-world.json --options.bundleDefaultAction NEW_OR_EXISTING

Note

Permitted entity mapping actions are:

• NEW_OR_UPDATE
• NEW_OR_EXISTING
• ALWAYS_CREATE_NEW
• DELETE
• IGNORE

You can override mutation actions if exists using --mappings option. For example, delete a bundle excluding the keys and trustedCerts.

graphman.sh import --gateway <target-gateway> --using delete-bundle --input hello-world.json --options.mappings.action DELETE --options.mappings.keys.action IGNORE --options.mappings.trustedCerts.action IGNORE

In case if you are interested to migrate policies and services along with their revisions, try importing the bundle with the revisions with the migratePolicyRevisions option.

graphman.sh import --gateway <target-gateway> --input hello-world-with-policy-revisions.json --options.migratePolicyRevisions

Using mappings command

Sometimes, we may require greater level of control over the bundle mutations. For which, one can take advantage of the mappings to specify the mutation actions at the entity level. mappings command helps us to generate the mapping instructions with fine level of control.

Generate mapping instructions at the bundled entity level.

graphman.sh mappings --input hello-world.json --mappings.action NEW_OR_EXISTING --mappings.level 2

Generate entity level mapping instructions for services alone

graphman.sh mappings --input hello-world.json --mappings.action NEW_OR_EXISTING --mappings.services.level 2

Generate mapping instructions for multiple entity classes

graphman.sh mappings --input hello-world.json --mappings.services.action NEW_OR_EXISTING --mappings.services.level 2 --mappings.encassConfigs.action IGNORE

Using diff command

To compare the configuration between the gateways or bundles, you can diff them using graphman.

graphman.sh diff --input-source bundle1.json --input-target bundle2.json --output delta.json

The output of diff includes the difference for entities and a mapping of goid conflicts. More precisely, what is to be applied to the target to match it with the source. By default, missing entities and modified entities will be included into the delta. You may choose to remove the extra entities from the target by --options.includeDeletes option.

graphman.sh diff --input-source bundle1.json --input-target bundle2.json --output delta.json --options.includeDeletes

Note

Use '@' prefix to the input parameter for treating it as gateway profile name. Otherwise, it will be considered as bundle file.

Bundle the delta between two gateways

Graphman helps you bundle the delta between two gateways.

You can use the difference between two gateways to produce a configuration bundle that contains this difference. You can use these bundles to bring up to date a target gateway based on its differences with a source gateway.

graphman.sh diff --input-source @<source-gateway> --input-target @<target-gateway> --output delta.json

As the diff command uses the summary bundle for identifying the differences between gateways, resultant delta bundle is loaded with the partial entity details, hence it is not import ready. So, either we should be instructing the diff command to renew the delta entities using the source gateway or renew them separately.

graphman.sh diff --input-source @<source-gateway> --input-target @<target-gateway> --output delta.json --options.renewEntities
  (or)
graphman.sh renew --input delta.json --gateway <source-gateway> --output delta-renewed.json  

Once the differences are identified with full entity details, delta bundle is import ready. After successful import, the target environment should be matching with that of the source gateway.

Report about the differences

Sometimes, you might be curious to observe the differences closely. For which, diff command can be instructed to capture the report.

graphman.sh diff --input-source bundle1.json --input-target bundle2.json --output delta.json --output-report delta-report.json

This report organizes the differences in 4 categories.

• inserts
  • entities from this category are entirely missing from the target environment.
• updates
  • entities from this category are different by one or more fields.
• deletes
  • entities from this category exist with the target environment, but missing from the source. In other words, they can be seen as unwanted entities, hence they are deletable.
• diffs
  • this category exemplifies the updates section such that what portion of the entity is different. All the differences are captured at the entity property level as a linear list.
  • For example:

      "diffs": {
        "services": [
        {
          "resolutionPath": "/some-service",
          "serviceType": "WEB_API",
          "details": [
            {
              "path": "$.checksum",
              "source": "0413eafd68e5b2cc5bd1a0fe6f5bacca861146c3",
              "target": "534c3f33415a355bdd36328ddcc454635c73c9b7"
            },
            {
              "path": "$.tracingEnabled",
              "source": true,
              "target": false
            },
            {
              "path": "$.wssProcessingEnabled",
              "source": true,
              "target": false
            },
            {
              "path": "$.properties[0].value",
              "source": "Hello World!",
              "target": "Hello!"
            }
          ]
        }
      ]
    }
    

Subtracting a bundle from another

You can also use this client to subtract from a first bundle, the entities that exist in a second bundle.

Why would you need to do this? For example, you want to remove an overlap between a framework type configuration from a service and all its dependencies (e.g. you end up with unwanted OTK config entities in a bundle). To perform this operation, use the diff command:

graphman.sh diff --input-source big-bundle.json --input-target what-to-cut.json --output trimmed.json

If you wish to subtract entities from what-to-cut.json even if they are different from big-bundle.json you can remove from checksum property in what-to-cut.json. For example if what-to-cut.json contains:

{
    "keys": [
        {
            "alias": "ssl"
        }
    ],
    "listenPorts": [
        {
            "name": "Default HTTP (8080)"
        },
        {
            "name": "Default HTTPS (8443)"
        },
        {
            "name": "Default HTTPS (9443)"
        },
        {
            "name": "Node HTTPS (2124)"
        }
    ]
}

Then the subtract command will always remove the default ssl key and default listenPorts no matter their value in the source.

Using combine command

You can combine two configuration bundles using the combine command:

graphman.sh combine --inputs bundle1.json bundle2.json --output full.json

Using slice command

You can slice the existing bundle by specifying one or more sections of it.

graphman.sh slice --input some-bundle.json  --sections services policies --output sliced-bundle.json

Because of the --sections argument, only the services and policies will be sliced as a result bundle.

Using renew command

Renews the specified bundle using the gateway. This operation is useful when the specified bundle is outdated or incomplete.

graphman.sh renew --gateway <some-gateway> --input some-bundle.json --output renewed-bundle.json

This operation can be scoped down to one or more sections of the bundle using --sections argument.

graphman.sh renew --gateway <some-gateway> --input some-bundle.json --sections clusterProperties secrets jdbcConnections

Using revise command

Revises the bundle as per the options. This operation is useful

• when the specified bundle has goid/guid references that are out of sync with respect to the target gateway.
• when the specified bundle is defined with the deprecated entity types.

graphman.sh revise --input some-bundle.json --output revised-bundle.json