Skip to content

Migration Guide

Jump to bottom Edit New page
Ammar Dodin edited this page Nov 30, 2017 · 46 revisions

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 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

getDialogNode

  • optional export parameter removed

getExamples

  • getExamples is now listEntities

getValues

  • getValues is now listValues

getSynonym

  • optional export parameter removed

getSynonyms

  • getSynonyms is now listSynonyms

getDialogNodes

  • getDialogNodes is now listDialogNodes
  • optional export parameter removed

getLogs

  • getLogs is now listLogs

getCounterExamples

  • getCounterExamples is now listCounterExamples

updateIntent

  • parameter old_intent renamed to intent
  • parameter intent renamed to new_intent
  • parameter descriptionrenamed to new_description
  • parameter examples renamed to new_examples

updateEntity

  • parameter old_entity renamed to entity
  • parameter entity renamed to new_entity
  • parameter description renamed to new_description
  • parameter metadata renamed to new_metadata
  • parameter fuzzy_match renamed to new_fuzzy_match
  • parameter values renamed to new_values

updateValue

  • parameter old_value renamed to value
  • parameter value renamed to new value
  • parameter metadata renamed to new_metadata
  • parameter synonyms renamed to new_synonyms

updateSynonym

  • parameter old_synonym renamed to synonym
  • parameter synonym renamed to new_synonym

updateDialogNode

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

updateCounterExample

  • parameter old_text renamed to text
  • parameter text renamed to 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
  • parameter file removed
  • parameters added description, conversions, enrichments, normalizations

updateConfiguration

  • required parameter added name
  • parameter file removed
  • parameters added description, conversions, enrichments, normalizations

createCollection

  • parameter language_code renamed to language

updateCollection

  • parameter collection_name renamed to name
  • parameter language_code removed

addDocument

  • parameter metadata renamed to file_content_type

query

  • parameter collection_id changed to collection_ids which is a string array

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
Add a custom footer
Add a custom sidebar
Clone this wiki locally