Map Analytics Inputs and Outputs to Tags

About I/O Mapping

Use I/O Mapping to connect, or map, the applicable asset tags in the analytics deployments for analytics inputs, outputs, and constant definitions that were previously configured in the Analytic Template.

Input tags are marked as optional or required in the 2. I/O Mapping section. You cannot proceed to the next step until all inputs marked as required are mapped.

You can only add or delete orchestration inputs through the 2. I/O Mapping section if your Analytic Template configuration has this enabled. If not, you must modify the original analytics definitions in the Analytic Template.
Important: The changes in the analytics catalog and template affect all analytics deployments and orchestrations that are using the selected analytic. Consider creating a new analytic rather than modifying one that is in use.

Map Tags and Asset Attributes for Deployment

The I/O Mapping is the second step in deployment. It allows you to map the inputs that were defined while building the analytic template to tenant-specific asset tags and attributes.

Mapping an analytic to time series data or asset attribute involves associating an analytic input to asset tags or assigning values including attributes.

You must select at least one asset, or an asset filter in the 1. Asset Selection section of deployment.
Tip: Input, constant, and output definitions are created while building the analytic template. Any changes made while building the analytic template are reflected in the related sections.

The framework does not allow partial mapping for required inputs. All required inputs must be mapped for each selected asset before you can proceed. If you are mapping more than 20 assets, it is recommended to map inputs by common tags. Any template definitions for constants and outputs are automatically mapped; however, you can replace specific values.

The 2.I/O Mapping section contains the following components:

ComponentDescription
ASSET(S) paneThe ASSET(S) pane may be hidden. To access this pane, select to expand it or select to collapse it. Depending on the type of mapping, you can access either the common tags available for all selected assets in the deployment or the asset hierarchy with only the relevant tags within that single asset node.
  • ASSET(S) subsection - Displays the asset applicability. Allows you change the asset selection to access tags and attributes of a specific asset.
  • Data Sources box- Allows you to select from available data sources. This selection varies based on the deployment.
    Note: If you have registered for external data sources in the Time Series Data Sources module, you can select registered external data sources also such as Predix Time series data sources from the available data sources. This functionality is enabled only for Input and Constant Port Mapping.
  • Search expanded tags box - Allows you to search for tags within the context of the expanded Tags node. For example, if you have expanded the Tags node for asset K12 Turbine 258, then the context for search is limited to tags within that asset.
  • Common subsection - Accessible only when All Assets option is selected. Displays the asset tree with Tags, Custom Attributes, and Reserved Attributes nodes. Only the common tags and attributes are available for mapping.
  • Find by Name subsection - Accessible only when All Assets option is selected. Allows you to search for specific tags or attributes by name.
  • - Accessible only when a specific asset is selected. Displays the asset tree with Tags, Custom Attributes, and Reserved Attributes nodes. You can access tags, custom attributes, and reserved attributes for the selected asset only.
Data Flow paneThe Data Flow pane may be hidden. To access this pane, select to expand it or select to collapse it. Adding iterations is applicable to orchestration deployments.
INPUT DEFINITION: TAGS & ATTRIBUTES tableA table of inputs to be used in the deployment. You can map the required tags to inputs here. When you are mapping asset by asset, only inputs for the selected asset appear in the ASSETS subsection.
Note: If you have registered for external data sources in the Time Series Data Sources module, in the DATA SOURCE column you can select registered external data sources. You can select the data source as Pre-prod time series or one of the registered external data sources on per port basis. Attributes values are always selected as Pre-prod data source.
CONSTANTS tableA table of constants selected when building the Analytic Template. You can change the value for constants displayed here.
OUTPUT DEFINITION: TAGS & ATTRIBUTES tableA table of outputs selected when building the Analytic Template. You can select the Output UoM and UoM Conversion values, map a tag to the constant, and select the outputs destination in a drop-down list. If enabled, you can map aggregate tags for computing aggregate values.
Note: Data source for each Output ports will be assigned by default to Pre-prod time series and you cannot write the data to Predix time series data source.
OUTPUT DEFINITION: ALERTS tableA table of Alert Template associations selected when building the Analytic Template.
Note: Only Pre-prod alert templates are associated for the analytic. Alert payloads are ingested to only Pre-prod environment.

Access Production Time Series Data from Pre-Prod Analytics

Before You Begin

It is assumed that, all the assets selected to configure an analytic in Pre-prod environment, available in Production environment also. Tag names and attribute names are also identical for these Pre-prod and production assets. If a tag or attribute mapped to a Pre-prod analytic does not exist in production environment, then analytic will fail to execute.

About This Task

To test or enhance the Analytic blueprints in the Pre-prod environment before promoting to production, the analytics need access to data in production environment. This makes the production data available to analytics being verified in Pre-prod environment.

Procedure

  1. Register Production time series data sources in the Time Series Data Sources module. The registration payload corresponding to each of the external data source must specify the following values:
    • Alias
    • Predix Zone ID
    • UAA
    • Client ID
    • Client Secret
  2. In the module navigation menu, navigate to Analytics > Deployments.
    The Deployments page appears.
  3. Select Actions and then from the drop-down list, select Register External Predix Data Sources.
    The data sources that provide the necessary external credentials are registered with the Analytics.
    Note:
    • To unregister the external data sources from the Analytics, in the Actions drop-down list, select Unregister External Predix Data Sources.
    • If you change the credentials of the external data sources or select Unregister External Predix Data Sources which are registered with the analytics, the current deployments will fail.

Results

The external time series data sources are registered and you can now access Production time series data in the Pre-prod analytics environment.

Modify the Analytic Version During Deployment

You can modify the analytic version being used within an Analytic Data Flow during deployment.

Before You Begin

You must have uploaded more than one analytic version to modify during the deployment of that analytic.

About This Task

Modifying the analytic version for an analytic step in an analytic data flow allows you to use a different version than set as current (default) in the analytic template.

The analytic version refers to the analytic artifacts that were loaded into the analytic catalog. You can determine the version that the analytic uses when deployed by itself or within an orchestration.
Tip: Map your inputs, constants, outputs, and attributes after you have modified the version of the analytic to apply during deployment. Modifying a different version post mapping may require you to perform the mapping step one more time for properly deploying it to the runtime.

Procedure

  1. In the module navigation menu, navigate to Analytics > Deployments.
  2. Select an existing deployment to access its workspace.
  3. In the page heading, select Edit to access the deployment.
  4. Select the 2. I/O Mapping tab.
  5. Select to access the Data Flow pane.
  6. Select a analytic step node. For example, if you have Analytic_Wind_Throughput as one of the analytic step in the deployment, then select that node to access Analytic_Wind_Throughput subsection of the 2. I/O Mapping section in the deployment.
  7. Select a version in the drop-down list box in the Version column, and then select Use this Version.
    The Mapping may be lost box appears with the message If there are structural changes between analytic versions, you may lose some or all of the existing mapping.
  8. In the Mapping may be lost box, select Continue to change the version or select Cancel to keep the current version.

Manually Map Inputs for Selected Assets (All Assets)

Use the Mapping Options box to map inputs for tags common to all assets selected in first step in Deployment.

Before You Begin

Make sure you have selected the target assets in the first step in Deployment.

About This Task

When you select the option to map inputs for all assets, the tags common to all assets selected in the 1. Asset Selection section are available to map. Mapping for all assets will map the inputs for the assets that use the selected tag.

Procedure

  1. In the module navigation menu, navigate to Analytics > Deployments.
  2. Select an existing deployment to access its workspace.
  3. In the page heading, select Edit to access the 1. Asset Selection section.
  4. Select the 2. I/O Mapping tab.
  5. Select to access the ASSET(S) pane.
  6. Select the Change Selection button.
  7. In the list, select the value All Assets.
    The value in the ASSET(S) pane displays the selected value.
  8. In the Common subsection, select the Tags node to access tags available for mapping.
    • Navigate the tree structure to find specific tags to map.
    • Or enter characters in the Search expanded tags box to find tags. Results are provided as you enter characters.
    Note: If there are no tags common to the selected assets, you must map by asset.
  9. Select a tag, drag and drop it onto the input row to map it.
  10. Perform any of the following optional steps in the INPUT DEFINITION: TAGS & ATTRIBUTES table:
    To do thisDo this
    Change the number of inputs per pageSelect a value in the Rows per page box to display more or less results. The maximum number of inputs per page is 20.
    Navigate between pages of the inputsIf the number of inputs exceed the maximum page display, the results are distributed across multiple pages. Use the page number link or the arrow links to navigate between pages.
  11. Repeat mapping tags for each required input definition.
    Important:
    • The MAPPING KEY column indicates which inputs are required.
    • Map one input per tag. Do not map the same tag to multiple inputs for the selected asset.
    • You cannot proceed until all required tag definitions are mapped.
  12. Select Save Changes to apply and save the mapping configuration.

Manually Map Inputs per Asset (Asset by Asset)

Map inputs to tags associated with a single asset applied in asset selection during deployment.

Before You Begin

Make sure you have selected the target assets in the 1. Asset Selection section for the deployment.

About This Task

Use this procedure to map tags or attributes for each selected asset individually. After an asset is selected for mapping, only input definitions for that asset are displayed in the INPUT DEFINITION: TAGS & ATTRIBUTES table, and only the selected asset tags and asset attributes are available as nodes in the Tags and Attributes pane. displays tags and attributes for the selected asset.

Procedure

  1. In the module navigation menu, navigate to Analytics > Deployments.
  2. Select an existing deployment to access its workspace.
  3. In the page heading, select Edit to access the 1. Asset Selection section.
  4. Select the 2. I/O Mapping tab.
  5. Select to access the ASSET(S) pane.
  6. Select the Change Selection button.
  7. Select an asset value in the list.
    The value in the ASSET(S) pane displays the selected value.
  8. In , select the Tags node to access tags available for mapping.
    • Navigate the tree structure to find specific tags to map.
    • Or enter characters in the Search expanded tags box to find tags. Results are provided as you enter characters.
  9. Select a tag, drag and drop it onto the input row to map it.
  10. Perform any of the following optional steps in the INPUT DEFINITION: TAGS & ATTRIBUTES table:
    To do thisDo this
    Change the number of inputs per pageSelect a value in the Rows per page box to display more or less results. The maximum number of inputs per page is 20.
    Navigate between pages of the inputsIf the number of inputs exceed the maximum page display, the results are distributed across multiple pages. Use the page number link or the arrow links to navigate between pages.
  11. Repeat mapping tags for each required input definition, then select the Change Selection button in the ASSET(S) box to select another asset.
    Important:
    • The Tags column indicates which inputs are required.
    • Map one input per tag. Do not map the same tag to multiple inputs for the selected asset.
    • You cannot proceed until all required tag definitions are mapped.
  12. Select Save Changes to apply and save the mapping configuration.

Map Inputs with Suggested Tags

Use the Suggested Tags option to map inputs for tags that have the same name as the input.

Before You Begin

Ensure that you have selected the target assets in the first step in deployment.

About This Task

Automapping maps the input and constant ports of an analytic with the tags or attributes of an asset that matches the names of the ports. Depending on the Mapping Value Type (MVT), that is, a tag or attribute of each input and constant port of an analytic, automapping searches for the corresponding tag or attribute that matches the port name in the assets that are a part of the asset filter, and then assigns the tag or attribute to each port. In addition, the data source corresponding to a tag or attribute is automatically selected for each input, constant, and output ports.

In addition to APM Time Series and APM Asset data sources, any data sources that are used must be registered with TMS. CAF recognizes two types of tags, which are Sensor and Computed. Sensor tags are assigned to input ports, and Computed tags are assigned to output ports. The tenant must assign a default data source for each type of tags and attributes.

If you have configured input parameters similar name as tags available for mapping, then you may use the Suggested Tags option to speed up the mapping process.

Procedure

  1. In the module navigation menu, navigate to Analytics > Deployments.
  2. Select an existing deployment to access its workspace.
  3. In the page heading, select Edit to access the 1. Asset Selection section.
  4. Select the 2. I/O Mapping tab.
  5. In the INPUTS: TAGS & ATTRIBUTES table, select the Get Suggested Mapping button to access tag suggestions to map to inputs.
  6. If you accept the suggestions, select Save Selected. If you do not want to accept suggestions or if no suggestions are listed, select Reset.
  7. Repeat for each required input tag.
    Important:
    • The Tags column indicates which inputs are required.
    • Map one input per tag. Do not map the same tag to multiple inputs for the selected asset.
    • You cannot proceed until all required tag definitions are mapped.
  8. Select Save to apply and save the mapping configuration.

Map Multiple Tags to an Input

You can map a single input port to multiple tags at any level of the asset hierarchy.

Before You Begin

This procedure assumes that the following prerequisite tasks have been completed.

  • You have uploaded the required assets, tags and time series data required for this analytic.
  • You have configured asset filters to use in the deployment.
  • You have the required access permissions to manage analytics on Spark runtime.
  • You have added and configured an Analytic Template that has the Aggregate Mapping option enabled.
  • You have created a deployment for that Analytic Template.
  • You have applied the deployment to the applicable assets through asset selection.

About This Task

This functionality is only available for tenants that are configured to support running analytics on the Spark runtime cluster environment. Depending on the tenant configuration, this option may not be available. The analytic artifact uploaded to the Analytic Template being used in the deployment also must support aggregation.

Procedure

  1. In the module navigation menu, navigate to Analytics > Deployments.
  2. Select an existing deployment to access its workspace.
  3. In the page heading, select Edit to access the 1. Asset Selection section.
  4. Select the 2. I/O Mapping tab.
  5. Select to access the ASSET(S) pane.
  6. Select the Change Selection button.
  7. In the list, select the value All Assets.
    The value in the ASSET(S) pane displays the selected value.
  8. In the Common subsection, select the Tags node to access tags available for mapping.
    • Navigate the tree structure to find specific tags to map. You can navigate at any level in the asset hierarchy including tag nodes of child assets. For example, if the Site is the parent node in the asset hierarchy, you can access common tags at its segment and asset level.
    • Or enter characters in the Search expanded tags box to find tags. Results are provided as you enter characters.
    Note: If there are no tags common to the selected assets, you must map by asset.
  9. Select a tag, drag and drop it onto the input row to map it.
  10. Select another tag, drag and drop it onto the same input row to map it too.

Results

The value in the MAPPING KEY column for that input changes to Multiple. Hovering your mouse cursor over the text shows a comma-separated list of tags that are currently mapped to that input.

Add Mapping Override to Analytic Inputs

You can add asset applicability overrides to inputs during I/O Mapping step in deployment.

Before You Begin

Make sure you have added at least one deployment. This is a tenant and runtime specific option. Make sure that the current runtime for the Analytic Template used in the deployment allows adding overrides.

About This Task

This option is only available for tenants that are configured to support input overrides during deployment. Using overrides allows you to select a different asset applicability than that defined in the 1. Asset Selection section. It is recommended that you map tags to inputs both for its default asset applicability and overriding asset applicability.

Inputs are marked as optional or required in the 2. I/O Mapping section of the Deployments page.

Procedure

  1. In the module navigation menu, navigate to Analytics > Deployments.
  2. Select an existing deployment to access its workspace.
  3. In the page heading, select Edit to access the deployment.
  4. Select the 2. I/O Mapping tab.
  5. Select to expand the Data Flow pane.
  6. Navigate to an iteration node to select it. For example, if you have Analytic_Wind_Throughput as one of the analytic steps in the deployment, then expand the node and select the iteration Analytic_Wind_Throughput_Iteration_1 to access it.
  7. In the INPUT DEFINITION: TAGS & ATTRIBUTES table, hover over the MAPPING KEY column of the input row to which you wish to add overrides. Select the to access the OVERRIDES table.
  8. Select the + Add Overrides button to add a new row.
  9. Select the Select an Asset Filter button.
  10. In the Override Criteria window that appears, select the check boxes of one or more filters listed, and then select the Add button.
    The selected asset filters appear in the Asset/Filter column.
  11. Use one of the following methods to map inputs to tags.

Results

The icon appears in the MAPPING KEY column for that input. Hovering over shows a comma-separated list of overrides.

Map Inputs, Constants, and Outputs for Assets in an Equipment Template

Map inputs, constants, and outputs for all assets within the selected equipment template in step 1 for the Analytic Deployment.

Before You Begin

This procedure applies to deployments using an equipment template for its asset applicability. Make sure you have selected the target equipment template to derive assets to map in step 1 for the Analytic Deployment.

About This Task

When you map inputs for assets within an equipment template, tags common to all assets selected in step 1 for the Analytic Deployment are available. If filters were applied to narrow the asset applicability, only tags common to those selected assets are available.

Procedure

  1. In the module navigation menu, navigate to Analytics > Deployments.
  2. In the Search pane, select an existing deployment to access its workspace.
  3. In the page heading, select Edit to access the 1. Asset Selection section.
  4. Select Next or the 2. I/O Mapping tab. You can map tags in one of the following ways:
    OptionDescription
    Mapping inputs, constants, and outputs to common tagsThe resulting list of tags are derived from an intersection of all tags within the template across all nodes. All common tags across the child nodes are listed at the root node. You can see all common tags, or tags filtered by Asset Type (class), or tags filtered by Sub Templates. For example, if GE90-Template-AV is the root node (first position), Tags node at the root of the tree structure will list all common tags.
    Mapping inputs, constants, and outputs to tags by positionThe resulting list of tags within a selected position.
    1. Select to access the ASSET(S) pane.
    2. In the Common subsection, expand nodes within the template to reveal tags common to map. You can traverse through the template structure to find common tags.
      Note: Each node starting at the root have the following structure.
      
root (Position 1)
|-tags
|-attributes
|-Sub Position 2 (equipment_1)
    |--tags    
    |--sub template_1
        |---sub position a (equipment_a)
        |---tags    
        |---sub templates
    |--attributes
 |-Sub Position 2 (equipment2)
    |--tags    
    |--sub template_2
        |---sub position b (equipment_b)
        |---tags    
        |---sub templates
    |--attributes
    3. Select the tag. Drag and drop the tag on to the input definition, constant, or output definition row to map the tag.
      The Data Source row displays the name of the mapped tag.
  5. Repeat for each required input, constant, and output tag.
    Note: You cannot proceed until all required tag definitions are mapped.
  6. Select Save to apply and save the mapping configuration.

Map an Attribute

You can map asset attribute to inputs, constants, and outputs in an analytic deployment.

Before You Begin

Make sure you have selected the target assets for your deployment.

The asset model has attributes ingested as part of the asset model.

About This Task

The data format for the component to be mapped (input, constant, or output) must be set to Asset Attribute when defining the analytic template. You cannot map attributes to data format defined as Time Series.

Procedure

  1. In the module navigation menu, navigate to Analytics > Deployments.
  2. In the Search pane, select an existing deployment to access its workspace.
  3. In the page heading, select Edit to access the 1. Asset Selection section.
  4. Select the 2. I/O Mapping tab.
  5. Select to access the ASSET(S) pane.
  6. Expand the @Reserved Attributes or @Custom Attributes nodes to select from a list of asset attributes available.
  7. Select an attribute from the list, and then drag and drop it onto the component (input, constant, or output) row to map.
    Note: You will receive an error message if you drag and drop onto the row with Time Series data format. You can only map attributes to analytic definition with the Asset Attribute or ANY data format.

    You must only select attributes that have the same data type as the defined. For example, if your analytic expects a STRING value in its input Temp Threshold, the selected attribute should also have the data type of STRING.

    The selected attribute is mapped in the Mapping Key column.
  8. Repeat this for mapping all other required definitions with Asset Attribute data format.

Modify the Output UoM Values

You can change a defined value for a unit of measure for the selected deployment. The unit of measurement (UOM) values are defined when building the Analytic Template. Changing the unit of measurements in the deployment affects the selected deployment only.

Before You Begin

Make sure you have selected the target assets for your deployment.

Procedure

  1. In the module navigation menu, navigate to Analytics > Deployments.
  2. Select an existing deployment to access its workspace.
  3. In the page heading, select Edit to access the 1. Asset Selection section.
  4. Select the 2. I/O Mapping tab.
  5. In the OUTPUT DEFINITION: TAGS & ATTRIBUTES table, select the Output UoM box to access output unit of measurements and then select a value in the list.
  6. Select Save to save the deployment.