Skip to main content

Archibus (Eptura) Data Source

The Archibus (Eptura) connector enables you to ingest space, facilities, employee, asset, and service desk data from your Archibus Web Central instance into Nexla. Follow the instructions below to create a new data flow that ingests data from an Archibus (Eptura) source in Nexla.
archibus_api.png

Archibus (Eptura)

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the Archibus (Eptura) connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Archibus (Eptura) instance, and click Next; or, create a new Archibus (Eptura) credential for use in this flow.

  3. In Nexla, Archibus (Eptura) data sources can be created using pre-built endpoint templates, which expedite source setup for common Archibus REST API endpoints. Each template is designed specifically for the corresponding Archibus endpoint, making source configuration easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    Archibus (Eptura) sources can also be configured manually, allowing you to ingest data from Archibus endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Archibus (Eptura) endpoints. Each template wraps a specific Archibus REST API endpoint — including data sources of the form Api_*_v1 and dedicated Service Desk endpoints — so that you can pull workplace data into Nexla without composing API URLs manually.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

    Get Buildings

    This endpoint retrieves all buildings from your Archibus portfolio inventory using the Api_Buildings_v1 data source. Use it to feed downstream space, real estate, and reporting flows with the latest building records.

    • Enter the 0-based row index from which Nexla should begin paging results in the Page Start (offset) field. The default value of 0 performs a full sync from the first row.
    • Enter the number of records per page in the Page Size field. The default value of 100 is a balanced choice; set this value to 0 to fetch all rows in a single call.

    Records are returned from the Archibus bl table by way of the Api_Buildings_v1 data source. For complete information about this endpoint and the available fields, see the Archibus Buildings REST API documentation.

    Get Floors

    This endpoint retrieves floor records from Archibus using the generic Data Source API and the Api_Floors_v1 data source. Use it to enrich building data with floor-level inventory for space planning and occupancy reporting.

    • Enter the 0-based row index from which Nexla should begin paging results in the Page Start (offset) field.
    • Enter the number of floor records per page in the Page Size field. Set this value to 0 to fetch all floors in a single call.

    The Data Source API respects Archibus per-user and per-role Virtual Private Archibus (VPA) restrictions, so the records returned will reflect the visibility rules associated with the Archibus user mapped to the OIDC token.

    Get Rooms / Spaces

    This endpoint retrieves room and space inventory records from Archibus using the Api_Rooms_v1 data source. It is the core space utilization feed for occupancy analysis, charge-back reporting, and AI-driven workplace optimization use cases.

    • Enter the 0-based row index from which Nexla should begin paging results in the Page Start (offset) field.
    • Enter the number of room records per page in the Page Size field. Set this value to 0 to fetch all rooms in a single call.

    Room records include attributes such as area, room category, room type, and division/department codes — refer to the Archibus Data Source REST API reference for a complete list of fields available from Api_Rooms_v1.

    Get Employee Locations

    This endpoint queries employee seat assignments and location data via the Api_HrEmLocations_v1 data source. Use it to align HR data with workplace assignments and to power people-and-place analytics.

    • Enter the 0-based row index from which Nexla should begin paging results in the Page Start (offset) field.
    • Enter the number of employee location records per page in the Page Size field.

    Datetime fields returned from this endpoint follow the format yyyy-MM-dd'T'HH:mm:ss'Z'. The Api_HrEmLocations_v1 data source supports incremental retrieval by filtering on the last-updated field — combine this endpoint with a Nexla scheduled ingest to capture only records changed since the previous run.

    Get Service Requests

    This endpoint retrieves service desk work requests from Archibus (sourced from the activity_log table). Use it to feed status dashboards, SLA reporting, and downstream ticketing or ITSM integrations.

    • Enter the 0-based row offset for paging through service requests in the Page Start (offset) field.
    • Enter the number of service request records per page in the Page Size field.

    Datetime fields are returned in the format yyyy-MM-dd'T'HH:mm:ss'Z'. For complete information about service desk record structure and lifecycle status codes, see the Archibus Service Desk REST API documentation.

    Get Data via DataSource

    This generic endpoint allows you to query any Archibus REST data source by name (Api_*_v1). Use it to access domain tables beyond the curated endpoints — including assets, leases, preventive maintenance schedules, problem types, and any custom data sources that follow the Archibus data source naming convention.

    • Enter the Archibus data source name in the Data Source Name field (e.g., Api_Buildings_v1, Api_HrEmLocations_v1, Api_ProbTypes_v1). Data source names follow the pattern Api_[dataSourceName]_v[version] and are defined in schema/ab-products/common/api/ab-api-datasources.axvw.
    • Enter the 0-based row index from which Nexla should begin paging results in the Page Start (offset) field. Use 0 for a full sync.
    • Enter the number of rows per page in the Page Size field. Set this value to 0 to fetch all rows in a single call.

    The Data REST API accesses the Archibus database only via data sources and enforces Archibus security, including per-user and per-role VPAs and per-field security groups. For more information about defining and using custom data sources, see the Archibus Data Sources REST API documentation.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

Archibus (Eptura) data sources can be manually configured to ingest data from any valid Archibus Web Central REST API endpoint, including custom data sources of the form Api_*_v1 and ad hoc endpoints under /api/v1/.... Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Archibus sources, such as sources that select specific fields via query parameters, apply Archibus filter expressions, or use chained API calls to enrich one data set with another.

API Method​

  1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

  2. Select the API method that will be used for calls to the Archibus REST API from the Method pulldown menu. The Archibus Data REST API is read using:

    • GET: For retrieving records from a data source (the most common method for Archibus source flows)

API Endpoint URL​

  1. Enter the URL of the Archibus REST API endpoint from which this source will fetch data in the Set API URL field. Archibus REST endpoints follow the pattern <base_url>/api/v1/data/<resource>?dataSource=Api_<Name>_v1 for Data REST API calls and <base_url>/api/v1/service-desk/... for service desk endpoints.

Field selection and filtering can be applied via Archibus-specific query parameters. Callers can specify which fields to query and include in returned data objects by passing the list of field names as a URI query parameter; field names must match Archibus schema field names defined in the AFM Fields table.

Date/Time Macros (API URL)​

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements, which is particularly useful for Archibus endpoints that filter by date_assigned, date_closed, or other timestamp fields.

Macros are particularly useful for Archibus service desk endpoints, employee location endpoints, and any custom data source where incremental ingestion based on a timestamp column is desired.

  1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

    • {now} – The current datetime
    • {now-1} – The datetime one time unit before the current datetime
    • {now+1} – The datetime one time unit after the current datetime
    • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

  2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. For Archibus endpoints that return ISO 8601 timestamps such as employee locations and service requests, use the format yyyy-MM-dd'T'HH:mm:ss'Z'.

  3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)​

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic Archibus endpoints — for example, iterating over a list of building codes from one Nexset to fetch related floors or rooms from another.

Lookup-based macros are useful when you need to drive Archibus API calls from a list of identifiers managed in another data source — such as iterating over a list of bl_id values to retrieve all floors for each building.

  1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

  2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data​

Optional

If only a subset of the data returned by the Archibus REST API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response.

The Archibus Data REST API typically returns records as a top-level JSON array. By entering the path to the relevant data, you can configure Nexla to treat each element of the returned array as an individual record.

Path to Data is essential when API responses have nested structures. Without specifying the correct path, Nexla might not be able to properly parse and organize your data into usable records.

  • To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

    • For Archibus responses in JSON format, enter the JSON path that points to the object or array that should be treated as relevant data. The pre-built Archibus templates use $[*] — which treats each element of the top-level array as a record — and this is a reasonable default for most Api_*_v1 data sources.
    Path to Data Example:

    For a typical Archibus data source response that returns a top-level JSON array of objects, the path to the response would be entered as $[*].

Autogenerate Path Suggestions​

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

  • To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

  • Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

    PathSuggestions.png

Metadata​

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful when you want to preserve important contextual information from the Archibus response — such as response timestamps or total record counts — that applies to all records but isn't part of the main data array.

Metadata paths are particularly useful for preserving API response context like request IDs, timestamps, or summary statistics that apply to all records in the response.

  • To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

    • For Archibus responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Pagination Settings​

Optional

The Archibus Data REST API uses offset-based paging controlled by the pageStart and pageSize query parameters. When manually configuring a source, replicate the pattern used by the pre-built templates:

  • Use pageStart=${rest.iterations.<endpoint_name>.page_start} as the offset parameter, starting from 0.

  • Use pageSize=${rest.iterations.<endpoint_name>.page_size} as the page size parameter. A value of 0 typically returns all rows in a single response.

  • The expected page size is 100 records by default, matching the behavior of the pre-built endpoint templates.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). The Archibus REST API generally only requires Content-Type: application/json, which is included automatically by the pre-built templates.

    You do not need to include any headers already present in the credentials. The OAuth 2.0 bearer token is added automatically by Nexla based on your credential configuration.

Endpoint Testing​

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source​

  1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Archibus (Eptura) data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.