Sometimes it is necessary to link "things" in your app to "entities" in Deskpro. For example, let's say we have an app that shows cards from a project management system. We may want to link each of these cards to Deskpro tickets. Under the hood, these links are formed using custom fields in Deskpro, and provide Deskpro users with extended functionlity - like including linked cards in filters and searches.

Configuration

To set up associated entities, you must first declare it in your app manifest. In this example we're going to create a "ticket" association definition called "linkedCards":

{
  "name": "my_app",
  "title": "My App",
  "description": "Brief description of my app",
  "version": "1.0.0",
  "scope": "agent",
  "isSingleInstall": true,
  "targets": [{
    "target": "ticket_sidebar",
    "entrypoint": "index.html"
    }
  }],
  "entityAssociations": {
    "linkedCards": {
      "entity": "ticket",
      "type": "external_id"
    }
  }
}
 copy

When the app is installed or updated, the necessary custom fields will be set up in Deskpro.

Basic Usage

Much like the state API, we provide a helper object for dealing with entity associations from the SDK client. These methods allow you to store, recall and delete associations for a given Deskpro entity.

Entity association management methods:

• client.getEntityAssociation("linkedCards", <deskpro_entity_id>).set(<item_id>) - set an assocaited item

• client.getEntityAssociation("linkedCards", <deskpro_entity_id>).get(<item_id>) - get assocaited item metadata

• client.getEntityAssociation("linkedCards", <deskpro_entity_id>).list() - get list of assocaited items

• client.getEntityAssociation("linkedCards", <deskpro_entity_id>).delete(<item_id>) - delete an assocaited item

You can also "count" the associated Deskpro entities using this method:

• client.entityAssociationCountEntities("linkedCards", <deskpro_entity_id>) - returns the number of linked entities

For example, this is useful if you'd like to count the number of Deskpro tickets associated with this "thing".

Here are the methods used in a practical example:

import { Context, useDeskproAppClient, useDeskproAppEvents } from "@deskpro/app-sdk";
import { useEffect, useState } from "react";

export const MyComponent = () => {
  const [ticketId, setTicketId] = useState<string|null>(null);
  const { client } = useDeskproAppClient();

  useDeskproAppEvents({
    onReady(context: Context) {
      setTicketId(context.data.ticket.id);
    },
  });

  useEffect(() => {
    if (!ticketId || !client) {
      return;
    }
    
    // Get associated card IDs
    client.getEntityAssociation("linkedCards", ticketId).list().then((cardIds) => {
      console.log(cardIds);
    });
    
  }, [client, ticketId]);

  const addCard = (cardId: string) => {
    if (!ticketId || !client) {
      return;
    }
    
    // Set an associated card ID
    client.getEntityAssociation("linkedCards", ticketId).set(cardId);
  };
  
  return (
    <>
      <button onClick={() => addCard("CRD0001")}>Add Card</button>
    </>
  );
};
 copy

It is also possible to store arbitrary metadata alongside each entity association, when using the set() and get() methods:

// Setting metadata
client.getEntityAssociation("linkedCards", <deskpro_entity_id>)
  .set<MyMetadata>(<item_id>, { metadata_object })
;

// Getting metadata
client.getEntityAssociation("linkedCards", <deskpro_entity_id>)
  .get<MyMetadata>(<item_id>)
  .then((metadata) => console.log(metadata))
;
 copy