LinkedIn
Copied!

Table of Contents

Text Analytics APIs

The Text Analytics APIs directly separate the Intelligent Virtual Assistant (IVA) and Text Analyzer rules into independent modules. The introduction of modularity between these components provides more reliability by preventing potential IVA integration issues each time a text analyzer configuration changes. 

The APIs cover all scenarios in which the IVA uses text analyzers, for example:

  • Adding models to text analyzers
  • Configuring text analyzers
  • Performing the Save As operation in the text analyzer
  • Removing models from text analyzers

Additionally, the APIs handle such model-building activities as:

  • Adding model feedback
  • Building models with a single click
  • Creating empty models
  • Listing all available text analytics models
  • Updating model ruleset version with a single click

The following sections provide an overview of each API, with a list of its fields, and a description of its behavior.

pxSaveAsTextAnalyzer

Use this API to save a text analyzer into a new class when creating a new IVA channel.

This API has the following input properties:

Purpose The text analyzer purpose.
Description The text analyzer description.
AppliesTo The applicable class of the text analyzer.
ExistingRuleName The name of the source text analyzer.
ExistingRuleAppliesTo The class of the source text analyzer.
RuleSet The target ruleset of the new text analyzer.
RuleSetVersion The target ruleset version of the new text analyzer.
CopyModels If set to true, the API checks whether the models in the text analyzer are accessible from the target Applies-To class. If not, the API copies the models together with the text analyzer.

The following table presents how the pxSaveAsTextAnalyzer API behaves, based on various combinations of the source and target text analyzer class and the model class:

CopyModels setting Source text analyzer class Model class Target class Outcome
true Data-Decision-Request-Email Data-Decision-Request Data-Decision-Request-MCP The model is not copied.
true Data-Decision-Request-Email Data-Decision-Request-Email and Data-Decision-Request  Data-Decision-Request-MCP The model is copied into the target class because it was specialized in the source class.
true Data-Decision-Request-Email Data-Decision-Request-Email Work- The model is copied into the target class because the source model is not accessible from the target class.
true Data-Decision-Request-Email Data-Decision-Request-Email Data-Decision-Request-Email The model is not copied because the source class and the destination class are the same.
true Data-Decision-Request-Email Data-Decision-Request-Email Data-Decision-Request-MCP (a model with the same name is already present) The model is not copied because a model with the same name already exists in the target class.
true Data-Decision-Request Data-Decision-Request Data-Decision-Request-Email The model is not copied because the target class is a child class of the parent.
true Data-Decision-Request-Email Data-Decision-Request and Data-Decision-Request-Email Data-Decision-Request-MCP The Save As operation completes successfully but the target rule refers to a model from the Data-Decision-Request class.
true Data-Decision-Request-Email Data-Decision-Request-Email Work- The Save As operation fails because the target rule is unable to find the model.

Back to top

pxAddModelInTextAnalyzer

Use this API to add a model to a Text Analyzer rule.

This API has the following input properties:

Purpose The purpose of the text analyzer.
AppliesTo The applicable class of the text analyzer.
ModelNames A comma-separated list of model names.

In the case of text categorization models, the pxAddModelInTextAnalyzer API replaces existing models with new ones. In the case of entity models, the API adds new models to the existing list of entity types to detect and marks all entity types as detectable. If an entity model with the same name is already present in the list, then the model is not replaced and an error message appears.

If there are no models of a specific analysis type (for example, topic detection) in the target text analyzer and you want to add a model of that type, then the API enables that analysis type and adds the models. If the text analyzer is in a blocked ruleset, then that text analyzer is saved in the next available ruleset.

The API uses the same set of validation messages as the Text Analyzer rule type when you click Save.

Back to top

pxRemoveModelFromTextAnalyzer

Use this API to remove a model from a text analyzer.

This API has the following input properties:

Purpose The purpose of the text analyzer.
AppliesTo The applicable class of the text analyzer.
ModelNames A comma-separated list of model names.

The pxRemoveModelFromTextAnalyzer API removes the models that you specify from the text analyzer. The API identifies the model type automatically. If a model is removed, and no models are configured for the corresponding analysis type (for example, topic detection), then the API automatically disables that analysis type. If the text analyzer is in a blocked ruleset, then that text analyzer is saved in the next available ruleset.

Back to top

D_pxListModelsInTextAnalyzerByType

This API lists all models in a text analyzer in a Page List property.

This API has the following input properties:

Purpose The purpose of the text analyzer.
AppliesTo The applicable class of the text analyzer.

Back to top

pxAddLanguageToModel

Use this API to add a language to any type of text analytics model.

This API has the following input properties:

Purpose The purpose of the text analyzer.
AppliesTo The applicable class of the text analyzer.
Language The language of the model to add.
EntityGranularity The Sentence or Paragraph analysis granularity of entity model.

The pxAddLanguageToModel API validates the Decision Data rule that holds a text analytics model and then adds a new language to the rule. For example, if the rule holds a model only for the English language and the API is called to add a model for the French language, the API call resolves successfully and the decision data now holds English and French versions of the model. If the text analyzer is in a blocked ruleset, then that text analyzer is saved in the next available ruleset.

Back to top

pxDeleteLanguageFromModel

Use this API to delete a language from a model, together with the associated artifacts. If the text analyzer is in a blocked ruleset, then that text analyzer is saved in the next available ruleset.

This API has the following input properties:

Purpose The purpose of the text analyzer.
AppliesTo The applicable class of the text analyzer.
Language The language of the model to delete.

Back to top

D_pxTopicsInModel

This API produces a data page with a list of Text Analyzer topics per language. If you save this data page, you can also use it to update the topic list.

This API has the following input properties:

Purpose The purpose of the text analyzer.
AppliesTo The applicable class of the text analyzer.
Languages A comma-separated list of languages. If left empty, the API provides the list of all topics in all languages in the model.

The following list provides the output model of the D_pxTopicsInModel API:

  • pxTopics(ENGLISH) {DataNLP-Taxonomy}
    • pxResults(1) {Data-NLP-TaxonomyRule}
      • pyCategory
      • pyName
      • pyTopicDisplayName
        • pxResults(1) {data-NLP-TaxonomyRule}
          • pyCategory
          • pyName
          • pyTopicDisplayName
          • pyShouldWords (If present)
          • pyNotWords (If present)
          • pyAndWords (If present)
          • pxResults(1) …

When you invoke the data page with the list of parameters, a tree structure lists the available topics at the language level. To update a topic value, edit the data page and save it. If you leave the Languages parameter empty, then the API lists all the languages available in the model. If the text analyzer is in a blocked ruleset, then that text analyzer is saved in the next available ruleset.

Back to top

D_pxTopicsInTextAnalyzer

This API provides a list of all topics in the text analyzer.

This API has the following input properties:

Purpose The purpose of the text analyzer.
AppliesTo The applicable class of the text analyzer.

The D_pxTopicsInTextAnalyzer API returns a Page List property that contains a list of text analyzer models and their types.

Back to top

pxConfigureTextAnalyzer

Use this API to configure such text analyzer settings as the language, analysis granularity, and others.

This API has the following input properties:

Purpose The purpose of the text analyzer.
AppliesTo The applicable class of the text analyzer.
ConfigPage A clipboard page of type Code-Pega-List that contains a pxResults pagelist of the Embed-NameValuePair type.

To deliver the expected results, the ConfigPage parameter has the following requirements:

  • It must contain a pxResults pagelist of type Embed-NameValuePair.
  • The pyName property must contain the name of the key to update.
  • The pyValue property must contain the value of the key to update.

The following list contains the pxResults keys together with acceptable values:

 
Key Value
Language
  •  Auto
  • <Language>
  • Publisher
DefaultLanguage Any of the supported languages in the sentence case, for example, French.
InputTextProperty The property name for the input text.
OutcomeProperty The property name for the NLP outcome.
DetectTags

Available values:

  • All
  • <Number of tags>

This option enables autotags by default. If you enter 0 or a negative number, this option disables autotags.

CompressionRatio

The value of the compression ratio.

This option enables summarization by default. When you enter 0 or a negative number, this option disables summarization.

TopicGranularity

Available values:

  • Sentence
  • Document
TopicSelection

Available values:

  • TopN
  • FScore
TopicThreshold

Available values:

  • <The number of topics>
  • <The confidence score threshold>
FallbackToRule

Available values:

  • true
  • false
SpellChecker

<The name of the SpellChecker rule>

When set, this parameter enables spelling checks.

MinimumScore <Minimum score value for sentiment>
MaximumScore <Maximum score value for sentiment>
Lexicon <The name of the lexicon rule to use>
DefaultTopic

<The name of the default topic model>

When set, this option replaces the existing topic model if the topic is included in a new model. Otherwise, this option sets the default topic within a model.

ClassificationPreference

Available values:

  • ML
  • Rules

For more information about text analyzer settings, see About Text Analyzer rules.

Back to top

D_pxGetModelAnalysis

Use this API to return model analysis details.

This API has the following input properties:

Purpose The purpose of the text analyzer.
AppliesTo The applicable class of the text analyzer.

The D_pxGetModelAnalysis API has the following output:

  • Accuracy (the F score)
  • Algorithm type
  • Last built by
  • Last built time
  • Model type
  • Training data count
  • Test data count
  • Test percentage count
  • Test selection type (for example, manual or user-defined)
  • Training percentage count

Back to top

pxCreateEmptyModel

Use this API to create an empty text analytics model. The outcome of the API is a Decision Data rule.

This API has the following input properties:

ModelName The name of the new model.
Description The model description.
ClassName The applicable class of the model.
RuleSetName The name of the target ruleset.
RuleSetVersion The version of the target ruleset.
AnalysisType

Available values:

  • Entity
  • Classification
  • Sentiment
  • Intent
Language The model language.
EntityGranularity

Available values:

  • Sentence
  • Paragraph

Back to top

pxCaptureTAFeedback

Use this API to capture and store feedback data for a text analytics model. The output of the API is the ID number of the feedback record that is stored for the specified model.

This API has the following input properties:

ModelName The name of the new model.
ClassName The applicable class of the model.
ModelType

Available values:

  • Entity
  • Classification
  • Sentiment
  • Intent
Language The language of the model.
Text Feedback text. Use this field for text extraction analysis. Paste annotated text with both the corrected and previously correct entities.
ActualResult The expected category assignment of the analyzed text. Use this field for intent, sentiment, and topic detection.
MachineOutcome The prediction that the model made.
TASummaryID

The ID number of the summary, if enabled.

FeedbackID This value returns an ID of the feedback record.
IsTest

Marks if the feedback record is for test purposes. If true, the model does not include the record in the feedback.

Available values:

  • true
  • false

Back to top

pxUpdateModels

Use this API to retrain a model with the recorded feedback. The API outputs the operation status, and a status message if the operation fails.

This API has the following input properties:

Purpose The purpose of the text analyzer.
AppliesTo The applicable class of the text analyzer.
ClassName The applicable class of the model.
Language The model language.
Status Returns the operation status.
StatusMsg Returns the error message if the operation fails.

Back to top

pxSaveAsModelAPI

Use this API to perform a Save As operation on an existing text analytics model. The API creates a model with a new name and copies all related artifacts from the source model to the newly-created model.

This API has the following input properties:

ModelName The name of the new model.
Description The description of the text analyzer.
AppliesTo The applicable class of the text analyzer.
RuleSet The target ruleset of the new text analyzer.
RuleSetVersion The target ruleset version of the new text analyzer.
ExistingModelName The name of the source text analyzer.
ExistingModelAppliesTo The class of the source text analyzer.
Status Returns the operation status.
StatusMsg

Returns the error message if the operation fails.

Back to top

pxCopyNLPFeedback

Use this API to feedback records between models in the same system.

This API has the following input properties:

SourceModelName The name of the model that is the source of feedback data.
SourceAppliesToClass The applicable class of the source model.
SourceRuleSet The ruleset of the source model.
TargetModelName The name of the model to which you want to copy the feedback data.
TargetAppliesToClass The applicable class of the model to which you want to copy the feedback data.
TargetRuleSet The ruleset of the model to which you want to copy the feedback data.

Back to top

pxSetPredictionRepository

Use this API to specify the repository for model training data.

This API has the following input properties:

RepositoryName The name of the repository that will store the training data.

For more information, see Specifying a database for Prediction Studio records.

Back to top

D_pzEntityTypesInTextAnalyzer

Use this API to list the entity types in a text analyzer. The output of this entity is a Page List property that contains all of the configured entity types in a text analyzer. 

This API has the following input properties:

Purpose The purpose of the text analyzer.
ClassName The applicable class of the text analyzer.

Back to top

D_pzGetEntityTypesForModel

Use this API to list the entity types in a model. The output of this entity is a Page List property that contains entity types from all languages in a model.

ModelName The model name.
ModelClass The applicable class of the model.

Back to top

Suggest Edit

Related Content

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.