The IBM TAS Connector for Envizi is released under the name "MAS Connector for Envizi". This connector supports the following capabilities through an App Connect flow:
-Automatically sync space and occupancy data from TRIRIGA with Envizi to enable energy usage calculations across entire facility portfolio with advanced analytics by location, by SQF, and by occupant.
Corporate sustainability managers can gather and maintain accurate sustainability data for their entire global real estate portfolio directly from TRIRIGA where those facilities are managed. Location data from TRIRIGA serves as a baseline for all other Sustainability reports in Envizi; space classification, floor space, and headcount data allows Sustainability managers to normalize data (by square meter, or by employee) to enable meaningful comparisons between buildings across the entire portfolio to identify opportunities to reduce environmental impact.
IBM App Connect provides a flexible environment for integration solutions to transform, enrich, route, and process business messages and data.
App Connect Flows enable specific integration use cases by connecting to predefined APIs to route and map data. Mapping has been pre-defined, but it can be customized.
Native API framework is used for Maximo and enabled thorugh provided packages that can be imported.
TRIRIGA to Envizi Integration Diagram
The image below illustrates the type of data that is being sent by the API and App Connect Flows.
TRIRIGA to Envizi Data Map
Included with this connector are two flows that export locations and accounts, along with all the required fields they contain. The table below shows the naming convention for these flows and the current integration use case.
| File | Flow | Destination | Operation |
|---|---|---|---|
| TririgaBuildings_Always_On_v1_1_1.yaml | Space Data | TRI to Envizi | Changes Only |
| TririgaBuildings_On_Demand_v1_1_1.yaml | Space Data | TRI to Envizi | Bulk Initial Load |
- An instance of App Connect Enterprise or App Connect Pro with the Designer component.
- Admin access to TRIRIGA with user/pw for integration
- Envizi instance with a AWS S3 Bucket
- Import AppConnect Cert to TRIRIGA to enable encrypted communication
- App Connect Configuration
a. Import Flows into App Connect
b. Configure Flows - TRIRIGA
a. Security Role Configuration
b. Group Name Configuration - Test
a. TRIRIGA outbound connectivity
Note: IBM Cloud App Connect Professional or Enterprise is needed to run this flow.
Note: The names in the screenshots are generic, the elements in this integration will not have the same names during setup.
Before importing the flow to App Connect, add Accounts for Amazon S3 and HTTP connectors. While adding the HTTP connector account, include credentials for the TRIRIGA user which can consume the OSLC API.
- Navigate to Catalog section of the App Connect instance
-
In the Search application field, type name of the connector.
-
If the App Connect instance does not have an account for the connector, click on Connect to create a new account. Else, open the account selection drop down, and click on Add a new account ...
- Enter the necessary details for the connector
a. For Amazon S3, it will be the Secret Access Key and Access Key ID provided by Envizi.
b. For HTTP, it will be the Authentication Key or username and password needed for TRIRIGA.
- Click on Connect
- From the account selection drop down, select the newly created account. e.g., The default name will be
Account 2ifAccount 1is already present - Click on the kebab menu (three dots) and select Rename Account
- Enter an account name and click on Rename Account. This name can now be used by the connector in the flow.
- Open the Dashboard of the App Connect instance.
- Click on the New button and select Import Flow.
- Browse to the flow's YAML file and click on Import.
- The flow will now be imported and opened.
When importing a flow, it is important to check if the flow is using the right accounts for the different connectors.
-
Click on Edit Flow
-
See if the connectors are using the right accounts.
-
To change the account for any connector, select the connector and click on the dropdown icon next to the Account's name
- Select the account name to use from the list
- Click on the Scheduler node
- Configure the schedule as needed
In order to properly configure TRIRIGA, a user needs to be configured with the proper security access for Object Migration and TRIRIGA APIs
Object Migration is a task managed by administrators. If a TRIRIGA User needs to have full access to Object Migration in TRIRIGA, access is granted at the group level. Follow the steps given in Chapter 1 to create a new security group.
- Select the newly created group or desired existing group and switch to the Access tab and add the appropriate access for importation of Object Migration Packages. There are 2 panes in Access: Object and Permissions.
- Scroll and find the Object Migration Object on the left pane and click Full Access on the right pane. The users in this group, granted through the Members tab, will be able to import the TRIRIGA API Object Migration package.
Access Permissions
Additional information on TRIRIGA Security groups
Import the OM Package labeled APIConnector into the TRIRIGA instance. Go to Tools -> Administration -> Object Migration and select New Import Package to begin the import process.
Please refer to the IBM® TRIRIGA documentation for more information on Object Migration.
In order for App Connect to be able to use TRIRIGA APIs, it will need a user with certain permissions. These user's credentials will be configured in App Connect.
-
Create a new user by following the steps given in Chapter 2.
-
Choose a security group or create a new group (refer to the above OM Migration steps if a new security group needs to be created) and add the newly created user to it.
-
Add the permissions below for the new user's group:
| Module | Business Object | Permissions |
|---|---|---|
| Location | triBuilding | Read |
| triAPIConnect | triAPICTimestamp | Read and Update |
- Follow the steps given in Chapter 1 and add any one of the licenses below for the new user's group:
a. IBM TRIRIGA Portfolio Data Manager
b. IBM Facilities and Real Estate Management on Cloud Self Service
c. Any other license that grants access to the modules
Please refer to the TRIRIGA Documentation on Security and Licenses for additional information.
The user will now be able to interact with the proper TRIRIGA Modules.
For outbound traffic from TRIRIGA, grant at least READ access on the Business Objects that will be used. The table below shows the various supported business Objects the API can pull from:
| Module | Business Object Label |
|---|---|
| Asset | Building Equipment |
| Classification | Request Class |
| Classification | Space Class Current |
| Classification | Asset Spec Class |
| People | People |
| Location | Property |
| Location | Building |
| Location | Floor |
| Location | Space |
| Organization | Organization |
| Request | Service Request |
| Task | Work Task |
In the example below, the API user is able to pull data from the Building Business Object:
For inbound traffic, Data Access needs to be enabled as well as Application Access permissions to the triAPIConnect Module or the individual Objects. To enable an API user to create a building, grant access to the triAPICBuilding Business object as shown below:
For users to pull from these URLs, the minimum requirements are:
| URL | Requirement |
|---|---|
| GET /oslc/spq/triAPICOutboundBuildingQC | READ access to triBuilding Business object |
| GET /oslc/spq/triAPICTimeStampQC | READ access to triAPICTimestamp Business Object |
| POST /oslc/so/triAPICTimeStampRS/ | Write access to triAPICTimestamp Business Object |
The following steps outline the necessary configurations for the Envizi Group Name Configuration page.
-
Go to Tools -> Builder Tools -> Data Modeler and using the Object Browser navigate to Location->triBuilding.
-
Revise the BO and add four fields: cstEnviziParentOneTX, cstEnviziParentTwoTX, cstEnviziParentThreeTX and cstEnviziGroupNamePathTX
Name and Label should be the following:
| Name | Label |
|---|---|
| cstEnviziParentOneTX | Envizi Group 1 |
| cstEnviziParentTwoTX | Envizi Group 2 |
| cstEnviziParentThreeTX | Envizi Group 3 |
| cstEnviziGroupNamePathTX | Envizi Path |
After entering these values, click Publish to publish the BO
-
Under Tools -> Builder Tools -> Form Builder, click on the Location module on the left side of the screen and then click on triBuilding.
-
Revise the triBuilding form by clicking Revise in the top right corner of the pop-up
-
In the Navigation pane on the left side of the screen, click on triBuilding and then Add Tab. Enter cstEnvizi as the Name and Envizi as the Label. Click Apply
-
Select this new tab and click on Add Section
-
Enter cstEnviziDetails as the Name and Envizi Details as the Label. Click Apply.
-
Now click on the newly created Section and select Add Field. Select each of the four created business objects from the previous step as fields under Envizi Details.
-
Select cstEnviziGroupNamePathTX and modify Start Row to 3 and Col Span to 2 on the properties window. Mark this field as ReadOnly and click Apply. The form should look like this:
-
Go to Import Migration and import package EnviziConfig.zip
-
To do that, click on New Import Package, and select the zip file and click Ok.
-
A new window will be displayed. If it is not displayed, just select the package from the list.
-
On this package, click on Validate and wait for the validation to complete. If no errors are displayed, import the package.
-
Go to Tools -> Administration -> Security Manager
-
This application sets who can and cannot access this newly created tab. Click on the desired group, and navigate to the Access tab
-
On this tab select Location -> triBuilding -> cstEnvizi
-
Choose the access level for the group and Save
-
Go to Tools -> Builder Tools -> Workflow Builder. Select Location -> triBuilding.
-
Within the Location object, search for the existing Workflow triBuilding - Synchronous - Permanent Save Validation.
-
Revise this workflow and after Call Module Level Validation add a new WF call to triBuilding - Update Envizi fields with defined options like displayed below:
It will be defined as the image below:
- Click on the Start task at the top and publish the workflow
- Go to My Reports and navigate to System Reports. Add those four new fields to the existing query triAPICBuilding - OSLC -- Outbound by clicking the Columns tab and adding the four fields like below:
-
Save the report.
-
Open Tools -> System Setup -> Integration -> OSLC Resource manager and search for triAPICOutboundBuildingRS. On this resource, add the four new fields either individually or using Import all Fields
- Go to Tools->Builder Tools-> Navigation Builder and find TRIRIGA Global Menu (or the menu associated to the user that will need access to the app). Select and click Edit
- On navigation Items section, expand Landing Page –Tools -> Menu Group –>System Setup. Select Menu group –>Integration and expand Navigations Item Library
- Search for Envizi, select the item and click on Add to Collection
- Click Save. Logout and Login again to the system
The triAPICTimestamp is a TRIRIGA record needed to set the baseline for when API connect runs for the first time.
To enable this functionality:
- Go to My Reports -> System Reports and search for Timestamp in the Name section.
- Run the system report triAPICTimestamp – Display – Manager Query as shown below:
- Click Add, and create a new record without details, as shown below, and close it
The default date and time the record gets automatically applied to the record, and consequent opening of the record shows the default date and time as shown below:
This tool will allow user to make changes on this new Envizi group name fields. But we must consider the existing records too. If you want those records to be populated, there is a patch helper workflow that can handle that.
The first thing that must be defined is which fields will be used to populate groups 1, 2 and 3 to be used on Envizi. To access the Envizi tool, go to Tools -> System Setup -> Integration -> Envizi Integation.
When you open the page, the fields will be displayed as Group1/Group2/Group3. By default the values are World Region/Country/City. The field Envizi Hierarchy Path shows how the Envizi groupnames will be configured according to the selected option.
Enable Envizi checkbox is available too. The Envizi tab will be displayed only when this checkbox is marked
One more item that must be configured is the Number of levels to be used on the Envizi configuration. Envizi hierarchy path will match this selection.
Also, notice that there is a section named Active/Retire with missing data and Draft/Revision with Missing Data. This section will list the buildings that don’t have data defined for Envizi group 3, so it means that no Envizi group will be populated on those buildings.
You can filter to change only the desired records by changing query cst -triBuilding -Query -Get All Buildings for envizi. The list of buildings displayed on this query will be the list of buildings that the patch helper will modify.
To use the tool, just select the desired Envizi group names and click Save. On the moment Save is triggered, all buildings will be populated with the desired options. This process may take a few minutes depending on how many buildings you have on your system. After that Envizi groups and path will be updated according to the selections made on Envizi Integration page.
Also, every time a building is saved and there are changes on the defined fields, or a new building is created, the Envizi groups and path will be modified according to the selected options. You can find the groups on tab Envizi on the building record
This flow is for the initial sync or to sync data that was added/updated between specific dates. This flow is meant to be executed just once whenever needed and then stopped.
- The following parameters in the initial Set variable node need to be configured in order to use this flow:
Override Dates in Set Variable
| Parameter | Value |
|---|---|
| OverrideFromDate | The start timestamp of the window between which the data will be pulled from. e.g., 2022-06-26T23:09:30-07:00 |
| OverrideToDate | The end timestamp of the window between which the data will be pulled from. e.g., 2023-06-26T23:09:30-07:00 |
These dates must be specified in ISO 8601 format
This flow is to keep syncing the data after the initial sync. This flow is meant to be kept running and will only sync the data that has been added or updated after its previous execution event. For example, if the flow executes at 2 PM and it's previous execution was at 1 PM, the flow will pull data that has been added or updated after 1 PM.
- Click on the initial Set variable node
- In Variable -> config -> customer, enter the value provided by Envizi
- In Variable -> config -> triURL, enter URL for the TRIRIGA instance. (e.g., https://example.com:9080)
- Click on the kebab menu (three dots) on either the flow's tile or the specific flow page.
- Click on Start API or Stop API depending on which action is desired.
A good way to test the TRIRIGA Outbound connectivity is to use the Always_On flow.
- Start the Always_On flow and add a test building in the system.
- If configured correctly, the integration should pick up this change and deliver a .csv file with just that test building.
See below for any errors that arise in App Connect.
The below errors are found in the App Connect logs.
| Error | Cause | Resolution |
|---|---|---|
| 404 - API doesn't exist | Flow is not running | Double check that the flow is Active in App Connect |
| 404 - The HTTP request returned with an error 404 "Not Found" | Incorrect App Connect connector config | Double check that the credentials being used in the HTTP post node in App Connect are correct |
- If these do not resolve the issue, try clearing the OSLC Cache in TRIRIGA Admin Console in case the integrations do not work in intended manner.
Note If you have not already done so, please import App Connect Cert to TRIRIGA to enable encrypted communication. Provide the Cert from App Connect as a secret to the instance of TAS as such:
cat <<EOF | oc create -f -
apiVersion: truststore-mgr.ibm.com/v1
kind: Truststore
metadata:
name: my-tas-truststore
spec:
license:
accept: true
includeDefaultCAs: true
servers:
- "example.com:443"
certificates:
- alias: alias_1
crt: |
-----BEGIN CERTIFICATE-----
...
Certificate 1
...
-----END CERTIFICATE-----
...
- alias: alias_n
crt: |
-----BEGIN CERTIFICATE-----
...
Certificate n
...
-----END CERTIFICATE-----
EOF