Managing Models
The services for model management are available in the TW.AnalysisServices.ModelManagementServicesAPI resource.
The sections below provide information about the purpose, input parameters, and the result of each service:
CreateModelAndDatashapesFromFile
Creates and deploys the model. Use this service to auto-generate data shapes by querying the model file.
Before using this service, ensure that a folder with the name of your Analysis Provider has been created in the TW.AnalysisServices.ModelRepository and that your model file is uploaded to that Analysis Provider folder.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model. If a fileURL is specified, then the model name should be the file name without the extension.
|
Returns the ID of the model. Throws an exception if there are any errors, such as invalid fileURL, model not found, and so on.
|
|
description
|
String
|
Specifies the model description.
|
|
|
providerName
|
String
|
Specifies the name of the provider.
|
|
|
fileURL
|
Hyperlink
|
Specifies the URL to the model file, which must be uploaded to the TW.AnalysisServices.ModelRepository folder, a ThingWorx repository. Use the following format: /Thingworx/FileRepositories/TW.AnalysisServices.ModelRepository/<AnalysisProviderName>/<FileName>
|
|
|
inputsToResultsCardinality
|
String
|
Depending on how you want to configure the analysis model, specify the inputs to results relationship as one of the following:
• Any — Creates multiple results from multiple inputs. The number of results is not equal to the number of inputs.
• NxN — Creates multiple results from multiple inputs. The number of results must be equal to the number of inputs.
• Nx1 — Creates a single result from multiple inputs.
• 1xN — Creates multiple results from a single input.
• 1x1 — Creates a single result from a single input.
The default value is Any.
|
|
|
customData
|
Infotable
|
Specifies any additional information that is customer-specific about a model.
|
CreateModelWithManualDatashapes
Creates and deploys the model, the data shapes are created in ThingWorx using the specified input and result JSON structures.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns the ID of the model. Throws an exception if the input JSON or result JSON is not provided.
|
|
description
|
String
|
Specifies the model description.
|
|
|
providerName
|
String
|
Specifies the name of the provider.
|
|
|
inputDatashapeJson
|
JSON
|
Specifies a JSON array representing the input data shape. See the format of the JSON below the table.
|
|
|
outputDatashapeJson
|
JSON
|
Specifies a JSON array representing the result data shape.
|
|
|
inputsToResultsCardinality
|
String
|
Depending on how you want to configure the analysis model, specify the inputs to results relationship as one of the following:
• Any — Creates multiple results from multiple inputs. The number of results is not equal to the number of inputs.
• NxN — Creates multiple results from multiple inputs. The number of results must be equal to the number of inputs.
• Nx1 — Creates a single result from multiple inputs.
• 1xN — Creates multiple results from a single input.
• 1x1 — Creates a single result from a single input.
The default value is Any.
|
|
|
customData
|
Infotable
|
Specifies any additional information that is customer-specific about a model.
|
CreateModelWithManualDatashapesAndFile
Creates and deploys the model. The data shapes are created in ThingWorx using the specified input and result JSON structures. Use this service if a model file has to be uploaded, but data shapes are to be generated from specified input structures.
Before using this service, ensure that a folder with the name of your Analysis Provider has been created in the TW.AnalysisServices.ModelRepository and that your model file is uploaded to that Analysis Provider folder.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns the ID of the model. Throws an exception if the input JSON or result JSON is not provided.
|
|
description
|
String
|
Specifies the model description.
|
|
|
providerName
|
String
|
Specifies the name of the provider.
|
|
|
fileURL
|
Hyperlink
|
Specifies the URL to the model file, which must be uploaded to the TW.AnalysisServices.ModelRepository folder, a ThingWorx repository. Use the following format: /Thingworx/FileRepositories/TW.AnalysisServices.ModelRepository/<AnalysisProviderName>/<FileName>
|
|
|
inputDatashapeJson
|
JSON
|
Specifies a JSON array representing the input data shape. See the format of the JSON below the table.
|
|
|
outputDatashapeJson
|
JSON
|
Specifies a JSON array representing the result data shape.
|
|
|
inputsToResultsCardinality
|
String
|
Depending on how you want to configure the analysis model, specify the inputs to results relationship as one of the following:
• Any — Creates multiple results from multiple inputs. The number of results is not equal to the number of inputs.
• NxN — Creates multiple results from multiple inputs. The number of results must be equal to the number of inputs.
• Nx1 — Creates a single result from multiple inputs.
• 1xN — Creates multiple results from a single input.
• 1x1 — Creates a single result from a single input.
The default value is Any.
|
|
|
customData
|
Infotable
|
Specifies any additional information that is customer-specific about a model.
|
CreateOrUpdateThingForModelFromTemplate
Creates or updates a thing that inherits the input and result data shape properties from the specified analysis model and is inherited from the given thing template.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns the name of the thing that is created.
Throws an exception if the thing exists, and is not inherited from the thing template.
|
|
providerName
|
String
|
Specifies the name of the provider.
|
|
|
templateName
|
String
|
Specifies the name of the thing template from which the thing inherits the input and result data shape properties.
|
|
|
forceUpdate
|
Boolean
|
If the thing exists, and the properties or data shapes of the model have changed, set the value of forceUpdate to true to update the thing.
If there is a name or type conflict on the input properties, the old property on the thing is deleted and recreated. If there is a name or type conflict on the result properties, a warning is displayed and the property is created with a _result suffix.
If forceUpdate is set to true, and the name conflict is not across inputs and results, then the old property is deleted and recreated.
If properties exist on the thing, and the value of forceUpdate is set to false, the operation fails, and the service throws an exception.
|
|
|
prefixInputsAndResults
|
Boolean
|
Set to true so that the input properties on the thing are prefixed with ia, and the result properties are prefixed with ra.
|
CreateOrUpdateThingShapeForModel
Creates or updates a thing shape that inherits the input and result data shape properties from the specified analysis model.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns the name of the thing shape that is created.
|
|
providerName
|
String
|
Specifies the name of the provider.
|
|
|
forceUpdate
|
Boolean
|
If the thing shape exists, and the properties or data shapes of the model have changed, set the value of forceUpdate to true to update the thing shape.
If there is a name or type conflict on the input properties, the old property on the thing shape is deleted and recreated. If there is a name or type conflict on the result properties, a warning is displayed and the property is created with a _result suffix.
If forceUpdate is set to true, and the name conflict is not across inputs and results, then the old property is deleted and recreated.
If properties exist on the thing shape, and the value of forceUpdate is set to false, the operation fails, and the service throws an exception.
|
|
|
prefixInputsAndResults
|
Boolean
|
Set to true so that the input properties on the thing shape are prefixed with ia, and the result properties are prefixed with ra.
|
CreateOrUpdateThingShapeAndThingForModelFromTemplate
Creates or updates a thing shape that inherits the input and result data shape properties of the specified analysis model, and a thing that implements this thing shape.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns the name of the thing that is created.
Throws an exception if the thing exists, and is not inherited from the thing shape.
|
|
providerName
|
String
|
Specifies the name of the provider.
|
|
|
templateName
|
String
|
Specifies the name of the thing template from which the thing inherits the input and result data shape properties.
|
|
|
forceUpdate
|
Boolean
|
If the thing shape exists, and the properties or data shapes of the model have changed, set the value of forceUpdate to true to update the thing shape.
If there is a name or type conflict on the input properties, the old property on the thing shape is deleted and recreated. If there is a name or type conflict on the result properties, a warning is displayed and the property is created with a _result suffix.
If forceUpdate is set to true, and the name conflict is not across inputs and results, then the old property is deleted and recreated.
If properties exist on the thing template, and the value of forceUpdate is set to false, the operation fails, and the service throws an exception.
|
|
|
prefixInputsAndResults
|
Boolean
|
Set to true so that the input properties on the thing shape are prefixed with ia, and the result properties are prefixed with ra.
|
CreateOrUpdateThingTemplateForModel
Creates or updates a thing template that inherits the input and result data shape properties of the specified analysis model.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns the name of the thing template that is created.
Throws an exception if the thing template exists.
|
|
providerName
|
String
|
Specifies the name of the provider.
|
|
|
forceUpdate
|
Boolean
|
If the thing template exists, and the properties or data shapes of the model have changed, set the value of forceUpdate to true to update the thing template.
If there is a name or type conflict on the input properties, the old property on the thing template is deleted and recreated. If there is a name or type conflict on the result properties, a warning is displayed and the property is created with a _result suffix.
If forceUpdate is set to true, and the name conflict is not across inputs and results, then the old property is deleted and recreated.
If properties exist on the thing template, and the value of forceUpdate is set to false, the operation fails, and the service throws an exception.
|
|
|
prefixInputsAndResults
|
Boolean
|
Set to true so that the input properties on the thing template are prefixed with ia, and the result properties are prefixed with ra.
|
CreateOrUpdateThingTemplateAndThingForModel
Creates or updates a thing template that inherits the input and result data shape properties of the specified model, and a thing that inherits this thing template.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns the name of the thing that is created.
Throws an exception if the thing exists, and is not inherited from the thing template.
|
|
providerName
|
String
|
Specifies the name of the provider.
|
|
|
forceUpdate
|
Boolean
|
If the thing template exists, and the properties or data shapes of the model have changed, set the value of forceUpdate to true to update the thing template.
If there is a name or type conflict on the input properties, the old property on the thing template is deleted and recreated. If there is a name or type conflict on the result properties, a warning is displayed and the property is created with a _result suffix.
If forceUpdate is set to true, and the name conflict is not across inputs and results, then the old property is deleted and recreated.
If properties exist on the thing template, and the value of forceUpdate is set to false, the operation fails, and the service throws an exception.
|
|
|
prefixInputsAndResults
|
Boolean
|
Set to true so that the input properties on the thing template are prefixed with ia, and the result properties are prefixed with ra.
|
DeleteModel
Deletes the specified model.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns a message that states the successful completion or errors that occur during the execution of the service.
|
|
providerName
|
String
|
Specifies the name of the provider.
|
DisableModel
Disables the specified model.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns a message that states the successful completion or errors that occur during the execution of the service.
|
|
providerName
|
String
|
Specifies the name of the provider.
|
EditModelAndDatashapes
Edits the specified model and its associated input and result data shapes, if specified. Use this service if the model is to be edited without editing the model file.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model. If a fileURL is specified, then the model name should be the file name without the extension.
|
Returns the ID of the model.
|
|
description
|
String
|
Specifies the model description.
|
|
|
providerName
|
String
|
Specifies the name of the provider.
|
|
|
inputDatashapeJson
|
JSON
|
This parameter is optional. It is required only if the input data shape is to be edited. A JSON array represents the input data shape. See the format of the JSON below the table.
|
|
|
outputDatashapeJson
|
JSON
|
This parameter is optional. It is required only if the result data shape is to be edited. A JSON array represents the result data shape.
|
|
|
inputsToResultsCardinality
|
String
|
Depending on how you want to configure the analysis model, specify the inputs to results relationship as one of the following:
• Any — Creates multiple results from multiple inputs. The number of results is not equal to the number of inputs.
• NxN — Creates multiple results from multiple inputs. The number of results must be equal to the number of inputs.
• Nx1 — Creates a single result from multiple inputs.
• 1xN — Creates multiple results from a single input.
• 1x1 — Creates a single result from a single input.
The default value is Any.
|
|
|
customData
|
Infotable
|
Specifies any additional information that is customer-specific about a model.
|
EditModelWithFile
Edits the specified model. Use this service if the model file is to be edited along with the auto-generated data shapes.
Before using this service, ensure that a folder with the name of your Analysis Provider has been created in the TW.AnalysisServices.ModelRepository and that your model file is uploaded to that Analysis Provider folder.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns the ID of the model. Throws an exception if there are any errors, such as invalid fileURL, model not found, and so on.
|
|
description
|
String
|
Specifies the model description.
|
|
|
providerName
|
String
|
Specifies the name of the provider.
|
|
|
fileURL
|
Hyperlink
|
Specifies the URL to the model file, which must be uploaded to the TW.AnalysisServices.ModelRepository folder, a ThingWorx repository. Use the following format: /Thingworx/FileRepositories/TW.AnalysisServices.ModelRepository/<AnalysisProviderName>/<FileName>
|
|
|
inputsToResultsCardinality
|
String
|
Depending on how you want to configure the analysis model, specify the inputs to results relationship as one of the following:
• Any — Creates an undefined inputs to results relationship.
• NxN — Creates multiple results from multiple inputs.
• Nx1 — Creates a single result from multiple inputs.
• 1xN — Creates multiple results from a single input.
• 1x1 — Creates a single result from a single input.
The default value is Any.
|
|
|
customData
|
Infotable
|
Specifies any additional information that is customer-specific about a model.
|
EnableModel
Enables the specified model.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns a message that states the successful completion or errors that occur during the execution of the service.
|
|
providerName
|
String
|
Specifies the name of the provider.
|
GetModel
Provides information about the specified model.
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
modelName
|
String
|
Specifies the name of the model.
|
Returns information about the model in the form of an infotable that has the TW.AnalysisServices.ModelDataShape data shape.
|
|
providerName
|
String
|
Specifies the name of the provider.
|
QueryModels
Returns model information based on the query.
 |
Provide inputs for either the values or query parameter.
|
|
Parameter Name
|
Base Type
|
Description
|
Result
|
|---|---|---|---|
|
values
|
Infotable
|
Specifies the attributes of the model in the form of a collection of multiple value rows.
|
Returns information about the model in the form of an infotable that has the TW.AnalysisServices.ModelDataShape data shape.
|
|
query
|
Query
|
Specifies the query that includes what information is required about a particular model.
|
inputDatashapeJson format
For a model that takes two inputs, x and ylist, where x is a number and ylist is a table with column y, the JSON format is:
```json
[{
"DefaultValue": 2,
"IDField": "x",
"Description": "input x",
"BaseType": "Number",
"Ordinal": 0,
"isPrimary": false,
"MinValue": null,
"ParentIDField": null,
"MaxValue": null,
"Unit": null,
"Depth": 1
},
{
"DefaultValue": "",
"IDField": "ylist",
"Description": "input table with column y",
"BaseType": "Infotable",
"Ordinal": 1,
"isPrimary": false,
"MinValue": null,
"ParentIDField": null,
"MaxValue": null,
"Unit": null,
"Depth": 1
},
{
"DefaultValue": "",
"IDField": "y",
"Description": "y ",
"BaseType": "Number",
"Ordinal": 0,
"isPrimary": false,
"MinValue": null,
"ParentIDField": "ylist",
"MaxValue": null,
"Unit": null,
"Depth": 2
}]
```json
[{
"DefaultValue": 2,
"IDField": "x",
"Description": "input x",
"BaseType": "Number",
"Ordinal": 0,
"isPrimary": false,
"MinValue": null,
"ParentIDField": null,
"MaxValue": null,
"Unit": null,
"Depth": 1
},
{
"DefaultValue": "",
"IDField": "ylist",
"Description": "input table with column y",
"BaseType": "Infotable",
"Ordinal": 1,
"isPrimary": false,
"MinValue": null,
"ParentIDField": null,
"MaxValue": null,
"Unit": null,
"Depth": 1
},
{
"DefaultValue": "",
"IDField": "y",
"Description": "y ",
"BaseType": "Number",
"Ordinal": 0,
"isPrimary": false,
"MinValue": null,
"ParentIDField": "ylist",
"MaxValue": null,
"Unit": null,
"Depth": 2
}]
```json