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

New Supported Methods

• new supported method queryNotices
• new supported method federatedQueryNotices
• new supported method federatedQuery
• 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 is now 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
• features is now a required parameter

deleteModel

• parameter headers removed

listModels

• parameter headers removed

Personality Insights

profile

• required parameters have changed from either text or content_items to content
• header parameters content_type, accept_language, content-languageare now top-level parameters and no longer encapsulated in a headers object
• content_type is now required

Text to Speech

Method Name Changes

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

Tone Analyzer

tone_chat

• tone_chat method is now toneChat
• utterances are now a top level parameter
• new optional parameter accept_language

tone

• required parameter added content_type
• required parameter text is now tone_input
• removed parameter isHTML

Speech to Text

getModels

• getModels is now listModels

getCustomizaition

• getCustomization is now getLanguageModel

getCustomizations

• getCustomizations is now listLanguageModels

getRecognizeStatus

• getRecognizeStatus is now getSessionStatus

getRecognitionJob

• getRecognitionJob is now checkJob

getRecognitionJobs

• getRecognitionJobs is now checkJobs

createRecognitionJob

• createRecognitionJob is now createJob

deleteRecognitionJob

• deleteRecognitionJob is now deleteJob

createCustomization

• createCustomization is now createLanguageModel
• new required parameter content_type

addCorpus

• parameter name is now corpus_name
• parameter corpus is now corpus_file

getCorpus

• parameter name is now corpus_name

deleteCorpus

• parameter name is now corpus_name

getCorpora

• getCorpora is now listCorpora

addWords

• new required parameter content_type

addWord

• parameter word is now word_name
• new require parameter content_type

getWords

• getWords is now listWords

deleteWord

• parameter word is now word_name

trainCustomization

• trainCustomization is now trainLanguageModel

resetCustomization

• resetCustomization is now resetLanguageModel

createSession

• parameters added customization_id, acoustic_customization_id, customization_weight

Visual Recognition

retrainClassifier

• retrainClassifier is now updateClassifier

recognizeText

• method is no longer supported

Similarity Search Methods

• The similary search beta is closed. The following methods are no longer available:
  • createCollection
  • getCollection
  • listCollections
  • deleteCollection
  • addImage
  • listImages
  • getImage
  • deleteImage
  • setImageData
  • getImageData
  • deleteImageData
  • findSimilar

classify

• parameters url, classifier_ids, owners, and threshold are now encapsulated in a new JSON parameter parameters

detectFaces

• parameter url is now encapsulated in a new JSON parameter parameters