IBM Insights Foundation for Energy documentation

Welcome to the IBM® Insights Foundation for Energy documentation, where you can find information about how to install, maintain, and use the product.

Product introduction

IBM Insights Foundation for Energy is an analytics platform for the energy and utilities industry. You can use the platform to develop new applications to support analytics use cases for your assets and networks, and to integrate existing applications with the solution.

You can use the extension capabilities that are provided by the user interface framework to build application user interfaces that meet your operational requirements.

Audience

IBM Insights Foundation for Energy is designed for personnel who are involved with analyzing energy and utility assets and determining maintenance plans.

Finding information

To find information on the web, including all translated documentation, access IBM Knowledge Center (http://www.ibm.com/support/knowledgecenter).

Accessibility features

Accessibility features help users who have a physical disability, such as restricted mobility or limited vision, to use information technology products. IBM Cognos® HTML documentation has accessibility features. PDF documents are supplemental and, as such, include no added accessibility features. For information about these features, see Accessibility features in this document.

Forward looking statements

This documentation describes the current functionality of the product. References to items that are not currently available may be included. No implication of any future availability should be inferred. Any such references are not a commitment, promise, or legal obligation to deliver any material, code, or functionality. The development, release, and timing of features or functionality remain at the sole discretion of IBM.

Solution overview

IBM® Insights Foundation for Energy is an analytics platform for the energy and utilities industry. You can use the platform to develop new applications to support analytics use cases for your assets and networks, and to integrate existing applications with the solution.

Currently, data from multiple systems must be manually analyzed. IBM Insights Foundation for Energy provides an analytics platform and core services to consolidate and correlate the data.

If you install the optional IBM Predictive Maintenance and Quality product, you can also use predictive maintenance capabilities to help you to anticipate asset failures and to predict the need for maintenance.

The product provides REST services that can be used to extend the product and provide integration interfaces to other systems.

Features
IBM Insights Foundation for Energy is an analytics platform that provides a broad range of analytics capabilities. It is based on IBM platform and analytics products.

Users and benefits
IBM Insights Foundation for Energy is designed for personnel who are involved with analyzing energy and utility assets and determining maintenance plans.

Supported asset classes and measurements
The default supported asset classes and measurements that are included with IBM Insights Foundation for Energy.

Included products
IBM Insights Foundation for Energy is built on IBM products. Versions of these products are included for use with the solution.

Concepts
IBM Insights Foundation for Energy has concepts that are unique to the solution and the energy industry. Understanding these concepts is important to understanding the data presented by the solution.

What's new
IBM Insights Foundation for Energy V1.5 is deployed on WebSphere® Application Server Liberty Profile. This new release includes simplified installation and operation, and improved customization and extension capabilities.

Features

IBM® Insights Foundation for Energy is an analytics platform that provides a broad range of analytics capabilities. It is based on IBM platform and analytics products.

IBM Insights Foundation for Energy enables applications, such as predictive maintenance or grid awareness and management, allowing energy companies to unify data and processes. It can create contextual awareness and visual insights to improve and optimize outcomes.

IBM Insights Foundation for Energy provides data management, visualization and analytics capabilities, and includes a broad range of integrated analytic technologies. It can also be used as a foundation for other analytics applications.

This foundation can be used to:

Unify systems and business processes by integrating multiple data sources such as sensors, SCADA, weather, EAM (Enterprise Asset Management).

Deliver contextual awareness by correlating, analyzing and visualizing data within and across systems and processes.

Parent topic: Solution overview

Users and benefits

IBM® Insights Foundation for Energy is designed for personnel who are involved with analyzing energy and utility assets and determining maintenance plans.

The following table describes the users and benefits that are associated with using IBM Insights Foundation for Energy.

Table 1.  IBM Insights Foundation for Energy users and benefits

If you are a...
This software can help you...

Reliability planning engineer
Analyze data on assets and networks.

Data scientist
Create and configure analysis models.

IT Administrator
Configure custom services and user interface elements.

Software developer

Create new applications.

Create new data models and services.

Create new user interfaces for new applications.

Parent topic: Solution overview

Supported asset classes and measurements

The default supported asset classes and measurements that are included with IBM® Insights Foundation for Energy.

The following table shows the default support.

Table 2. The measurements associated with each asset class

Asset Class
Measurements

Substation Transformer

Cooling Stage

Load Power

DGA Reading

Oil Temperature

Top Oil Temperature

Load Tap Changer

Distribution Transformer

Load Energy

Overhead Cable

Underground Cable

Pole

Pole Inspection

Parent topic: Solution overview

Included products

IBM® Insights Foundation for Energy is built on IBM products. Versions of these products are included for use with the solution.

Apache Jena 0.2.3

DB2® Enterprise Server Edition 10.5.0.5

IBM Cognos® Business Intelligence 10.2.2

IBM HTTP Server 8.5.5.5

IBM ILOG® CPLEX® Optimization Studio 12.6.0.1

IBM Integration Bus 9.0.0.3

IBM SPSS® Data Access Pack 7.1.1

IBM SPSS Modeler 17.0

IBM SPSS Modeler Batch 17.0

IBM SPSS Modeler Collaboration and Deployment Services Adapter 17.0

IBM SPSS Statistics 23.0

IBM SPSS Statistics 23.0 Collaboration and Deployment Services Adapter 7.0

IBM SPSS Analytic Server 2.0

IBM WebSphere® MQ 7.5.0.4

IBM WebSphere SDK Java™ Technology Edition 7.1.2.10

SPSS Collaboration and Deployment Services 7.0.0

WebSphere Application Server Liberty Profile 8.5.5.5

WebSphere Application Server Network Deployment 8.5.5.5

Parent topic: Solution overview

Concepts

IBM® Insights Foundation for Energy has concepts that are unique to the solution and the energy industry. Understanding these concepts is important to understanding the data presented by the solution.

Asset health
Asset health indicates how well a specific asset will provide its service in the future in terms of a percentage figure.

Failure
Failure is the probability that a single asset or a network will fail.

Risk
Risk is the probability of failure multiplied by the consequence of failure.

Parent topic: Solution overview

Asset health

Asset health indicates how well a specific asset will provide its service in the future in terms of a percentage figure.

IBM® Insights Foundation for Energy provides an aggregate score for the health of each asset. Factors such as age, manufacture, overload time, and others are considered when calculating the health score.

Asset health is shown in terms of a percentage figure. The higher the value for asset health, the less likely the asset will fail.

Parent topic: Concepts

Failure

Failure is the probability that a single asset or a network will fail.

The failure calculation takes into consideration the probability, in percentage terms, that the asset itself will fail as well as the impact on assets upstream and downstream from the failing asset. Network failure probability takes into account four failure probabilities:

The probability of failure of an individual asset. This is calculated as {(100 - Asset Health score) * constant}

The probability of failure of an asset downstream from the individual failing asset.

The probability of failure of an asset upstream from the individual failing asset.

The probability of the physical failure of a supporting asset. A supporting asset is one that gives physical support to the individual asset, for example, a cable c1 is physically supported by 2 poles, p1 and p2, then the physical failure probability of the cable c1 = 1 - (1 - Physical failure probability of p1) * (1 - Physical failure probability of p2).

The higher the failure score, the more likely the asset will fail.

Parent topic: Concepts

Risk

Risk is the probability of failure multiplied by the consequence of failure.

For example, if the probability of failure is 30% and the consequence of failure is 2.5%, then the risk of failure is 0.75%.

Parent topic: Concepts

What's new

IBM® Insights Foundation for Energy V1.5 is deployed on WebSphere® Application Server Liberty Profile. This new release includes simplified installation and operation, and improved customization and extension capabilities.

Revised architecture

IBM Insights Foundation for Energy now installs on three servers to support simplified installation, deployment, and operation.

User interface framework

Use the extension capabilities that are provided by the enhanced user interface framework to build application user interfaces that meet your operational needs. As an application developer, you can create customized user interface components to extend the user interface. Your administrator can register new user interface components, and configure the style, layout, widgets, access controls, and services for the pages in your application.

REST service framework

Use the extension capabilities that are provided by the enhanced Representational State Transfer (REST) service framework to create customized REST services with minimal coding. Your administrator can then register custom services, and assign access to the services to user roles in your solution.

Parent topic: Solution overview

Securing the solution

Securing your IBM® Insights Foundation for Energy solution is an important consideration. To ensure that the system is secure, you must manage who can access the system and assign the correct level of access within the solution.

Securing access to the solution

IBM Insights Foundation for Energy uses a WebSphere® Application Server Liberty Profile basic user registry to authenticate and authorize users. For more information about Liberty profile user registries, see the related link.

Your administrator assigns access to features, data, and services in your solution based on the user role groups.

The following topics explain how to manage user access to IBM Insights Foundation for Energy.

User roles and access
IBM Insights Foundation for Energy implements security by limiting access to features, data, and services based on user roles.

Adding users and groups
To access specific features or services in the solution, a user must be a member of a user role group that provides the required level of access to that feature or service. IBM Insights Foundation for Energy uses a basic user registry to define users and user role groups. You can add users and user role groups to the solution by adding users and groups to the WebSphere Application Server Liberty Profile server_ife_frwk.xml configuration file on the application server.

Modifying or removing users and groups
You can change passwords and group membership for users in IBM Insights Foundation for Energy. Membership of a user role group gives users access to the parts of the solution that are appropriate to that user role. You can change the access level of a user by updating the basic user registry to remove the user from one group and add the user to another group. You can also update the basic user registry to remove users and groups that no longer require access to the solution. To update the basic user registry, edit the WebSphere Application Server Liberty Profile server_ife_frwk.xml file on the application server.

Mapping groups to license types
IBM Insights Foundation for Energy has standard user licenses and limited user licenses. To generate usage information for the IBM License Metric Tool, you must map each user role group to the relevant license type in the slmtag_groups.properties file on the application server.

Related information

WebSphere Application server 8.5.5 product documentation: Configuring a user registry for the Liberty profile

User roles and access

IBM® Insights Foundation for Energy implements security by limiting access to features, data, and services based on user roles.

To use a specific feature of IBM Insights Foundation for Energy, a user must be a member of a user role that provides the required access level to that feature. Users and user role groups are defined in a basic user registry that is deployed with IBM Insights Foundation for Energy. The basic user registry is defined in the WebSphere® Application Server Liberty Profile server_ife_frwk.xml configuration file.

The following table shows the sample users and user role groups that are defined in the IBM Insights Foundation for Energy basic user registry, and the default access levels for the groups.

Table 3. User groups and sample users defined in the user registry

User role groups
Sample users
Default access levels

admins
Bob
Members of the admins role group have the following access levels:

Members can access the Administration Console view and the sample application.

Members also have create, read, update, and delete access to the REST services that are provided with the solution.

users
user1, user2
Members of the users role group have the following access levels:

Members can access the sample application.

Members have varying levels of access to the REST services that are provided with the solution.

After you define users for your organization, you can delete the sample users.

For more information about configuring access levels to pages and services in IBM Insights Foundation for Energy based on user role groups, see the related links.

Parent topic: Securing the solution

Related tasks

Configuring pages

Configuring REST services

Adding users and groups

To access specific features or services in the solution, a user must be a member of a user role group that provides the required level of access to that feature or service. IBM® Insights Foundation for Energy uses a basic user registry to define users and user role groups. You can add users and user role groups to the solution by adding users and groups to the WebSphere® Application Server Liberty Profile server_ife_frwk.xml configuration file on the application server.

Before you begin

Decide on the groups, users, and user passwords that you want to add to the IBM Insights Foundation for Energy basic user registry.

About this task

To add user role groups and users to IBM Insights Foundation for Energy, edit the server_ife_frwk.xml file on the application server.

Note: For each user entry that you add to server_ife_frwk.xml, you must include an encoded version of the user's password. The procedure describes how to use the Liberty profile securityUtility command line tool to encode the password for each new user. Add the encoded password that the utility outputs to the user entry in the XML file.

Procedure

Log on to the application server as a user who has edit access to the server_ife_frwk.xml file, for example, the root user.

Use the Liberty profile securityUtility command line tool to generate an encoded password for each new user. To encode a user password, run the following command:

                           /opt/IBM/WebSphere/Liberty/bin/securityUtility encode
                              userPassword

Where userPassword is the password to encode.

As a precaution, make a backup copy of the server_ife_frwk.xml file that is in the /opt/IBM/WebSphere/Liberty/user/servers/member01 directory.

To add groups and users, edit the server_ife_frwk.xml file.

To add a group, add a group element to the basicRegistry element. Then, add a member element for each user in the group. For example, to add a group that is named reliability_group with a member named reliability_engineer_1, add the following entry to the basicRegistry element in the server_ife_frwk.xml file:

                        <group name="reliability_group">
                           <member name="reliability_engineer_1"/>
                           </group>

 For each new group member, add a user element to the basicRegistry element. Each user element has a name attribute and a password attribute.

Note: Copy the encoded password that you generated for the user with the securityUtility tool into the server_ife_frwk.xml as the value for the password attribute.

For example, to add a user with the user name reliability_engineer_1, add the following user element to the basicRegistry element in the server_ife_frwk.xml file:

                        <user name="reliability_engineer_1" password="{xor}KzosKw=="/>

Where {xor}KzosKw== is the encoded password that you generated with the Liberty profile securityUtility tool for the reliability_engineer_1 user.

Results

The new groups and users are added to the basic user registry, and the users can now be authenticated when they log on to IBM Insights Foundation for Energy.

What to do next

To generate usage information for the IBM License Metric Tool, you must map each user role group to the relevant license type in the slmtag_groups.properties file on the application server. For more information, see Mapping groups to license types.

If you are an administrator, you can now assign access to pages and REST services in the solution to each new user role. For more information about configuring access control for pages and services, see the related links.

Parent topic: Securing the solution

Related tasks

Configuring pages

Configuring REST services

Modifying or removing users and groups

You can change passwords and group membership for users in IBM® Insights Foundation for Energy. Membership of a user role group gives users access to the parts of the solution that are appropriate to that user role. You can change the access level of a user by updating the basic user registry to remove the user from one group and add the user to another group. You can also update the basic user registry to remove users and groups that no longer require access to the solution. To update the basic user registry, edit the WebSphere® Application Server Liberty Profile server_ife_frwk.xml file on the application server.

Before you begin

While you update the basic user registry, ensure that the affected users are not logged on to IBM Insights Foundation for Energy.

Before you remove groups from the basic registry, ensure that the groups are not assigned access to pages and services in the solution. For more information about configuring access to pages and services in IBM Insights Foundation for Energy, see the related links.

About this task

You can modify or remove users or user role groups for IBM Insights Foundation for Energy by editing the server_ife_frwk.xml file on the application server.

Note: To change a user password in the server_ife_frwk.xml file, you must first generate an encoded version of the new password. The procedure describes how to use the Liberty profile securityUtility command line tool to encode a new password. Add the encoded password that the utility outputs to the user entry in the XML file.

Procedure

Log on to the application server as a user who has edit access to the server_ife_frwk.xml file, for example, the root user.

Use the Liberty profile securityUtility command line tool to generate an encoded password for each user password that you want to change. To encode a user password, run the following command:

                           /opt/IBM/WebSphere/Liberty/bin/securityUtility encode
                              userPassword

Where userPassword is the password to encode.

As a precaution, make a backup copy of the server_ife_frwk.xml file that is in the /opt/IBM/WebSphere/Liberty/user/serves/member01 directory.

To modify or remove users and groups, edit the server_ife_frwk.xml file.

To add members to a group, see Adding users and groups.

 To remove a member from a group, delete the member element from the group element in the server_ife_frwk.xml file.

To change the password for a user, copy the encoded password that you generated for the user with the securityUtility tool into the server_ife_frwk.xml as the value for the user's password attribute. For example, to change the password for a user with the user name reliability_engineer_1, edit the entry for the user in the server_ife_frwk.xml file as follows:

                        <user name="reliability_engineer_1" password="{xor}Lz4sLCgwLTs="/>

Where {xor}Lz4sLCgwLTs= is the new encoded password that you generated for the reliability_engineer_1 user.

 To remove a user from IBM Insights Foundation for Energy, delete the user element for that user, and remove any group member element for that user.

Results

The users and groups are modified or removed in the IBM Insights Foundation for Energy basic user registry.

What to do next

If you modified or removed user role groups, update the license mapping for the affected groups in the slmtag_groups.properties file on the application server. For more information, see Mapping groups to license types.

If you are an administrator, you can change access to pages and REST services in the solution based on the modified user role groups. For more information about configuring access control for pages and services, see the related links.

Parent topic: Securing the solution

Related tasks

Configuring pages

Configuring REST services

Mapping groups to license types

IBM® Insights Foundation for Energy has standard user licenses and limited user licenses. To generate usage information for the IBM License Metric Tool, you must map each user role group to the relevant license type in the slmtag_groups.properties file on the application server.

Before you begin

For more information about license usage metrics in IBM Insights Foundation for Energy, see License usage metrics.

About this task

To map a user role group to a license type, edit the slmtag_groups.properties file that is packaged in the ife_frwk_service WAR folder. There are two properties in the file: groups_StandardUser is the property for the standard user license, and groups_LimitedUser is the property for the limited user license.

Procedure

Log on to the application server as a user who has edit access to the slmtag_groups.properties file, for example, the root user.

Edit the slmtag_groups.properties file. The default file content maps the admins sample group to the standard user license, and maps the users sample group to the limited user license:

                           groups_StandardUser=admins

                           groups_LimitedUser=users

To map a group to the standard user license, add the group name as a value for the groups_StandardUser property. Use a comma as the delimiter between group names. For example, groups_StandardUser=standardUserGroup1,standardUserGroup2.

To map a group to the limited user license, add the group name as a value for the groups_LimitedUser property. Use a comma as the delimiter between group names. For example, groups_LimitedUser=limitedUserGroup1,limitedUserGroup2.

Results

Usage information for the two types of licensed users in IBM Insights Foundation for Energy is generated for the IBM License Metric Tool.

Parent topic: Securing the solution

Managing the Standard Operating Procedures

A Standard Operating Procedure (SOP) is a set of instructions that describes all the relevant steps and activities of a process or procedure.

IBM® Insights Foundation for Energy enables an administrator to organize personnel, information, and tasks in response to events and incidents in order to achieve a comprehensive control of the operation. A SOP comprises of these components:

Standard Operating Procedure Definition

An SOP definition is the template that is used when a SOP is instantiated in response to a particular occurrence. A SOP Definition is made up of activities that are described by Activity Definitions.

Activity Definition

A SOP Definition contains one or more Activity Definitions. An activity definition sets the individual instructions that need to be performed as part of the SOP.

SOP Instance

A single Instance of an SOP in response to a particular event or occurrence. One SOP Definition can be used for many SOP Instances. An SOP Instance can be in one of these states.

Active

Started

Stopped

Completed

Canceled

Activity Instance

An Activity Instance is the instantiation of a single Activity Definition. A single Activity Definition can be used to create multiple Activity Instances. An Activity Instance can be in a number of states:

Active

Waiting

Started

Skipped

Completed

References

Supplemental information which is relevant to a Standard Operating Procedure or Activity. References can also be used to define e-mail templates.

Roles

There are two abilities, Owners and Readers. These can be set against administrative and user roles.

A Reader can monitor the activities that are associated with a standard operating procedure.

An Owner can monitor and complete the activities that are associated with the standard operating procedure.

Activity Type

The Activity Type describes the response to the activity.

Manual: This type of activity must be manually carried out by the owner of the SOP.

If-Then-Else Activity: A conditional activity that allows branching based on specific criteria. The user can choose which of the SOP Definitions to instantiate when starting the activity.

Alert Activity: This activity defines an e-mail template that can be sent when a user starts this activity.

REST Activity: An activity that creates a REST service call. The user can specify the service URL and any required authentication information to be invoked when the activity is started.

SOP Activity: An activity that starts another standard operating procedure.

Roles for Standard Operating Procedures

The abilities for each of the roles for SOPs are as follows:

SOP Administrator roles

View and delete an SOP definition

Launch, view, and edit an SOP instance

Start and complete activities in an SOP instance

SOP author roles

Create, edit, view, and delete an SOP definition

Create an SOP draft

View, edit, and delete an SOP activity

Submit an SOP draft for approval

Approve an SOP draft

Reference Librarian Role

Create shared references

Owner Roles (SOP definition)

Create an SOP draft

View, edit, and delete an SOP definition

Edit and delete an SOP activity

Submit an SOP draft for approval

Approve an SOP draft

Launch, view, and edit an SOP instance

Reader roles (SOP Definition)

View an SOP definition

View an SOP instance from My Activities

View an SOP activity, provided the user has Reader role in the Activity definition

Owners roles (SOP activity)

View an SOP instance from My Activities

Start and complete activities in an SOP instance for their own activities from My Activities

Reader roles (SOP activity)

View SOP instance from My Activities

Approval life cycle for an Standard Operating Procedure

An SOP definition can assume different status during its life cycle.

Draft: When the SOP is first created, a draft version is saved initially. From an approved version of an SOP, it is also possible to create another draft version, when it is necessary to change the SOP definition using the approved version as a base. A draft can be edited, submitted for approval, or discarded.

Pending approval: This is a draft SOP definition submitted for approval, ready to be approved or disapproved. The name of the version is defined in this status and it will name the SOP definition version if approved. If this version is not approved, the SOP definition goes back to the draft version status.

Approved: When an SOP definition is approved it is ready to be launched.

Figure 1. SOP Life Cycle

Defining a Standard Operating Procedure
Define an SOP with all activities.

Editing a Standard Operating Procedure
Edit an Standard Operating Procure.

Submitting a draft Standard Operating Procedure for approval
You can submit a draft version of an SOP for approval or discard it.

Testing a Standard Operating Procedure
Test an approved version of a Standard Operating Procedure (SOP).

Viewing a Standard Operating Procedure
You can view a Standard Operation Procedure (SOP) as an administrator.

Exporting a Standard Operating Procedure
You can export your Standard Operating Procedure definitions as an XML file. This capability is useful for migration purposes.

Importing a Standard Operating Procedure
You can import a previously exported Standard Operating Procedure definitions file. This capability is useful in cases where the organization has predefined SOPs that were implemented using a different tool.

Creating a reference for Standard Operating Procedures
References are supplemental information relevant to an SOP or an activity. References can also be used to define e-mail templates.

Reverting to a particular version of a Standard Operating Procedure
You can revert back to a particular version of a Standard Operating Procedure (SOP).

Defining a Standard Operating Procedure

Define an SOP with all activities.

Procedure

In Insights Foundation for Energy, click IFE Administration > Standard Operating Procedures > Definition .

Define the basic information for the SOP.

Click Create.

Type a name and description for the SOP.

If the activities need to be carried out in a particular order, select Activities are done in order in the General Settings field.

Click Add References to add supplemental information.

Click Next to go to the Roles section.

Define the roles for the SOP.

Select the Roles that will be assigned as Owners and Readers for the SOP created with this definition.

If you want the role to be able to monitor activities that are associated with the standard operating procedure, select Reader.

If you want a role to be able to monitor and complete activities that are associated with the standard operating procedure, select Owner.

Click Next to go to the Activities section.

Define the activities for the SOP.

Click Add.

If the activity is required, select Required. If not, the SOP can move on to the next activity during instantiation.

Select Autostart if this activity is to start automatically without owner operation.

You can select the roles for the Owners and Readers. If not, the roles are inherited from the SOP definition.

Set the duration of the activity. The duration is the length the activity takes once started.

Type a description of the activity.

Set the Activity type. The options are:

Manual Activity

If-Then-Else Activity

Alert Activity

REST Service

SOP Activity

To add more activities click Add and define the next activity for the SOP.

Click Next to go to the Summary section.

Review the SOP.

Review the information in the summary.

Click Save.

Important: The SOP is in now draft state. The SOP must be approved before it can be instantiated.

In the draft state, the SOP can be edited or deleted if not required.

Parent topic: Managing the Standard Operating Procedures

Editing a Standard Operating Procedure

Edit an Standard Operating Procure.

About this task

To be able to edit an approved Standard Operating Procedure (SOP), the SOP must be returned to a draft version.

Note: You can always edit an SOP in a draft version.

Procedure

In Insights Foundation for Energy, click IFE Administration > Standard Operating Procedures > Definition .

From the list of SOP definitions, select the SOP to be edited.

From the Version field, select the version to be edited.

Click Create Draft. The SOP state is now in draft.

Click the SOP you want to edit.

To add an activity, click Add in the Activities tab.

To edit an activity, click the activity and then click Edit.

To delete an activity, click the activity and then click Delete.

To edit a role, select the Roles tab and then click Edit.

To edit references, select the References tab, click Edit or Delete for a specific reference or click Add to add a new reference.

When the edits are complete, click Save.

What to do next

Before the edits are accepted, you must submit the draft version for approval.

Parent topic: Managing the Standard Operating Procedures

Submitting a draft Standard Operating Procedure for approval

You can submit a draft version of an SOP for approval or discard it.

Before you begin

The SOP must be have been submitted for approval, and you must have the administrator role.

Procedure

In Insights Foundation for Energy, click IFE Administration > Standard Operating Procedures > Definition .

To approve an SOP, select Submit for Approval in the Submit for Approval list.

Attention: An SOP that has been submitted for approval cannot be edited. The administrator can either Approve or Disapprove the SOP.

Parent topic: Managing the Standard Operating Procedures

Testing a Standard Operating Procedure

Test an approved version of a Standard Operating Procedure (SOP).

About this task

An SOP that is in a draft state be tested.

Procedure

In Insights Foundation for Energy, click IFE Administration > Standard Operating Procedures .

Click on the approved SOP Definition that you want to test.

Click Definition Actions and from the drop-down list select Launch.

Once launched, the SOP Definition list will update to indicated the number of Active SOPs based on this definition.

The My Activities banner indicator shows that there are one or more activities that require attention.

You can perform the SOP and check for completeness.

If the SOP needs further work, click Create Draft to return the SOP to a draft state.

Parent topic: Managing the Standard Operating Procedures

Viewing a Standard Operating Procedure

You can view a Standard Operation Procedure (SOP) as an administrator.

There are two ways to view an SOP instance:

From the SOP Administration page.

From the My Activities widget.

Viewing a Standard Operating Procedure as an administrator
You can view a Standard Operation Procedure (SOP) as an administrator.

Viewing a Standard Operating Procedure as a user
You can view a Standard Operation Procedure (SOP) as a user.

Parent topic: Managing the Standard Operating Procedures

Viewing a Standard Operating Procedure as an administrator

You can view a Standard Operation Procedure (SOP) as an administrator.

About this task

To view the SOP instance from the SOP Administration do the following steps:

Procedure

In Insights Foundation for Energy, click IFE Administration > Standard Operating Procedures .

Click on the approved SOP Definition that you want to view.

Click Definition Actions and from the drop-down list select Launch.

Once launched, the SOP Definition list will update to indicated the number of Active SOPs based on this definition.

Click the approved SOP Definition.

Click the Instances tab.

Click the SOP instance to view the details.

Parent topic: Viewing a Standard Operating Procedure

Viewing a Standard Operating Procedure as a user

You can view a Standard Operation Procedure (SOP) as a user.

Before you begin

The Standard Operating Procedure must have been launched before a user can view the instance.

About this task

Users that are not authorized to view the Standard Operation Procedures Definition administration page, can view an SOP instance from My Activities.

Procedure

In Insights Foundation for Energy, click IFE Administration .

Click the My Activities icon.

Click the SOP instance you want to view.

Parent topic: Viewing a Standard Operating Procedure

Exporting a Standard Operating Procedure

You can export your Standard Operating Procedure definitions as an XML file. This capability is useful for migration purposes.

About this task

To export an SOP definition performs the following steps:

Procedure

In Insights Foundation for Energy, click IFE Administration > Standard Operating Procedures > Definition .

Select Standard Operating Procedures Definition administration page.

From the Definition Actions drop-down list, select Export All .

In the pop-up window that is displayed, click Save File > OK .

Navigate to the directory where you want to save the SopDefinitions.xml file and click Save.

Parent topic: Managing the Standard Operating Procedures

Importing a Standard Operating Procedure

You can import a previously exported Standard Operating Procedure definitions file. This capability is useful in cases where the organization has predefined SOPs that were implemented using a different tool.

About this task

To import an SOP definition performs the following steps:

Procedure

In Insights Foundation for Energy, click IFE Administration > Standard Operating Procedures > Definition .

Select Standard Operating Procedures Definition administration page.

From the Definition Actions drop-down list, select Import.

In the Import Standard Operating Procedures window, select the XML file to upload.

The imported definitions are displayed in the list of SOP definitions. You can import an SOP definition that has the same name as an existing SOP definition. In this case, the existing SOP definition is not overwritten. Instead, two SOP definitions with the same name are displayed in the list of definitions.

Click Import.

Parent topic: Managing the Standard Operating Procedures

Creating a reference for Standard Operating Procedures

References are supplemental information relevant to an SOP or an activity. References can also be used to define e-mail templates.

About this task

A user can create references for Standard Operating Procedures.

Procedure

In Insights Foundation for Energy, click IFE Administration > Standard Operating Procedures > References .

Click Add.

In the Name field, type the name of the reference.

In the URI field, type or paste the web accessible address.

In the Description field, type a description of the reference.

If you want to restrict the use of the reference, select the Private check box. Otherwise the reference can be shared to other users.

Parent topic: Managing the Standard Operating Procedures

Reverting to a particular version of a Standard Operating Procedure

You can revert back to a particular version of a Standard Operating Procedure (SOP).

About this task

The Standard Operating Procedures shows the latest version of a definition. If you need to revert to a earlier version of a definition, you can use these steps.

Procedure

In Insights Foundation for Energy, click IFE Administration > Standard Operating Procedures > Definition .

From the list of SOP definitions, select the SOP to be edited.

From the Version field, select the version to be reverted to.

Click Create Draft. The SOP state is now in draft.

What to do next

Before the revert is accepted, you must submit the draft version for approval.

Parent topic: Managing the Standard Operating Procedures

Use case: Define a new asset class in the data model

In this tutorial, you are the administrator of a system and you have a new asset class called Meter as well as assets belonging to this asset class.

You want to integrate the new asset class called Meter into IBM Insights Foundation for Energy. Assets belonging to this asset class need to be integrated into current system. These are the steps required to integrate the new asset class Meter into IFE.

Define the Ontology for the new asset class
Ontology is used to define the supported assets classes and the properties of the asset classes.

Prepare and load Static Data
When you have completed defining the new asset class Meter, you can prepare static data files, define the asset and load the data files to the database.

Prepare and load the dynamic data
Prepare the data files and tables for the dynamic data, load the dynamic data and define the asset style.

Define the Ontology for the new asset class

Ontology is used to define the supported assets classes and the properties of the asset classes.

IBM® Insights Foundation for Energy integrates data from different data sources, for example EAM System, GIS System. Data from different sources are consolidated into a common asset class and properties definitions. The mapping between an external object id and an internal object id is also maintained by IBM Insights Foundation for Energy.

Defining the resource type
The resource type is the category of the asset. In this use case the resource type is Meter. When you have created the resource type you can add meter instruments to this resource type.

Defining the property type and creating the database table
Attributes of the new resource type are stored in a database table called Meter. You need to create this table.

Registering the table
After you have created the CIM.METER table, you need to run a procedure to register the physical table to bind it to the resource type.

Modifying the property name and description
You need to check the property name and description fields in the CIM.PROPERTYTYPE table and make edits if necessary.

Parent topic: Use case: Define a new asset class in the data model

Defining the resource type

The resource type is the category of the asset. In this use case the resource type is Meter. When you have created the resource type you can add meter instruments to this resource type.

About this task

To define a new resource type Meter, you need to add a new row to the resource type table in the data base for IBM® Insights Foundation for Energy.

Procedure

In the database for IBM Insights Foundation for Energy add a new row to the CIM.RESOURCETYPE table. Here is an example for the resource type Meter.

                     INSERT INTO CIM.RESOURCETYPE(CODE, NAME, ISASSET,  ISRESOURCE,
                        CIMID, TABLE, SERVICEURL, DESCRIPTION)
                        VALUES  ('Meter', 'Meter', 1, 1, null, null,
                        '/asset/MyAsset', 'Meter asset');

Parent topic: Define the Ontology for the new asset class

Defining the property type and creating the database table

Attributes of the new resource type are stored in a database table called Meter. You need to create this table.

About this task

To store attributes for the new defined resource type, you need to create a new table in the IBM® Insights Foundation for Energy database.

Procedure

Here is an example SQL command to create a table named CIM.Meter

                     CREATE TABLE CIM.Meter(
                        oid BIGINT NOT NULL,
                        serialNumber VARCHAR(128) NOT NULL,
                        isActive CHAR(1) NOT NULL,
                        installationDate DATE,
                        removalDate DATE,
                        lastUpdateTime TIMESTAMP NOT NULL GENERATED
                        ALWAYS FOR EACH ROW ON UPDATE AS ROW CHANGE TIMESTAMP  IMPLICITLY HIDDEN,
                        manufacture VARCHAR(128),
                        randomError INTEGER
                        )

Parent topic: Define the Ontology for the new asset class

Registering the table

After you have created the CIM.METER table, you need to run a procedure to register the physical table to bind it to the resource type.

About this task

You need to register the CIM.METER table to the resource type.

Procedure

Run the command: CALL CIM.Generate_Resource_Type_Metadata('Meter', 'CIM', 'METER'); in the IBM® Insights Foundation for Energy database.

Check the 3 parameters in the stored procedure:

CODE of the logical resource and should be the same as the CODE in the ResourceType table.

the schema name from when you created physical table, for example the schema name for CIM.METER is CIM.

the table name without the schema name, for example the table name of CIM.METER is METER

Open the IBM Insights Foundation for Energy database check the CIM.RESOURCETYPE table to validate that the physical table registered successfully. Make sure that the value of TABLE column is correct.

Figure 2. Register table

Parent topic: Define the Ontology for the new asset class

Modifying the property name and description

You need to check the property name and description fields in the CIM.PROPERTYTYPE table and make edits if necessary.

Procedure

Open the IBM® Insights Foundation for Energy database check the CIM.PROPERTYTYPE table to validate that the CUSTOM PROPERTIES registered successfully. All the columns in the CIM.METER table are automatically registered in the property type table.

You are able to edit the property codes to be in the right case that you need. For example: serialnumber, isactive installationdate, removaldate and randomerror to serialNumber, isActive, installationDate, removalDate and randomError.

You are also able to edit the NAME and DESCRIPTION columns to a more user friendly name and description.

If you want to use some of the custom properties as filter criteria, edit the CIM.PROPERTYTYPE table and set ISMINIMAL to 1.

Figure 3. Property type table

Create an index in the target column of the physical asset table to improve filter performance. For example:

                        CREATE INDEX CIM.Meter_customprop1_IDX
                           ON CIM.METER
                           (randomError  ASC)
                           MINPCTUSED 0
                           ALLOW REVERSE SCANS
                           PAGE SPLIT SYMMETRIC
                           COLLECT SAMPLED DETAILED STATISTICS
                           COMPRESS YES;

Parent topic: Define the Ontology for the new asset class

Prepare and load Static Data

When you have completed defining the new asset class Meter, you can prepare static data files, define the asset and load the data files to the database.

Defining the data for the resource
The resource data is saved in a .csv file that you need to create and add content to.

Defining the terminal data
The terminal data is saved in a .csv file that you need to create and add content to.

Defining the connectivity node data
The connectivity node data is saved in a .csv file that you need to create and add content to.

Defining the measurement data
The measurement data is saved in a .csv file that you need to create and add content to.

Defining the asset data
The asset data is saved in a .csv file that you need to create and add content to.

Configuring the data loader
The data loader needs to be configured and a new section to be added to the config.properties file.

Loading the static data

Parent topic: Use case: Define a new asset class in the data model

Defining the data for the resource

The resource data is saved in a .csv file that you need to create and add content to.

Procedure

Go to /opt/IBM/energy/data/cityname/resources on the application server, and create a file called meter.csv.

Add the following content to the file:

                        <isActive>, <mRID>,
                           <resourceType>,<name>,<description>,<isContainer>,<container>,
                           <location>,<direction>,<mainAddress>,<phone1>,<phone2>,<secondaryAddress>,
                           <locationDescription>,<geometry>

The resource CSV file is loaded to the ObjectID, Resource and Location tables. The columns in the CSV file include:

Table 4. The columns in the .csv file

Field | Type | Description
isActive | CHAR(1) | Delete tag, 0 remove, 1 insert or update
mRID | VARCHAR(256) | Master resource id. A string based identifier of the logical resource.
resourceType | VARCHAR(128) | Code of the resource type defined in the ResourceType table.
name | VARCHAR(128) | The name of the logical resource.
description | VARCHAR(512) | The description of the logical resource.
isContainer | CHAR(1) | Indicates if the logical resources is a container (has children), 0 not container, or 1 is container.
container | VARCHAR(256) | The Master resource id of the container of the logical resource.
location | VARCHAR(256) | The master resource id of the location.
direction | VARCHAR(32) | The direction of a given asset. that shows field crews to quickly find a given asset. For example: NW shows to a field crew that a street light is located NW (northwest) of the customer's site.
mainAddress | VARCHAR(256) | Main address of the location.
phone1 | VARCHAR(32) | Phone number
phone2 | VARCHAR(32) | Phone number
secondaryAddress | VARCHAR(256) | Secondary address of the location. For example, a PO Box address may have different ZIP code than that in the mainAddress.
geometry | GEOMETRY | The geometry of the resource in Well-Known Text (WKT), normally this information comes from the Geographical Information System (GIS).
locationDescription | VARCHAR(256) | Description of the location.

Here is a sample CSV section that needs to be added to the meter.csv file:

                        isActive,mRID,resourceType,name,description,isContainer,container,location,
                           direction,mainAddress,phone1,phone2,secondaryAddress,
                           locationDescription,geometry
                           1,Meter_1813699,Meter,Meter_1813699,Meter_1813699,0,Substation_NIXON,
                           Loc_Meter_1813699,,Southern Yellow Pine,,,,CCA,
                           POINT (-83.4973760 42.5683241)

Parent topic: Prepare and load Static Data

Defining the terminal data

The terminal data is saved in a .csv file that you need to create and add content to.

Procedure

Go to /opt/IBM/energy/data/cityname/terminals on the application server, and create a file named meter.csv.

Add the following content to the file:

                        <isActive>,<mRID>,<name>,<description>,<sequenceNumber>,
                           <connected>,<phases>,<resource>,<connectivityNode>

The resource CSV file is loaded to the ObjectID, Resource and Location tables. The columns in the CSV file include:

Table 5. The columns in the .csv file

Field | Type | Description
isActive | CHAR(1) | Delete tag, indicates if current terminal is active.
mRID | VARCHAR(256) | Master resource id. A string based identifier of the terminal.
name | VARCHAR(128) | The name of the terminal.
description | VARCHAR(512) | Description of terminal.
sequenceNumber | INTEGER | The sequence number of terminal. If a resource has multiple terminals, the sequence number is used to order the terminals in sequence.
connected | CHAR(1) | Indicates if the terminal is connected.
phases | VARCHAR(32) | The phases of the terminal.
resource | VARCHAR(256) | The mRID of the resource that the terminal is connected to.
connectivityNode | VARCHAR(256) | The mRID of the connectivity node that the terminal is connected to.

The meter asset is connected to distribution transformer through terminals and connectivity nodes. If the meter Meter_1813699 is connected to the distribution transformer DT_101221, the terminal of Meter_1813699 is Terminal_Meter_1813699_1 and the terminal of DT_101221 is Terminal_DT_101221_2. The two terminals are both connected to connectivity node CN_cn85555. Below is a diagram for the connection information:

Here is a sample csv that needs to be added to the meter.csv file.

                        isActive,mRID,name,description,sequenceNumber,connected,phases,
                           resource,connectivityNode
                           "1","Terminal_Meter_1813699_1","Terminal 1","Terminal 1","1","1",,
                           "Meter_1813699","CN_cn85555"
                           "1","Terminal_DT_101221_2","Terminal 2",
                           "Terminal 2","2","1",,"DT_101221","CN_cn85555"

Parent topic: Prepare and load Static Data

Defining the connectivity node data

The connectivity node data is saved in a .csv file that you need to create and add content to.

About this task

Procedure

Go to /opt/IBM/energy/data/cityname/connectivityNodes on the application server, and create file called meter.csv.

Add the following content to the file:

                        <isActive>,<mRID>,<name>,<description>,<container>

The resource CSV file is loaded to the ObjectID, Resource and Location tables. The columns in the CSV file include:

Table 6. The columns in the .csv file

Field | Type | Description
isActive | CHAR(1) | Delete tag. Indicates if current connectivity node is active.
mRID | VARCHAR(256) | Master resource id. A string based identifier of the connectivity node.
name | VARCHAR(128) | The name of the connectivity node.
description | VARCHAR(512) | The description of the connectivity node.
container | VARCHAR(256) | The Master resource id of the container of the connectivity node.

As the meter asset is connected to distribution transformer here is a sample csv section that needs to be added to meter.csv. In the teminal data file, it defines Meter_1813699 is connected to distribution transformer DT_101221, through 2 terminals and 1 connectivity node, so here below example defines the detail of the connectivity node.

                        isActive,mRID,name,description,container
                           "1","CN_cn85555","cn85555","cn5555","Substation_NIXON"

Parent topic: Prepare and load Static Data

Defining the measurement data

The measurement data is saved in a .csv file that you need to create and add content to.

Procedure

Go to /opt/IBM/energy/data/cityname/measurements on the application server, and create a file named meter.csv.

Add the following content to the file:

                        <mRID>,<isActive>,<name>,<measurementType>,<phaseCode>,<unitMultiplier>,
                           <unitSymbol>,<resource>,<terminal>

The measurement CSV file is loaded to the ObjectID and Measurement table. The columns in the CSV file include:

Table 7. Columns in the measurement table

Field | Type | Description
isActive | CHAR(1) | Delete Tag. Indicates if current measurement is active.
mRID | VARCHAR(256) | Master resource ID. a string based identifier of the measurement.
name | VARCHAR(128) | The name of the measurement.
measurementType | VARCHAR(128) | The type of measurement.
phaseCode | VARCHAR(32) | The phase code of the measurement.
unitMultiplier | VARCHAR(32) | Multiplier of unit. For example: k indicates one thousand, if the symbol is V, then the fully qualified unit is kV.
unitSymbol | VARCHAR(32) | The symbol of the unit. For example: V indicates voltage.
resource | VARCHAR(256) | The mRid of the logical resource that the measurement is measuring.
terminal | VARCHAR(256) | The mRid of the terminal that the measurement is measuring.

As the data of meter measurement indicates the power payload, the sample csv section needs to be added to meter.csv file.

                        mRID,isActive,name,measurementType,phaseCode,unitMultiplier,
                           unitSymbol,resource,terminal
                           "M_MT_148610_Payload","1","PayLoad","PayLoad",,"none","none","Meter_1813699",

Parent topic: Prepare and load Static Data

Defining the asset data

The asset data is saved in a .csv file that you need to create and add content to.

Procedure

Go to /opt/IBM/energy/data/cityname/assets on the application server, and create file called meter.csv.

Add the following content to the file:

                        <mRID>,<serialNumber>,<isActive>,<installationDate>,<removalDate>,
                           <manufacture>,<randomError>

Table 8. The columns in the .csv file

Field | Type | Description
mRID | VARCHAR(256) | Master resource id. A string based identifier of the physical asset.
serialNumber | VARCHAR(128) | The serial number of the physical asset.
isActive | CHAR(1) | Indicates if the assets is currently active, 1 = active, 0 = inactive.
installationDate | VARCHAR(512) | Date when the asset was installed.
removalDate | VARCHAR(256) | The date when the asset is to be removed.
manufacturer |  | Manufacturer of the meter.
randomError |  | Random error number of the meter.

Here is the sample csv section that needs to be added to meter.csv file.

                        mRID,serialNumber,isActive,installationDate,removalDate,manufacture,randomError
                           Meter_1813699,1813699,1,1973-01-01,,ABC,4

Parent topic: Prepare and load Static Data

Configuring the data loader

The data loader needs to be configured and a new section to be added to the config.properties file.

About this task

Edit the config.properties file.

Procedure

Go to /opt/IBM/energy/data/cityname/ and open the config.properties file.

Add resources/meter.cs to the adapters.1.file section. For example:

                        adapters.1.file=resources/substation.csv,resources/substat
                           ionTransformer.csv,resources/distributionTransformer.csv,resources/o
                           verheadCable.csv,resources/undergroundCable.csv,resources/lineSegme
                           nt.csv,resources/pole.csv,resources/fuse.csv,resources/switch.csv,r
                           esources/busbar.csv,resources/dynamicProtectiveDevice.csv,resource
                           s/meter.csv

Add connectivityNodes/meter.cs to the adapters.2.file section. For example:

                        adapters.2.file=connectivityNodes/connectivityNode.csv,co
                           nnectivityNodes/busbar.csv,connectivityNodes/meter.csv

Add terminals/meter.cs to the adapters.3.name section. For example:

                        adapters.3.file=terminals/terminal.csv,terminals/busbar.csv,terminals/meter.csv

Add measurements/meter.csv to the adapters.4.file section. For example:

                        adapters.4.file=measurements/measurement.csv,measurements/meter.csv

Add new sections for the new asset Meter. For example:

                        adapters.12.name=com.ibm.ife.framework.adapter.Asset
                           adapters.12.file=assets/meter.csv
                           adapters.12.type=Meter

Save the file config.properties.

Parent topic: Prepare and load Static Data

Loading the static data

About this task

Procedure

Find the data loader tool in the application server: /opt/IBM/energy/data/runDataLoader.sh.

Run the data loader tool with the following command:

                        [root@ioc16-app data]# pwd
                           /opt/IBM/energy/data
                           root@ioc16-app data]# ./runDataLoader.sh <Path to data folder>

Parent topic: Prepare and load Static Data

Prepare and load the dynamic data

Prepare the data files and tables for the dynamic data, load the dynamic data and define the asset style.

Defining the reading data file

Creating the reading data tables
If the new measurement readings need to be stored, but the readings cannot be saved in the existing common IBM® Insights Foundation for Energy reading tables, you can create a new table in which to store them.

Inserting the routing configuration data for the new measurement reading
You need to define the routing for the new table CIM.METERPAYLOAD you cave created.

Running the data loader
When you run the data loader it monitors csv files in the incoming folder. Valid measurements csv files are processed and put into the processed folder.

Defining the asset style
You can define icon of the the asset and how it will show on the map in IBM Insights Foundation for Energy.

Parent topic: Use case: Define a new asset class in the data model

Defining the reading data file

About this task

This example applies the same use case, the asset meter that has payload reading data. The reading data files needs to be defined.

Procedure

Create and create file called meterPayload.csv on the application server, and save it to a temporary location.

Add the following content to the file:

                        <mrid>,<timestamp>,<serialNumber>, <payload>

Here is a sample CSV section that needs to be added to the meter.cs file:

                        mRID,timestamp,serialNumber,payload
                           M_MT_148610_Payload,2015-01-01 00:00:00.000,148610,20000

Copy the meterPayload.csv file to this location /opt/IBM/energy/apps/simulator/incoming on the application server.

Parent topic: Prepare and load the dynamic data

Creating the reading data tables

If the new measurement readings need to be stored, but the readings cannot be saved in the existing common IBM® Insights Foundation for Energy reading tables, you can create a new table in which to store them.

About this task

For example: The meter payload records need to be saved as a CSV file as readings in CIM.METERPAYLOAD in IFE database.

Procedure

Run the sql command to create a new table called CIM.METERPAYLOAD.

                     CREATE TABLE CIM.METERPAYLOAD(
                        measurement BIGINT NOT NULL,
                        timestamp TIMESTAMP NOT NULL,
                        serialNumber VARCHAR(128) NOT NULL,
                        payload INTEGER
                        )
                        DATA CAPTURE NONE
                        COMPRESS YES ADAPTIVE
                        VALUE COMPRESSION;

Parent topic: Prepare and load the dynamic data

Inserting the routing configuration data for the new measurement reading

You need to define the routing for the new table CIM.METERPAYLOAD you cave created.

About this task

Procedure

Run the following sq command to insert the routing information.

                        INSERT INTO CIM.CFG_MEASUREMENT_MAPPING
                           (RESOURCETYPEID,MEASUREMENTTYPE,TYPE,DESCRIPTION,
                           MESSAGEMAPPING,TARGETTABLE,COLUMNMAPPING)
                           VALUES(21,'PayLoad','Number=3,Number=4',
                           'Meter PayLoad','SerialNumber=3,payload=4','CIM.METERPAYLOAD',
                           'SerialNumber=3,payload=4'
                           )

Restart the IBM® Insights Foundation for Energy message broker.

Parent topic: Prepare and load the dynamic data

Running the data loader

When you run the data loader it monitors csv files in the incoming folder. Valid measurements csv files are processed and put into the processed folder.

Procedure

Run simulator using run_simulator.sh script:

                     [root@ioc16-app data]# pwd
                        /opt/IBM/energy/apps/simulator
                        [root@ioc16-app data]# ./run_simulator.sh

Parent topic: Prepare and load the dynamic data

Defining the asset style

You can define icon of the the asset and how it will show on the map in IBM® Insights Foundation for Energy.

About this task

The steps here are to illustrate the asset Meter.

Procedure

Go to the database, and open the AHA.ASSETSTYLE table.

Edit the table for the asset Meter.

ASSETTYPE 22, the resource type ID is 22.

GEOTYPE 0, the meter shops as a point on the map. If 1, then it shows as a line.

SHAPE, you decide what kind of icon you want to represent the asset on the map. You can also add your own icons here: /opt/IBM/WebSphere/Liberty/usr/servers/member01/apps/ife_aha_mig_app.ear/ife_aha_web.war/icon

MINSIZE and MAXSIZE defines the size of the icon.

DEVIDESCALE, keep empty

Figure 4. Define asset type style

Parent topic: Prepare and load the dynamic data

Viewing and analyzing energy data

Use IBM® Insights Foundation for Energy to analyze the health and risks to the network grid.

IBM Insights Foundation for Energy is a web-based solution that uses portal technology. You can access the solution with any supported web browser.

Assets can be viewed on a geospatial map or as a list. The displayed assets can be filtered using criteria specified by the user.

Detailed reports can be displayed for individual assets, or groups of assets.

The User Interface

The application user interface is composed of four parts:

Filter bar - to filter assets for different criteria, e.g. status, asset class, geography.

Task bar - to show or hide the filter bar, legend panel, or switch between the content to map, list or report view.

Content area - to visualize differing approaches of assets, including map, list, and report views.

Legend panel - to show the different asset classes and the score ranges the representative colors.

Figure 5. User interface shows filter and task bars, and content area and filter panel

Task bar
The task bar contains the controls for how the various panels and filter options show in user interface.

Filter bar
The filter bar contains the controls to filter assets for different criteria, e.g. status, asset class, geography.

Logging on to the Asset Health application
Log on to access the IBM Insights Foundation for Energy user interface.

Viewing assets on a map
Assets and their connections within the energy network can be seen on a geographic map. Depending on the zoom level, either individual assets and their health, or an aggregation of assets and the health of the combined assets are displayed.

Viewing assets as a list
Assets and their network health and risk values can be displayed as a list.

Filtering assets
The assets displayed on the map or list can be filtered based on selected criteria.

Preview cards
When a user clicks on an asset or region, a preview card is displayed with additional information on that asset or region.

Showing connectivity
When viewing the preview card for a single asset, you can display how the asset is connected in the network.

Viewing asset reports
You can view detailed reports on a single asset or on a group of assets.

Exporting data
After filtering the data to the desired subset, information on the selected assets can be exported for use in other systems.

Creating input for a rate use case
Using IBM Insights Foundation for Energy, regional planning engineers determine where investment is required to maintain or improve reliability.

Task bar

The task bar contains the controls for how the various panels and filter options show in user interface.

You can select how various panels, maps and reports show and also you can select the filter options that are available.

map icon Map - used to select the map view.

List icon List - used to show the data as a list.

Report icon Report - used to show the summary and treatment asset reports.

Filter icon Filter - used to show the filter bar for the filter options.

legend icon Legend - used to show or hide the legend panel on the content area.

Export icon Export - used to export the list view as CSV or XLSX file, or a report as PDF or XLSX file.

Parent topic: Viewing and analyzing energy data

Related tasks

Exporting data

Filter bar

The filter bar contains the controls to filter assets for different criteria, e.g. status, asset class, geography.

You can select the filter control options that are available. The predefined filters are:

Time - The period of time for the assets that you want to view.

Score type - There are four types: Health, Risk, Failure and Consequences. where Health is the asset health as a percentage, Failure is probability of failure, Consequence is the consequence of failure.

Status - Filters for the status for the score type you selected. There are four states, Critical, Warning, OK, No score

Geography - Filters the area map that you require.

Asset class - Shows the asset class that you want to view for the geographical area.

Advanced - You can add your many filters and decide if they should be an And relationship or Or relationship by choosing All criteria or Any criteria.

Parent topic: Viewing and analyzing energy data

Related tasks

Filtering assets

Logging on to the Asset Health application

Log on to access the IBM® Insights Foundation for Energy user interface.

Before you begin

Contact your local administrator to obtain your user ID and password. Your administrator is responsible for ensuring that you have the security access level that is appropriate to your role in your organization. Your administrator will also supply you with the web address URL for accessing the solution portal.

About this task

Use the following procedure to start a new browser session and access IBM Insights Foundation for Energy.

Procedure

Enter the URL into the address field of the browser.

Note: The fully qualified domain name is required in the URL, for example, https://web_hostname/wps/myportal where web_hostname is the host name of the web server. If you use the IP address instead of the registered fully qualified domain name, some windows do not open correctly. Also, if you do not use the https protocol, the link is redirected to use the https protocol.

On the login page, enter your user ID and password.

Click Log In.

Click the down arrow at the top left hand corner, and click Energy > Asset Health .

Results

Only the pages, features, and data that you have permission to access are displayed. Contact your administrator if you require more access.

Parent topic: Viewing and analyzing energy data

Viewing assets on a map

Assets and their connections within the energy network can be seen on a geographic map. Depending on the zoom level, either individual assets and their health, or an aggregation of assets and the health of the combined assets are displayed.

Procedure

Sign on IBM® Insights Foundation for Energy as a user.

If the task bar is not displayed, display it by clicking the arrow in the circle on the bottom of the page.

In the task bar at the bottom of the page click Map. The map is displayed.

Zoom in or out of the map to see your desired view. IBM Insights Foundation for Energy displays assets and their selected filtered score as individual icons. If there are too many assets to be displayed individual icons, icons are grouped into predefined regions and the overall score for the region is displayed. Optionally you can click on a region and click Zoom-In in the preview card to display the assets of the region.

For further information on the asset or area, click the asset or area. A preview card with additional information and options is displayed.

If too many assets are displayed, change the filter values and click Apply. The assets meeting the filter criteria will be displayed in the map.

Viewing the legend
A legend showing the icons used for the various assets and the colors indicating their status can be displayed.

Parent topic: Viewing and analyzing energy data

Viewing the legend

A legend showing the icons used for the various assets and the colors indicating their status can be displayed.

About this task

Procedure

If the task bar is not displayed, display it by clicking the arrow in the circle on the bottom of the page.

In the task bar click Legend. The legend is displayed.

To control which assets are displayed, select and deselect the icon to the left of the asset label in the legend.

To dismiss the legend, click Legend in the task bar again.

Parent topic: Viewing assets on a map

Related tasks

Filtering assets

Viewing assets as a list

Assets and their network health and risk values can be displayed as a list.

Procedure

Sign on IBM® Insights Foundation for Energy as a user.

If the task bar is not displayed, display it by clicking the arrow in the circle on the bottom of the page.

In the task bar click List. The list is displayed.

IBM Insights Foundation for Energy displays assets and their health status as individual table rows. The table can be sorted by clicking on the desired table header. The list will be redisplayed sorted by that field.

For further information on the asset, click the asset. A preview card with additional information and options is displayed.

If too many assets are displayed, change the filter values and click Apply. The assets meeting the filter criteria will be displayed in the list.

Parent topic: Viewing and analyzing energy data

Filtering assets

The assets displayed on the map or list can be filtered based on selected criteria.

About this task

IBM® Insights Foundation for Energy has the following predefined filter options:

Analysis Year

Geography

Score Type, where Health is the asset health, Failure is probability of failure, Consequence is the consequence of failure.

Status

Asset Class

Additional filter criteria can be specified using the Advanced option.

To reduce the number of displayed assets to those meeting the desired criteria, do the following.

Procedure

If the filter bar is not displayed at the top of the page, click the Filter option in the task bar on the bottom of the page. If the task bar is not displayed, display it by clicking the arrow in the circle on the bottom of the page.

Click the desired filter option and select the desired value.

Click Apply.

Results

The map or list view will display the assets meeting the selected filter criteria.

What to do next

To clear all filter values, click Reset All.

Adding additional filter criteria
In addition to the provided filters, you can specify your own criteria to filter the data displayed in the map and list

Parent topic: Viewing and analyzing energy data

Related concepts

Filter bar

Related tasks

Viewing the legend

Adding additional filter criteria

In addition to the provided filters, you can specify your own criteria to filter the data displayed in the map and list

Procedure

If the filter bar is not displayed at the top of the page, click the Filter option in the task bar. If the task bar is not displayed, display it by clicking the arrow in the circle on the bottom of the page.

Click Advanced. This option can only be selected when one or more asset classes is selected in the Asset Class filter.

Click Add Filter.

From the drop-down fields select the desired criteria.

Repeat the steps if multiple criteria are desired. If multiple criteria are desired, indicate if all conditions must be true ( All criteria) for an asset to be selected or if only one of the conditions must be true ( Any criteria).

Results

The map or list view will display the assets meeting the selected filter criteria.

What to do next

When additional filter criteria have been specified, the Advanced option in the filter bar indicates the number of additional filters that have been defined in parenthesis. To clear the advanced filter criteria, click Advanced in the filter bar and then click Clear All. To clear all filter values, click Reset All in the filter bar.

Parent topic: Filtering assets

Preview cards

When a user clicks on an asset or region, a preview card is displayed with additional information on that asset or region.

If a region containing multiple assets is selected, the preview card will display the average scores for the region, the total number of assets by class within the region, and available actions.

If a single asset is selected, the preview card will display the scores for that asset as well as available actions.

Parent topic: Viewing and analyzing energy data

Showing connectivity

When viewing the preview card for a single asset, you can display how the asset is connected in the network.

About this task

These steps can be used after selecting a single asset on the map or list view.

Procedure

On the preview card for the asset, click Show Connectivity.

Select one of four types of connections to view.

Upstream - Assets located from the selected asset towards the power source.

Downstream - Assets located from the selected asset, away from the power source, and towards other assets and customers.

Find Path - The shortest path between the two selected assets.

Find Nearby - The assets connected to the selected asset within a defined degree of separation.

If you selected Upstream, Downstream, or Find Path, you must select a source asset to be used in the calculation. Click the Source field and then click an asset on the map to be used as the endpoint in the network for the analysis.

If you selected Find Nearby, select the degree value. This value is the number of assets away from the selected asset.

Click Apply in the Show Connectivity panel.

Results

The map will be redrawn highlighting the requested connectivity.

What to do next

To clear the highlighting on the map, close the Show Connectivity panel.

Parent topic: Viewing and analyzing energy data

Viewing asset reports

You can view detailed reports on a single asset or on a group of assets.

Single asset reports
A report with details about a single asset can be displayed.

Multiple asset reports
A summarized report about multiple assets selected by filter criteria can be displayed.

Report data
IBM Insights Foundation for Energy reports provide background information on single and multiple assets.

Viewing analytics dashboards
When viewing a report, additional analytic data is available from IBM Predictive Maintenance and Quality.

Parent topic: Viewing and analyzing energy data

Single asset reports

A report with details about a single asset can be displayed.

Procedure

On the map or list, click the desired asset. The preview card for the asset will be displayed.

Click View Asset Report.

Results

The report for the selected asset is displayed.

What to do next

Report data can also be exported.

Parent topic: Viewing asset reports

Multiple asset reports

A summarized report about multiple assets selected by filter criteria can be displayed.

Procedure

On the map or list, use the filter criteria to specify the assets to be included in the report.

In the task bar at the bottom of the page click Report . If the task bar is not displayed, display it by clicking the arrow in the circle on the bottom of the page.

Results

An aggregate report for the assets is displayed.

What to do next

The report can be further refined by changing the Time, Geography, and Asset Class filters. Report data can also be exported.

Parent topic: Viewing asset reports

Report data

IBM® Insights Foundation for Energy reports provide background information on single and multiple assets.

The tables describe the type of data included in each report.

Table 9.  Data provided in IBM Insights Foundation for Energy single asset reports

Report Tab | Data | Description
Summary | Score | Current Health, Risk, Consequence of Failure score and change since last year.
Summary | Asset Map | Asset location in the map.
Summary | Asset Information | Selected year, asset id and other basic information.
Summary | Score over time | Health, risk, consequence of failure score over time.
Summary | Score breakdown | Calculation detail of health, risk, consequence of failure scores
Health Degradation | Asset Information | Selected year, asset id and other basic information.
Health Degradation | Health score over time | Health score over time.
Health Degradation | Health score breakdown over time | Calculation detail of scores(factor/driver/asset scores) over time.
Historical Data | Asset Information | Selected year, asset id and other basic information.
Historical Data | Advanced Analytics | Link to PMQ report.
Historical Data | Dissolved Gas Analysis | DGA report specific to substation transformer.
Asset Details | Asset Information | Selected year, asset id and other basic information.
Asset Details | Asset properties | All of property values of selected asset.
Treatment | Asset Information | Selected year, asset id and other basic information.
Treatment | Treatment Option | Treatment options over time.
Treatment | Minimal and Maximum Budgets by Year | The minimum and maximum annual treatment cost for the asset.

Table 10.  Data provided in IBM Insights Foundation for Energy multiple asset reports

Report Tab | Data | Description
Summary | Aggregate Score | Current Health, Risk, Consequence of Failure score and change since last year.
Summary | Region Map | Assets region located in the map.
Summary | Asset Information | Selected filter.
Summary | Asset Breakdown | Number of selected assets for each asset class.
Summary | Aggregate Score over time | Aggregate health, risk, consequence of failure score over time.
Summary | Score by asset class | Aggregate health and risk score by asset class.
Summary | Score breakdown | Factor scores by asset class for health, risk, consequence of failure.
Treatment | Asset Information | Selected filter.
Treatment | Asset Breakdown | Number of selected assets for each asset class.
Treatment | Mimimal and Maximum budgets by year | Aggregate minimum and maximum annual treatment cost for all included assets
Treatment | Treatment options | Treatment options for each asset over time

Parent topic: Viewing asset reports

Viewing analytics dashboards

When viewing a report, additional analytic data is available from IBM® Predictive Maintenance and Quality.

Procedure

When viewing a report, click Advanced Analytics.

Results

When viewing a single asset report, the Equipment Dashboard for that single asset is displayed. When viewing a multiple asset report, the site overview dashboard is displayed.

Parent topic: Viewing asset reports

Exporting data

After filtering the data to the desired subset, information on the selected assets can be exported for use in other systems.

Procedure

Sign on IBM® Insights Foundation for Energy as a user.

Using the map or list, filter the assets as desired.

If you want to export a report summarizing all the displayed assets displayed on a map, click Results > Show Report . If you want to export a report with data about a single asset, click the asset on the map or list. On the displayed preview card, click Show Report. The list of assets displayed in the list view can also be exported.

Click Export to export the data into one of the following formats when viewing a list.

CSV

XLSX

When viewing a report, the report can be exported into one of the following formats.

PDF

XLSX

All the tabs in the report will be exported into a .zip file.

Parent topic: Viewing and analyzing energy data

Related concepts

Task bar

Creating input for a rate use case

Using IBM® Insights Foundation for Energy, regional planning engineers determine where investment is required to maintain or improve reliability.

About this task

$33.5 billion is spent annually maintaining distribution grids across the United States. North America has an estimated $4 trillion backlog in electrical infrastructure. Customer minutes without power have increased 15% since 2002 while in the last decade the cost to maintain distribution equipment has gone up 42%.

The delivery of consistent and reliable energy is an important business. By having a better understanding of asset risks, preventative maintenance, and planning, the energy business can be better and more efficient.

Regional planning engineers need to easily manage and optimize regional budgets. They want to be able to generate budget plans quickly and efficiently without having to analyze masses of data. They want the information they need in an accessible, single location so his utility can provide reliable, affordable energy for their customers.

Procedure

The regional planning engineer signs on IBM Insights Foundation for Energy as a user.

He clicks Map. The map is displayed.

He zooms in to determine an area he is interested in analyzing.

Clicking an area of interest, a preview card is displayed giving information on the health and risks of the assets in the area.

Wanting to look at the assets in the area, the regional planning engineer clicks Zoom-in to see more details on the area assets. The map is redisplayed with the individual assets displayed.

The regional planning engineer wants to look at high risk assets so he changes his Score type filter to Risk score and the Score Range to the high risk range and clicks Apply. The map is redisplayed with the assets at the highest risk.

Wanting to see the high risk assets as a list, he clicks List. The high risk assets are displayed as a list.

The regional planning engineer now wants to export the list so he can provide the information to the maintenance plan. To do so he clicks Export and selects the format for the data export, for example, CSV.

Parent topic: Viewing and analyzing energy data

Customizing the solution

You can customize the solution to suit your business requirements.

Use the Administration Console view to register custom user interface components and to customize the user interface to suit your particular operation.

Customizing the user interface
You can use the extension capabilities that are provided by the user interface framework to build application user interfaces that meet your operational requirements.

Customizing the user interface

You can use the extension capabilities that are provided by the user interface framework to build application user interfaces that meet your operational requirements.

IBM® Insights Foundation for Energy provides a number of reusable user interface components including pages, styles, layouts, and widgets. You can also add custom widgets and layouts to your solution by using the user interface extension framework. Use the Administration Console view to register new user interface components, to add new pages, and to configure the style, layout, widgets, access controls, and Representational State Transfer (REST) services for the pages in your solution.

Configuring pages
If you are an administrator, you can add and configure custom pages. Each page has a style and a layout to manage the widgets on the page.

Configuring page hierarchies
If you are an administrator, you can add and remove page hierarchies, and you can configure the contents of page hierarchies. Page hierarchies that contain one or more pages are displayed in the main navigation bar.

Configuring REST services
If you are an administrator, you can register and configure custom Representational State Transfer (REST) services.

Parent topic: Customizing the solution

Configuring pages

If you are an administrator, you can add and configure custom pages. Each page has a style and a layout to manage the widgets on the page.

About this task

Use the Administration Console view to add and configure custom pages. Each page is defined by a set of properties, and each property value that you enter is validated by the solution upon entry. You can view pages that are provided with the solution, but you cannot delete them, and you can edit only the layout properties for these pages.

Procedure

In the Administration Console view, click Page .

Adding a custom page

Click Create.

In the Create a Page window, enter the details for your custom page.

In Title, enter a unique page title.

Optional: In Description, enter a description of the page.

In URI, enter a valid URI, for example /ibm/ife/sample/index/HTML.

Click Save. The new page is listed under the Create button.

For a newly created page, select Groups in the Access control field if you want those groups to access this page. Click Save.

Editing information for a custom page

Edit the page title, description, URI and access control for a custom page.

Click Save to save the changes to the page's configuration.

Deleting a custom page

Click the delete icon beside the custom page, and then in the confirmation window, click Yes.

Note: You cannot delete a custom page if the page is included in the configuration of a page hierarchy.

Parent topic: Customizing the user interface

Related concepts

User roles and access

Configuring page hierarchies

If you are an administrator, you can add and remove page hierarchies, and you can configure the contents of page hierarchies. Page hierarchies that contain one or more pages are displayed in the main navigation bar.

About this task

Use the Administration Console view to add, edit, and remove page hierarchies. Each hierarchy has a label and can contain one or more pages or page hierarchies. Each element of a page hierarchy is defined by a set of properties, and each property value that you enter is validated by the solution upon entry. The position of a page hierarchy in the main navigation bar is determined by the value of the hierarchy's sequence property. You cannot change the properties of system page hierarchies that are provided with the solution, but you can remove them or change their contents.

Procedure

In the Administration Console view, click Page Hierarchy .

Adding a page hierarchy

Add a label to create a new page hierarchy. You can add a top-level page hierarchy or you can add a page hierarchy to an existing page hierarchy. The label for a page hierarchy is displayed in the main navigation bar.

To add a top-level hierarchy, click Create.

To add a hierarchy in an existing page hierarchy, click the add icon beside the page hierarchy.

In the Create an Item window, enter the label details for your custom page hierarchy.

In Type, select Label in the drop-down list to add a page hierarchy.

In Name, enter a name for the page hierarchy. The name is displayed in the main navigation bar.

Optional: In Description, enter a description of the page hierarchy.

In Sequence, enter a number greater than or equal to 0 as the sequence number for the page hierarchy. The sequence number is a relative value that determines the position of a page hierarchy in relation to other page hierarchies in the main navigation bar. For example, if you have two top-level page hierarchies, then the page hierarchy with the lower sequence value is positioned to the left in the main navigation bar.

Click Save.

Note: A page hierarchy is not displayed in the main navigation bar until it contains one or more pages.

Adding a page to a hierarchy

Click the add icon beside the page hierarchy.

In the Create an Item window, enter the details for your custom page.

In Type, select Page from the drop-down list.

In Name, enter the page name to display in the page hierarchy.

Optional: In Description, enter a description of the page.

In Sequence, enter a number greater than or equal to 0. The sequence number is a relative value that determines the position of a page in a hierarchy in relation to other pages or page hierarchies.

In Page definition, select the page to add to the hierarchy from the drop-down list.

Click Save.

Note: You must refresh the browser to display the new page in the main navigation bar.

Editing a page hierarchy

Select a page hierarchy to edit the name, description, and sequence for the page hierarchy.

Select a page in a page hierarchy to edit the name, description, sequence, and page definition for the page.

Click Save.

Deleting a page hierarchy

Click the delete icon beside the page hierarchy, and then in the confirmation window, click Yes.

Deleting a page from a page hierarchy

Click the delete icon beside the page, and then in the confirmation window, click Yes.

Parent topic: Customizing the user interface

Configuring REST services

If you are an administrator, you can register and configure custom Representational State Transfer (REST) services.

About this task

Use the Administration Console view to register and configure custom REST services. Each service is defined by a set of properties, and each property value that you enter is validated by the solution upon entry.

Procedure

In the Administration Console view, click Service .

Registering a custom REST service

Click Create.

In the Create a Service window, enter the details for your custom service.

In Name, enter the name of the service.

In URI, enter the URI for the resource. For example, /ibm/ife/api/ui-service/style.

Note: You can append /* to the base URI for the service to include all the resources that are managed by the service. For example, /ibm/ife/api/ui-service/*.

Optional: In Description, enter a description of the service.

Click Save. The new service is listed under the Create button. Edit the service to assign access rights to the service to user groups in your solution.

Editing a custom REST service

Select the service and edit the values.

Edit the values for the name, URI, and description.

For Access Control , assign access rights to the service for the user role groups in your solution. For each user role group, you can select one or more of the access controls that are labeled Create, Read, Update, and Delete. For more information about user role groups, see the related link.

Click Save to save the changes.

Deleting a custom REST service

Click the delete icon beside the service, and then in the confirmation window, click Yes.

Parent topic: Customizing the user interface

Related concepts

User roles and access

Maintaining the solution

Perform maintenance tasks to keep your solution running smoothly.

Restarting the IBM Insights Foundation for Energy components
After you install a custom application, or if you modify files in the system, for the changes to take effect, you might need to restart the IBM® Insights Foundation for Energy components. Use the platform control tool to stop and start the components that are running on the servers.

Restarting the IBM Insights Foundation for Energy components

After you install a custom application, or if you modify files in the system, for the changes to take effect, you might need to restart the IBM® Insights Foundation for Energy components. Use the platform control tool to stop and start the components that are running on the servers.

Understanding the platform control tool components
The individual platform control tool components are organized into logical groupings called base components. It is recommended that you run a single IFEControl command to stop or start all the components on a server. However, if necessary, you can stop or start the platform control tool components either at the base component level or at the individual component level. It is important that you stop and start the components in the correct order.

Stopping the components
Use the platform control tool to stop the components on the IBM Insights Foundation for Energy servers.

Starting the components
Use the platform control tool to start the components on the IBM Insights Foundation for Energy servers.

Parent topic: Maintaining the solution

Understanding the platform control tool components

The individual platform control tool components are organized into logical groupings called base components. It is recommended that you run a single IFEControl command to stop or start all the components on a server. However, if necessary, you can stop or start the platform control tool components either at the base component level or at the individual component level. It is important that you stop and start the components in the correct order.

The following table lists the base components and their individual components on the three servers:

Table 11. Base components and their individual components on each server

Servers | Base components | Individual components | Started products or services
Database server | db | db2 | DB2® Enterprise Server Edition
jena | Apache Jena
Application server | app | appiib | IBM® Integration Bus
appliberty | WebSphere® Application Server Liberty Profile
appihs | IBM HTTP Server
Analytics server | ana | anacognos | IBM Cognos® Business Intelligence
anaihs | IBM HTTP Server for Cognos
askliberty | WebSphere Application Server Liberty Profile for the Analytics Solution Kit (ASK)
anacndsserv | WebSphere Application Server Network Deployment for SPSS® Collaboration and Deployment Services
anaspss | IBM SPSS Modeler

Parent topic: Restarting the IBM Insights Foundation for Energy components

Stopping the components

Use the platform control tool to stop the components on the IBM® Insights Foundation for Energy servers.

About this task

It is recommended that you run the IFEControl command with the -a option to stop all the components. However, in some cases, it might be necessary to stop only a selection of base components or individual components.

Note: If it is necessary to stop only a selection of base components or individual components, you must stop the components in the correct order as outlined in Table 1 .

Procedure

Log on to the analytics server as the ibmadmin user.

Stopping all the components

To stop all the IBM Insights Foundation for Energy components, enter the following command, where password is the topology password that was created during the installation process:

                           IFEControl -a stop -c all -p
                              password

Stopping base components or individual components

To stop a base component or an individual component, enter the following command:

                           IFEControl -a stop -c
                              component -p
                              password

In the previous command, component is the name of the base component or the individual component, and password is the topology password that was created during the installation process.

Note: You must stop base components or individual components in the correct order that is outlined in Table 1. For example, if you want to stop only the app base component and the anacndsserv component, you must stop the anacndsserv component before you stop the app component.

Table 12. The order in which to stop base components or individual components

Order in which to stop base components | Order in which to stop individual components
1. ana | 1. anaspss
2. anacndsserv
3. askliberty
4. anaihs
5. anacognos
2. app | 6. appihs
7. appliberty
8. appmb
3. db | 9. jena
10. db2

Parent topic: Restarting the IBM Insights Foundation for Energy components

Starting the components

Use the platform control tool to start the components on the IBM® Insights Foundation for Energy servers.

About this task

It is recommended that you run the IFEControl command with the -a option to start all the components. However, in some cases, it might be necessary to start only a selection of base components or individual components.

Note: If it is necessary to start only a selection of base components or individual components, you must start the components in the correct order as outlined in Table 1 .

Procedure

Log on to the analytics server as the ibmadmin user.

Starting all the components

To start all the IBM Insights Foundation for Energy components, enter the following command, where password is the topology password that was created during the installation process:

                           IFEControl -a start -c all -p
                              password

Starting base components or individual components

To start a base component or an individual component, enter the following command:

                           IFEControl -a start -c
                              component -p
                              password

In the previous command, component is the name of the base component or the individual component, and password is the topology password that was created during the installation process.

Note: You must start base components or individual components in the correct order that is outlined in Table 1. For example, if you want to start only the anaspss and the anacognos components, you must start the anacognos component before you start the anaspss component.

Table 13. The order in which to start base components or individual component

Order in which to start base components | Order in which to start individual components
1. db | 1. db2
2. jena
2. app | 3. appmb
4. appliberty
5. appihs
3. ana | 6. anacognos
7. anaihs
8. askliberty
9. anacndsserv
10. anaspss

Parent topic: Restarting the IBM Insights Foundation for Energy components

Troubleshooting and support

To isolate and resolve problems with your IBM® software, you can use the troubleshooting and support information, which contains instructions for using the problem-determination resources that are provided with your IBM products.

Techniques for troubleshooting problems
Troubleshooting is a systematic approach to solving a problem. The goal of troubleshooting is to determine why something does not work as expected and how to resolve the problem.

Known problems and solutions for IBM Insights Foundation for Energy
Some common problems with IBM Insights Foundation for Energy are documented, along with their solutions or workarounds. If you have a problem with IBM Insights Foundation for Energy, review the problem-solution topics to determine if a solution is available to the problem that you are experiencing.

IBM Insights Foundation for Energy messages
Each message topic helps you to identify the cause of a particular error condition and recommends actions to take to resolve the error.

Techniques for troubleshooting problems

Troubleshooting is a systematic approach to solving a problem. The goal of troubleshooting is to determine why something does not work as expected and how to resolve the problem.

The first step in the troubleshooting process is to describe the problem completely. Problem descriptions help you and the IBM technical-support representative know where to start to find the cause of the problem. This step includes asking yourself basic questions:

What are the symptoms of the problem?

Where does the problem occur?

When does the problem occur?

Under which conditions does the problem occur?

Can the problem be reproduced?

The answers to these questions typically lead to a good description of the problem, which can then lead you to a problem resolution.

What are the symptoms of the problem?

When starting to describe a problem, the most obvious question is What is the problem? This question might seem straightforward; however, you can break it down into several more-focused questions that create a more descriptive picture of the problem. These questions can include:

Who, or what, is reporting the problem?

What are the error codes and messages?

How does the system fail? For example, is it a loop, hang, crash, performance degradation, or incorrect result?

Where does the problem occur?

Determining where the problem originates is not always easy, but it is one of the most important steps in resolving a problem. Many layers of technology can exist between the reporting and failing components. Networks, disks, and drivers are only a few of the components to consider when you are investigating problems.

The following questions help you to focus on where the problem occurs to isolate the problem layer:

Is the problem specific to one platform or operating system, or is it common across multiple platforms or operating systems?

Is the current environment and configuration supported?

If one layer reports the problem, the problem does not necessarily originate in that layer. Part of identifying where a problem originates is understanding the environment in which it exists. Take some time to completely describe the problem environment, including the operating system and version, all corresponding software and versions, and hardware information. Confirm that you are running within an environment that is a supported configuration; many problems can be traced back to incompatible levels of software that are not intended to run together or have not been fully tested together.

When does the problem occur?

Develop a detailed timeline of events leading up to a failure, especially for those cases that are one-time occurrences. You can most easily develop a timeline by working backward: Start at the time an error was reported (as precisely as possible, even down to the millisecond), and work backward through the available logs and information. Typically, you need to look only as far as the first suspicious event that you find in a diagnostic log.

To develop a detailed timeline of events, answer these questions:

Does the problem happen only at a certain time of day or night?

How often does the problem happen?

What sequence of events leads up to the time that the problem is reported?

Does the problem happen after an environment change, such as upgrading or installing software or hardware?

Responding to these types of questions can give you a frame of reference in which to investigate the problem.

Under which conditions does the problem occur?

Knowing which systems and applications are running at the time that a problem occurs is an important part of troubleshooting. These questions about your environment can help you to identify the root cause of the problem:

Does the problem always occur when the same task is being performed?

Does a certain sequence of events need to occur for the problem to surface?

Do any other applications fail at the same time?

Answering these types of questions can help you explain the environment in which the problem occurs and correlate any dependencies. Remember that just because multiple problems might have occurred around the same time, the problems are not necessarily related.

Can the problem be reproduced?

From a troubleshooting standpoint, the ideal problem is one that can be reproduced. Typically, when a problem can be reproduced you have a larger set of tools or procedures at your disposal to help you investigate. Consequently, problems that you can reproduce are often easier to debug and solve. However, problems that you can reproduce can have a disadvantage: If the problem is of significant business impact, you do not want it to recur. If possible, re-create the problem in a test or development environment, which typically offers you more flexibility and control during your investigation.

Can the problem be re-created on a test system?

Are multiple users or applications encountering the same type of problem?

Can the problem be re-created by running a single command, a set of commands, or a particular application?

Parent topic: Troubleshooting and support

Known problems and solutions for IBM Insights Foundation for Energy

Some common problems with IBM® Insights Foundation for Energy are documented, along with their solutions or workarounds. If you have a problem with IBM Insights Foundation for Energy, review the problem-solution topics to determine if a solution is available to the problem that you are experiencing.

Browser back button does not return to the perceived previous page
When you click the browser back button, the browser might return to a page other than where you think it should.

Updated service passwords for the data loader are not automatically encrypted
If you update the service password in the data loader configuration file, the updated password is not automatically encrypted. You must run the encryption utility to store an encrypted version of the password in the configuration file.

Dissolved Gas Analysis graphic cannot be exported in the .xlsx file
A Dissolved Gas Analysis graphic in the single asset report for Substation Transformer cannot be exported in the .xlsx file.

Drilled-down bar chart does not clear
When you drill-down on a bar chart, it does not clear when you select another asset on a map or list.

A bar chart does not clear when user selects another asset
Bar chart does not clear after user selects another asset on a map or list.

Parent topic: Troubleshooting and support

Browser back button does not return to the perceived previous page

When you click the browser back button, the browser might return to a page other than where you think it should.

Symptoms

Clicking the browser back button results in a page other than what is expected being displayed.

Resolving the problem

Use product navigation to navigate through the product. The browser forward and back buttons might not navigate to the desired product pages.

Parent topic: Known problems and solutions for IBM Insights Foundation for Energy

Updated service passwords for the data loader are not automatically encrypted

If you update the service password in the data loader configuration file, the updated password is not automatically encrypted. You must run the encryption utility to store an encrypted version of the password in the configuration file.

Symptoms

If you change the service password in the data loader configuration file, the password is stored in plain text. Automatic encryption is not available for passwords that are stored in the data loader configuration file.

Resolving the problem

To update the service password for the data loader, you must run the encryption utility to store an encrypted version of the password in the data loader configuration file. Enter a new value in plain text for the servicePassword property in the /opt/IBM/energy/data/cityname/config.properites file. Then, run the encrypt.sh utility to encrypt the updated service password.

Log on to the application server as a user who has edit access to the config.properites file, for example, the root user.

Edit the /opt/IBM/energy/data/cityname/config.properites file, and enter a new value in plain text for the servicePassword property.

To encrypt the new service password in the data loader configuration file, go to the /opt/IBM/energy/lib directory and enter the following command:

                              ./encrypt.sh /opt/IBM/energy/data/cityname/config.properties servicePassword
                                 encryptType

Where encryptType is the type of encryption to use. Advanced Encryption Standard (AES) and Base64 are the supported encryption types, so the value for encryptType is either aes or base64.

For example, to encrypt the service password using AES, enter the following command:

./encrypt.sh /opt/IBM/energy/data/cityname/config.properties servicePassword aes

Note: AES is the recommended encryption to use to encrypt the service password.

Parent topic: Known problems and solutions for IBM Insights Foundation for Energy

Dissolved Gas Analysis graphic cannot be exported in the .xlsx file

A Dissolved Gas Analysis graphic in the single asset report for Substation Transformer cannot be exported in the .xlsx file.

Symptoms

When you want to export the single asset report for Substation Transformer into .xlsx file, the Dissolved Gas Analysis graphic does not show in the exported .xlsx file.

Resolving the problem

Export the single asset report for Substation Transformer into a .pdf file.

Parent topic: Known problems and solutions for IBM Insights Foundation for Energy

Drilled-down bar chart does not clear

When you drill-down on a bar chart, it does not clear when you select another asset on a map or list.

Symptoms

When you are on the DNO sample application page and select an asset on a map or list, then select a measurement in the Asset Details list and drill down the bar chart, when you select another asset on map or list the drilled-down bar chart does not clear or refresh for the new measurement.

Resolving the problem

Drill up the bar chart to the top level. The normal bar chart can be refreshed correctly.

Parent topic: Known problems and solutions for IBM Insights Foundation for Energy

A bar chart does not clear when user selects another asset

Bar chart does not clear after user selects another asset on a map or list.

Symptoms

When you are on the DNO sample application page, and select an asset on map or list, and then a measurement in the Asset Details list, a bar chart will show for this measurement. If you then select another asset on map or list, the bar chart will not be cleared.

Resolving the problem

Select a measurement under the new selected asset, the bar chart will be updated.

Parent topic: Known problems and solutions for IBM Insights Foundation for Energy

IBM Insights Foundation for Energy messages

Each message topic helps you to identify the cause of a particular error condition and recommends actions to take to resolve the error.

To help you understand the errors that you might encounter, each message topic is divided into three sections: the message that is displayed in the product or its logs, an explanation, and an action.

The message

Contains two identifiers, which are the error identification and associated text. The error identification is the message ID. It is a unique number that identifies a message. A final character of E indicates that the message resulted from an error, W indicates a warning message, and I indicates an information message.

The explanation

Contains an additional explanation of the message.

The user response

Suggests the corrective action for resolving the error.

Note: The topics in this section are specific to IBM® Insights Foundation for Energy. For all other messages, see the appropriate product documentation.

CIYIF0001E
Service Error - An internal error occurred.

CIYIF0002E
System Error - An internal error occurred.

CIYIF0011E
The style cannot be deleted because it is used by one or more pages.

CIYIF0012E
The database operation failed.

CIYIF0013E
The extension cannot be deleted because it is used by one or more layouts.

CIYIF0014E
The extension cannot be deleted because it is used by one or more widgets.

CIYIF0015E
The layout cannot be deleted because it is used by one or more pages.

CIYIF0016E
You must enter a valid value for the module name. The Module name field cannot be empty.

CIYIF0017E
You must enter a valid value for the package name. The Package name field cannot be empty.

CIYIF0018E
You must enter a valid value for the package location. The Package location field cannot be empty.

CIYIF0019E
The widget cannot be deleted because it is used by one or more pages.

CIYIF0020E
The page cannot be deleted because it is used by one or more page hierarchies.

CIYIF0021E
The call to the access control REST service failed because the resource ID input parameter was not provided.

CIYIF0022E
The call to the access control REST service failed because the resource type input parameter was not provided.

Parent topic: Troubleshooting and support

CIYIF 0001 E

An error occurred in services provided by the product.

Contact IBM® Support to resolve the issue.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0002 E

An internal error occurred with the product.

Contact your administrator to resolve the issue. The administrator needs to check or possibly restart the system.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0011 E

The style cannot be deleted because one or more pages are configured to use this style.

To delete the style, you must first remove the style from any page configuration.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0012 E

The database operation failed.

See the WebSphere® Application Server Liberty Profile log files for more information about why the database operation failed. The log files are named console.log and messages.log, and they are in the /opt/IBM/WebSphere/Liberty/usr/servers/member01/logs directory on the application server.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0013 E

The extension cannot be deleted because one or more layouts are configured to use this extension.

To delete the extension, you must first remove the extension from any layout configuration.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0014 E

The extension cannot be deleted because one or more widgets are configured to use this extension.

To delete the extension, you must first remove the extension from any widget configuration.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0015 E

The layout cannot be deleted because one or more pages are configured to use this layout.

To delete the layout, you must first remove the layout from any page configuration.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0016 E

There must be a valid value for the module name. The Module name field cannot be empty.

Enter a valid value in the Module name field.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0017 E

There must be a valid value for the path name. The Package name field cannot be empty.

Enter a valid value in the Package name field.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0018 E

There must be a valid value for the package location. The Package location field cannot be empty.

Enter a valid value in the Package location field.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0019 E

The widget cannot be deleted because one or more pages are configured to use this widget.

To delete the widget, you must first remove the widget from any page configuration.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0020 E

The page cannot be deleted because one or more page hierarchies are configured to use the page.

To delete the page, you must first remove the page from any page hierarchy configuration.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0021 E

You must specify a resource ID as an input parameter for this access control REST service method.

Specify a resource ID as a parameter to the access control REST service method.

Parent topic: IBM Insights Foundation for Energy messages

CIYIF 0022 E

You must specify a resource type as an input parameter for this access control REST service method.

Specify a resource type as a parameter to the access control REST service method.

Parent topic: IBM Insights Foundation for Energy messages

Reference

These topics contain additional reference information to help you.

The Common Information Model
The Common Information Model (CIM) Data Model needs be populated with data through Data Loading.

License usage metrics
IBM® License Metric Tool helps Passport Advantage® clients determine their full and sub-capacity PVU licensing requirements.

Supported browsers
The IBM Insights Foundation for Energy user interface is supported in several browsers.

Accessibility
Accessibility features help users with physical disabilities, such as restricted mobility or limited vision, to use software products successfully.

The Common Information Model

The Common Information Model (CIM) Data Model needs be populated with data through Data Loading.

The CIM is a standard adopted by the International Electromechanical Commission (IEC) for the reporting and exchange of information about electrical supply networks. Three types of data need be loaded into CIM Data Model:

Ontology - used to define the supported assets classes and properties of the asset classes.

Static data - used to define nameplate data, geographical location, network connectivity, measurement definitions and the relationships between assets.

Dynamic data - is the data that changes over time.

Ontology
Ontology is used to define the supported assets classes and properties on asset classes. IBM® Insights Foundation for Energy integrates data from different data sources that is consolidated into common asset class and properties definitions.

Logical Resource
The logical resource is abstract of components of an electrical network.

Asset identity and Attributes
The asset identity and attributes describe physical asset of a logical resource at a point in time.

Geometry
The geospatial information specifies the location of a logical resource in a network.

Relationships and connectivity
The relationships that include network connectivity, the supporting structure, and flow roles are described here.

Parent topic: Reference

Ontology

Ontology is used to define the supported assets classes and properties on asset classes. IBM® Insights Foundation for Energy integrates data from different data sources that is consolidated into common asset class and properties definitions.

The mapping between external object id and internal object id is also maintained by IBM Insights Foundation for Energy.

Ontology can also be used to map between semantics from all the data sources and a common semantics. Data sources can have their own semantics; they often do not use the same vocabulary of terms and data concepts. For example, a PowerTransfomer can be called differently in different data sources. IBM Insights Foundation for Energy maps semantics from all the data sources into the IEC CIM semantics.

There is three types of table in ontology:

Object ID

ResourceType

PropertyType

ObjectID

All objects are identified by a database generated object identifier, and a unique URI that is in two parts: namespace and local name. For example: for the URI http://cityName#transformer1, the namespace is http://cityName# and its local name is transformer1.

oid

BIGINT

Internal object ids which uniquely identifies an object.

It is generated by the database.

namespace

VARCHAR(256)

Namespace part of the URI.

localName

VARCHAR(256)

Local name part of the URI.

ResourceType

The ResourceType table is use to store the metadata of the CIM PowerSystemResource. For example: The CIM asset classes PowerTransformer, and Switch, are subclasses of PowerSystemResource. The user can register these standard or custom defined power system resources to the ResourceType table.

id

BIGINT

The primary key id of the resource type.

code

VARCHAR(128)

A unique string based code of the resource type.

name

VARCHAR(128)

Display name of the resource type.

description

VARCHAR(512)

Description of the resource type.

isAsset

CHAR(1)

Indicates whether resources of this type can be linked to physical asset.

1 = yes, 0 = no.

If isAsset = 1, then the table field holds the name of table used to store the properties of the asset.

isResource

CHAR(1)

Indicates whether this resource type is a power system resource or a container.

0 = is a container (for example, a geospatial region),

1 = is a power system resource. For example, a transformer.

cimID

VARCHAR(128)

Class name of this resource type as in the IEC CIM when the resource type is defined in IEC CIM. For example, PowerTransformer.

table

VARCHAR(256)

Used when isAsset = 1. The fully qualified table name used to store the properties of the asset.

serviceURL

VARCHAR(256)

The relative service URL which expose instance data of this resource type.

PropertyType

The PropertyType is used to store the properties metadata of each resource type when ResourceType.isAsset = 1.

id

BIGINT

The primary key, id of the property type.

resourceType

BIGINT

The foreign Key, the id of resource type.

code

VARCHAR(128)

A unique string based code of the property type.

name

VARCHAR(128)

Display name of property type.

description

VARCHAR(512)

Description of property type.

cimID

VARCHAR(128)

The property name of this property type in the IEC CIM when defined in IEC CIM. For example, Asset.lifecycle.installationDate.

column

VARCHAR(128)

Column name in target table which been used to store this property value.

dataType

VARCHAR(32)

The data type of the property.

length

INTEGER

The length of the property.

scale

INTEGER

The scale of the property.

isEnum

CHAR(1)

Indicates if the property value is an enumeration.

isReference

CHAR(1)

Not used.

isMinimal

CHAR(1)

Indicates if the property is a minimal property.

Minimal property is an important property to filter and sort data.

tag

VARCHAR(128)

Tags on property type.

group

VARCHAR(128)

The group name of the property. Used to group related properties.

unit

VARCHAR(128)

The unit of the property value.

Parent topic: The Common Information Model

Logical Resource

The logical resource is abstract of components of an electrical network.

When a transformer is referred to in an electrical network, we are interested in its role in the network, how it connected and physical device that is acts upon it. In this example the transformer is the logical resource within the electrical network.

The types of Logical resource varies; the type is defined in the ResourceType table. Some types of logical resources are associated with properties that are stored in a separate child table. Ofr example, a logical resource can also have a location that is stored in the Location table.

The relationship between logical resources are described by a container and the objects it comprises. The container is used to group together components of an asset, or to group assets of a service region. For example, an overhead cable is composed of line segments, the overhead cable is the container and the line segment are its objects. The aggregation of the relationship can be hierarchical, that is, a container can contain other containers.

Attributes for Logical Resources

oid

BIGINT

Primary key, the object id of the resource type.

The Object ID is generated in the ObjectID table.

lastUpdateTime

TIMESTAMP

Generated last update time.

resourceType

BIGINT

Foreign key, the type of this logical resource with reference to the ResourceType table.

mRID

VARCHAR(256)

Master resource ID. The string based identifier of the logical resource.

name

VARCHAR(128)

The name of logical resource.

description

VARCHAR(512)

The description of the logical resource.

isContainer

CHAR(1)

Indicates if the logical resources is a container of other components.

location

BIGINT

Foreign key, the location of the logical resource with reference to the Location table.

container

BIGINT

Foreign key, the container or parent of this logical resource, with reference to self.

Parent topic: The Common Information Model

Asset identity and Attributes

The asset identity and attributes describe physical asset of a logical resource at a point in time.

Each logical resource can be associated with more than one physical asset. Each asset described indicates which physical asset is acting as this logical role over different time periods. For example the logical resource transformer1 is associated with two physical transformers, one was active from the year 2000 to 2010 and the other has been active from the year 2010 to the present day.

The separation of the logical resource from the physical asset has several benefits.

You are able to track the replacement history of a logical resource.

The role and responsibility is made clear: the role of the logical resource is to describe the measurement, the connections and location of an asset, and the relationship between assets. The physical asset focuses on the identity of the asset and the static attributes of the nameplate data.

For each resource type registered, when isAsset = 1 in the ResourceType table, there is a corresponding asset identity table used to store the attributes of the asset. Some attributes are also registered in the PropertyType table.

IBM® Insights Foundation for Energy provides five asset identity and attribute tables:

Pole: attributes for pole.

SubstationTransformer: attributes for substation transformers.

DistributionTransformer: attributes for distribution transformers.

OverheadCable: attributes for overhead cables.

UnderGroundCable: attributes for underground cables.

Common attributes for all assets

Note: Where an attribute is mandatory, it will be used in the analysis of asset health. You must provide values for these fields.

oid

BIGINT

Mandatory, the Primary Key, Foreign Key, object id of the logical resource.

serialNumber

VARCHAR(128)

Mandatory, the serial number of the physical asset.

isActive

CHAR(1)

Mandatory, indicates if the assets is currently active, 1 = active, 0 = inactive.

installationDate

DATE

Mandatory, the date when the asset is installed.

removalDate

DATE

Date when asset is removed.

lastUpdateTime

TIMESTAMP

Mandatory, Generated last update time.

Attributes for Pole assets

Note: Where an attribute is mandatory, it will be used in the analysis of asset health. You must provide values for these fields.

length

DECIMAL(8 , 4)

Mandatory, the length of the pole includes any section of the pole that is underground after installation. The unit is defined in the PropertyType table.

lengthClass

VARCHAR(32)

classification

VARCHAR(32)

Pole class: 1, 2, 3, 4, 5, 6, 7, H1, H2, Other, Unknown.

materialKind

VARCHAR(32)

The material the pole is made from. For example, wood, metal, cement.

speciesType

VARCHAR(32)

Mandatory, Pole species. Aluminum, Aluminum Davit, Concrete, Fiberglass, Galvanized Davit, Galvanized, Steel Davit Primed, Steel Davit, Steel Standard Primed, Steel, Truncated, Wood-Treated, Wood-Hard, Wood-Salt Treated, Wood-Soft, Wood, Other, Unknown.

reclaimedStatus

CHAR(1)

Mandatory, Indicates if the pole is made from reclaimed material.

treatmentKind

VARCHAR(32)

The treatment type for the pole.

preservativeKind

VARCHAR(32)

Mandatory, The type of preservative used for the pole.

originalGroundlineCircumference

DECIMAL(8 , 4)

manufacturer

VARCHAR(128)

The manufacturer of the pole.

ownerType

VARCHAR(32)

Type of pole owner, for example, company.

inspectionType

VARCHAR(32)

inspectionTreatmentType

VARCHAR(32)

inspectionStatus

VARCHAR(32)

Mandatory, Status of last inspection.

Attributes for Substation Transformer assets

Note: Where an attribute is mandatory, it will be used in the analysis of asset health. You must provide values for these fields.

operatingVoltage

INTEGER

Mandatory, the operating voltage.

summerEmergencyRating

INTEGER

Mandatory, the Summer Emergency Rating.

summerNormalRating

INTEGER

Mandatory, the Summer Normal Rating.

winterEmergencyRating

INTEGER

Mandatory, the Winter Emergency Rating.

winterNormalRating

INTEGER

Mandatory, the Winter Normal Rating.

stage1Rating

INTEGER

Mandatory, the Stage 1 Rating.

stage2Rating

INTEGER

Mandatory, the Stage 2 Rating.

stage3Rating

INTEGER

Mandatory, the Stage 3 Rating.

manufacturer

VARCHAR(128)

Mandatory, the manufacturer of the transformer.

subTypeCode

VARCHAR(32)

The substation type code.

feeder

VARCHAR(32)

Feeder for the transformer.

alterFeeder

VARCHAR(32)

Alter feeder of the transformer.

feederInfo

INTEGER

The feed information.

workorderi

VARCHAR(32)

electricTraceWeight

INTEGER

Electric trace weight.

GLNX

INTEGER

GLNY

INTEGER

protectiveGLNX

INTEGER

Protective GLNX

protectiveGLNY

INTEGER

Protective GLNY

owner

VARCHAR(32)

Mandatory, the owner of the transformer

groundreac

INTEGER

groundresi

INTEGER

highsidegr

INTEGER

highside_1

INTEGER

highsidepr

VARCHAR(32)

labeltext

VARCHAR(32)

Label text

phaseDesignation

INTEGER

The phase designation

nominalVoltage

INTEGER

Nominal Voltage

ratedkva

FLOAT(53)

Mandatory, rated KVA

highsideco

VARCHAR(32)

lowsidecon

VARCHAR(32)

lowsidegro

FLOAT(53)

lowsideg_1

FLOAT(53)

lowsidepro

VARCHAR(32)

lowsidevol

INTEGER

filledweig

FLOAT(53)

Filled weight

emptyweigh

FLOAT(53)

Empty weight

heightbush

FLOAT(53)

heightnobu

FLOAT(53)

ratedkva65

INTEGER

ratedterti

INTEGER

switchtype

VARCHAR(32)

tertiaryco

VARCHAR(32)

tertiaryvo

INTEGER

sectionalizer

VARCHAR(32)

Sectionalizer

cabinetcon

VARCHAR(32)

xfnumber

VARCHAR(32)

cableid

VARCHAR(32)

The identification number of the cable.

circuit

VARCHAR(32)

Circuit description

workLocation

VARCHAR(32)

Work location

phaseOrientation

VARCHAR(32)

The phase orientation

facilityId

VARCHAR(32)

constructi

INTEGER

isOutageDevice

CHAR(1)

Mandatory, indicates if the transformer is an outage device.

numberOfCustomers

INTEGER

Mandatory, the number of downstream customers supported by transformer.

Attributes for overhead cable assets

Note: Where an attribute is mandatory, it will be used in the analysis of asset health. You must provide values for these fields.

length

FLOAT(53)

The length of the cable. The units are defined in the PropertyType table.

feeder

VARCHAR(32)

The feeder for the cable.

operatingVoltage

INTEGER

The operating voltage

owner

VARCHAR(32)

The owner of cable.

labeltext

VARCHAR(32)

Label text

phaseDesignation

INTEGER

Phase Designation.

phaseOrientation

VARCHAR(32)

Phase Orientation

cableRatingASet1

INTEGER

Cable Rating A Set 1

cableRatingBSet1

INTEGER

Cable Rating B Set 1

cableRatingASet2

INTEGER

Cable Rating A Set 2

cableRatingBSet2

INTEGER

Cable Rating B Set 2

cableRatingASet3

INTEGER

Cable Rating A Set 3

cableRatingBSet3

INTEGER

Cable Rating B Set 3

cableRatingASet4

INTEGER

Cable Rating A Set 4

cableRatingBSet4

INTEGER

Cable Rating B Set 4

Attributes for underground cable assets

Note: Where an attribute is mandatory, it will be used in the analysis of asset health. You must provide values for these fields.

length

FLOAT(53)

The length of the underground cable. The unit is defined in the PropertyType table

feeder

VARCHAR(32)

Feeder of cable

subTypeCode

VARCHAR(32)

Sub type code

operatingVoltage

INTEGER

Operating Voltage

owner

VARCHAR(32)

The owner of cable.

labeltext

VARCHAR(32)

Label text

phaseDesignation

INTEGER

Phase Designation.

phaseOrientation

VARCHAR(32)

Phase Orientation

cableId

VARCHAR(32)

Cable ID

circuit

VARCHAR(32)

Circuit

cableNumber

VARCHAR(32)

Cable Number

cableRatingASet1

INTEGER

Cable Rating A Set 1

cableRatingBSet1

INTEGER

Cable Rating B Set 1

cableRatingASet2

INTEGER

Cable Rating A Set 2

cableRatingBSet2

INTEGER

Cable Rating B Set 2

cableRatingASet3

INTEGER

Cable Rating A Set 3

cableRatingBSet3

INTEGER

Cable Rating B Set 3

cableRatingASet4

INTEGER

Cable Rating A Set 4

cableRatingBSet4

INTEGER

Cable Rating B Set 4

Parent topic: The Common Information Model

Geometry

The geospatial information specifies the location of a logical resource in a network.

Geospatial location is a key attribute in a physical infrastructure that enables geospatial analytics and visualization of the entities on a map.

Location attributes

The location attributes are typically stored in a GIS system, an example being the Environmental Systems Research Institute (ESRI) ArcGIS.

oid

BIGINT

Primary key, object id of the location.

Object id is generated in ObjectID table.

lastUpdateTime

TIMESTAMP

Generated last update time.

mRID

VARCHAR(256)

Master resource id. Which is a string based identifier.

isActive

CHAR(1)

Indicate if the location is active or not.

direction

VARCHAR(32)

The direction that allows field crews to find quickly a given asset. For example, a streetlight may be located at the 'NW' (northwest) corner of the customer's site.

mainAddress

VARCHAR(256)

Main address of the location.

phone1

VARCHAR(32)

Phone number.

phone2

VARCHAR(32)

Phone number.

secondaryAddress

VARCHAR(256)

Secondary address of the location. For example, PO Box address may have different ZIP code than that in the 'mainAddress'.

geometry

GEOMETRY

The geospatial location in GIS.

locationDescription

VARCHAR(256)

Description of the location.

Parent topic: The Common Information Model

Relationships and connectivity

The relationships that include network connectivity, the supporting structure, and flow roles are described here.

The IEC CIM is the template for model network connectivity between logical resources. In IEC CIM, ConnectiivtyNode and Terminal are used to model connectivity between conducting equipment.

ConnectivityNode: points where terminals of conducting equipment are connected together with zero impedance.

Terminal: An electrical connection point to a piece of electrical equipment. Terminals are connected at physical connection points called "connectivity nodes".

Using this model, the terminals are connected to a connectivity node, as in the following diagram.

Figure 6. Terminals connected to a connectivity node

The same model is used to describe the connectivity between logical resources.

Attributes for the Connectivity Node

oid

BIGINT

Primary key, object id of the connectivity node.

Object id is generated in ObjectID table.

lastUpdateTime

TIMESTAMP

Generated last update time.

mRID

VARCHAR(256)

The master resource ID. This is a string based identifier for the connectivity node.

isActive

CHAR(1)

Indicates if current connectivity node is active.

name

VARCHAR(128)

The name of the connectivity node.

description

VARCHAR(512)

The description of the connectivity node.

container

BIGINT

A foreign key, the parent of this connectivity node with reference to the resource table.

Attributes for the terminals

oid

BIGINT

Primary key, object id of the terminal.

Object id is generated in ObjectID table.

lastUpdateTime

TIMESTAMP

Generated last update time.

mRID

VARCHAR(256)

The master resource ID. This is a string based identifier for the connectivity node.

isActive

CHAR(1)

Indicates if the current terminal is active.

name

VARCHAR(128)

The name of the terminal.

description

VARCHAR(512)

The description of terminal.

sequenceNumber

INTEGER

The sequence number of the terminal. If a resource has multiple terminals, the sequence number is used to put the terminals in order.

connected

CHAR(1)

Indicates if the terminal is connected.

phases

VARCHAR(32)

The phases of the terminal.

resource

BIGINT

A foreign Key, the resource end of the terminal, with reference to the Resource attributes.

connectivityNode

BIGINT

A foreign key, the connectivity node end of the terminal, with reference to the ConnectivityNode attributes.

The attributes for support association

For supporting structural relationships, the supporting structure relationship does not indicate any electric transmission between assets. For example, if several poles are used support the an overhead cable, then there is a supporting structure relationship between the poles and the overhead cable, however, this relationship cannot be modeled using the connectivity relationship as no electric current flows from the cable to the poles.

oid

BIGINT

The primary key, the object id of the support association.

The object id is generated in the ObjectID attributes.

lastUpdateTime

TIMESTAMP

Generated last update time.

mRID

VARCHAR(256)

The master resource id. This is a string based identifier for the support association.

isActive

CHAR(1)

Indicates if current support association is active.

supporter

BIGINT

A foreign key, the oid for the supporter resource, with reference to the Resource attributes.

supported

BIGINT

A foreign key, the oid of the supported resource, with reference to the resource attributes. For example if the supporter is a pole then the oid is for the pole, the supported is the oid of the cable.

The attributes for flow role

Flow role is used to describe the role of a logical resource in a network. For example, we can assign the role power source to one asset, and assign the role power sink of to another asset, we can then use these roles to calculate power flow.

oid

BIGINT

Primary key, foreign key, object id of logical resource.

lastUpdateTime

TIMESTAMP

Generated last update time.

isActive

CHAR(1)

Indicates if the current flow role is active.

role

INTEGER

The role of the logical resource in the network.

Parent topic: The Common Information Model

License usage metrics

IBM® License Metric Tool helps Passport Advantage® clients determine their full and sub-capacity PVU licensing requirements.

Learn more: IBM License Metric Tool .

<CONSUMING_PRODUCT_NAME> writes usage information to Software License Metric Tag (SLMTag) files. These files have the extension .slmtag and are read periodically by the IBM License Metric Tool (ILMT) after it has been configured to scan for these files. You can generate reports that summarize usage.

For more information about using IBM License Management Tool, see the IBM License Management Tool 9.0 Knowledge Center .

SLMTag logging

When IBM Insights Foundation for Energy is running, license management information is logged every day to the /opt/IBM/energy/properties/slmtags directory on the application server. The logged .slmtag files contain usage information for the three types of usage:

Standard user

The usage information that is logged is the number of licensed standard users in the system.

Limited user

The usage information that is logged is the number of licensed limited users in the system.

Asset analytics

The usage information that is logged is the number of managed assets in the system. This value is retrieved from the CIM database. For the IBM Insights Foundation for Energy 1.5 release, this value is always 0.

Note: The numbers of licensed standard users and limited users in the system is retrieved from the basic user registry that is deployed with IBM Insights Foundation for Energy. To ensure the accuracy of these numbers, the configuration file that maps user groups to license types must be kept up to date. For more information about mapping groups to license types, see the related link.

The following content is an example of usage information from an .slmtag file:

                        <SchemaVersion>2.1.1</SchemaVersion>
                           <SoftwareIdentity>
                           	<PersistentId>e137414b35d140dca5fd631df1098e0d</PersistentId>
                           	<Name>IBM Insights Foundation for Energy</Name>
                           	<InstanceId>/opt/IBM/energy</InstanceId>
                           </SoftwareIdentity>
                           <Metric logTime="2015-08-05T16:44:36+08:00">
                           	<Type>AUTHORIZED_USER</Type>
                           	<SubType>Standard User</SubType>
                           	<Value>5</Value>
                           	<Period>
                           		<StartTime>2015-08-05T16:44:36+08:00</StartTime>
                           		<EndTime>2015-08-05T16:44:36+08:00</EndTime>
                           	</Period>
                           </Metric>
                           <Metric logTime="2015-08-05T16:44:36+08:00">
                           	<Type>AUTHORIZED_USER</Type>
                           	<SubType>Limited User</SubType>
                           	<Value>5</Value>
                           	<Period>
                           		<StartTime>2015-08-05T16:44:36+08:00</StartTime>
                           		<EndTime>2015-08-05T16:44:36+08:00</EndTime>
                           	</Period>
                           </Metric>
                           <Metric logTime="2015-08-05T16:44:36+08:00">
                           	<Type>ASSET</Type>
                           	<SubType></SubType>
                           	<Value>0</Value>
                           	<Period>
                           		<StartTime>2015-08-05T16:44:36+08:00</StartTime>
                           		<EndTime>2015-08-05T16:44:36+08:00</EndTime>
                           	</Period>
                           </Metric>

Parent topic: Reference

Related tasks

Mapping groups to license types

Supported browsers

The IBM® Insights Foundation for Energy user interface is supported in several browsers.

Browsers

Google Chrome 43 or later

Microsoft Internet Explorer 11

Mozilla Firefox 31 ESR

Safari 8 for Mac OS

Known issues on Chrome

The Logical Map on DNO sample application page cannot be zoomed in or zoomed out.

Known issues on Internet Explorer

The Logical Map on DNO sample application page cannot be zoomed in or zoomed out.

On the SOP administration page, for the HTTPS URI in the SOP Reference tab, the Launch URI button might not work. To open the URI, copy the URI and paste it in your browser.

Known issues on Safari

A line chart on the DNO sample application page cannot be zoomed in or out.

The Logical Map on DNO sample application page cannot be zoomed in or zoomed out.

Sometimes when you click an object on Logical Map on DNO sample application page, the preview card does not show.

Parent topic: Reference

Accessibility

Accessibility features help users with physical disabilities, such as restricted mobility or limited vision, to use software products successfully.

The major accessibility features in this product enable users to do the following:

Use assistive technologies, such as screen-reader software and digital speech synthesizer, to hear what is displayed on the screen. Consult the product documentation of the assistive technology for details on using those technologies with this product.

Operate specific or equivalent features using only the keyboard.

Magnify what is displayed on the screen.

In addition, the documentation was modified to include the following features to aid accessibility:

All documentation is available in XHTML formats to give the maximum opportunity for users to apply screen-reader software technology.

All images in the documentation are provided with alternative text so that users with vision impairments can understand the contents of the images.

The solution includes the following features to aid accessibility:

The Administration Console view includes an accessibility prologue that describes a link that you use to skip over the navigation elements of the page.

If you are using a screen reader and keyboard, click the Enable accessibility mode button to optimize your user experience. The button is displayed after you click the link to skip over the navigation elements on the Administration Console view.

The following web browser and screen reader are recommended:

Web browser

Mozilla Firefox 31 ESR

Screen reader

Freedom Scientific JAWS 16

Parent topic: Reference

Notices

This information was developed for products and services offered worldwide.

This material may be available from IBM in other languages. However, you may be required to own a copy of the product or product version in that language in order to access it.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. This document may describe products, services, or features that are not included in the Program or license entitlement that you have purchased.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation

North Castle Drive

Armonk, NY 10504-1785

U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law

IBM Japan Ltd.

19-21, Nihonbashi-Hakozakicho, Chuo-ku

Tokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Software Group

Attention: Licensing

3755 Riverside Dr.

Ottawa, ON

K1V 1B7

Canada

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Depending upon the configurations deployed, this Software Offering may use session cookies that collect each user's

name

user name

password

profile name

personally identifiable information other than name, user name, password, profile name and position

for purposes of

session management

single sign-on configuration

usage tracking or functional purposes other than session management, authentication, enhanced user usability and single sign-on configuration

These cookies cannot be disabled.

If the configurations deployed for this Software Offering provide you as customer the ability to collect personally identifiable information from end users via cookies and other technologies, you should seek your own legal advice about any laws applicable to such data collection, including any requirements for notice and consent.

For more information about the use of various technologies, including cookies, for these purposes, see IBM's Privacy Policy at http://www.ibm.com/privacy and IBM's Online Privacy Statement at http://www.ibm.com/privacy/details in the section entitled "Cookies, Web Beacons and Other Technologies" and the "IBM Software Products and Software-as-a-Service Privacy Statement" at http://www.ibm.com/software/info/product-privacy.

©

©

Product Information

This document applies to Industry Solutions Insights Foundation for Energy Version 1.5.0 and may also apply to subsequent releases.

Copyright

Licensed Materials - Property of IBM

© Copyright IBM Corp. 2015.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM, the IBM logo and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at " Copyright and trademark information " at www.ibm.com/legal/copytrade.shtml.

Parent topic: Notices

Preparing your development environment

Before you develop custom widgets and layouts, install a development environment and deploy the user interface framework EAR that is provided with IBM® Insights Foundation for Energy.

About this task

Install Rational® Software Architect for WebSphere® Software as your development environment. Edit the configuration for WebSphere Application Server Liberty Profile to deploy the user interface framework EAR.

Procedure

Install Rational Software Architect for WebSphere Software version 9.1.1. For more information, see the related link.

To deploy the ife_frwk_app.ear file to WebSphere Application Server Liberty Profile, edit the server.xml file to add the following configuration:

                        <enterpriseApplication id="ife_frwk_app" location="ife_frwk_app.ear" name="ife_frwk_app">
                           <classloadercommonLibraryRef="ifebaseLib"/>
                           <application-bnd>
                           <security-rolename="users">
                           <special-subjecttype="ALL_AUTHENTICATED_USERS"/>
                           </security-role>
                           </application-bnd>
                           </enterpriseApplication>

For more information about WebSphere Application Server Liberty Profile, see the related link.

Related information

WebSphere Application Server Network Deployment 8.5.5 product documentation: Liberty profile

IBM Rational Software Architect 9.1.1 product documentation

Creating a custom widget

To create a custom widget, add a JavaScript widget module to your custom web project.

Before you begin

When you design a custom widget, you need to identify the extension that is relevant for the widget. Every widget is registered as part of an extension. An extension is defined by a name and an optional description, and it groups widgets that have similar functions. Your JavaScript widget module must include any functions that are required by the extension. For example, the sample application includes a Preview Card extension to group widgets that display asset data in a preview card. Each widget that is added to the Preview Card extension must implement a function to provide the data to display on the preview card.

The user interface framework provides a number of JavaScript libraries and packages that you can use when you are creating custom widget modules. For more information, see JavaScript libraries and packages.

About this task

Use the JavaScript widget file that is named AssetPreviewCard.js as a guide to creating a custom widget. The AssetPreviewCard.js file is provided with the ife_sampleapp_web web project. The AssetPreviewCard widget is registered as part of the Preview Card extension.

Procedure

Open the Java EE view in Rational® Software Architect.

Go to the directory that you configured as the WebContent directory in your web project.

Create a directory to contain your custom JavaScript widget files, for example, WebContent/js/widget

Use the sample AssetPreviewCard.js JavaScript file as a guide to creating your custom widget module. The functions that you implement in a JavaScript widget module vary depending on the purpose of the widget. Table 1 describes some common widget functions. The widget module might also be required to implement some functions specific to the extension that the widget is added to.

Examples of widget functions

The following table describes three common widget functions:

Widget functions

Function | Description
placeAt:function(divId) | Positions the widget within a <div> element with the specified ID.
startup:function() | The function is run when the widget is displayed on a page.
getParameters:function() | The getParameters function returns a JSON object that lists the parameters that are required by the widget; for example, {"orientation":"horizontal"}.

Example of a function that is required by an extension

The widget extension might require the widget module to implement some functions. For example, if you add a widget to the Preview Card extension that is provided with the solution, then you must implement the setModel(message) function in the widget module. The setModel(message) function provides the asset data to display in the preview card.

Optional: You can also add image files to the web project to use as widget thumbnails. For example, you can add image files under the WebContent/images directory.

What to do next

Use the sample page configuration and HTML file to test your custom widget before you deploy your web project. For more information about testing your custom widget, see the related link. After you test and deploy your custom widget, your administrator can then register and configure the widget. For more information about configuring a widget, see the related link.

Related tasks

Testing custom layouts and widgets

Configuring widgets

Testing custom layouts and widgets

Use the sample page configuration that is provided with the solution to test custom widgets and layouts before you deploy them to production.

About this task

Before you deploy your custom web project to production, you can test your custom user interface components by using a JSON file and an HTML file that are provided with the sample web project, ife_sampleapp_web. The JSON file is named pageConfig_page1.json, and the HTML file is named layoutWrapper.html. Edit the pageConfig_page1.json file to add the configuration details for the layout and widgets that you want to test.

Procedure

Add configuration details for the layout to the pageConfig_page1.json file. The properties for a layout are described in the following table:

Property name
Type
Description

layout_id
String
An ID for the layout. The ID must be unique to the JSON file.

name
String
The name of the layout.

description
String
The description of the layout.

module
JSON object
The module property includes the following elements:

moduleName: the name of the JavaScript module that implements the layout, for example, ifef/layout/IFELayoutWithTaskbar.

pathName: the name of the package that contains the layout module, for example, ifef.

pathLocation: the package location, for example, /ibm/ife/framework/js.

Add configuration details for each widget to the widgets property in the pageConfig_page1.json file. The properties for a widget are described in the following table:

Property name
Type
Description

widget_id
String
An ID for the widget. The ID must be unique to the JSON file.

name
String
The name of the widget.

description
String
The description of the widget.

module
JSON object
The module property includes the following elements:

moduleName: the name of the JavaScript module that implements the widget, for example, ife/list/AssetListViewer.

pathName: the name of the package that contains the widget module, for example, ife.

pathLocation: the package location, for example, /ibm/ife/sample/widget/js.

Add configuration details for the config property to the pageConfig_page1.json file. The config property specifies the region and parameters for each widget on the page. The config properties are described in the following table:

Property name | Type | Description
widget_id | String | The ID of the widget to be displayed.
region_id | String | The ID of the region that contains the widget.
parameters | JSON object | The elements that are included in the parameters property are determined by the widget and by the region that includes the widget. The parameters are defined in the widget module's getParameters function, and in the layout module's getRegionParameters function.

To test the page configuration that is specified in the pageConfig_page1.json file, use the following URL:

http://

host

:

port

/ibm/ife/framework/layoutWrapper.html?config=/ibm/ife/sample/widget/pageConfig_page1.json.

Example

The following example shows sample configuration details in the pageConfig_page1.json file:

                     "layout": {"layout_id":"layout1",
                        "name": "IFELayout",
                        "description": "",
                        "module":{"moduleName":"ifef/layout/IFELayoutWithTaskbar",
                        "pathName":"ifef",
                        "pathLocation":"/ibm/ife/framework/js"
                        }
                        }
                        "widgets":
                        [
                        {"widget_id":"ife.List",
                        "name":"List",
                        "description":"",
                        "module":{"moduleName":"ife/list/AssetListViewer",
                        "pathName":"ife",
                        "pathLocation":"/ibm/ife/sample/widget/js"
                        }
                        },
                        {"widget_id": "ife.Filter",
                        "name": "Filter",
                        "description": "",
                        "module": {"moduleName":"ife/filter/FilterBar",
                        "pathName":"ife",
                        "pathLocation":"/ibm/ife/sample/widget/js"
                        }
                        }
                        ]
                        "config":
                        [
                        {"widget_id":"ife.List",
                        "region_id":"View",
                        "parameters":
                        {"noInit":true,
                        "view_name":"contentViewTab-List",
                        "i18nLabel":"List",
                        "greyIcon":"/ibm/ife/sample/widget/icon/ICN-TB_List-STD.png",
                        "selectedIcon":"/ibm/ife/sample/widget/icon/ICN-TB_List-SEL.png"
                        }
                        },
                        {"widget_id":"ife.Filter",
                        "region_id":"Task",
                        "parameters":
                        {"i18nLabel":"Filter",
                        "darkIcon":"/ibm/ife/sample/widget/icon/ICN-TB_Filter-STD.png",
                        "selectedIcon":"/ibm/ife/sample/widget/icon/ICN-TB_Filter-SEL.png",
                        "primaryPaneAttr":
                        {"title": "",
                        "overflow":"hidden",
                        "hasHideButton": false,
                        "name":"",
                        "position":{"top":"0px","left":"0px"},
                        "fullSize":{"width":"100%", "height":"36px"}
                        }
                        }
                        }
                        ]

What to do next

Deploy your custom web project to WebSphere® Application Server Liberty Profile.

Configuring widgets

If you are an administrator, you can register and configure custom widgets.

About this task

Use the Administration Console view to register and configure custom widgets. To group widgets that have similar functions, every widget is registered as part of an extension. Each widget is defined by a set of properties, and each property value that you enter is validated by the solution upon entry. You can view widgets that are provided with the solution, but you cannot edit or remove them.

Procedure

In the Administration Console view, click Widget . The extensions and their widgets are listed on the left.

Registering a custom widget

Click the add icon beside an extension.

In the Create a Widget window, enter the details for your custom widget.

In Name, enter a unique name for the widget.

Optional: In Description, enter a description of the widget.

In Module name, enter the name of the widget JavaScript module. For example, ife/map/MapViewExt.

In Package name, enter the name of the package that contains the widget JavaScript module. For example, ife.

In Package location, enter the location of the package. For example, /ibm/ife/sample/widget/js.

Optional: In Thumbnail, you can enter the details of a file to display as a thumbnail for the widget.

Click Save. The new widget is listed under the extension.

Editing a custom widget

Select the widget to edit the name, description, and thumbnail for the widget.

Note: The module name, package name, and package location cannot be edited.

Click Save.

Deleting a custom widget

Click the delete icon beside the widget, and then in the confirmation window, click Yes.

Note: You cannot delete a widget if the widget is included in the configuration of a page.

Creating a custom layout

A layout manages one or more regions, and each region includes one or more extensions. An extension is a mechanism for grouping widgets that have similar functions. To create a custom layout, add a JavaScript layout module to your custom web project.

Before you begin

The user interface framework provides a number of JavaScript libraries and packages that you can use when you are creating custom layout modules. For more information, see JavaScript libraries and packages.

About this task

Use the JavaScript layout file that is named IOWLayout.js as a guide to creating a custom layout. The IOWLayout.js file is provided with the ife_frwk_web web project.

Procedure

Open the Java EE view in Rational® Software Architect.

Go to the directory that you configured as the WebContent directory in your web project.

Create a directory to contain your custom JavaScript layout files, for example, WebContent/js/layout .

Use the IOWLayout.js JavaScript file as a guide to creating your custom layout module. The functions that you implement in a JavaScript layout module vary depending on the purpose of the layout. The following table describes some common layout functions:

Layout functions

Function
Description

placeAt: function(divId)
Positions the widget within a parent <div> element with the specified ID.

addWidget: function(widget, region)
The addWidget function adds a widget to a region in the layout; for example, addWidget(mapWidget, "View") .

getRegions: function()
The getRegions function returns a JSON array that contains the names of the regions in the layout; for example, ["View", "Task"].

getRegionParameters: function(region)
The getRegionParameters function returns a JSON object that describes extra widget parameters for any widget that is managed by the specified region; for example, { "view_name":"", "selectedIcon":"", "i18nLabel":"","greyIcon":""}.

Note: You can also specify default values for the parameters, for example, "i18nLabel":"Map".

Optional: You can also add image files to the web project to use as layout thumbnails. For example, you can add image files under the WebContent/images directory.

What to do next

Use the sample page configuration and HTML file to test your custom layout before you deploy your web project. For more information about testing your custom layout, see the related link. After you test and deploy your custom layout, your administrator can then register and configure the layout. For more information about configuring a layout, see the related link.

Related tasks

Testing custom layouts and widgets

Configuring layouts

Configuring layouts

As an administrator, you can register and configure custom layouts. A layout manages the widgets on a page. A layout is made up of regions, and each region can contain one or more extensions.

About this task

Use the Administration Console view to register and configure custom layouts. Each layout is defined by a set of properties, and each property value that you enter is validated by the solution upon entry. You can view layouts that are provided with the solution, but you cannot edit or remove them.

Procedure

In the Administration Console view, click Layout .

Registering a custom layout

Click Create.

In the Create a Layout window, enter the details for your custom layout.

In Name, enter a unique name for the layout.

Optional: In Description, enter a description of the layout.

In Module name, enter the name of the layout JavaScript module. For example, ife/layout/SampleLayout.

In Package name, enter the name of the package that contains the layout JavaScript module. For example, ife.

In Package location, enter the location of the package. For example, /ibm/ife/sample/widget/js.

Optional: In Thumbnail, you can enter the details of a file to display as a thumbnail for the layout. For example, /ibm/ife/framework/images/admin/sidebarlayout.png.

Click Save. The new layout is listed under the Create button.

Note: The regions for the layout are listed in the Regions table. Each region is defined by a unique name and a list of extensions, and can also include a description. The regions for a layout are defined in the layout's JavaScript module.

Editing a custom layout

To edit a region for a selected custom layout, click the row in the Regions table. The Edit a Region window displays.

In the Edit a Region window, enter the details for the region.

In Unique name, enter a unique name for the region.

Optional: In Description, you can enter a description of the region.

In Extensions, select one or more extensions to include in the region from the drop-down list.

Click Save to save the changes to the region.

You can also edit the name, description, and thumbnail for a custom layout.

Note: The module name, package name, and package location cannot be edited.

Click Save.

Deleting the configuration for a custom layout

Click the delete icon beside the custom layout, and then in the confirmation window, click Yes.

Note: You cannot delete the configuration for a custom layout if the layout is included in the configuration of a page.

Deploying a web project

Deploy your custom web project to WebSphere® Application Server Liberty Profile. You can package and deploy your web project as a WAR file or as an EAR file.

Before you begin

For more information about configuring WebSphere Application Server Liberty Profile, see WebSphere Application Server Network Deployment 8.5.5 product documentation: Liberty profile .

Procedure

To deploy a custom web project to WebSphere Application Server Liberty Profile, edit the server.xml file to add configuration for either the WAR file, or the EAR file.

To deploy the sample ife_sampleapp_web.war file, add the following configuration to the server.xml file:

                           <enterpriseApplication id="ife_sampleapp_web" location="ife_sampleapp_web.war" name="ife_sampleapp_web">
                              <classloadercommonLibraryRef="ifebaseLib"/>
                              <application-bnd>
                              <security-rolename="users">
                              <special-subjecttype="ALL_AUTHENTICATED_USERS"/>
                              </security-role>
                              </application-bnd>
                              </enterpriseApplication>

To deploy the sample ife_sample_app.ear file, add the following configuration to the server.xml file:

                           <enterpriseApplication id="ife_sample_app" location="ife_sample_app.ear" name="ife_sample_app">
                              <classloadercommonLibraryRef="ifebaseLib"/>
                              <application-bnd>
                              <security-rolename="users">
                              <special-subjecttype="ALL_AUTHENTICATED_USERS"/>
                              </security-role>
                              </application-bnd>
                              </enterpriseApplication>

What to do next

Use the Administration Console view to register and configure your custom widgets and layouts. For more information, see the related links.

Related tasks

Configuring widgets

Configuring layouts

Copyright notice and trademarks