Request

Response

    Subscribe to Domain Events

    This topic provides instructions on how to subscribe to domain events on a Manufacturing Data Model entity, receive event payloads in real time over PubNub, and remove the subscription when it is no longer needed.

    As a prerequisite for completing the current topic, you need the ID of the entity you want to monitor (a component ID is used in the examples below). If you do not already have one, complete the Retrieve Items tutorial to obtain a component ID.

    You will also need a PubNub account to obtain a channel ID. See the PubNub documentation for setup instructions.

    You will use the following operations in this topic:

    Step 1 - Register an Event Listener

    The addEventListener mutation registers a listener on a target entity. You provide the ID of the entity you want to monitor, the type of event to subscribe to, the PubNub channel on which payloads will be delivered, and an expiration timestamp after which the listener stops automatically.

    1. In Manufacturing Data Model Explorer, enter the following mutation in the Query Pane:

      Mutation

      mutation AddEventListener($input: AddEventListenerInput!) {
         addEventListener(input: $input) {
            credentials {
               cipherKey
               subscriptionKey
            }
            eventListener {
               id
               targetId
               channelId
               eventType
               expiration
            }
         }
      }
      
      Show More
    2. In the Query Variables Pane, enter the targetId of the component or asset you want to monitor, the event type string, your PubNub channel ID, and an expiration timestamp. To obtain a componentId, refer to Retrieve Items.

      Query Variables

      {
         "input": {
            "targetId": "cHJvZHVjdH45YWJNY0Z4S2doUHljd3VNb2FHTmlrX0wyQ35NeWpwUUR6Q3YwdFZQQzBYMVRhUVdPX2FnYQ",
            "eventType": "autodesk.data.mfgdm:version.created-1.0.0",
            "expiration": "2026-12-31T23:59:59.000Z",
            "channelId": "my-app-channel-001"
         }
      }
      
      Show More
    3. Click Play. The response contains the listener details and the PubNub credentials needed to receive events.

      Response

      {
         "data": {
            "addEventListener": {
               "credentials": {
                  "cipherKey": "Tgt70STmEQchB6brALwEUj3o1bjQMfBlvDm1MfNFFTYTGFcMqnFnJ56AGjE9Ti2IZdp359JCh0G76Q39aAOEJf6fGM2rISjdkKW",
                  "subscriptionKey": "sub-c-00552074-7db6-11ea-b5c3-ce1367e69237"
               },
               "eventListener": {
                  "id": "123fe252-4a54-4d22-b9e9-cd942a95f33f",
                  "targetId": "cHJvZHVjdH45YWJNY0Z4S2doUHljd3VNb2FHTmlrX0wyQ35NeWpwUUR6Q3YwdFZQQzBYMVRhUVdPX2FnYQ",
                  "channelId": "my-app-channel-001",
                  "eventType": "autodesk.data.mfgdm:version.created-1.0.0",
                  "expiration": "2026-12-31T23:59:59.000Z"
               }
            }
         }
      }
      
      Show More

    Note: Save the eventListener.id from the response. You will need it in Step 3 to remove the listener. Save the subscriptionKey and cipherKey from credentials. You will need them in Step 2 to connect to PubNub.

    Step 2 - Connect to PubNub and Receive Events

    Use the subscriptionKey and cipherKey returned in Step 1 to connect to PubNub on the channel specified in your listener. When an event fires on the monitored entity, the payload is delivered to that channel.

    The following example uses the PubNub JavaScript SDK.

    1. Install the PubNub SDK:

      npm install pubnub
      
    2. Connect to your channel and listen for messages:

      const PubNub = require("pubnub");
      
      const pubnub = new PubNub({
         subscribeKey: "<subscriptionKey from Step 1>",
         cipherKey: "<cipherKey from Step 1>",
         userId: "my-app-user"
      });
      
      pubnub.addListener({
         message: function (event) {
            console.log("Received event:", JSON.stringify(event.message, null, 2));
         }
      });
      
      pubnub.subscribe({ channels: ["my-app-channel-001"] });
      
      Show More
    3. Trigger the subscribed event by performing the corresponding action in Autodesk Fusion or via the API. For version.created, call the createVersion mutation on the component you are monitoring.

      When the event fires, you will receive a payload similar to the following on your channel:

      Received Payload

      {
         "id": "fd3bd89e-201e-4824-867a-7543a3b47e73",
         "specversion": "1.0",
         "type": "autodesk.data.mfgdm:version.created-1.0.0",
         "source": "urn:com.autodesk.forge:clientid:<your-client-id>",
         "subject": "cHJvZHVjdH45YWJNY0Z4S2doUHljd3VNb2FHTmlrX0wyQ35NeWpwUUR6Q3YwdFZQQzBYMVRhUVdPX2FnYQ",
         "time": "2026-04-20T10:15:30.000Z",
         "data": {
            "targetId": "cHJvZHVjdH45YWJNY0Z4S2doUHljd3VNb2FHTmlrX0wyQ35NeWpwUUR6Q3YwdFZQQzBYMVRhUVdPX2FnYQ",
            "versionId": "dmVyc2lvbn45YWJNY0Z4S2doUHljd3VNb2FHTmlrX0wyQ35NeWpwUUR6Q3YwdFZQQzBYMVRhUVdPX2FnYQ",
            "description": "Design review update",
            "author": "ABCDE12345FGHIJ",
            "historyChangeId": "aGlzdG9yeX45YWJNY0Z4S2doUHljd3VNb2FHTmlrX0wyQ35NeWpwUUR6Q3YwdFZQQzBYMVRhUVdPX2FnYQ"
         }
      }
      
      Show More

    Note: Event payloads follow the CloudEvents specification. The id field is a required field on every delivered event and contains a unique identifier for that event occurrence. The data field contains the event-specific payload. The targetId in the payload matches the subject field and identifies the entity on which the event occurred. For the full list of event types and their payload fields, see Domain Events.

    Step 3 - Remove the Event Listener

    When your application no longer needs to receive events, remove the listener using the removeEventListener mutation. Listeners also expire automatically at the timestamp set in Step 1, but removing them explicitly is recommended to avoid unnecessary resource usage.

    1. In Manufacturing Data Model Explorer, enter the following mutation in the Query Pane:

      Mutation

      mutation RemoveEventListener($input: RemoveEventListenerInput!) {
         removeEventListener(input: $input) {
            success
         }
      }
      
    2. In the Query Variables Pane, enter the eventListenerId saved from Step 1.

      Query Variables

      {
         "input": {
            "eventListenerId": "123fe252-4a54-4d22-b9e9-cd942a95f33f"
         }
      }
      
    3. Click Play. A successful response confirms the listener has been removed.

      Response

      {
         "data": {
            "removeEventListener": {
               "success": true
            }
         }
      }
      

    Step 4 - Extend a Listener Expiration (Optional)

    Listeners stop delivering events automatically once the expiration timestamp set in Step 1 is reached. Use the updateEventListenerExpiration mutation to extend an active listener without recreating it.

    1. In Manufacturing Data Model Explorer, enter the following mutation in the Query Pane:

      Mutation

      mutation UpdateEventListenerExpiration($input: UpdateEventListenerExpirationInput!) {
         updateEventListenerExpiration(input: $input) {
            success
         }
      }
      
    2. In the Query Variables Pane, enter the id of the listener to extend and the new expiration timestamp.

      Query Variables

      {
         "input": {
            "id": "123fe252-4a54-4d22-b9e9-cd942a95f33f",
            "expiration": "2027-06-30T23:59:59.000Z"
         }
      }
      
    3. Click Play. A successful response confirms the expiration has been updated.

      Response

      {
         "data": {
            "updateEventListenerExpiration": {
               "success": true
            }
         }
      }
      

    Note: The input field for the listener ID is id on this mutation, compared to eventListenerId used on removeEventListener.

    Additional Notes

    • Wildcard subscriptions: You can subscribe to multiple event types at once using wildcard notation in the eventType field. For example, autodesk.data.mfgdm:bomrelation.*-1.0.0 matches all BOM relation event types. Use autodesk.data.mfgdm:* to match all core events on the target.
    • Scope: The targetId determines the scope of events received. Subscribing to an asset-scoped event at the asset level delivers events for all entities within that asset. Subscribing at the component level delivers only events for that component.
    • Event type reference: For the full list of available event types, scope types, and payload field descriptions, see Domain Events.