Request

Response

    Beta APIs are subject to change. Please avoid using them in production environments.

    Create Exchange Using AEC Data Model Filters

    In this tutorial, you will learn how to create an exchange using AEC Data Model filters to extract detailed, granular data from the exchange

    You can filter the data based on Category, Family, and Type. For each filter, you can select an option of your choice. For example, if you want to extract only windows from a model, select the “Windows” option under Category. You can then refine your selection further by applying additional filters under Family and Type as needed.

    In this tutorial, we will create an exchange using the AEC Data Model filter, specifically focusing on the Windows category.

    You will use the following mutation in this tutorial:

    TypeOperationDescription
    Mutation createExchange Creates a data exchange.

    Step 1 - Create Exchange based on filter category “Windows”

    The following steps demonstrate how you can run the createExchange mutation to create an exchange based on the AEC Data Model filter category “Windows”.

    1. Enter the following query in the Query Pane of the Data Exchange Explorer.

      Query

      mutation CreateExchange(
              $filter: String
              $sourceFileId: String!
              $targetExchangeName: String!
              $targetFolderId: String!
          ) {
              createExchange(
                  input: {
                      filter: $filter
                      source: { fileId: $sourceFileId }
                      target: { name: $targetExchangeName, folderId: $targetFolderId }
                  }
              ) {
                  exchange {
                      id
                      name
                      elements {
                          results {
                              id
                              name
                          }
                      }
                  }
              }
          }
      
      Show More
    2. In the Query Variables pane, enter the values for the following fields:

      • filter: The RSQL AEC DM filter string that specifies the criteria for data extraction. In this case, the filter is based on the Windows category.
      • sourceFileId: The item ID of the Revit source file from which the exchange is being created.
      • targetExchangeName: The name of the exchange that will be created.
      • targetFolderId: The ID of the target folder where the exchange will be stored.

      Note

      Keep the following rules in mind when building AEC Data Model filters:

      • Enclose string values in single quotes. For example, use category=='Walls' (correct), not category==Walls (incorrect). A filter without single quotes around the value may not be applied as expected.
      • Use either filter or viewName, but not both. The createExchange mutation accepts only one of these inputs per call. Use viewName for Revit files that have not yet been imported as AEC data; use filter when AEC Data Model is enabled on the hub/project.
      • Filters require AEC Data Model to be enabled on the hub/project. To enable it, see the AEC Data Model Onboarding Guide.

      You can filter on Category, Family, and Type, and combine conditions using logical operators. For example:

      • (category=='Walls') — extract only elements in the Walls category.
      • (family=='IND Staircase Assembly Steel_2' or family=='IND Staircase Assembly Steel_4') — extract elements matching either family.
      • (type=='Basic Wall') — extract only elements of the Basic Wall type.

      Query Variables

      {
        "filter": "(category=='Windows')",
        "sourceFileId": "aXRlbX5iLjc2OGNhZTE0LTc2YjMtNDUzMS05MDMwLTI1MjEyZGFiNGU0OH5iLjIyYTVkYzQ3LWNhMTktNDIzMS05ZjNlLTE1N2ViZDQ4NDJmZn51cm46YWRzay53aXBwcm9kOmZzLmZvbGRlcjpjby5ON21kU05TSFR3Nk81dWNualhsSjJRfnVybjphZHNrLndpcHByb2Q6ZG0ubGluZWFnZTpCVGJ3enVuSlFRU0wwTVBsbFhNVDZB",
        "targetExchangeName": "AEC Filter based Exchange - Category Windows",
        "targetFolderId": "Zm9sZH5iLjc2OGNhZTE0LTc2YjMtNDUzMS05MDMwLTI1MjEyZGFiNGU0OH5iLjIyYTVkYzQ3LWNhMTktNDIzMS05ZjNlLTE1N2ViZDQ4NDJmZn51cm46YWRzay53aXBwcm9kOmZzLmZvbGRlcjpjby5ON21kU05TSFR3Nk81dWNualhsSjJR"
      }
      
    3. Click Play. The exchange will be created based on the filter category==’Windows’ and the response will look similar to the following code block.

      Response

      {
        "data": {
            "createExchange": {
                "exchange": {
                    "id": "ZXhjfnlwdWFzY1NicWlIT0R1R0s4OUkwTHdfTDJDfjU1NGEzMGMzLTkxYWMtMzIwNC04NzVmLWM0MDc3ZjJkZDI1YQ",
                    "name": "AEC Filter based Exchange - Category Windows",
                    "elements": {
                        "results": [ ]
                      }
                  }
              }
          }
      }
      
      Show More

    The exchange has been created successfully; however, the result contains empty elements. This could be due to the exchange being in one of the following states: IN_PROGRESS, FAILED, or COMPLETED with no elements. Refer to ExchangeStatus page to learn more about the status of the exchange.

    To check the status of the exchange, you can run the getExchangeCreationStatus query. For detailed instructions, refer to the procedure outlined in the next step.

    Step 2 - Get Exchange Status

    The following steps demonstrate how you can run the getExchangeCreationStatus query to check the status of the exchange that was created in the previous step.

    1. Enter the following query in the Query Pane of the Data Exchange Explorer.

      Query

      query GetExchangeStatus($exchangeId: ID!) {
          getExchangeCreationStatus(exchangeId: $exchangeId) {
              status
              versionNumber
              exchange {
                  id
                  name
                  elements {
                      results {
                          id
                          name
                      }
                  }
              }
          }
      }
      
      Show More
    2. In the Query Variables pane, enter the value for the exchangeId field.

      Query Variables

      {
        "exchangeId": "ZXhjfnlwdWFzY1NicWlIT0R1R0s4OUkwTHdfTDJDfjU1NGEzMGMzLTkxYWMtMzIwNC04NzVmLWM0MDc3ZjJkZDI1YQ"
      }
      
    3. Click Play. The response will look similar to the following code block.

      Response

      {
          "data":{
              "getExchangeCreationStatus":{
                  "status":"COMPLETED",
                  "versionNumber":1,
                  "exchange":{
                      "id":"ZXhjfnlwdWFzY1NicWlIT0R1R0s4OUkwTHdfTDJDfjU1NGEzMGMzLTkxYWMtMzIwNC04NzVmLWM0MDc3ZjJkZDI1YQ",
                      "name":"AEC Filter based Exchange - Category Windows",
                      "elements":{
                          "results":[
                              {
                                  "id":"YWVjZX53TGhzYkpOSmVndGM5QlVsaFB6a2xwX0wyQ35CVGJ3enVuSlFRU0wwTVBsbFhNVDZBXzU3YmEy",
                                  "name":"36\" x 48\""
                              }
                          ]
                      }
                  }
              }
          }
      }
      
      Show More

    The exchange status is COMPLETED. To retrieve exchange-related information, follow the steps in Get Exchange, or refer to tasks under Advanced Queries.

    If the status is IN_PROGRESS, wait for the exchange to complete and then follow the same steps to retrieve the information.