Asset Ingestion

Asset Ingestion Process

CAUTION:

In Predix APM, adding or modifying assets using the Legacy Predix APM user interface, APIs, or Asset Ingestion Service, or bypassing the Unified Asset Ingestion Data Loader, causes the asset databases to become out-of-sync.

In Predix APM:
In Legacy Predix APM:
  • You can add, modify, or delete assets in the user interface, using APIs, or using the Asset Ingestion Service.
  • You can add tags to assets in the user interface, using APIs, or using the Asset Ingestion Service.
The asset ingestion process is two-fold:
  1. Ingest the enterprise, site, segment, and asset data using the Asset Ingestion Loader (Tools > Data Loaders). For more information on using the Asset Ingestion Loader refer to Unified Loaders documentation in About Data Loaders section of the help.
  2. Ingest reserved attributes, custom attributes, groups, templates, tags, geo location, and classifications for the ingested assets using the Ingestion Setup (Admin > Operations Manager).
When data is loaded into GE Digital APM using the Asset Ingestion Data Loader, the data is populated in both GE Digital APM Enterprise and Predix Asset databases.

Typically, a system integrator or customer administrator performs asset ingestion. The ingestion process includes the following actions:

  1. Creating an asset ingestion file.

    Asset ingestion files are JSON files that specify customer assets and their hierarchical structure or asset model.  You can specify a complete set of assets and its asset model in a single JSON file within a ZIP file, or as discrete JSON files for each type, such as classifications, instances, connections, tag classifications, and tag associations within a single ZIP file.

  2. Submitting the ingestion file.

    Appropriate credentials are needed to submit an asset ingestion file. Ask the customer administrator to provide the asset ingestor user ID and password.

  3. Verifying the ingestion.

    After submitting an ingestion file, log in to GE Digital APM to verify that the asset model and assets were ingested correctly. Correct any errors in the ingestion file and resubmit as needed.

About Asset Ingestion File

Determine how to extract asset hierarchy data and convert it to the JSON asset-ingestion file. Use the JSON asset-ingestion file to build an inventory of the assets and levels that make up the existing customer asset hierarchy. You also can use the file to develop an asset hierarchy for a new customer. Typically, the source of the hierarchy comes from a customer database. After building the asset model and data for ingestion, create a ZIP file containing JSON code for ingesting assets into GE Digital APM.

The following applies to the asset ingestion JSON file(s):

  • It must conform to the specified JSON format with all the required elements. https://apm-application-help-rc.int-app.aws-usw02-pr.predix.io/Documentation.json to download the template JSON.
    Note: If selecting the link fails to initiate the file download, then, right-click on the link and select the option to save the file. Depending on the browser, this option varies. For example, in Chrome, this option is Save as and in IE this option is Save target as. It gives you a way to save the file locally. After downloading the file, navigate to the saved folder and access the file in a text editor for accessing or modifying.
  • The values in the JSON do not support the following characters: $ < > : | ( ) , = ! ? & \.
  • Does not apply to Legacy Predix APM: The enterprise, site, segment, and asset data must be uploaded using the Asset Ingestion Loader (Tools > Data Loaders). For more information on using the Asset Ingestion Loader refer to Unified Loaders documentation in About Data Loaders section of the help.
  • You should limit the number of objects during ingestion to 150,000 objects per file. The ingestion will continue, however when you inspect the job on the data ingestion page, the summary will either load very slowly or not load at all.
  • If needed, split into individual JSON files, each for classifications, tagClassifications, and tagAssociations.
  • It may be combined into a single ZIP file, or can be ingested as separate ZIP files.
  • The recommended order of JSON files within a single ZIP file is as follows:
    Note: If the files are out of order, the ingestion utility may take longer to ingest the model and data. This latency can be caused as the utility attempts to skip elements that are out of order and ingest the required elements first. For example, it is not possible to save instances before ingesting classification. Hence the utility will skip any instances that were out of order and ingest classifications first. After the utility has gone through the queue once, it will circle back to ingest instances. If any required elements are absent, then ingestion will fail.

    You can accomplish this in the following ways:

    1. your_classifications.json
    2. your_tagClassifications.json
    3. your_tagAssociations.json
    Make sure you use a compression utility that produces ZIP files without introducing the control character (CTRL-CHAR). You can use one of the following that applies to you:
    • In Mac OS, compress the JSON into a ZIP file using command line compression utility.
      zip -r archive_name.zip your_classifications.json your_tagClassifications.json 
      your_tagAssociations.json
      Legacy Predix APM only:
    • In Windows, use utilities such as 7-Zip or WinZip to create the ZIP file. Make sure to add the JSON files in the order specified above.

Ingestion Endpoints and Credentials

Consult the following tables for information regarding requirements for ingesting data such as assets, alerts (alarms), and time series data into GE Digital APM.

Endpoints and Credentials in the Setup Page

Predix APM Only: You can view some of these key-value pairs on the Tenant Preferences page in your tenant. Log in to your tenant as a user administrator, and then select > Admin > Tenant Preferences.

Table 1. Authorization Credentials
Credential NameDescription
Grant TypeThe type of authorization to grant access to ingestion services. Typically, the default value is Password.
Client IDA large alphanumeric string typically with the prefix ingestor, which represents the client id needed for the server to authenticate the validity of the client. For example, ingestor.5dadc6577e2d410c9baffcb34ceaf841.
UsernameAn alphanumeric string that represents your ingestor username.
PasswordHidden text (asterisks) that represents the password for ingesting assets or alerts. This parameter is user-configurable.
Tenant UUIDAn alphanumeric string that represents the tenant id. For example, 6F527FC00A184CDE9693BBA2820ADF77.
Table 2. Ingestion Endpoints
EndpointDescription
Token Request URLThe access URL to obtain the authorization token required for ingesting assets and alerts into GE Digital APM. For example, https://9864edf5-b2b9-4786-9935-6821bc1a364c.predix-uaa-staging.grc-apps.svc.ice.ge.com/oauth/token.
Asset ingestion URLThe access URL to ingest assets using HTTPS through a REST client. For example, https://apm-s95-adapter-dev.grc-apps.svc.ice.ge.com/v1/asset/upload.
Alerts ingestion URLThe access URL to ingest alerts using HTTPS through a REST client. For example, https://apm-gateway-dev.grc-apps.svc.ice.ge.com/v1/jobs.
Timeseries ingestion URLThe access URL to ingest time series using HTTPS through a REST client. For example, https://apm-timeseries-services-dev.grc-apps.svc.ice.ge.com/v1/data/add?file_type=json.

Other Endpoints

You need the following endpoints to check the status of ingestion.

Table 3. Status Check Endpoints
EndpointDescription
Asset ingestion status check URLThe URL to check the status of asset ingestion using HTTP GET through a REST client. Use the https://apm-s95-adapter-<environment>.<hostname> from the asset ingestion URL, and append /v1/tasks/<uuid> (replace <uuid> with the value from the POST response). For example, https://apm-s95-adapter-dev.grc-apps.svc.ice.ge.com/v1/tasks/fdgd36378.
Alerts ingestion status check URLThe URL to check the ingestion status for alerts using HTTPS GET through a REST client. Append /<uuid>/status to the alert ingestion URL. (Replace <uuid> with the value from the POST response). For example, https://apm-gateway-dev.grc-apps.svc.ice.ge.com/v1/jobs/8C3D72213EC44D7697A8C465F858F59E/status.

For information about bulk ingestion using the Asset APIs, see About Classifications. For information about browsing using the Asset APIs, see About Instances.

Obtain the Authorization Token for your Tenant

Before You Begin

You need the following:
  • The token request URL.
  • Get the following information from the Setup section:
    • Token Request URL
    • Client ID
    • Username
  • The ingestion password that you set up during first-time tenant access as an administrator.
  • Access to a REST client such as Postman or Advanced REST client, or curl CLI.

About This Task

Use this procedure to obtain an authorization bearer token before registering services using Event Hub with your tenant. Also, before ingesting data (assets, alerts, or time series) into a specific tenant. Tokens are client-specific and usually expire within a set time period. You must obtain a new token every time your token expires.

Procedure

  1. Access your REST client.
  2. Enter the token request URL in the HOST value field.
    Note: This URL is used to authenticate the token before connecting to the respective ingestion service. You can obtain this from the Setup section.
  3. Select the POST method.
  4. In the request authorization: enter or select the following:
    1. Select Basic Auth.
    2. In the Username field, enter the Client ID obtained from the Setup section.
    3. Leave the password blank.
    The authorization headers auto populate in the request.
  5. In the request body, select x-www-form-urlencoded.
  6. Enter the following query parameters (key-value pairs):
    Note: You can obtain the values from the Setup section.
    OptionDescription
    grant_typeGrant type for ingestion. The default value is password.
    usernameIngestion account username (for example, 07F28C049E0F4F29B8E85E4A6C916D7F_ingestor).
    passwordIngestion account password created during the initial tenant setup.
  7. Select Send.

Results

On successful ingestion, you receive the authorization bearer token as a JSON response; copy this information into a temporary file. Also, make note of the expires_in field in the JSON response, as it gives the expiration time in seconds.

Example

The following code sample shows a JSON response :

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI1ZTJjOTBlYS05ZWRkLTRkYTEtODBjOC00YTBkNjdmNzdlZjMiLCJzdWIiOiI2YWY0YjBlNi1mZmY4LTRmOWEtYTdhNC1mYzI5Nzg4ZTY5YzAiLCJzY29wZSI6WyJvcGVuaWQiXSwiY2xpZW50X2lkIjoiaW5nZXN0b3IuREU2QjcxODQyODI0NENGMkE0MDlGM0YwRUU1OTBBNzQiLCJjaWQiOiJpbmdlc3Rvci5ERTZCNzE4NDI4MjQ0Q0YyQTQwOUYzRjBFRTU5MEE3NCIsImF6cCI6ImluZ2VzdG9yLkRFNkI3MTg0MjgyNDRDRjJBNDA5RjNGMEVFNTkwQTc0IiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjZhZjRiMGU2LWZmZjgtNGY5YS1hN2E0LWZjMjk3ODhlNjljMCIsIm9yaWdpbiI6InVhYSIsInVzZXJfbmFtZSI6IjlCMjY0QUU3MDk2NzQ3QzM4MEM2QjA5OUU2NkQ3NTdBX2luZ2VzdG9yIiwiZW1haWwiOiI5QjI2NEFFNzA5Njc0N0MzODBDNkIwOTlFNjZENzU3QV9pbmdlc3RvckBhcG0tYXBwbGljYXRpb24tYWNjZXB0YW5jZS5ncmMtYXBwcy5zdmMuaWNlLmdlLmNvbSIsImF1dGhfdGltZSI6MTQ0OTE2NTQyNywicmV2X3NpZyI6ImJiNjI3MzU0IiwiaWF0IjoxNDQ5MTY1NDI3LCJleHAiOjE0NDkyNTE4MjcsImlzcyI6Imh0dHBzOi8vMDRiOGM4OTEtZWRlYS00NGQ0LWI3YmEtYmIzMGQ3MDA2ZDU5LnByZWRpeC11YWEtc3lzaW50LmdyYy1hcHBzLnN2Yy5pY2UuZ2UuY29tL29hdXRoL3Rva2VuIiwiemlkIjoiMDRiOGM4OTEtZWRlYS00NGQ0LWI3YmEtYmIzMGQ3MDA2ZDU5IiwiYXVkIjpbImluZ2VzdG9yLkRFNkI3MTg0MjgyNDRDRjJBNDA5RjNGMEVFNTkwQTc0Iiwib3BlbmlkIl19.dtcD0uYyahB0ocp6I7xPoefwAxPBiXx0yqVxrmPHxagXEwuK9a1SswiG9-dIByf6ty2PMPDau4UeMwxzZg29DE6qxfEWXEOP4J7Uy_H2AiM9V9WqJg7Q2NbVoEYwlKfnH8RIScz20nDLP1IEqFHld1Kf7MhXwxhcLVed250Z0I7qmMlB1axqjcWqeBv2BdLUlgja1o5YOa9A9xq46rwZ81TyGyAu9_UavibYO6H9l4cYQYJkU5TwFJdY4D83hvxRtXpUownDC7wHVWDHUP1DXpu44F3uMkBB40K8FqbzQQmhujOmSbV5hdVaSF_QBu71a59KI78knEyclDa0BK5GHA",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIzZTU0NTgzZS0xZjIwLTQ0ZjUtODk2NC0zMTQxNDcyYzhiMzUtciIsInN1YiI6IjZhZjRiMGU2LWZmZjgtNGY5YS1hN2E0LWZjMjk3ODhlNjljMCIsInNjb3BlIjpbIm9wZW5pZCJdLCJpYXQiOjE0NDkxNjU0MjcsImV4cCI6MTQ0OTc3MDIyNywiY2lkIjoiaW5nZXN0b3IuREU2QjcxODQyODI0NENGMkE0MDlGM0YwRUU1OTBBNzQiLCJjbGllbnRfaWQiOiJpbmdlc3Rvci5ERTZCNzE4NDI4MjQ0Q0YyQTQwOUYzRjBFRTU5MEE3NCIsImlzcyI6Imh0dHBzOi8vMDRiOGM4OTEtZWRlYS00NGQ0LWI3YmEtYmIzMGQ3MDA2ZDU5LnByZWRpeC11YWEtc3lzaW50LmdyYy1hcHBzLnN2Yy5pY2UuZ2UuY29tL29hdXRoL3Rva2VuIiwiemlkIjoiMDRiOGM4OTEtZWRlYS00NGQ0LWI3YmEtYmIzMGQ3MDA2ZDU5IiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9uYW1lIjoiOUIyNjRBRTcwOTY3NDdDMzgwQzZCMDk5RTY2RDc1N0FfaW5nZXN0b3IiLCJvcmlnaW4iOiJ1YWEiLCJ1c2VyX2lkIjoiNmFmNGIwZTYtZmZmOC00ZjlhLWE3YTQtZmMyOTc4OGU2OWMwIiwicmV2X3NpZyI6ImJiNjI3MzU0IiwiYXVkIjpbImluZ2VzdG9yLkRFNkI3MTg0MjgyNDRDRjJBNDA5RjNGMEVFNTkwQTc0Iiwib3BlbmlkIl19.Kc4PioQAOeHNeGacFwfePhLSogh06RR8c4zQPPr46rD_S49UHegOq1Uv3cWnP6sttL25GaPeidTnYyFLADFF-GyORkdmKUjx4CiAdQucoKusidjoNJQmaQNhicL62B2goUNf9VYztjrBqHGZkKt2DvdtU0RtXAkgc-qFUo2ToMQj86hqc80OhiIb_2mnXOOWZswrrfxPizgk9zL22-i6a00LGsptJZ2ErCDSmpGBka6h6H-N8vVWTsOhx_nnp7jUHKGZOZQjcsqSIWwRosIE_G6kgGMpL2L_bLgDVpZiQ3Ri19K5J7co1y4TqjMF3kvXb0rOdIJsDO1PCfMztAazlw",
  "expires_in": 86399,
  "scope": "openid",
  "jti": "5e2c90ea-9edd-4da1-80c8-4a0d67f77ef3"
}

What To Do Next

Use the obtained token for accessing, registering tenant resources and performing data ingestion for the tenant.

Ingest Assets through the REST Client

Before You Begin

Important: You must ingest the enterprise, site, segment, and asset data using the Asset Ingestion Loader (Tools > Data Loaders). For more information on using the Asset Ingestion Loader refer to Unified Loaders documentation in About Data Loaders section of the help.
CAUTION:

In Predix APM, adding or modifying assets using the Legacy Predix APM user interface, APIs, or Asset Ingestion Service, or bypassing the Unified Asset Ingestion Data Loader, causes the asset databases to become out-of-sync.

In Predix APM:
In Legacy Predix APM:
  • You can add, modify, or delete assets in the user interface, using APIs, or using the Asset Ingestion Service.
  • You can add tags to assets in the user interface, using APIs, or using the Asset Ingestion Service.
You need the following:
  • Asset ZIP file containing a valid JSON file.
  • Oauth token to ingest assets.
    Important: Make sure you have a valid, unexpired token. Tokens are client specific and usually expire within a set time. Look for the token expiration in the JSON response.
  • On the Setup section, get the following information:
    • Client ID
    • Asset ingestion URL
    • Username
  • Ingestion Password that was created during initial tenant setup.
  • Access to a REST client such as Postman or Advanced REST client.

About This Task

Use the REST client to only ingest the following:
  • Reserved attributes
  • Custom attributes
  • Geo location
  • Groups
  • Templates
  • Tags
  • Classifications
You must ingest the asset model and instances before adding assets to users.
Important:
  • When ingesting classifications, tagClassifications, and tagAssociations as separate files, you must ingest the <your_classifications_filename>.zip first. You can then repeat this procedure to ingest each of the remaining files in the following order: <your_tagClassfications_filename>.zip, and <your_tagAssociations_filename.zip>.

Procedure

  1. Access your REST client.
  2. Enter the ingestion URL in the HOST value field.
  3. Select the POST method.
  4. In the request header, enter the following key-value pairs:
    Table 4. Asset Ingestion Service Headers
    ParameterDescription
    AuthorizationEnter the token_type followed by a space, then the access_token from the response you previously obtained, for example, bearer eyJhbGciOiJSUzI1NiJ9.A... The following code sample includes a bearer token:
    {
      "access_token": "eyJhbGciOiJSUzI1NiJ9.A...",
      "token_type": "bearer",
      "refresh_token": "eyJhbGciOiJSUzI1NiJ9.e..",
      "expires_in": 86399,
      "scope": "openid",
      "jti": "5e2c90ea-9edd-4da1-80c8-4a0d67f77ef3"
    }
    tenantThe unique ID for the tenant (for example, 07F28C049E0F4F29B8E85E4A6C916D7F)
  5. In the Body field, select form-data.
  6. Enter file in the key field and select File as the parameter type.
  7. Select the ZIP file to ingest.
    Important: You cannot load a JSON file directly. You must use a compression utility to convert the JSON to a ZIP file before ingesting.
    A sample JSON within the ZIP is shown below:
    {
        "classifications": [
            {
                "id": "Sample-Asset-Enterprise-Type",
                "name": "Sample Enterprise Type",
                "description": "Enterprise Type Descirption",
                "ccomClass": "ENTERPRISE_TYPE",
                "properties": [
                    {
                        "id": "Sample Enterprise Asset Type Property",
                        "value": [
                "Sample Enterprise Asset Type property value"
              ],
                        "type": "string"
            }
          ],
                "parent": null
        },
            {
                "id": "Sample-Asset-Site-Type",
                "name": "Sample Asset Site Type",
                "description": "Site Type Description",
                "ccomClass": "SITE_TYPE",
                "properties": [
                    {
                        "id": "Sample Site Asset Type property",
                        "value": [
                "Sample Site Asset Type property value"
              ],
                        "type": "string"
            }
          ],
                "parent": null
        },
            {
                "id": "Sample-Asset-Segment-Type",
                "name": "Sample-Asset-Segment-Type",
                "description": "Segment Type Description",
                "ccomClass": "SEGMENT_TYPE",
                "parent": null
        },
            {
                "id": "Sample-Asset-Type",
                "name": "Sample Asset Type",
                "description": "Asset Type Description",
                "ccomClass": "ASSET_TYPE",
                "parent": null
        }
      ],
        "instances": [
            {
                "id": "Sample-Asset-Enterprise",
                "name": "Sample Enterprise",
                "description": "Sample Asset entierprise description",
                "properties": [
                    {
                        "id": "Location",
                        "value": [
                "Bay Area"
              ],
                        "type": "string"
            }
          ],
                "classification": "Sample-Asset-Enterprise-Type",
                "ccomClass": "ENTERPRISE"
        },
            {
                "id": "Sample-CA-Site",
                "name": "Sample Site",
                "description": "Sample Site description",
                "properties": [
                    {
                        "id": "Sample_CA_address",
                        "value": [
                "Bay Area"
              ],
                        "type": "string"
            }
          ],
                "classification": "Sample-Asset-Site-Type",
                "ccomClass": "SITE"
        },
            {
                "id": "Sample-CA-Segment-ID",
                "name": "Samp Segment",
                "description": "Sample Segment description",
                "properties": [
                    {
                        "id": "Sample_model_number",
                        "value": [
                "Sample Segment description"
              ],
                        "type": "string"
            }
          ],
                "classification": "Sample-Asset-Segment-Type",
                "ccomClass": "SEGMENT"
        },
            {
                "id": "Sample-CA-Asset-ID",
                "name": "Sample Asset",
                "description": "Sample Description",
                "classification": "Sample-Asset-Type",
                "ccomClass": "ASSET"
        },
            {
                "id": "Sample-CA-Asset-ID_Template",
                "name": "Sample Asset",
                "description": "Sample Description",
                "classification": "Sample-Asset-Type",
                "ccomClass": "ASSET"
        },
            {
                "id": "Sample-CA-Asset-ID_Template_Embeded",
                "name": "Sample Asset",
                "description": "Sample Description",
                "classification": "Sample-Asset-Type",
                "ccomClass": "ASSET"
        }
      ],
        "connections": [
            {
                "from": {
                    "id": "Sample-CA-Site",
                    "ccomClass": "SITE"
                },
                "to": [
                    {
                        "type": "parent",
                        "id": "Sample-Asset-Enterprise",
                        "ccomClass": "ENTERPRISE"
            }
          ]
        },
            {
                "from": {
                    "id": "Sample-CA-Segment-ID",
                    "ccomClass": "SEGMENT"
                },
                "to": [
                    {
                        "type": "parent",
                        "id": "Sample-CA-Site",
                        "ccomClass": "SITE"
            }
          ]
        },
            {
                "from": {
                    "id": "Sample-CA-Asset-ID",
                    "ccomClass": "ASSET"
                },
                "to": [
                    {
                        "type": "parent",
                        "id": "Sample-CA-Segment-ID",
                        "ccomClass": "SEGMENT"
            }
          ]
        }
      ],
        "tagClassifications": [
            {
                "id": "Sample_Tag_Type_Classification_ID",
                "name": "Sample_Tag_Pressure_Classification_name",
                "description": "This is tag Pressure Classification description",
                "unitGroup": "pressure",
                "properties": [
                    {
                        "id": "compressor",
                        "value": [
                190
              ],
                        "type": "int"
            }
          ]
        }
      ],
        "tagAssociations": [
            {
                "monitoredEntity": {
                    "id": "Sample-Asset-Enterprise",
                    "ccomClass": "ENTERPRISE"
                },
                "tags": [
                    {
                        "name": "Sample Enterprise Tag",
                        "id": "Sample-Asset-Enterprise.Sample_Tag_Pressure",
                        "description": "Enterprise Tag Descrpition",
                        "classification": "Sample_Tag_Type_Classification_ID",
                        "aliases": [
                "Sample Enterprise Tag Alias"
              ]
            }
          ]
        },
            {
                "monitoredEntity": {
                    "id": "Sample-CA-Site",
                    "ccomClass": "SITE"
                },
                "tags": [
                    {
                        "name": "Sample Site Tag Pressure",
                        "id": "Sample-CA-Site.Sample_Tag_Pressure",
                        "description": "Site Tag Pressure Descrpition",
                        "classification": "Sample_Tag_Type_Classification_ID",
                        "aliases": [
                "Sample Site Tag Pressure Alias"
              ]
            }
          ]
        },
            {
                "monitoredEntity": {
                    "id": "Sample-CA-Segment-ID",
                    "ccomClass": "SEGMENT"
                },
                "tags": [
                    {
                        "name": "Sample Segment Tag name",
                        "id": "Sample-CA-Segment-ID.Sample_Tag_Segment_ID",
                        "description": "Segment Tag Pressure Descrpition",
                        "classification": "Sample_Tag_Type_Classification_ID",
                        "aliases": [
                "Sample Tag Segment Alias 1"
              ]
            }
          ]
        },
            {
                "monitoredEntity": {
                    "id": "Sample-CA-Asset-ID",
                    "ccomClass": "ASSET"
                },
                "tags": [
                    {
                        "name": "Sample Asset Tag Pressure name",
                        "id": "Sample-CA-Asset-ID.Sample_Tag_Pressure_ID",
                        "description": "Asset Tag Pressure Descrpition",
                        "classification": "Sample_Tag_Type_Classification_ID",
                        "properties": [
                            {
                                "id": "ch_attr_min",
                                "type": "Character",
                                "value": [
                    "A"
                  ]
                },
                            {
                                "id": "ch_attr_array",
                                "type": "Character",
                                "value": [
                    "Z",
                    "a",
                    "v",
                    "N",
                    "q",
                    "i"
                  ]
                },
                            {
                                "id": "sh_attr_min",
                                "type": "Short",
                                "value": [
                    -32768
                  ]
                },
                            {
                                "id": "sh_attr_max",
                                "type": "Short",
                                "value": [
                    32767
                  ]
                },
                            {
                                "id": "sh_attr_array",
                                "type": "Short",
                                "value": [
                    32767,
                    300,
                    600,
                    90,
                    158,
                    -32768
                  ]
                },
                            {
                                "id": "int_attr_min",
                                "type": "Integer",
                                "value": [
                    -2147483648
                  ]
                },
                            {
                                "id": "int_attr_max",
                                "type": "Integer",
                                "value": [
                    2147483647
                  ]
                },
                            {
                                "id": "int_attr_array",
                                "type": "Integer",
                                "value": [
                    2147483647,
                    200,
                    -500,
                    600,
                    99999,
                    -1452895
                  ]
                },
                            {
                                "id": "fl_attr_min",
                                "type": "Float",
                                "value": [
                    -3.4e+38
                  ]
                },
                            {
                                "id": "fl_attr_max",
                                "type": "Float",
                                "value": [
                    3.4e+38
                  ]
                },
                            {
                                "id": "fl_attr_array",
                                "type": "Float",
                                "value": [
                    3.4e+38,
                    3.2e+38,
                    3.1e+38
                  ]
                },
                            {
                                "id": "dbl_attr_min",
                                "type": "Double",
                                "value": [
                    -1.7e+308
                  ]
                },
                            {
                                "id": "dbl_attr_max",
                                "type": "Double",
                                "value": [
                    1.7e+308
                  ]
                },
                            {
                                "id": "dbl_attr_array",
                                "type": "Double",
                                "value": [
                    1.7e+308,
                    1.6e+302,
                    1.4e+302,
                    1.1e+38
                  ]
                },
                            {
                                "id": "bool_attr_true",
                                "type": "Boolean",
                                "value": [
                    true
                  ]
                },
                            {
                                "id": "bool_attr_fal",
                                "type": "Boolean",
                                "value": [
                    false
                  ]
                },
                            {
                                "id": "ts_attr",
                                "type": "Timestamp",
                                "value": [
                    "07/15/2016 04:45:30"
                  ]
                },
                            {
                                "id": "ts_attr_array",
                                "type": "Timestamp",
                                "value": [
                    "07/15/2016 04:45:30",
                    "07/16/2016 04:45:30",
                    "08/20/2016 04:45:30",
                    "09/21/2016 04:45:30"
                  ]
                },
                            {
                                "id": "str_attr_min",
                                "type": "String",
                                "value": [
                    "Test String"
                  ]
                },
                            {
                                "id": "str_attr_array",
                                "type": "String",
                                "value": [
                    "First",
                    "Second",
                    "Third",
                    "Fourt"
                  ]
                }
              ],
                        "reservedProperties": {
                            "status": "01",
                            "uom": "psi",
                            "dataType": "Double",
                            "resolution": "7"
                        },
                        "aliases": [
                "Sample Tag Pressure Alias"
              ]
            }
          ]
        }
      ],
        "groups": [
            {
                "id": "Sample_Tag_Group",
                "name": "Sample Tag Group",
                "description": "Sample Tag Group Description",
                "ccomClass": "GROUP",
                "associatedEntityCcomClass": "TAG",
                "properties": [
                    {
                        "id": "Sample_Tag_Group_attribute",
                        "value": [
              "Sample Tag Group Attribute Description"
            ],
                        "type": "string"
          }
        ],
                "associatedEntityIds": [
          "Sample-CA-Segment-ID.Sample_Tag_Segment_ID",
          "Sample-CA-Site.Sample_Tag_Pressure"
        ],
                "mappedInstances": [
                    {
                        "ccomClass": "ASSET",
                        "id": "Sample-CA-Asset-ID"
          }
        ]
      }
    ],
        "templates": [
            {
                "id": "Template_AV101",
                "name": "Template_AV101_Name",
                "description": "sample engine template message for Aviation- With RA",
                "notes": [
                    {
                        "content": "This is the first draft of engine template",
                        "createdBy": "aviation-admin"
            }
          ],
                "properties": [
                    {
                        "id": "effectivityDate",
                        "value": [
                        "12/05/2016 10:34:00"
                      ],
                        "type": "Timestamp"
                    }
                  ],
                "ccomClass": "TEMPLATE",
                "reservedProperties": {
                    "state": "03",
                    "status": "01"
                },
                "placeholders": [
                    {
                        "placeholderId": "PID_AV1011_A",
                        "name": "PID_AV1011_A_Name",
                        "description": null,
                        "properties": [
                            {
                                "id": "effectivityDate",
                                "value": [
                        "12/05/2016 10:34:00"
                      ],
                                "type": "Timestamp"
                    }
                  ],
                        "assetTypeAssociations": [
                            {
                                "id": "Sample-Asset-Type",
                                "ccomClass": "ASSET_TYPE",
                                "isPrimary": true,
                                "status": "ACTIVE"
                }
              ],
                        "tagTypeAssociations": [
                            {
                                "id": "Sample_Tag_Type_Classification_ID",
                                "ccomClass": "TAG_TYPE",
                                "tagExpressions": [
                                    {
                                        "idExpr": "{ASSET.ID}.{TAG_TYPE.ID}.{range}.TE1",
                                        "nameExpr": "{ASSET.NAME}_{TAG_TYPE.NAME}_TE1",
                                        "timeSeriesLinkExpr": "{ASSET.ID}-{TAG_TYPE.ID}-TE1",
                                        "range": "[1 - 2]"
                  }
                ]
              }
            ],
                        "placeholders": [
                            {
                                "placeholderId": "PID_AV1011_B",
                                "name": "PID_AV1011_B_Name",
                                "description": null,
                                "properties": [
                                    {
                                        "id": "effectivityDate",
                                        "value": [
                        "12/05/2016 10:34:00"
                      ],
                                        "type": "Timestamp"
                    }
                  ],
                                "assetTypeAssociations": [
                                    {
                                        "id": "Sample-Asset-Type",
                                        "ccomClass": "ASSET_TYPE",
                                        "isPrimary": true,
                                        "status": "ACTIVE"
                }
                  ],
                                "tagTypeAssociations": [
                                    {
                                        "id": "Sample_Tag_Type_Classification_ID",
                                        "ccomClass": "TAG_TYPE",
                                        "tagExpressions": [
                                            {
                                                "idExpr": "{ASSET.ID}.{TAG_TYPE.ID}.{range}.TE1",
                                                "nameExpr": "{ASSET.NAME}_{TAG_TYPE.NAME}_TE1",
                                                "timeSeriesLinkExpr": "{ASSET.ID}-{TAG_TYPE.ID}-TE1",
                                                "range": "[1 - 2]"
                  }
                ]
              }
                  ]
                }
    
                        ]
    
                }
                ]
            },
            {
                "id": "Template_AV101_Embeded_Template",
                "name": "Template_AV101_Name_EmbededTemplate",
                "description": "sample engine template message for Aviation- With RA",
                "revision": "0",
                "notes": [
                    {
                        "content": "This is the first draft of engine template",
                        "createdBy": "aviation-admin"
            }
          ],
                "ccomClass": "TEMPLATE",
                "reservedProperties": {
                    "state": "03",
                    "status": "01"
                },
                "placeholders": [
                    {
                        "placeholderId": "PID_AV1011_Embeded",
                        "name": "PID_AV1011_Embeded_Name",
                        "description": null,
                        "assetTypeAssociations": [
                            {
                                "id": "Sample-Asset-Type",
                                "ccomClass": "ASSET_TYPE",
                                "isPrimary": true,
                                "status": "ACTIVE"
                }
              ],
                        "tagTypeAssociations": [
                            {
                                "id": "Sample_Tag_Type_Classification_ID",
                                "ccomClass": "TAG_TYPE",
                                "tagExpressions": [
                                    {
                                        "idExpr": "{ASSET.ID}.{TAG_TYPE.ID}.{range}.TE1",
                                        "nameExpr": "{ASSET.NAME}_{TAG_TYPE.NAME}_TE1",
                                        "timeSeriesLinkExpr": "{ASSET.ID}-{TAG_TYPE.ID}-TE1",
                                        "range": "[1 - 2]"
                  }
                ]
              }
              ]
            }
          ]
        }],
        "templateConnections": [
            {
                "templateId": "Template_AV101",
                "parentEntityId": null,
                "parentEntityCcomClass": null,
                "connections": [
                    {
                        "id": "Sample-CA-Asset-ID_Template",
                        "placeholderId": "PID_AV1011_A",
                        "ccomClass": "ASSET"
            },
                    {
                        "id": "Sample-CA-Asset-ID_Template_Embeded",
                        "placeholderId": "PID_AV1011_B",
                        "ccomClass": "ASSET"
            }
          ]
        },
            {
                "templateId": "Template_AV101_Embeded_Template",
                "parentEntityId": null,
                "parentEntityCcomClass": null,
                "connections": [
                    {
                        "id": "Sample-CA-Asset-ID_Template_Embeded",
                        "placeholderId": "PID_AV1011_Embeded",
                        "ccomClass": "ASSET"
            }
          ]
        }
      ]
    
    
    }
    
  8. Select Send.

Results

On successful acceptance, you receive a 200 OK in the JSON response. Note that the ingestion happens asynchronously, which means that your request is queued for the server to process it. You must check the ingestion progress through HTTP GET to make sure if ingestion was successful. Save the uuid from the JSON response for tracking purposes.

Example

The following code sample appears a JSON response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 293

{
  "tenantUuid": "A5BE798652EE43F0BDE0CA20A7239BBB",
  "description": "Upload S95 assets from zip file: newE2EAsset.zip, size: 1927 bytes",
  "status": "QUEUED",
  "ingestionLogMsgList": [],
  "uuid": "2408ba25-77d2-42b2-9a8f-88b01875a86b",
  "isActive": true,
  "createdOn": 1464298499106,
  "updatedOn": 1464298499106
}

What To Do Next

Verify asset ingestion.

For information about bulk ingestion using the Asset APIs, see About Classifications. For information about browsing using the Asset APIs, see About Instances.

Ingest Assets through the User Interface

Before You Begin

Important: You must ingest the enterprise, site, segment, and asset data using the Asset Ingestion Loader (Tools > Data Loaders). For more information on using the Asset Ingestion Loader, refer to Unified Loaders documentation in the About Data Loaders section of the help.
CAUTION:

In Predix APM, adding or modifying assets using the Legacy Predix APM user interface, APIs, or Asset Ingestion Service, or bypassing the Unified Asset Ingestion Data Loader, causes the asset databases to become out-of-sync.

In Predix APM:
In Legacy Predix APM:
  • You can add, modify, or delete assets in the user interface, using APIs, or using the Asset Ingestion Service.
  • You can add tags to assets in the user interface, using APIs, or using the Asset Ingestion Service.
You must have the Asset ZIP file containing one or more valid JSON files. You must have access to the Asset Ingestion module in your application.

About This Task

Ingest only the following asset data through the user interface:

  • Reserved attributes
  • Custom attributes
  • Geo location
  • Groups
  • Templates
  • Tags
  • Classifications
As an administrator or asset modeler, you can ingest the asset model and asset data through the user interface. You must do this before adding assets to users.
Important:
  • When ingesting classifications, tagClassifications, and tagAssociations as separate files, you must ingest the <your_classifications_filename>.zip file first. You can then repeat this procedure to ingest each of the remaining files in the following order: <your_tagClassfications_filename>.zip, and <your_tagAssociations_filename.zip>.
The following limitations exist for asset ingestion:
  • Same file cannot be reingested until completed. Unless, the file has been in progress for more than 30 minutes.
  • Ingestion zip file size is limited to 10 MB.
The following table displays a summary of the last 100 ingestions:
Field Description
File NameDisplays the name of the ingestion file.
StatusDisplays the status of the ingestion. The status can be any of the following:
  • Uploading Files - The files are being uploaded.
  • File upload failed - The file upload has failed.
  • In queue - The file is in queued to be processed.
  • Failed - The ingestion did not complete successfully.
  • Completed with errors - The ingestion completed with errors.
Task ProgressDisplays the percentage of the ingestion.
Start TimeDisplays the date and time the ingestion started.
End TimeDisplays the date and time the ingestion ended.
File SizeDisplays the size of the ingestion file.

Procedure

  1. In the module navigation menu, go to Ingestion Setup.
  2. Select Upload Data in the Asset Ingestion page.
  3. Select anywhere in the text field.
  4. In the dialog box, navigate to the location of the ZIP file and select it. Make sure you upload a zip file containing only one JSON file.
  5. Select Open to select the file for upload.
    The Upload button becomes enabled only after you select a valid ZIP file for upload. An error message appears if you select an invalid file type.
  6. Select the Check for existing objects before creating new check box for the ingestion process to check the system for any existing objects and update the record in the system. Note that selecting this check box may cause the ingestion to take longer to process. If the file selected for upload is already in progress, the File ingestion is already in progress message appears. Select Close to prevent re-uploading the same file.
  7. Select Upload to initiate the upload process. The file is added to the upload log that appears on the Asset Ingestion page. Note that the ingestion happens asynchronously, which means that on selecting Upload, the file is not processed immediately but is queued for the server to process it.
  8. Select on the file name link to access the detailed information:
    Element Description
    Start TimeDisplays the date and time the ingestion started.
    End TimeDisplays the date and time the ingestion ended.
    Ingestion StatusDisplays the status of the ingestion. For more details on each status, see the table below.
    Task ProgressDisplays the percentage of the task completed.
    Ingested FilesDisplays the number of files ingested.
    Files with ErrorsDisplays the number of files ingested with errors.
    Skipped ItemsDisplays the number of items skipped during the ingestion.
    Completed ObjectsDisplays the number of objects completed during the ingestion.
    Failed ObjectsDisplays the number of objects failed during the ingestion.
    Pending ObjectsDisplays the number of objects pending.
    ErrorsThis section appears any errors that have occurred during the ingestion. The following information appears:
    • Time Stamp - Date and time of the error.
    • Resource - Appears the file name of the ingestion.
    • Action - Appears the action of the ingestion.
    • Message - Appears a detailed message of the error.
    • Recommendation - Appears a recommendation for the error.

    Enter a parameter to filter the search.

    Rows per pageSelect the drop-down error to change number of rows. The options are: 10, 20, 50, and 100.
    Skipped ItemsDisplays any items that were skipped during the ingestion.

Results

The following legends display:
LegendDescription
CompletedThe ingestion completed successfully. You should be able to see the ingested asset data in the Assets module.
Completed with ErrorsThe ingestion completed with errors. Review the error(s) for details and possible resolution. Some of these errors can be related to data validation issues.
In ProgressThe file ingestion into the application asset store is currently in progress. Ingested assets will be available in the application after the ingestion completes.
Skipped The file ingestion was skipped due to the file being already in progress from a previous ingestion. Wait for the previous ingestion to complete or wait 30 minutes to re-ingest the file.

Asset Ingestion HTTP Status Codes

GE Digital APM Time Series microservices adhere to standard HTTP and REST conventions in its use of HTTP status codes.

The following HTTP status codes provide information that may help with troubleshooting any ingestion-related issues. The information returned may vary depending on the type of HTTP method used (GET or POST).

Table 5. HTTP Status Codes
Status CodeMeaning
200 OK

If a valid ZIP file is attached, or the ZIP file is empty, the task status varies based on ingestion progress. The code for a valid ZIP file displays as Inprogress, QUEUED, or Completed.

If the JSON within the ZIP file is empty, the task status displays as failed.

202 AcceptedA new resource was created successfully. Check the Location header in the response to get information on the resource URI.
204 No ContentAn update to an existing resource was applied successfully.
400 Bad RequestThe request was not formatted appropriately. Review the response body for additional information on the type of error that occurred. For example, this error appears if you did not attach a ZIP file, or your request contains invalid query syntax or operators.
401 UnauthorizedThe request failed authentication; the provided credentials are either invalid, or were not provided. This can also happen when the token has expired.
404 Not FoundThe requested resource was not found. It might mean that the resource you requested was not created at the server side.
500 Server ErrorYou receive a server error if down-stream systems are not available.

Exception: You may receive a 500 instead of a 404 when you are updating a tag group with a non-existing URI.

Verify Asset Ingestion

About This Task

After submitting an asset ingestion file, you can use HTTP GET or the GE Digital APM application to verify asset ingestion. GE Digital APM reconciles multiple submissions of the same file and prevents duplicate instances of the same asset.

Procedure

  • Use the HTTPS GET method to track the ingestion progress:
    1. In the REST client, select the GET method.
    2. In the Host value field, enter the http://apm-adapter-config-provider-<environment>.<hostname_from_asset_ingestion_url>/v1/tasks/<uuid>. Get the <environment> and <hostname> from the asset ingestion URL. For example, http://apm-adapter-config-provider-acceptance.grc-apps.svc.ice.ge.com/v1/tasks/f239b5ad-5a76-4319-b81c-dc051708fe4.
      Note: Replace the <uuid> with the value that you obtained in the JSON response from the earlier POST method. It should look similar to the example above.
    3. In the Header field, enter the Authorization token and tenant:
      Table 6. Request headers
      ParameterDescription
      AuthorizationEnter the token_type followed by a space, then the access_token from the response you previously obtained. For example, bearer eyJhbGciOiJSUzI1NiJ9.A... The following code sample includes a bearer token:
      {
        "access_token": "eyJhbGciOiJSUzI1NiJ9.A...",
        "token_type": "bearer",
        "refresh_token": "eyJhbGciOiJSUzI1NiJ9.e..",
        "expires_in": 86399,
        "scope": "openid",
        "jti": "5e2c90ea-9edd-4da1-80c8-4a0d67f77ef3"
      }
      tenantThe unique ID for the tenant (for example, 07F28C049E0F4F29B8E85E4A6C916D7F).
    4. Select Send. Check the status in the JSON response for the ingestion progress. A sample response is below:
      {
                  "tenantUuid" : "B9480221DA7448C19EE90C8B4539F6C4",
                  "description" : "Upload S95 assets from zip file : PetronasAssetAliasUpdate.zip
                      bytes",
                  "Status" : "IN PROGRESS...",
                  "uuid" : fe39b5ad-5a76-4319-b81c-dc051708fe4",
                  "isActive" : true,
                  "createdOn" : 1458853374558,
                  "updatedOn" : 1458853374599
              }
      
  • Verify the ingestion progress in the GE Digital APM application:
    1. Sign in to GE Digital APM.
    2. In the module navigation menu, go to Ingestion Setup.

      The Asset Ingestion view appears in a list of transactions; each one is a single submission of an asset ingestion file.

      Note: The last one hundred (100) ingestion transactions for that tenant appear. If you want to access transactions prior to that, you can use the REST endpoint as described above.
    3. Depending on the status of the ingestion process, perform one of the following actions:
      First column (color indicator) appearsDo this
      Access the Context Browser to verify that the structure of the asset model is accurate and complete.
      Perform the task Troubleshooting asset ingestion errors.