# tririga-envizi-appconnect-flows
**Repository Path**: mirrors_ibm/tririga-envizi-appconnect-flows
## Basic Information
- **Project Name**: tririga-envizi-appconnect-flows
- **Description**: App Connect flows for integration with TRIRIGA and Envizi applications
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-07-13
- **Last Updated**: 2025-09-14
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# IBM TAS Connector for Envizi
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.
***
## Use Case Examples
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.
***
## Connector Architecture
**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*
***
## Data Mapping
The image below illustrates the type of data that is being sent by the API and App Connect Flows.
*TRIRIGA to Envizi Data Map*
***
## App Connect Flows
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
***
## Installation & Configuration Guide
>## Before you begin you will need:
>
>1. An instance of App Connect Enterprise or App Connect Pro with the Designer component.
>2. Admin access to TRIRIGA with user/pw for integration
>3. Envizi instance with a AWS S3 Bucket
>4. [Import AppConnect Cert to TRIRIGA](#tririga-certificates) to enable encrypted communication
***
## Installation Steps Overview
1. App Connect Configuration
a. Import Flows into App Connect
b. Configure Flows
2. TRIRIGA
a. Security Role Configuration
b. Group Name Configuration
3. Test
a. TRIRIGA outbound connectivity
***
## Part 1: App Connect Configuration
*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.*
### Adding Accounts
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.
1. Navigate to Catalog section of the App Connect instance
*Create Account 1*
2. In the **Search application** field, type name of the connector.
3. 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 ...**
*Add a New Account*
4. 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.
*Connect to S3/HTTP*
5. Click on **Connect**
*Connect the Account*
6. From the account selection drop down, select the newly created account. e.g., The default name will be `Account 2` if `Account 1` is already present
7. Click on the kebab menu (three dots) and select **Rename Account**
*Rename the Account step 1*
8. Enter an account name and click on **Rename Account**. This name can now be used by the connector in the flow.
*Rename the Account step 2*
### Importing the flow
1. Open the Dashboard of the App Connect instance.
2. Click on the **New** button and select **Import Flow**.
*Import the flow*
3. Browse to the flow's YAML file and click on **Import**.
*Select the desired flow*
4. The flow will now be imported and opened.
*The main page for the flow*
### Configuring the flow to use the right accounts
When importing a flow, it is important to check if the flow is using the right accounts for the different connectors.
1. Click on **Edit Flow**
2. See if the connectors are using the right accounts.
3. To change the account for any connector, select the connector and click on the dropdown icon next to the Account's name
*Change associated Account*
4. Select the account name to use from the list
*Select desired Account*
### Configuring the Scheduler
1. Click on the **Scheduler** node
*The Scheduler node*
2. Configure the schedule as needed
*Options for configuration- Hourly*
*Options for configuration- Daily*
## Part 2: TRIRIGA Configuration
### Step 1: Security Role Configuration
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 Access
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](https://www.ibm.com/docs/en/SSFCZ3_11.2/pdf/pdf_tri_app_admin.pdf) to create a new security group.
1. 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**.
2. 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](https://www.ibm.com/docs/en/tap/3.6.1?topic=security-groups)
#### Import OM Package
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](https://www.ibm.com/docs/en/tap/3.6.1?topic=objects-object-migration-overview ) for more information on Object Migration.
#### TRIRIGA API User Access
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.
1. Create a new user by following the steps given in [Chapter 2](https://www.ibm.com/docs/en/SSFCZ3_11.2/pdf/pdf_tri_app_admin.pdf).
2. Choose a security group or create a new group (refer to [the above OM Migration steps](#object-migration-access) if a new security group needs to be created) and add the newly created user to it.
3. Add the permissions below for the new user's group:
| Module | Business Object | Permissions |
|---------------|-------------------------|--------------------|
| Location | triBuilding | Read |
| triAPIConnect | triAPICTimestamp | Read and Update |
4. Follow the steps given in [Chapter 1](https://www.ibm.com/docs/en/SSFCZ3_11.2/pdf/pdf_tri_app_admin.pdf) 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](https://www.ibm.com/docs/en/tap/3.6.1?topic=platform-license-files) for additional information.
The user will now be able to interact with the proper TRIRIGA Modules.
#### Outbound Traffic from TRIRIGA
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](https://github.com/IBM/tririga-api/blob/main/markdowns/Asset.md)
Classification | [Request Class](https://github.com/IBM/tririga-api/blob/main/markdowns/RequestClass.md)
Classification | [Space Class Current](https://github.com/IBM/tririga-api/blob/main/markdowns/SpaceClass.md)
Classification | [Asset Spec Class](https://github.com/IBM/tririga-api/blob/main/markdowns/AssetSpecClass.md)
People | [People](https://github.com/IBM/tririga-api/blob/main/markdowns/People.md)
Location |[Property](https://github.com/IBM/tririga-api/blob/main/markdowns/Property.md)
Location |[Building](https://github.com/IBM/tririga-api/blob/main/markdowns/Building.md)
Location |[Floor](https://github.com/IBM/tririga-api/blob/main/markdowns/Floor.md)
Location |[Space](https://github.com/IBM/tririga-api/blob/main/markdowns/Space.md)
Organization |[Organization](https://github.com/IBM/tririga-api/blob/main/markdowns/Organization.md)
Request |[Service Request](https://github.com/IBM/tririga-api/blob/main/markdowns/ServiceRequest.md)
Task |[Work Task](https://github.com/IBM/tririga-api/blob/main/markdowns/WorkTask.md)
In the example below, the API user is able to pull data from the Building Business Object:
#### Inbound traffic to TRIRIGA
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:
#### Minimum requirements
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
### Step 2: Group Name Configuration
The following steps outline the necessary configurations for the Envizi Group Name Configuration page.
#### Data Modeler
1. Go to **Tools -> Builder Tools -> Data Modeler** and using the Object Browser navigate to **Location->triBuilding**.
2. 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
#### Form Builder
1. Under **Tools -> Builder Tools -> Form Builder**, click on the Location module on the left side of the screen and then click on **triBuilding**.
2. Revise the triBuilding form by clicking **Revise** in the top right corner of the pop-up
3. 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**
4. Select this new tab and click on **Add Section**
5. Enter **cstEnviziDetails** as the **Name** and **Envizi Details** as the **Label**. Click **Apply**.
6. 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**.
7. 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:
8. Click on **triBuilding** on the left panel and then click on **Sort Tab**. Move
the **cstEnvizi** tab to the second position and click **Apply**
9. Publish the form
#### Object Migration
1. Go to **Import Migration** and import package EnviziConfig.zip
2. To do that, click on New Import Package, and select the zip file and click Ok.
3. A new window will be displayed. If it is not displayed, just select the package from the list.
4. On this package, click on **Validate** and wait for the validation to complete. If no errors are displayed, import the package.
#### Security Manager
1. Go to **Tools -> Administration -> Security Manager**
2. This application sets who can and cannot access this newly created tab. Click on the desired group, and navigate to the **Access** tab
3. On this tab select **Location -> triBuilding -> cstEnvizi**
4. Choose the access level for the group and **Save**
#### Workflow Builder
1. Go to **Tools -> Builder Tools -> Workflow Builder**. Select **Location -> triBuilding**.
2. Within the Location object, search for the existing Workflow **triBuilding - Synchronous - Permanent Save Validation**.
3. 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:
4. Click on the **Start** task at the top and publish the workflow
#### My Reports and OSLC
1. 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:
2. Save the report.
3. 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**
#### Navigation Builder
1. 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**
2. On navigation Items section, expand **Landing Page –Tools -> Menu Group –>System Setup**. Select **Menu group –>Integration** and expand **Navigations Item Library**
3. Search for Envizi, select the item and click on **Add to Collection**
4. Click **Save**. Logout and Login again to the system
#### Time Stamp Pre-requisite
The triAPICTimestamp is a TRIRIGA record needed to set the baseline for when API connect runs for the first time.
To enable this functionality:
1. Go to **My Reports -> System Reports** and search for **Timestamp** in the **Name** section.
2. Run the system report **triAPICTimestamp – Display – Manager Query** as shown below:
3. 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:
#### Using the Integration
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
## Operating the Connector
#### On-demand Flow
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.
1. 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**
#### Always-On Flow
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.
#### Configuring the Flow Parameters
1. Click on the initial **Set variable** node
*Fields in 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)
### Starting and Stopping the flow
1. Click on the kebab menu (three dots) on either the flow's tile or the specific flow page.
*Start the flow from the dashboard*
*Start the flow from the page*
2. Click on **Start API** or **Stop API** depending on which action is desired.
## Part 3: Testing
A good way to test the TRIRIGA Outbound connectivity is to use the *Always_On* flow.
1. Start the *Always_On* flow and add a test building in the system.
2. If configured correctly, the integration should pick up this change and deliver a .csv file with just that test building.
See [below](#common-errors-that-arise-from-tririga) for any errors that arise in App Connect.
## Troubleshooting
### Common errors that arise from TRIRIGA
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.
## Reference for Pre-requisite
### TRIRIGA Certificates
> **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 <