Skip to main content

Text Analytics APIs

Suggest edit Updated on September 28, 2021

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:

PurposeThe text analyzer purpose.
DescriptionThe text analyzer description.
AppliesToThe applicable class of the text analyzer.
ExistingRuleNameThe name of the source text analyzer.
ExistingRuleAppliesToThe class of the source text analyzer.
RuleSetThe target ruleset of the new text analyzer.
RuleSetVersionThe target ruleset version of the new text analyzer.
CopyModelsIf 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 settingSource text analyzer classModel classTarget classOutcome
trueData-Decision-Request-EmailData-Decision-RequestData-Decision-Request-MCPThe model is not copied.
trueData-Decision-Request-EmailData-Decision-Request-Email and Data-Decision-Request Data-Decision-Request-MCPThe model is copied into the target class because it was specialized in the source class.
trueData-Decision-Request-EmailData-Decision-Request-EmailWork-The model is copied into the target class because the source model is not accessible from the target class.
trueData-Decision-Request-EmailData-Decision-Request-EmailData-Decision-Request-EmailThe model is not copied because the source class and the destination class are the same.
trueData-Decision-Request-EmailData-Decision-Request-EmailData-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.
trueData-Decision-RequestData-Decision-RequestData-Decision-Request-EmailThe model is not copied because the target class is a child class of the parent.
trueData-Decision-Request-EmailData-Decision-Request and Data-Decision-Request-EmailData-Decision-Request-MCPThe Save As operation completes successfully but the target rule refers to a model from the Data-Decision-Request class.
trueData-Decision-Request-EmailData-Decision-Request-EmailWork-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:

PurposeThe purpose of the text analyzer.
AppliesToThe applicable class of the text analyzer.
ModelNamesA 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:

PurposeThe purpose of the text analyzer.
AppliesToThe applicable class of the text analyzer.
ModelNamesA 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:

PurposeThe purpose of the text analyzer.
AppliesToThe 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:

PurposeThe purpose of the text analyzer.
AppliesToThe applicable class of the text analyzer.
LanguageThe language of the model to add.
EntityGranularityThe 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:

PurposeThe purpose of the text analyzer.
AppliesToThe applicable class of the text analyzer.
LanguageThe 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:

PurposeThe purpose of the text analyzer.
AppliesToThe applicable class of the text analyzer.
LanguagesA 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:

PurposeThe purpose of the text analyzer.
AppliesToThe 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:

PurposeThe purpose of the text analyzer.
AppliesToThe applicable class of the text analyzer.
ConfigPageA 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:

 
KeyValue
Language
  •  Auto
  • <Language>
  • Publisher
DefaultLanguageAny of the supported languages in the sentence case, for example, French.
InputTextPropertyThe property name for the input text.
OutcomePropertyThe 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:

PurposeThe purpose of the text analyzer.
AppliesToThe 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:

ModelNameThe name of the new model.
DescriptionThe model description.
ClassNameThe applicable class of the model.
RuleSetNameThe name of the target ruleset.
RuleSetVersionThe version of the target ruleset.
AnalysisType

Available values:

  • Entity
  • Classification
  • Sentiment
  • Intent
LanguageThe 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:

ModelNameThe name of the new model.
ClassNameThe applicable class of the model.
ModelType

Available values:

  • Entity
  • Classification
  • Sentiment
  • Intent
LanguageThe language of the model.
TextFeedback text. Use this field for text extraction analysis. Paste annotated text with both the corrected and previously correct entities.
ActualResultThe expected category assignment of the analyzed text. Use this field for intent, sentiment, and topic detection.
MachineOutcomeThe prediction that the model made.
TASummaryID

The ID number of the summary, if enabled.

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

PurposeThe purpose of the text analyzer.
AppliesToThe applicable class of the text analyzer.
ClassNameThe applicable class of the model.
LanguageThe model language.
StatusReturns the operation status.
StatusMsgReturns 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:

ModelNameThe name of the new model.
DescriptionThe description of the text analyzer.
AppliesToThe applicable class of the text analyzer.
RuleSetThe target ruleset of the new text analyzer.
RuleSetVersionThe target ruleset version of the new text analyzer.
ExistingModelNameThe name of the source text analyzer.
ExistingModelAppliesToThe class of the source text analyzer.
StatusReturns 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:

SourceModelNameThe name of the model that is the source of feedback data.
SourceAppliesToClassThe applicable class of the source model.
SourceRuleSetThe ruleset of the source model.
TargetModelNameThe name of the model to which you want to copy the feedback data.
TargetAppliesToClassThe applicable class of the model to which you want to copy the feedback data.
TargetRuleSetThe 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:

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

PurposeThe purpose of the text analyzer.
ClassNameThe 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.

ModelNameThe model name.
ModelClassThe applicable class of the model.

Back to top

Did you find this content helpful? YesNo

Have a question? Get answers now.

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

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us