Migration Guide

Version 3.0 Release Migration Guide

This guide will highlight the major changes in the SDK and how to update your code accordingly. This release contains new usage patterns for a lot of service. Old usage patterns should still be functional in this release; however, in the next major release, your code will be mandated to use those new usage patterns.

In this major release, several services have been generated from the Swagger specifications of our services. Furthermore, the language has changed from NodeJS to TypeScript for these services. The change of language to TypeScript will not have an impact on NodeJS usage because the published public package contains NodeJS that is the result of transpiling the TypeScript code.

The following services are now being generated programmatically:

• Conversation
• Discovery
• Language Translator
• Natural Language Classifier
• Natural Language Understanding
• Personality Insights
• Text to Speech
• Tone Analyzer
• Speech to Text
• Visual Recognition

It's important to note that with so many of the services being moved to automated generation, there are many minor changes to method names, parameter names, etc. Therefore, this list is not exhaustive. However, we hope that this new approach will result in more consistent, maintainable code going forward.

Directory and Files

In each specific project directory the previous structure was something like

• node-sdk/discovery
  • v1.js

This has been replaced with something like

• node-sdk/discovery
  • v1.ts
  • v1-generated.ts

Where v1.ts is an adapter and v1-generated.ts is the new generated code. After building, there will be compiled files v1.js and v1-generated.js which are the JavaScript compilations of the TypeScript files.

Non generated code and helper methods are found in the /lib folder.

Adapters

Adapters are provided to ensure your old code will not break. These adapters follow the conventions of the v2 NodeSDK such as method names, parameters, etc. and call upon the generated code.

These are named for example for discovery: v1.ts Generated files follow the convention v1-generated.ts

These adapters should not be relied on and will not be supported for future versions and your code should be migrated to use the generated code.

New usage patterns in specific services

Conversation

getIntents

• getIntents is now listIntents

getExamples

• getExamples is now listExamples

getEntities

• getEntities is now listEntities

getValues

• getValues is now listValues

getSynonyms

• getSynonyms is now listSynonyms

getDialogNodes

• getDialogNodes is now listDialogNodes

getLogs

• getLogs is now listLogs

getCounterExamples

• getCounterExamples is now listCounterExamples

updateIntent

• parameter old_intent is now intent
• parameter intent is now new_intent
• parameter description is now new_description
• parameter examples is now new_examples

updateEntity

• parameter old_entity is now entity
• parameter entity is now new_entity
• parameter description is now new_description
• parameter metadata is now new_metadata
• parameter fuzzy_match is now new_fuzzy_match
• parameter values is now new_values

updateValue

• parameter old_value is now value
• parameter value is now new value
• parameter metadata is now new_metadata
• parameter synonyms is now new_synonyms

updateSynonym

• parameter old_synonym is now synonym
• parameter synonym is now new_synonym

updateDialogNode

• parameter old_dialog_node is now dialog_node
• parameter dialog_node is now new_dialog_node
• parameter description is now new_description
• parameter conditions is now new_conditions
• parameter parent is now new_parent
• parameter previous_sibling is now new_previous_sibling
• parameter output is now new_output
• parameter context is now new_context
• parameter metadata is now new_metadata
• parameter next_step is now new_next_step
• parameter title is now new_title
• parameter type is now new_type
• parameter event_name is now new_event_name
• parameter variable is now new_variable
• parameter actions is now new_action

updateCounterExample

• parameter old_text is now text
• parameter text is now new_text

Discovery

getEnvironments

• getEnvironments is now listEnvironments
• parameter added name

getConfigurations

• getConfigurations is now listConfigurations
• parameter added name

getCollectionFields

• getCollectionFields is now listCollectionFields

getCollections

• getCollections is now listCollections
• parameter added name

createConfiguration

• required parameter added name
• optional parameter added description
• file is now decomposed into three top-level parameters, namely, conversions, enrichments, and normalizations.

updateConfiguration

• required parameter added name
• optional parameter added description
• file is now decomposed into three top-level parameters, namely, conversions, enrichments, and normalizations.

createCollection

• parameter language_code is now language

updateCollection

• parameter collection_name is now name
• parameter language_code is removed

addDocument

• new optional parameter file_content_type

queryNotices

• new supported method queryNotices

federatedQueryNotices

• new supported method federatedQueryNotices

federatedQuery

• new supported method federatedQuery

trainingData

• new supported method addTrainingData
• new supported method createTrainingExample
• new supported method deleteAllTrainingData
• new supported method deleteTrainingData
• new supported method deleteTrainingExample
• new supported method getTrainingData
• new supported method getTrainingExample
• new supported method listTrainingData
• new supported method listTrainingExamples
• new supported method updateTrainingExample

Language Translator

getModels

• getModels is now listModels
• parameter default renamed to default_models

getIdentifiableLanguages

• getIdentifiableLanguages is now listIdentifiableLanguages

Natural Language Classifier

create

• create is now createClassifier
• required parameter added metadata

status

• status is now getClassifier

list

• list is now listClassifiers

remove

• remove is now deleteClassifier

Natural Language Understanding

analyze

• parameter headers removed
• optional parameters added clean, xpath, fallback_to_raw, return_analyzed_text, language, limit_text_characters

deleteModel

• parameter headers removed

Personality Insights

profile

• required parameters have changed from either text or content_items to content
• required parameter added content_type

Text to Speech

Method Name Changes

• voice renamed to getVoice
• voices renamed to listVoices
• pronunciation renamed to getPronunciation
• createCustomization renamed to createVoiceModel
• updateCustomization renamed to updateVoiceModel
• getCustomization renamed to getVoiceModel
• deleteCustomization renamed to deleteVoiceModel
• getWords renamed to listWords

Tone Analyzer

tone_chat

• tone_chat is now toneChat

tone

• required parameter added content_type
• required parameter text renamed to tone_input

Speech to Text

createJob

• createRecognitionJob is now createJob

getRecognitionJobs

• getRecognitionJobs is now checkJobs

getRecognitionJob

• getRecognitionJob is now checkJob

deleteRecognitionJob

• deleteRecognitionJob is now deleteJob

createSession

• parameters added customization_id, acoustic_customization_id, customization_weight

Visual Recognition

retrainClassifier

• retrainClassifier is now updateClassifier

recognizeText

• method is no longer supported

classify

• parameters url, classifier_ids, owners, and threshold encapsulated to new JSON object parameter parameters

detectFaces

• parameter url encapsulated in JSON parameter parameters