Messages generated during conversion of APIs to DataPower API Gateway

Reference information about the messages generated by the migration utility commands apicm archive:port-to-apigw and apicm archive:port-to-apigw-v10.

Activity log messages

Entire API/General messages

Policies

Migration utility messages

Miscellaneous messages

Referenced objects

Activity log messages

ACT06 `activity-log` policy set to `activity-log_1.5.0`, converting `activity-log` to `activity-log_1.5.0`.

Explanation

See message text.

Severity

info

ACT07 `activity-log` policy set to `set-variable_2.0.0`, converting `activity-log` to `set-variable_2.0.0`.

Explanation

The activity-log success and error values are saved into context variables. A subsequent log policy will reference these variables, which will generate the analytics log data based upon the desired log level.

Severity

info

ACT09 For `activity-log` policy set to `set-variable_2.0.0`, added a `switch` policy with `log` policies into the API finally clause to utilize the `activity-log` variables that were set.

Explanation

A switch policy determines if the analytics log level should be based upon the success of the API or on error activity-log settings. The context variable set in a prior set-variable policy is used as the log policy log level to gather the appropriate level of data in the analytics log.

Severity

info

Entire API/General messages

API01 The specified API YAML input file is of gateway type `datapower-api-gateway`. This utility accepts only v5-compatible APIs of gateway type `datapower-gateway`.

Explanation

The input API YAML file must be of gateway type datapower-gateway. If the gateway type is datapower-api-gateway, the API does not need to be converted. Any other gateway type is not supported.

Response

Review your input file to confirm that it is v5 compatible.

Severity

error

API02 Input API policy is already version 2.0.0. This version is reserved for API Gateway policies only. Skipping conversion of this policy.

Explanation

The input API YAML file must be of gateway type datapower-gateway. Every policy within that API must be version 1.0.0. Version 2.0.0 policies are reserved for the API Gateway, which should be included only in APIs with gateway type datapower-api-gateway. No conversion is performed for this policy.

Severity

error

API04 Added missing `/` to the front of the basepath.

Explanation

A v5 API with a basepath property value that does not start with a / will have the character / added at the beginning of the basepath property of the API Gateway.

Severity

info

API05 Trailing slashes (`/`) removed from the basepath to conform to the API Gateway specification.

Explanation

A v5 API with a `basepath` property value that is not a / but ends with the / character will have the ending / character removed in the basepath property of the API Gateway.

Response

Calls to the API might need to be updated to conform to the new basepath.

Severity

warn

API06 Changed gateway type to `datapower-api-gateway`.

Explanation

See message text.

Severity

info

API07 Moved `assembly request` into `assembly execute`.

Explanation

Older v5 APIs might include the execute property within an assembly request property. This execute property is moved to the API Gateway assembly`property.

Severity

info

API08 Moved `assembly implementation` into `assembly execute`.

Explanation

Older v5 APIs might include the execute property within an assembly implementation property. This execute property is moved to the API Gateway assembly property.

Severity

info

API09 Moved `assembly response` into `assembly execute`.

Explanation

Older v5 APIs might have the execute property within an assembly response property. This execute property is moved to the API Gateway assembly property.

Severity

info

API10 Removed `x-ibm-gateway-invoke-v4-nomap-emulation` API property and replaced it with a `gatewayscript` policy to conform to the API Gateway specification.

Explanation

This v5 API property applies only to the invoke policy. In API Gateway, this property has been replaced by a gatewayscript policy that will modify the invoke policy response in a similar fashion.

Severity

warn

API11 The API property `x-ibm-gateway-sourcecode-resolve-apic-variables` does not exist in the API Gateway. The property has been removed from the YAML file.

Explanation

This v5 API property is not supported by the API gateway and has been removed. If the x-ibm-gateway-map-resolve-apic-variables property is not set, then the original value of this property will be set into the map option mapResolveApicVariables automatically.

Severity

error

API12 The API property `x-ibm-gateway-reencode-request-params-slash` does not exist in the API Gateway. The property has been removed from the YAML file.

Explanation

This v5 API property only applies to the invoke and proxy policies. In the API Gateway, the functionality of this property has been implemented as an option in the invoke policy.
This change was made for the following reasons.
  • The option is now clearly visible in the invoke policy, making it easy to identify available options.
  • Each use of the invoke policy can now have a different setting.

Severity

error

API13 The API property `x-ibm-gateway-framework-legacy-json-encoding` does not exist in the API Gateway. The property has been removed from the YAML file.

Explanation

This v5 API property is not supported by the API gateway and has been removed. If the value of the x-ibm-gateway-framework-legacy-json-encoding property is present, it will be used by the migration utility when migrating xslt, gatewayscript, and map policy source code to produce the same result as v5 would have produced based upon the property value.

Severity

error

API14 Converted v5-compatible policies to the API Gateway and updated policy versions to 2.0.0.

Explanation

See message text.

Severity

info

API15 The `x-ibm-gateway-api-enforce-response-limits` API property is enabled. Appended `parse` policy to the end of the assembly to parse the JSON response.

Explanation

The v5 API property x-ibm-gateway-api-enforce-response-limits ensures that a JSON response payload is within the defined JSON parser limits. This functionality is emulated in API Gateway by adding a parse policy at the end of the assembly.

Severity

info

API16 Removed the `x-ibm-gateway-api-enforce-response-limits` API property and replaced it with a `parse` policy to conform to the API Gateway specification.

Explanation

The v5 API property x-ibm-gateway-api-enforce-response-limits ensures that a JSON response payload is within the defined JSON parser limits. This functionality is emulated in API Gateway by replacing it with a parse policy.

Severity

info

API17 Setting `x-ibm-soap` to `%s`.

Explanation

The v5 API path does not have a x-ibm-soap property with a soap-action child property, but the schema referenced by this path is for a SOAP document. The x-ibm-soap property is added with a child property of soap-action into this path of the APIgateway. The soap-action property will be determined from the schema encountered.

Severity

info

API18 This `set-variable` policy is used to add the client identification header to the message headers for use by a subsequent `invoke` policy.

Explanation

Typically, the client identification header as defined by the security definition is X-IBM-Client-Id. This header will be removed from the message headers at the start of the API. A set-variable policy will add this header back into the message headers, as the v5 API specifies not to suppress this header from being sent by subsequent invoke policies.

Severity

info

API19 Skipping appending of a `parse` policy for the `x-ibm-gateway-api-enforce-response-limits` API property, as this `parse` policy already exists at the end of the assembly and contains the same `input` and `output` values.

Explanation

See message text.

Severity

info

API20 Added `parse` policy to the beginning of the assembly to parse incoming data.

Explanation

The v5-compatible implementation implicitly parses messages. However, by requiring explicit parsing for every assembly wherever parsing is required, the API Gateway provides greater control over when and how parsing is performed.
The parse policy is added in API Gateway for the following purposes.
  • To explicitly control when parsing occurs.
  • To determine which threat protection settings to apply to a parse.
  • To determine which kinds of output to allow.
  • To determine how to gather metadata from the parse.

By separating the parsing time from the processing time of the assembly, explicit parsing can also enhance performance.

API Gateway has no implicit parsing. The assembly must explicitly parse when parsing is desired, which ensures that the correct limits and input checks are done.

Response

You should retain the added parse policy for any of the following reasons.

  • You need non-well-formed XML or JSON documents to abort and call the catch.
  • The data is still streaming and you need to keep a copy of the data for various reasons.
  • You need to use the payload data with another policy.

If you do not need the parse policy, remove it. If you retain the parse policy, consider the following questions.

  • Which threat protection settings do you want to enforce with this parse policy?
  • Does the use of this parse policy remove the need for an additional parse policy?
  • Do you want to use the metadata from the parse, such as document size and complexity?

Severity

info

API21 Moved catalog specific `x-ibm-gateway-*` API Property: `%s` under catalog: `%s` to API level for further processing.

Explanation

x-ibm-gateway catalog-level properties are not supported in API Gateway. The properties have been moved to the top-level properties section in the API for further processing by the migration utility.

Severity

info

API22 Skipped adding `parse` policy since an adjacent parse of the same properties was already added.

Explanation

The invoke policy might add a parse policy next to it in the assembly. If this parse policy is detected, another parse is not added because it would result in duplicate parses in the assembly. This prevention of duplicate parses applies only if both parses are found to have the same properties.

Severity

info

API23 Removed redundant `parse` policy from end of the assembly.

Explanation

The tool added a duplicate parse policy to the end of the assembly. The duplicate policy has been removed as it performs the same action as another parse policy in the assembly.

Severity

info

API24 Removed redundant `parse` policy from the beginning of the assembly.

Explanation

The tool added a duplicate parse policy to the beginning of the assembly. The duplicate policy has been removed as it performs the same action as another parse policy in the assembly.

Severity

info

API25 Removed unsupported `name` property from the Swagger info property.

Explanation

An empty name property under the info property is not supported in API Gateway. If an API is published with an empty name property, an error is generated. Therefore, the migration utility removes the empty name property if it is found.

Severity

info

API26 Removed empty `description` property from the Swagger info property.

Explanation

An empty description property is not supported in API Gateway. If an API is published with an empty description property, an error is generated. Therefore, the migration utility removes the empty description property if it is found.

Severity

info

API27 Removed empty `security` property from the Swagger file.

Explanation

An empty object security property is not supported in API Gateway. If an API is published with an empty object security property, an error is generated. Therefore, the migration utility removes the empty object security property if it is found.

Severity

info

API28 Moved `%s` from API properties to this policy option `%s` and set to [%s].

Explanation

In the API Gateway, the functionality of this property has been implemented as a policy option.

Severity

info

API29 Preserved API Property `%s` in YAML.

Explanation

The API property was preserved because there is a 1.0.0 or 1.5.0 policy that requires it.

Severity

info

API30 Removed API Property `%s` from YAML.

Explanation

This property is obsolete and has been removed from the YAML file.

Severity

info

API31 The API property `x-ibm-gateway-custom-policy-with-gws-action` does not exist in the API Gateway. The property has been removed from the YAML file.

Explanation

In v10, this property is not required to control the behavior of a custom policy that includes a GatewayScript action, as both true and false scenarios are handled as expected.

Severity

error

API32 The `$ref %s` was not found in the swagger.

Explanation

A $ref could not be dereferenced because the reference content was not found in the v5 YAML.

Response

Review the v5 file to confirm that the $ref references are valid and exist in the YAML.

Severity

warn

API33 Found usage of inline parameters: `%s` in `%s` policy.

Explanation

API Gateway does not support inline parameters in the Gatewayscript 2.0.0 or XSLT 2.0.0 policies.

Response

Modify the policy to use context variables instead of inline parameters. The following tables show examples of inline parameters in v5 and how they can be rewritten to use context variables in API Gateway.
Table 1. GatewayScript 2.0.0 examples
v5 API Gateway
If test.data is a variable:

$(test.data)

 context.get('test.data');
If test.body is a message:

$(test.body)

 context.getMessage('test').body;
{test.example} context.get('request.parameters.test.example')

For more GatewayScript 2.0.0 examples, see Using context variables in GatewayScript and XSLT policies with the DataPower API Gateway.

Table 2. XSLT 2.0.0 example
v5 API Gateway
$(request.parameters.example) apigw:get-variable('request.parameters.example')
Note: Be sure to use the apigw namespace.
{example} apigw:get-variable('request.parameters.example')

For more XSLT 2.0.0 examples, see Using context variables in GatewayScript and XSLT policies with the DataPower API Gateway.

Severity

error

API34 Found `x-ibm-gateway-*` catalog specific property: `%s` under catalog section: `%s`, within an unpublished API.

Explanation

The API was most likely found under the drafts folder of an organization. Because it is not published to a specific catalog, the migration utility cannot determine which API to apply the properties to.

Response

Apply the x-ibm-gateway-* properties to the policies of the assembly manually before publishing.

Severity

info

API35 Found `x-ibm-gateway-*` catalog specific property: `%s` under catalog section: `%s`. This API is published under catalog: `%s`

Explanation

The API is published to a specific catalog, and other catalog-specific x-ibm-gateway-* properties were found under other catalogs.

Response

If you want to move this API to other catalogs, apply these properties manually to the policies in the assembly.

Severity

info

API36 `x-ibm-gateway-*` API Property: `%s` found to have invalid value: `%s`.

Explanation

See message text.

Response

Check the API to ensure that the API property has the correct value. For more information on the API property, see the appropriate section of the IBM API Connect Knowledge Center.

Severity

error

API37 JSON Schema contains an invalid reference.

Explanation

See message text.

Response

Confirm that your schema definitions are valid. If you find errors, fix them.

Severity

info

API38 XSD generation ignoring references beyond limit set by property.

Explanation

XSD generation from JSON schema uses the x-ibm-gateway-schema-definition-reference-limit property value to determine how many recursions to go in circular references.

Response

Severity

info

API39 An error occurred while generating the XSD for `%s` definition.

Explanation

See message text.

Response

Confirm that your JSON schema is valid before continuing.

Severity

warn

API40 Skipping JSON Schema definition: `%s` with multiple roots or not intended for XML data.

Explanation

See message text.

Severity

info

API41 Set `chunked-uploads` value to `false` to emulate v5 behavior.

Explanation

For information about the Allow chunked uploads property in the Invoke policy, see Invoke.

Severity

info

API42 Input option `chunked-uploads` set to `true`, which is the API Gateway `chunked-uploads` default. All invoke and proxy 1.5.0 and 2.0.0 policies will use this default value.

Explanation

For information about the Allow chunked uploads property in the Invoke policy, see Invoke.

Severity

info

API43 Created `compatibility:` section for API-wide toggles set by migration utility.

Explanation

The migration utility generates a compatibility section that allows DataPower to read in custom settings to for compatibility between v5 and API Gateway.

Severity

info

API44 Set compatibility toggle `%s` to value: `%s`.

Explanation

See message text.

Severity

info

API45 Compatibility toggle: `%s` set to value: `%s`, which is the same as the API Gateway default.

Explanation

The migration utility input specified to set a compatibility toggle to a value that is already the default. Therefore, no change was made in the API as the default will automatically be used.

Severity

info

API46 Updated `securityDefinition`: `%s` with new name: `%s` as specified in toggle input: `%s`.

Explanation

See message text.

Severity

info

API47 `application-authentication` was found to be set, adding `application-authentication-source` and `custom-header-name` defaults.

Explanation

In v5, application-authentication-source does not exist. In API Gateway, it is a new option that must be set if authentication is set. Therefore, the migration utility automatically sets application-authentication-source to its most-compatible default, and as a result also sets custom-header-name. If application-authentication is not set in the v5 API, the migration utility does not set application-authentication-source and custom-header-name.

Severity

info

API48 `%s` found in API definition `%s`, changing the value to a string null.

Explanation

See message text.

Severity

info

API49 Changed `$(request.body*)` to `$(request.parsed_body*)` in: `%s` to use parsed copy of data.

Explanation

In the API Gateway, the request.body context is never parsed and cannot be evaluated. The parse policy added to the beginning of the assembly automatically copies request.body into request.parsed_body and parses that copy. The reference to request.body has been changed to use this new context.

Severity

warn

API51 Added missing path parameter definition for path `%s` operation `%s` parameter `%s`.

Explanation

See message text.

Severity

info

API52 Added missing path parameter reference for path `%s` operation `%s` parameter `%s`.

Explanation

See message text.

Severity

info

API53 A path parameter reference `%s` is not a path parameter.

Explanation

See message text.

Severity

warn

API54 A parameter reference `%s` is not defined.

Explanation

See message text.

Severity

warn

API55 Definition: %s is missing property 'Body' or 'properties', this is an invalid SOAP definition.

Explanation

The structure of the SOAP definition is invalid. For example, if the definition contains a SOAP fault that is not within the SOAP body, then the definition is invalid.

Severity

error

API56 Catalog specific API Property found without a corresponding default property: %s for catalog: %s, created empty string default property at the API level.

Explanation

See message text.

Severity

info

API57 Definition reference: %s is incorrect, and should be a string of form '#/definitions/foo' where 'foo' is an existing definition

Explanation

See message text.

Response

For example, the following reference is invalid:
moreDetails:
           $ref: '#definitions/MoreDetails'
To make this a valid reference, use the following form:
moreDetails:
           $ref: '#/definitions/MoreDetails'

Severity

error

API58 `securityDefinition` property encountered without a `security` property. An empty `security` property is added.

Explanation

See message text.

Severity

info

API59 The missing referenced definition `%s` was added to the swagger.

Explanation

See message text.

Severity

info

API60 The API property name `%s` is invalid and has been removed from the swagger.

Explanation

API properties with an invalid characters such as $ and parentheses are ignored.

Severity

info

API61 Set buffering property to true.

Explanation

APIs will always have buffering enabled, as v5 did not support streaming.

Severity

info

API62 A query based security definition `%s` was present. A new security definition `%s` was created to match implicit v5 behavior.

Explanation

The security definitions in v5 for an API key that was specified as a query parameter were configured using the key names client_id and client_secret. However, this behavior implicitly provided the ability to also use query parameters app_id and app_secret. The specification of app_id and app_secret must be done explicitly in v10.

Severity

info

API63 A security set was created with security definition references `%s` to match implicit v5 behavior.

Explanation

The security definitions in v5 for an API key that was specified as a query parameter were configured using the key names client_id and client_secret. However, this behavior implicitly provided the ability to also use query parameters app_id and app_secret. The specification of app_id and app_secret must be done explicitly in v10.

Severity

info

API64 Suffix %s appended to API `version`.

Explanation

See message text.

Severity

info

API65 The referenced definition %s was changed to %s.

Explanation

The referenced definition contained a / character in the name and was not defined in the API. The / character has been removed to allow the API to publish during archive:push.

Severity

info

API66 Security has been removed as there are no associated security definitions.

Explanation

The API security is extraneous without associated security definitions.

Severity

info

API67 The API property `x-ibm-gateway-framework-preserve-escaped-reverse-solidus` does not exist in the API Gateway. The property has been removed from the YAML file.

Explanation

This v5 API property is not supported by the API gateway and has been removed. If the x-ibm-gateway-framework-preserve-escaped-reverse-solidus API property is present with a true value, it will be used by the migration utility when migrating xslt, gatewayscript, and map policy source code to produce the same result as v5 would have produced.

Severity

info

API68 For path %s, the property name %s is invalid and has been removed from the swagger.

Explanation

A property of an API path that has a null value is invalid and will be removed from the path.

Severity

info

Policies

GatewayScript policy messages

GWS02 This `gatewayscript` policy was added before the newly converted `switch` policy in the assembly to assist with the condition logic.

Explanation
A conditional policy from a v5 API is converted to a switch policy in the API Gateway. The v5 API uses GatewayScript for the if and switch policies, whereas the API Gateway condition syntax is JSONata based. These conditions have been moved into a gatewayscript policy that will execute immediately before the switch policy. The switch conditions will use results from the gatewayscript policy to execute the correct assembly path.
Response
Review the changes to ensure that the switch policy result will be consistent with the v5 API.
Severity
info

GWS04 Found `gatewayscript` policy. Porting might be required.

Explanation
Review the `gatewayscript` policy and make any necessary changes. The following list includes examples of some of the differences between gatewayscript code in v5-compatible APIs and API Gateway.
  • Calls that reference the request.parameters context variable in v5-compatible APIs might not produce the same results in API Gateway. For example, consider the following call in a v5-compatible API.
    apim.getvariable('request.parameters.org_name')
    This call is not equivalent to the following call in an API Gateway API.
    context.get('request.parameters.org_name')
    The context.get() call in API Gateway supports multiple occurrences of the same parameter variable. Therefore, it returns structured JSON for retrieving parameters, as in the following example return.
    "{\"locations\":[\"query\"],\"values\":[\"sandbox-test-org\"]}"
    For this example, the apim.getvariable call should be changed to the following call in API Gateway.
    ((context.get('request.parameters.org_name)  || {}).values || []).slice(-1)[0]
  • Access to header-metadata is not supported in API Gateway. In some cases, the call can be edited to conform to the API Gateway specification. For example, the call hm.current.remove("Accept-Encoding"); can be replaced in API Gateway with context.message.header.remove("message.headers.Accept-Encoding") or context.clear("message.headers.Accept-Encoding").

    However, if you are using header-metadata to set the response message header before the proxy policy, you must add a gatewayscript policy after the invoke policy to set the header on the response message.

  • In v5 and in v10 API Gateway, apim.getvariable() returns an XML node set if an XML node set was set in the variable being retrieved. In v10 API Gateway, context.get() always returns an XML document, even if an xml node set was set in the variable. The API may require modification to work properly.
  • In both v5 and v10 API Gateway, using the apim.getvariable() function on XML data returns an XML NodeList object. In v10 API Gateway, using the context.get() function on XML data returns an XML document. Consider this change before switching to context.get() using the optimize-gws migration configuration option, as API behavior may change as a result.
Severity
warn

GWS05 Added `require(`apim`)` function to `gatewayscript` policy to conform to the API Gateway specification.

Explanation
See message text.
Response
Review the changes to ensure that the gatewayscript policy result will be consistent with the v5 API.
Severity
info

GWS06 Found `require('header-metadata');` in the `gatewayscript` source.

Explanation
The header-metadata module is not supported in the API Gateway. All API context variables in the API Gateway are in the global context module. You can access the context variables directly using context.set() or context.get().

For more information about using context variables in gatewayscript policies in API Gateway, see Using context variables in GatewayScript and XSLT policies with the DataPower API Gateway.

Response
For better performance, either use the --optimize-gws=true toggle when running the migration utility, or use the context module for native API Gateway performance. For more information about header-metadata, see Access to the headers object in the IBM DataPower Gateways documentation.
Severity
info

GWS07 Replaced `require('local:///isp/policy/apim.custom.js')` with `require('apim')` to conform to the API Gateway specification.

Explanation
The v5 gatewayscript compatibility module does not exist on the local file system in the API Gateway. The require function for this module was present in the gatewayscript code and has been changed for API Gateway compatibility.
Severity
info

GWS08 Empty source `gatewayscript` found.

Explanation
See message text.
Response
Consider updating the empty gatewayscript policy or remove it from the assembly for better performance.
Severity
warn

GWS09 Found `require('fs')` in the `gatewayscript` source.

Explanation
The fs module is supported in the API Gateway. Some API Gateway configuration folders have restricted access.
Severity
info

GWS10 Found `require('service-metadata')` in the `gatewayscript` source.

Explanation
See message text.
Response
The Gatewayscript examples in the following table show how the service variables map to API Gateway metric functions. To obtain the metric data, use the getMetricData() API of the context.metric object in DataPower API Gateway, as in the following example.
var md = context.metric.getMetricData();
For more information about the context.metric object, see context.metric object for API Gateway services in the IBM DataPower Gateways documentation.
v5 MPGW service variable Gatewayscript example Description
dp:variable('var://service/time-response-complete') md.filter(n => n.type === 'assembly-invoke').slice(-1).endTime The end time of the last assembly-invoke metric data.
dp:variable('var://service/time-elapsed') md.slice(-1).endTime The end time of the last element in the metric data array.
dp:variable('var://service/time-forwarded') md.filter(n => n.type === 'assembly-invoke').slice(-1).requestTime The request time of the last assembly-invoke metric data.
dp:variable('var://service/URL-out') md.filter(n => n.type === 'assembly-invoke').slice(-1).targetURL The target URL of the last assembly-invoke metric data.
dp:variable('var://service/mpgw/request-size') md.filter(n => n.type === 'assembly-invoke').slice(-1).requestSize The request size of the last assembly-invoke metric data.
dp:variable('var://service/mpgw/response-size') md.filter(n => n.type === 'assembly-invoke').slice(-1).responseSize The response size of the last assembly-invoke metric data.
Severity
info

GWS11 Found `require('mgmt')` in the `gatewayscript` source.

Explanation
The mgmt module is not supported in the API Gateway.
Response
Remove use of the mgmt module from the source code.
Severity
error

GWS12 Found `require('policy/policy-utility')` or `require('policy/policy-utility.js')` in the `gatewayscript` source.

Explanation
policy-utility is a DataPower module that is not supported in the API Gateway.
Response
Remove use of the policy-utility module from the source code.
Severity
error

GWS18 Found `gatewayscript` containing session function: `%s` and replaced with API Gateway native `%s`

Explanation
See message text.
Severity
info

GWS19 Invalid `gatewayscript` found. The gateway script could not be parsed due to `%s`

Explanation
See message text.
Severity
warn

GWS20 Found `gatewayscript` containing apim function: `%s`. No replacement was performed. The closest match is '%s', but it may not work in all situations.

Explanation
See message text.
Severity
warn

GWS21 Found `gatewayscript` containing session context function: `%s`. No replacement was performed. The closest match is '%s', but it may not work in all situations.

Explanation
See message text.
Severity
warn

GWS22 Found `gatewayscript` containing: `%s` and replaced with API Gateway equivalent context var of: `%s`

Explanation
The following context variable names differ between v5 and v10 API Gateway. The migration utility replaces the v5 variable name with the equivalent v10 API Gateway variable name. For more information, see API Connect context variables.
v5 context variable v10 API Gateway context variable
env.path api.catalog.path
env.name api.catalog.name
client.app.type client.app.lifecycle-state
Severity
info

GWS24 Found gatewayscript policy containing api.document. Adding a gatewayscript policy to populate the api.document context.

Explanation
The migration utility added a gatewayscript policy before the gatewayscript policy that contains api.document. The additional gatewayscript policy is required to populate the api.document context.
Severity
info

GWS25 Replaced TLS Profile name `webapi-sslcli-mgmt` or `api-sslcli-all` with default TLS profile name `api-ssl-client-all` to conform to the API Gateway specification.

Explanation
See message text.
Severity
info

GWS26 Removed %s `\\` characters to conform to the API Gateway specification.

Explanation
The processing of v5 API metadata would implicitly remove extraneous \\ characters. The source property of the gatewayscript policy has been changed to removed these characters as they would have been removed in v5.
Severity
info

Invoke policy messages

INV01 Moved `x-ibm-gateway-decode-request-params` from API properties to each `invoke` policy.

Explanation
This v5 API property only applies to the invoke and proxy policies. In API Gateway, the functionality of this property is implemented as an option in the invoke policy.
 This change was made for the following purposes.
  • The option is now clearly visible in the invoke policy, making it easy to identify available options.
  • Each use of the invoke policy can now have a different setting.
Severity
info

INV02 Moved `x-ibm-gateway-invoke-keep-payload` from API properties to the `keep-payload` `invoke` property where applicable.

Explanation
This v5 API property applies only to the invoke policy. In API Gateway, the functionality of this property is implemented as an option in the invoke policy. 
This change was made for the following purposes:
  • The option is now clearly visible in the invoke policy, making it easy to identify available options.
  • Each use of the invoke policy can now have a different setting.
Severity
warn

INV03 Moved `x-ibm-gateway-queryparam-encode-plus-char` from API properties to each `invoke` policy.

Explanation
This API property only applies to the Invoke policy. In API gateway, this property is an option in the Invoke policy.
This change was made for the following purposes:
  • The option is now clearly visible on the invoke policy, making it easy to identify available options.
  • Each use of the invoke policy can now have a different setting.
Severity
info

INV04 Added `parse` policy immediately after the `invoke` policy to parse the `invoke` output.

Explanation
The invoke policy output context in the API Gateway is not parsed. For compatibility with the v5 API, the invoke policy output context will be explicitly parsed by a parse policy that has been added to execute immediately after the invoke policy.
Severity
info

INV05 Removed `x-ibm-gateway-invoke-suppress-clientid` API property from the YAML file and replaced it with allowlists and blocklists to conform to the API Gateway specification.

Explanation
This v5 API property applies only to the invoke policy. In API Gateway, the functionality of this property is implemented as an option in the invoke policy. 
This change was made for the following purposes:
  • The option is now clearly visible in the invoke policy, making it easy to identify available options.
  • Each use of the invoke policy can now have a different setting.
Severity
warn

INV06 Found `invoke` policy. Converted to API Gateway `invoke` policy.

Explanation
See message text.
Severity
info

INV07 The API property `x-ibm-gateway-invoke-emulate-v4-soap-error` does not exist in the API Gateway.

Explanation
A x-ibm-gateway-invoke-emulate-v4-soap-error property was found. This property does not exist in the API gateway.
Response
Remove the x-ibm-gateway-invoke-emulate-v4-soap-error property from the API.
Severity
error

INV08 Incorrect timeout value of `%s` found in `%s` policy, updated to `60` seconds.

Explanation
The timeout property of the v5 invoke policy is invalid. It must be a numeric data type. It has been set to the default value of 60.
Response
Correct the timeout value if the default value does not satisfy the requirements of the policy.
Severity
info

INV09 Renamed the `keepPayload` property in the `invoke` policy to `keep-payload`.

Explanation
See message text.
Severity
info

INV10 `X-IBM-Client-Id` HTTP header suppressed using header-control blocklist, as the `x-ibm-gateway-invoke-suppress-clientid` property is undefined or not set in the v5-compatible YAML input file.

Explanation
The v5 default behavior was to not send the X-IBM-Client-Id HTTP header to the invoke target. The x-ibm-gateway-invoke-suppress-clientid is not provided, so the header will not be sent. The API Gateway accomplishes this behavior by adding the header to the invoke policy header-control blocklist.
Severity
info

INV11 `X-IBM-Client-Id` HTTP header suppressed using header-control blocklist, as the `x-ibm-gateway-invoke-suppress-clientid` property is set to `true` in the v5-compatible YAML input file.

Explanation
The v5 default behavior was to not send the X-IBM-Client-Id HTTP header to the invoke target. The x-ibm-gateway-invoke-suppress-clientid property is provided with a value of true, so the header will not be sent. The API Gateway accomplishes this behavior by adding the header to the invoke policy header-control blocklist.
Severity
info

INV12 Removed `x-ibm-gateway-optimize-invoke` API property from the YAML file and converted the `invoke` policy to conform to the API Gateway specification.

Explanation
This v5 API property is not supported by the API Gateway.
Severity
info

INV13 Added `set-variable` policy to preserve `X-IBM-Client-Id` HTTP header before the `invoke` policy, as `x-ibm-gateway-invoke-suppress-clientid` is set to `false` in the v5c YAML input file.

Explanation
By default in the API Gateway, the X-IBM-Client-Id HTTP header is not copied from the inbound request headers to the message context headers used by the invoke policy. This request header will be copied to the message context headers so that it will be available to be sent by the invoke policy.
Severity
warn

INV14 Added `gatewayscript` policy for `x-ibm-gateway-invoke-v4-nomap-emulation` as the property is set to `true` in the v5-compatible YAML input file.

Explanation
The v5 invoke policy used this property internally, but this behavior is not supported by the API Gateway invoke policy. A gatewayscript policy that implements the behavior of this v5 API property has been added to execute after the invoke policy.
Severity
info

INV15 Invoke `keep-payload` property has been set to the value of the API property `x-ibm-gateway-invoke-keep-payload`.

Explanation
Although not supported by the v5 UI, a keep-payload property in the invoke policy is always used if present to control this behavior. If not present in the policy, the API property is used instead. The policy property is not present, but the API property is present, therefore the keep-payload property in the API Gateway will use the v5 API property.
Severity
info

INV16 Set `keep-payload` setting to `true`.

Explanation
The keep-payload setting is set based on the following conditions:
  • For an invoke policy that meets all of the following criteria, the keep-payload property is always set to true.
    • The policy is at the end of the assembly.
    • The API property x-ibm-gateway-optimize-invoke is not set to false.
    • The invoke policy does not contain a stop-on-error property.
  • For an invoke policy that does not meet the above criteria, the keep-payload property is set to one of the following values, in order of precedence.
    • The value of keepPayload property, if it is set.
    • The value of the API property x-ibm-gateway-invoke-keep-payload, if it is set.
  • For an invoke policy that meets none of the above criteria, the keep-payload property is not set at all.
  • For a proxy policy, the keep-payload property is always set to true after it is converted to an invoke policy.
Severity
info

INV17 Invoke policy set to `invoke_1.5.0`, converting invoke to `invoke_1.5.0`

Explanation
See message text.
Severity
info

INV18 Set `final-action` parameter on `invoke_1.5.0`

Explanation
If the invoke_1.5.0 policy is last in the assembly, the migration utility adds the final-action parameter, which ensures that the policy sends output to the message context. If invoke_1.5.0 is not last in the assembly, the policy adds a parse after the wrapper policy to parse the output.
Severity
info

JSON-to-XML policy messages

J2X01 Added a `parse` policy to execute before the `json-to-xml` policy.

Explanation
A v5 json-to-xm policy must have the current API Gateway context parsed explicitly prior to execution. The parse policy has been added to execute before the json-to-xml policy.
Severity
info

J2X02 Found `json-to-xml` policy and converted to API Gateway `json-to-xml`.

Explanation
See message text.
Severity
info

JWT-Generate policy messages

JTG01 JWE properties are missing in the `jwt-generate policy`, so encryption has been disabled.

Explanation
If jwe-enc or jwe-alg is specified, then at least one of jwe-jwk and jwe-crypto must also be specified.
Severity
warn

JTG02 JWS property is missing in the `jwt-generate policy`, so signing has been disabled.

Explanation
If jws-alg is specified, at least one of jws-jwk or jws-crypto must also be specified.

A private key must be specified, which can be either a JSON web key or a cypto object.

Severity
warn

JTG03 Converted the `jwt-generate` policy to the API Gateway `jwt-generate` policy .

Explanation
See message text.
Severity
info

LTPA-Generate policy messages

LTPA01 Found v5-compatible `ltpa-generate` policy. Because this policy does not exist in the API Gateway, it is unchanged.

Explanation
The ltpa-generate policy is not available in the API Gateway.
Response
Remove the ltpa-generate policy from the API.
Severity
error

Map policy messages

MAP01 "Moved `%s` from API properties to each `map` policy as map option: `%s`."

Explanation
This v5 API property applies only to the map policy. In API Gateway, the functionality of this property is implemented as an option in the map policy.
This change was made for the following purposes.
  • The option is now clearly visible on the map policy, making it easy to identify available options.
  • Each use of the map policy can now have a different setting.
Severity
info

MAP02 Replaced %s with %s to conform to the API Gateway syntax specification.

Explanation
API Connect Version 5 treats a map value property with a string quoted with \" or \\\" as the same, specifically as a double quote. This is not supported in the API Gateway. The \\\ is converted to a single \.
Severity
info

MAP03 Converted `map` to API Gateway `map` for conformance."

Explanation
See message text.
Severity
info

MAP04 Set `map` option of `mapResolveApicVariables` to previous default of `true` for compatibility.

Explanation
If a map policy is found to not have mapResolveApicVariables set, the option is set to true to maintain backwards compatibility.
Severity
info

MAP05 Set `map` option of `mapParseXMLOutput` to `true` for compatibility.

Explanation
This property is always set by the migration utility to maintain compatibility with v5. If XML data is output from the `map_2.0.0` policy, then the data is parsed before it reaches <output>.body.
Severity
info

MAP06 Removed %s `\\` characters to conform to the API Gateway specification.

Explanation
The processing of v5 API metadata would implicitly remove extraneous \\ characters. The value properties of the map policy action have been changed to remove these characters as they would have been removed in v5.
Severity
info

Proxy policy messages

PRX01 Found `proxy` policy and converted to API Gateway `invoke` policy, as `proxy` does not exist in the API Gateway.

Explanation
A proxy policy was found. The policy was converted to an invoke policy in the API gateway.
Response
Review the changes to ensure that the invoke policy result will be consistent with the v5 API. Alternatively, you can specify that the migration utility convert proxy policies to proxy_1.5.0, which is a backward-compatible policy available in the API Gateway.
Severity
info

PRX02 Removed `x-ibm-gateway-proxy-suppress-clientid` API property from the YAML file and replaced it with allowlists and blocklists to conform to the API Gateway specification.

Explanation
This v5 API property applies only to the proxy policy. In the API Gateway, this property is represented by the header control and parameter control options in the invoke policy to either allow or restrict the X-IBM-Client-Id header or client_id parameter being sent to the backend server.
This change was made for the following reasons.
  • The option is now clearly visible in the invoke policy, making it easy to identify available options.
  • Each use of the invoke policy can now have a different setting.
Severity
warn

PRX03 Set policy `title` to `invoke` as this is now an `invoke` policy.

Explanation
The functionality of the v5 invoke and proxy policies has been merged into the API Gateway invoke policy. The title property of the policy was changed to invoke.
Severity
info

PRX04 Proxy: Changed `No-Cache` to lowercase `no-cache`.

Explanation
See message text.
Severity
info

PRX05 Proxy: Changed `Time-to-Live` to lowercase `time-to-live`.

Explanation
See message text.
Severity
info

PRX06 Proxy: Changed `Protocol-Based` to lowercase `protocol`.

Explanation
See message text.
Severity
info

PRX07 `client_id` query parameter suppressed using parameter-control blocklist, as `x-ibm-gateway-proxy-suppress-clientid` is set to `true` in the v5-compatible YAML input file.

Explanation
The v5 default behavior is to send the client_id query parameter to the proxy target. The x-ibm-gateway-proxy-suppress-clientid property was provided with a value of true, indicating not to send this query parameter. The API Gateway accomplishes this behavior by adding this query parameter name to the parameter-control blocklist of the policy.
Severity
info

PRX08 `X-IBM-Client-Id` HTTP header suppressed using header-control blocklist, as `x-ibm-gateway-proxy-suppress-clientid` is set to `true` in the v5-compatible YAML input file.

Explanation
The v5 default behavior was to not send the X-IBM-Client-Id HTTP header to the proxy target. The x-ibm-gateway-proxy-suppress-clientid property was provided with a value of true, indicating not to send this HTTP header. The API Gateway accomplishes this behavior by adding this header name to the header-control blocklist of the policy.
Severity
info

PRX09 `X-IBM-Client-Id` HTTP header suppressed using header-control blocklist, as `x-ibm-gateway-proxy-suppress-clientid` is undefined or not set in the v5-compatible YAML input file.

Explanation
The v5 default behavior was to not send the X-IBM-Client-Id HTTP header to the proxy target. The x-ibm-gateway-proxy-suppress-clientid property was not provided, indicating not to send this HTTP header. The API Gateway accomplishes this behavior by adding this header name to the header-control blocklist of the policy.
Severity
info

PRX10 `client_id` not suppressed in query parameter, as `x-ibm-gateway-proxy-suppress-clientid` is undefined or not set in the v5-compatible YAML input file.

Explanation
The v5 default behavior was to send the client_id query parameter to the proxy target. The x-ibm-gateway-proxy-suppress-clientid property was not provided, indicating to send this query parameter. No API Gateway invoke policy configuration is required to emulate this behavior.
Severity
warn

PRX11 `output` deleted as this policy is the last policy in the assembly flow.

Explanation
The v5 proxy API can specify an output context that makes the proxy response available for subsequent policies, but that response was also made available as the API response, should a subsequent policy not update the message context. When the proxy policy is the last policy in the v5 assembly, this output is removed, which allows the API Gateway invoke response to be returned to the client.
Severity
info

PRX12 Added `gatewayscript` policy to copy the proxy policy headers, status, and output to `message` context.

Explanation
A v5 proxy policy that specifies an output response context name is not the last policy in the assembly flow. A gatewayscript policy has been added after the API Gateway invoke policy. The gatewayscript policy copies the contents of the response context to the message context to emulate v5 behavior.

Severity
warn

PRX13 Added `set-variable` policy to preserve `X-IBM-Client-Id` HTTP header immediately before the proxy as `x-ibm-gateway-proxy-suppress-clientid` was set to `false` in the V5-compatible YAML input file.

Explanation
By default in the API Gateway, the X-IBM-Client-Id HTTP header is not copied from the inbound request headers to the message context headers used by the invoke policy. This request header will be copied to the message context headers so that it will be available to be sent by the invoke policy.
Severity
info

PRX14 Proxy policy set to `proxy_1.5.0`, converting proxy to `proxy_1.5.0`

Explanation
See message text.
Severity
info

PRX15 Set `final-action` parameter on `proxy_1.5.0`

Explanation
If the proxy_1.5.0 policy is last in the assembly, the migration utility adds the final-action parameter, which ensures that the policy sends output to the message context. If proxy_1.5.0 is not last in the assembly, the policy adds a parse after the wrapper policy to parse the output.
Severity
info

Redact policy messages

RE01 This API Gateway `redact` policy is added  to contain all v5-compatible `redact` paths targeted against the `request`.

Explanation
To redact the request body, an API Gateway redact policy is placed at the front of the assembly in order to redact incoming data. All redactions in v5c that are not found within a switch, if, or operation-switch component will be moved to this single redact policy.
Response
Review to confirm that this change meets the purpose of the API.
Severity
warn

RE02 API Gateway `redact` policy added to contain all v5-compatible `redact` paths targeted against `response`, `logs`, and `all`.

Explanation

In the API Gateway, response and logs data must be redacted at the end of the assembly. This API Gateway redact policy was added to the end of the assembly to conform to the specification. If logs or all is the v5-compatible target for the redact policy, then a new log policy will be added in gather-only mode to populate the log API context.

The API Gateway emulates the v5-compatible redact on response and logs by adding a redact action at the end of the assembly to redact the response. All redactions in v5c that are not found inside of a switch, if, or operation-switch component will be moved to this single redact policy.

Response
Review to confirm that this change meets the purpose of the API.
Severity
warn

RE03 Found v5-compatible `redact` policy. `action:path` pairs from this policy will be sorted into one or both leading and trailing API Gateway `redact` policies to conform to the API Gateway specification.

Explanation
To emulate the v5 redact on request and response, some of the redact policies must be moved to either the end of the assembly or beginning of the assembly. This change is necessary because the redact policy now works directly on the API context, so it must be placed in a specific order so that it can redact data either before it enters the assembly or after it exits the assembly.
Response
Review the changes to ensure that the redact policy result will be consistent with the v5 API.
Severity
warn

RE04 Found duplicate v5-compatible `redact` path of the same `redact` type. Duplicate item will not be added.

Explanation
Because multiple redactions are consolidated into the leading or trailing redact policy, there might be some paths that are duplicates of current paths in the consolidated redact policy. These paths are not added as they are redundant.
Response
Review the changes to ensure that the redact policy result will be consistent with the v5 API.
Severity
warn

RE05 Redaction on `request` was found in the v5-compatible YAML input file. Added first API Gateway `redact` policy to the front of the assembly after the `parse` policy to perform this redaction.

Explanation
To redact the request body, an API Gateway redact policy is placed at the front of the assembly in order to redact incoming data. All redactions in v5c that are not found within a switch, if, or operation-switch component will be moved to this single redact policy.
Response
Review to confirm that this change meets the purpose of the API.
Severity
info

RE06 Redact on `response`, `logs`, or `all` was found in the v5-compatible YAML input file. Added second API Gateway `redact` to the end of the assembly to perform this redaction. `log` policy also added if redact on `logs` or `all` was found.

Explanation

In the API Gateway, response and logs data must be redacted at the end of the assembly. This API Gateway redact policy was added to the end of the assembly to conform to the specification. If logs or all is the v5-compatible target for the redact policy, then a new log policy will be added in gather-only mode to populate the log API context.

The API Gateway emulates the v5-compatible redact on response and logs by adding a redact action at the end of the assembly to redact the response. All redactions in v5c that are not found inside of a switch, if, or operation-switch component will be moved to this single redact policy.

Response
Review to confirm that this change meets the purpose of the API.
Severity
warn

RE07 Potential JSON v5-compatible `redact` path detected.

Explanation
A v5 redact path has been detected that is highly likely to be targeted against JSON data. It has been converted to a JSONata path because the redact policy in the API Gateway uses JSONata to specify path:.
Response
Review to confirm that the path is meant for JSON data and it is formed properly.
Severity
warn

RE08 XML v5-compatible `redact` path detected. Converted to `redact` XPath: `%s` to JSONata: `%s`.

Explanation
A v5-compatible redact path has been detected that is highly likely to be targeted against XML data. It has been converted to JSONata to meet the API Gateway specification. The redact policy in the API Gateway uses JSONata for path:.
Response
Review to confirm that the path is meant for XML data and it is formed properly. Note that a malformed XPath may still publish on API Connect v10 API Gateway, but will fail subsequent API calls with a 404 API Not found error. The API Definition DataPower object will also be in the [down] state because of the invalid XPath. It is also possible for an invalid XPath to work on v5 but fail on API Gateway. For example, the XPath /test/path/ is invalid because of the trailing slash. However, this XPath will work in v5, and fail with the above scenario in v10 API Gateway.
Severity
warn

RE09 Common `redact` XPath `%s` replaced with JSONata `%s` to adhere to the API Gateway `redact` specification.

Explanation

The redact policy in API Gateway uses JSONata to specify the path:. All v5-compatible redact paths are converted to JSONata.

Response
Review to confirm that the changes conform to the purpose of the redact policy.
Severity
info

RE10 Invalid redact action: `%s` found.

Explanation
A v5-compatible redact policy was found to contain an invalid action type. Valid types include redact or remove.
Response
Review the action type in the redact policy and update to either redact or remove.
Severity
error

RE11 Added `log` policy to populate the `log` API context, because a v5-compatible `redact` policy was found targeted against `logs` or `all`. An API Gateway `redact` policy will be appended after this policy to redact the outgoing `log` data.

Explanation
The API Gateway specification requires a log policy in the assembly to populate the log.request_body and log.response_body context variables. After the log policy, the redact policy will then redact the contents of log.request_body and log.response_body.
Severity
warn

RE12 Added `parse` policy before `redact` policy to parse incoming data.

Explanation
The incoming data must be parsed for the redact policy to work properly. For example, if the incoming data contains unparsed but well-formed XML data, the redact policy does nothing and the data passes through. With this added parse policy, the XML data is parsed properly and the redaction works as expected.
Response
Review the changes to ensure that the redact policy result will be consistent with the v5 API.
Severity
warn

RE13 Found v5-compatible `redact` policy inside of a `switch` policy. Converted all paths to JSONata.

Explanation

If a v5-compatible redact policy is found within a switch, if, or operation-switch component, it will be left in place. If the redaction is on the response and there is an invoke policy at the end of the assembly, problems could arise.

Response
Review and confirm that this redaction conforms to the purpose of the API.
Severity
warn

RE14 Invalid `redact` action found: path is empty.

Explanation
The v5-compatible redact policy was found to have an empty path. This configuration is invalid
Response
To make the API functional, update the path in the redact policy.
Severity
error

Set-Variable policy messages

SV01 Found `set-variable` policy and converted to API Gateway `set-variable` policy.

Explanation
See message text.
Severity
info

SV02 Cannot recognize `set-variable` `action` `%s`. It must be `set`, `add`, or `clear` with a valid variable name.

Explanation
The v5 set-variable policy contains an action that is not set, add, or clear.  The API Gateway set-variable policy should be modified to use the correct settings.
Severity
error

SV05 Required property `type` not found. Added `type` of `any` to conform to the API Gateway specification.

Explanation
The v5 set-variable policy does not have a type property. The type is inherent in the data type of the value. The API Gateway includes this property, which is set to the data type of the value. In conditions where the data type would be determined at runtime (for example, with a variable substitution), the value is set to any.
Response
Consider changing the added type to a more specific type.
Severity
warn

SV06 Required property `type` not found. Added `type` of `%s` to conform to the API Gateway specification, and it is consistent with the provided `value`.

Explanation
See message text.
Severity
info

SV07 The set-variable policy has no valid actions and has been removed from the assembly.

Explanation
See message text.
Severity
info

SV08 The set-variable action name '%s' has spaces in the name. Changing the action name to '%s'.

Explanation
See message text.
Severity
info

Switch policy messages

SW01 Found `operation-switch_1.0.0` and converted to API Gateway `operation-switch_2.0.0`.

Explanation
See message text.
Severity
info

SW03 Found `switch` policy and converted to the API Gateway `switch` policy.

Explanation
A switch policy from a v5 API is converted to an API Gateway switch policy. The v5 API uses GatewayScript syntax for conditions, whereas the API Gateway uses JSONata syntax.  The conditions have been moved to a gatewayscript policy that will execute immediately before the switch policy. The switch conditions will use results from the gatewayscript policy to execute the correct assembly path.
Response
Review the changes to ensure that the switch policy result will be consistent with the v5 API.
Severity
info

SW04 Found `if` policy and converted to API Gateway `switch` policy.

Explanation
An if policy from a v5 API is converted to an API Gateway switch policy. The v5 API uses GatewayScript syntax for conditions, whereas the API Gateway uses JSONata syntax.  The conditions have been moved to a gatewayscript policy that will execute immediately before the switch policy. The switch conditions will use results from the gatewayscript policy to execute the correct assembly path.
Severity
info

SW05 Found `switch` condition: `%s` and converted it to JSONata: `%s` to conform to the API Gateway specification.

Explanation
A v5 switch policy condition was converted directly into a JSONata condition. This condition does not require a gatewayscript policy that would be executed prior to the switch.
Severity
warn

SW06 `switch` condition: `%s` could not be converted to JSONata. (Error code: `%d`).

Explanation
Cannot convert an if/switch condition to JSONata. A GatewayScript policy will be added to handle the Switch logic instead. Changes are needed only if highest performance is desired. See the Response section for more details on performance. This message can appear for the following reasons.
Error code Explanation
1 The auto-generated JSONata mapping file was not found.
2 The condition was not found in the auto-generated JSONata mapping file.
3 The condition resolved to empty.
4 An unknown error occurred
Response
To improve performance, review the condition in the v5 API and provide the JSONata for this condition.

If an indexOf() method is used to determine whether a substring is present in a value, consider using the $contains() JSONata string function . If indexOf() is used to get a substring before or after the match, consider using the substringBefore() or $substringAfter() JSONata string functions.

For more information about using JSONata to write switch conditions, see Writing switch condition scripts - DataPower® API Gateway.

Severity
warn

SW07 `switch` condition: `%s` could not be converted to JSONata or handled by `gatewayscript`.

Explanation
The if/switch condition cannot be converted to JSONata. This error can occur for the following reasons:
  • A condition contains invalid Javascript.
  • The condition contains multiple expressions.
Response
Review the contents of the condition and edit as necessary.
Severity
error

SW08 `switch` policy set to `switch_1.5.0`, converting `switch` to `switch_1.5.0`.

Explanation
See message text.
Severity
info

SW09 `if` policy set to `if_1.5.0`, converting `if` to `if_1.5.0`.

Explanation
See message text.
Severity
info

SW10 Replaced `\\\"` with `\"` %d times to conform to the JavaScript syntax specification.

Explanation
See message text.
Severity
info

SW11 Condition: %s could not be parsed %s.

Explanation
See message text.
Severity
error

SW12 Condition: %s contains inline parameters %s within a string. These references cannot be resolved.

Explanation
See message text.
Severity
error

SW13 Empty switch condition found and will be ignored.

Explanation
See message text.
Severity
info

Throw policy messages

TH01 Found `throw` policy and converted to API Gateway `throw` policy to conform to the API Gateway specification.

Explanation
See message text.
Severity
info

Validate policy messages

VAL01 Found v5-compatible `validate-usernametoken` policy. This policy does not exist in the API Gateway. No action has been taken.

Explanation
A validate-usernametoken policy was found. This policy does not exist in the api gateway and has been ignored.
Response
Remove the validate-usernametoken policy from the API.
Severity
error

VAL02 Converted `validate` policy into an API Gateway `validate` policy.

Explanation
A validate policy was found.
Response
Review the changes to ensure that the validate policy result will be consistent with the v5 API.
Severity
info

VAL03 Found `definition: request` and replaced it with `validate-against: body-param`.

Explanation
The definition property in the v5 validate policy contained a value of request. This value has been changed to a value of body-param in the validate-against property of the API Gateway validate policy.
Severity
info

VAL04 Found `definition: response` and replaced it with `validate-against: response-param`.

Explanation
The definition property of the v5 validate policy contained a value of request. This value has been changed to a value of response-param in the validate-against`property of the API Gateway validate policy.
Severity
info

VAL05 Found `soap-env` `validate` definition and converted it to the API Gateway `xml-schema` property.

Explanation
The definition property in the v5 validate policy references an OpenAPI definition. The definition referenced is for a SOAP document. This value has been changed to a value of url in the validate-against`property in the API Gateway validate policy. The definition property value has been moved to the xml-schema property.
Severity
info

VAL06 Set `xml-validation-mode` to `soap-body`.

Explanation
The definition property in the v5 validate policy references an OpenAPI definition. The definition referenced is for a SOAP document. This value has been changed to a value of url in the validate-against property in the API Gateway validate policy. The xml-validation-mode property value has been set to soap-body.
Severity
info

VAL07 Set `validate-against` to `%s`.

Explanation
The definition property in the v5 validate policy references an OpenAPI definition.  This value has been changed to conform to the API Gateway validate policy property validate-against with a value of definition or url. 
Severity
info

VAL08 Added `parse` policy before `validate` policy.

Explanation
A v5 validate policy that is configured to validate the current context payload against a schema definition must have the input of the current API Gateway context parsed explicitly prior to execution. The parse policy has been added to execute before the validate policy.
Severity
info

WSDL messages

WSDL01 An API created from WSDL does not have the required field `%s`.

Explanation
See message text.
Severity
error

WSDL02 The WSDL file `%s` does not exist. This file is referenced by field `%s`.

Explanation
See message text.
Severity
error

WSDL03 An API created from WSDL has excessive examples. The total length of the examples is %d. This may cause a problem during publish.

Explanation
See message text.
Severity
warn

WSDL04 An API created from WSDL has excessive examples. The total length of the examples is %d. The examples are removed.

Explanation
See message text.
Severity
warn

WSDL05 A severe error occurred while analyzing an API created from WSDL. [%s]

Explanation
See message text.
Severity
error

WSDL06 An error occurred while analyzing an API created from WSDL. [%s]

Explanation
See message text.
Severity
warn

WSDL07 An API created from WSDL has an embedded error, which was issued when the API was originally created. The error may be fixed in the current version of API Connect. You may want to recreate this API from WSDL. The embedded error [%s] is located at `#/x-ibm-configuration/x-ibm-apiconnect-wsdl/messages/error`.

Explanation
See message text.
Severity
warn

WSDL08 An API created from WSDL is updated to use a new zip (%s). The original zip is located at (%s). Unnecessary files have been removed from the new zip.

Explanation
See message text.
Severity
info

WSDL09 An API was created from a WSDL (%s). Analysis indicates that this zip file may contain unnecessary 'xsd' and 'wsdl' files. Removing the unnecessary files could reduce the size of the zip file by %d bytes.

Explanation
See message text.
Severity
info

XML-to-JSON policy messages

X2J01 Added a `parse` policy to execute before the `xml-to-json` policy.

Explanation
A v5 xml-to-json policy must have the current API Gateway context parsed explicitly prior to execution. The parse policy has been added to execute before the xml-to-json policy.
Severity
info

X2J02 Found `xml-to-json` policy and converted to API Gateway `xml-to-json` policy.

Explanation
v5 xml-to-json policies are converted to API Gateway xml-to-json policies.
Note: When a v5 xml-to-json policy that contains the xml:space="preserve" attribute is migrated to API Gateway, spaces are not retained after curly braces, commas, and quotes in the JSON.
Response
Review the JSON and edit as necessary.
Severity
info

XSLT policy messages

XSLT01 Replaced `apim.custom`, `apim.setvariable`, and `webapi-util` with `apim.custom.xsl within xsl import and xsl include statements.

Explanation
The v5 xslt policy code that contains an xsl import or xsl include of v5 framework stylesheets that were found in the local directory of the file system have been changed to use the v5-compatible stylesheet in the store directory of the file system.
Severity
info

XSLT02 Added `parse` policy to execute before the `xslt` policy.

Explanation
A v5 xslt policy that is configured to use the current context payload as input to the stylesheet must have the current API Gateway context parsed explicitly prior to execution. The parse policy has been added to execute before the xslt policy.
Severity
info

XSLT03 Found `xslt` policy. Porting might be required.

Explanation
Review the xslt policy and make any changes required for use in API Gateway.
Response
If you want to use v5-compatible XSLT code in API Gateway, use the API Gateway extension elements and functions to ensure compatibility with API Gateway. Depending on the content of your code, you may need to make the following changes.
  • Remove the apim.setvariable-impl.xsl stylesheet from the XSLT code. This stylesheet is not used in API Gateway. Instead, use the API Gateway extension functions to manipulate the assembly context.
  • Use API Gateway extension elements to manipulate values in the assembly context. The following example uses the apigw:set-header extension element to set the value of the request header.
    <apigw:set-header name="'request'" value="$request" />
  • Use of dp:variable and dp:set-variable functions is not supported in API Gateway. These functions should be changed to apim:getVariable and apim:setVariable. Access to session, service, and system metadata is restricted.

For more information about the API Gateway extension elements and functions, see the IBM DataPower Gateway documentation.

Severity
warn

XSLT04 `xslt` policy set to `xslt_1.0.0`, converting xslt to `xslt_1.0.0`.

Explanation
See message text.
Severity
info

XSLT05 Replaced TLS Profile name `webapi-sslcli-mgmt` or `api-sslcli-all` with default TLS profile name `api-ssl-client-all` to conform to the API Gateway specification.

Explanation
See message text.
Severity
info

XSLT06 Removed %s `\\` characters to conform to the API Gateway specification.

Explanation
The processing of v5 API metadata would implicitly remove extraneous \\ characters. The source property of the xslt policy has been changed to remove these characters as they would have been removed in v5.
Severity
info

Migration utility messages

Catalog property updated with catalog name Message API: {{.APIFile}}, pOrg: {{.ProviderOrg}}: Updated catalogs: property: {{.OldCatalogName}} with catalog name: {{.NewCatalogName}} based on matching catalog title: {{.FoundCatalogTitle}} since API Gateway requires catalog name instead of catalog title in `catalogs:`

Explanation

In v5, the catalogs: property uses names based on the Catalog Title. In API Gateway, the Catalog Name must be used. The Migration Utility attempted to find a matching Catalog Title in the same provider-org as the API, and succeeded. The catalogs: property that formerly used the Catalog Title has been automatically updated by the Migration Utility to use the Catalog Name of the Catalog instead.

Response

Review your API to confirm that the Catalog Name used in the catalogs: property is correct.

Severity

info

Miscellaneous messages

UT01 Invalid suffix provided. Using `-apigw` as the default for API Gateway API `title` and `x-ibm-name`.

Explanation

The provided suffix input was incorrectly formatted. The migration utility uses -apigw as the default suffix. It will be appended to the end of the x-ibm-name and title to maintain uniqueness from the original v5-compatible input API.

Severity

warn

UT02 No API suffix provided. Using `-apigw` as the default for the API Gateway API `title` and `x-ibm-name`.

Explanation

The --suffix option is optional. Because no input was provided, the migration utility defaults to -apigw. This suffix will be appended to the end of the x-ibm-name and title to maintain uniqueness from the v5-compatible input API.

Severity

info

UT03 Input file not found: `%s`, exiting. Verify that the v5-compatible YAML input file exists and is a valid OpenAPI.

Explanation

See message text.

Severity

error

UT04 An error occurred while reading the input file: `%s`. Verify that the v5-compatible YAML input file exists and is a valid OpenAPI.

Explanation

See message text.

Severity

error

UT05 Output directory not found: `%s`, creating it.

Explanation

See message text.

Severity

info

UT06 An error occurred while trying to create the output directory: `%s`. Verify that this utility has sufficient access to the filesystem in order to write to the output directory and file.

Explanation

See message text.

Severity

error

UT07 Finished creating API Gateway API draft from v5-compatible API input file. Attempting to save to output file.

Explanation

See message text.

Severity

info

UT08 Output directory not found: `%s`, exiting. Verify that this utility has sufficient access to the filesystem in order to write to the output directory and file. For further assistance, contact IBM Support.

Explanation

See message text.

Severity

error

UT09 An internal error occurred: `%s`.

Explanation

See message text.

Severity

error

UT10 An internal error occurred processing the condition map: `%s`.

Explanation

See message text.

Severity

error

UT11 Output API Gateway draft API saved as: `%s`.

Explanation

See message text.

Severity

info

UT12 Input v5-compatible API could not be converted. Exiting.

Explanation

See message text.

Severity

error

UT13 An error occurred while processing the v5-compatible input API.

Explanation

See message text.

Severity

error

UT14 An error occurred while converting the v5-compatible input API to API Gateway: `%s`.

Explanation

See message text.

Severity

error

UT15 An error occurred adding a comment to the resultant YAML: `%s`.

Explanation

See message text.

Severity

error

UT16 An error occurred during v5 escaped character emulation parsing the updated source: %s"

Explanation

Contact IBM support.

Severity

error

Referenced objects

OAuth2 messages

OA201 Found OAuth2 security definition using the provider `%s`. The corresponding OAuth provider for type API Gateway must exist on the server.

Explanation
See message text.
Severity
info

OA202 Found OAuth2 security definition with no provider specified. The API Gateway OAuth2 security definition requires a provider to be specified in an `x-ibm-oauth-provider` field.

Explanation
See message text.
Severity
error

TLS-Profile messages

TLS01 Renamed `api-sslcli-all` `tls-profile` to `api-sslcli-client-all` to conform to the API Gateway specification.

Explanation
See message text.
Severity
info

TLS02 Added `1.0.0` as `tls-profile` version to `%s` to conform to API Gateway specification.

Explanation
The API Gateway TLS profiles support versioning. A default version of 1.0.0 has been added to the profile configuration.
Severity
info